muonroi-cli 1.2.3 → 1.3.2

package/src/scaffold/point-to-existing.ts

@@ -0,0 +1,83 @@
+/**
+ * point-to-existing.ts — Validate a user-provided path for an existing project
+ * and detect whether it contains a verify recipe.
+ *
+ * Designed for testability: callers inject detectVerifyRecipe so unit tests
+ * never hit the real orchestrator.
+ */
+
+import { realpathSync, statSync } from "node:fs";
+import * as path from "node:path";
+import { detectBBFramework } from "./init-new.js";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface PointToExistingOptions {
+  /** Raw path string entered by the user. May be relative or absolute. */
+  path: string;
+  /**
+   * Injected verify-recipe detector.
+   * Returns a non-null recipe when the cwd looks like a configured project,
+   * or null when no recipe is found.
+   */
+  detectVerifyRecipe: (cwd: string) => Promise<unknown | null>;
+}
+
+export type PointToExistingReason = "not_a_dir" | "no_recipe" | "ok";
+
+export interface PointToExistingResult {
+  ok: boolean;
+  reason: PointToExistingReason;
+  recipe?: unknown;
+  absolutePath: string;
+  /** Detected target framework (e.g. "muonroi-building-block") when BB heuristic matches. */
+  targetFramework?: "muonroi-building-block" | string;
+}
+
+export { detectBBFramework };
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve and validate a user-provided path for sprint re-entry.
+ *
+ * Steps:
+ *  1. Resolve to an absolute path (handles ~ and relative segments).
+ *  2. Stat — confirm it is an existing directory. Returns `not_a_dir` otherwise.
+ *  3. Call opts.detectVerifyRecipe(absPath). If null → `no_recipe`.
+ *  4. Return { ok: true, reason: "ok", recipe, absolutePath }.
+ */
+export async function pointToExisting(opts: PointToExistingOptions): Promise<PointToExistingResult> {
+  // Step 1: resolve to absolute path, expanding ~ on POSIX.
+  const expanded = opts.path.startsWith("~")
+    ? path.join(process.env.HOME ?? process.env.USERPROFILE ?? "/", opts.path.slice(1))
+    : opts.path;
+
+  const absolutePath = path.resolve(expanded);
+
+  // Step 2: verify it is an existing directory.
+  try {
+    // realpathSync also catches dangling symlinks.
+    realpathSync(absolutePath);
+    const st = statSync(absolutePath);
+    if (!st.isDirectory()) {
+      return { ok: false, reason: "not_a_dir", absolutePath };
+    }
+  } catch {
+    return { ok: false, reason: "not_a_dir", absolutePath };
+  }
+
+  // Step 3: detect verify recipe.
+  const recipe = await opts.detectVerifyRecipe(absolutePath);
+  if (recipe === null || recipe === undefined) {
+    return { ok: false, reason: "no_recipe", absolutePath };
+  }
+
+  // Step 4: success.
+  const targetFramework = detectBBFramework(absolutePath);
+  return { ok: true, reason: "ok", recipe, absolutePath, ...(targetFramework ? { targetFramework } : {}) };
+}

package/src/scaffold/resume-from-gate-failures.ts

@@ -0,0 +1,167 @@
+/**
+ * resume-from-gate-failures.ts — /ideal --resume <project-path> handler.
+ *
+ * Task 6.16:
+ *   Detects EE-GATE-FAILURES.md at the given project path.
+ *   Loads failure context + re-enters CB-1 via existing runSprint machinery.
+ *
+ * NOTE: point-to-existing.ts is used ONLY for path validation.
+ * CB-1 re-entry + context loading are implemented here from scratch.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+import type { ContinueAsCouncilOptions } from "./continue-as-council.js";
+import { continueAsCouncil } from "./continue-as-council.js";
+import { pointToExisting } from "./point-to-existing.js";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface ResumeFromGateFailuresOptions {
+  /**
+   * Path to the project directory containing EE-GATE-FAILURES.md.
+   * May be absolute or relative.
+   */
+  projectPath: string;
+  /**
+   * Inject council runner (for testability).
+   * Defaults to continueAsCouncil with no-op stream.
+   */
+  runCouncil?: ContinueAsCouncilOptions["runCouncil"];
+  /**
+   * Inject fs ops for testability.
+   */
+  fs?: {
+    exists: (p: string) => boolean;
+    readFile: (p: string) => string;
+  };
+  /**
+   * Inject detectVerifyRecipe for path validation via point-to-existing.
+   */
+  detectVerifyRecipe?: (cwd: string) => Promise<unknown | null>;
+}
+
+export interface ResumeResult {
+  ok: boolean;
+  reason: "no_gate_failures_file" | "invalid_path" | "resumed" | "error";
+  specPath?: string;
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * /ideal --resume <project-path>
+ *
+ * 1. Validates the path via point-to-existing (path validation only).
+ * 2. Loads EE-GATE-FAILURES.md content.
+ * 3. Re-enters CB-1 via continueAsCouncil with failures as initial prompt.
+ */
+export async function resumeFromGateFailures(opts: ResumeFromGateFailuresOptions): Promise<ResumeResult> {
+  const fsOps = opts.fs ?? {
+    exists: (p: string) => existsSync(p),
+    readFile: (p: string) => readFileSync(p, "utf-8"),
+  };
+
+  // Step 1: validate path using point-to-existing (path validation only)
+  const detectRecipe = opts.detectVerifyRecipe ?? (() => Promise.resolve(null));
+  const pathResult = await pointToExisting({ path: opts.projectPath, detectVerifyRecipe: detectRecipe });
+
+  if (!pathResult.ok) {
+    return { ok: false, reason: "invalid_path", error: `Path validation failed: ${pathResult.reason}` };
+  }
+
+  const absolutePath = pathResult.absolutePath;
+
+  // Step 2: detect EE-GATE-FAILURES.md
+  const gateFailuresPath = path.join(absolutePath, "EE-GATE-FAILURES.md");
+  if (!fsOps.exists(gateFailuresPath)) {
+    return {
+      ok: false,
+      reason: "no_gate_failures_file",
+      error: `No EE-GATE-FAILURES.md found at ${absolutePath}`,
+    };
+  }
+
+  // Step 3: load failure context
+  let failuresContent: string;
+  try {
+    failuresContent = fsOps.readFile(gateFailuresPath);
+  } catch (err) {
+    return {
+      ok: false,
+      reason: "error",
+      error: `Failed to read EE-GATE-FAILURES.md: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  // Also load EE-INTENT.md if present for original intent context
+  const intentPath = path.join(absolutePath, "EE-INTENT.md");
+  let intentContent = "";
+  if (fsOps.exists(intentPath)) {
+    try {
+      intentContent = fsOps.readFile(intentPath);
+    } catch {
+      // Non-fatal — proceed without it
+    }
+  }
+
+  // Step 4: Re-enter CB-1 via continueAsCouncil with failure context
+  const resumePrompt = buildResumePrompt(failuresContent, intentContent);
+
+  try {
+    const councilResult = await continueAsCouncil({
+      prompt: resumePrompt,
+      outputDir: absolutePath,
+      runCouncil: opts.runCouncil,
+    });
+
+    return { ok: true, reason: "resumed", specPath: councilResult.specPath };
+  } catch (err) {
+    return {
+      ok: false,
+      reason: "error",
+      error: `Council re-entry failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function buildResumePrompt(failuresContent: string, intentContent: string): string {
+  const sections: string[] = [
+    "# /ideal --resume: Fix gate failures",
+    "",
+    "The previous scaffold run produced gate failures. Please analyze them and provide",
+    "corrected BB ecosystem wiring (Program.cs, Directory.Packages.props, etc.).",
+    "",
+  ];
+
+  if (intentContent) {
+    sections.push("## Original Intent");
+    sections.push("");
+    sections.push(intentContent.slice(0, 800));
+    sections.push("");
+  }
+
+  sections.push("## Gate Failures to Fix");
+  sections.push("");
+  sections.push(failuresContent.slice(0, 2000));
+  sections.push("");
+  sections.push("## Instructions");
+  sections.push("");
+  sections.push(
+    "1. Identify root cause of each failure from the output above.",
+    "2. Suggest specific code changes to Program.cs or Directory.Packages.props.",
+    "3. If boundary violations: list which packages to remove or replace with OSS alternatives.",
+    "4. Output a revised scaffold plan that will pass the quality gate.",
+  );
+
+  return sections.join("\n");
+}

package/src/storage/__tests__/ui-interaction-log.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Tests for logUIInteraction — verify subtype routing and fail-open behaviour.
+ *
+ * The underlying logInteraction is mocked so we can assert the call shape
+ * without standing up a SQLite test fixture.
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../interaction-log.js", () => ({
+  logInteraction: vi.fn(),
+}));
+
+import { logInteraction } from "../interaction-log.js";
+import { logUIInteraction } from "../ui-interaction-log.js";
+
+describe("logUIInteraction", () => {
+  beforeEach(() => {
+    vi.mocked(logInteraction).mockClear();
+  });
+
+  it("skips persistence when sessionId is null", () => {
+    logUIInteraction(null, {
+      subtype: "route_decision",
+      data: { path: "hot-path", complexity: "low", forceCouncil: false, runId: "r1" },
+    });
+    expect(logInteraction).not.toHaveBeenCalled();
+  });
+
+  it("skips persistence when sessionId is undefined", () => {
+    logUIInteraction(undefined, {
+      subtype: "askcard_open",
+      data: { questionId: "q1", question: "?", phase: "clarify", optionCount: 2 },
+    });
+    expect(logInteraction).not.toHaveBeenCalled();
+  });
+
+  it("writes ui_interaction with subtype and structured payload", () => {
+    logUIInteraction("sess-1", {
+      subtype: "askcard_answered",
+      data: { questionId: "q1", answerKind: "choice", answerText: "React" },
+    });
+    expect(logInteraction).toHaveBeenCalledWith("sess-1", "ui_interaction", {
+      eventSubtype: "askcard_answered",
+      data: { questionId: "q1", answerKind: "choice", answerText: "React" },
+    });
+  });
+
+  it("routes each subtype with the right shape", () => {
+    const cases = [
+      {
+        subtype: "route_decision" as const,
+        data: { path: "council" as const, complexity: "high", forceCouncil: true, runId: "r9" },
+      },
+      {
+        subtype: "sprint_stage" as const,
+        data: { sprintIndex: 1, stage: "planning" as const, runId: "r9" },
+      },
+      { subtype: "sprint_halt" as const, data: { sprintN: 2, reason: "no_recipe", runId: "r9" } },
+      { subtype: "askcard_cancel" as const, data: { questionId: "q9" } },
+      {
+        subtype: "halt_card_open" as const,
+        data: {
+          reason: "no_recipe",
+          optionCount: 3,
+          optionIds: ["init_new", "point_to_existing", "continue_as_council"],
+        },
+      },
+      {
+        subtype: "halt_card_answered" as const,
+        data: { chosenId: "init_new", chosenLabel: "Init new project", index: 0 },
+      },
+      { subtype: "init_new_step" as const, data: { from: "name", to: "fe-stack" } },
+      {
+        subtype: "init_new_submitted" as const,
+        data: { projectName: "todo-app", feStack: "react", bbTemplate: "mr-base-sln", packageCount: 5 },
+      },
+      {
+        subtype: "init_new_result" as const,
+        data: { outcome: "error" as const, message: "dotnet new install failed: exit 1" },
+      },
+    ];
+    for (const c of cases) {
+      logUIInteraction("sess-2", c);
+    }
+    expect(vi.mocked(logInteraction).mock.calls.map(([, , meta]) => meta?.eventSubtype)).toEqual([
+      "route_decision",
+      "sprint_stage",
+      "sprint_halt",
+      "askcard_cancel",
+      "halt_card_open",
+      "halt_card_answered",
+      "init_new_step",
+      "init_new_submitted",
+      "init_new_result",
+    ]);
+  });
+
+  it("fails open when logInteraction throws", () => {
+    vi.mocked(logInteraction).mockImplementationOnce(() => {
+      throw new Error("db gone");
+    });
+    expect(() => logUIInteraction("sess-3", { subtype: "askcard_cancel", data: { questionId: "q1" } })).not.toThrow();
+  });
+});

package/src/storage/atomic-io.test.ts

@@ -2,7 +2,7 @@ import { promises as fs } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { atomicReadJSON, atomicWriteJSON } from "./atomic-io.js";
+import { atomicReadJSON, atomicWriteJSON, sweepStaleAtomicTemps } from "./atomic-io.js";
 
 let tmpDir: string;
 
@@ -59,3 +59,34 @@ describe("atomicReadJSON", () => {
     await expect(atomicReadJSON(filePath)).rejects.toThrow();
   });
 });
+
+describe("sweepStaleAtomicTemps", () => {
+  it("Test 5: removes only matching .{pid}.{hex}.tmp older than cutoff", async () => {
+    const oldStale = path.join(tmpDir, "state.json.12345.abcdef012345.tmp");
+    const freshStale = path.join(tmpDir, "state.json.99999.fedcba543210.tmp");
+    const unrelated = path.join(tmpDir, "notes.tmp");
+    const real = path.join(tmpDir, "state.json");
+
+    await fs.writeFile(oldStale, "{}");
+    await fs.writeFile(freshStale, "{}");
+    await fs.writeFile(unrelated, "junk");
+    await fs.writeFile(real, "{}");
+
+    // Backdate oldStale by 48h
+    const old = Date.now() / 1000 - 48 * 3600;
+    await fs.utimes(oldStale, old, old);
+
+    const removed = await sweepStaleAtomicTemps(tmpDir, 24 * 60 * 60 * 1000);
+    expect(removed).toBe(1);
+
+    await expect(fs.access(oldStale)).rejects.toThrow();
+    await expect(fs.access(freshStale)).resolves.toBeUndefined();
+    await expect(fs.access(unrelated)).resolves.toBeUndefined();
+    await expect(fs.access(real)).resolves.toBeUndefined();
+  });
+
+  it("Test 6: returns 0 and does not throw when dir does not exist", async () => {
+    const removed = await sweepStaleAtomicTemps(path.join(tmpDir, "does-not-exist"));
+    expect(removed).toBe(0);
+  });
+});

package/src/storage/atomic-io.ts

@@ -1,6 +1,14 @@
+import * as crypto from "node:crypto";
 import { promises as fs } from "node:fs";
 import * as path from "node:path";
 
+// Unique tmp path per call so concurrent writers don't clobber each other's
+// .tmp before rename — required for Windows where rename of a file held by
+// another writer fails EPERM/EBUSY.
+function tmpPathFor(filePath: string): string {
+  return `${filePath}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`;
+}
+
 /**
  * Atomically write a JSON value to filePath using .tmp + rename pattern.
  * Pitfall 9 mitigation: a Ctrl+C between write and rename leaves no dangling state.
@@ -9,7 +17,7 @@ import * as path from "node:path";
  * On serialize failure, .tmp is never created. On rename failure, .tmp is cleaned up.
  */
 export async function atomicWriteJSON(filePath: string, value: unknown): Promise<void> {
-  const tmpPath = `${filePath}.tmp`;
+  const tmpPath = tmpPathFor(filePath);
   let serialized: string;
   try {
     serialized = JSON.stringify(value, null, 2);
@@ -21,6 +29,17 @@ export async function atomicWriteJSON(filePath: string, value: unknown): Promise
     await fs.writeFile(tmpPath, serialized, "utf8");
     await fs.rename(tmpPath, filePath);
   } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    // ENOENT on rename means another writer already completed the atomic swap.
+    // Verify the final file exists before treating as success.
+    if (e.code === "ENOENT") {
+      try {
+        await fs.access(filePath);
+        return; // race loser — final file written by another process
+      } catch {
+        // final file does not exist — real failure
+      }
+    }
     // Clean up the .tmp if rename failed mid-flight
     await fs.unlink(tmpPath).catch(() => {
       /* ignore */
@@ -34,17 +53,96 @@ export async function atomicWriteJSON(filePath: string, value: unknown): Promise
  * Same durability guarantees as atomicWriteJSON but without JSON serialization.
  */
 export async function atomicWriteText(filePath: string, content: string): Promise<void> {
-  const tmpPath = `${filePath}.tmp`;
+  const tmpPath = tmpPathFor(filePath);
   await fs.mkdir(path.dirname(filePath), { recursive: true });
+  // Retry the write+rename pair up to 3 times with backoff. On Windows the
+  // rename can race with antivirus / Search Indexer / Explorer probes that
+  // briefly open the target for read; under load the OS sometimes returns
+  // EBUSY / EPERM, and observed once in E2E: the rename Promise hangs
+  // forever (Bun's libuv path on a contended target). The retry+timeout
+  // recovers without losing the write.
+  const RETRIES = 3;
+  const STEP_TIMEOUT_MS = 10_000;
+  let lastErr: unknown;
+  for (let attempt = 0; attempt < RETRIES; attempt++) {
+    try {
+      await withTimeout(fs.writeFile(tmpPath, content, "utf8"), STEP_TIMEOUT_MS, "writeFile");
+      await withTimeout(fs.rename(tmpPath, filePath), STEP_TIMEOUT_MS, "rename");
+      return;
+    } catch (err) {
+      lastErr = err;
+      const e = err as NodeJS.ErrnoException;
+      if (e?.code === "ENOENT") {
+        try {
+          await fs.access(filePath);
+          return; // race loser
+        } catch {}
+      }
+      await fs.unlink(tmpPath).catch(() => {
+        /* ignore */
+      });
+      if (attempt < RETRIES - 1) {
+        await new Promise((r) => setTimeout(r, 50 * 2 ** attempt));
+      }
+    }
+  }
+  throw lastErr;
+}
+
+function withTimeout<T>(p: Promise<T>, ms: number, label: string): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  return Promise.race([
+    p.finally(() => {
+      if (timer) clearTimeout(timer);
+    }),
+    new Promise<T>((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`atomicWriteText.${label} timed out after ${ms}ms`)), ms);
+    }),
+  ]);
+}
+
+/**
+ * Best-effort sweep of stale atomic-write staging files in `dir`.
+ *
+ * Matches the per-call tmp shape `{name}.{pid}.{hex}.tmp` and removes any
+ * older than `maxAgeMs` (default 24h). Designed to run on boot — if a writer
+ * crashed mid-rename, its tmp will accumulate forever otherwise.
+ *
+ * Errors are swallowed: sweeping is opportunistic and must never block boot.
+ * Recurses one level (e.g. ~/.muonroi-cli/{sessions,usage}/) but stops there
+ * to keep cost bounded.
+ */
+export async function sweepStaleAtomicTemps(
+  dir: string,
+  maxAgeMs: number = 24 * 60 * 60 * 1000,
+  depth: number = 1,
+): Promise<number> {
+  let removed = 0;
+  const cutoff = Date.now() - maxAgeMs;
+  let entries: import("node:fs").Dirent[];
   try {
-    await fs.writeFile(tmpPath, content, "utf8");
-    await fs.rename(tmpPath, filePath);
-  } catch (err) {
-    await fs.unlink(tmpPath).catch(() => {
-      /* ignore */
-    });
-    throw err;
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  for (const ent of entries) {
+    const full = path.join(dir, ent.name);
+    if (ent.isDirectory()) {
+      if (depth > 0) removed += await sweepStaleAtomicTemps(full, maxAgeMs, depth - 1);
+      continue;
+    }
+    if (!/\.\d+\.[0-9a-f]{12}\.tmp$/.test(ent.name)) continue;
+    try {
+      const st = await fs.stat(full);
+      if (st.mtimeMs < cutoff) {
+        await fs.unlink(full);
+        removed++;
+      }
+    } catch {
+      /* ignore individual failures */
+    }
   }
+  return removed;
 }
 
 /**

package/src/storage/config.ts

@@ -1,6 +1,6 @@
 import * as os from "node:os";
 import * as path from "node:path";
-import { atomicReadJSON, atomicWriteJSON } from "./atomic-io.js";
+import { atomicReadJSON, atomicWriteJSON, sweepStaleAtomicTemps } from "./atomic-io.js";
 
 /**
  * TUI-owned cap configuration stored at ~/.muonroi-cli/config.json.
@@ -34,6 +34,10 @@ function muonroiHome(override?: string): string {
  */
 export async function loadConfig(homeOverride?: string): Promise<MuonroiConfig> {
   const home = muonroiHome(homeOverride);
+  // Best-effort cleanup of crashed-writer leftovers. Never throws.
+  sweepStaleAtomicTemps(home).catch(() => {
+    /* swallow */
+  });
   const filePath = path.join(home, "config.json");
   const existing = await atomicReadJSON<MuonroiConfig>(filePath);
   if (existing) {