eai-cli 0.0.0-bootstrap.0

package/resources/gofer/hook-scripts/log-stage-launch-time.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * log-stage-launch-time.mjs — Gofer launch-latency hook
+ *
+ * Captures the latency between hook invocation and stage launch, then appends
+ * a JSONL record to `.specify/logs/stage-launch-time.jsonl`.
+ *
+ * This is used to compare numbered (`/3_gofer_plan`) vs namespaced
+ * (`/gofer:plan-stage`) launch paths so we can detect any performance
+ * regression introduced by the alias indirection.
+ *
+ * Inputs (env or argv):
+ *   GOFER_STAGE  / argv[2]      — stage name (e.g. `3_gofer_plan`)
+ *   GOFER_MODE   / argv[3]      — 'numbered' | 'namespaced'
+ *
+ * Optional:
+ *   GOFER_LOG_FILE              — override log file path (used by tests)
+ *   GOFER_PROJECT_DIR           — override project root (defaults to cwd)
+ *
+ * Output (one JSONL line per invocation):
+ *   { stage, mode, timestamp, latency_ms }
+ *
+ * Exits 0 on success, 0 even on missing inputs (logs are advisory).
+ */
+
+import { appendFileSync, existsSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+
+const T0 = process.hrtime.bigint();
+
+function resolveLogPath() {
+  if (process.env.GOFER_LOG_FILE) return process.env.GOFER_LOG_FILE;
+  const root = process.env.GOFER_PROJECT_DIR || process.cwd();
+  return join(root, '.specify', 'logs', 'stage-launch-time.jsonl');
+}
+
+function ensureDir(filePath) {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+function resolveStage() {
+  return process.env.GOFER_STAGE || process.argv[2] || 'unknown';
+}
+
+function resolveMode() {
+  const raw = process.env.GOFER_MODE || process.argv[3] || 'numbered';
+  // Normalize: only 'numbered' and 'namespaced' are valid; anything else
+  // is recorded as-is so we can spot bad call sites.
+  return raw;
+}
+
+function main() {
+  const stage = resolveStage();
+  const mode = resolveMode();
+  const logPath = resolveLogPath();
+  ensureDir(logPath);
+
+  // hrtime difference, converted to milliseconds.
+  const T1 = process.hrtime.bigint();
+  const latencyNs = Number(T1 - T0);
+  const latency_ms = latencyNs / 1_000_000;
+
+  const record = {
+    stage,
+    mode,
+    timestamp: new Date().toISOString(),
+    latency_ms,
+  };
+
+  appendFileSync(logPath, JSON.stringify(record) + '\n', 'utf8');
+  process.exit(0);
+}
+
+main();

package/resources/gofer/hook-scripts/post-tool-use.mjs

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+/**
+ * post-tool-use.mjs — Claude Code PostToolUse hook
+ *
+ * Fires on every tool call. Extracts tool_input and tool_response from the
+ * hook payload (when available) and writes per-observation files for the
+ * VS Code extension to consume. Also reads transcript JSONL for token usage
+ * metadata and writes context-bridge.json.
+ *
+ * stdin: JSON with { tool_name, session_id, transcript_path, tool_input?, tool_response?, tool_use_id? }
+ * stdout: (none — PostToolUse hooks don't produce output)
+ * Bridge: .specify/hooks/context-bridge-{sessionId}.json (per-session)
+ * Legacy: .specify/hooks/context-bridge.json (backward compat)
+ * Observations: .specify/hooks/observations/{uuid}.json
+ */
+
+import { readFileSync, writeFileSync, renameSync, mkdirSync, appendFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { randomUUID } from 'crypto';
+
+const PROJECT_DIR = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const HOOKS_DIR = join(PROJECT_DIR, '.specify', 'hooks');
+const BRIDGE_PATH = join(HOOKS_DIR, 'context-bridge.json');
+const OBSERVATIONS_DIR = join(PROJECT_DIR, '.specify', 'hooks', 'observations');
+const DEBUG_LOG = join(PROJECT_DIR, '.specify', 'hooks', 'hook-debug.log');
+const PERF_LOG = join(PROJECT_DIR, '.specify', 'hooks', 'hook-perf.jsonl');
+const PERF_ENABLED = process.env.GOFER_PERF_LOG === '1' || process.env.GOFER_PERF_MODE === '1';
+const TAIL_BYTES = 20 * 1024; // Read last 20KB of transcript
+const MAX_OBSERVATION_BYTES = 10240; // 10KB cap per observation
+
+function debug(msg) {
+  try {
+    const ts = new Date().toISOString();
+    appendFileSync(DEBUG_LOG, `[${ts}] [post-tool-use] ${msg}\n`);
+  } catch { /* ignore */ }
+}
+
+function perf(operation, start, extra = {}) {
+  if (!PERF_ENABLED) return;
+
+  try {
+    mkdirSync(dirname(PERF_LOG), { recursive: true });
+    const durationMs = Math.round((Date.now() - start) * 100) / 100;
+    appendFileSync(
+      PERF_LOG,
+      `${JSON.stringify({
+        hook: 'post-tool-use',
+        operation,
+        durationMs,
+        timestamp: new Date().toISOString(),
+        ...extra,
+      })}\n`
+    );
+  } catch {
+    // Performance logging must never affect hook behavior.
+  }
+}
+
+// Model context limits (tokens)
+const MODEL_LIMITS = {
+  'claude-opus-4-8': 1000000,
+  'claude-opus-4-7': 1000000,
+  'claude-opus-4-6': 1000000,
+  'claude-opus-4-5': 200000,
+  'claude-sonnet-4-6': 1000000,
+  'claude-sonnet-4-5': 200000,
+  'claude-sonnet-4-5-20250514': 200000,
+  'claude-sonnet-4-20250514': 200000,
+  'claude-haiku-4-5': 200000,
+  'claude-haiku-3-5-20241022': 200000,
+};
+
+function getContextLimit(model) {
+  if (!model) return 200000;
+  for (const [key, limit] of Object.entries(MODEL_LIMITS)) {
+    if (model.includes(key) || key.includes(model)) return limit;
+  }
+  return 200000;
+}
+
+function readStdin() {
+  try {
+    const raw = readFileSync(0, 'utf-8').trim();
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+function tailRead(filePath, bytes) {
+  try {
+    const fd = readFileSync(filePath);
+    const start = Math.max(0, fd.length - bytes);
+    return fd.subarray(start).toString('utf-8');
+  } catch {
+    return '';
+  }
+}
+
+function extractLatestUsage(transcriptPath) {
+  if (!transcriptPath) return null;
+
+  const tail = tailRead(transcriptPath, TAIL_BYTES);
+  if (!tail) return null;
+
+  const lines = tail.split('\n').filter(Boolean);
+
+  // Walk backward to find last assistant message with usage
+  for (let i = lines.length - 1; i >= 0; i--) {
+    try {
+      const entry = JSON.parse(lines[i]);
+      if (entry.type === 'assistant' && entry.message?.usage) {
+        const usage = entry.message.usage;
+        const model = entry.message?.model || '';
+        return {
+          inputTokens: usage.input_tokens || 0,
+          cacheCreationInputTokens: usage.cache_creation_input_tokens || 0,
+          cacheReadInputTokens: usage.cache_read_input_tokens || 0,
+          outputTokens: usage.output_tokens || 0,
+          model,
+          timestamp: entry.timestamp || new Date().toISOString(),
+        };
+      }
+    } catch {
+      // Skip malformed lines
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Serialize tool_response to a string, truncating to maxBytes if needed.
+ * Returns { content: string, truncated: boolean }
+ */
+function serializeToolResponse(toolResponse, maxBytes = MAX_OBSERVATION_BYTES) {
+  let content;
+  if (typeof toolResponse === 'string') {
+    content = toolResponse;
+  } else {
+    try {
+      content = JSON.stringify(toolResponse);
+    } catch {
+      content = String(toolResponse);
+    }
+  }
+
+  if (content.length > maxBytes) {
+    return {
+      content: content.slice(0, maxBytes) + '\n[truncated at 10KB]',
+      truncated: true,
+    };
+  }
+
+  return { content, truncated: false };
+}
+
+/**
+ * Write observation content to a per-observation file using atomic write.
+ * Returns the observation ID on success, null on failure.
+ */
+function writeObservation(id, toolName, toolInput, toolResponse) {
+  try {
+    mkdirSync(OBSERVATIONS_DIR, { recursive: true });
+
+    const serialized = serializeToolResponse(toolResponse);
+    const observation = {
+      id,
+      toolName,
+      toolInput: toolInput || {},
+      toolResponse: serialized.content,
+      timestamp: new Date().toISOString(),
+      truncated: serialized.truncated,
+    };
+
+    const filePath = join(OBSERVATIONS_DIR, `${id}.json`);
+    const tmpPath = filePath + '.tmp';
+    writeFileSync(tmpPath, JSON.stringify(observation, null, 2));
+    renameSync(tmpPath, filePath);
+
+    debug(`Observation written: id=${id}, tool=${toolName}, size=${serialized.content.length}, truncated=${serialized.truncated}`);
+    return id;
+  } catch (err) {
+    debug(`Observation write error: ${err.message}`);
+    return null;
+  }
+}
+
+function stripRuntimeBridgeFields(value) {
+  const copy = JSON.parse(JSON.stringify(value ?? {}));
+  delete copy.timestamp;
+  if (copy.session) {
+    delete copy.session.lastActivity;
+  }
+  if (copy.lastToolUse) {
+    delete copy.lastToolUse.timestamp;
+  }
+  return copy;
+}
+
+function bridgeEquivalent(left, right) {
+  return JSON.stringify(stripRuntimeBridgeFields(left)) === JSON.stringify(stripRuntimeBridgeFields(right));
+}
+
+function atomicWriteIfChanged(filePath, data, equivalent = (left, right) => JSON.stringify(left) === JSON.stringify(right)) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  try {
+    const existing = JSON.parse(readFileSync(filePath, 'utf-8'));
+    if (equivalent(existing, data)) {
+      return false;
+    }
+  } catch {
+    // Missing or invalid existing data should be replaced.
+  }
+
+  const tmpPath = filePath + '.tmp';
+  writeFileSync(tmpPath, JSON.stringify(data, null, 2));
+  renameSync(tmpPath, filePath);
+  return true;
+}
+
+function writeBridge(data) {
+  try {
+    const start = Date.now();
+    let writes = 0;
+
+    // Write per-session bridge file if sessionId is present
+    if (data.sessionId) {
+      // Sanitize sessionId to prevent path traversal
+      const safeSessionId = data.sessionId.replace(/[^a-zA-Z0-9_-]/g, '');
+      const perSessionPath = join(HOOKS_DIR, `context-bridge-${safeSessionId}.json`);
+      if (atomicWriteIfChanged(perSessionPath, data, bridgeEquivalent)) {
+        writes += 1;
+        debug(`Per-session bridge written: session=${data.sessionId}, path=${perSessionPath}`);
+      } else {
+        debug(`Per-session bridge unchanged: session=${data.sessionId}, path=${perSessionPath}`);
+      }
+    }
+
+    // Always write legacy bridge file for backward compat
+    if (atomicWriteIfChanged(BRIDGE_PATH, data, bridgeEquivalent)) {
+      writes += 1;
+      debug(`Legacy bridge written: session=${data.sessionId}, tool=${data.lastToolUse?.toolName}, obsId=${data.lastToolUse?.observationId || 'none'}`);
+    } else {
+      debug(`Legacy bridge unchanged: session=${data.sessionId}, tool=${data.lastToolUse?.toolName}, obsId=${data.lastToolUse?.observationId || 'none'}`);
+    }
+    perf('bridge-write', start, { writes });
+  } catch (err) {
+    debug(`Bridge write error: ${err.message}`);
+    process.stderr.write(`[post-tool-use] bridge write error: ${err.message}\n`);
+  }
+}
+
+function readExistingBridge() {
+  try {
+    return JSON.parse(readFileSync(BRIDGE_PATH, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+// Main
+debug(`Hook fired. PROJECT_DIR=${PROJECT_DIR}`);
+
+const input = readStdin();
+debug(`stdin: ${JSON.stringify({ session_id: input.session_id, tool_name: input.tool_name, has_transcript: !!input.transcript_path, has_tool_input: !!input.tool_input, has_tool_response: !!input.tool_response })}`);
+
+const sessionId = input.session_id || '';
+const toolName = input.tool_name || '';
+const transcriptPath = input.transcript_path || '';
+const toolInput = input.tool_input || undefined;
+const toolResponse = input.tool_response || undefined;
+
+const usage = extractLatestUsage(transcriptPath);
+debug(`usage: ${usage ? `inputTokens=${usage.inputTokens}, cache=${usage.cacheReadInputTokens}` : 'null'}`);
+
+// Write observation file if tool_response is available (new Claude Code payload)
+let observationId;
+if (toolResponse) {
+  const observationStart = Date.now();
+  observationId = randomUUID();
+  writeObservation(observationId, toolName, toolInput, toolResponse);
+  perf('observation-write', observationStart, { written: true });
+}
+
+const existing = readExistingBridge();
+const now = Date.now();
+
+const lastToolUse = {
+  toolName,
+  timestamp: now,
+};
+
+// Add observation pointer if observation was written
+if (observationId) {
+  lastToolUse.observationId = observationId;
+}
+if (toolInput) {
+  lastToolUse.toolInput = toolInput;
+}
+
+const bridge = {
+  timestamp: now,
+  sessionId,
+  model: usage?.model || existing.model || '',
+  context: usage
+    ? {
+        totalContextTokens:
+          usage.inputTokens +
+          usage.cacheCreationInputTokens +
+          usage.cacheReadInputTokens,
+        inputTokens: usage.inputTokens,
+        cacheCreationInputTokens: usage.cacheCreationInputTokens,
+        cacheReadInputTokens: usage.cacheReadInputTokens,
+        outputTokens: usage.outputTokens,
+        contextLimit: getContextLimit(usage.model),
+        utilizationPercent:
+          ((usage.inputTokens +
+            usage.cacheCreationInputTokens +
+            usage.cacheReadInputTokens) /
+            getContextLimit(usage.model)) *
+          100,
+      }
+    : existing.context || null,
+  lastToolUse,
+  session: {
+    active: true,
+    lastActivity: now,
+  },
+};
+
+writeBridge(bridge);
+perf('hook-total', now, { sessionId: sessionId || undefined, toolName: toolName || undefined });

package/resources/gofer/hook-scripts/queued-input.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * queued-input.mjs — Gofer queued-input hook (crash-resilient)
+ *
+ * When the user submits a prompt mid-stage, this hook captures the prompt as
+ * a queued input that will be replayed as a "next-prompt suggestion" once the
+ * current stage completes. This decouples user inputs from stage state
+ * without losing context across crashes.
+ *
+ * Wire-up:
+ *   - Default queue file: `<projectRoot>/.specify/state/queued-input.jsonl`
+ *   - Each JSONL record:
+ *       { id, timestamp, stage, prompt, payload, status }
+ *     where `status ∈ {queued, replayed, crashed}`.
+ *
+ * Behaviour:
+ *   1. On startup, scan the queue for `status=queued` or `status=crashed`
+ *      records left over from a previous session and report:
+ *        "<N> items pending replay"
+ *      to stderr.
+ *   2. Read JSON payload from stdin (best-effort).
+ *   3. Append a new JSONL record with `status='queued'`.
+ *   4. Log `queued: <total> items pending` to stderr (count of all non-empty
+ *      lines, preserving the original public log shape).
+ *   5. Exit 0.
+ *
+ * Public API (importable):
+ *   - readQueue(queuePath): JSONL records as objects (best-effort lenient).
+ *   - replayQueue(queuePath): returns and marks-replayed all `queued`/`crashed`
+ *     records. Idempotent.
+ *
+ * Environment:
+ *   GOFER_PROJECT_DIR   override project root (defaults to cwd)
+ *   GOFER_QUEUE_FILE    override queue file path (used by tests)
+ */
+
+import {
+  readFileSync,
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const STATUS_QUEUED = 'queued';
+const STATUS_REPLAYED = 'replayed';
+const STATUS_CRASHED = 'crashed';
+
+function readStdin() {
+  try {
+    const raw = readFileSync(0, 'utf8').trim();
+    if (!raw) return {};
+    return JSON.parse(raw);
+  } catch {
+    // Treat unparseable stdin as an empty payload — we still want to record
+    // that *something* tried to enqueue.
+    return {};
+  }
+}
+
+export function resolveQueuePath() {
+  if (process.env.GOFER_QUEUE_FILE) return process.env.GOFER_QUEUE_FILE;
+  const root = process.env.GOFER_PROJECT_DIR || process.cwd();
+  return join(root, '.specify', 'state', 'queued-input.jsonl');
+}
+
+function ensureDir(filePath) {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Read every JSONL record from the queue file. Lines that fail to parse are
+ * skipped (logged to stderr but not fatal — we want to be resilient to a
+ * partially-written line from a hard crash).
+ *
+ * @param {string} queuePath
+ * @returns {Array<{ id: string, timestamp: string, stage: string|null, prompt: string|null, payload: object, status: string }>}
+ */
+export function readQueue(queuePath) {
+  if (!existsSync(queuePath)) return [];
+  const raw = readFileSync(queuePath, 'utf8');
+  const out = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      out.push(JSON.parse(trimmed));
+    } catch {
+      // Skip malformed line (likely truncated by a crash mid-write).
+    }
+  }
+  return out;
+}
+
+/**
+ * Returns records that need replay (status=queued or status=crashed) and
+ * rewrites the queue with their statuses flipped to `replayed`. Idempotent:
+ * calling twice returns an empty array on the second call.
+ *
+ * @param {string} [queuePathOverride]
+ */
+export function replayQueue(queuePathOverride) {
+  const queuePath = queuePathOverride || resolveQueuePath();
+  const records = readQueue(queuePath);
+  const pending = records.filter(
+    (r) => r.status === STATUS_QUEUED || r.status === STATUS_CRASHED,
+  );
+
+  if (pending.length === 0) return [];
+
+  // Flip pending records to replayed, preserving order and the rest unchanged.
+  const updated = records.map((r) => {
+    if (r.status === STATUS_QUEUED || r.status === STATUS_CRASHED) {
+      return { ...r, status: STATUS_REPLAYED, replayedAt: new Date().toISOString() };
+    }
+    return r;
+  });
+
+  ensureDir(queuePath);
+  writeFileSync(
+    queuePath,
+    updated.map((r) => JSON.stringify(r)).join('\n') + '\n',
+    'utf8',
+  );
+
+  return pending;
+}
+
+function countLines(filePath) {
+  try {
+    const raw = readFileSync(filePath, 'utf8');
+    if (!raw) return 0;
+    return raw.split('\n').filter((l) => l.trim().length > 0).length;
+  } catch {
+    return 0;
+  }
+}
+
+function countPending(filePath) {
+  const records = readQueue(filePath);
+  return records.filter(
+    (r) => r.status === STATUS_QUEUED || r.status === STATUS_CRASHED,
+  ).length;
+}
+
+function main() {
+  const payload = readStdin();
+  const queuePath = resolveQueuePath();
+  ensureDir(queuePath);
+
+  // Crash-recovery summary (T146): if there are leftover pending records from
+  // a previous session, surface them on the very first hook invocation.
+  const leftover = countPending(queuePath);
+  if (leftover > 0) {
+    process.stderr.write(`${leftover} items pending replay\n`);
+  }
+
+  const record = {
+    id: randomUUID(),
+    timestamp: new Date().toISOString(),
+    stage: payload.stage ?? null,
+    prompt: payload.prompt ?? null,
+    payload,
+    status: STATUS_QUEUED,
+  };
+
+  appendFileSync(queuePath, JSON.stringify(record) + '\n', 'utf8');
+
+  const pending = countLines(queuePath);
+  process.stderr.write(`queued: ${pending} items pending\n`);
+
+  process.exit(0);
+}
+
+// Only run main when executed directly (not when imported as a module).
+const isMain =
+  process.argv[1] &&
+  (process.argv[1].endsWith('queued-input.mjs') ||
+    process.argv[1] === new URL(import.meta.url).pathname);
+
+if (isMain) {
+  main();
+}

package/resources/gofer/hook-scripts/session-lifecycle.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * session-lifecycle.mjs — Claude Code SessionStart / SessionEnd hook
+ *
+ * Shared script, mode determined by CLI argument:
+ *   node session-lifecycle.mjs start
+ *   node session-lifecycle.mjs end
+ *
+ * start: Writes bridge with session.active: true
+ * end:   Writes bridge with session.active: false
+ *
+ * stdin:  JSON with { session_id, transcript_path }
+ * stdout: (none)
+ * Bridge: .specify/hooks/context-bridge.json
+ */
+
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+
+const PROJECT_DIR = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const BRIDGE_PATH = join(PROJECT_DIR, '.specify', 'hooks', 'context-bridge.json');
+
+const mode = process.argv[2] || 'start'; // 'start' or 'end'
+
+function readStdin() {
+  try {
+    const chunks = [];
+    try {
+      let bytesRead;
+      while ((bytesRead = readFileSync(0, { length: 4096 })) && bytesRead.length > 0) {
+        chunks.push(Buffer.from(bytesRead));
+      }
+    } catch {
+      // EOF
+    }
+    const raw = Buffer.concat(chunks).toString('utf-8').trim();
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeBridge(data) {
+  try {
+    mkdirSync(dirname(BRIDGE_PATH), { recursive: true });
+    const tmpPath = BRIDGE_PATH + '.tmp';
+    writeFileSync(tmpPath, JSON.stringify(data, null, 2));
+    renameSync(tmpPath, BRIDGE_PATH);
+  } catch {
+    // Silently fail
+  }
+}
+
+// Main
+const input = readStdin();
+const sessionId = input.session_id || '';
+const now = Date.now();
+
+if (mode === 'start') {
+  const bridge = {
+    timestamp: now,
+    sessionId,
+    model: '',
+    context: null,
+    lastToolUse: null,
+    session: {
+      active: true,
+      lastActivity: now,
+      startedAt: now,
+    },
+  };
+  writeBridge(bridge);
+} else {
+  // end
+  let existing = {};
+  try {
+    existing = JSON.parse(readFileSync(BRIDGE_PATH, 'utf-8'));
+  } catch {
+    // No existing bridge
+  }
+
+  const bridge = {
+    ...existing,
+    timestamp: now,
+    sessionId: sessionId || existing.sessionId || '',
+    session: {
+      active: false,
+      lastActivity: now,
+      endedAt: now,
+    },
+  };
+  writeBridge(bridge);
+}