@promptcellar/pc 0.5.4 → 0.6.0

package/docs/plans/2026-02-03-multi-prompt-capture-design.md

@@ -1,501 +0,0 @@
-# Multi-Prompt Capture Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Capture all user prompts in real-time (not just the first), grouped by session ID.
-
-**Architecture:** Switch Claude Code from Stop hook to UserPromptSubmit hook. Add deduplication state tracking for Codex CLI. Gemini already fires per-prompt, just verify session handling.
-
-**Tech Stack:** Node.js, ES modules, Conf for state storage
-
----
-
-## Task 1: Create State Management Utility
-
-**Files:**
-- Create: `src/lib/state.js`
-
-**Step 1: Create the state utility file**
-
-```javascript
-import Conf from 'conf';
-
-const state = new Conf({
-  projectName: 'promptcellar',
-  configName: 'capture-state',
-  schema: {
-    threads: {
-      type: 'object',
-      default: {}
-    }
-  }
-});
-
-const MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
-
-/**
- * Get the last captured index for a thread.
- * @param {string} threadId
- * @returns {number}
- */
-export function getLastCapturedIndex(threadId) {
-  const threads = state.get('threads');
-  return threads[threadId]?.lastIndex || 0;
-}
-
-/**
- * Save the last captured index for a thread.
- * @param {string} threadId
- * @param {number} lastIndex
- */
-export function saveLastCapturedIndex(threadId, lastIndex) {
-  const threads = state.get('threads');
-  threads[threadId] = {
-    lastIndex,
-    updatedAt: Date.now()
-  };
-  state.set('threads', threads);
-}
-
-/**
- * Clean up stale thread entries older than maxAgeMs.
- * @param {number} maxAgeMs - Default 24 hours
- */
-export function cleanupStaleThreads(maxAgeMs = MAX_AGE_MS) {
-  const threads = state.get('threads');
-  const now = Date.now();
-  let changed = false;
-
-  for (const [threadId, data] of Object.entries(threads)) {
-    if (now - data.updatedAt > maxAgeMs) {
-      delete threads[threadId];
-      changed = true;
-    }
-  }
-
-  if (changed) {
-    state.set('threads', threads);
-  }
-}
-
-export default { getLastCapturedIndex, saveLastCapturedIndex, cleanupStaleThreads };
-```
-
-**Step 2: Commit**
-
-```bash
-git add src/lib/state.js
-git commit -m "feat: add state management for capture deduplication"
-```
-
----
-
-## Task 2: Rewrite Claude Code Hook for UserPromptSubmit
-
-**Files:**
-- Modify: `hooks/prompt-capture.js`
-
-**Step 1: Rewrite the hook for UserPromptSubmit**
-
-Replace entire file with:
-
-```javascript
-#!/usr/bin/env node
-
-/**
- * Claude Code UserPromptSubmit hook for capturing prompts to PromptCellar.
- *
- * This script is called by Claude Code on every user prompt submission.
- * UserPromptSubmit hooks receive JSON via stdin with:
- * - session_id: session identifier
- * - prompt: the user's prompt text
- * - cwd: working directory
- */
-
-import { capturePrompt } from '../src/lib/api.js';
-import { getFullContext } from '../src/lib/context.js';
-import { isLoggedIn, isVaultAvailable } from '../src/lib/config.js';
-import { encryptPrompt } from '../src/lib/crypto.js';
-import { requireVaultKey } from '../src/lib/keychain.js';
-
-async function readStdin() {
-  return new Promise((resolve) => {
-    let data = '';
-    process.stdin.setEncoding('utf8');
-    process.stdin.on('data', chunk => data += chunk);
-    process.stdin.on('end', () => resolve(data));
-
-    // Timeout after 1 second if no input
-    setTimeout(() => resolve(data), 1000);
-  });
-}
-
-async function main() {
-  try {
-    const input = await readStdin();
-
-    if (!input.trim()) {
-      process.exit(0);
-    }
-
-    if (!isLoggedIn()) {
-      process.exit(0);
-    }
-
-    if (!isVaultAvailable()) {
-      process.exit(0);
-    }
-
-    const event = JSON.parse(input);
-
-    // UserPromptSubmit provides the prompt directly
-    if (!event.prompt) {
-      process.exit(0);
-    }
-
-    const promptContent = event.prompt.trim();
-    if (!promptContent) {
-      process.exit(0);
-    }
-
-    const context = getFullContext('claude-code');
-
-    // Override with event data if available
-    if (event.cwd) {
-      context.working_directory = event.cwd;
-    }
-    if (event.session_id) {
-      context.session_id = event.session_id;
-    }
-
-    const vaultKey = await requireVaultKey({ silent: true });
-    if (!vaultKey) {
-      process.exit(0);
-    }
-    const { encrypted_content, content_iv } = encryptPrompt(promptContent, vaultKey);
-
-    await capturePrompt({
-      ...context,
-      encrypted_content,
-      content_iv
-    });
-
-  } catch {
-    // Fail silently — stderr from hooks can cause issues
-    process.exit(0);
-  }
-}
-
-main();
-```
-
-**Step 2: Commit**
-
-```bash
-git add hooks/prompt-capture.js
-git commit -m "feat: rewrite Claude hook for UserPromptSubmit (real-time capture)"
-```
-
----
-
-## Task 3: Update Codex Hook for Multi-Prompt Capture
-
-**Files:**
-- Modify: `hooks/codex-capture.js`
-
-**Step 1: Update the hook with deduplication**
-
-Replace entire file with:
-
-```javascript
-#!/usr/bin/env node
-
-/**
- * Codex CLI notify hook for capturing prompts to PromptCellar.
- *
- * Codex calls this script with a JSON argument containing:
- * - type: event type (e.g., 'agent-turn-complete')
- * - thread-id: session identifier
- * - turn-id: turn identifier
- * - cwd: working directory
- * - input-messages: array of user messages (accumulates over session)
- * - last-assistant-message: final assistant response
- *
- * This hook captures ALL new user messages since last capture using
- * state tracking to avoid duplicates.
- */
-
-import { capturePrompt } from '../src/lib/api.js';
-import { getFullContext } from '../src/lib/context.js';
-import { isLoggedIn, isVaultAvailable } from '../src/lib/config.js';
-import { encryptPrompt } from '../src/lib/crypto.js';
-import { requireVaultKey } from '../src/lib/keychain.js';
-import { getLastCapturedIndex, saveLastCapturedIndex, cleanupStaleThreads } from '../src/lib/state.js';
-
-function extractContent(message) {
-  if (typeof message === 'string') {
-    return message;
-  }
-  if (message.content) {
-    return Array.isArray(message.content)
-      ? message.content.filter(c => c.type === 'text').map(c => c.text).join('\n')
-      : message.content;
-  }
-  return null;
-}
-
-async function main() {
-  // Codex passes JSON as first argument
-  const jsonArg = process.argv[2];
-
-  if (!jsonArg) {
-    process.exit(0);
-  }
-
-  if (!isLoggedIn()) {
-    process.exit(0);
-  }
-
-  if (!isVaultAvailable()) {
-    process.exit(0);
-  }
-
-  try {
-    const event = JSON.parse(jsonArg);
-
-    // Only capture on agent-turn-complete
-    if (event.type !== 'agent-turn-complete') {
-      process.exit(0);
-    }
-
-    const inputMessages = event['input-messages'] || [];
-    if (inputMessages.length === 0) {
-      process.exit(0);
-    }
-
-    const threadId = event['thread-id'];
-    if (!threadId) {
-      process.exit(0);
-    }
-
-    // Clean up stale threads periodically
-    cleanupStaleThreads();
-
-    // Get last captured index to avoid duplicates
-    const lastIndex = getLastCapturedIndex(threadId);
-    const newMessages = inputMessages.slice(lastIndex);
-
-    if (newMessages.length === 0) {
-      process.exit(0);
-    }
-
-    const vaultKey = await requireVaultKey({ silent: true });
-    if (!vaultKey) {
-      process.exit(0);
-    }
-
-    // Build base context once
-    const baseContext = getFullContext('codex');
-    if (event.cwd) {
-      baseContext.working_directory = event.cwd;
-    }
-    baseContext.session_id = threadId;
-
-    // Capture each new message
-    for (const message of newMessages) {
-      const content = extractContent(message);
-      if (!content || !content.trim()) {
-        continue;
-      }
-
-      const { encrypted_content, content_iv } = encryptPrompt(content.trim(), vaultKey);
-
-      await capturePrompt({
-        ...baseContext,
-        encrypted_content,
-        content_iv
-      });
-    }
-
-    // Update state with new index
-    saveLastCapturedIndex(threadId, inputMessages.length);
-
-  } catch {
-    // Fail silently to not disrupt Codex
-    process.exit(0);
-  }
-}
-
-main();
-```
-
-**Step 2: Commit**
-
-```bash
-git add hooks/codex-capture.js
-git commit -m "feat: update Codex hook to capture all prompts with deduplication"
-```
-
----
-
-## Task 4: Verify Gemini Hook Session Handling
-
-**Files:**
-- Modify: `hooks/gemini-capture.js` (minor update)
-
-**Step 1: Review and verify session_id handling**
-
-The Gemini hook already captures per-prompt via BeforeAgent. Verify that session_id is properly included. The current implementation at lines 81-83 already handles this:
-
-```javascript
-if (event.session_id) {
-  context.session_id = event.session_id;
-}
-```
-
-No changes needed - the hook already works correctly for multi-prompt capture.
-
-**Step 2: Commit (documentation only if no changes)**
-
-No commit needed - Gemini hook already supports multi-prompt capture.
-
----
-
-## Task 5: Update Setup Command for UserPromptSubmit Hook
-
-**Files:**
-- Modify: `src/commands/setup.js`
-
-**Step 1: Update Claude Code hook configuration**
-
-Change the `setupClaudeCode` function to use `UserPromptSubmit` instead of `Stop`.
-
-Find and replace in `setupClaudeCode` function (around lines 167-210):
-
-Change line 61-64 (isClaudeHookInstalled):
-```javascript
-function isClaudeHookInstalled(settings) {
-  const matchers = settings.hooks?.UserPromptSubmit || [];
-  return matchers.some(matcher =>
-    matcher.hooks?.some(hook => hook.command?.includes(HOOK_SCRIPT_NAME))
-  );
-}
-```
-
-Change lines 187-189 (remove existing hook):
-```javascript
-    // Remove existing hook matchers that contain our hook
-    settings.hooks.UserPromptSubmit = (settings.hooks.UserPromptSubmit || []).filter(matcher =>
-      !matcher.hooks?.some(hook => hook.command?.includes(HOOK_SCRIPT_NAME))
-    );
-```
-
-Change lines 193-206 (add new hook):
-```javascript
-  // Ensure hooks.UserPromptSubmit exists
-  if (!settings.hooks) {
-    settings.hooks = {};
-  }
-  if (!settings.hooks.UserPromptSubmit) {
-    settings.hooks.UserPromptSubmit = [];
-  }
-
-  // Add the UserPromptSubmit hook
-  settings.hooks.UserPromptSubmit.push({
-    matcher: '*',
-    hooks: [{
-      type: 'command',
-      command: 'pc-capture'
-    }]
-  });
-```
-
-**Step 2: Update unsetup function**
-
-Change lines 317-324 (unsetup Claude hook):
-```javascript
-  // Remove Claude hook
-  const claudeSettings = getClaudeSettings();
-  if (isClaudeHookInstalled(claudeSettings)) {
-    claudeSettings.hooks.UserPromptSubmit = (claudeSettings.hooks.UserPromptSubmit || []).filter(matcher =>
-      !matcher.hooks?.some(hook => hook.command?.includes(HOOK_SCRIPT_NAME))
-    );
-    saveClaudeSettings(claudeSettings);
-    console.log(chalk.green('  Removed Claude Code hook.'));
-    removed = true;
-  }
-```
-
-**Step 3: Commit**
-
-```bash
-git add src/commands/setup.js
-git commit -m "feat: update setup to use UserPromptSubmit hook for Claude Code"
-```
-
----
-
-## Task 6: Bump Version and Final Commit
-
-**Files:**
-- Modify: `package.json`
-
-**Step 1: Bump version to 0.5.0**
-
-This is a feature release (captures all prompts instead of just first).
-
-Change line 3:
-```json
-  "version": "0.5.0",
-```
-
-**Step 2: Commit version bump**
-
-```bash
-git add package.json
-git commit -m "chore: bump version to 0.5.0"
-```
-
----
-
-## Task 7: Test the Implementation
-
-**Step 1: Verify state.js loads correctly**
-
-```bash
-node -e "import('./src/lib/state.js').then(m => console.log('state.js OK'))"
-```
-
-Expected: `state.js OK`
-
-**Step 2: Verify hooks load correctly**
-
-```bash
-node -e "import('./hooks/prompt-capture.js').catch(() => console.log('prompt-capture.js OK'))"
-node -e "import('./hooks/codex-capture.js').catch(() => console.log('codex-capture.js OK'))"
-node -e "import('./hooks/gemini-capture.js').catch(() => console.log('gemini-capture.js OK'))"
-```
-
-Expected: Each prints OK (the catch is because they exit on no input)
-
-**Step 3: Verify setup command loads**
-
-```bash
-node -e "import('./src/commands/setup.js').then(m => console.log('setup.js OK'))"
-```
-
-Expected: `setup.js OK`
-
----
-
-## Summary
-
-| Task | Description |
-|------|-------------|
-| 1 | Create `src/lib/state.js` for Codex deduplication |
-| 2 | Rewrite `hooks/prompt-capture.js` for UserPromptSubmit |
-| 3 | Update `hooks/codex-capture.js` with deduplication |
-| 4 | Verify `hooks/gemini-capture.js` (no changes needed) |
-| 5 | Update `src/commands/setup.js` for new hook type |
-| 6 | Bump version to 0.5.0 |
-| 7 | Test all modules load correctly |