AxmeAI
diff --git a/‎package-lock.json‎
Lines changed: 1595 additions & 10 deletions b/‎package-lock.json‎
Lines changed: 1595 additions & 10 deletions
diff --git a/‎package.json‎
Lines changed: 3 additions & 0 deletions b/‎package.json‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎src/cli.ts‎
Lines changed: 94 additions & 16 deletions b/‎src/cli.ts‎
Lines changed: 94 additions & 16 deletions
diff --git a/‎src/setup/cursor-writers.ts‎
Lines changed: 160 additions & 0 deletions b/‎src/setup/cursor-writers.ts‎
Lines changed: 160 additions & 0 deletions
diff --git a/‎src/types.ts‎
Lines changed: 22 additions & 1 deletion b/‎src/types.ts‎
Lines changed: 22 additions & 1 deletion
@@ -22,6 +22,9 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "js-yaml": "^4.1.0"
   },
+  "optionalDependencies": {
+    "@cursor/sdk": "1.0.12"
+  },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
 
@@ -197,6 +197,18 @@ async function ensureAuthConfiguredForSetup(): Promise<void> {
     console.log("  Auth selection cancelled. Heuristic fallback will be used.");
     return;
   }
+  if (choice === "cursor_sdk" && !options.cursorSdk?.present) {
+    // User picked Cursor SDK but no key is detected yet — paste flow.
+    const { promptCursorApiKey } = await import("./utils/auth-prompt.js");
+    const { saveCursorApiKey } = await import("./utils/auth-config.js");
+    const key = await promptCursorApiKey();
+    if (!key) {
+      console.log("  Cursor API key paste cancelled. Auth not saved.");
+      return;
+    }
+    saveCursorApiKey(key);
+    console.log(`  Saved Cursor API key: ~/.config/axme-code/cursor.yaml (chmod 600)`);
+  }
   saveAuthConfig(choice);
   console.log(`  Saved auth mode: ${choice} (${authConfigPath()})`);
 }
@@ -320,7 +332,10 @@ function usage(): void {
   console.log(`AXME Code - Persistent memory, decisions, and safety guardrails for Claude Code
 
 Usage:
-  axme-code setup [path] [--force]              Initialize project (LLM scan + .mcp.json + CLAUDE.md)
+  axme-code setup [path] [--force] [--ide=<claude-code|cursor>]
+                                                Initialize project (LLM scan + .mcp.json + CLAUDE.md
+                                                for Claude Code, or .cursor/{mcp,hooks}.json + rules
+                                                /axme-code.mdc for Cursor). Defaults to claude-code.
   axme-code serve                               Start MCP server (stdio transport)
   axme-code status [path]                       Show project status
   axme-code --version | -v                      Print the installed version
@@ -335,9 +350,11 @@ Usage:
   axme-code reindex [path]                      Force a full re-embed of all memories + decisions
                                                 into .axme-code/_index/embeddings.json (search mode only)
 
-  axme-code auth                                Re-detect and choose auth mode (subscription/api_key)
+  axme-code auth                                Re-detect and choose auth mode
+                                                (subscription / api_key / cursor_sdk)
   axme-code auth status                         Show current auth mode + detected options
-  axme-code auth use <subscription|api_key>     Set auth mode non-interactively
+  axme-code auth use <subscription|api_key|cursor_sdk>
+                                                Set auth mode non-interactively
   axme-code cleanup legacy-artifacts [--dry-run]   Remove pre-PR#7 sessions/logs
   axme-code cleanup decisions-normalize [--dry-run]   Add status:active to decisions
   axme-code audit-kb [path] [--all-repos]       KB audit: dedup, conflicts, compaction
@@ -367,7 +384,22 @@ async function main() {
       const setupStartMs = Date.now();
       const forceSetup = args.includes("--force");
       const pluginMode = args.includes("--plugin") || !!process.env.CLAUDE_PLUGIN_ROOT;
-      const setupArgs = args.filter(a => a !== "--force" && a !== "--plugin");
+      const { parseIdeFlag } = await import("./utils/ide-detect.js");
+      const ide = parseIdeFlag(args) ?? "claude-code";
+      if (ide === "cursor" && pluginMode) {
+        console.error("Error: --ide=cursor is not supported with --plugin in this release.");
+        console.error("Run setup without --plugin (Cursor plugin packaging is a Phase 2 follow-up).");
+        process.exit(1);
+      }
+      // Strip --force, --plugin, --ide and its value from positional args.
+      const setupArgs: string[] = [];
+      for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--force" || a === "--plugin") continue;
+        if (a === "--ide") { i++; continue; } // also skip the value
+        if (a.startsWith("--ide=")) continue;
+        setupArgs.push(a);
+      }
       const projectPath = resolve(setupArgs[1] || ".");
       const hasGitDir = existsSync(join(projectPath, ".git"));
       const ws = detectWorkspace(projectPath);
@@ -481,7 +513,10 @@ async function main() {
       const isPlugin = pluginMode;
 
       if (!isPlugin) {
-        // Create or update .mcp.json (workspace root + each child repo)
+        // Create or update .mcp.json (workspace root + each child repo).
+        // Cursor reads BOTH .mcp.json AND .cursor/mcp.json — we always write
+        // the root file regardless of --ide so a repo configured for Cursor
+        // can also be opened in Claude Code without re-running setup.
         const mcpEntry = { command: "axme-code", args: ["serve"] };
         const mcpPaths = [projectPath];
         if (isWorkspace) {
@@ -504,14 +539,30 @@ async function main() {
         console.log(`  .mcp.json: skipped (plugin provides MCP server)`);
       }
 
-      // Generate CLAUDE.md
-      generateClaudeMd(projectPath, isWorkspace);
-
-      if (!isPlugin) {
-        // Configure Claude Code hooks in .claude/settings.json
-        configureHooks(projectPath);
+      if (ide === "cursor") {
+        // Cursor branch: write .cursor/{mcp,hooks}.json + rules/axme-code.mdc.
+        // Skip .claude/CLAUDE.md (D-080: agent must never write to it) and
+        // .claude/settings.json (Cursor doesn't read it).
+        const { writeCursorMcpJson, writeCursorHooksJson, writeCursorRulesMdc } =
+          await import("./setup/cursor-writers.js");
+        const cursorPaths = [projectPath];
+        if (isWorkspace) {
+          for (const p of ws.projects) cursorPaths.push(join(projectPath, p.path));
+        }
+        for (const dir of cursorPaths) writeCursorMcpJson(dir);
+        console.log(`  .cursor/mcp.json: updated (${cursorPaths.length} locations)`);
+        writeCursorHooksJson(projectPath, buildHookCommand);
+        console.log("  .cursor/hooks.json: hooks configured (preToolUse + postToolUse + sessionEnd)");
+        writeCursorRulesMdc(projectPath, isWorkspace);
+        console.log("  .cursor/rules/axme-code.mdc: created");
       } else {
-        console.log(`  Hooks: skipped (plugin provides hooks)`);
+        // Claude Code branch (unchanged): CLAUDE.md + .claude/settings.json
+        generateClaudeMd(projectPath, isWorkspace);
+        if (!isPlugin) {
+          configureHooks(projectPath);
+        } else {
+          console.log(`  Hooks: skipped (plugin provides hooks)`);
+        }
       }
 
       // Add .axme-code/ to .gitignore
@@ -774,10 +825,26 @@ Do NOT skip — without context you will miss critical project rules.
       }
       if (sub === "use" || sub === "set") {
         const mode = args[2];
-        if (mode !== "subscription" && mode !== "api_key") {
-          console.error("Usage: axme-code auth use <subscription|api_key>");
+        if (mode !== "subscription" && mode !== "api_key" && mode !== "cursor_sdk") {
+          console.error("Usage: axme-code auth use <subscription|api_key|cursor_sdk>");
           process.exit(1);
         }
+        if (mode === "cursor_sdk") {
+          // Non-interactive set still requires a key — read from
+          // CURSOR_API_KEY env or refuse politely.
+          const { loadCursorApiKey, saveCursorApiKey } = await import("./utils/auth-config.js");
+          if (!loadCursorApiKey() && !process.env.CURSOR_API_KEY) {
+            console.error(
+              "cursor_sdk mode requires a key. Set CURSOR_API_KEY in env, or run\n" +
+                "  axme-code auth          (interactive — paste key when prompted)",
+            );
+            process.exit(1);
+          }
+          if (process.env.CURSOR_API_KEY && !loadCursorApiKey()) {
+            saveCursorApiKey(process.env.CURSOR_API_KEY);
+            console.log("  Saved Cursor API key from env to ~/.config/axme-code/cursor.yaml (chmod 600)");
+          }
+        }
         saveAuthConfig(mode as AuthMode);
         console.log(`Saved auth mode: ${mode} (${authConfigPath()})`);
         break;
@@ -794,20 +861,31 @@ Do NOT skip — without context you will miss critical project rules.
           process.exit(1);
         }
         if (!process.stdin.isTTY) {
-          console.error("`axme-code auth` requires an interactive terminal. Use `axme-code auth use <subscription|api_key>` non-interactively.");
+          console.error("`axme-code auth` requires an interactive terminal. Use `axme-code auth use <subscription|api_key|cursor_sdk>` non-interactively.");
           process.exit(1);
         }
         const choice = await promptAuthChoice(options);
         if (!choice) {
           console.log("Cancelled. No change.");
           break;
         }
+        if (choice === "cursor_sdk" && !options.cursorSdk?.present) {
+          const { promptCursorApiKey } = await import("./utils/auth-prompt.js");
+          const { saveCursorApiKey } = await import("./utils/auth-config.js");
+          const key = await promptCursorApiKey();
+          if (!key) {
+            console.log("Cursor API key paste cancelled. No change.");
+            break;
+          }
+          saveCursorApiKey(key);
+          console.log("  Saved Cursor API key: ~/.config/axme-code/cursor.yaml (chmod 600)");
+        }
         saveAuthConfig(choice);
         console.log(`Saved auth mode: ${choice} (${authConfigPath()})`);
         break;
       }
       console.error(`Unknown 'auth' subcommand: ${sub}`);
-      console.error("Available: (none)|choose, status|show, use|set <subscription|api_key>");
+      console.error("Available: (none)|choose, status|show, use|set <subscription|api_key|cursor_sdk>");
       process.exit(1);
     }
 
 
@@ -0,0 +1,160 @@
+/**
+ * Idempotent writers for Cursor-specific config files.
+ *
+ * Layout:
+ *   .cursor/mcp.json            — Cursor's MCP server registration (mirrors .mcp.json)
+ *   .cursor/hooks.json          — preToolUse / postToolUse / sessionEnd commands
+ *   .cursor/rules/axme-code.mdc — auto-applied rule (Cursor's CLAUDE.md analogue)
+ *
+ * All three writers preserve user-added entries on re-run: the merge logic
+ * filters out previous axme entries by string match on `axme-code` in the
+ * command field, then re-adds fresh ones — exactly the pattern
+ * configureHooks() uses for `.claude/settings.json`.
+ *
+ * D-080 forbids writing `.claude/CLAUDE.md`. Cursor's analogue is
+ * `.cursor/rules/<rule>.mdc` with YAML frontmatter (`alwaysApply: true`).
+ * The body content mirrors the Claude Code template but is reworded for
+ * Cursor terminology ("Cursor session" not "Claude session").
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const HOOK_TIMEOUT_MS: Record<HookKind, number> = {
+  preToolUse: 5,
+  postToolUse: 10,
+  sessionEnd: 120,
+};
+
+type HookKind = "preToolUse" | "postToolUse" | "sessionEnd";
+
+interface CursorHookEntry {
+  command: string;
+  type?: "command";
+  timeout?: number;
+  matcher?: string;
+  failClosed?: boolean;
+  loop_limit?: number | null;
+  [key: string]: unknown;
+}
+
+interface CursorHooksFile {
+  version?: number;
+  hooks?: Partial<Record<HookKind, CursorHookEntry[]>>;
+  [key: string]: unknown;
+}
+
+interface CursorMcpFile {
+  mcpServers?: Record<string, { command: string; args?: string[] }>;
+  [key: string]: unknown;
+}
+
+function readJsonOr<T extends object>(path: string, fallback: T): T {
+  if (!existsSync(path)) return fallback;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJsonAtomic(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(value, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * Write `.cursor/mcp.json`, merging with any existing servers. Cursor reads
+ * `.cursor/mcp.json` AND root `.mcp.json` — we always write the Cursor
+ * one too, so a repo configured with `--ide=cursor` keeps working even
+ * if the user later removes `.mcp.json`.
+ */
+export function writeCursorMcpJson(projectPath: string): void {
+  const path = join(projectPath, ".cursor", "mcp.json");
+  const cfg = readJsonOr<CursorMcpFile>(path, {});
+  if (!cfg.mcpServers) cfg.mcpServers = {};
+  cfg.mcpServers.axme = { command: "axme-code", args: ["serve"] };
+  writeJsonAtomic(path, cfg);
+}
+
+/**
+ * Write `.cursor/hooks.json` with three event arrays. Each entry uses
+ * `buildHookCommand()` with `--ide cursor` appended so the hook
+ * subprocess can pick the right adapter without re-detecting.
+ *
+ * Idempotency: existing entries whose command contains "axme-code" are
+ * dropped before re-insert; user-added entries are preserved verbatim.
+ */
+export function writeCursorHooksJson(
+  projectPath: string,
+  buildHookCommand: (hookName: string, projectPath: string) => string,
+): void {
+  const path = join(projectPath, ".cursor", "hooks.json");
+  const cfg = readJsonOr<CursorHooksFile>(path, { version: 1 });
+  if (!cfg.version) cfg.version = 1;
+  if (!cfg.hooks) cfg.hooks = {};
+
+  const hookKinds: HookKind[] = ["preToolUse", "postToolUse", "sessionEnd"];
+  const cliHookNames: Record<HookKind, string> = {
+    preToolUse: "pre-tool-use",
+    postToolUse: "post-tool-use",
+    sessionEnd: "session-end",
+  };
+
+  for (const kind of hookKinds) {
+    const existing = cfg.hooks[kind] ?? [];
+    const preserved = existing.filter((e) => !String(e.command ?? "").includes("axme-code"));
+    const fresh: CursorHookEntry = {
+      command: `${buildHookCommand(cliHookNames[kind], projectPath)} --ide cursor`,
+      type: "command",
+      timeout: HOOK_TIMEOUT_MS[kind],
+    };
+    cfg.hooks[kind] = [...preserved, fresh];
+  }
+
+  writeJsonAtomic(path, cfg);
+}
+
+const RULE_FRONTMATTER = `---
+name: axme-code
+description: AXME Code session start ritual + safety reminders for Cursor
+alwaysApply: true
+---
+`;
+
+const RULE_BODY = `## AXME Code
+
+### Session Start (MANDATORY)
+Call \`axme_context\` tool with this project's path at the start of every Cursor session.
+This loads: oracle, decisions, safety rules, memories, test plan, active plans.
+Do NOT skip — without context you will miss critical project rules.
+
+### During Work
+- Error pattern or successful approach discovered → call \`axme_save_memory\` immediately.
+- Architectural decision made or discovered → call \`axme_save_decision\` immediately.
+- New safety constraint found → call \`axme_update_safety\` immediately.
+
+### Git commit/push gate
+Every \`git commit\` and \`git push\` command MUST end with the marker:
+\`\`\`
+#!axme pr=<NUMBER|none> repo=<OWNER/REPO>
+\`\`\`
+Without this suffix the pre-tool-use hook blocks the command.
+
+### Available AXME tools
+\`axme_context\`, \`axme_save_memory\`, \`axme_save_decision\`, \`axme_update_safety\`,
+\`axme_safety\`, \`axme_status\`, \`axme_worklog\`, \`axme_workspace\`,
+\`axme_oracle\`, \`axme_decisions\`, \`axme_memories\`.
+`;
+
+/**
+ * Write `.cursor/rules/axme-code.mdc` (Cursor's auto-applied rule format).
+ * Always overwrites — the rule body is canonical and small. Frontmatter
+ * `alwaysApply: true` makes Cursor inject this content into every chat
+ * session's system context.
+ */
+export function writeCursorRulesMdc(projectPath: string, _isWorkspace: boolean): void {
+  const path = join(projectPath, ".cursor", "rules", "axme-code.mdc");
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, RULE_FRONTMATTER + "\n" + RULE_BODY, "utf-8");
+}
@@ -398,9 +398,30 @@ export type E2EMode = "after-task" | "after-stage" | "manual";
 
 // --- Auth ---
 
-export type AuthMode = "subscription" | "api_key";
+/**
+ * Authentication mode for LLM agent invocations.
+ *
+ * - `subscription`: Claude Code OAuth subscription. The factory deletes
+ *   ANTHROPIC_API_KEY from the subprocess env so Claude Code doesn't pick
+ *   an empty-balance key over OAuth.
+ * - `api_key`: Direct ANTHROPIC_API_KEY in env, passed through unchanged.
+ * - `cursor_sdk`: Cursor SDK API key issued at cursor.com (Integrations).
+ *   The actual key is stored at ~/.config/axme-code/cursor.yaml (chmod 600);
+ *   `auth.yaml` only carries the mode flag.
+ */
+export type AuthMode = "subscription" | "api_key" | "cursor_sdk";
 
 export interface AuthConfig {
   mode: AuthMode;
   chosenAt: string;
 }
+
+/**
+ * Cursor SDK API key payload, stored separately at
+ * ~/.config/axme-code/cursor.yaml so the secret is not co-mingled with
+ * the auth-mode flag and can be permission-locked (chmod 600) on its own.
+ */
+export interface CursorApiKeyConfig {
+  apiKey: string;
+  chosenAt: string;
+}