context-mode 0.9.21 → 1.0.0

package/build/adapters/codex/index.js

@@ -0,0 +1,223 @@
+/**
+ * adapters/codex — Codex CLI platform adapter.
+ *
+ * Implements HookAdapter for Codex CLI's MCP-only paradigm.
+ *
+ * Codex CLI hook specifics:
+ *   - NO hook support (PRs #2904, #9796 were closed without merge)
+ *   - Only "hook": notify config for agent-turn-complete (very limited)
+ *   - Config: ~/.codex/config.toml (TOML format, not JSON)
+ *   - MCP: full support via [mcp_servers] in config.toml
+ *   - All capabilities are false — MCP is the only integration path
+ *   - Session dir: ~/.codex/context-mode/sessions/
+ */
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, accessSync, constants, } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+// ─────────────────────────────────────────────────────────
+// Adapter implementation
+// ─────────────────────────────────────────────────────────
+export class CodexAdapter {
+    name = "Codex CLI";
+    paradigm = "mcp-only";
+    capabilities = {
+        preToolUse: false,
+        postToolUse: false,
+        preCompact: false,
+        sessionStart: false,
+        canModifyArgs: false,
+        canModifyOutput: false,
+        canInjectSessionContext: false,
+    };
+    // ── Input parsing ──────────────────────────────────────
+    // Codex CLI does not support hooks. These methods exist to satisfy the
+    // interface contract but will throw if called.
+    parsePreToolUseInput(_raw) {
+        throw new Error("Codex CLI does not support hooks");
+    }
+    parsePostToolUseInput(_raw) {
+        throw new Error("Codex CLI does not support hooks");
+    }
+    parsePreCompactInput(_raw) {
+        throw new Error("Codex CLI does not support hooks");
+    }
+    parseSessionStartInput(_raw) {
+        throw new Error("Codex CLI does not support hooks");
+    }
+    // ── Response formatting ────────────────────────────────
+    // Codex CLI does not support hooks. Return undefined for all responses.
+    formatPreToolUseResponse(_response) {
+        return undefined;
+    }
+    formatPostToolUseResponse(_response) {
+        return undefined;
+    }
+    formatPreCompactResponse(_response) {
+        return undefined;
+    }
+    formatSessionStartResponse(_response) {
+        return undefined;
+    }
+    // ── Configuration ──────────────────────────────────────
+    getSettingsPath() {
+        return resolve(homedir(), ".codex", "config.toml");
+    }
+    getSessionDir() {
+        const dir = join(homedir(), ".codex", "context-mode", "sessions");
+        mkdirSync(dir, { recursive: true });
+        return dir;
+    }
+    getSessionDBPath(projectDir) {
+        const hash = createHash("sha256")
+            .update(projectDir)
+            .digest("hex")
+            .slice(0, 16);
+        return join(this.getSessionDir(), `${hash}.db`);
+    }
+    getSessionEventsPath(projectDir) {
+        const hash = createHash("sha256")
+            .update(projectDir)
+            .digest("hex")
+            .slice(0, 16);
+        return join(this.getSessionDir(), `${hash}-events.md`);
+    }
+    generateHookConfig(_pluginRoot) {
+        // Codex CLI does not support hooks — return empty registration
+        return {};
+    }
+    readSettings() {
+        // Codex CLI uses TOML format. Full TOML parsing is complex;
+        // return null for now. MCP configuration should be done manually
+        // or via a dedicated TOML library in the upgrade flow.
+        try {
+            const raw = readFileSync(this.getSettingsPath(), "utf-8");
+            // Return raw TOML as a single-key object for inspection
+            return { _raw_toml: raw };
+        }
+        catch {
+            return null;
+        }
+    }
+    writeSettings(_settings) {
+        // Codex CLI uses TOML format. Writing TOML requires a dedicated
+        // serializer. This is a no-op; TOML config should be edited
+        // manually or via the `codex` CLI tool.
+    }
+    // ── Diagnostics (doctor) ─────────────────────────────────
+    validateHooks(_pluginRoot) {
+        return [
+            {
+                check: "Hook support",
+                status: "warn",
+                message: "Codex CLI does not support hooks (PRs #2904, #9796 closed without merge). " +
+                    "Only MCP integration is available.",
+            },
+        ];
+    }
+    checkPluginRegistration() {
+        // Check for context-mode in [mcp_servers] section of config.toml
+        try {
+            const raw = readFileSync(this.getSettingsPath(), "utf-8");
+            const hasContextMode = raw.includes("context-mode");
+            const hasMcpSection = raw.includes("[mcp_servers]") || raw.includes("[mcp_servers.");
+            if (hasContextMode && hasMcpSection) {
+                return {
+                    check: "MCP registration",
+                    status: "pass",
+                    message: "context-mode found in [mcp_servers] config",
+                };
+            }
+            if (hasMcpSection) {
+                return {
+                    check: "MCP registration",
+                    status: "fail",
+                    message: "[mcp_servers] section exists but context-mode not found",
+                    fix: 'Add context-mode to [mcp_servers] in ~/.codex/config.toml',
+                };
+            }
+            return {
+                check: "MCP registration",
+                status: "fail",
+                message: "No [mcp_servers] section in config.toml",
+                fix: 'Add [mcp_servers.context-mode] to ~/.codex/config.toml',
+            };
+        }
+        catch {
+            return {
+                check: "MCP registration",
+                status: "warn",
+                message: "Could not read ~/.codex/config.toml",
+            };
+        }
+    }
+    getInstalledVersion() {
+        // Codex CLI has no marketplace or plugin system
+        return "not installed";
+    }
+    // ── Upgrade ────────────────────────────────────────────
+    configureAllHooks(_pluginRoot) {
+        // Codex CLI does not support hooks — nothing to configure
+        return [];
+    }
+    backupSettings() {
+        const settingsPath = this.getSettingsPath();
+        try {
+            accessSync(settingsPath, constants.R_OK);
+            const backupPath = settingsPath + ".bak";
+            copyFileSync(settingsPath, backupPath);
+            return backupPath;
+        }
+        catch {
+            return null;
+        }
+    }
+    setHookPermissions(_pluginRoot) {
+        // No hook scripts for Codex CLI
+        return [];
+    }
+    updatePluginRegistry(_pluginRoot, _version) {
+        // Codex CLI has no plugin registry
+    }
+    // ── Routing Instructions (soft enforcement) ────────────
+    getRoutingInstructionsConfig() {
+        return {
+            fileName: "AGENTS.md",
+            globalPath: resolve(homedir(), ".codex", "AGENTS.md"),
+            projectRelativePath: "AGENTS.md",
+        };
+    }
+    writeRoutingInstructions(projectDir, pluginRoot) {
+        const config = this.getRoutingInstructionsConfig();
+        const targetPath = resolve(projectDir, config.projectRelativePath);
+        const sourcePath = resolve(pluginRoot, "configs", "codex", config.fileName);
+        try {
+            const content = readFileSync(sourcePath, "utf-8");
+            try {
+                const existing = readFileSync(targetPath, "utf-8");
+                if (existing.includes("context-mode"))
+                    return null;
+                writeFileSync(targetPath, existing.trimEnd() + "\n\n" + content, "utf-8");
+                return targetPath;
+            }
+            catch {
+                writeFileSync(targetPath, content, "utf-8");
+                return targetPath;
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    getRoutingInstructions() {
+        const instructionsPath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "configs", "codex", "AGENTS.md");
+        try {
+            return readFileSync(instructionsPath, "utf-8");
+        }
+        catch {
+            // Fallback inline instructions
+            return "# context-mode\n\nUse context-mode MCP tools (execute, execute_file, batch_execute, fetch_and_index, search) instead of bash/cat/curl for data-heavy operations.";
+        }
+    }
+}

package/build/adapters/detect.d.ts

@@ -0,0 +1,26 @@
+/**
+ * adapters/detect — Auto-detect which platform is running.
+ *
+ * Detection priority:
+ *   1. Environment variables (high confidence)
+ *   2. Config directory existence (medium confidence)
+ *   3. Fallback to Claude Code (low confidence — most common)
+ *
+ * Each platform sets identifiable env vars or creates config dirs:
+ *   - Claude Code:  CLAUDE_PROJECT_DIR, ~/.claude/
+ *   - Gemini CLI:   GEMINI_PROJECT_DIR, ~/.gemini/
+ *   - OpenCode:     OPENCODE_PROJECT_DIR, .opencode/
+ *   - Copilot CLI:  GITHUB_COPILOT_*, ~/.config/github-copilot/
+ *   - VS Code:      VSCODE_*, ~/.vscode/
+ *   - Cursor:       CURSOR_*, ~/.cursor/
+ */
+import type { PlatformId, DetectionSignal, HookAdapter } from "./types.js";
+/**
+ * Detect the current platform by checking env vars and config dirs.
+ */
+export declare function detectPlatform(): DetectionSignal;
+/**
+ * Get the adapter instance for a given platform.
+ * Lazily imports platform-specific adapter modules.
+ */
+export declare function getAdapter(platform?: PlatformId): Promise<HookAdapter>;

package/build/adapters/detect.js

@@ -0,0 +1,131 @@
+/**
+ * adapters/detect — Auto-detect which platform is running.
+ *
+ * Detection priority:
+ *   1. Environment variables (high confidence)
+ *   2. Config directory existence (medium confidence)
+ *   3. Fallback to Claude Code (low confidence — most common)
+ *
+ * Each platform sets identifiable env vars or creates config dirs:
+ *   - Claude Code:  CLAUDE_PROJECT_DIR, ~/.claude/
+ *   - Gemini CLI:   GEMINI_PROJECT_DIR, ~/.gemini/
+ *   - OpenCode:     OPENCODE_PROJECT_DIR, .opencode/
+ *   - Copilot CLI:  GITHUB_COPILOT_*, ~/.config/github-copilot/
+ *   - VS Code:      VSCODE_*, ~/.vscode/
+ *   - Cursor:       CURSOR_*, ~/.cursor/
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+/**
+ * Detect the current platform by checking env vars and config dirs.
+ */
+export function detectPlatform() {
+    // ── High confidence: environment variables ─────────────
+    if (process.env.CLAUDE_PROJECT_DIR || process.env.CLAUDE_SESSION_ID) {
+        return {
+            platform: "claude-code",
+            confidence: "high",
+            reason: "CLAUDE_PROJECT_DIR or CLAUDE_SESSION_ID env var set",
+        };
+    }
+    if (process.env.GEMINI_PROJECT_DIR || process.env.GEMINI_SESSION_ID) {
+        return {
+            platform: "gemini-cli",
+            confidence: "high",
+            reason: "GEMINI_PROJECT_DIR or GEMINI_SESSION_ID env var set",
+        };
+    }
+    if (process.env.OPENCODE_PROJECT_DIR || process.env.OPENCODE_SESSION_ID) {
+        return {
+            platform: "opencode",
+            confidence: "high",
+            reason: "OPENCODE_PROJECT_DIR or OPENCODE_SESSION_ID env var set",
+        };
+    }
+    if (process.env.GITHUB_COPILOT_AGENT || process.env.COPILOT_SESSION_ID) {
+        return {
+            platform: "copilot-cli",
+            confidence: "high",
+            reason: "GITHUB_COPILOT_AGENT or COPILOT_SESSION_ID env var set",
+        };
+    }
+    if (process.env.VSCODE_PID || process.env.VSCODE_CWD) {
+        return {
+            platform: "vscode-copilot",
+            confidence: "high",
+            reason: "VSCODE_PID or VSCODE_CWD env var set",
+        };
+    }
+    if (process.env.CURSOR_SESSION_ID || process.env.CURSOR_TRACE_ID) {
+        return {
+            platform: "cursor",
+            confidence: "high",
+            reason: "CURSOR_SESSION_ID or CURSOR_TRACE_ID env var set",
+        };
+    }
+    // ── Medium confidence: config directory existence ──────
+    const home = homedir();
+    if (existsSync(resolve(home, ".claude"))) {
+        return {
+            platform: "claude-code",
+            confidence: "medium",
+            reason: "~/.claude/ directory exists",
+        };
+    }
+    if (existsSync(resolve(home, ".gemini"))) {
+        return {
+            platform: "gemini-cli",
+            confidence: "medium",
+            reason: "~/.gemini/ directory exists",
+        };
+    }
+    if (existsSync(resolve(home, ".cursor"))) {
+        return {
+            platform: "cursor",
+            confidence: "medium",
+            reason: "~/.cursor/ directory exists",
+        };
+    }
+    // ── Low confidence: fallback ───────────────────────────
+    return {
+        platform: "claude-code",
+        confidence: "low",
+        reason: "No platform detected, defaulting to Claude Code",
+    };
+}
+/**
+ * Get the adapter instance for a given platform.
+ * Lazily imports platform-specific adapter modules.
+ */
+export async function getAdapter(platform) {
+    const target = platform ?? detectPlatform().platform;
+    switch (target) {
+        case "claude-code": {
+            const { ClaudeCodeAdapter } = await import("./claude-code/index.js");
+            return new ClaudeCodeAdapter();
+        }
+        case "gemini-cli": {
+            const { GeminiCLIAdapter } = await import("./gemini-cli/index.js");
+            return new GeminiCLIAdapter();
+        }
+        case "opencode": {
+            const { OpenCodeAdapter } = await import("./opencode/index.js");
+            return new OpenCodeAdapter();
+        }
+        case "codex": {
+            const { CodexAdapter } = await import("./codex/index.js");
+            return new CodexAdapter();
+        }
+        case "vscode-copilot": {
+            const { VSCodeCopilotAdapter } = await import("./vscode-copilot/index.js");
+            return new VSCodeCopilotAdapter();
+        }
+        default: {
+            // Unsupported platform — fall back to Claude Code adapter
+            // (MCP server works everywhere, hooks may not)
+            const { ClaudeCodeAdapter } = await import("./claude-code/index.js");
+            return new ClaudeCodeAdapter();
+        }
+    }
+}

package/build/adapters/gemini-cli/config.d.ts

@@ -0,0 +1,8 @@
+/**
+ * adapters/gemini-cli/config — Thin re-exports from GeminiCLIAdapter.
+ *
+ * This module exists for backward compatibility. All logic lives in the
+ * adapter class (index.ts). New code should use getAdapter() from detect.ts.
+ */
+export { GeminiCLIAdapter } from "./index.js";
+export { HOOK_TYPES, HOOK_SCRIPTS, REQUIRED_HOOKS, OPTIONAL_HOOKS } from "./hooks.js";

package/build/adapters/gemini-cli/config.js

@@ -0,0 +1,8 @@
+/**
+ * adapters/gemini-cli/config — Thin re-exports from GeminiCLIAdapter.
+ *
+ * This module exists for backward compatibility. All logic lives in the
+ * adapter class (index.ts). New code should use getAdapter() from detect.ts.
+ */
+export { GeminiCLIAdapter } from "./index.js";
+export { HOOK_TYPES, HOOK_SCRIPTS, REQUIRED_HOOKS, OPTIONAL_HOOKS } from "./hooks.js";

package/build/adapters/gemini-cli/hooks.d.ts

@@ -0,0 +1,44 @@
+/**
+ * adapters/gemini-cli/hooks — Gemini CLI hook definitions and matchers.
+ *
+ * Defines the hook types, matchers, and registration format specific to
+ * Gemini CLI's hook system. This module is used by:
+ *   - CLI setup/upgrade commands (to configure hooks in settings.json)
+ *   - Doctor command (to validate hook configuration)
+ *   - Hook config generation
+ *
+ * Gemini CLI hook system reference:
+ *   - Hooks are registered in ~/.gemini/settings.json under "hooks" key
+ *   - Each hook type maps to an array of { matcher, hooks } entries
+ *   - Hook names: BeforeTool, AfterTool, PreCompress, SessionStart
+ *   - Input: JSON on stdin
+ *   - Output: JSON on stdout (or empty for passthrough)
+ */
+/** Gemini CLI hook types. */
+export declare const HOOK_TYPES: {
+    readonly BEFORE_TOOL: "BeforeTool";
+    readonly AFTER_TOOL: "AfterTool";
+    readonly PRE_COMPRESS: "PreCompress";
+    readonly SESSION_START: "SessionStart";
+};
+export type HookType = (typeof HOOK_TYPES)[keyof typeof HOOK_TYPES];
+/** Map of hook types to their script file names. */
+export declare const HOOK_SCRIPTS: Record<HookType, string>;
+/** Required hooks that must be configured for context-mode to function. */
+export declare const REQUIRED_HOOKS: HookType[];
+/** Optional hooks that enhance functionality but aren't critical. */
+export declare const OPTIONAL_HOOKS: HookType[];
+/**
+ * Check if a hook entry points to a context-mode hook script.
+ */
+export declare function isContextModeHook(entry: {
+    hooks?: Array<{
+        command?: string;
+    }>;
+}, hookType: HookType): boolean;
+/**
+ * Build the hook command string for a given hook type.
+ * Uses the CLI dispatcher: `context-mode hook gemini-cli <event>`
+ * Requires global install: `npm install -g context-mode`
+ */
+export declare function buildHookCommand(hookType: HookType): string;

package/build/adapters/gemini-cli/hooks.js

@@ -0,0 +1,64 @@
+/**
+ * adapters/gemini-cli/hooks — Gemini CLI hook definitions and matchers.
+ *
+ * Defines the hook types, matchers, and registration format specific to
+ * Gemini CLI's hook system. This module is used by:
+ *   - CLI setup/upgrade commands (to configure hooks in settings.json)
+ *   - Doctor command (to validate hook configuration)
+ *   - Hook config generation
+ *
+ * Gemini CLI hook system reference:
+ *   - Hooks are registered in ~/.gemini/settings.json under "hooks" key
+ *   - Each hook type maps to an array of { matcher, hooks } entries
+ *   - Hook names: BeforeTool, AfterTool, PreCompress, SessionStart
+ *   - Input: JSON on stdin
+ *   - Output: JSON on stdout (or empty for passthrough)
+ */
+// ─────────────────────────────────────────────────────────
+// Hook type constants
+// ─────────────────────────────────────────────────────────
+/** Gemini CLI hook types. */
+export const HOOK_TYPES = {
+    BEFORE_TOOL: "BeforeTool",
+    AFTER_TOOL: "AfterTool",
+    PRE_COMPRESS: "PreCompress",
+    SESSION_START: "SessionStart",
+};
+// ─────────────────────────────────────────────────────────
+// Hook script file names
+// ─────────────────────────────────────────────────────────
+/** Map of hook types to their script file names. */
+export const HOOK_SCRIPTS = {
+    [HOOK_TYPES.BEFORE_TOOL]: "beforetool.mjs",
+    [HOOK_TYPES.AFTER_TOOL]: "aftertool.mjs",
+    [HOOK_TYPES.PRE_COMPRESS]: "precompress.mjs",
+    [HOOK_TYPES.SESSION_START]: "sessionstart.mjs",
+};
+// ─────────────────────────────────────────────────────────
+// Hook validation
+// ─────────────────────────────────────────────────────────
+/** Required hooks that must be configured for context-mode to function. */
+export const REQUIRED_HOOKS = [
+    HOOK_TYPES.BEFORE_TOOL,
+    HOOK_TYPES.SESSION_START,
+];
+/** Optional hooks that enhance functionality but aren't critical. */
+export const OPTIONAL_HOOKS = [
+    HOOK_TYPES.AFTER_TOOL,
+    HOOK_TYPES.PRE_COMPRESS,
+];
+/**
+ * Check if a hook entry points to a context-mode hook script.
+ */
+export function isContextModeHook(entry, hookType) {
+    const scriptName = HOOK_SCRIPTS[hookType];
+    return (entry.hooks?.some((h) => h.command?.includes(scriptName)) ?? false);
+}
+/**
+ * Build the hook command string for a given hook type.
+ * Uses the CLI dispatcher: `context-mode hook gemini-cli <event>`
+ * Requires global install: `npm install -g context-mode`
+ */
+export function buildHookCommand(hookType) {
+    return `context-mode hook gemini-cli ${hookType.toLowerCase()}`;
+}

package/build/adapters/gemini-cli/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * adapters/gemini-cli — Gemini CLI platform adapter.
+ *
+ * Implements HookAdapter for Gemini CLI's JSON stdin/stdout hook paradigm.
+ *
+ * Gemini CLI hook specifics:
+ *   - I/O: JSON on stdin, JSON on stdout (same paradigm as Claude Code)
+ *   - Hook names: BeforeTool, AfterTool, PreCompress, SessionStart
+ *   - Arg modification: `hookSpecificOutput.tool_input` (merged with original)
+ *   - Blocking: `decision: "deny"` in response (NOT permissionDecision)
+ *   - Output modification: `decision: "deny"` + reason replaces output,
+ *     `hookSpecificOutput.additionalContext` appends
+ *   - PreCompress: advisory only (async, cannot block)
+ *   - No `decision: "ask"` support
+ *   - Hooks don't fire for subagents yet
+ *   - Config: ~/.gemini/settings.json (user), .gemini/settings.json (project)
+ *   - Session ID: session_id field
+ *   - Project dir env: GEMINI_PROJECT_DIR (also CLAUDE_PROJECT_DIR alias)
+ *   - Session dir: ~/.gemini/context-mode/sessions/
+ */
+import type { HookAdapter, HookParadigm, PlatformCapabilities, DiagnosticResult, PreToolUseEvent, PostToolUseEvent, PreCompactEvent, SessionStartEvent, PreToolUseResponse, PostToolUseResponse, PreCompactResponse, SessionStartResponse, HookRegistration, RoutingInstructionsConfig } from "../types.js";
+export declare class GeminiCLIAdapter implements HookAdapter {
+    readonly name = "Gemini CLI";
+    readonly paradigm: HookParadigm;
+    readonly capabilities: PlatformCapabilities;
+    parsePreToolUseInput(raw: unknown): PreToolUseEvent;
+    parsePostToolUseInput(raw: unknown): PostToolUseEvent;
+    parsePreCompactInput(raw: unknown): PreCompactEvent;
+    parseSessionStartInput(raw: unknown): SessionStartEvent;
+    formatPreToolUseResponse(response: PreToolUseResponse): unknown;
+    formatPostToolUseResponse(response: PostToolUseResponse): unknown;
+    formatPreCompactResponse(response: PreCompactResponse): unknown;
+    formatSessionStartResponse(response: SessionStartResponse): unknown;
+    getSettingsPath(): string;
+    getSessionDir(): string;
+    getSessionDBPath(projectDir: string): string;
+    getSessionEventsPath(projectDir: string): string;
+    generateHookConfig(_pluginRoot: string): HookRegistration;
+    readSettings(): Record<string, unknown> | null;
+    writeSettings(settings: Record<string, unknown>): void;
+    validateHooks(pluginRoot: string): DiagnosticResult[];
+    checkPluginRegistration(): DiagnosticResult;
+    getInstalledVersion(): string;
+    configureAllHooks(_pluginRoot: string): string[];
+    backupSettings(): string | null;
+    setHookPermissions(pluginRoot: string): string[];
+    updatePluginRegistry(pluginRoot: string, version: string): void;
+    getRoutingInstructionsConfig(): RoutingInstructionsConfig;
+    writeRoutingInstructions(projectDir: string, pluginRoot: string): string | null;
+    /** Get the project directory from environment variables. */
+    private getProjectDir;
+    /**
+     * Extract session ID from Gemini CLI hook input.
+     * Priority: session_id field > env fallback > ppid fallback.
+     */
+    private extractSessionId;
+}