@jmylchreest/aide-plugin 0.0.56 → 0.0.58

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jmylchreest/aide-plugin",
-  "version": "0.0.56",
-  "description": "aide plugin for OpenCode — multi-agent orchestration, memory, skills, and persistence",
+  "version": "0.0.58",
+  "description": "aide plugin for OpenCode and Codex CLI — multi-agent orchestration, memory, skills, and persistence",
   "type": "module",
   "main": "./src/opencode/index.ts",
   "exports": {
@@ -14,6 +14,7 @@
     "src/core",
     "src/cli",
     "src/lib",
+    "src/hooks",
     "skills",
     "bin",
     "README.md"
@@ -31,6 +32,7 @@
   "keywords": [
     "aide",
     "opencode",
+    "codex",
     "ai",
     "agents",
     "orchestration",
@@ -50,6 +52,7 @@
   },
   "dependencies": {
     "cross-spawn": "^7.0.6",
+    "smol-toml": "^1.3.1",
     "which": "^6.0.1"
   }
 }

package/src/cli/codex-config.ts

@@ -0,0 +1,428 @@
+/**
+ * Codex CLI configuration generator.
+ *
+ * Generates .codex/config.toml (MCP server) and .codex/hooks.json
+ * for integrating aide with Codex CLI.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { homedir } from "os";
+import * as TOML from "smol-toml";
+import whichSync from "which";
+
+const MCP_SERVER_NAME = "aide";
+const AIDE_PLUGIN_BIN_NAME = "aide-plugin";
+
+/** Check if a hook command belongs to aide (matches both global install and local dev paths). */
+function isAideHookCommand(command?: string): boolean {
+  if (!command) return false;
+  return command.includes(AIDE_PLUGIN_BIN_NAME) || command.includes("index.ts hook");
+}
+
+/**
+ * Resolve the command prefix for hook/mcp commands.
+ *
+ * If `aide-plugin` is on PATH (global npm install), use it directly.
+ * Otherwise fall back to `bun <path-to-cli>` for local dev.
+ */
+function resolvePluginCommand(): { bin: string; hookPrefix: string; mcpCommand: string; mcpArgs: string[]; wrapperEnv?: Record<string, string> } {
+  try {
+    const resolved = whichSync.sync(AIDE_PLUGIN_BIN_NAME, { nothrow: true });
+    if (resolved) {
+      return {
+        bin: AIDE_PLUGIN_BIN_NAME,
+        hookPrefix: `${AIDE_PLUGIN_BIN_NAME} hook`,
+        mcpCommand: AIDE_PLUGIN_BIN_NAME,
+        mcpArgs: ["mcp"],
+      };
+    }
+  } catch { /* not on PATH */ }
+
+  // Fallback: use bun with full path to the wrapper/CLI
+  const thisDir = dirname(fileURLToPath(import.meta.url));
+  const pluginRoot = resolve(thisDir, "..", "..");
+  const cliPath = join(pluginRoot, "src", "cli", "index.ts");
+  const wrapperPath = join(pluginRoot, "bin", "aide-wrapper.ts");
+
+  return {
+    bin: `bun ${cliPath}`,
+    hookPrefix: `bun ${cliPath} hook`,
+    mcpCommand: "bun",
+    mcpArgs: [wrapperPath, "mcp"],
+    wrapperEnv: { AIDE_PLUGIN_ROOT: pluginRoot },
+  };
+}
+
+// =============================================================================
+// Config paths
+// =============================================================================
+
+export function getCodexGlobalConfigDir(): string {
+  return join(homedir(), ".codex");
+}
+
+export function getCodexProjectConfigDir(cwd?: string): string {
+  return join(cwd || process.cwd(), ".codex");
+}
+
+export function getCodexConfigTomlPath(scope: "user" | "project"): string {
+  const dir =
+    scope === "user"
+      ? getCodexGlobalConfigDir()
+      : getCodexProjectConfigDir();
+  return join(dir, "config.toml");
+}
+
+export function getCodexHooksJsonPath(scope: "user" | "project"): string {
+  const dir =
+    scope === "user"
+      ? getCodexGlobalConfigDir()
+      : getCodexProjectConfigDir();
+  return join(dir, "hooks.json");
+}
+
+// =============================================================================
+// TOML config read/write
+// =============================================================================
+
+interface CodexTomlConfig {
+  mcp_servers?: Record<string, Record<string, unknown>>;
+  [key: string]: unknown;
+}
+
+function readCodexToml(path: string): CodexTomlConfig {
+  if (!existsSync(path)) return {};
+  try {
+    return TOML.parse(readFileSync(path, "utf-8")) as CodexTomlConfig;
+  } catch {
+    return {};
+  }
+}
+
+function writeCodexToml(path: string, config: CodexTomlConfig): void {
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    path,
+    TOML.stringify(config as Record<string, unknown>) + "\n",
+  );
+}
+
+// =============================================================================
+// hooks.json generation
+// =============================================================================
+
+interface CodexHookEntry {
+  type: string;
+  command: string;
+  timeout?: number;
+  statusMessage?: string;
+}
+
+interface CodexHookMatcher {
+  matcher: string;
+  hooks: CodexHookEntry[];
+}
+
+interface CodexHooksJson {
+  hooks: Record<string, CodexHookMatcher[]>;
+}
+
+function generateHooksJson(hookPrefix: string): CodexHooksJson {
+  return {
+    hooks: {
+      SessionStart: [
+        {
+          matcher: "*",
+          hooks: [
+            {
+              type: "command",
+              command: `${hookPrefix} session-start`,
+              timeout: 60,
+              statusMessage: "Initializing aide session",
+            },
+          ],
+        },
+      ],
+      UserPromptSubmit: [
+        {
+          matcher: "*",
+          hooks: [
+            {
+              type: "command",
+              command: `${hookPrefix} skill-injector`,
+              timeout: 5,
+              statusMessage: "Matching aide skills",
+            },
+          ],
+        },
+      ],
+      PreToolUse: [
+        {
+          matcher: "*",
+          hooks: [
+            {
+              type: "command",
+              command: `${hookPrefix} tool-tracker`,
+              timeout: 2,
+            },
+            {
+              type: "command",
+              command: `${hookPrefix} write-guard`,
+              timeout: 3,
+            },
+            {
+              type: "command",
+              command: `${hookPrefix} pre-tool-enforcer`,
+              timeout: 3,
+            },
+            {
+              type: "command",
+              command: `${hookPrefix} context-guard`,
+              timeout: 2,
+            },
+          ],
+        },
+      ],
+      PostToolUse: [
+        {
+          matcher: "*",
+          hooks: [
+            {
+              type: "command",
+              command: `${hookPrefix} comment-checker`,
+              timeout: 3,
+            },
+            {
+              type: "command",
+              command: `${hookPrefix} context-pruning`,
+              timeout: 3,
+            },
+          ],
+        },
+      ],
+      Stop: [
+        {
+          matcher: "*",
+          hooks: [
+            {
+              type: "command",
+              command: `${hookPrefix} persistence`,
+              timeout: 5,
+            },
+            {
+              type: "command",
+              command: `${hookPrefix} session-summary`,
+              timeout: 10,
+            },
+            {
+              type: "command",
+              command: `${hookPrefix} agent-cleanup`,
+              timeout: 5,
+            },
+            {
+              type: "command",
+              command: `${hookPrefix} session-end`,
+              timeout: 10,
+            },
+          ],
+        },
+      ],
+    },
+  };
+}
+
+// =============================================================================
+// Install / uninstall
+// =============================================================================
+
+export function installCodex(scope: "user" | "project"): {
+  configWritten: boolean;
+  hooksWritten: boolean;
+} {
+  const configPath = getCodexConfigTomlPath(scope);
+  const hooksPath = getCodexHooksJsonPath(scope);
+  let configWritten = false;
+  let hooksWritten = false;
+
+  const config = readCodexToml(configPath);
+  const resolved = resolvePluginCommand();
+  let configChanged = false;
+
+  // Enable hooks feature flag (required for Codex to process hooks.json)
+  const features = (config.features || {}) as Record<string, unknown>;
+  if (!features.codex_hooks) {
+    features.codex_hooks = true;
+    config.features = features;
+    configChanged = true;
+  }
+
+  // Add aide MCP server
+  const mcpServers = (config.mcp_servers || {}) as Record<
+    string,
+    Record<string, unknown>
+  >;
+
+  if (!mcpServers[MCP_SERVER_NAME]) {
+    mcpServers[MCP_SERVER_NAME] = {
+      command: resolved.mcpCommand,
+      args: resolved.mcpArgs,
+      env: {
+        AIDE_CODE_WATCH: "1",
+        AIDE_CODE_WATCH_DELAY: "30s",
+        ...(resolved.wrapperEnv || {}),
+      },
+    };
+    config.mcp_servers = mcpServers;
+    configChanged = true;
+  }
+
+  if (configChanged) {
+    writeCodexToml(configPath, config);
+    configWritten = true;
+  }
+
+  let existingHooks: CodexHooksJson | null = null;
+  if (existsSync(hooksPath)) {
+    try {
+      existingHooks = JSON.parse(
+        readFileSync(hooksPath, "utf-8"),
+      ) as CodexHooksJson;
+    } catch {
+      // Overwrite corrupt file
+    }
+  }
+
+  const hasAideHook = (event: string) =>
+    existingHooks?.hooks?.[event]?.some((m) =>
+      m.hooks?.some((h) => isAideHookCommand(h.command)),
+    ) ?? false;
+  const hasAideHooks = hasAideHook("SessionStart") && hasAideHook("Stop");
+
+  if (!hasAideHooks) {
+    const dir = dirname(hooksPath);
+    mkdirSync(dir, { recursive: true });
+
+    if (existingHooks?.hooks) {
+      // Merge: add aide hooks to existing hooks.json
+      const aideHooks = generateHooksJson(resolved.hookPrefix).hooks;
+      for (const [event, matchers] of Object.entries(aideHooks)) {
+        if (!existingHooks.hooks[event]) {
+          existingHooks.hooks[event] = matchers;
+        } else {
+          // Append aide matchers to existing event
+          existingHooks.hooks[event].push(...matchers);
+        }
+      }
+      writeFileSync(
+        hooksPath,
+        JSON.stringify(existingHooks, null, 2) + "\n",
+      );
+    } else {
+      writeFileSync(
+        hooksPath,
+        JSON.stringify(generateHooksJson(resolved.hookPrefix), null, 2) + "\n",
+      );
+    }
+    hooksWritten = true;
+  }
+
+  return { configWritten, hooksWritten };
+}
+
+export function uninstallCodex(scope: "user" | "project"): {
+  configRemoved: boolean;
+  hooksRemoved: boolean;
+} {
+  const configPath = getCodexConfigTomlPath(scope);
+  const hooksPath = getCodexHooksJsonPath(scope);
+  let configRemoved = false;
+  let hooksRemoved = false;
+
+  // Remove aide MCP server from config.toml
+  if (existsSync(configPath)) {
+    const config = readCodexToml(configPath);
+    const mcpServers = (config.mcp_servers || {}) as Record<
+      string,
+      Record<string, unknown>
+    >;
+
+    if (mcpServers[MCP_SERVER_NAME]) {
+      delete mcpServers[MCP_SERVER_NAME];
+      if (Object.keys(mcpServers).length === 0) {
+        delete config.mcp_servers;
+      } else {
+        config.mcp_servers = mcpServers;
+      }
+      writeCodexToml(configPath, config);
+      configRemoved = true;
+    }
+  }
+
+  // Remove aide hooks from hooks.json
+  if (existsSync(hooksPath)) {
+    try {
+      const hooks = JSON.parse(
+        readFileSync(hooksPath, "utf-8"),
+      ) as CodexHooksJson;
+
+      if (hooks.hooks) {
+        let changed = false;
+        for (const [event, matchers] of Object.entries(hooks.hooks)) {
+          const filtered = matchers.filter(
+            (m) => !m.hooks?.some((h) => isAideHookCommand(h.command)),
+          );
+          if (filtered.length !== matchers.length) {
+            hooks.hooks[event] = filtered;
+            changed = true;
+          }
+          if (hooks.hooks[event].length === 0) {
+            delete hooks.hooks[event];
+          }
+        }
+        if (changed) {
+          writeFileSync(hooksPath, JSON.stringify(hooks, null, 2) + "\n");
+          hooksRemoved = true;
+        }
+      }
+    } catch {
+      // Leave corrupt file alone
+    }
+  }
+
+  return { configRemoved, hooksRemoved };
+}
+
+export function isCodexConfigured(scope: "user" | "project"): {
+  mcp: boolean;
+  hooks: boolean;
+} {
+  const configPath = getCodexConfigTomlPath(scope);
+  const hooksPath = getCodexHooksJsonPath(scope);
+
+  let mcp = false;
+  if (existsSync(configPath)) {
+    const config = readCodexToml(configPath);
+    const mcpServers = (config.mcp_servers || {}) as Record<string, unknown>;
+    mcp = MCP_SERVER_NAME in mcpServers;
+  }
+
+  let hooks = false;
+  if (existsSync(hooksPath)) {
+    try {
+      const hooksJson = JSON.parse(
+        readFileSync(hooksPath, "utf-8"),
+      ) as CodexHooksJson;
+      hooks =
+        hooksJson.hooks?.SessionStart?.some((m) =>
+          m.hooks?.some((h) => isAideHookCommand(h.command)),
+        ) ?? false;
+    } catch {
+      // Corrupt file
+    }
+  }
+
+  return { mcp, hooks };
+}

package/src/cli/hook.ts

@@ -0,0 +1,85 @@
+/**
+ * Hook dispatcher for Codex CLI.
+ *
+ * Codex hooks.json calls `aide-plugin hook <name>` which dispatches to
+ * the appropriate hook script in src/hooks/. Input is normalized from
+ * stdin and passed through to the hook script.
+ *
+ * This avoids duplicating hook scripts — the same scripts work for both
+ * Claude Code (via plugin.json) and Codex CLI (via hooks.json).
+ */
+
+import { execFileSync } from "child_process";
+import { existsSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { readStdin, normalizeHookInput } from "../lib/hook-utils.js";
+
+/** Maps hook CLI names to their script files in src/hooks/. */
+const HOOK_MAP: Record<string, string> = {
+  "session-start": "session-start.ts",
+  "skill-injector": "skill-injector.ts",
+  "tool-tracker": "tool-tracker.ts",
+  "write-guard": "write-guard.ts",
+  "pre-tool-enforcer": "pre-tool-enforcer.ts",
+  "context-guard": "context-guard.ts",
+  "hud-updater": "hud-updater.ts",
+  "comment-checker": "comment-checker.ts",
+  "context-pruning": "context-pruning.ts",
+  "persistence": "persistence.ts",
+  "session-summary": "session-summary.ts",
+  "agent-cleanup": "agent-cleanup.ts",
+  "session-end": "session-end.ts",
+};
+
+export function listHooks(): string[] {
+  return Object.keys(HOOK_MAP);
+}
+
+/**
+ * Dispatch a hook by name.
+ *
+ * Reads stdin, normalizes field names for cross-platform compatibility,
+ * then spawns the hook script with the normalized input.
+ */
+export async function dispatchHook(hookName: string): Promise<void> {
+  const scriptFile = HOOK_MAP[hookName];
+  if (!scriptFile) {
+    console.error(
+      `Unknown hook: ${hookName}\nAvailable hooks: ${Object.keys(HOOK_MAP).join(", ")}`,
+    );
+    process.exit(1);
+  }
+
+  const thisDir = dirname(fileURLToPath(import.meta.url));
+  const pluginRoot = resolve(thisDir, "..", "..");
+  const scriptPath = join(pluginRoot, "src", "hooks", scriptFile);
+
+  if (!existsSync(scriptPath)) {
+    console.error(`Hook script not found: ${scriptPath}`);
+    process.exit(1);
+  }
+
+  const env = {
+    ...process.env,
+    AIDE_PLUGIN_ROOT: pluginRoot,
+    AIDE_PLATFORM: "codex",
+  };
+
+  const rawInput = await readStdin();
+  const normalizedInput = normalizeHookInput(rawInput);
+
+  try {
+    execFileSync(process.execPath, [scriptPath], {
+      input: normalizedInput,
+      stdio: ["pipe", "inherit", "inherit"],
+      env,
+      timeout: 120_000,
+    });
+  } catch (err: unknown) {
+    if (err && typeof err === "object" && "status" in err) {
+      process.exit((err as { status: number }).status ?? 1);
+    }
+    throw err;
+  }
+}

package/src/cli/index.ts

@@ -1,45 +1,71 @@
 #!/usr/bin/env bun
 /**
- * aide CLI — install/uninstall the aide plugin for OpenCode.
+ * aide CLI — install/uninstall the aide plugin for OpenCode and Codex CLI.
  *
  * Usage:
- *   bunx @jmylchreest/aide-plugin install   # Install globally for OpenCode
- *   bunx @jmylchreest/aide-plugin uninstall  # Remove from OpenCode config
- *   bunx @jmylchreest/aide-plugin status     # Show current installation status
- *   bunx @jmylchreest/aide-plugin mcp        # Start MCP server (used by OpenCode)
+ *   aide-plugin install [--platform codex|opencode]   # Install for detected platform
+ *   aide-plugin uninstall [--platform codex|opencode]  # Remove from platform config
+ *   aide-plugin status [--platform codex|opencode]     # Show installation status
+ *   aide-plugin mcp                                    # Start MCP server
+ *   aide-plugin hook <name>                            # Dispatch hook (Codex CLI)
  */
 
 import { install } from "./install.js";
 import { uninstall } from "./uninstall.js";
 import { status } from "./status.js";
 import { mcp } from "./mcp.js";
+import { dispatchHook, listHooks } from "./hook.js";
 
 const args = process.argv.slice(2);
 const command = args[0];
 
+type Platform = "opencode" | "codex";
+
+function detectPlatform(): Platform {
+  const idx = args.indexOf("--platform");
+  if (idx !== -1 && args[idx + 1]) {
+    const val = args[idx + 1] as string;
+    if (val === "codex" || val === "opencode") return val;
+    console.error(`Unknown platform: ${val}. Use "opencode" or "codex".`);
+    process.exit(1);
+  }
+
+  if (process.env.CODEX_HOME || process.env.CODEX_SANDBOX_TYPE) return "codex";
+
+  return "opencode";
+}
+
 function printUsage(): void {
-  console.log(`aide - AI Development Environment plugin for OpenCode
+  console.log(`aide - AI Development Environment plugin for OpenCode and Codex CLI
 
 Usage:
-  aide-plugin install     Install aide plugin globally for OpenCode
-  aide-plugin uninstall   Remove aide plugin from OpenCode config
+  aide-plugin install     Install aide plugin (auto-detects platform)
+  aide-plugin uninstall   Remove aide plugin from platform config
   aide-plugin status      Show current installation status
   aide-plugin mcp         Start MCP server (delegates to aide-wrapper)
+  aide-plugin hook <name> Dispatch a hook by name (used by Codex hooks.json)
   aide-plugin --help      Show this help message
 
 Options:
-  --project    Apply to project-level opencode.json instead of global
-  --no-mcp     Skip MCP server registration (plugin only)
+  --platform codex|opencode   Target platform (auto-detected if omitted)
+  --project                   Apply to project-level config instead of global
+  --no-mcp                    Skip MCP server registration (plugin only)
+
+Available hooks:
+  ${listHooks().join(", ")}
 
 Examples:
   bunx @jmylchreest/aide-plugin install
-  aide-plugin install --project`);
+  aide-plugin install --platform codex
+  aide-plugin install --project
+  aide-plugin hook session-start`);
 }
 
 async function main(): Promise<void> {
   const flags = {
     project: args.includes("--project"),
     noMcp: args.includes("--no-mcp"),
+    platform: detectPlatform(),
   };
 
   switch (command) {
@@ -50,11 +76,22 @@ async function main(): Promise<void> {
       await uninstall(flags);
       break;
     case "status":
-      await status();
+      await status(flags);
       break;
     case "mcp":
       await mcp(args.slice(1));
       break;
+    case "hook": {
+      const hookName = args[1];
+      if (!hookName) {
+        console.error(
+          `Missing hook name.\nAvailable hooks: ${listHooks().join(", ")}`,
+        );
+        process.exit(1);
+      }
+      await dispatchHook(hookName);
+      break;
+    }
     case "--help":
     case "-h":
     case "help":