feat(cli): add --copy / -c flag for clipboard output

Copies the generated prompt to the system clipboard instead of
printing to stdout. Cross-platform: uses pbcopy (macOS), xclip or
xsel (Linux), clip.exe (Windows/WSL). Falls back to stdout with a
stderr warning if no clipboard tool is detected.

- src/clipboard.ts: new utility with commandExists probe loop
- src/index.ts: wire --copy / -c option via commander
- src/__tests__/clipboard.test.ts: unit tests with mocked execSync
- README.md: document --copy flag with examples

Closes #1

Author: Akido

README.md

@@ -83,6 +83,20 @@ commitprompt --branch main --type feat --mode commit
 
 Valid types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `ci`, `perf`
 
+### Copy to clipboard
+
+```bash
+# Copy the generated prompt directly to your clipboard
+commitprompt --copy
+commitprompt -c
+
+# Works with all other flags
+commitprompt --mode pr --branch main --copy
+commitprompt --diff changes.diff -c
+```
+
+On **macOS** this uses `pbcopy`. On **Linux** it tries `xclip` then `xsel`. On **Windows/WSL** it uses `clip.exe`. If no clipboard tool is found, the prompt is printed to stdout as a fallback with a warning on stderr.
+
 ### Shell autocomplete
 
 ```bash
@@ -132,6 +146,7 @@ If the change is complex, add a body paragraph explaining WHY (not WHAT).
 | `--type <type>` | Override auto-detected change type | - |
 | `--context` | Include repo context (package.json name, README intro) in prompt | - |
 | `--completions <bash\|zsh>` | Print shell completion script and exit | - |
+| `-c, --copy` | Copy the generated prompt to the system clipboard | - |
 
 **Input priority:** `--diff` > `--branch` > stdin pipe > `--staged` (default)
 

src/__tests__/clipboard.test.ts

@@ -0,0 +1,53 @@
+/**
+ * clipboard.test.ts
+ * Tests for the cross-platform clipboard utility.
+ * We mock execSync to avoid requiring a real clipboard tool in CI.
+ */
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import * as childProcess from 'child_process';
+
+// We need to mock before importing the module under test
+vi.mock('child_process');
+
+const mockedExecSync = vi.mocked(childProcess.execSync);
+
+describe('copyToClipboard', () => {
+  afterEach(() => {
+    vi.resetAllMocks();
+  });
+
+  it('returns null (success) when a clipboard command is available and succeeds', async () => {
+    // First call: commandExists -> success for pbcopy
+    // Second call: actual copy -> success
+    mockedExecSync.mockReturnValueOnce(Buffer.from('')); // command -v pbcopy
+    mockedExecSync.mockReturnValueOnce(Buffer.from('')); // pbcopy pipe
+
+    const { copyToClipboard } = await import('../clipboard.js');
+    const result = copyToClipboard('hello clipboard');
+    expect(result).toBeNull();
+  });
+
+  it('returns an error string when the clipboard command throws', async () => {
+    // command -v pbcopy succeeds, but pbcopy itself throws
+    mockedExecSync.mockReturnValueOnce(Buffer.from('')); // command -v pbcopy
+    mockedExecSync.mockImplementationOnce(() => {
+      throw new Error('pbcopy: pipe broken');
+    });
+
+    const { copyToClipboard } = await import('../clipboard.js');
+    const result = copyToClipboard('hello');
+    expect(result).toContain('pbcopy');
+    expect(result).toContain('failed');
+  });
+
+  it('returns a "no clipboard tool found" message when all commands are missing', async () => {
+    // All commandExists calls fail
+    mockedExecSync.mockImplementation(() => {
+      throw new Error('not found');
+    });
+
+    const { copyToClipboard } = await import('../clipboard.js');
+    const result = copyToClipboard('hello');
+    expect(result).toContain('no clipboard tool found');
+  });
+});

src/clipboard.ts

@@ -0,0 +1,52 @@
+/**
+ * clipboard.ts - Cross-platform clipboard write utility
+ *
+ * Tries, in order:
+ *   macOS:   pbcopy
+ *   Linux:   xclip -selection clipboard
+ *   Linux:   xsel --clipboard --input
+ *   WSL/Win: clip.exe
+ *
+ * Returns an error message string if no clipboard tool is available,
+ * or null on success.
+ */
+import { execSync } from 'child_process';
+
+/** Commands to probe + pipe into (in priority order). */
+const CLIPBOARD_CMDS: ReadonlyArray<{ cmd: string; args: string[] }> = [
+  { cmd: 'pbcopy', args: [] },
+  { cmd: 'xclip', args: ['-selection', 'clipboard'] },
+  { cmd: 'xsel', args: ['--clipboard', '--input'] },
+  { cmd: 'clip.exe', args: [] },
+];
+
+function commandExists(cmd: string): boolean {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Write `text` to the system clipboard.
+ * @returns null on success, or an error string if clipboard is unavailable.
+ */
+export function copyToClipboard(text: string): string | null {
+  for (const { cmd, args } of CLIPBOARD_CMDS) {
+    if (!commandExists(cmd)) continue;
+    try {
+      const fullCmd = [cmd, ...args].join(' ');
+      execSync(fullCmd, { input: text, stdio: ['pipe', 'ignore', 'ignore'] });
+      return null; // success
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return `clipboard: "${cmd}" failed: ${msg}`;
+    }
+  }
+  return (
+    'clipboard: no clipboard tool found. ' +
+    'Install pbcopy (macOS), xclip or xsel (Linux), or use clip.exe (Windows/WSL).'
+  );
+}

src/index.ts

@@ -14,6 +14,7 @@ import {
 import { parseDiff } from './diff-parser.js';
 import { buildPrompt, type Mode } from './prompt-builder.js';
 import { readRepoContext } from './context-reader.js';
+import { copyToClipboard } from './clipboard.js';
 
 // Valid commit types (also used for autocomplete)
 const VALID_TYPES = ['feat', 'fix', 'docs', 'refactor', 'test', 'chore', 'ci', 'perf'];
@@ -47,6 +48,10 @@ program
     '--completions <shell>',
     'Print shell completion script for bash or zsh and exit'
   )
+  .option(
+    '-c, --copy',
+    'Copy the generated prompt to the system clipboard instead of (or in addition to) printing it'
+  )
   .parse(process.argv);
 
 const opts = program.opts<{
@@ -57,6 +62,7 @@ const opts = program.opts<{
   type?: string;
   context?: boolean;
   completions?: string;
+  copy?: boolean;
 }>();
 
 // Handle --completions before anything else
@@ -123,7 +129,18 @@ if (opts.type) {
 
 const prompt = buildPrompt(parsed, raw, mode, 120, contextString);
 
-process.stdout.write(prompt + '\n');
+if (opts.copy) {
+  const err = copyToClipboard(prompt);
+  if (err) {
+    // Clipboard failed: print the prompt anyway and warn on stderr
+    process.stderr.write(`Warning: ${err}\n`);
+    process.stdout.write(prompt + '\n');
+  } else {
+    process.stderr.write('Prompt copied to clipboard.\n');
+  }
+} else {
+  process.stdout.write(prompt + '\n');
+}
 
 // --- Completion scripts ---