march-cli 0.1.0

package/src/config/loader.mjs

@@ -0,0 +1,109 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Priority (last wins):
+ *   1. ~/.march/config — legacy global defaults
+ *   2. ~/.march/config.json — global config
+ *   3. <cwd>/.marchrc — legacy project overrides
+ *   4. <cwd>/.march/config — legacy project dir overrides
+ *   5. <cwd>/.march/config.json — project config
+ * Scalar values override.
+ */
+export function loadConfig(cwd, { homeDir = homedir() } = {}) {
+  const layers = [];
+
+  // 1. Global config: ~/.march/config
+  const globalPath = join(homeDir, ".march", "config");
+  layers.push(loadJson(globalPath));
+
+  layers.push(loadJson(join(homeDir, ".march", "config.json")));
+
+  // 2. Project config: <cwd>/.marchrc
+  layers.push(loadJson(join(cwd, ".marchrc")));
+
+  // 3. Project dir config: <cwd>/.march/config
+  layers.push(loadJson(join(cwd, ".march", "config")));
+  layers.push(loadJson(join(cwd, ".march", "config.json")));
+
+  return mergeLayers(layers);
+}
+
+function loadJson(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function mergeLayers(layers) {
+  const result = {
+    model: null,
+    provider: null,
+    serviceTier: null,
+    providers: {},
+    webSearch: { provider: null, providers: {} },
+    maxTurns: null,
+    trimBatch: null,
+    memoryRoot: null,
+    notifications: { turnEnd: false },
+  };
+
+  for (const layer of layers) {
+    if (!layer) continue;
+    if (layer.model != null) result.model = layer.model;
+    if (layer.provider) result.provider = layer.provider;
+    if (layer.serviceTier) result.serviceTier = layer.serviceTier;
+    if (layer.providers && typeof layer.providers === "object" && !Array.isArray(layer.providers)) {
+      result.providers = mergeProviders(result.providers, layer.providers);
+    }
+    if (layer.webSearch && typeof layer.webSearch === "object" && !Array.isArray(layer.webSearch)) {
+      result.webSearch = mergeWebSearch(result.webSearch, layer.webSearch);
+    }
+    if (layer.notifications && typeof layer.notifications === "object" && !Array.isArray(layer.notifications)) {
+      result.notifications = {
+        ...result.notifications,
+        ...layer.notifications,
+      };
+    }
+    if (layer.memoryRoot) result.memoryRoot = layer.memoryRoot;
+  }
+
+  return result;
+}
+
+function mergeWebSearch(current, next) {
+  const merged = {
+    provider: next.provider ?? current.provider ?? null,
+    providers: { ...(current.providers ?? {}) },
+  };
+  if (next.providers && typeof next.providers === "object" && !Array.isArray(next.providers)) {
+    for (const [id, profile] of Object.entries(next.providers)) {
+      if (!profile || typeof profile !== "object" || Array.isArray(profile)) continue;
+      merged.providers[id] = {
+        ...(merged.providers[id] ?? {}),
+        ...profile,
+      };
+    }
+  }
+  return merged;
+}
+
+function mergeProviders(current, next) {
+  const merged = { ...current };
+  for (const [id, profile] of Object.entries(next)) {
+    if (!profile || typeof profile !== "object" || Array.isArray(profile)) continue;
+    merged[id] = {
+      ...(merged[id] ?? {}),
+      ...profile,
+      auth: {
+        ...(merged[id]?.auth ?? {}),
+        ...(profile.auth ?? {}),
+      },
+    };
+  }
+  return merged;
+}

package/src/config/settings-command.mjs

@@ -0,0 +1,97 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { loadConfig } from "./loader.mjs";
+
+const WRITABLE_KEYS = new Set(["memoryRoot"]);
+const SCOPES = new Set(["global", "project"]);
+
+export function parseSettingsCommand(input) {
+  if (input !== "/settings" && !input.startsWith("/settings ")) return { type: "none" };
+  const arg = input.slice("/settings".length).trim();
+  if (!arg) return { type: "view" };
+
+  const setMatch = arg.match(/^set\s+(global|project)\s+(memoryRoot)\s+(.+)$/);
+  if (setMatch) {
+    return { type: "set", scope: setMatch[1], key: setMatch[2], value: setMatch[3].trim() };
+  }
+
+  const unsetMatch = arg.match(/^unset\s+(global|project)\s+(memoryRoot)$/);
+  if (unsetMatch) {
+    return { type: "unset", scope: unsetMatch[1], key: unsetMatch[2] };
+  }
+
+  return { type: "error", message: "Usage: /settings [set <global|project> memoryRoot <value> | unset <global|project> memoryRoot]" };
+}
+
+export function handleSettingsCommand(command, { cwd = process.cwd(), homeDir = homedir() } = {}) {
+  if (command.type === "view") return formatSettingsView({ cwd, homeDir });
+  if (command.type === "error") return [`Error: ${command.message}`];
+  if (!SCOPES.has(command.scope) || !WRITABLE_KEYS.has(command.key)) {
+    return ["Error: unsupported settings scope or key"];
+  }
+
+  const path = settingsPathForScope(command.scope, { cwd, homeDir });
+  const data = readSettingsFile(path);
+  if (command.type === "set") {
+    data[command.key] = command.value;
+  } else if (command.type === "unset") {
+    delete data[command.key];
+  }
+  writeSettingsFile(path, data);
+  return [
+    `Settings ${command.type === "set" ? "updated" : "unset"}: ${command.scope}.${command.key}`,
+    "Changes apply on next March startup; current session runtime is unchanged.",
+    ...formatSettingsView({ cwd, homeDir }),
+  ];
+}
+
+export function formatSettingsView({ cwd = process.cwd(), homeDir = homedir() } = {}) {
+  const globalPath = settingsPathForScope("global", { cwd, homeDir });
+  const projectPath = settingsPathForScope("project", { cwd, homeDir });
+  const globalSettings = readSettingsFile(globalPath);
+  const projectSettings = readSettingsFile(projectPath);
+  const merged = loadConfig(cwd, { homeDir });
+  return [
+    "Settings:",
+    `  configured.providers: ${Object.keys(merged.providers ?? {}).join(", ") || "(none)"}`,
+    `  global: ${globalPath}`,
+    ...formatScopeLines(globalSettings),
+    `  project: ${projectPath}`,
+    ...formatScopeLines(projectSettings),
+    "Commands:",
+    "  /settings set project memoryRoot <path>",
+    "  /settings unset project memoryRoot",
+  ];
+}
+
+function settingsPathForScope(scope, { cwd, homeDir }) {
+  return scope === "global"
+    ? join(homeDir, ".march", "config")
+    : join(cwd, ".march", "config");
+}
+
+function readSettingsFile(path) {
+  if (!existsSync(path)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeSettingsFile(path, data) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}
+
+function formatScopeLines(settings) {
+  const keys = Object.keys(settings).sort();
+  if (keys.length === 0) return ["    (empty)"];
+  return keys.map((key) => `    ${key}: ${formatSettingValue(settings[key])}`);
+}
+
+function formatSettingValue(value) {
+  return Array.isArray(value) ? value.join(", ") : String(value);
+}

package/src/context/diagnostics.mjs

@@ -0,0 +1,70 @@
+const MAX_DIAGNOSTICS = 20;
+
+export function buildDiagnosticsLayer({ snapshot } = {}) {
+  const diagnostics = snapshot?.diagnostics ?? [];
+  if (diagnostics.length === 0) return "[diagnostics]";
+
+  const sorted = [...diagnostics].sort((a, b) => severityRank(a.severity) - severityRank(b.severity));
+
+  const counts = countSeverities(diagnostics);
+  const lines = ["[diagnostics]", "source: lsp"];
+  if (snapshot?.status) lines.push(`status: ${snapshot.status}`);
+  lines.push(`summary: ${formatSummary(counts)}${diagnostics.length > MAX_DIAGNOSTICS ? `, showing ${MAX_DIAGNOSTICS} of ${diagnostics.length}` : ""}`);
+  lines.push("");
+  for (const diagnostic of sorted.slice(0, MAX_DIAGNOSTICS)) {
+    lines.push(formatDiagnostic(diagnostic));
+  }
+  return lines.join("\n");
+}
+
+export function buildDiagnosticsForPath({ snapshot, path } = {}) {
+  const targetPath = String(path ?? "");
+  if (!targetPath) return "";
+  const diagnostics = (snapshot?.diagnostics ?? []).filter((diagnostic) => diagnostic.path === targetPath);
+  if (diagnostics.length === 0) return "";
+  return buildDiagnosticsLayer({
+    snapshot: {
+      ...snapshot,
+      diagnostics,
+    },
+  });
+}
+
+function formatDiagnostic(diagnostic) {
+  const severity = formatSeverity(diagnostic.severity);
+  const line = (diagnostic.range?.start?.line ?? 0) + 1;
+  const col = (diagnostic.range?.start?.character ?? 0) + 1;
+  const code = diagnostic.code == null ? "" : ` ${diagnostic.code}`;
+  const source = diagnostic.source ?? diagnostic.serverId ?? "lsp";
+  return `- ${severity} ${source} ${diagnostic.path}:${line}:${col}${code}\n  ${singleLine(diagnostic.message ?? "")}`;
+}
+
+function countSeverities(diagnostics) {
+  const counts = { error: 0, warning: 0, info: 0, hint: 0 };
+  for (const diagnostic of diagnostics) counts[formatSeverity(diagnostic.severity)]++;
+  return counts;
+}
+
+function formatSummary(counts) {
+  return [
+    [counts.error, "errors"],
+    [counts.warning, "warnings"],
+    [counts.info, "info"],
+    [counts.hint, "hints"],
+  ].filter(([count]) => count > 0).map(([count, label]) => `${count} ${label}`).join(", ") || "0 diagnostics";
+}
+
+function formatSeverity(severity) {
+  if (severity === 2) return "warning";
+  if (severity === 3) return "info";
+  if (severity === 4) return "hint";
+  return "error";
+}
+
+function severityRank(severity) {
+  return { error: 0, warning: 1, info: 2, hint: 3 }[formatSeverity(severity)] ?? 4;
+}
+
+function singleLine(text) {
+  return String(text).replace(/\s+/g, " ").trim();
+}

package/src/context/engine.mjs

@@ -0,0 +1,148 @@
+import { resolve } from "node:path";
+import { buildSessionIdentity } from "./session-status.mjs";
+import { buildSystemCore, resolveSystemCorePromptKey } from "./system-core.mjs";
+import { buildInjectionsLayer } from "./injections.mjs";
+import { buildProjectContext } from "./project-context.mjs";
+import { formatRecallHints } from "../memory/markdown-store.mjs";
+
+export class ContextEngine {
+  constructor({ cwd, modelId, provider = "deepseek", thinkingLevel = "medium", namespace = "", shellRuntime = null, lspService = null, injections = [], maxTurns, trimBatch }) {
+    this.cwd = cwd;
+    this.modelId = modelId;
+    this.provider = provider;
+    this.thinkingLevel = thinkingLevel;
+    this.turns = [];
+    this.sessionName = "";
+    this.toolDefs = [];
+    this.namespace = namespace;
+    this.shellRuntime = shellRuntime;
+    this.lspService = lspService;
+    this.injections = [...injections];
+    this.maxTurns = maxTurns ?? 15;
+    this.trimBatch = trimBatch ?? 5;
+    this.systemCorePromptKey = resolveSystemCorePromptKey({ modelId });
+    this.systemCore = buildSystemCore({ modelId });
+  }
+
+  // ── Public API ──────────────────────────────────────────────────────
+
+  buildContext(userMessage = "") {
+    return this.buildContextLayers(userMessage).map((layer) => layer.text).join("\n\n");
+  }
+
+  buildProviderContext(userMessage = "") {
+    const layers = this.buildContextLayers(userMessage);
+    const systemLayer = layers.find((layer) => layer.name === "system_core");
+    return {
+      system: systemLayer?.text ?? this.systemCore,
+      userMessages: layers
+        .filter((layer) => layer.name !== "system_core")
+        .map((layer) => ({
+          name: layer.name,
+          content: layer.name === "recent_chat" ? appendCurrentUser(layer.text, userMessage) : layer.text,
+        })),
+    };
+  }
+
+  buildContextLayers(_userMessage = "") {
+    const layers = [
+      { name: "system_core", text: this.systemCore },
+    ];
+
+    const injectionsLayer = buildInjectionsLayer(this.injections);
+    if (injectionsLayer) layers.push({ name: "injections", text: injectionsLayer });
+
+    layers.push({ name: "session_identity", text: this.#buildSessionIdentity() });
+
+    const projectCtx = buildProjectContext(this.cwd);
+    if (projectCtx) layers.push({ name: "project_context", text: projectCtx });
+
+    layers.push({ name: "recent_chat", text: this.#buildRecentChat() });
+
+    return layers;
+  }
+
+  recordTurn({ userMessage, assistantMessage, userRecallHints = [], assistantRecallHints = [] }) {
+    this.turns.push({
+      index: this.turns.length + 1,
+      userMessage,
+      assistantMessage: assistantMessage ?? "",
+      userRecallHints,
+      assistantRecallHints,
+    });
+    if (this.turns.length > this.maxTurns) {
+      const keep = Math.max(1, this.maxTurns - this.trimBatch);
+      this.turns = this.turns.slice(-keep);
+    }
+  }
+
+  getRecentRecallMemoryIds() {
+    const ids = new Set();
+    for (const turn of this.turns) {
+      for (const hint of turn.userRecallHints ?? []) if (hint?.id) ids.add(hint.id);
+      for (const hint of turn.assistantRecallHints ?? []) if (hint?.id) ids.add(hint.id);
+    }
+    return ids;
+  }
+
+  resolvePath(raw) {
+    return resolve(this.cwd, raw);
+  }
+
+  setInjections(injections = []) { this.injections = [...injections]; }
+  setToolDefs(defs) { this.toolDefs = defs; }
+  setRuntimeState({ modelId, provider, thinkingLevel } = {}) {
+    if (modelId) this.modelId = modelId;
+    if (provider) this.provider = provider;
+    if (thinkingLevel) this.thinkingLevel = thinkingLevel;
+    const nextPromptKey = resolveSystemCorePromptKey({ modelId: this.modelId });
+    if (nextPromptKey !== this.systemCorePromptKey) {
+      this.systemCorePromptKey = nextPromptKey;
+      this.systemCore = buildSystemCore({ modelId: this.modelId });
+    }
+  }
+  setSessionName(name) { this.sessionName = String(name || "").trim(); }
+
+  restoreSession(data, _pool, { replace = false } = {}) {
+    if (replace) {
+      this.turns = [];
+      this.sessionName = "";
+    }
+    if (data.turns) this.turns = data.turns;
+    if (typeof data.sessionName === "string") this.sessionName = data.sessionName;
+    this.setRuntimeState(data);
+  }
+
+  // ── Private layers ──────────────────────────────────────────────────
+
+  #buildSessionIdentity() {
+    return buildSessionIdentity({ cwd: this.cwd, workspaceRoot: this.cwd });
+  }
+
+  #buildRecentChat() {
+    if (this.turns.length === 0) {
+      return `[recent_chat]\n(no prior turns)`;
+    }
+    const entries = [];
+    for (const turn of this.turns) {
+      let block = `## Turn ${turn.index}\n` +
+        `[user]\n${String(turn.userMessage ?? "")}\n`;
+      const userRecall = formatRecallHints("user", turn.userRecallHints ?? []);
+      if (userRecall) block += `\n${userRecall}\n`;
+      block += `\n[March]\n`;
+      if (turn.assistantMessage) {
+        block += `\n${String(turn.assistantMessage ?? "")}\n`;
+      }
+      const assistantRecall = formatRecallHints("assistant", turn.assistantRecallHints ?? []);
+      if (assistantRecall) block += `\n${assistantRecall}\n`;
+      entries.push(block);
+    }
+    return `[recent_chat]\n${entries.join("\n\n")}`;
+  }
+
+}
+
+function appendCurrentUser(recentChat, userMessage) {
+  const currentUser = String(userMessage ?? "").trimEnd();
+  return `${recentChat}\n\n[current_user]\n${currentUser}`;
+}

package/src/context/injections.mjs

@@ -0,0 +1,26 @@
+export function buildInjectionsLayer(injections = []) {
+  const blocks = injections
+    .map(normalizeInjection)
+    .filter(Boolean)
+    .map(({ type, source, content }) => `## ${formatInjectionTitle(type, source)}\n${content}`);
+
+  if (blocks.length === 0) return "";
+  return `[injections]\n${blocks.join("\n\n")}`;
+}
+
+function normalizeInjection(injection) {
+  if (!injection || typeof injection.content !== "string") return null;
+  const content = injection.content.trim();
+  if (!content) return null;
+  return {
+    type: String(injection.type || "external"),
+    source: String(injection.source || "unknown"),
+    content,
+  };
+}
+
+function formatInjectionTitle(type, source) {
+  if (type === "mcp_server") return `MCP server: ${source}`;
+  if (type === "extension") return `Extension: ${source}`;
+  return `${type}: ${source}`;
+}

package/src/context/project-context.mjs

@@ -0,0 +1,20 @@
+import { loadProjectContextFiles } from "@earendil-works/pi-coding-agent";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+/**
+ * Build the [project_context] layer from AGENTS.md / CLAUDE.md files.
+ * Uses SDK's loadProjectContextFiles to scan:
+ *   - ~/.march/ (global)
+ *   - cwd upward to root (ancestor directories, closest first)
+ *
+ * Returns null if no files found.
+ */
+export function buildProjectContext(cwd) {
+  const agentDir = resolve(homedir(), ".march");
+  const files = loadProjectContextFiles({ cwd, agentDir });
+  if (!files || files.length === 0) return null;
+
+  const blocks = files.map((f) => `--- ${f.path} ---\n${f.content.trimEnd()}`);
+  return `[project_context]\n${blocks.join("\n\n")}`;
+}

package/src/context/session-status.mjs

@@ -0,0 +1,15 @@
+export function buildSessionIdentity({
+  cwd,
+  workspaceRoot = cwd,
+  platform = process.platform,
+} = {}) {
+  const shellInfo = platform === "win32"
+    ? "shells: powershell (recommended), bash (Git Bash)"
+    : "shell: bash";
+
+  return `[session_identity]
+cwd: ${cwd}
+workspace_root: ${workspaceRoot}
+platform: ${platform}
+${shellInfo}`;
+}

package/src/context/shell-layers.mjs

@@ -0,0 +1,23 @@
+export function buildShellLayers({ shellRuntime, truncateText = truncate } = {}) {
+  const shells = (shellRuntime?.listShells?.() ?? []).filter((s) => s.status !== "killed");
+  if (!shells.length) return [];
+  const blocks = shells.map((shell) => {
+    const snapshot = shellRuntime.snapshotShell(shell.id);
+    const output = snapshot.plain ? truncateText(snapshot.plain, 2000) : "(no output)";
+    return [
+      `## ${shell.name} (${shell.id})`,
+      `status: ${shell.status}`,
+      `command: ${shell.command}${shell.args?.length ? ` ${shell.args.join(" ")}` : ""}`,
+      `cwd: ${shell.cwd}`,
+      `lines: ${shell.lineCount}`,
+      "recent_output:",
+      output,
+    ].join("\n");
+  });
+  return [`[shells]\n${blocks.join("\n\n")}`];
+}
+
+function truncate(text, maxLen) {
+  if (text.length <= maxLen) return text;
+  return text.slice(0, maxLen) + "\n...(truncated)";
+}

package/src/context/system-core/base.md

@@ -0,0 +1,60 @@
+<identity>
+You are March, a terminal-native coding agent. You operate in the user's project directory with direct file access.
+The user primarily asks for software engineering work: fixing bugs, adding behavior, refactoring, explaining code, and maintaining this repository. Interpret unclear requests in that project context.
+</identity>
+
+<communication_contract>
+- Be concise and direct. Match the response shape to the task; simple questions get simple answers.
+- Assume users may not see tool calls. Before the first tool call, say in one sentence what you are about to do. While working, give brief updates when you find something important, change direction, or hit a blocker.
+- Don't narrate hidden reasoning. State decisions, results, and relevant next steps.
+- End with one or two sentences: what changed, verification status, and what's next if anything.
+- Report outcomes truthfully. If tests fail or a step was skipped, say so plainly with the relevant output or reason.
+</communication_contract>
+
+<operating_contract>
+- Default to doing the requested work in the repository, not giving abstract advice.
+- Build context from current project facts before editing. Inspect existing code and conventions first.
+- Keep the change scoped to the request. Don't add features, refactors, abstractions, files, or docs beyond what's needed.
+- Three similar lines beats a premature abstraction. No half-finished implementations.
+- Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal guarantees; validate at real boundaries such as user input and external APIs.
+- Avoid backwards-compatibility hacks. If unused code is truly unused, delete it rather than leaving shims or markers.
+- Default to add one short comment when the WHY is helpful.
+</operating_contract>
+
+<safety_contract>
+- Local, reversible actions such as reading files, editing files, and running tests are normally okay.
+- Confirm before actions that are hard to reverse, destructive, outward-facing, or affect shared state: deleting user work, force operations, dependency downgrades, CI/CD changes, pushing code, creating PRs/issues, sending messages, or publishing content to external services.
+- Before deleting or overwriting, inspect the target. If reality contradicts the request or you didn't create the state, stop and surface it.
+- Don't bypass safeguards to make an obstacle disappear. Never skip hooks or signing unless explicitly requested; investigate failures and fix the underlying issue.
+</safety_contract>
+
+<editing_contract>
+- Use read(path) for file inspection with 1-based line numbers.
+- Use grep(pattern), find(pattern), and ls(path) to explore the project before editing.
+- Prefer dedicated read/search/edit tools over shell commands for file inspection and modification.
+- Use command_exec for one-shot commands. Use terminal_* only for interactive programs, long-running processes, or when preserving terminal state matters.
+- Keep the working directory stable; use paths instead of cd unless the user asks otherwise.
+- Use edit_file for all file writes.
+- For targeted edits: use edit_file with mode="patch" and edits[] entries: replace_range(startLine, endLine, newText) or replace_text(oldText, newText).
+- For new files use edit_file with mode="write" and content. For full replacement of an existing file use mode="overwrite" and content.
+</editing_contract>
+
+<verification_contract>
+- Run the most relevant tests, type checks, or linters when practical after code changes.
+- If you cannot verify, say what was not run and why.
+- Do not claim success beyond what you actually checked.
+</verification_contract>
+
+<git_contract>
+- Check worktree state before committing or making broad edits.
+- Do not overwrite or discard user changes unless explicitly asked.
+- When project instructions require a commit after each completed modification, create a focused commit for your change.
+- Never use --no-verify, --no-gpg-sign, or commit.gpgsign=false unless the user explicitly asks.
+</git_contract>
+
+<memory_system>
+- [memory_hint source="..."] blocks in recent_chat show memory hints matched from your thinking output. Use memory_open(id) to read the full content.
+- Use memory_search(query) for full-text search across all memories.
+- To edit an existing memory, use memory_open(id) to get its path, then edit_file with mode="patch" for targeted edits.
+- Use memory_save() to create memories or update whole fields. Before creating a new memory, merge related updates into an existing memory when they share the same topic or decision thread. Tags are the primary retrieval key for future recall. Prefer lowercase kebab-case tags like 'march-cli', 'tooling', 'permissions'.
+</memory_system>

package/src/context/system-core/prompts/deepseek-v4-pro.md

@@ -0,0 +1,3 @@
+<model_specific>
+Build context from current project facts before editing. Avoid broad rewrites unless explicitly requested.
+</model_specific>

package/src/context/system-core/prompts/default.md

@@ -0,0 +1,3 @@
+<model_specific>
+Use tools deliberately. Keep tool arguments strict and minimal.
+</model_specific>

package/src/context/system-core.mjs

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PROMPT_DIR = join(dirname(fileURLToPath(import.meta.url)), "system-core", "prompts");
+const BASE_PROMPT_PATH = join(dirname(fileURLToPath(import.meta.url)), "system-core", "base.md");
+const DEFAULT_PROMPT_KEY = "default";
+
+export function buildSystemCore({ modelId } = {}) {
+  const prompt = loadSystemCorePrompt({ modelId });
+  return `[system_core]\n${prompt.base}\n\n${prompt.append}`;
+}
+
+export function resolveSystemCorePromptKey({ modelId = "" } = {}) {
+  const key = sanitizeModelId(modelId);
+  if (key && existsSync(promptPath(key))) return key;
+  return DEFAULT_PROMPT_KEY;
+}
+
+function loadSystemCorePrompt({ modelId } = {}) {
+  const key = resolveSystemCorePromptKey({ modelId });
+  return {
+    key,
+    base: readFileSync(BASE_PROMPT_PATH, "utf8").trim(),
+    append: readFileSync(promptPath(key), "utf8").trim(),
+  };
+}
+
+function promptPath(key) {
+  return join(PROMPT_DIR, `${key}.md`);
+}
+
+function sanitizeModelId(modelId) {
+  return String(modelId || "").trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-");
+}

package/src/debug/model-context-dumper.mjs

@@ -0,0 +1,52 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+
+export function createModelContextDumper({ enabled = false, rootDir = "", now = () => new Date() } = {}) {
+  let sequence = 0;
+  return {
+    enabled: Boolean(enabled),
+    rootDir,
+    dump({ kind = "model", prompt = "", metadata = {} } = {}) {
+      if (!enabled) return null;
+      sequence += 1;
+      mkdirSync(rootDir, { recursive: true });
+      const timestamp = now().toISOString();
+      const filename = `${sanitizeTimestamp(timestamp)}-${String(sequence).padStart(4, "0")}-${sanitizeKind(kind)}.md`;
+      const path = join(rootDir, filename);
+      writeFileSync(path, `${formatHeader({ kind, timestamp, ...metadata })}\n\n${prompt}`, "utf8");
+      return path;
+    },
+    dumpSidecar({ sourcePath, suffix, value } = {}) {
+      if (!enabled || !sourcePath || !suffix) return null;
+      const ext = extname(sourcePath);
+      const stem = basename(sourcePath, ext);
+      const path = join(rootDir, `${stem}-${sanitizeKind(suffix)}.json`);
+      mkdirSync(rootDir, { recursive: true });
+      writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+      return path;
+    },
+  };
+}
+
+function formatHeader(metadata) {
+  const lines = ["---"];
+  for (const [key, value] of Object.entries(metadata)) {
+    if (value == null || value === "") continue;
+    lines.push(`${key}: ${formatValue(value)}`);
+  }
+  lines.push("---");
+  return lines.join("\n");
+}
+
+function formatValue(value) {
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return JSON.stringify(String(value));
+}
+
+function sanitizeTimestamp(timestamp) {
+  return timestamp.replace(/[:.]/g, "-");
+}
+
+function sanitizeKind(kind) {
+  return String(kind).replace(/[^a-z0-9_-]+/gi, "-").replace(/^-+|-+$/g, "") || "model";
+}