@staix/agent-mem 0.10.0 → 0.12.0

package/src/setup.ts

@@ -10,6 +10,7 @@ import { fileURLToPath } from "node:url";
 import { isDeepStrictEqual } from "node:util";
 import { HOOK_EVENTS } from "./hook-contract.ts";
 import { memoryHome } from "./memory/home.ts";
+import { label, PLAIN, type Style } from "./memory/style.ts";
 import { canonicalPath, memoryGitEnv, memoryGitSync, processLiveness, processSignature, realPath } from "./memory/platform.ts";
 
 export const SETUP_TARGETS = ["claude", "codex", "kimi", "pi", "qwen", "jcode", "agy"] as const;
@@ -152,7 +153,8 @@ function context(options: SetupContext, workspace?: WorkspaceBinding) {
 }
 function command(target: SetupTarget, bun: string, entry: string): string[] | null {
   if (target === "kimi" || target === "jcode" || target === "agy") return null;
-  return [target, "mcp", "add", ...(target === "claude" || target === "qwen" ? ["--scope", "user", "--transport", "stdio"] : []), "amem", "--", bun, "--smol", entry, "mcp"];
+  if (target === "qwen") return [target, "mcp", "add", "--scope", "user", "--transport", "stdio", "amem", bun, "--", "--smol", entry, "mcp"];
+  return [target, "mcp", "add", ...(target === "claude" ? ["--scope", "user", "--transport", "stdio"] : []), "amem", "--", bun, "--smol", entry, "mcp"];
 }
 function assertJcodeHome(env: Env): void {
   if (env.JCODE_HOME !== undefined && !isAbsolute(env.JCODE_HOME)) throw Error("setup requires an absolute JCODE_HOME; unset it to use the default");
@@ -227,7 +229,12 @@ function verifyNativeMcp(target: SetupTarget, env: Env, cwd: string): void {
 }
 function native(argv: readonly string[], env: Env, cwd: string): void {
   const result = spawnSync(argv[0]!, argv.slice(1), { cwd, env: { ...env }, encoding: "utf8", timeout: 10_000, maxBuffer: MAX, stdio: ["ignore", "pipe", "pipe"] });
-  if (result.status !== 0) throw Error(`${argv[0]} MCP registration failed in staging; no native output disclosed`);
+  if (result.status !== 0) {
+    const timedOut = (result.error as NodeJS.ErrnoException | undefined)?.code === "ETIMEDOUT";
+    const argumentsRejected = argv[0] === "qwen" && `${result.stderr ?? ""}\n${result.stdout ?? ""}`.includes("Not enough non-option arguments:");
+    const reason = timedOut ? "timed out" : argumentsRejected ? "rejected command arguments" : "failed";
+    throw Error(`${argv[0]} MCP registration ${reason} in staging; no native output disclosed`);
+  }
 }
 function hookDocument(before: Image, events: readonly string[], commandFor: (event: string) => string, timeout = 1): Image {
   const document = json(before), hooks = document.hooks === undefined ? {} : record(document.hooks);
@@ -284,16 +291,33 @@ function prepare(c: ReturnType<typeof context>, target: SetupTarget, options: Se
       if (servers && Object.hasOwn(record(servers), "amem")) (options.native ?? native)([target, "mcp", "remove", ...(target === "claude" || target === "qwen" ? ["--scope", "user"] : []), "amem"], env, staging);
       (options.native ?? native)(argv, env, staging);
       changes[0]!.after = { ...read(staged.paths[target][0]!), mode: changes[0]!.before.mode };
-      if (changes[0]!.after.bytes === null) throw Error("native registration produced no configuration");
+      if (changes[0]!.after.bytes === null) throw Error(`${target} native registration produced no configuration`);
       const installedText = Buffer.from(changes[0]!.after.bytes!, "base64").toString("utf8");
-      const installed = target === "codex" ? toml(installedText) : json(changes[0]!.after);
-      const installedServer = record(record(installed[target === "codex" ? "mcp_servers" : "mcpServers"]).amem);
-      if (installedServer.command !== c.bun || JSON.stringify(installedServer.args) !== JSON.stringify(["--smol", c.entry, "mcp"]) || installedServer.enabled === false) throw Error("native registration did not produce the planned amem server");
+      let installed: Record<string, unknown>, installedServer: Record<string, unknown>;
+      try {
+        installed = target === "codex" ? toml(installedText) : json(changes[0]!.after);
+        installedServer = record(record(installed[target === "codex" ? "mcp_servers" : "mcpServers"]).amem);
+      } catch { throw Error(`${target} native registration produced invalid configuration; no configuration published`); }
+      if (installedServer.command !== c.bun || JSON.stringify(installedServer.args) !== JSON.stringify(["--smol", c.entry, "mcp"]) || installedServer.enabled === false) throw Error(`${target} native registration did not produce the planned amem server`);
       const serverKey = target === "codex" ? "mcp_servers" : "mcpServers";
       const withoutAmem = (value: Record<string, unknown>) => { const copy = { ...value }, servers = { ...record(value[serverKey] ?? {}) }; delete servers.amem; copy[serverKey] = servers; return copy; };
-      if (!isDeepStrictEqual(withoutAmem(document)[serverKey], withoutAmem(installed)[serverKey])) throw Error("native registration changed unrelated MCP servers; no configuration published");
+      const originalUnrelated = withoutAmem(document), installedUnrelated = withoutAmem(installed);
+      if (target === "codex") {
+        // Restore the omitted default only in this detached comparison, never in native output.
+        const originalServers = record(originalUnrelated[serverKey]), installedServers = record(installedUnrelated[serverKey]);
+        for (const [name, value] of Object.entries(originalServers)) {
+          if (!Object.hasOwn(installedServers, name)) continue;
+          const before = record(value), after = installedServers[name];
+          if (typeof before.command === "string" && Object.hasOwn(before, "args") && Array.isArray(before.args) && before.args.length === 0
+              && after && typeof after === "object" && !Array.isArray(after) && !Object.hasOwn(after, "args")) {
+            installedServers[name] = { ...after, args: [] };
+          }
+        }
+      }
+      if (!isDeepStrictEqual(originalUnrelated[serverKey], installedUnrelated[serverKey])) throw Error(`${target} native registration changed unrelated MCP servers; no configuration published`);
       if (target === "codex") {
-        if (!isDeepStrictEqual(withoutAmem(document), withoutAmem(installed))) throw Error("native registration changed unrelated settings; no configuration published");
+        if (!isDeepStrictEqual(originalUnrelated, installedUnrelated)) throw Error("codex native registration changed unrelated settings; no configuration published");
+        changes[0]!.after = putMcpRecord(target, changes[0]!.before, installedServer);
       } else {
         // Keep all unrelated JSON settings from the original; use only the CLI-generated server record.
         // Qwen's restored image also retires its previous managed hook on a runtime upgrade.
@@ -425,16 +449,54 @@ export function undoSetup(plan: SetupPlan, options: SetupContext = {}): { restor
   return withSetupLock(options, () => undoUnlocked(plan, options));
 }
 
-export async function runSetup(target: string, mode: SetupPlan["mode"], options: SetupContext = {}): Promise<string> {
-  const plan = planSetup(target, mode, options);
-  if (mode === "preview") return JSON.stringify(plan, null, 2);
+/** Person-facing setup plan (#125): each target once, with its effective files, MCP and hook changes, then skipped clients and notes. `--json` keeps the raw plan. */
+export function setupPlanText(plan: SetupPlan, s: Style = PLAIN): string {
+  const verb = plan.mode === "undo" ? "undo" : plan.mode === "apply" ? "apply" : "preview";
+  // Undo restores every target with a receipt whether or not its CLI is still installed (undoUnlocked), so undo never collapses an action.
+  const full = (action: SetupPlan["actions"][number]) => plan.mode === "undo" || action.available;
+  const skipped = plan.actions.filter(action => !full(action)), changing = plan.actions.filter(action => full(action) && action.mcpChange !== "unchanged");
+  const lines = [`${s.bold(`amem setup ${verb}:`)} ${plan.targets.length} target${plan.targets.length === 1 ? "" : "s"}, ${changing.length} with ${plan.mode === "undo" ? "restores" : "MCP changes"}${skipped.length ? `, ${skipped.length} skipped` : ""}`, ""];
+  for (const action of plan.actions) {
+    if (!full(action)) { lines.push(`${label(s, "skipped")} ${s.bold(action.target)}: CLI not installed`); continue; }
+    const state = action.mcpChange === "unchanged" ? "ok" : "attention";
+    const what = action.mcpChange === "unchanged" ? plan.mode === "undo" ? "no setup receipt; nothing to restore" : "already set up; no change" : action.mcpChange === "restore" ? `restore original MCP/hook files${action.available ? "" : " (CLI not installed)"}` : `MCP ${action.mcpChange}`;
+    lines.push(`${label(s, state)} ${s.bold(action.target)}: ${what} ${s.dim(`(${action.state})`)}`);
+    for (const file of action.files) lines.push(`            file     ${file}`);
+    if (action.cwd) lines.push(`            cwd      ${action.cwd}`);
+    lines.push(`            receipt  ${action.receipt}`);
+    if (action.available && action.registration) lines.push(`            command  ${action.registration.map(quote).join(" ")}`);
+    for (const hook of action.hooks) lines.push(`            hook     ${hook.event}: ${hook.command} (timeout ${hook.timeout})`);
+    if (action.available && !action.hooks.length && plan.mode !== "undo") lines.push(`            hook     ${s.dim("none")}`);
+    lines.push(`            ${s.dim(action.lifecycle)}`);
+  }
+  const warnings = plan.notes.filter(note => /^WARNING|detected|version-specific/.test(note)), notes = plan.notes.filter(note => !warnings.includes(note));
+  if (skipped.length) lines.push("", `Skipped clients: ${skipped.map(action => action.target).join(", ")} (not installed)`);
+  if (warnings.length) lines.push("", "Warnings:", ...warnings.map(note => `  - ${s.attention(note)}`));
+  lines.push("", "Notes:", ...notes.map(note => `  - ${note}`));
+  if (plan.mode === "preview") lines.push("", `Next: amem setup ${plan.targets.length === 1 ? plan.targets[0] : "all"} --apply (asks before writing); --json prints the full plan`);
+  return lines.join("\n");
+}
+
+function setupResultText(result: SetupApplyResult | { restored: SetupTarget[] }, s: Style): string {
+  if ("restored" in result) return `${label(s, "ok")} restored: ${result.restored.join(", ") || "none"}`;
+  return [`${label(s, "ok")} applied: ${result.applied.join(", ") || "none"}`, `${label(s, "ok")} unchanged: ${result.unchanged.join(", ") || "none"}`,
+    ...(result.skipped ?? []).map(item => `${label(s, "skipped")} ${item.target}: ${item.reason}`)].join("\n");
+}
+
+/** What the default confirmation prints before its prompt: the raw plan under `--json`, the readable plan otherwise. */
+export function setupConfirmationText(plan: SetupPlan, json: boolean, s: Style = PLAIN): string { return json ? JSON.stringify(plan, null, 2) : setupPlanText(plan, s); }
+
+export async function runSetup(target: string, mode: SetupPlan["mode"], options: SetupContext & { json?: boolean; style?: Style } = {}): Promise<string> {
+  const plan = planSetup(target, mode, options), s = options.json ? PLAIN : options.style ?? PLAIN;
+  if (mode === "preview") return options.json ? JSON.stringify(plan, null, 2) : setupPlanText(plan, s);
   if (!(options.stdinTTY ?? process.stdin.isTTY)) throw Error("setup --apply/--undo require a terminal on stdin");
   const confirm = options.confirm ?? (async (shown: SetupPlan) => {
-    process.stdout.write(JSON.stringify(shown, null, 2) + "\n");
+    process.stdout.write(setupConfirmationText(shown, options.json === true, s) + "\n\n");
     const terminal = createInterface({ input: process.stdin, output: process.stdout });
     try { return (await terminal.question(`Type yes to ${mode} the listed configuration changes: `)).trim() === "yes"; }
     finally { terminal.close(); }
   });
-  if (!await confirm(plan)) return JSON.stringify({ cancelled: true });
-  return JSON.stringify(mode === "apply" ? applySetup(plan, options) : undoSetup(plan, options), null, 2);
+  if (!await confirm(plan)) return options.json ? JSON.stringify({ cancelled: true }) : "setup cancelled; nothing changed";
+  const result = mode === "apply" ? applySetup(plan, options) : undoSetup(plan, options);
+  return options.json ? JSON.stringify(result, null, 2) : setupResultText(result, s);
 }