mirror-mind 0.0.1 → 0.33.0

package/ts/src/builder/templateGeneration.ts

@@ -0,0 +1,148 @@
+// CV22.DS7.US8 plateau 2 — method template preparation.
+//
+// Port of `src/memory/builder/template_generation.py`. This is the one command in
+// the plateau that writes into the USER's repository: nine files under
+// `docs/project/roadmap/`, whose bytes are the template bodies transcribed in
+// `ariadMethod.ts` and graded by deep equality there.
+//
+// The rule that makes it safe to re-run is `if target.exists()` — an existing file
+// is PRESERVED, never overwritten, and reported as such. A port that writes
+// unconditionally would silently replace a Navigator's authored `plan.md` with the
+// blank template, which is the worst defect available in this story: destructive,
+// silent, and in someone else's git history.
+//
+// Confinement is checked after resolution (`is_relative_to(root)`), so a template
+// path that escapes the project root raises instead of writing. Today no declared
+// template can trigger it — `validateMethodDefinition` already rejects an absolute
+// path or a `..` component — but the guard is the second of the two, and it is the
+// one that survives a DSL edited by hand after DS10.
+
+import { relative, resolve } from "node:path";
+import { writeBuilderArtifact } from "./artifacts/artifactWriter.ts";
+import type { MethodDefinition, TemplateDefinition } from "./methodDefinition.ts";
+import { projectFolder } from "./projectPaths.ts";
+
+/** Python `PENDING_TEMPLATE_PREPARATION_ITEMS`. */
+export const PENDING_TEMPLATE_PREPARATION_ITEMS = [
+  "runtime delivery cursor sync",
+  "active roadmap item resolution",
+  "story lifecycle execution",
+  "project/journey override merge",
+  "release and push policy enforcement",
+] as const;
+
+/** Python `TemplateWriteResult`. */
+export interface TemplateWriteResult {
+  readonly id: string;
+  readonly path: string;
+  readonly action: "created" | "preserved";
+  readonly description: string | null;
+}
+
+/** Python `BuilderTemplatePreparation`. */
+export interface BuilderTemplatePreparation {
+  readonly journey: string;
+  /** The project's folder, named beside the journey (CR009). */
+  readonly project: string;
+  readonly method: string;
+  readonly checked: readonly string[];
+  readonly created: readonly TemplateWriteResult[];
+  readonly preserved: readonly TemplateWriteResult[];
+  readonly pending: readonly string[];
+}
+
+/** Python `_target_path`, including the escape guard. */
+function targetPath(root: string, template: TemplateDefinition): string {
+  const target = resolve(root, template.path);
+  const relation = relative(root, target);
+  if (relation.startsWith("..") || resolve(relation) === relation) {
+    throw new Error(`template path escapes project root: ${template.path}`);
+  }
+  return target;
+}
+
+/**
+ * Python `prepare_method_templates`.
+ *
+ * `checked` accumulates EVERY template path, in declaration order, whether or not
+ * it was written — so the report distinguishes "looked at nine, created two,
+ * preserved seven" from "only saw two".
+ */
+export function prepareMethodTemplates(
+  projectPath: string,
+  options: { journey: string; method: MethodDefinition },
+): BuilderTemplatePreparation {
+  const root = resolve(projectPath);
+  const created: TemplateWriteResult[] = [];
+  const preserved: TemplateWriteResult[] = [];
+  const checked: string[] = [];
+
+  for (const template of options.method.templates) {
+    const target = targetPath(root, template);
+    checked.push(template.path);
+    // A template is a scaffold: written where absent, and the Driver's from then on.
+    const outcome = writeBuilderArtifact({
+      path: target,
+      content: template.content,
+      policy: "create-only",
+      projectRoot: root,
+    });
+    const result: TemplateWriteResult = {
+      id: template.id,
+      path: template.path,
+      action: outcome === "existing" ? "preserved" : "created",
+      description: template.description ?? null,
+    };
+    (outcome === "existing" ? preserved : created).push(result);
+  }
+
+  return {
+    journey: options.journey,
+    project: projectFolder(projectPath),
+    method: options.method.id,
+    checked,
+    created,
+    preserved,
+    pending: [...PENDING_TEMPLATE_PREPARATION_ITEMS],
+  };
+}
+
+/** Python `_format_paths` / `_format_results`: the PATH, not the id. */
+function formatPaths(paths: readonly string[]): string[] {
+  return paths.length > 0 ? [...paths] : ["none"];
+}
+
+function formatResults(results: readonly TemplateWriteResult[]): string[] {
+  return results.length > 0 ? results.map((result) => result.path) : ["none"];
+}
+
+/** Python `render_template_preparation_report`: plain text, no card frame. */
+export function renderTemplatePreparationReport(report: BuilderTemplatePreparation): string {
+  return `${[
+    "■ Ariad Template Preparation",
+    "",
+    "journey",
+    report.journey,
+    "",
+    "project",
+    report.project,
+    "",
+    "method",
+    report.method,
+    "",
+    "checked",
+    ...formatPaths(report.checked),
+    "",
+    "created",
+    ...formatResults(report.created),
+    "",
+    "preserved",
+    ...formatResults(report.preserved),
+    "",
+    "pending",
+    ...report.pending,
+    "",
+    "boundary",
+    "No story lifecycle work was executed.",
+  ].join("\n")}\n`;
+}

package/ts/src/builder/transition.ts

@@ -0,0 +1,178 @@
+// CV22.DS7.US8 plateau 7 — the ■ BUILDER MODE ACTIVE card and `load`'s query.
+//
+// Ports `render_builder_mode_transition` and its private helpers from
+// `src/memory/surfaces/mode_transition.py`, plus `_extract_query` from
+// `cli/build.py`.
+//
+// `_box` / `_line` / `_wrap` are character-identical to the Explorer card's
+// (`explorer/transition.ts`), and that is not an accident worth deduplicating
+// away: they are the SAME Python module, so sharing them here is correct where
+// sharing them with the story cards in `render.ts` would not be — those chunk
+// over-long words, these truncate. The duplication stays inside the module that
+// owns each oracle.
+//
+// Three behaviors this file reproduces that a reasonable port would fix:
+//
+//   1. **`_extract_query` tests every LINE, not only headings**, and a match
+//      `continue`s — so a body line containing `context` is silently DROPPED from
+//      the query while the lines around it survive. Harmless in a long
+//      description, fatal in a short one: a body whose only line mentions the word
+//      captures nothing and the query becomes the slug.
+//   2. **No Unicode normalization.** The Portuguese section names are compared as
+//      literals, so an NFD `Descrição` does not match the NFC list and the query
+//      falls back to the slug. Adding `.normalize("NFC")` here would fix the
+//      defect and break parity; it is a CR instead.
+//   3. **`[:500]` is code points**, not UTF-16 units. A briefing of astral
+//      characters cut with `slice(0, 500)` loses half the text, changing the
+//      embedding and therefore the ranking, with no error.
+
+import { codePointLength, pySplitWhitespace, sliceCodePoints } from "#util/pythonText.ts";
+
+const WIDTH = 56;
+
+/** `mode_transition._line`: slice to WIDTH, then pad — both by code point. */
+function line(text: string): string {
+  const content = sliceCodePoints(text, WIDTH);
+  return `│${content.padEnd(WIDTH + (content.length - codePointLength(content)))}│`;
+}
+
+/** `mode_transition._wrap`: greedy fill at WIDTH-2, long words NOT chunked. */
+function wrap(text: string): string[] {
+  const maxWidth = WIDTH - 2;
+  const words = pySplitWhitespace(text);
+  if (words.length === 0) return [""];
+  const lines: string[] = [];
+  let current = words[0] as string;
+  for (const word of words.slice(1)) {
+    if (codePointLength(current) + 1 + codePointLength(word) <= maxWidth) {
+      current = `${current} ${word}`;
+    } else {
+      lines.push(current);
+      current = word;
+    }
+  }
+  lines.push(current);
+  return lines;
+}
+
+type Row = readonly [label: string, value: string];
+
+/** `mode_transition._box`. */
+function box(title: string, rows: readonly Row[]): string {
+  const lines = ["Mirror", `╭${"─".repeat(WIDTH)}╮`, line(`        ${title}`)];
+  for (const [label, value] of rows) {
+    lines.push(line(""));
+    lines.push(line(`  ${label}`));
+    for (const wrapped of wrap(value)) lines.push(line(`  ${wrapped}`));
+  }
+  lines.push(`╰${"─".repeat(WIDTH)}╯`);
+  return lines.join("\n");
+}
+
+/**
+ * `mode_transition._extract_stage`.
+ *
+ * `^\*\*Stage:\*\*\s*(.+)$` under `re.MULTILINE`. Written with explicit anchors
+ * because JavaScript's `m` flag also anchors at U+2028/U+2029 where Python's does
+ * not, and `.` must not cross a newline in either.
+ */
+const STAGE_RE = /(?<=^|\n)\*\*Stage:\*\*[^\S\n]*(?<stage>[^\n]+)(?=\n|$)/u;
+
+export function extractStage(content: string): string | null {
+  const match = STAGE_RE.exec(content);
+  const stage = match?.groups?.stage;
+  return stage === undefined ? null : stage.trim();
+}
+
+/**
+ * `mode_transition._extract_section`.
+ *
+ * Capture starts at the first heading whose text contains one of `names`, and ends
+ * at the NEXT heading. When nothing was captured it falls back to every non-heading
+ * line joined and cut at 240 — a port that returns `null` there renders a card with
+ * no briefing row, which is the row a Navigator reads first.
+ */
+export function extractSection(content: string, names: readonly string[]): string | null {
+  const lines = content.split("\n");
+  let capturing = false;
+  const result: string[] = [];
+  for (const raw of lines) {
+    const stripped = raw.trim();
+    const header = stripped.replace(/^#+/u, "").trim().toLowerCase();
+    if (stripped.startsWith("#")) {
+      if (capturing) break;
+      if (names.some((name) => header.includes(name))) {
+        capturing = true;
+      }
+    } else if (capturing) {
+      result.push(stripped);
+    }
+  }
+  const text = result
+    .filter((entry) => entry !== "")
+    .join(" ")
+    .trim();
+  if (text) return text;
+  const fallback = lines
+    .filter((entry) => entry.trim() !== "" && !entry.startsWith("#"))
+    .map((entry) => entry.trim())
+    .join(" ");
+  return sliceCodePoints(fallback, 240).trim() || null;
+}
+
+/** `mode_transition._truncate_words`. */
+export function truncateWords(text: string, limit: number): string {
+  const words = pySplitWhitespace(text);
+  if (words.length <= limit) return text;
+  // Python `rstrip(".,;")` strips a SET of characters, not a suffix.
+  return `${words
+    .slice(0, limit)
+    .join(" ")
+    .replace(/[.,;]+$/u, "")}…`;
+}
+
+/** Python `render_builder_mode_transition`. */
+export function renderBuilderModeTransition(options: {
+  journey: string;
+  journeyContent: string;
+  projectPath?: string | null;
+}): string {
+  const rows: Row[] = [["active journey", options.journey]];
+  const stage = extractStage(options.journeyContent);
+  if (stage) rows.push(["journey path", stage]);
+  if (options.projectPath) rows.push(["project path", options.projectPath]);
+  const briefing = extractSection(options.journeyContent, ["briefing", "description", "context"]);
+  if (briefing) rows.push(["briefing", truncateWords(briefing, 32)]);
+  rows.push(["boundary", "Builder executes commitment."]);
+  return box("■  BUILDER MODE ACTIVE", rows);
+}
+
+/** The five section names `_extract_query` accepts, NFC as Python writes them. */
+const QUERY_SECTIONS = ["description", "briefing", "context", "descrição", "contexto"] as const;
+
+/**
+ * Python `cli/build._extract_query`.
+ *
+ * Note what this is NOT: it is not `extractSection` with different names. The
+ * match runs against every line, a matching line is SKIPPED rather than captured,
+ * and the fallback is the slug rather than a 240-character digest. Two extractors,
+ * two behaviors, over the same document — reproduced separately because merging
+ * them changes both.
+ */
+export function extractQuery(journeyContent: string, slug: string): string {
+  const result: string[] = [];
+  let capturing = false;
+  for (const raw of journeyContent.split("\n")) {
+    const header = raw.replace(/^#+/u, "").trim().toLowerCase();
+    if (QUERY_SECTIONS.some((section) => header.includes(section))) {
+      capturing = true;
+      continue;
+    }
+    if (capturing) {
+      if (raw.startsWith("#")) break;
+      result.push(raw);
+    }
+  }
+  const text = result.join(" ").trim();
+  return text ? sliceCodePoints(text, 500) : slug;
+}

package/ts/src/consult/args.ts

@@ -0,0 +1,99 @@
+import { isConsultTier, resolveConsultModel } from "./modelCatalog.ts";
+
+export type ConsultParseResult = ConsultCreditsCommand | ConsultAskCommand;
+
+export interface ConsultCreditsCommand {
+  command: "credits";
+}
+
+export interface ConsultAskCommand {
+  command: "ask";
+  modelId: string;
+  prompt: string;
+  persona: string | null;
+  journey: string | null;
+  org: boolean;
+  query: string | null;
+  mirrorHome: string | null;
+}
+
+export class ConsultArgError extends Error {}
+
+export const CONSULT_USAGE =
+  "Usage: consult <family> [tier] [question] [--persona P] [--journey J] [--org]\n" +
+  "     consult credits";
+
+export function parseConsultArgs(argv: readonly string[]): ConsultParseResult {
+  if (argv.length === 0) {
+    throw new ConsultArgError(CONSULT_USAGE);
+  }
+  if (argv[0] === "credits") {
+    return { command: "credits" };
+  }
+
+  let persona: string | null = null;
+  let journey: string | null = null;
+  let org = false;
+  let query: string | null = null;
+  let mirrorHome: string | null = null;
+  const positional: string[] = [];
+
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    const next = argv[i + 1];
+    if (arg === "--persona" && next !== undefined) {
+      persona = next;
+      i += 2;
+    } else if (arg === "--journey" && next !== undefined) {
+      journey = next;
+      i += 2;
+    } else if (arg === "--query" && next !== undefined) {
+      query = next;
+      i += 2;
+    } else if (arg === "--mirror-home" && next !== undefined) {
+      mirrorHome = next;
+      i += 2;
+    } else if (arg === "--org") {
+      org = true;
+      i += 1;
+    } else {
+      positional.push(arg);
+      i += 1;
+    }
+  }
+
+  if (positional.length === 0) {
+    throw new ConsultArgError("Error: model family is required.");
+  }
+
+  const family = positional[0] ?? "";
+  let tier = "lite";
+  let prompt: string | null = null;
+
+  if (positional.length === 1) {
+    throw new ConsultArgError("Error: question is required.");
+  }
+  if (positional.length === 2) {
+    if (isConsultTier(positional[1] ?? "")) {
+      throw new ConsultArgError("Error: question is required.");
+    }
+    prompt = positional[1] ?? "";
+  } else if (isConsultTier(positional[1] ?? "")) {
+    tier = positional[1] ?? "lite";
+    prompt = positional.slice(2).join(" ");
+  } else {
+    prompt = positional.slice(1).join(" ");
+  }
+
+  return {
+    command: "ask",
+    modelId: resolveConsultModel(family, tier),
+    prompt,
+    persona,
+    journey,
+    org,
+    query,
+    mirrorHome,
+  };
+}

package/ts/src/consult/core.ts

@@ -0,0 +1,122 @@
+import type { WritableDatabase } from "#db/database.ts";
+import { logLlmCall } from "#observability/llmCalls.ts";
+import { computeCost } from "#providers/cost.ts";
+import type { CreditProvider } from "#providers/credits.ts";
+import type { LlmMessage, LlmProvider, LlmRequest } from "#providers/llm.ts";
+import { pythonJsonDumps } from "#util/pyGenerators.ts";
+import type { ConsultAskCommand, ConsultCreditsCommand, ConsultParseResult } from "./args.ts";
+import { renderConsultAsk, renderCredits } from "./render.ts";
+
+export const SYSTEM_PREAMBLE = `You are the user's Mirror, as described in the context below. Answer in first person, as the user.
+Respect the vocabulary, tone, and philosophy described in the identity context.
+
+`;
+
+export interface ConsultContextRequest {
+  persona: string | null;
+  journey: string | null;
+  org: boolean;
+  query: string | null;
+  mirrorHome: string | null;
+}
+
+export type ConsultContextLoader = (request: ConsultContextRequest) => Promise<string> | string;
+
+export interface RunConsultOptions {
+  llm: LlmProvider;
+  credits: CreditProvider;
+  loadContext: ConsultContextLoader;
+  /** Optional: when provided, `ask` logs to the llm_calls ledger with the
+   * real fetched cost (AI-09). Omitted by existing/credits-only callers with
+   * no behavior change -- logging is simply skipped. */
+  db?: WritableDatabase;
+}
+
+export async function runConsult(
+  command: ConsultParseResult,
+  options: RunConsultOptions,
+): Promise<string> {
+  if (command.command === "credits") {
+    return runConsultCredits(command, options);
+  }
+  return runConsultAsk(command, options);
+}
+
+export async function runConsultCredits(
+  _command: ConsultCreditsCommand,
+  options: RunConsultOptions,
+): Promise<string> {
+  return renderCredits(await options.credits.getCredits());
+}
+
+export async function runConsultAsk(
+  command: ConsultAskCommand,
+  options: RunConsultOptions,
+): Promise<string> {
+  const context = await options.loadContext({
+    persona: command.persona,
+    journey: command.journey,
+    org: command.org,
+    query: command.query,
+    mirrorHome: command.mirrorHome,
+  });
+  const request = buildConsultLlmRequest(command.modelId, command.prompt, context);
+  const response = await options.llm.complete(request);
+  const cost = response.generationId
+    ? await options.credits.fetchGenerationCost(response.generationId)
+    : null;
+  const credits = await options.credits.getCredits();
+  if (options.db) {
+    // Consult joins the ledger with its real fetched cost (AI-09). When the
+    // poll comes back empty, Python does NOT store null -- `build_llm_logger`
+    // falls through to `compute_cost`, so the row says "estimated" where this
+    // used to say "unknown". Most of consult's models are outside the price
+    // table and estimate to null anyway, but the two engines must mean the
+    // same thing by a null (CV22.DS8.US3 plan review, database-architect).
+    const model = response.model ?? command.modelId;
+    logLlmCall(options.db, {
+      role: "consult",
+      model,
+      prompt: request.prompt,
+      response: response.content,
+      promptTokens: response.promptTokens,
+      completionTokens: response.completionTokens,
+      latencyMs: response.latencyMs,
+      costUsd:
+        cost ??
+        computeCost(model, response.promptTokens ?? null, response.completionTokens ?? null),
+    });
+  }
+  return renderConsultAsk(command.modelId, response, credits, cost);
+}
+
+/**
+ * Python's `cmd_ask` envelope: a system message carrying the preamble and the
+ * Mirror context, then the user's question.
+ *
+ * `messages` is what leaves for the provider; `prompt` is the same envelope
+ * serialized exactly as Python serializes it (`json.dumps(messages,
+ * ensure_ascii=False)` inside `send_to_model`), because that string is what
+ * the replay transport resolves against and what the ledger's `prompt` column
+ * holds under `MEMORY_LOG_LLM_CALLS=full`. `JSON.stringify` was close enough
+ * to read but not to compare: it omits the space after `,` and `:` that
+ * Python writes, so the two engines recorded different bytes for the same
+ * call in a column both of them read (CV22.DS8.US3 plan review,
+ * database-architect).
+ */
+export function buildConsultLlmRequest(
+  modelId: string,
+  prompt: string,
+  context: string,
+): LlmRequest {
+  const messages: LlmMessage[] = [
+    { role: "system", content: SYSTEM_PREAMBLE + context },
+    { role: "user", content: prompt },
+  ];
+  return {
+    role: "consult",
+    model: modelId,
+    messages,
+    prompt: pythonJsonDumps(messages),
+  };
+}

package/ts/src/consult/modelCatalog.ts

@@ -0,0 +1,55 @@
+export type ConsultTier = "lite" | "mid" | "flagship";
+
+export const CONSULT_TIERS = ["lite", "mid", "flagship"] as const;
+
+export const LLM_FAMILIES: Record<string, Record<ConsultTier, string>> = {
+  claude: {
+    lite: "anthropic/claude-haiku-4.5",
+    mid: "anthropic/claude-sonnet-4.6",
+    flagship: "anthropic/claude-opus-4.6",
+  },
+  deepseek: {
+    lite: "deepseek/deepseek-chat",
+    mid: "deepseek/deepseek-v3.2",
+    flagship: "deepseek/deepseek-r1",
+  },
+  gemini: {
+    lite: "google/gemini-2.5-flash-lite",
+    mid: "google/gemini-2.5-flash",
+    flagship: "google/gemini-2.5-pro",
+  },
+  grok: {
+    lite: "x-ai/grok-3-mini",
+    mid: "x-ai/grok-3",
+    flagship: "x-ai/grok-4.1-fast",
+  },
+  llama: {
+    lite: "meta-llama/llama-3.3-70b-instruct",
+    mid: "meta-llama/llama-4-scout",
+    flagship: "meta-llama/llama-4-maverick",
+  },
+  openai: {
+    lite: "openai/gpt-5.4-nano",
+    mid: "openai/gpt-5.4-mini",
+    flagship: "openai/gpt-5.4",
+  },
+};
+
+export function isConsultTier(value: string): value is ConsultTier {
+  return value === "lite" || value === "mid" || value === "flagship";
+}
+
+export function resolveConsultModel(family: string, tier = "mid"): string {
+  if (family.includes("/")) return family;
+  const familyLower = family.toLowerCase();
+  const tiers = LLM_FAMILIES[familyLower];
+  if (!tiers) {
+    const available = Object.keys(LLM_FAMILIES).sort().join(", ");
+    throw new Error(`Family '${family}' not found. Available: ${available}`);
+  }
+  const tierLower = tier.toLowerCase();
+  if (!isConsultTier(tierLower)) {
+    throw new Error(`Tier '${tier}' does not exist for '${family}'. Use: lite, mid, flagship`);
+  }
+  return tiers[tierLower];
+}

package/ts/src/consult/render.ts

@@ -0,0 +1,47 @@
+import type { LlmResponse } from "#providers/llm.ts";
+
+export const USD_TO_BRL = 5.7;
+export const BALANCE_BAR_WIDTH = 20;
+
+export interface CreditInfo {
+  totalCredits: number;
+  totalUsage: number;
+  balance: number;
+}
+
+export function renderCredits(info: CreditInfo): string {
+  const balanceBrl = info.balance * USD_TO_BRL;
+  const fill =
+    info.totalCredits > 0 ? Math.trunc((BALANCE_BAR_WIDTH * info.balance) / info.totalCredits) : 0;
+  const bar = "▓".repeat(fill) + "░".repeat(BALANCE_BAR_WIDTH - fill);
+  return `Balance: openrouter: ${bar} R$ ${balanceBrl.toFixed(2)}`;
+}
+
+export function renderConsultAsk(
+  requestedModel: string,
+  response: LlmResponse,
+  credits: CreditInfo,
+  cost: number | null = null,
+): string {
+  const lines = [
+    `Consulting ${requestedModel}...`,
+    `--- response via ${response.model ?? requestedModel} ---`,
+    response.content,
+    "--- end ---",
+  ];
+  const costParts: string[] = [];
+  if (response.promptTokens) costParts.push(`prompt: ${response.promptTokens}`);
+  if (response.completionTokens) costParts.push(`completion: ${response.completionTokens}`);
+  if (costParts.length > 0) lines.push(`[${costParts.join(", ")}]`);
+  if (cost !== null) lines.push(renderCost(cost));
+  lines.push(renderCredits(credits));
+  return lines.join("\n");
+}
+
+export function renderCost(totalCost: number): string {
+  const costBrl = totalCost * USD_TO_BRL;
+  if (totalCost < 0.01) {
+    return `Call cost: $${totalCost.toFixed(6)} (R$ ${costBrl.toFixed(4)})`;
+  }
+  return `Call cost: $${totalCost.toFixed(4)} (R$ ${costBrl.toFixed(2)})`;
+}