@devtrace-ai/cli 1.0.0

package/dist/claude-hook-install.js

@@ -0,0 +1,183 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveClaudeSettingsPath = resolveClaudeSettingsPath;
+exports.installClaudeHooks = installClaudeHooks;
+exports.uninstallClaudeHooks = uninstallClaudeHooks;
+exports.countDevtraceEntries = countDevtraceEntries;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Installs/uninstalls the DevTrace hook entries into Claude Code's
+ * ~/.claude/settings.json (PostToolUse + SessionStart), so `devtrace
+ * claude-hook` runs as a first-party structured-event capture source
+ * instead of transcript scraping. See docs/plans/03b Gap 1.
+ *
+ * Merge, don't clobber: only DevTrace's own hook entries are added/removed;
+ * any other hooks or settings keys already present are preserved untouched.
+ *
+ * Path resolution mirrors src/hooks.ts's git-hook bake-in pattern: an
+ * absolute node execPath + absolute script path resolved once at install
+ * time, so the hook command never needs PATH or a network/registry hit.
+ */
+const POST_TOOL_USE_MATCHER = 'Edit|Write|MultiEdit';
+/** Resolves the absolute invocation command for the DevTrace hook subcommand. */
+function resolveInvocationCommand() {
+    const execPath = process.execPath;
+    const scriptPath = path.resolve(require.main?.filename ?? process.argv[1]);
+    return `"${execPath}" "${scriptPath}" claude-hook`;
+}
+/**
+ * Resolves the target settings.json path. Honors CLAUDE_SETTINGS_PATH as a
+ * test/override hook (mirrors DEVTRACE_HOME's role for src/config.ts),
+ * falling back to the real ~/.claude/settings.json.
+ */
+function resolveClaudeSettingsPath() {
+    if (process.env.CLAUDE_SETTINGS_PATH) {
+        return process.env.CLAUDE_SETTINGS_PATH;
+    }
+    const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+    return path.join(homeDir, '.claude', 'settings.json');
+}
+function loadSettings(settingsPath) {
+    if (!fs.existsSync(settingsPath))
+        return {};
+    try {
+        const raw = fs.readFileSync(settingsPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function saveSettings(settingsPath, settings) {
+    const dir = path.dirname(settingsPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+}
+/**
+ * Inserts (or replaces) a DevTrace-owned hook entry within a given event's
+ * matcher blocks, without touching any other tool's blocks or hook entries.
+ */
+function upsertHookEntry(blocks, matcher, command) {
+    const result = blocks ? blocks.map(b => ({ ...b, hooks: [...b.hooks] })) : [];
+    // Strip any pre-existing DevTrace entries first (idempotent reinstall / upgrade path),
+    // dropping now-empty matcher blocks that only contained our entry.
+    for (let i = result.length - 1; i >= 0; i--) {
+        result[i].hooks = result[i].hooks.filter(h => !h.__devtrace__);
+        if (result[i].hooks.length === 0 && (result[i].matcher ?? undefined) === matcher) {
+            result.splice(i, 1);
+        }
+    }
+    const targetBlockIdx = result.findIndex(b => (b.matcher ?? undefined) === matcher);
+    const entry = { type: 'command', command, __devtrace__: true };
+    if (targetBlockIdx !== -1) {
+        result[targetBlockIdx].hooks.push(entry);
+    }
+    else {
+        const block = matcher !== undefined ? { matcher, hooks: [entry] } : { hooks: [entry] };
+        result.push(block);
+    }
+    return result;
+}
+/** Removes only DevTrace-owned hook entries from a given event's matcher blocks. */
+function removeHookEntries(blocks) {
+    if (!blocks)
+        return blocks;
+    const result = [];
+    for (const b of blocks) {
+        const hooks = b.hooks.filter(h => !h.__devtrace__);
+        if (hooks.length > 0) {
+            result.push({ ...b, hooks });
+        }
+    }
+    return result;
+}
+/**
+ * Installs DevTrace's PostToolUse (Edit|Write|MultiEdit) and SessionStart
+ * hooks into Claude Code's settings.json. Merge-only: preserves any
+ * pre-existing unrelated settings keys and other tools' hook entries.
+ * Safe to run repeatedly (replaces only DevTrace's own entries).
+ */
+function installClaudeHooks() {
+    const settingsPath = resolveClaudeSettingsPath();
+    const before = loadSettings(settingsPath);
+    const command = resolveInvocationCommand();
+    const after = { ...before, hooks: { ...(before.hooks ?? {}) } };
+    after.hooks.PostToolUse = upsertHookEntry(before.hooks?.PostToolUse, POST_TOOL_USE_MATCHER, command);
+    after.hooks.SessionStart = upsertHookEntry(before.hooks?.SessionStart, undefined, command);
+    saveSettings(settingsPath, after);
+    return { settingsPath, before, after };
+}
+/**
+ * Removes only DevTrace's PostToolUse/SessionStart hook entries from
+ * settings.json, leaving everything else (other hooks, unrelated settings
+ * keys) untouched.
+ */
+function uninstallClaudeHooks() {
+    const settingsPath = resolveClaudeSettingsPath();
+    const before = loadSettings(settingsPath);
+    const after = { ...before };
+    if (before.hooks) {
+        after.hooks = { ...before.hooks };
+        after.hooks.PostToolUse = removeHookEntries(before.hooks.PostToolUse);
+        after.hooks.SessionStart = removeHookEntries(before.hooks.SessionStart);
+        // Drop empty arrays entirely so uninstall doesn't leave clutter like `"PostToolUse": []`.
+        if (after.hooks.PostToolUse && after.hooks.PostToolUse.length === 0)
+            delete after.hooks.PostToolUse;
+        if (after.hooks.SessionStart && after.hooks.SessionStart.length === 0)
+            delete after.hooks.SessionStart;
+        if (Object.keys(after.hooks).length === 0)
+            delete after.hooks;
+    }
+    saveSettings(settingsPath, after);
+    return { settingsPath, before, after };
+}
+/** Counts DevTrace-owned hook entries currently present, for summary printing. */
+function countDevtraceEntries(settings) {
+    let count = 0;
+    for (const key of ['PostToolUse', 'SessionStart']) {
+        const blocks = settings.hooks?.[key];
+        if (!blocks)
+            continue;
+        for (const b of blocks) {
+            count += b.hooks.filter(h => h.__devtrace__).length;
+        }
+    }
+    return count;
+}

package/dist/claude-hooks.js

@@ -0,0 +1,236 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLAUDE_HOOK_LOG_FILENAME = exports.CLAUDE_LEDGER_FILENAME = void 0;
+exports.handleHookEvent = handleHookEvent;
+exports.readStdinSync = readStdinSync;
+exports.runClaudeHookCli = runClaudeHookCli;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * First-party Claude Code capture via hooks (tier-2 "instrumented").
+ *
+ * Design: docs/plans/03b-sota-capture-research-completion.md Gap 1.
+ * Claude Code invokes hook commands with stdin JSON. PostToolUse adds
+ * tool_name/tool_input/tool_response; no model is present there, so model
+ * is captured once per session via SessionStart and joined on session_id
+ * downstream (the ledger just records both event kinds; joining happens
+ * at commit-correlation time if ever needed).
+ *
+ * Privacy commitment: this module NEVER writes prompt text, old/new string
+ * contents, or transcript paths to disk — only counts and repo-relative
+ * paths. See handleHookEvent() below for the exact fields persisted.
+ *
+ * Reliability commitment: this must never block or break Claude Code. Every
+ * public entry point catches all errors, logs them to `.devtrace/hook.log`,
+ * and the CLI wrapper (src/index.ts `claude-hook` command) always exits 0.
+ */
+exports.CLAUDE_LEDGER_FILENAME = 'claude-ledger.jsonl';
+exports.CLAUDE_HOOK_LOG_FILENAME = 'hook.log';
+const EDIT_TOOL_NAMES = new Set(['Edit', 'Write', 'MultiEdit']);
+/** Counts added/removed lines from a single string replacement (old -> new). */
+function diffStringLines(oldStr, newStr) {
+    const oldLines = oldStr.length > 0 ? oldStr.split('\n').length : 0;
+    const newLines = newStr.length > 0 ? newStr.split('\n').length : 0;
+    if (oldStr === '') {
+        // Pure insertion (e.g. Write creating a new file, or Edit's old_string is empty).
+        return { added: newLines, removed: 0 };
+    }
+    if (newStr === '') {
+        return { added: 0, removed: oldLines };
+    }
+    // We don't have a real diff algorithm here (and don't want one — this is metadata-only,
+    // not content analysis). Use a coarse line-delta: net line count change, split into
+    // added/removed via the naive assumption that all old lines were replaced by all new lines.
+    return { added: newLines, removed: oldLines };
+}
+/**
+ * Computes {linesAdded, linesRemoved} for a PostToolUse Edit|Write|MultiEdit event from
+ * tool_input, WITHOUT ever retaining the actual string contents.
+ */
+function computeLineDeltas(toolName, toolInput) {
+    if (toolName === 'MultiEdit' && Array.isArray(toolInput.edits)) {
+        let added = 0;
+        let removed = 0;
+        for (const edit of toolInput.edits) {
+            if (!edit || typeof edit !== 'object')
+                continue;
+            const e = edit;
+            const oldStr = typeof e.old_string === 'string' ? e.old_string : '';
+            const newStr = typeof e.new_string === 'string' ? e.new_string : '';
+            const d = diffStringLines(oldStr, newStr);
+            added += d.added;
+            removed += d.removed;
+        }
+        return { added, removed };
+    }
+    if (toolName === 'Edit') {
+        const oldStr = typeof toolInput.old_string === 'string' ? toolInput.old_string : '';
+        const newStr = typeof toolInput.new_string === 'string' ? toolInput.new_string : '';
+        return diffStringLines(oldStr, newStr);
+    }
+    if (toolName === 'Write') {
+        const content = typeof toolInput.content === 'string' ? toolInput.content : '';
+        return { added: content.length > 0 ? content.split('\n').length : 0, removed: 0 };
+    }
+    return { added: 0, removed: 0 };
+}
+/** Resolves the repo-relative file path from tool_input, given the repo root. */
+function resolveRelativeFilePath(toolInput, repoRoot) {
+    const filePath = typeof toolInput.file_path === 'string' ? toolInput.file_path : null;
+    if (!filePath)
+        return null;
+    const rel = path.isAbsolute(filePath) ? path.relative(repoRoot, filePath) : filePath;
+    // Never store paths that resolve outside the repo (defensive; shouldn't normally happen).
+    if (rel.startsWith('..'))
+        return null;
+    return rel;
+}
+function appendLedgerLine(repoRoot, event) {
+    const devtraceDir = path.join(repoRoot, '.devtrace');
+    const ledgerPath = path.join(devtraceDir, exports.CLAUDE_LEDGER_FILENAME);
+    fs.appendFileSync(ledgerPath, JSON.stringify(event) + '\n', 'utf8');
+}
+function logHookError(repoRoot, message) {
+    try {
+        const devtraceDir = path.join(repoRoot, '.devtrace');
+        if (!fs.existsSync(devtraceDir))
+            return; // not initialized here — nothing to log into
+        const logPath = path.join(devtraceDir, exports.CLAUDE_HOOK_LOG_FILENAME);
+        const line = `[${new Date().toISOString()}] ${message}\n`;
+        fs.appendFileSync(logPath, line, 'utf8');
+    }
+    catch {
+        // Logging must never throw either.
+    }
+}
+/**
+ * Handles one Claude Code hook invocation (already-parsed JSON payload).
+ * Returns true if a ledger line was written, false if the event was a no-op
+ * (uninitialized repo, unsupported event, malformed payload). Never throws —
+ * all failures are caught internally and logged to .devtrace/hook.log.
+ */
+function handleHookEvent(rawPayload) {
+    let repoRootForLogging = process.cwd();
+    try {
+        if (!rawPayload || typeof rawPayload !== 'object')
+            return false;
+        const payload = rawPayload;
+        const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
+        repoRootForLogging = cwd;
+        const sessionId = typeof payload.session_id === 'string' ? payload.session_id : '';
+        const eventName = typeof payload.hook_event_name === 'string' ? payload.hook_event_name : '';
+        if (!sessionId || !eventName)
+            return false;
+        // Only act if DevTrace is initialized in this repo (.devtrace/ exists). Otherwise silent no-op.
+        const devtraceDir = path.join(cwd, '.devtrace');
+        if (!fs.existsSync(devtraceDir) || !fs.statSync(devtraceDir).isDirectory()) {
+            return false;
+        }
+        if (eventName === 'SessionStart') {
+            const model = typeof payload.model === 'string' && payload.model ? payload.model : null;
+            appendLedgerLine(cwd, {
+                kind: 'session-start',
+                ts: new Date().toISOString(),
+                sessionId,
+                model
+            });
+            return true;
+        }
+        if (eventName === 'PostToolUse') {
+            const toolName = typeof payload.tool_name === 'string' ? payload.tool_name : '';
+            if (!EDIT_TOOL_NAMES.has(toolName))
+                return false;
+            const toolInput = payload.tool_input && typeof payload.tool_input === 'object'
+                ? payload.tool_input
+                : {};
+            const relPath = resolveRelativeFilePath(toolInput, cwd);
+            if (!relPath)
+                return false;
+            const { added, removed } = computeLineDeltas(toolName, toolInput);
+            appendLedgerLine(cwd, {
+                kind: 'edit',
+                ts: new Date().toISOString(),
+                sessionId,
+                tool: toolName,
+                filePath: relPath,
+                linesAdded: added,
+                linesRemoved: removed
+            });
+            return true;
+        }
+        return false;
+    }
+    catch (err) {
+        logHookError(repoRootForLogging, `handleHookEvent error: ${err.message}`);
+        return false;
+    }
+}
+/**
+ * Reads all stdin synchronously (hook commands run once and exit; Claude Code
+ * waits for the process, so a blocking read is correct and simple here).
+ */
+function readStdinSync() {
+    try {
+        return fs.readFileSync(0, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Entry point for the `devtrace claude-hook` CLI command. Reads stdin JSON,
+ * dispatches to handleHookEvent, and NEVER throws — malformed input, missing
+ * fields, or an uninitialized repo all resolve to a silent no-op so Claude
+ * Code is never blocked or broken by DevTrace.
+ */
+function runClaudeHookCli() {
+    try {
+        const raw = readStdinSync();
+        if (!raw || !raw.trim())
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return; // malformed stdin: silent no-op, never crash
+        }
+        handleHookEvent(parsed);
+    }
+    catch {
+        // Absolute last resort — never let this throw out of the CLI entry point.
+    }
+}

package/dist/cli.js

@@ -0,0 +1,113 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliHelper = void 0;
+const readline = __importStar(require("readline"));
+class CliHelper {
+    static rl = null;
+    static initInterface() {
+        if (!this.rl) {
+            this.rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout
+            });
+        }
+    }
+    static closeInterface() {
+        if (this.rl) {
+            this.rl.close();
+            this.rl = null;
+        }
+    }
+    /**
+     * Prompts the user with a text question.
+     */
+    static askQuestion(query) {
+        this.initInterface();
+        return new Promise((resolve) => {
+            this.rl.question(query, (answer) => {
+                resolve(answer.trim());
+            });
+        });
+    }
+    /**
+     * Prompts the user with a multiple-choice question.
+     */
+    static async askChoice(query, options) {
+        console.log(`\n${query}`);
+        options.forEach((opt, idx) => {
+            console.log(`  ${idx + 1}: ${opt}`);
+        });
+        while (true) {
+            const answer = await this.askQuestion(`Choice [1-${options.length}]: `);
+            const choice = parseInt(answer, 10);
+            if (choice >= 1 && choice <= options.length) {
+                return choice;
+            }
+            console.log(`Invalid choice. Please select a number between 1 and ${options.length}.`);
+        }
+    }
+    /**
+     * Prompts the user for a Likert rating scale (1-5).
+     */
+    static async askLikert(query, description) {
+        console.log(`\n✏️  ${query}`);
+        console.log(`   (Scale 1-5: ${description})`);
+        while (true) {
+            const answer = await this.askQuestion('Score [1-5]: ');
+            const val = parseInt(answer, 10);
+            if (val >= 1 && val <= 5) {
+                return val;
+            }
+            console.log('Invalid input. Please enter a score from 1 to 5.');
+        }
+    }
+    /**
+     * Prompts the user for task complexity.
+     */
+    static async askComplexity() {
+        const choice = await this.askChoice('Rate Task Complexity:', [
+            'Low (simple bugfixes, refactorings, documentation changes)',
+            'Medium (standard features, styling changes, unit test suites)',
+            'High (large architectural adjustments, complex algorithms)'
+        ]);
+        if (choice === 1)
+            return 'low';
+        if (choice === 2)
+            return 'medium';
+        return 'high';
+    }
+}
+exports.CliHelper = CliHelper;