muonroi-cli 1.2.0

package/src/ee/scope.ts

@@ -0,0 +1,93 @@
+/**
+ * Scope builder — derives EE scope from session cwd by reading .git/HEAD + .git/config.
+ *
+ * Pitfall 6 (CONTEXT.md): scope is cached at session boot, NOT re-computed per call.
+ * Never uses child_process — reads git files directly via fs.
+ *
+ * EE-05: Scope payload is one of {global | ecosystem:muonroi | repo:<remote> | branch:<remote+branch>}.
+ */
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { loadUserSettings } from "../utils/settings.js";
+import type { Scope } from "./types.js";
+
+let cached: Scope | null = null;
+let cachedFor: string | null = null;
+
+function parseGitConfig(text: string): { remote?: string } {
+  // Find [remote "origin"]\n  url = X
+  const m = text.match(/\[remote\s+"origin"\]([\s\S]*?)(?=\n\[|$)/);
+  if (!m) return {};
+  const url = m[1].match(/^\s*url\s*=\s*(.+)$/m);
+  return { remote: url ? url[1].trim() : undefined };
+}
+
+function parseHEAD(text: string): { branch?: string; detached?: boolean } {
+  const t = text.trim();
+  if (t.startsWith("ref: refs/heads/")) return { branch: t.slice("ref: refs/heads/".length) };
+  return { detached: true };
+}
+
+async function findGitRoot(start: string): Promise<string | null> {
+  let dir = start;
+  for (let i = 0; i < 10; i++) {
+    try {
+      await fs.access(path.join(dir, ".git", "HEAD"));
+      return dir;
+    } catch {
+      /* not here */
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+export async function buildScope(opts: { cwd: string }): Promise<Scope> {
+  if (cached && cachedFor === opts.cwd) return cached;
+  const root = await findGitRoot(opts.cwd);
+  if (!root) {
+    cached = { kind: "global" };
+    cachedFor = opts.cwd;
+    return cached;
+  }
+  const head = await fs.readFile(path.join(root, ".git", "HEAD"), "utf8").catch(() => "");
+  const cfg = await fs.readFile(path.join(root, ".git", "config"), "utf8").catch(() => "");
+  const { remote } = parseGitConfig(cfg);
+  const { branch } = parseHEAD(head);
+
+  // Ecosystem detection — check if remote matches any configured pattern
+  if (remote) {
+    const eco = loadUserSettings().ecosystem;
+    if (eco && eco.patterns.some((p) => remote.includes(p))) {
+      cached = { kind: "ecosystem", name: eco.name };
+      cachedFor = opts.cwd;
+      return cached;
+    }
+  }
+
+  if (remote && branch) cached = { kind: "branch", remote, branch };
+  else if (remote) cached = { kind: "repo", remote };
+  else cached = { kind: "global" };
+  cachedFor = opts.cwd;
+  return cached;
+}
+
+export function scopeLabel(s: Scope): string {
+  switch (s.kind) {
+    case "global":
+      return "global";
+    case "ecosystem":
+      return `ecosystem:${s.name}`;
+    case "repo":
+      return `repo:${s.remote}`;
+    case "branch":
+      return `branch:${s.remote}#${s.branch}`;
+  }
+}
+
+export function resetScopeCache(): void {
+  cached = null;
+  cachedFor = null;
+}

package/src/ee/tenant.ts

@@ -0,0 +1,14 @@
+/**
+ * Centralized tenant ID — single source of truth.
+ * Default "local" for BYOK/self-hosted mode.
+ * Phase 4 cloud mode will call setTenantId() after auth.
+ */
+let _tenantId = "local";
+
+export function getTenantId(): string {
+  return _tenantId;
+}
+
+export function setTenantId(id: string): void {
+  _tenantId = id;
+}

package/src/ee/touch.test.ts

@@ -0,0 +1,71 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { type StubHandle, startStubEEServer } from "../__test-stubs__/ee-server.js";
+import { createEEClient } from "./client.js";
+import type { FeedbackPayload } from "./types.js";
+
+describe("EEClient feedback + touch fire-and-forget", () => {
+  let stub: StubHandle;
+  let ee: ReturnType<typeof createEEClient>;
+
+  beforeAll(async () => {
+    stub = await startStubEEServer({});
+    ee = createEEClient({ baseUrl: `http://localhost:${stub.port}` });
+  });
+
+  afterAll(async () => {
+    await stub.stop();
+  });
+
+  it("feedback() returns void synchronously; calls /api/feedback POST", async () => {
+    const payload: FeedbackPayload = {
+      principle_uuid: "P1",
+      classification: "FOLLOWED",
+      tool_name: "Edit",
+      duration_ms: 42,
+      tenantId: "local",
+    };
+    const result = ee.feedback(payload);
+    expect(result).toBeUndefined();
+
+    // Wait for fire-and-forget to land
+    await new Promise((r) => setTimeout(r, 50));
+    expect(stub.calls.feedback.length).toBe(1);
+    expect(stub.calls.feedback[0]).toMatchObject({
+      principle_uuid: "P1",
+      classification: "FOLLOWED",
+    });
+  });
+
+  it("touch() returns void synchronously; calls /api/principle/touch POST", async () => {
+    const result = ee.touch("P2", "local");
+    expect(result).toBeUndefined();
+
+    await new Promise((r) => setTimeout(r, 50));
+    expect(stub.calls.touch.length).toBe(1);
+    expect(stub.calls.touch[0]).toBe("P2");
+  });
+
+  it("feedback() never throws even on network error", () => {
+    const broken = createEEClient({
+      baseUrl: "http://localhost:1",
+      fetchImpl: vi.fn().mockRejectedValue(new Error("ECONNREFUSED")),
+    });
+    expect(() =>
+      broken.feedback({
+        principle_uuid: "X",
+        classification: "IGNORED",
+        tool_name: "Bash",
+        duration_ms: 0,
+        tenantId: "local",
+      }),
+    ).not.toThrow();
+  });
+
+  it("touch() never throws even on network error", () => {
+    const broken = createEEClient({
+      baseUrl: "http://localhost:1",
+      fetchImpl: vi.fn().mockRejectedValue(new Error("ECONNREFUSED")),
+    });
+    expect(() => broken.touch("X", "local")).not.toThrow();
+  });
+});

package/src/ee/types.ts

@@ -0,0 +1,322 @@
+/**
+ * EE HTTP client type contracts.
+ *
+ * These are the wire shapes sent to/received from the Experience Engine
+ * running at localhost:8082. The EE protocol deliberately excludes provider
+ * API keys — only toolName + toolInput + cwd cross the HTTP boundary (T-00.06-01).
+ *
+ * Phase 1 cross-phase changes:
+ *   EE-04: tenantId is REQUIRED on every request (single-tenant local = "local")
+ *   EE-05: Scope union required on InterceptRequest + PostToolPayload
+ *   EE-06: principle_uuid + embedding_model_version on every InterceptMatch
+ */
+
+export type Scope =
+  | { kind: "global" }
+  | { kind: "ecosystem"; name: string }
+  | { kind: "repo"; remote: string }
+  | { kind: "branch"; remote: string; branch: string };
+
+export interface InterceptRequest {
+  toolName: string;
+  toolInput: unknown;
+  cwd: string;
+  tenantId: string; // EE-04: required
+  scope: Scope; // EE-05: required
+}
+
+export interface InterceptMatch {
+  principle_uuid: string; // EE-06
+  embedding_model_version: string; // EE-06
+  confidence: number;
+  why: string;
+  message: string;
+  expectedBehavior?: string;
+  scope_label: string;
+  last_matched_at: string;
+}
+
+export interface InterceptResponse {
+  decision: "allow" | "block";
+  matches?: InterceptMatch[];
+  // back-compat aliases for Phase 0 internals — keep optional
+  suggestions?: string[];
+  surfacedIds?: string[];
+  reason?: string;
+}
+
+export interface PostToolPayload {
+  toolName: string;
+  toolInput: unknown;
+  outcome: {
+    success: boolean;
+    exitCode?: number;
+    durationMs?: number;
+    error?: string;
+  };
+  cwd: string;
+  tenantId: string; // EE-04: required
+  scope: Scope; // EE-05: required
+  surfacedIds?: string[];
+}
+
+// ─── P0: Route model types (aligned with EE server.js actual response) ────────
+export interface RouteModelRequest {
+  task: string;
+  tenantId: string;
+  cwd: string;
+  context?: {
+    projectSlug?: string;
+    phase?: string;
+    files?: string[];
+    domain?: string;
+    activeRun?: string;
+    localRoute?: { tier: string; confidence: number };
+    recentTurns?: string;
+    projectSize?: "small" | "medium" | "large";
+    filesTouched?: number;
+    mode?: string;
+  };
+  runtime?: "claude" | "gemini" | "codex" | "opencode";
+}
+
+export type RouteTier = "fast" | "balanced" | "premium";
+export type RouteSource = "default" | "keyword" | "history" | "history-upgrade" | "brain";
+
+export interface RouteModelResponse {
+  model: string;
+  tier: RouteTier;
+  confidence: number;
+  reason: string;
+  source: RouteSource;
+  taskHash: string;
+  reasoningEffort?: "low" | "medium" | "high";
+}
+
+export interface ColdRouteRequest {
+  task: string;
+  tenantId: string;
+  cwd: string;
+  context?: RouteModelRequest["context"];
+  runtime?: RouteModelRequest["runtime"];
+}
+
+export interface ColdRouteResponse {
+  model: string;
+  tier: RouteTier;
+  reason: string;
+  taskHash: string;
+}
+
+// ─── P0: Route feedback ──────────────────────────────────────────────────────
+export type RouteOutcome = "success" | "fail" | "retry" | "cancelled";
+
+export interface RouteFeedbackPayload {
+  taskHash: string;
+  outcome: RouteOutcome;
+  tier?: string | null;
+  model?: string | null;
+  retryCount?: number;
+  duration?: number | null;
+}
+
+// ─── Feedback + touch contract ───────────────────────────────────────────────
+export type Classification = "FOLLOWED" | "IGNORED" | "IRRELEVANT";
+
+export interface FeedbackPayload {
+  principle_uuid: string;
+  classification: Classification;
+  tool_name: string;
+  duration_ms: number;
+  tenantId: string;
+}
+
+// ─── P1: Prompt-stale reconciliation ─────────────────────────────────────────
+export interface PromptStaleRequest {
+  state: {
+    surfacedIds?: string[];
+    sessionId?: string;
+    timestamp?: string;
+  };
+  nextPromptMeta?: {
+    trigger: "compact" | "clear" | "auto-compact" | "session-end";
+    cwd?: string;
+    tenantId?: string;
+  };
+}
+
+export interface PromptStaleResponse {
+  ok: boolean;
+  unused: string[];
+  irrelevant: string[];
+  expired: string[];
+}
+
+// ─── P1: Session extract ─────────────────────────────────────────────────────
+export interface ExtractRequest {
+  transcript: string;
+  projectPath: string;
+  meta?: {
+    sessionId?: string;
+    tenantId?: string;
+    source?: "cli-exit" | "cli-clear" | "hook-stop";
+    scope?: string;
+  };
+}
+
+export interface ExtractResponse {
+  ok: boolean;
+  mistakes?: number;
+  stored?: number;
+}
+
+// ─── P2: Knowledge visibility ────────────────────────────────────────────────
+export interface EEStatsResponse {
+  totalIntercepts: number;
+  suggestions: number;
+  misses: number;
+  mistakesDetected?: number;
+  lessonsStored?: number;
+  extractSessions?: number;
+  evolution?: {
+    promoted: number;
+    demoted: number;
+    abstracted: number;
+    archived: number;
+  };
+  perProject?: Record<string, { intercepts: number; suggestions: number }>;
+  feedbackCounts?: Record<string, number>;
+  noiseCounts?: Record<string, number>;
+  costLedger?: Array<{ date: string; embed: number; brain: number; judge: number; extract: number }>;
+  routingStats?: {
+    byTier: Record<string, number>;
+    bySource: Record<string, number>;
+    outcomes: Record<string, number>;
+  };
+}
+
+export interface EEGraphEdge {
+  type: "generalizes" | "relates-to" | "supersedes" | "contradicts";
+  target: string;
+  weight: number;
+  direction: "incoming" | "outgoing";
+  createdAt: string;
+}
+
+export interface EEGraphResponse {
+  id: string;
+  edges: EEGraphEdge[];
+  count: number;
+}
+
+export interface EETimelineEntry {
+  id: string;
+  trigger: string;
+  solution: string;
+  tier: number;
+  confirmedAt: string[];
+  createdAt: string;
+  superseded?: boolean;
+  score: number;
+}
+
+export interface EETimelineResponse {
+  topic: string;
+  timeline: EETimelineEntry[];
+  count: number;
+}
+
+export interface EEGatesResponse {
+  gates: Array<{
+    name: string;
+    status: "pass" | "fail" | "partial";
+    checks: Array<{ label: string; ok: boolean; detail?: string }>;
+  }>;
+}
+
+export interface EEEvolveResponse {
+  success: boolean;
+  promoted?: number;
+  demoted?: number;
+  abstracted?: number;
+  archived?: number;
+}
+
+export interface EEShareResponse {
+  shared: unknown;
+  success: boolean;
+}
+
+export interface EEImportResponse {
+  imported: unknown;
+  success: boolean;
+}
+
+// ─── Task routing ────────────────────────────────────────────────────────────
+export interface RouteTaskRequest {
+  task: string;
+  context?: Record<string, unknown>;
+  runtime?: "claude" | "gemini" | "codex" | "opencode";
+}
+
+export interface RouteTaskOption {
+  id: string;
+  label: string;
+  route: string;
+  description: string;
+}
+
+export interface RouteTaskResponse {
+  route: "qc-flow" | "qc-lock" | "direct" | null;
+  confidence: number;
+  source: string;
+  reason: string;
+  needs_disambiguation: boolean;
+  options: RouteTaskOption[];
+  taskHash: string | null;
+}
+
+// ─── Semantic search ─────────────────────────────────────────────────────────
+export interface EESearchResult {
+  id: string;
+  score: number;
+  text: string;
+  collection: string;
+}
+
+export interface EESearchResponse {
+  points: EESearchResult[];
+}
+
+// ─── User identity ───────────────────────────────────────────────────────────
+export interface EEUserResponse {
+  user: string;
+}
+
+// ─── Client interface ────────────────────────────────────────────────────────
+export interface EEClient {
+  health(): Promise<{ ok: boolean; status: number }>;
+  intercept(req: InterceptRequest): Promise<InterceptResponse>;
+  posttool(payload: PostToolPayload): Promise<void>;
+  routeModel(req: RouteModelRequest, signal?: AbortSignal): Promise<RouteModelResponse | null>;
+  coldRoute(req: ColdRouteRequest, signal?: AbortSignal): Promise<ColdRouteResponse | null>;
+  feedback(payload: FeedbackPayload): void;
+  touch(principle_uuid: string, tenantId: string): void;
+  // P0: Route feedback
+  routeFeedback(payload: RouteFeedbackPayload): void;
+  // P1: Prompt-stale + extract
+  promptStale(req: PromptStaleRequest): Promise<PromptStaleResponse | null>;
+  extract(req: ExtractRequest, signal?: AbortSignal): Promise<ExtractResponse | null>;
+  // P2: Knowledge visibility
+  stats(since?: string): Promise<EEStatsResponse | null>;
+  graph(id: string): Promise<EEGraphResponse | null>;
+  timeline(topic: string): Promise<EETimelineResponse | null>;
+  gates(): Promise<EEGatesResponse | null>;
+  evolve(trigger?: string): Promise<EEEvolveResponse | null>;
+  sharePrinciple(principleId: string): Promise<EEShareResponse | null>;
+  importPrinciple(data: unknown): Promise<EEImportResponse | null>;
+  // Task routing + search + user
+  routeTask(req: RouteTaskRequest): Promise<RouteTaskResponse | null>;
+  search(query: string, limit?: number): Promise<EESearchResponse | null>;
+  user(): Promise<EEUserResponse | null>;
+}

package/src/flow/__tests__/migration.test.ts

@@ -0,0 +1,133 @@
+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 { detectLegacyFlow, migrateQuickCodexFlow } from "../migration.js";
+
+describe("migration", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "flow-migrate-"));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  describe("detectLegacyFlow", () => {
+    it("returns true when .quick-codex-flow/ exists", async () => {
+      await fs.mkdir(path.join(tmpDir, ".quick-codex-flow"), { recursive: true });
+      expect(await detectLegacyFlow(tmpDir)).toBe(true);
+    });
+
+    it("returns false when .quick-codex-flow/ does not exist", async () => {
+      expect(await detectLegacyFlow(tmpDir)).toBe(false);
+    });
+  });
+
+  describe("migrateQuickCodexFlow", () => {
+    it("copies STATE.md -> state.md, PROJECT-ROADMAP.md -> roadmap.md, BACKLOG.md -> backlog.md", async () => {
+      const qcDir = path.join(tmpDir, ".quick-codex-flow");
+      await fs.mkdir(qcDir, { recursive: true });
+      await fs.writeFile(path.join(qcDir, "STATE.md"), "## Active Run\n\nmy-run", "utf8");
+      await fs.writeFile(path.join(qcDir, "PROJECT-ROADMAP.md"), "## Milestones\n\nv1.0", "utf8");
+      await fs.writeFile(path.join(qcDir, "BACKLOG.md"), "## Deferred\n\nitem 1", "utf8");
+
+      await migrateQuickCodexFlow(tmpDir);
+
+      const flowDir = path.join(tmpDir, ".muonroi-flow");
+      const state = await fs.readFile(path.join(flowDir, "state.md"), "utf8");
+      expect(state).toContain("my-run");
+
+      const roadmap = await fs.readFile(path.join(flowDir, "roadmap.md"), "utf8");
+      expect(roadmap).toContain("v1.0");
+
+      const backlog = await fs.readFile(path.join(flowDir, "backlog.md"), "utf8");
+      expect(backlog).toContain("item 1");
+    });
+
+    it("splits monolithic QC run file into runs/<id>/{roadmap,state,delegations,gray-areas}.md", async () => {
+      const qcDir = path.join(tmpDir, ".quick-codex-flow");
+      await fs.mkdir(qcDir, { recursive: true });
+      // Top-level files needed for migration not to fail
+      await fs.writeFile(path.join(qcDir, "STATE.md"), "", "utf8");
+      await fs.writeFile(path.join(qcDir, "PROJECT-ROADMAP.md"), "", "utf8");
+      await fs.writeFile(path.join(qcDir, "BACKLOG.md"), "", "utf8");
+
+      // Monolithic run file
+      const runContent = [
+        "## Delivery Roadmap\n\nPhase 1 done",
+        "## Resume Digest\n\nLast worked on X",
+        "## Experience Snapshot\n\nLearned Y",
+        "## Delegation State\n\nAgent A owns task 1",
+        "## Gray Area Register\n\nG1: unclear requirement",
+        "## Decision Register\n\nD1: chose option A",
+      ].join("\n\n");
+      await fs.writeFile(path.join(qcDir, "my-feature-run.md"), runContent, "utf8");
+
+      const result = await migrateQuickCodexFlow(tmpDir);
+      expect(result.runsCreated).toBe(1);
+
+      const flowDir = path.join(tmpDir, ".muonroi-flow");
+
+      // Find the created run directory
+      const runs = await fs.readdir(path.join(flowDir, "runs"));
+      expect(runs.length).toBe(1);
+      const runDir = path.join(flowDir, "runs", runs[0]);
+
+      const roadmap = await fs.readFile(path.join(runDir, "roadmap.md"), "utf8");
+      expect(roadmap).toContain("Phase 1 done");
+
+      const state = await fs.readFile(path.join(runDir, "state.md"), "utf8");
+      expect(state).toContain("Last worked on X");
+      expect(state).toContain("Learned Y");
+
+      const delegations = await fs.readFile(path.join(runDir, "delegations.md"), "utf8");
+      expect(delegations).toContain("Agent A owns task 1");
+
+      const grayAreas = await fs.readFile(path.join(runDir, "gray-areas.md"), "utf8");
+      expect(grayAreas).toContain("unclear requirement");
+
+      // Decision Register appended to top-level decisions.md
+      const decisions = await fs.readFile(path.join(flowDir, "decisions.md"), "utf8");
+      expect(decisions).toContain("chose option A");
+    });
+
+    it("preserves unknown sections as-is in state.md (tolerant)", async () => {
+      const qcDir = path.join(tmpDir, ".quick-codex-flow");
+      await fs.mkdir(qcDir, { recursive: true });
+      await fs.writeFile(path.join(qcDir, "STATE.md"), "", "utf8");
+      await fs.writeFile(path.join(qcDir, "PROJECT-ROADMAP.md"), "", "utf8");
+      await fs.writeFile(path.join(qcDir, "BACKLOG.md"), "", "utf8");
+
+      const runContent = ["## Resume Digest\n\nresume info", "## Custom Unknown Section\n\ncustom content here"].join(
+        "\n\n",
+      );
+      await fs.writeFile(path.join(qcDir, "custom-run.md"), runContent, "utf8");
+
+      await migrateQuickCodexFlow(tmpDir);
+
+      const flowDir = path.join(tmpDir, ".muonroi-flow");
+      const runs = await fs.readdir(path.join(flowDir, "runs"));
+      const state = await fs.readFile(path.join(flowDir, "runs", runs[0], "state.md"), "utf8");
+      expect(state).toContain("custom content here");
+    });
+
+    it("does NOT delete original .quick-codex-flow/ after migration", async () => {
+      const qcDir = path.join(tmpDir, ".quick-codex-flow");
+      await fs.mkdir(qcDir, { recursive: true });
+      await fs.writeFile(path.join(qcDir, "STATE.md"), "original", "utf8");
+      await fs.writeFile(path.join(qcDir, "PROJECT-ROADMAP.md"), "", "utf8");
+      await fs.writeFile(path.join(qcDir, "BACKLOG.md"), "", "utf8");
+
+      await migrateQuickCodexFlow(tmpDir);
+
+      // Original still exists
+      const stat = await fs.stat(qcDir);
+      expect(stat.isDirectory()).toBe(true);
+      const content = await fs.readFile(path.join(qcDir, "STATE.md"), "utf8");
+      expect(content).toBe("original");
+    });
+  });
+});