@nick848/fet 1.0.4 → 1.0.5

package/dist/cli/index.js

@@ -2,15 +2,15 @@
 import {
   FetError,
   toFetError
-} from "../chunk-FZOVNHE7.js";
+} from "../chunk-V4ZRBF5L.js";
 
 // src/cli/index.ts
 import { createInterface } from "readline/promises";
 import { Command } from "commander";
 
 // src/commands/init.ts
-import { readFile as readFile6, stat as stat2 } from "fs/promises";
-import { join as join7 } from "path";
+import { readFile as readFile6, stat as stat3 } from "fs/promises";
+import { join as join8 } from "path";
 
 // src/fs/atomic-write.ts
 import { dirname } from "path";
@@ -118,23 +118,26 @@ async function writeInitJournal(projectRoot, journal) {
 
 // src/gitnexus.ts
 import { execFile } from "child_process";
+import { stat as stat2 } from "fs/promises";
+import { join as join4 } from "path";
 import { promisify } from "util";
 var execFileAsync = promisify(execFile);
+var DEFAULT_GRAPH_PATH = ".gitnexus";
 async function detectGitNexus(env = process.env) {
   const checkedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const executable = env.FET_GITNEXUS_EXECUTABLE?.trim() || "gitnexus";
+  const command = resolveGitNexusCommand(env);
   try {
-    const { stdout, stderr } = await execFileAsync(executable, ["--version"], { shell: process.platform === "win32" });
+    const { stdout, stderr } = await execFileAsync(command.file, [...command.args, "--version"], { shell: process.platform === "win32" });
     return {
       installed: true,
-      executablePath: executable,
+      executablePath: command.label,
       version: (stdout.trim() || stderr.trim() || "unknown").split(/\r?\n/)[0] ?? "unknown",
       checkedAt
     };
   } catch (error) {
     return {
       installed: false,
-      executablePath: executable,
+      executablePath: command.label,
       version: null,
       checkedAt,
       error: error instanceof Error ? error.message : String(error)
@@ -148,7 +151,66 @@ function toGitNexusState(detection, previous) {
     executablePath: detection.installed ? detection.executablePath : null,
     version: detection.version,
     checkedAt: detection.checkedAt,
-    recommendationShownAt: previous?.recommendationShownAt ?? null
+    recommendationShownAt: previous?.recommendationShownAt ?? null,
+    graphPath: previous?.graphPath ?? null,
+    graphExists: previous?.graphExists ?? false,
+    lastIndexedAt: previous?.lastIndexedAt ?? null,
+    lastRefreshAt: previous?.lastRefreshAt ?? null,
+    lastStatus: previous?.lastStatus ?? null,
+    setupHandoffPath: previous?.setupHandoffPath ?? null,
+    setupHandoffUpdatedAt: previous?.setupHandoffUpdatedAt ?? null,
+    handoffPath: previous?.handoffPath ?? null,
+    handoffUpdatedAt: previous?.handoffUpdatedAt ?? null
+  };
+}
+async function inspectGitNexusGraph(projectRoot, env = process.env) {
+  const relative2 = env.FET_GITNEXUS_GRAPH_PATH?.trim() || DEFAULT_GRAPH_PATH;
+  const graphPath = join4(projectRoot, relative2);
+  try {
+    const info = await stat2(graphPath);
+    return {
+      graphPath: relative2,
+      graphExists: true,
+      lastIndexedAt: info.mtime.toISOString()
+    };
+  } catch {
+    return {
+      graphPath: relative2,
+      graphExists: false,
+      lastIndexedAt: null
+    };
+  }
+}
+async function runGitNexus(args, options) {
+  const command = resolveGitNexusCommand(options.env ?? process.env);
+  const fullCommand = [command.file, ...command.args, ...args];
+  try {
+    const { stdout, stderr } = await execFileAsync(command.file, [...command.args, ...args], {
+      cwd: options.cwd,
+      shell: process.platform === "win32"
+    });
+    return {
+      exitCode: 0,
+      stdout,
+      stderr,
+      command: fullCommand
+    };
+  } catch (error) {
+    const maybe = error;
+    return {
+      exitCode: typeof maybe.code === "number" ? maybe.code : 1,
+      stdout: maybe.stdout ?? "",
+      stderr: maybe.stderr ?? (error instanceof Error ? error.message : String(error)),
+      command: fullCommand
+    };
+  }
+}
+function mergeGitNexusGraphInfo(state, graph2) {
+  return {
+    ...state,
+    graphPath: graph2.graphPath,
+    graphExists: graph2.graphExists,
+    lastIndexedAt: graph2.lastIndexedAt
   };
 }
 function renderGitNexusRecommendation(state) {
@@ -157,17 +219,27 @@ function renderGitNexusRecommendation(state) {
   }
   return "Optional GitNexus code graph support is not installed. Consider installing GitNexus later to speed up OpenSpec artifact generation and improve code insertion context.";
 }
+function resolveGitNexusCommand(env) {
+  const raw = env.FET_GITNEXUS_COMMAND?.trim() || env.FET_GITNEXUS_EXECUTABLE?.trim() || "gitnexus";
+  const parts = splitCommand(raw);
+  const [file = "gitnexus", ...args] = parts;
+  return { file, args, label: raw };
+}
+function splitCommand(value) {
+  const matches = value.match(/"[^"]+"|'[^']+'|\S+/g);
+  return (matches?.length ? matches : [value]).map((part) => part.replace(/^["']|["']$/g, ""));
+}
 
 // src/version.ts
 import { existsSync, readFileSync } from "fs";
-import { dirname as dirname4, join as join4, parse } from "path";
+import { dirname as dirname4, join as join5, parse } from "path";
 import { fileURLToPath } from "url";
 var FET_VERSION = readPackageVersion();
 function readPackageVersion() {
   let currentDir = dirname4(fileURLToPath(import.meta.url));
   const root = parse(currentDir).root;
   while (true) {
-    const packageJsonPath = join4(currentDir, "package.json");
+    const packageJsonPath = join5(currentDir, "package.json");
     if (existsSync(packageJsonPath)) {
       const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
       if (typeof packageJson.version === "string" && packageJson.version.length > 0) {
@@ -377,7 +449,8 @@ var RULES = [
   "openspec/.fet.lock",
   "openspec/.fet-init-journal.json",
   "openspec/changes/*/fet-state.json",
-  "openspec/changes/*/.fet/"
+  "openspec/changes/*/.fet/",
+  ".gitnexus/"
 ];
 function mergeGitignore(existing) {
   const block = `${BEGIN}
@@ -400,7 +473,7 @@ ${block}
 
 // src/commands/update-context.ts
 import { readFile as readFile5 } from "fs/promises";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 
 // src/config/yaml.ts
 import { readFile as readFile3 } from "fs/promises";
@@ -421,11 +494,11 @@ async function mergeFetConfig(configPath, renderedFetYaml) {
 
 // src/context-placeholders.ts
 import { readFile as readFile4 } from "fs/promises";
-import { join as join5 } from "path";
+import { join as join6 } from "path";
 var AGENTS_LLM_PLACEHOLDER_PATTERN = /\[NEEDS? LLM INPUT\]/g;
 async function countAgentsLlmPlaceholders(projectRoot) {
   try {
-    const content = await readFile4(join5(projectRoot, "AGENTS.md"), "utf8");
+    const content = await readFile4(join6(projectRoot, "AGENTS.md"), "utf8");
     return [...content.matchAll(AGENTS_LLM_PLACEHOLDER_PATTERN)].length;
   } catch {
     return 0;
@@ -454,8 +527,8 @@ async function updateContextCommand(ctx) {
 }
 async function updateContextFiles(ctx) {
   const scan = await ctx.scanner.scan(ctx.projectRoot, {});
-  const agentsPath = join6(ctx.projectRoot, "AGENTS.md");
-  const configPath = join6(ctx.projectRoot, "openspec", "config.yaml");
+  const agentsPath = join7(ctx.projectRoot, "AGENTS.md");
+  const configPath = join7(ctx.projectRoot, "openspec", "config.yaml");
   const existingAgents = await readOptional(agentsPath);
   const warnings = [...scan.warnings];
   if (existingAgents && hasInvalidManagedAutoRegion(existingAgents)) {
@@ -505,7 +578,7 @@ async function readOptional(path) {
 
 // src/commands/init.ts
 async function initCommand(ctx) {
-  const alreadyInitialized = await exists(join7(ctx.projectRoot, "openspec", "config.yaml"));
+  const alreadyInitialized = await exists(join8(ctx.projectRoot, "openspec", "config.yaml"));
   let warnings = [];
   await withProjectLock(
     ctx.projectRoot,
@@ -527,7 +600,10 @@ async function initCommand(ctx) {
       const state = await ctx.stateStore.getOrCreateGlobal();
       state.openspec = identity;
       state.graph ??= {};
-      const gitnexus = toGitNexusState(await detectGitNexus(), state.graph.gitnexus);
+      const gitnexus = mergeGitNexusGraphInfo(
+        toGitNexusState(await detectGitNexus(), state.graph.gitnexus),
+        await inspectGitNexusGraph(ctx.projectRoot)
+      );
       if (!gitnexus.installed && !gitnexus.recommendationShownAt) {
         warnings.push(renderGitNexusRecommendation(gitnexus));
         gitnexus.recommendationShownAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -557,7 +633,7 @@ async function initCommand(ctx) {
   });
 }
 async function ensureGitignore(ctx) {
-  const gitignorePath = join7(ctx.projectRoot, ".gitignore");
+  const gitignorePath = join8(ctx.projectRoot, ".gitignore");
   const existing = await readOptional2(gitignorePath);
   await atomicWrite(gitignorePath, mergeGitignore(existing));
 }
@@ -570,7 +646,7 @@ async function readOptional2(path) {
 }
 async function exists(path) {
   try {
-    await stat2(path);
+    await stat3(path);
     return true;
   } catch {
     return false;
@@ -578,20 +654,20 @@ async function exists(path) {
 }
 
 // src/commands/doctor.ts
-import { readFile as readFile7, stat as stat3 } from "fs/promises";
-import { join as join8 } from "path";
+import { readFile as readFile7, stat as stat4 } from "fs/promises";
+import { join as join9 } from "path";
 async function doctorCommand(ctx, options = {}) {
   const checks = [];
   checks.push(await checkOpenSpec(ctx));
   checks.push(await checkState(ctx));
-  checks.push(await checkFile("agents", join8(ctx.projectRoot, "AGENTS.md"), "AGENTS.md \u7F3A\u5931", "fet update-context"));
-  checks.push(await checkFile("config", join8(ctx.projectRoot, "openspec", "config.yaml"), "openspec/config.yaml \u7F3A\u5931", "fet init"));
+  checks.push(await checkFile("agents", join9(ctx.projectRoot, "AGENTS.md"), "AGENTS.md \u7F3A\u5931", "fet update-context"));
+  checks.push(await checkFile("config", join9(ctx.projectRoot, "openspec", "config.yaml"), "openspec/config.yaml \u7F3A\u5931", "fet init"));
   checks.push(await checkPlaceholders(ctx.projectRoot));
   checks.push(await checkGitNexus(ctx));
   for (const adapter of ctx.toolAdapters) {
     checks.push(...await adapter.doctor(ctx.projectRoot));
   }
-  const lockPath = join8(ctx.projectRoot, "openspec", ".fet.lock");
+  const lockPath = join9(ctx.projectRoot, "openspec", ".fet.lock");
   if (await exists2(lockPath)) {
     if (options.fixLock) {
       await clearLock(ctx.projectRoot);
@@ -611,7 +687,10 @@ async function doctorCommand(ctx, options = {}) {
 }
 async function checkGitNexus(ctx) {
   const global = await ctx.stateStore.readGlobal();
-  const state = toGitNexusState(await detectGitNexus(), global?.graph?.gitnexus);
+  const state = mergeGitNexusGraphInfo(
+    toGitNexusState(await detectGitNexus(), global?.graph?.gitnexus),
+    await inspectGitNexusGraph(ctx.projectRoot)
+  );
   if (global) {
     global.graph ??= {};
     global.graph.gitnexus = state;
@@ -620,7 +699,7 @@ async function checkGitNexus(ctx) {
   return state.installed ? {
     id: "gitnexus",
     status: "pass",
-    message: `GitNexus detected: ${state.executablePath ?? "gitnexus"} (${state.version ?? "unknown"})`
+    message: `GitNexus detected: ${state.executablePath ?? "gitnexus"} (${state.version ?? "unknown"}), graph ${state.graphExists ? "found" : "not found"}`
   } : {
     id: "gitnexus",
     status: "warn",
@@ -649,7 +728,7 @@ async function checkFile(id, path, missing, suggestedCommand) {
 }
 async function checkPlaceholders(projectRoot) {
   try {
-    await readFile7(join8(projectRoot, "AGENTS.md"), "utf8");
+    await readFile7(join9(projectRoot, "AGENTS.md"), "utf8");
     const count2 = await countAgentsLlmPlaceholders(projectRoot);
     return count2 ? {
       id: "context-placeholders",
@@ -663,7 +742,7 @@ async function checkPlaceholders(projectRoot) {
 }
 async function exists2(path) {
   try {
-    await stat3(path);
+    await stat4(path);
     return true;
   } catch {
     return false;
@@ -672,13 +751,13 @@ async function exists2(path) {
 
 // src/commands/fill-context.ts
 import { mkdir as mkdir3 } from "fs/promises";
-import { dirname as dirname5, join as join9 } from "path";
+import { dirname as dirname5, join as join10 } from "path";
 async function fillContextCommand(ctx) {
   await withProjectLock(
     ctx.projectRoot,
     { command: "fill-context", cwd: ctx.cwd, fetVersion: ctx.fetVersion },
     async () => {
-      const handoffPath = join9(ctx.projectRoot, ".fet", "fill-context.md");
+      const handoffPath = join10(ctx.projectRoot, ".fet", "fill-context.md");
       await mkdir3(dirname5(handoffPath), { recursive: true });
       await atomicWrite(handoffPath, renderGenericHandoff());
       for (const adapter of ctx.toolAdapters) {
@@ -733,9 +812,259 @@ Use the IDE AI to complete FET-generated placeholders.
 `;
 }
 
+// src/commands/graph.ts
+import { mkdir as mkdir4 } from "fs/promises";
+import { dirname as dirname6, join as join11 } from "path";
+async function graphCommand(ctx, action, args = []) {
+  switch (action) {
+    case "status":
+      await graphStatusCommand(ctx);
+      return;
+    case "doctor":
+      await graphDoctorCommand(ctx);
+      return;
+    case "setup":
+      await graphSetupCommand(ctx);
+      return;
+    case "handoff":
+      await graphHandoffCommand(ctx);
+      return;
+    case "init":
+      await graphAnalyzeCommand(ctx, "init", args);
+      return;
+    case "refresh":
+      await graphAnalyzeCommand(ctx, "refresh", args);
+      return;
+  }
+}
+async function graphStatusCommand(ctx) {
+  const result = await refreshGraphState(ctx, { runStatus: true });
+  const warnings = result.state.installed ? [] : ["GitNexus is not installed. Run fet graph setup for installation handoff instructions."];
+  ctx.output.result({
+    ok: true,
+    command: "graph status",
+    summary: result.state.installed ? `GitNexus graph status checked. Graph ${result.state.graphExists ? "exists" : "does not exist"} at ${result.state.graphPath ?? ".gitnexus"}.` : "GitNexus is not installed. Graph support remains optional.",
+    warnings,
+    nextSteps: result.state.installed && !result.state.graphExists ? ["Run fet graph init to build the first GitNexus graph"] : void 0,
+    data: result
+  });
+}
+async function graphDoctorCommand(ctx) {
+  const result = await refreshGraphState(ctx, { runStatus: true });
+  const warnings = [
+    ...!result.state.installed ? ["GitNexus is not installed."] : [],
+    ...result.state.installed && !result.state.graphExists ? ["GitNexus is installed but no graph directory was found."] : [],
+    ...!result.state.handoffPath ? ["Graph handoff instructions have not been generated."] : []
+  ];
+  ctx.output.result({
+    ok: true,
+    command: "graph doctor",
+    summary: warnings.length ? `Graph doctor completed with ${warnings.length} warning(s).` : "Graph doctor completed without warnings.",
+    warnings,
+    nextSteps: warnings.length ? ["Run fet graph setup", "Run fet graph handoff", "Run fet graph init when GitNexus is installed"] : void 0,
+    data: result
+  });
+}
+async function graphSetupCommand(ctx) {
+  let result;
+  const handoffPath = join11(ctx.projectRoot, ".fet", "graph-setup.md");
+  await withProjectLock(ctx.projectRoot, { command: "graph setup", cwd: ctx.cwd, fetVersion: ctx.fetVersion }, async () => {
+    result = await refreshGraphState(ctx, { write: false });
+    await writeHandoffFile(handoffPath, renderGraphSetupHandoff(result.state));
+    const global = await ctx.stateStore.getOrCreateGlobal();
+    global.graph ??= {};
+    global.graph.gitnexus = {
+      ...result.state,
+      setupHandoffPath: ".fet/graph-setup.md",
+      setupHandoffUpdatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await ctx.stateStore.writeGlobal(global);
+  });
+  ctx.output.result({
+    ok: true,
+    command: "graph setup",
+    summary: "GitNexus setup handoff generated.",
+    warnings: result.state.installed ? [] : ["GitNexus is not installed. The handoff explains installation and IDE-assisted setup options."],
+    nextSteps: result.state.installed ? ["Run gitnexus setup if you want to configure IDE/MCP integrations", "Run fet graph init"] : ["Open .fet/graph-setup.md in your IDE AI"],
+    data: {
+      path: ".fet/graph-setup.md",
+      gitnexus: result.state
+    }
+  });
+}
+async function graphHandoffCommand(ctx) {
+  let result;
+  const handoffPath = join11(ctx.projectRoot, ".fet", "graph-handoff.md");
+  await withProjectLock(ctx.projectRoot, { command: "graph handoff", cwd: ctx.cwd, fetVersion: ctx.fetVersion }, async () => {
+    result = await refreshGraphState(ctx, { runStatus: true, write: false });
+    await writeHandoffFile(handoffPath, renderGraphUsageHandoff(result.state));
+    const global = await ctx.stateStore.getOrCreateGlobal();
+    global.graph ??= {};
+    global.graph.gitnexus = {
+      ...result.state,
+      handoffPath: ".fet/graph-handoff.md",
+      handoffUpdatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await ctx.stateStore.writeGlobal(global);
+  });
+  ctx.output.result({
+    ok: true,
+    command: "graph handoff",
+    summary: "GitNexus graph usage handoff generated.",
+    warnings: result.state.installed ? [] : ["GitNexus is not installed. The handoff still documents the fallback behavior."],
+    nextSteps: ["Cursor/Codex/OpenCode: read .fet/graph-handoff.md before broad repository scans"],
+    data: {
+      path: ".fet/graph-handoff.md",
+      gitnexus: result.state
+    }
+  });
+}
+async function graphAnalyzeCommand(ctx, mode, args) {
+  const detection = await detectGitNexus();
+  if (!detection.installed) {
+    throw new FetError({
+      code: "GRAPH_PROVIDER_NOT_FOUND" /* GraphProviderNotFound */,
+      message: "GitNexus is not installed or is not available on PATH.",
+      details: { executable: detection.executablePath, error: detection.error },
+      suggestedCommand: "fet graph setup"
+    });
+  }
+  const run = await runGitNexus(["analyze", ...args], { cwd: ctx.projectRoot });
+  if (run.exitCode !== 0) {
+    throw new FetError({
+      code: "GRAPH_COMMAND_FAILED" /* GraphCommandFailed */,
+      message: "GitNexus analyze failed.",
+      details: { command: run.command.join(" "), exitCode: run.exitCode, stdout: run.stdout, stderr: run.stderr },
+      suggestedCommand: "fet graph doctor"
+    });
+  }
+  const result = await refreshGraphState(ctx, { write: false });
+  const global = await ctx.stateStore.getOrCreateGlobal();
+  global.graph ??= {};
+  global.graph.gitnexus = {
+    ...result.state,
+    lastRefreshAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await ctx.stateStore.writeGlobal(global);
+  ctx.output.result({
+    ok: true,
+    command: `graph ${mode}`,
+    summary: mode === "init" ? "GitNexus graph initialized." : "GitNexus graph refreshed.",
+    warnings: result.state.graphExists ? [] : ["GitNexus analyze completed, but the configured graph directory was not found."],
+    nextSteps: ["Run fet graph status", "Use .fet/graph-handoff.md or generated IDE prompts to prefer graph context"],
+    data: {
+      gitnexus: global.graph.gitnexus,
+      run: {
+        command: run.command,
+        stdout: run.stdout.trim(),
+        stderr: run.stderr.trim()
+      }
+    }
+  });
+}
+async function refreshGraphState(ctx, options = {}) {
+  const global = await ctx.stateStore.getOrCreateGlobal();
+  global.graph ??= {};
+  const detection = await detectGitNexus();
+  const graph2 = await inspectGitNexusGraph(ctx.projectRoot);
+  let state = mergeGitNexusGraphInfo(toGitNexusState(detection, global.graph.gitnexus), graph2);
+  let gitnexusStatus = null;
+  if (options.runStatus && detection.installed) {
+    gitnexusStatus = await runGitNexus(["status"], { cwd: ctx.projectRoot });
+    state = {
+      ...state,
+      lastStatus: firstLine(gitnexusStatus.stdout) || firstLine(gitnexusStatus.stderr) || `exit ${gitnexusStatus.exitCode}`
+    };
+  }
+  if (options.write ?? true) {
+    global.graph.gitnexus = state;
+    await ctx.stateStore.writeGlobal(global);
+  }
+  return {
+    state,
+    gitnexusStatus: gitnexusStatus ? {
+      exitCode: gitnexusStatus.exitCode,
+      command: gitnexusStatus.command,
+      stdout: gitnexusStatus.stdout.trim(),
+      stderr: gitnexusStatus.stderr.trim()
+    } : null
+  };
+}
+async function writeHandoffFile(path, content) {
+  await mkdir4(dirname6(path), { recursive: true });
+  await atomicWrite(path, content);
+}
+function renderGraphSetupHandoff(state) {
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+generator: graph-setup
+FET:END -->
+
+# FET Graph Setup
+
+GitNexus graph support is optional. FET does not install GitNexus automatically and does not require graph support for OpenSpec workflows.
+
+Current status:
+
+- Installed: ${state.installed ? "yes" : "no"}
+- Executable: ${state.executablePath ?? "gitnexus"}
+- Version: ${state.version ?? "unknown"}
+- Graph path: ${state.graphPath ?? ".gitnexus"}
+- Graph exists: ${state.graphExists ? "yes" : "no"}
+
+Suggested setup flow:
+
+1. If GitNexus is not installed, install it using the method recommended by the GitNexus project.
+2. If you want GitNexus MCP or IDE integration, run \`gitnexus setup\` yourself after reviewing what it changes.
+3. Return to this project and run \`fet graph init\` to build the first graph.
+4. Run \`fet graph handoff\` so IDE AI can prefer graph context before broad repository scans.
+
+Guardrails:
+
+- Do not block FET/OpenSpec commands when GitNexus is unavailable.
+- Do not generate or modify application code during setup.
+- Do not run global IDE configuration commands unless the user explicitly approves them.
+`;
+}
+function renderGraphUsageHandoff(state) {
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+generator: graph-handoff
+FET:END -->
+
+# FET Graph Handoff
+
+Use GitNexus graph context as an optional first pass before broad repository scans.
+
+Current status:
+
+- Installed: ${state.installed ? "yes" : "no"}
+- Graph path: ${state.graphPath ?? ".gitnexus"}
+- Graph exists: ${state.graphExists ? "yes" : "no"}
+- Last indexed at: ${state.lastIndexedAt ?? "unknown"}
+- Last status: ${state.lastStatus ?? "unknown"}
+
+When graph context is available:
+
+1. Use the graph to identify likely modules, dependencies, and insertion points.
+2. Read only the concrete source files needed to confirm behavior.
+3. Prefer OpenSpec artifacts and AGENTS.md over graph guesses when they conflict.
+4. Fall back to normal repository inspection if the graph is missing, stale, or incomplete.
+
+When producing OpenSpec artifacts:
+
+- Use graph context to make proposal, design, specs, and tasks more precise.
+- Avoid large repository scans when the graph already narrows the relevant area.
+- Keep all generated artifacts in the normal OpenSpec change directory.
+`;
+}
+function firstLine(value) {
+  return value.trim().split(/\r?\n/)[0]?.trim() || null;
+}
+
 // src/commands/proxy.ts
 import { readFile as readFile10 } from "fs/promises";
-import { join as join11 } from "path";
+import { join as join13 } from "path";
 
 // src/state/project.ts
 import { execFile as execFile2 } from "child_process";
@@ -764,8 +1093,8 @@ async function git(cwd, args) {
 }
 
 // src/state/store.ts
-import { mkdir as mkdir4, readFile as readFile8 } from "fs/promises";
-import { join as join10 } from "path";
+import { mkdir as mkdir5, readFile as readFile8 } from "fs/promises";
+import { join as join12 } from "path";
 
 // src/state/schema.ts
 var phases = ["explore", "propose", "implement", "verify", "sync", "archive"];
@@ -874,7 +1203,7 @@ var StateStore = class {
   }
   async writeGlobal(state) {
     state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    await mkdir4(join10(this.projectRoot, "openspec"), { recursive: true });
+    await mkdir5(join12(this.projectRoot, "openspec"), { recursive: true });
     await atomicWrite(this.globalPath(), `${JSON.stringify(state, null, 2)}
 `);
   }
@@ -895,15 +1224,15 @@ var StateStore = class {
   }
   async writeChange(state) {
     state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    await mkdir4(join10(this.projectRoot, "openspec", "changes", state.changeId), { recursive: true });
+    await mkdir5(join12(this.projectRoot, "openspec", "changes", state.changeId), { recursive: true });
     await atomicWrite(this.changePath(state.changeId), `${JSON.stringify(state, null, 2)}
 `);
   }
   globalPath() {
-    return join10(this.projectRoot, "openspec", "fet-state.json");
+    return join12(this.projectRoot, "openspec", "fet-state.json");
   }
   changePath(changeId) {
-    return join10(this.projectRoot, "openspec", "changes", changeId, "fet-state.json");
+    return join12(this.projectRoot, "openspec", "changes", changeId, "fet-state.json");
   }
 };
 function isNotFound(error) {
@@ -1020,7 +1349,7 @@ async function createChangelogEntry(projectRoot, changeId) {
   };
 }
 async function appendChangelog(projectRoot, entry) {
-  const changelogPath = join11(projectRoot, "CHANGELOG.md");
+  const changelogPath = join13(projectRoot, "CHANGELOG.md");
   const existing = await readOptional3(changelogPath);
   const block = `updateTime: ${entry.updateTime}
 \u66F4\u65B0\u5185\u5BB9:${entry.content}
@@ -1031,12 +1360,12 @@ ${block}` : block;
   await atomicWrite(changelogPath, next);
 }
 async function readChangeRequirement(projectRoot, changeId) {
-  const changeRoot = join11(projectRoot, "openspec", "changes", changeId);
-  const proposal = await readOptional3(join11(changeRoot, "proposal.md"));
+  const changeRoot = join13(projectRoot, "openspec", "changes", changeId);
+  const proposal = await readOptional3(join13(changeRoot, "proposal.md"));
   if (proposal) {
     return summarizeMarkdown(proposal);
   }
-  const readme = await readOptional3(join11(changeRoot, "README.md"));
+  const readme = await readOptional3(join13(changeRoot, "README.md"));
   if (readme) {
     return summarizeMarkdown(readme);
   }
@@ -1180,8 +1509,8 @@ async function assertVerified(ctx) {
 
 // src/commands/verify.ts
 import { createHash } from "crypto";
-import { mkdir as mkdir5, readFile as readFile11, stat as stat4 } from "fs/promises";
-import { join as join12 } from "path";
+import { mkdir as mkdir6, readFile as readFile11, stat as stat5 } from "fs/promises";
+import { join as join14 } from "path";
 async function verifyCommand(ctx, options) {
   if (options.auto) {
     const scan = await ctx.scanner.scan(ctx.projectRoot, {});
@@ -1248,9 +1577,9 @@ async function verifyCommand(ctx, options) {
 async function writeInstructions(ctx, changeId) {
   await assertChangeExists(ctx, changeId);
   const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const dir = join12(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
-  const instructionsPath = join12(dir, "verify-instructions.md");
-  await mkdir5(dir, { recursive: true });
+  const dir = join14(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
+  const instructionsPath = join14(dir, "verify-instructions.md");
+  await mkdir6(dir, { recursive: true });
   await atomicWrite(instructionsPath, renderVerifyInstructions(changeId, generatedAt));
   const state = await ctx.stateStore.getOrCreateChange(changeId, "verify");
   state.currentPhase = "verify";
@@ -1266,7 +1595,7 @@ async function writeInstructions(ctx, changeId) {
 async function markDone(ctx, changeId) {
   await assertChangeExists(ctx, changeId);
   const declaredAt = (/* @__PURE__ */ new Date()).toISOString();
-  const instructionsPath = join12(ctx.projectRoot, "openspec", "changes", changeId, ".fet", "verify-instructions.md");
+  const instructionsPath = join14(ctx.projectRoot, "openspec", "changes", changeId, ".fet", "verify-instructions.md");
   const instructions = await readInstructions(instructionsPath, changeId);
   const instructionsGeneratedAt = readFrontMatterValue(instructions, "generatedAt") ?? declaredAt;
   const state = await ctx.stateStore.getOrCreateChange(changeId, "verify");
@@ -1301,7 +1630,7 @@ async function assertChangeExists(ctx, changeId) {
 }
 async function readInstructions(path, changeId) {
   try {
-    await stat4(path);
+    await stat5(path);
     const content = await readFile11(path, "utf8");
     const fileChangeId = readFrontMatterValue(content, "changeId");
     if (fileChangeId !== changeId) {
@@ -1419,9 +1748,9 @@ function renderIdeModelPolicy(command) {
 import { resolve } from "path";
 
 // src/adapters/codex/index.ts
-import { mkdir as mkdir6, readFile as readFile12, stat as stat5 } from "fs/promises";
+import { mkdir as mkdir7, readFile as readFile12, stat as stat6 } from "fs/promises";
 import { homedir } from "os";
-import { dirname as dirname6, join as join13 } from "path";
+import { dirname as dirname7, join as join15 } from "path";
 
 // src/adapters/commands.ts
 var FET_WORKFLOW_COMMANDS = [
@@ -1437,7 +1766,18 @@ var FET_WORKFLOW_COMMANDS = [
   "bulk-archive",
   "onboard"
 ];
-var FET_ADAPTER_COMMANDS = [...FET_WORKFLOW_COMMANDS, "fill-context", "passthrough"];
+var FET_GRAPH_COMMANDS = ["graph-status", "graph-setup", "graph-init", "graph-refresh", "graph-doctor", "graph-handoff"];
+var FET_ADAPTER_COMMANDS = [...FET_WORKFLOW_COMMANDS, "fill-context", "passthrough", ...FET_GRAPH_COMMANDS];
+function renderFetAdapterUsage(command, args = "[...args]") {
+  if (command.startsWith("graph-")) {
+    const subcommand = command.slice("graph-".length);
+    return `fet graph ${subcommand}${args ? ` ${args}` : ""}`;
+  }
+  if (command === "passthrough") {
+    return `fet passthrough <openspec-command>${args ? ` ${args}` : ""}`;
+  }
+  return `fet ${command}${args ? ` ${args}` : ""}`;
+}
 
 // src/adapters/codex/templates.ts
 function codexGuideFile() {
@@ -1485,15 +1825,19 @@ function renderCommand(command) {
   if (command === "passthrough") {
     return renderPassthroughCommand();
   }
+  if (command.startsWith("graph-")) {
+    return renderGraphCommand(command);
+  }
+  const usage = renderFetAdapterUsage(command, "");
   return `<!-- FET:MANAGED
 schemaVersion: 1
 fetVersion: ${FET_VERSION}
 generator: codex-adapter
 adapterVersion: 1
-command: fet ${command}
+command: ${usage}
 FET:END -->
 
-# fet ${command}
+# ${usage}
 
 ${renderIdeModelPolicy(command)}
 
@@ -1504,7 +1848,7 @@ If GitNexus graph context is available, consult it before broad source scans and
 Then run:
 
 \`\`\`sh
-fet ${command}
+${usage}
 \`\`\`
 
 If the command needs a change id, pass it with \`--change <change-id>\` or use the active OpenSpec change from the user's request.
@@ -1538,6 +1882,36 @@ fet passthrough <openspec-command> [...args]
 This preserves the FET entry point while allowing access to unmanaged or newly added OpenSpec commands. Passthrough does not update FET lifecycle state.
 `;
 }
+function renderGraphCommand(command) {
+  const usage = renderFetAdapterUsage(command, "");
+  const subcommand = command.slice("graph-".length);
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+generator: codex-adapter
+adapterVersion: 1
+command: ${usage}
+FET:END -->
+
+# ${usage}
+
+${renderIdeModelPolicy(command)}
+
+When the user asks Codex to work with optional GitNexus graph support, use FET as the entry point.
+
+If GitNexus graph context is available, consult it before broad source scans and use it to narrow the files you read. If it is unavailable, continue normally.
+
+Run:
+
+\`\`\`sh
+${usage}
+\`\`\`
+
+For graph init or refresh, pass extra GitNexus analyze arguments only when the user provides them.
+
+After the command completes, report the GitNexus state, generated handoff files, and next steps.
+`;
+}
 function renderSlashPrompt(command) {
   if (command === "continue") {
     return renderContinueSlashPrompt();
@@ -1575,9 +1949,10 @@ function renderSlashPrompt(command) {
   if (command === "passthrough") {
     return renderPassthroughSlashPrompt();
   }
-  const usage = command === "passthrough" ? "fet passthrough <openspec-command> [...args]" : `fet ${command} [...args]`;
-  const shellCommand = command === "passthrough" ? "fet passthrough $ARGUMENTS" : `fet ${command} $ARGUMENTS`;
-  const description = command === "passthrough" ? "Run an unmanaged OpenSpec command through FET passthrough" : `Run the FET-managed OpenSpec ${command} workflow`;
+  const usage = renderFetAdapterUsage(command);
+  const isGraph = command.startsWith("graph-");
+  const shellCommand = isGraph ? `${renderFetAdapterUsage(command, "")} $ARGUMENTS` : `fet ${command} $ARGUMENTS`;
+  const description = isGraph ? `Run optional GitNexus graph ${command.slice("graph-".length)} through FET` : `Run the FET-managed OpenSpec ${command} workflow`;
   return `<!-- FET:MANAGED
 schemaVersion: 1
 fetVersion: ${FET_VERSION}
@@ -2033,7 +2408,7 @@ var CodexAdapter = class {
   adapterVersion = 1;
   async detect(projectRoot) {
     return {
-      detected: await exists3(join13(projectRoot, ".codex")) || await exists3(join13(projectRoot, "AGENTS.md")),
+      detected: await exists3(join15(projectRoot, ".codex")) || await exists3(join15(projectRoot, "AGENTS.md")),
       reason: "Codex adapter is available for projects that use AGENTS.md"
     };
   }
@@ -2072,7 +2447,7 @@ var CodexAdapter = class {
       if (existing && !existing.includes("FET:MANAGED") && force) {
         await createBackup(target);
       }
-      await mkdir6(dirname6(target), { recursive: true });
+      await mkdir7(dirname7(target), { recursive: true });
       await atomicWrite(target, file.content);
       written.push(displayPath);
     }
@@ -2099,9 +2474,9 @@ var CodexAdapter = class {
 };
 function resolveTarget(projectRoot, file) {
   if (file.root === "codex-home") {
-    return join13(resolveCodexHome(), file.path);
+    return join15(resolveCodexHome(), file.path);
   }
-  return join13(projectRoot, file.path);
+  return join15(projectRoot, file.path);
 }
 function displayPathFor(file) {
   if (file.root === "codex-home") {
@@ -2110,7 +2485,7 @@ function displayPathFor(file) {
   return file.path;
 }
 function resolveCodexHome() {
-  return process.env.FET_CODEX_HOME ?? process.env.CODEX_HOME ?? join13(homedir(), ".codex");
+  return process.env.FET_CODEX_HOME ?? process.env.CODEX_HOME ?? join15(homedir(), ".codex");
 }
 async function readExisting(path) {
   try {
@@ -2121,7 +2496,7 @@ async function readExisting(path) {
 }
 async function exists3(path) {
   try {
-    await stat5(path);
+    await stat6(path);
     return true;
   } catch {
     return false;
@@ -2129,8 +2504,8 @@ async function exists3(path) {
 }
 
 // src/adapters/cursor/index.ts
-import { mkdir as mkdir7, readFile as readFile13, stat as stat6 } from "fs/promises";
-import { dirname as dirname7, join as join14 } from "path";
+import { mkdir as mkdir8, readFile as readFile13, stat as stat7 } from "fs/promises";
+import { dirname as dirname8, join as join16 } from "path";
 
 // src/adapters/cursor/templates.ts
 function cursorSkillFiles() {
@@ -2166,7 +2541,7 @@ alwaysApply: false
   };
 }
 function renderSkill(command) {
-  const usage = command === "passthrough" ? "fet passthrough <openspec-command> [...args]" : `fet ${command}`;
+  const usage = renderFetAdapterUsage(command, command === "passthrough" ? "[...args]" : "");
   if (command === "fill-context") {
     return `<!-- FET:MANAGED
 schemaVersion: 1
@@ -2232,7 +2607,7 @@ var CursorAdapter = class {
   adapterVersion = 1;
   async detect(projectRoot) {
     return {
-      detected: await exists4(join14(projectRoot, ".cursor")),
+      detected: await exists4(join16(projectRoot, ".cursor")),
       reason: "Cursor adapter is available for any project"
     };
   }
@@ -2249,7 +2624,7 @@ var CursorAdapter = class {
     const written = [];
     const skipped = [];
     for (const file of plan.files) {
-      const target = join14(projectRoot, file.path);
+      const target = join16(projectRoot, file.path);
       const existing = await readExisting2(target);
       if (existing && !existing.includes("FET:MANAGED") && !force) {
         throw new FetError({
@@ -2262,7 +2637,7 @@ var CursorAdapter = class {
       if (existing && !existing.includes("FET:MANAGED") && force) {
         await createBackup(target);
       }
-      await mkdir7(dirname7(target), { recursive: true });
+      await mkdir8(dirname8(target), { recursive: true });
       await atomicWrite(target, file.content);
       written.push(file.path);
     }
@@ -2272,7 +2647,7 @@ var CursorAdapter = class {
     const plan = await this.planInstall(projectRoot);
     const checks = [];
     for (const file of plan.files) {
-      const target = join14(projectRoot, file.path);
+      const target = join16(projectRoot, file.path);
       const content = await readExisting2(target);
       const managed = Boolean(content?.includes("FET:MANAGED"));
       const versionMatches = Boolean(content?.includes(`adapterVersion: ${this.adapterVersion}`));
@@ -2295,7 +2670,7 @@ async function readExisting2(path) {
 }
 async function exists4(path) {
   try {
-    await stat6(path);
+    await stat7(path);
     return true;
   } catch {
     return false;
@@ -2307,13 +2682,13 @@ import { execFile as execFile4 } from "child_process";
 import { promisify as promisify4 } from "util";
 
 // src/openspec/inspector.ts
-import { readdir, stat as stat7 } from "fs/promises";
-import { join as join15 } from "path";
+import { readdir, stat as stat8 } from "fs/promises";
+import { join as join17 } from "path";
 async function inspectOpenSpecProject(projectRoot) {
-  const openspecPath = join15(projectRoot, "openspec");
-  const changesPath = join15(openspecPath, "changes");
-  const legacyArchivePath = join15(openspecPath, "archive");
-  const changesArchivePath = join15(changesPath, "archive");
+  const openspecPath = join17(projectRoot, "openspec");
+  const changesPath = join17(openspecPath, "changes");
+  const legacyArchivePath = join17(openspecPath, "archive");
+  const changesArchivePath = join17(changesPath, "archive");
   return {
     exists: await exists5(openspecPath),
     changes: await listDirectories(changesPath, { exclude: ["archive"] }),
@@ -2321,13 +2696,13 @@ async function inspectOpenSpecProject(projectRoot) {
   };
 }
 async function inspectOpenSpecChange(projectRoot, changeId) {
-  const changePath = join15(projectRoot, "openspec", "changes", changeId);
-  const tasksPath = join15(changePath, "tasks.md");
-  const specsPath = join15(changePath, "specs");
+  const changePath = join17(projectRoot, "openspec", "changes", changeId);
+  const tasksPath = join17(changePath, "tasks.md");
+  const specsPath = join17(changePath, "specs");
   return {
     changeId,
     exists: await exists5(changePath),
-    hasProposal: await exists5(join15(changePath, "proposal.md")),
+    hasProposal: await exists5(join17(changePath, "proposal.md")),
     hasTasks: await exists5(tasksPath),
     hasSpecs: await exists5(specsPath),
     tasksPath,
@@ -2345,7 +2720,7 @@ async function listDirectories(path, options = {}) {
 }
 async function exists5(path) {
   try {
-    await stat7(path);
+    await stat8(path);
     return true;
   } catch {
     return false;
@@ -2504,12 +2879,12 @@ function parseCommands(help) {
 }
 
 // src/scanner/package.ts
-import { readFile as readFile14, stat as stat8 } from "fs/promises";
-import { join as join16 } from "path";
+import { readFile as readFile14, stat as stat9 } from "fs/promises";
+import { join as join18 } from "path";
 import { parse as parse2 } from "yaml";
 async function readPackageJson(projectRoot) {
   try {
-    return JSON.parse(await readFile14(join16(projectRoot, "package.json"), "utf8"));
+    return JSON.parse(await readFile14(join18(projectRoot, "package.json"), "utf8"));
   } catch {
     return null;
   }
@@ -2575,7 +2950,7 @@ function detectFramework(pkg) {
 }
 async function detectLanguage(projectRoot, pkg) {
   const deps = { ...pkg?.dependencies ?? {}, ...pkg?.devDependencies ?? {} };
-  if (deps.typescript || await exists6(join16(projectRoot, "tsconfig.json"))) {
+  if (deps.typescript || await exists6(join18(projectRoot, "tsconfig.json"))) {
     return "typescript";
   }
   return "javascript";
@@ -2590,7 +2965,7 @@ async function detectWorkspaces(projectRoot, pkg) {
     return packageWorkspaces;
   }
   try {
-    const workspace = parse2(await readFile14(join16(projectRoot, "pnpm-workspace.yaml"), "utf8"));
+    const workspace = parse2(await readFile14(join18(projectRoot, "pnpm-workspace.yaml"), "utf8"));
     return (workspace?.packages ?? []).map((path) => ({
       name: path,
       path,
@@ -2610,7 +2985,7 @@ async function detectLockManagers(projectRoot) {
   ];
   const found = [];
   for (const [file, manager] of lockFiles) {
-    if (await exists6(join16(projectRoot, file))) {
+    if (await exists6(join18(projectRoot, file))) {
       found.push(manager);
     }
   }
@@ -2627,7 +3002,7 @@ function scriptCommand(packageManager, name) {
 }
 async function exists6(path) {
   try {
-    await stat8(path);
+    await stat9(path);
     return true;
   } catch {
     return false;
@@ -2635,13 +3010,13 @@ async function exists6(path) {
 }
 
 // src/scanner/routes.ts
-import { readdir as readdir2, stat as stat9 } from "fs/promises";
-import { join as join17, relative, sep } from "path";
+import { readdir as readdir2, stat as stat10 } from "fs/promises";
+import { join as join19, relative, sep } from "path";
 async function scanRoutes(projectRoot) {
   const candidates = ["src/routes", "src/pages", "app", "pages"];
   const routes = [];
   for (const candidate of candidates) {
-    const root = join17(projectRoot, candidate);
+    const root = join19(projectRoot, candidate);
     if (!await exists7(root)) {
       continue;
     }
@@ -2669,7 +3044,7 @@ async function listFiles(root) {
   const entries = await readdir2(root, { withFileTypes: true });
   const files = [];
   for (const entry of entries) {
-    const path = join17(root, entry.name);
+    const path = join19(root, entry.name);
     if (entry.isDirectory()) {
       files.push(...await listFiles(path));
     } else {
@@ -2680,7 +3055,7 @@ async function listFiles(root) {
 }
 async function exists7(path) {
   try {
-    await stat9(path);
+    await stat10(path);
     return true;
   } catch {
     return false;
@@ -2827,6 +3202,13 @@ program.name("fet").description("Frontend workflow orchestration tool built arou
 addGlobalOptions(program.command("init")).description("\u521D\u59CB\u5316 FET + OpenSpec").action(wrap("init", initCommand));
 addGlobalOptions(program.command("update-context")).description("\u66F4\u65B0\u9879\u76EE\u4E0A\u4E0B\u6587").action(wrap("update-context", updateContextCommand));
 addGlobalOptions(program.command("fill-context")).description("Refresh IDE prompts for filling AGENTS.md placeholders").action(wrap("fill-context", fillContextCommand));
+var graph = addGlobalOptions(program.command("graph").description("Manage optional GitNexus code graph support"));
+for (const action of ["status", "setup", "doctor", "handoff"]) {
+  addGlobalOptions(graph.command(action).description(`Run fet graph ${action}`)).action(wrap("graph", (ctx) => graphCommand(ctx, action)));
+}
+for (const action of ["init", "refresh"]) {
+  addGlobalOptions(graph.command(`${action} [args...]`).description(`Run GitNexus analyze for graph ${action}`).allowUnknownOption(true).passThroughOptions()).action(wrap("graph", (ctx, args = []) => graphCommand(ctx, action, args)));
+}
 addGlobalOptions(program.command("doctor").description("\u8BCA\u65AD\u72B6\u6001\u3001\u914D\u7F6E\u4E0E\u4E00\u81F4\u6027").option("--fix-lock", "\u6E05\u7406 FET \u9501\u6587\u4EF6")).action(
   wrap("doctor", (ctx, options) => doctorCommand(ctx, { fixLock: Boolean(options.fixLock) }))
 );