@jmylchreest/aide-plugin 0.0.57 → 0.0.58

package/src/hooks/task-completed.ts

@@ -0,0 +1,445 @@
+#!/usr/bin/env node
+/**
+ * Task Completed Hook (TaskCompleted)
+ *
+ * OPT-IN: This hook is NOT registered in plugin.json by default.
+ * To enable, add a TaskCompleted entry to .claude-plugin/plugin.json.
+ * Not available in OpenCode (no equivalent event).
+ *
+ * Validates SDLC stage completion before allowing tasks to be marked complete.
+ * Parses task subject for [story-id][STAGE] pattern and runs stage-specific checks.
+ *
+ * Stage validations:
+ * - DESIGN: Check for design output (decisions, interfaces)
+ * - TEST: Check that test files exist
+ * - DEV: Check that tests pass
+ * - VERIFY: Full suite green, lint clean
+ * - DOCS: Check that docs were updated
+ *
+ * Exit codes:
+ * - 0: Allow completion
+ * - 2: Block completion (stderr fed back as feedback)
+ */
+
+import spawn from "cross-spawn";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import which from "which";
+import { debug, setDebugCwd } from "../lib/logger.js";
+import { readStdin } from "../lib/hook-utils.js";
+
+const SOURCE = "task-completed";
+
+// Safety limit for regex parsing
+const MAX_SUBJECT_LENGTH = 1000;
+
+interface HookInput {
+  hook_event_name: "TaskCompleted";
+  session_id: string;
+  cwd: string;
+  task_id: string;
+  task_subject: string;
+  task_description?: string;
+  teammate_name?: string;
+  team_name?: string;
+}
+
+interface StageInfo {
+  storyId: string;
+  stage: string;
+}
+
+/**
+ * Parse task subject for SDLC stage pattern
+ * Expected: [story-id][STAGE] Description
+ */
+function parseStageFromSubject(subject: string): StageInfo | null {
+  // Safety check for regex
+  if (subject.length > MAX_SUBJECT_LENGTH) {
+    debug(SOURCE, `Subject too long for parsing (${subject.length} chars)`);
+    return null;
+  }
+
+  // Match patterns like:
+  // [story-auth][DESIGN] Design auth module
+  // [Story-1][DEV] Implement feature
+  const match = subject.match(/\[([^\]]+)\]\[([A-Z]+)\]/i);
+  if (!match) return null;
+
+  return {
+    storyId: match[1],
+    stage: match[2].toUpperCase(),
+  };
+}
+
+/**
+ * Split a shell-style command string into [binary, ...args] for execFileSync.
+ * Handles simple cases like "npm test", "go test ./...", "npx tsc --noEmit".
+ */
+function splitCommand(cmd: string): [string, string[]] {
+  const parts = cmd.split(/\s+/).filter(Boolean);
+  return [parts[0], parts.slice(1)];
+}
+
+/**
+ * Check if a command succeeds (cross-platform via cross-spawn)
+ */
+function commandSucceeds(cmd: string, cwd: string): boolean {
+  const [bin, args] = splitCommand(cmd);
+  if (!which.sync(bin, { nothrow: true })) {
+    debug(SOURCE, `Binary not found in PATH: ${bin}`);
+    return false;
+  }
+  const result = spawn.sync(bin, args, { cwd, stdio: "pipe", timeout: 60000 });
+  if (result.status !== 0) {
+    debug(SOURCE, `Command failed: ${cmd}: exit ${result.status}`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Get command output or null on failure (cross-platform via cross-spawn)
+ */
+function getCommandOutput(cmd: string, cwd: string): string | null {
+  const [bin, args] = splitCommand(cmd);
+  if (!which.sync(bin, { nothrow: true })) {
+    debug(SOURCE, `Binary not found in PATH: ${bin}`);
+    return null;
+  }
+  const result = spawn.sync(bin, args, { cwd, stdio: "pipe", timeout: 30000 });
+  if (result.status !== 0 || !result.stdout) {
+    debug(SOURCE, `getCommandOutput failed for: ${cmd}: exit ${result.status}`);
+    return null;
+  }
+  return result.stdout.toString().trim();
+}
+
+/**
+ * Detect project type (typescript, go, python)
+ */
+function detectProjectType(
+  cwd: string,
+): "typescript" | "go" | "python" | "unknown" {
+  if (existsSync(join(cwd, "package.json"))) return "typescript";
+  if (existsSync(join(cwd, "go.mod"))) return "go";
+  if (
+    existsSync(join(cwd, "pyproject.toml")) ||
+    existsSync(join(cwd, "setup.py"))
+  )
+    return "python";
+  return "unknown";
+}
+
+/**
+ * Validate DESIGN stage completion
+ */
+function validateDesign(
+  cwd: string,
+  storyId: string,
+): { ok: boolean; reason?: string } {
+  // Check if any decisions were recorded for this story
+  // This is a soft check - design output is hard to validate programmatically
+  debug(SOURCE, `Validating DESIGN for ${storyId}`);
+
+  // For now, just pass - design validation is subjective
+  // Could be enhanced to check for design doc files or decisions
+  return { ok: true };
+}
+
+/**
+ * Validate TEST stage completion
+ */
+function validateTest(
+  cwd: string,
+  storyId: string,
+): { ok: boolean; reason?: string } {
+  debug(SOURCE, `Validating TEST for ${storyId}`);
+
+  const projectType = detectProjectType(cwd);
+
+  // Check if test files exist (recently modified)
+  const testPatterns: Record<string, string[]> = {
+    typescript: [
+      "**/*.test.ts",
+      "**/*.spec.ts",
+      "**/*.test.tsx",
+      "**/*.spec.tsx",
+    ],
+    go: ["**/*_test.go"],
+    python: ["**/test_*.py", "**/*_test.py"],
+    unknown: [],
+  };
+
+  // For now, just pass - test file existence is hard to validate without grep
+  // The real validation happens in DEV stage (tests must pass)
+  return { ok: true };
+}
+
+/**
+ * Validate DEV stage completion
+ */
+function validateDev(
+  cwd: string,
+  storyId: string,
+): { ok: boolean; reason?: string } {
+  debug(SOURCE, `Validating DEV for ${storyId}`);
+
+  const projectType = detectProjectType(cwd);
+
+  // Run tests based on project type
+  const testCommands: Record<string, string> = {
+    typescript: "npm test",
+    go: "go test ./...",
+    python: "pytest",
+    unknown: "",
+  };
+
+  const testCmd = testCommands[projectType];
+  if (!testCmd) {
+    debug(SOURCE, "Unknown project type, skipping test validation");
+    return { ok: true };
+  }
+
+  // Check if test command exists in package.json scripts
+  if (projectType === "typescript") {
+    try {
+      const pkgPath = join(cwd, "package.json");
+      if (!existsSync(pkgPath)) return { ok: true };
+      const pkgJson = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      if (!pkgJson?.scripts?.test) {
+        debug(SOURCE, "No test script defined, skipping");
+        return { ok: true };
+      }
+    } catch (err) {
+      debug(SOURCE, `Failed to read package.json: ${err}`);
+      return { ok: true };
+    }
+  }
+
+  if (!commandSucceeds(testCmd, cwd)) {
+    return {
+      ok: false,
+      reason: `Tests are failing. Run \`${testCmd}\` and fix failures before completing DEV stage.`,
+    };
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Run a validation command, checking package.json for script existence when
+ * the project is TypeScript. Returns a failure message or null if the check
+ * passed (or was skipped because the script doesn't exist).
+ */
+function runValidationStep(
+  label: string,
+  cmd: string,
+  scriptName: string | null,
+  projectType: string,
+  cwd: string,
+): string | null {
+  if (!cmd) return null;
+
+  if (projectType === "typescript" && scriptName) {
+    try {
+      const pkgPath = join(cwd, "package.json");
+      if (!existsSync(pkgPath)) return null;
+      const pkgJson = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      if (!pkgJson.scripts?.[scriptName]) return null;
+    } catch (err) {
+      debug(
+        SOURCE,
+        `Failed to check ${scriptName} script in package.json: ${err}`,
+      );
+      return null;
+    }
+  }
+
+  if (!commandSucceeds(cmd, cwd)) {
+    return `${label}: run \`${cmd}\``;
+  }
+  return null;
+}
+
+/**
+ * Validate VERIFY stage completion
+ */
+function validateVerify(
+  cwd: string,
+  storyId: string,
+): { ok: boolean; reason?: string } {
+  debug(SOURCE, `Validating VERIFY for ${storyId}`);
+
+  const projectType = detectProjectType(cwd);
+  const failures: string[] = [];
+
+  // Define validation steps per project type: [label, commands-by-type, package.json script name]
+  const steps: Array<{
+    label: string;
+    commands: Record<string, string>;
+    scriptName: string | null;
+  }> = [
+    {
+      label: "Tests failing",
+      commands: {
+        typescript: "npm test",
+        go: "go test ./...",
+        python: "pytest",
+        unknown: "",
+      },
+      scriptName: null, // always run if command exists
+    },
+    {
+      label: "Lint errors",
+      commands: {
+        typescript: "npm run lint",
+        go: "go vet ./...",
+        python: "ruff check .",
+        unknown: "",
+      },
+      scriptName: "lint",
+    },
+    {
+      label: "Type errors",
+      commands: {
+        typescript: "npx tsc --noEmit",
+        go: "",
+        python: "",
+        unknown: "",
+      },
+      scriptName: null,
+    },
+    {
+      label: "Build failing",
+      commands: {
+        typescript: "npm run build",
+        go: "go build ./...",
+        python: "",
+        unknown: "",
+      },
+      scriptName: "build",
+    },
+  ];
+
+  for (const step of steps) {
+    const cmd = step.commands[projectType] || "";
+    const failure = runValidationStep(
+      step.label,
+      cmd,
+      step.scriptName,
+      projectType,
+      cwd,
+    );
+    if (failure) failures.push(failure);
+  }
+
+  if (failures.length > 0) {
+    return {
+      ok: false,
+      reason: `VERIFY stage incomplete:\n${failures.map((f) => `- ${f}`).join("\n")}`,
+    };
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Validate DOCS stage completion
+ */
+function validateDocs(
+  cwd: string,
+  storyId: string,
+): { ok: boolean; reason?: string } {
+  debug(SOURCE, `Validating DOCS for ${storyId}`);
+
+  // Documentation validation is subjective
+  // Could check for recently modified .md files or doc comments
+  // For now, just pass
+  return { ok: true };
+}
+
+/**
+ * Main validation dispatcher
+ */
+function validateStage(
+  cwd: string,
+  stage: string,
+  storyId: string,
+): { ok: boolean; reason?: string } {
+  switch (stage) {
+    case "DESIGN":
+      return validateDesign(cwd, storyId);
+    case "TEST":
+      return validateTest(cwd, storyId);
+    case "DEV":
+      return validateDev(cwd, storyId);
+    case "VERIFY":
+      return validateVerify(cwd, storyId);
+    case "DOCS":
+      return validateDocs(cwd, storyId);
+    case "FIX":
+      // FIX stage just needs to pass - it's a remediation stage
+      return { ok: true };
+    default:
+      debug(SOURCE, `Unknown stage: ${stage}, allowing completion`);
+      return { ok: true };
+  }
+}
+
+async function main(): Promise<void> {
+  try {
+    const input = await readStdin();
+    if (!input.trim()) {
+      process.exit(0);
+    }
+
+    const data: HookInput = JSON.parse(input);
+    const cwd = data.cwd || process.cwd();
+
+    setDebugCwd(cwd);
+    debug(SOURCE, `TaskCompleted: ${data.task_subject}`);
+
+    // Parse stage from task subject
+    const stageInfo = parseStageFromSubject(data.task_subject);
+
+    if (!stageInfo) {
+      // Not an SDLC task, allow completion
+      debug(SOURCE, "Not an SDLC task, allowing completion");
+      process.exit(0);
+    }
+
+    debug(
+      SOURCE,
+      `SDLC task: story=${stageInfo.storyId}, stage=${stageInfo.stage}`,
+    );
+
+    // Validate the stage
+    const result = validateStage(cwd, stageInfo.stage, stageInfo.storyId);
+
+    if (!result.ok) {
+      // Block completion - stderr is fed back to the agent
+      console.error(result.reason);
+      process.exit(2);
+    }
+
+    // Allow completion
+    debug(SOURCE, `Stage ${stageInfo.stage} validation passed`);
+    process.exit(0);
+  } catch (err) {
+    debug(SOURCE, `Error: ${err}`);
+    // On error, allow completion (don't block on hook failures)
+    process.exit(0);
+  }
+}
+
+process.on("uncaughtException", (err) => {
+  debug(SOURCE, `UNCAUGHT EXCEPTION: ${err}`);
+  process.exit(0);
+});
+process.on("unhandledRejection", (reason) => {
+  debug(SOURCE, `UNHANDLED REJECTION: ${reason}`);
+  process.exit(0);
+});
+
+main();

package/src/hooks/tool-tracker.ts

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * Tool Tracker Hook (PreToolUse)
+ *
+ * Tracks the currently running tool per agent for HUD display.
+ * Sets currentTool in aide-memory before tool execution.
+ */
+
+import { readStdin } from "../lib/hook-utils.js";
+import { trackToolUse, formatToolDescription } from "../core/tool-tracking.js";
+import { findAideBinary } from "../core/aide-client.js";
+import { debug } from "../lib/logger.js";
+
+const SOURCE = "tool-tracker";
+
+interface HookInput {
+  hook_event_name: string;
+  session_id: string;
+  cwd: string;
+  tool_name?: string;
+  agent_id?: string;
+  tool_input?: {
+    command?: string;
+    description?: string;
+    prompt?: string;
+    file_path?: string;
+    model?: string;
+    subagent_type?: string;
+  };
+  transcript_path?: string;
+  permission_mode?: string;
+}
+
+async function main(): Promise<void> {
+  try {
+    const input = await readStdin();
+    if (!input.trim()) {
+      console.log(JSON.stringify({ continue: true }));
+      return;
+    }
+
+    const data: HookInput = JSON.parse(input);
+    const cwd = data.cwd || process.cwd();
+    const agentId = data.agent_id || data.session_id;
+    const toolName = data.tool_name || "";
+
+    if (agentId && toolName) {
+      const binary = findAideBinary({
+        cwd,
+        pluginRoot:
+          process.env.AIDE_PLUGIN_ROOT || process.env.CLAUDE_PLUGIN_ROOT,
+      });
+
+      if (binary) {
+        trackToolUse(binary, cwd, {
+          toolName,
+          agentId,
+          toolInput: data.tool_input,
+        });
+      }
+    }
+
+    console.log(JSON.stringify({ continue: true }));
+  } catch (error) {
+    debug(SOURCE, `Hook error: ${error}`);
+    console.log(JSON.stringify({ continue: true }));
+  }
+}
+
+process.on("uncaughtException", (err) => {
+  debug(SOURCE, `UNCAUGHT EXCEPTION: ${err}`);
+  try {
+    console.log(JSON.stringify({ continue: true }));
+  } catch {
+    console.log('{"continue":true}');
+  }
+  process.exit(0);
+});
+process.on("unhandledRejection", (reason) => {
+  debug(SOURCE, `UNHANDLED REJECTION: ${reason}`);
+  try {
+    console.log(JSON.stringify({ continue: true }));
+  } catch {
+    console.log('{"continue":true}');
+  }
+  process.exit(0);
+});
+
+main();

package/src/hooks/write-guard.ts

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * Write Guard Hook (PreToolUse)
+ *
+ * Advises the agent to use Edit instead of Write on existing files.
+ * Injects advisory context (soft warning) rather than blocking,
+ * preventing excessive permission prompts in Claude Code.
+ *
+ * Core logic is in src/core/write-guard.ts for cross-platform reuse.
+ */
+
+import { readStdin } from "../lib/hook-utils.js";
+import { debug } from "../lib/logger.js";
+import { checkWriteGuard } from "../core/write-guard.js";
+
+const SOURCE = "write-guard";
+
+interface HookInput {
+  hook_event_name: string;
+  session_id: string;
+  cwd: string;
+  tool_name?: string;
+  agent_name?: string;
+  agent_id?: string;
+  tool_input?: Record<string, unknown>;
+  transcript_path?: string;
+  permission_mode?: string;
+}
+
+interface HookOutput {
+  continue: boolean;
+  message?: string;
+  hookSpecificOutput?: {
+    hookEventName: string;
+    additionalContext?: string;
+  };
+}
+
+async function main(): Promise<void> {
+  try {
+    const input = await readStdin();
+    if (!input.trim()) {
+      console.log(JSON.stringify({ continue: true }));
+      return;
+    }
+
+    const data: HookInput = JSON.parse(input);
+    const toolName = data.tool_name || "";
+    const toolInput = data.tool_input || {};
+    const cwd = data.cwd || process.cwd();
+
+    const result = checkWriteGuard(toolName, toolInput, cwd);
+
+    if (!result.allowed) {
+      debug(
+        SOURCE,
+        `Advisory: Write to existing file: ${toolInput.file_path || toolInput.filePath || toolInput.path}`,
+      );
+      const output: HookOutput = {
+        continue: true,
+        hookSpecificOutput: {
+          hookEventName: data.hook_event_name || "PreToolUse",
+          additionalContext: result.message,
+        },
+      };
+      console.log(JSON.stringify(output));
+    } else {
+      console.log(JSON.stringify({ continue: true }));
+    }
+  } catch (error) {
+    debug(SOURCE, `Hook error: ${error}`);
+    console.log(JSON.stringify({ continue: true }));
+  }
+}
+
+process.on("uncaughtException", (err) => {
+  debug(SOURCE, `UNCAUGHT EXCEPTION: ${err}`);
+  try {
+    console.log(JSON.stringify({ continue: true }));
+  } catch {
+    console.log('{"continue":true}');
+  }
+  process.exit(0);
+});
+process.on("unhandledRejection", (reason) => {
+  debug(SOURCE, `UNHANDLED REJECTION: ${reason}`);
+  try {
+    console.log(JSON.stringify({ continue: true }));
+  } catch {
+    console.log('{"continue":true}');
+  }
+  process.exit(0);
+});
+
+main();

package/src/lib/hook-utils.ts

@@ -1,5 +1,5 @@
 /**
- * Shared utilities for Claude Code hooks.
+ * Shared utilities for Claude Code and Codex CLI hooks.
  *
  * readStdin() is the only unique implementation here. All other functions
  * are convenience wrappers around src/core/aide-client.ts that resolve the
@@ -41,6 +41,58 @@ export async function readStdin(): Promise<string> {
   return Buffer.concat(chunks).toString("utf-8");
 }
 
+/**
+ * Normalize hook input JSON from different platforms (Claude Code, Codex CLI).
+ *
+ * Both platforms use command-type hooks with JSON stdin, but field names may
+ * differ between versions. This function maps known alternative names to the
+ * canonical snake_case format used by aide hook scripts.
+ *
+ * Returns the normalized JSON string (or the original if no changes needed).
+ */
+export function normalizeHookInput(raw: string): string {
+  try {
+    const data = JSON.parse(raw) as Record<string, unknown>;
+
+    // Map known alternative field names → canonical snake_case
+    const aliases: Record<string, string> = {
+      hookEventName: "hook_event_name",
+      sessionId: "session_id",
+      toolName: "tool_name",
+      agentId: "agent_id",
+      agentName: "agent_name",
+      toolInput: "tool_input",
+      permissionMode: "permission_mode",
+    };
+
+    let changed = false;
+    for (const [alt, canonical] of Object.entries(aliases)) {
+      if (alt in data && !(canonical in data)) {
+        data[canonical] = data[alt];
+        delete data[alt];
+        changed = true;
+      }
+    }
+
+    return changed ? JSON.stringify(data) : raw;
+  } catch {
+    return raw;
+  }
+}
+
+/**
+ * Detect which AI assistant harness is running these hooks.
+ *
+ * - Codex CLI: hook dispatcher sets AIDE_PLATFORM=codex
+ * - Claude Code: sets CLAUDE_PLUGIN_ROOT
+ * - OpenCode uses a separate code path (src/opencode/hooks.ts), so hooks
+ *   in src/hooks/ are only invoked by Claude Code or Codex.
+ */
+export function detectPlatform(): "claude-code" | "codex" {
+  if (process.env.AIDE_PLATFORM === "codex") return "codex";
+  return "claude-code";
+}
+
 /**
  * Get the plugin root directory from environment variables.
  */