@staix/agent-research 0.0.0-stage → 0.2.1

package/src/setup.ts

@@ -0,0 +1,296 @@
+import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, realpathSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isDeepStrictEqual } from "node:util";
+import { assertWritable, plain, readBytesBounded, readTextBounded, sha256, writeAtomic } from "./study.ts";
+
+export const SETUP_TARGETS = ["claude", "codex", "kimi", "pi", "qwen", "jcode", "agy"] as const;
+type AgentSetupTarget = typeof SETUP_TARGETS[number];
+export type SetupTarget = AgentSetupTarget | "console";
+export type SetupMode = "dry-run" | "apply" | "undo";
+export interface McpEntry { command: string; args: string[] }
+export interface ConsoleManifest { api: 1; tool: "ares"; module: string; sha256: string }
+type SetupEntry = McpEntry | ConsoleManifest;
+interface Host { target: SetupTarget; file: string; key: string; format: "json" | "toml" | "manifest" }
+export interface SetupAction { target: SetupTarget; file: string; entry: string; receipt: string; lock: string; change: "add" | "replace" | "unchanged" | "restore" | "remove" | "none" | "refused"; receiptChange: "add" | "replace" | "remove" | "none"; reason?: string }
+export interface SetupReport { mode: SetupMode; applied: boolean; root: string; entry: McpEntry; actions: SetupAction[]; notes: string[]; console?: ConsoleManifest }
+interface Receipt { v: 1; target: SetupTarget; file: string; existed: boolean; keyExisted: boolean; priorPresent: boolean; prior?: unknown; priorToml?: string; installed: SetupEntry }
+interface Plan { host: Host; action: SetupAction; before: string | null; after: string | null; receiptBefore: string | null; receiptAfter: string | null }
+export const SETUP_CONFIG_BYTES = 4 * 1024 * 1024, SETUP_RECEIPT_BYTES = 8 * 1024 * 1024;
+const OWN_ROOT = fileURLToPath(new URL("..", import.meta.url));
+class SetupError extends Error {}
+function fail(message: string, nextStep = "correct the config or restore its setup receipt, then rerun ares setup"): never { throw new SetupError(`setup: ${message}; ${nextStep}`); }
+function failureReason(error: unknown): string {
+  return error instanceof SetupError ? error.message : `setup: ${error instanceof Error ? error.message : "file operation failed"}; check file permissions and the setup receipt, then rerun ares setup`;
+}
+function setupLockRefusal(file: string): never {
+  fail(`target is locked by another setup: ${file}`, `if no ares setup is running, remove ${file} and rerun ares setup`);
+}
+function absolute(value: string, label: string): string {
+  if (!isAbsolute(value) || value.includes("\0")) fail(`${label} must be an absolute path`, label === "--root" ? "pass --root ABS for an existing agent-research release" : `set ${label} to an absolute path and rerun ares setup`);
+  return resolve(value);
+}
+/** Links are always refused. Ownership checks protect mutable config/receipts; release reads may be administrator-owned. */
+function guard(file: string, owned = true): void {
+  const parts: string[] = []; for (let current = resolve(file); ; current = dirname(current)) { parts.unshift(current); if (current === dirname(current)) break; }
+  for (const part of parts) {
+    let info;
+    try { info = lstatSync(part); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") continue; throw error; }
+    if (info.isSymbolicLink()) fail("links are refused in config and receipt paths");
+    if (part === resolve(file)) {
+      if (!info.isFile()) fail("config or receipt is not a regular file");
+      if (owned && info.uid !== process.getuid!()) fail("config or receipt is owned by another user");
+    } else {
+      if (!info.isDirectory()) fail("config or receipt parent is not a directory");
+      if (owned && info.uid !== 0 && info.uid !== process.getuid!()) fail("config or receipt parent is owned by another user");
+    }
+  }
+}
+function read(file: string, max: number, owned = true): string | null {
+  guard(file, owned);
+  try { return readTextBounded(file, max, { noFollow: true, ...(owned ? { uid: process.getuid!() } : {}) }); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw error; }
+}
+function write(file: string, value: string | null, max: number, privateFile = false): void {
+  guard(file);
+  if (value === null) { unlinkSync(file); return; }
+  assertWritable(value, max, "setup output");
+  let mode = 0o600;
+  try { if (!privateFile) mode = lstatSync(file).mode & 0o777; } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  if (privateFile) privateDirectory(dirname(file), true);
+  guard(file); writeAtomic(file, value, max, mode);
+}
+function record(value: unknown): Record<string, unknown> { if (!plain(value)) fail("config must contain an object"); return value; }
+function document(host: Host, source: string | null): Record<string, unknown> {
+  if (source === null) return {};
+  try { return record(host.format === "toml" ? Bun.TOML.parse(source) : JSON.parse(source)); }
+  catch { fail(`invalid ${host.format.toUpperCase()}; fix ${host.file} before applying setup`); }
+}
+function entry(host: Host, source: string | null): unknown { if (host.format === "manifest") return source === null ? undefined : document(host, source); const doc = document(host, source); return doc[host.key] === undefined ? undefined : record(doc[host.key]).ares; }
+function hosts(env: NodeJS.ProcessEnv, cwd: string): Record<AgentSetupTarget, Host> {
+  const home = absolute(env.HOME?.trim() || homedir(), "HOME");
+  const dir = (key: string, fallback: string) => absolute(env[key]?.trim() || join(home, fallback), key);
+  const json = (target: AgentSetupTarget, file: string, key = "mcpServers"): Host => ({ target, file, format: "json", key });
+  return {
+    claude: json("claude", env.CLAUDE_CONFIG_DIR?.trim() ? join(dir("CLAUDE_CONFIG_DIR", ".claude"), ".claude.json") : join(home, ".claude.json")),
+    codex: { target: "codex", file: join(dir("CODEX_HOME", ".codex"), "config.toml"), format: "toml", key: "mcp_servers" },
+    kimi: json("kimi", join(dir("KIMI_CODE_HOME", ".kimi-code"), "mcp.json")),
+    pi: json("pi", join(dir("PI_CODING_AGENT_DIR", ".pi/agent"), "mcp.json")),
+    qwen: json("qwen", join(dir("QWEN_HOME", ".qwen"), "settings.json")),
+    jcode: json("jcode", join(dir("JCODE_HOME", ".jcode"), "mcp.json"), "servers"),
+    agy: json("agy", join(absolute(cwd, "cwd"), ".agents", "mcp_config.json")),
+  };
+}
+/** Header/key handling follows vmem setup; Bun decodes quoted keys instead of a second TOML decoder. */
+function tomlKey(raw: string): string[] | undefined {
+  const pattern = /\s*([A-Za-z0-9_-]+|"(?:[^"\\]|\\.)*"|'[^']*')\s*(?:\.|$)/y, parts: string[] = [];
+  while (pattern.lastIndex < raw.length) {
+    const match = pattern.exec(raw); if (!match) return undefined;
+    const token = match[1]!;
+    try { parts.push(token.startsWith('"') || token.startsWith("'") ? record(Bun.TOML.parse(`key = ${token}`)).key as string : token); } catch { return undefined; }
+  }
+  return parts;
+}
+function header(line: string): string | undefined {
+  line = line.replace(/\r?\n$/, "");
+  const match = /^\s*(\[\[?)/.exec(line); if (!match) return undefined;
+  let quote = "", index = match[0].length;
+  for (; index < line.length; index++) {
+    const char = line[index]!;
+    if (quote) { if (char === "\\" && quote === '"') index++; else if (char === quote) quote = ""; }
+    else if (char === '"' || char === "'") quote = char;
+    else if (char === "]") break;
+  }
+  const close = match[1] === "[[" ? "]]" : "]";
+  return !quote && line.startsWith(close, index) && /^\s*(?:#.*)?$/.test(line.slice(index + close.length)) ? line.slice(match[0].length, index).trim() : undefined;
+}
+/** Multiline strings may contain apparent table headers; never treat those lines as config entries. */
+function spans(lines: string[]): [number, number][] {
+  const result: [number, number][] = [], comments: boolean[] = []; let start = -1, quote = "";
+  for (let i = 0; i <= lines.length; i++) {
+    const line = lines[i], name = line !== undefined && !quote ? header(line) : undefined;
+    comments[i] = !quote && line?.trim().startsWith("#") === true;
+    if (i === lines.length || name !== undefined) {
+      if (start >= 0) { let stop = i; while (stop > start && (!lines[stop - 1]!.trim() || comments[stop - 1])) stop--; result.push([start, stop]); start = -1; }
+      const key = name === undefined ? undefined : tomlKey(name); if (key?.[0] === "mcp_servers" && key[1] === "ares") start = i;
+    }
+    for (let pos = 0; line !== undefined && pos < line.length; pos++) {
+      const char = line[pos]!;
+      if (!quote && char === "#") break;
+      if (quote && char === "\\" && quote[0] === '"') { pos++; continue; }
+      if (quote.length === 3 && line.startsWith(quote, pos)) { const end = quote[0]!; while (line[pos + 1] === end) pos++; quote = ""; }
+      else if (quote.length === 1 && char === quote) quote = "";
+      else if (!quote && (char === '"' || char === "'")) { quote = line.startsWith(char.repeat(3), pos) ? char.repeat(3) : char; pos += quote.length - 1; }
+    }
+  }
+  return result;
+}
+const linesOf = (source: string): string[] => source.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+function priorToml(source: string | null): string | undefined {
+  const lines = linesOf(source ?? ""), owned = spans(lines);
+  return owned.length ? owned.map(([start, stop]) => lines.slice(start, stop).join("")).join("") : undefined;
+}
+function put(host: Host, source: string | null, value: unknown, rawToml?: string, keepKey = false): string {
+  if (host.format === "manifest") return JSON.stringify(value ?? {}, null, 2) + "\n";
+  if (host.format === "json") {
+    const doc = document(host, source), servers = { ...record(doc[host.key] ?? {}) };
+    if (value === undefined) delete servers.ares; else servers.ares = value;
+    if (Object.keys(servers).length || keepKey) doc[host.key] = servers; else delete doc[host.key];
+    return JSON.stringify(doc, null, source && /\n(\t| +)"/.exec(source)?.[1] || "  ") + "\n";
+  }
+  const newline = source?.includes("\r\n") ? "\r\n" : "\n", lines = linesOf(source ?? ""), owned = spans(lines);
+  let block = rawToml ?? "";
+  if (value !== undefined && rawToml === undefined) {
+    const target = record(value);
+    block = `[mcp_servers.ares]${newline}command = ${JSON.stringify(target.command)}${newline}args = ${JSON.stringify(target.args)}${newline}`;
+  }
+  if (owned.length) {
+    for (const [start, stop] of [...owned].reverse()) lines.splice(start, stop - start);
+    lines.splice(owned[0]![0], 0, block);
+  } else if (block) {
+    const prefix = (source ?? "").endsWith("\n") || !source ? "" : newline;
+    lines.push(prefix + (source ? newline : "") + block);
+  }
+  const output = lines.join("");
+  try { const parsed = document(host, output); if (!isDeepStrictEqual(parsed.mcp_servers === undefined ? undefined : record(parsed.mcp_servers).ares, rawToml === undefined ? value : entry(host, rawToml))) throw new Error(); }
+  catch { fail("TOML entry cannot be edited safely; convert inline/dotted ares settings to [mcp_servers.ares] tables first"); }
+  return output;
+}
+function install(root: string): string {
+  const requested = absolute(root, "--root");
+  let location: string;
+  try { location = realpathSync(requested); } catch { fail("install root is unreadable or missing", "pass --root ABS for an existing agent-research release"); }
+  const source = read(join(location, "package.json"), 65_536, false);
+  let pkg: unknown; try { pkg = source === null ? null : JSON.parse(source); } catch { fail("install root package.json is not valid JSON", "select or reinstall an intact agent-research release root"); }
+  if (!plain(pkg) || pkg.name !== "@staix/agent-research" || typeof pkg.version !== "string") fail("--root is not an agent-research installation", "select a release root containing package.json and bin/ares.js");
+  const bootstrap = join(location, "bin", "ares.js"); guard(bootstrap, false);
+  try { if (!lstatSync(bootstrap).isFile()) throw new Error(); } catch { fail("install root has no regular bin/ares.js", "select or reinstall an intact agent-research release root"); }
+  return location;
+}
+function validInstalled(host: Host, value: unknown): boolean {
+  if (!plain(value)) return false;
+  return host.format === "manifest"
+    ? value.api === 1 && value.tool === "ares" && typeof value.module === "string" && isAbsolute(value.module) && typeof value.sha256 === "string" && /^[a-f0-9]{64}$/.test(value.sha256)
+    : typeof value.command === "string" && Array.isArray(value.args) && value.args.every(arg => typeof arg === "string");
+}
+function receipt(source: string | null, host: Host): Receipt | undefined {
+  if (source === null) return undefined;
+  let raw: unknown; try { raw = JSON.parse(source); } catch { fail("receipt must be valid JSON"); }
+  if (!plain(raw) || raw.v !== 1 || raw.target !== host.target || raw.file !== host.file || typeof raw.existed !== "boolean" || typeof raw.keyExisted !== "boolean" || typeof raw.priorPresent !== "boolean"
+    || !validInstalled(host, raw.installed)
+    || (raw.priorPresent && !Object.hasOwn(raw, "prior")) || (raw.priorToml !== undefined && typeof raw.priorToml !== "string")) fail("unsupported, malformed or foreign setup receipt");
+  return raw as unknown as Receipt;
+}
+function plan(host: Host, receiptPath: string, mode: SetupMode, desired: SetupEntry, ownsLock = false): Plan {
+  const action: SetupAction = { target: host.target, file: host.file, entry: host.format === "manifest" ? "console plugin manifest" : `${host.key}.ares`, receipt: receiptPath, lock: `${host.file}.ares-setup.lock`, change: "none", receiptChange: "none" };
+  if (host.format === "manifest") privateDirectory(dirname(host.file));
+  guard(action.lock);
+  if (!ownsLock && existsSync(action.lock)) setupLockRefusal(action.lock);
+  const before = read(host.file, SETUP_CONFIG_BYTES), receiptBefore = read(receiptPath, SETUP_RECEIPT_BYTES), prior = receipt(receiptBefore, host), current = entry(host, before);
+  const result: Plan = { host, action, before, after: before, receiptBefore, receiptAfter: receiptBefore };
+  if (mode === "undo") {
+    if (!prior) return result;
+    if (!isDeepStrictEqual(current, prior.installed)) fail("ares entry changed since apply; keep the user edit and reconcile the receipt manually before undo");
+    result.after = put(host, before, prior.priorPresent ? prior.prior : undefined, prior.priorToml, prior.keyExisted);
+    if (!prior.existed && isDeepStrictEqual(document(host, result.after), {})) result.after = null;
+    result.receiptAfter = null; action.change = prior.priorPresent ? "restore" : "remove"; action.receiptChange = "remove"; return result;
+  }
+  if (isDeepStrictEqual(current, desired) && (host.format !== "manifest" || !privateModesNeeded(host.file))) { action.change = "unchanged"; return result; }
+  const original = prior?.priorToml === undefined ? prior?.priorPresent ? prior.prior : undefined : entry(host, prior.priorToml);
+  if (prior && !isDeepStrictEqual(current, prior.installed) && !isDeepStrictEqual(current, original)) fail("ares entry changed since apply; reconcile it before replacing the installed root");
+  result.after = put(host, before, desired);
+  const saved: Receipt = prior ?? { v: 1, target: host.target, file: host.file, existed: before !== null, keyExisted: Object.hasOwn(document(host, before), host.key), priorPresent: current !== undefined,
+    ...(current === undefined ? {} : { prior: current }), ...(host.format === "toml" && current !== undefined ? { priorToml: priorToml(before) } : {}), installed: desired };
+  result.receiptAfter = JSON.stringify({ ...saved, installed: desired }, null, 2) + "\n";
+  assertWritable(result.receiptAfter, SETUP_RECEIPT_BYTES, "setup receipt");
+  assertWritable(result.after, SETUP_CONFIG_BYTES, "client config");
+  action.change = current === undefined ? "add" : "replace"; action.receiptChange = receiptBefore === null ? "add" : "replace"; return result;
+}
+/** Per-config, not per-family, so two family homes cannot race on the same client file. */
+function acquireSetupLock(file: string): () => void {
+  guard(file); mkdirSync(dirname(file), { recursive: true, mode: 0o700 }); guard(file);
+  let fd: number;
+  try { fd = openSync(file, "wx", 0o600); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "EEXIST") setupLockRefusal(file); throw error; }
+  return () => { try { closeSync(fd); } finally { unlinkSync(file); } };
+}
+/** Agent setup only. Console dispatch is deliberately separate for the plugin integration. */
+export function runSetup(target: string, mode: SetupMode, options: { env: NodeJS.ProcessEnv; cwd?: string; root?: string }): SetupReport {
+  if (target === "console") return consoleManifest(mode, options.env, options.root ?? OWN_ROOT, options.root !== undefined);
+  if (target !== "all" && !(SETUP_TARGETS as readonly string[]).includes(target)) fail("unknown target", `use ${SETUP_TARGETS.join("|")}|all|console`);
+  if (!["dry-run", "apply", "undo"].includes(mode)) fail("unsupported setup mode", "choose dry-run, apply or undo and rerun ares setup");
+  const env = options.env, root = install(options.root ?? OWN_ROOT), desired: McpEntry = { command: "bun", args: ["--smol", join(root, "bin", "ares.js"), "mcp"] };
+  const table = hosts(env, options.cwd ?? process.cwd()), family = absolute(env.AGENTHUB_HOME?.trim() || join(absolute(env.HOME?.trim() || homedir(), "HOME"), ".agenthub"), "AGENTHUB_HOME");
+  const targets = target === "all" ? SETUP_TARGETS.filter(name => name !== "agy") : [target as AgentSetupTarget], plans: Plan[] = [];
+  const report: SetupReport = { mode, applied: false, root, entry: desired, actions: [], notes: target === "all" ? ["all covers user-level clients; run ares setup agy from its workspace separately"] : [] };
+  for (const name of targets) {
+    const host = table[name], receiptPath = join(family, "research", "setup", `${name}-${sha256(host.file).slice(0, 16)}.json`);
+    try { const item = plan(host, receiptPath, mode, desired); plans.push(item); report.actions.push(item.action); }
+    catch (error) { report.actions.push({ target: name, file: host.file, entry: host.format === "manifest" ? "console plugin manifest" : `${host.key}.ares`, receipt: receiptPath, lock: `${host.file}.ares-setup.lock`, change: "refused", receiptChange: "none", reason: failureReason(error) }); }
+  }
+  return executePlans(plans, mode, desired, report);
+}
+function executePlans(plans: Plan[], mode: SetupMode, desired: SetupEntry, report: SetupReport): SetupReport {
+  if (mode === "dry-run" || report.actions.some(action => action.change === "refused")) return report;
+  for (let item of plans) {
+    if (["none", "unchanged"].includes(item.action.change)) continue;
+    let release: (() => void) | undefined;
+    try {
+      release = acquireSetupLock(item.action.lock);
+      const fresh = plan(item.host, item.action.receipt, mode, desired, true);
+      Object.assign(item.action, fresh.action); item = { ...fresh, action: item.action };
+      if (["none", "unchanged"].includes(item.action.change)) continue;
+      if (read(item.host.file, SETUP_CONFIG_BYTES) !== item.before || read(item.action.receipt, SETUP_RECEIPT_BYTES) !== item.receiptBefore) fail("config or receipt changed during setup; rerun preview before applying");
+      // Receipt is durable before apply changes client config. Undo keeps the receipt until restoration succeeds.
+      if (mode === "apply") write(item.action.receipt, item.receiptAfter, SETUP_RECEIPT_BYTES);
+      try {
+        if (read(item.host.file, SETUP_CONFIG_BYTES) !== item.before) fail("client config changed after receipt creation; rerun preview before applying");
+        write(item.host.file, item.after, SETUP_CONFIG_BYTES, item.host.format === "manifest");
+      }
+      catch (error) { if (mode === "apply" && read(item.action.receipt, SETUP_RECEIPT_BYTES) === item.receiptAfter) write(item.action.receipt, item.receiptBefore, SETUP_RECEIPT_BYTES); throw error; }
+      if (mode === "undo") write(item.action.receipt, null, SETUP_RECEIPT_BYTES);
+      report.applied = true;
+    } catch (error) { item.action.change = "refused"; item.action.reason = failureReason(error); break; }
+    finally { release?.(); }
+  }
+  return report;
+}
+
+/** The manifest directory must satisfy agent-console's private user-owned registration boundary. */
+function privateDirectory(dir: string, apply = false): void {
+  let info;
+  try { info = lstatSync(dir); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return; throw error; }
+  if (!info.isDirectory() || info.isSymbolicLink()) fail("console plugin directory must be a real directory");
+  if (info.uid !== process.getuid!()) fail("console plugin directory is owned by another user");
+  if (apply) chmodSync(dir, 0o700);
+}
+function privateModesNeeded(file: string): boolean {
+  try { if ((lstatSync(dirname(file)).mode & 0o777) !== 0o700) return true; } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  try { return (lstatSync(file).mode & 0o777) !== 0o600; } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; return false; }
+}
+/** Console registration is separate from agent-client `all`; no instruction blocks or other manifests are touched. */
+export function consoleManifest(mode: SetupMode, env: NodeJS.ProcessEnv, requestedRoot = OWN_ROOT, versioned = false): SetupReport {
+  if (!["dry-run", "apply", "undo"].includes(mode)) fail("unsupported setup mode", "choose dry-run, apply or undo and rerun ares setup");
+  const root = install(requestedRoot), module = join(root, "src", "ui", "plugin.ts");
+  const mcp: McpEntry = { command: "bun", args: ["--smol", join(root, "bin", "ares.js"), "mcp"] };
+  let desired: SetupEntry = mcp;
+  if (mode !== "undo") {
+    guard(module, false);
+    let bytes: Buffer;
+    try { bytes = readBytesBounded(module, SETUP_CONFIG_BYTES, { noFollow: true }); }
+    catch { fail("console plugin module is missing, unreadable or over 4 MiB", "select an intact release containing src/ui/plugin.ts and rerun ares setup console"); }
+    desired = { api: 1, tool: "ares", module, sha256: sha256(bytes) };
+  }
+  const pkg = record(JSON.parse(read(join(root, "package.json"), 65_536, false)!)), version = pkg.version;
+  if (versioned && (typeof version !== "string" || version.length > 64 || !/^\d{1,9}\.\d{1,9}\.\d{1,9}(?:[-+][0-9A-Za-z.+-]{1,40})?$/.test(version))) fail("release version cannot name a console registration", "use an agent-research root with a semantic package version: three 1..9-digit parts, optional -/+ suffix of 1..40 characters from 0-9A-Za-z.+-, and at most 64 characters total");
+  const family = absolute(env.AGENTHUB_HOME?.trim() || join(absolute(env.HOME?.trim() || homedir(), "HOME"), ".agenthub"), "AGENTHUB_HOME");
+  const file = join(family, "console", "plugins", versioned ? `ares@${version}.json` : "ares.json");
+  const host: Host = { target: "console", file, key: "", format: "manifest" }, receiptPath = join(family, "research", "setup", `console-${sha256(file).slice(0, 16)}.json`);
+  const report: SetupReport = { mode, applied: false, root, entry: mcp, ...(mode === "undo" ? {} : { console: desired as ConsoleManifest }), actions: [], notes: ["Registers only the ares console plugin; restart the console to load changed code."] };
+  let item: Plan;
+  try { item = plan(host, receiptPath, mode, desired); }
+  catch (error) { report.actions.push({ target: "console", file, entry: "console plugin manifest", receipt: receiptPath, lock: `${file}.ares-setup.lock`, change: "refused", receiptChange: "none", reason: failureReason(error) }); return report; }
+  report.actions.push(item.action); return executePlans([item], mode, desired, report);
+}

package/src/study-export.ts

@@ -0,0 +1,254 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, isAbsolute, sep } from "node:path";
+import { readAttemptRecords, type Attempt, type AttemptStatus } from "./exp/attempts.ts";
+import { ablateResultPath, readClosedAblate } from "./exp/ablate.ts";
+import { finalResultPath, readClosedFinal } from "./exp/final.ts";
+import { readClosedInvestigation } from "./exp/investigate.ts";
+import { readSelection } from "./exp/selection.ts";
+import { designBinding, protocolHash, readProtocol } from "./exp/protocol.ts";
+import { FORMAT_VERSIONS } from "./manifest.ts";
+import { PAPER_EVIDENCE_BYTES, paperBuildPaths } from "./paper/build.ts";
+import { assertWritable, openStudy, plain, readLedger, readTextBounded, sha256, withLock, writeAtomic, type LedgerEvent } from "./study.ts";
+
+/** Reader bound for every bundle file; writeAtomic refuses anything larger. */
+export const BUNDLE_FILE_BYTES = 64 * 1024 * 1024;
+export const BUNDLE_FILES = ["manifest.json", "ledger.jsonl", "attempts.jsonl", "results.json", "reviews.jsonl", "evidence.json"] as const;
+const STATUSES: AttemptStatus[] = ["running", "succeeded", "failed", "cancelled", "unknown"];
+const SHA256 = /^[a-f0-9]{64}$/;
+const HEX = /^[a-f0-9]{16,64}$/;
+const TOKEN = /^[a-z][a-z0-9_.:-]{0,47}$/;
+const GIT_ID = /^[a-f0-9]{40}$/, ATTEMPT_ID = /^[a-f0-9]{16}$/;
+const ACTOR_KINDS = new Set(["person", "agent", "auto"]), EVIDENCE_FAMILIES = new Set(["attempt", "posthoc", "investigate", "ablate", "final"]);
+/** Exact-shape field or null: hand-edited free text in an identity field is never copied. */
+const shaped = (value: unknown, pattern: RegExp): string | null => typeof value === "string" && pattern.test(value) ? value : null;
+const finite = (value: unknown): number | null => typeof value === "number" && Number.isFinite(value) ? value : null;
+const METRIC_KEYS = new Set(["name", "unit", "metric"]);
+/** Closed data keys per ledger event type; unlisted types keep the envelope with empty data. Never host, containerId or hubProject. */
+const LEDGER_KEYS: Record<string, readonly string[]> = {
+  "scope.set": ["sha256"], "autonomy.set": ["from", "to", "phase"], "gate.approve": ["gate", "binding"], "gate.reject": ["gate", "binding"],
+  "lit.search": ["sources", "added", "merged", "total"], "lit.screen": ["decision"], "lit.card": ["id", "sha256"], "lit.bib": ["entries", "sha256"], "lit.verify": ["verified", "failed"],
+  "archive.exported": ["fingerprint"], "skill.proposed": ["skillProposal", "sha256"], "skill.decided": ["skillProposal", "decision"], "watch.set": ["sha256"],
+  "plan.set": ["revision", "state", "sha256"], "plan.gates": ["revision"], "plan.paused": ["revision"], "plan.control": ["revision"], "node.observed": ["revision", "status"], "node.intent": ["revision"],
+  "executor.set": ["kind"], "protocol.set": ["sha256", "protocolHash", "treeHash"], "selection.set": ["sha256", "metric"], "final.seeds.set": ["sha256"],
+  "investigate.closed": ["run", "sha256", "ruleSha256", "winner"], "ablate.closed": ["sha256", "investigateSha256"], "final.closed": ["sha256", "status", "investigateSha256"],
+  "idea.decided": ["decision"], "paper.built": ["manuscriptSha256", "evidenceSha256", "sourceManuscriptSha256"], "review.added": [], "review.resolved": ["buildSha256"],
+  "attempt.started": ["id", "run", "seed", "commit", "treeId"],
+};
+for (const t of ["attempt.run", "attempt.snapshot", "attempt.stage.changed", "attempt.stage.evidence", "attempt.stage.recovered", "attempt.stage.started", "attempt.succeeded", "attempt.failed", "attempt.cancelled", "attempt.unknown"]) LEDGER_KEYS[t] = ["id", "run", "stage", "status"];
+
+export interface BundleManifest {
+  bundle: 1; formats: typeof FORMAT_VERSIONS; studyIdSha256: string; mode: string; protocolHash: string | null; sealBinding: string | null;
+  window: { from: string | null; to: string | null }; counts: { attempts: number; byStatus: Record<AttemptStatus, number>; byRun: Record<string, Record<AttemptStatus, number>>; ledgerEvents: number; reviews: number };
+  files: Record<string, string>;
+}
+export interface BundleListing { bundle: string; files: string[]; wouldWrite: true }
+
+/** A closed scalar: numbers, booleans, hashes and enum-like tokens survive; free text, paths and URLs do not. */
+function closed(value: unknown): value is number | boolean | string | null {
+  if (value === null || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  return typeof value === "string" && (HEX.test(value) || TOKEN.test(value));
+}
+function reduceData(data: Record<string, unknown>, keys: readonly string[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const key of keys) { const value = Object.hasOwn(data, key) ? data[key] : undefined; if (closed(value) || (METRIC_KEYS.has(key) && typeof value === "string")) out[key] = value; else if (Array.isArray(value) && value.every(closed)) out[key] = value; }
+  return out;
+}
+/** Result keys that hold free text even when a value happens to be one token. */
+const FREE_TEXT_KEYS = new Set(["removes", "description", "note", "notes", "label", "text", "message", "cause", "retryWhen", "method", "question"]);
+/** Keep numbers, booleans, null, hashes and closed tokens recursively; drop free-text keys and every other string. */
+function project(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(project).filter(v => v !== undefined);
+  if (plain(value)) { const out: Record<string, unknown> = {}; for (const [k, v] of Object.entries(value)) { if (FREE_TEXT_KEYS.has(k)) continue; const p = METRIC_KEYS.has(k) && typeof v === "string" ? v : project(v); if (p !== undefined) out[k] = p; } return out; }
+  return closed(value) ? value : undefined;
+}
+/** A parseable ISO timestamp or null. */
+const isoAt = (value: unknown): string | null => typeof value === "string" && value.length <= 64 && /^\d{4}-\d{2}-\d{2}T[\d:.]+(?:Z|[+-]\d{2}:\d{2})$/.test(value) && Number.isFinite(Date.parse(value)) ? value : null;
+function reduceEvent(event: LedgerEvent) {
+  const actor = { kind: ACTOR_KINDS.has(event.actor?.kind as string) ? event.actor.kind : "other", ...(event.actor.id !== undefined ? { idSha256: sha256(event.actor.id) } : {}) };
+  const at = isoAt(event.at);
+  return { v: event.v, at, actor, type: TOKEN.test(event.type) ? event.type : "other", data: reduceData(plain(event.data) ? event.data : {}, (Object.hasOwn(LEDGER_KEYS, event.type) ? LEDGER_KEYS[event.type]! : [])) };
+}
+// Closed codes emitted by attempts.ts, metrics.ts and artifacts.ts; never derive a class from user prose.
+const ATTEMPT_REASON_CODES = new Set([
+  "executor-start", "executor-start-uncertain", "preparation", "lost", "wall-clock", "candidate-exit", "evaluator-exit",
+  "evidence-read", "invalid-metrics", "malformed-metrics", "undeclared-metric", "missing-metric", "invalid-metric-value",
+  "nonfinite-metric", "metrics-limit", "duplicate-metric", "missing-metrics", "missing-receipt", "changed-output",
+  "artifact-limit", "artifact-read", "invalid-artifact", "invalid-log-state", "missing-logs",
+]);
+function reasonClass(reason: string | undefined, status: AttemptStatus): string | undefined {
+  if (reason === undefined) return undefined;
+  if (status === "cancelled") return "cancel-reason";
+  return ATTEMPT_REASON_CODES.has(reason) ? reason : "other";
+}
+function duration(start: unknown, end: unknown): number | null {
+  if (typeof start !== "string" || typeof end !== "string") return null;
+  const ms = Date.parse(end) - Date.parse(start);
+  return Number.isFinite(ms) ? ms : null;
+}
+function digest(image: unknown): string | null {
+  const match = typeof image === "string" ? /@(sha256:[a-f0-9]{64})$/.exec(image) : null;
+  return match?.[1] ?? null;
+}
+function attemptRow(a: Attempt) {
+  const stages: Record<string, unknown> = {};
+  for (const name of ["candidate", "evaluator"] as const) {
+    const stage = plain(a.stages) && Object.hasOwn(a.stages, name) ? a.stages[name] : undefined;
+    if (!plain(stage)) continue;
+    stages[name] = { exitCode: Number.isSafeInteger(stage.exitCode) ? stage.exitCode : null, durationMs: duration(stage.startedAt, stage.endedAt), network: stage.network === "none" ? "none" : "other", limits: plain(stage.limits) ? reduceData(stage.limits, ["cpus", "memoryMb", "pidsLimit", "wallSeconds", "gpus"]) : null, imageDigest: digest(stage.image) };
+  }
+  const reason = reasonClass(a.reason, a.status);
+  return {
+    id: a.id, run: a.run, studyIdSha256: sha256(String(a.studyId)), protocolHash: shaped(a.protocolHash, SHA256), sealBinding: shaped(a.sealBinding, SHA256), commit: shaped(a.commit, GIT_ID), treeId: shaped(a.treeId, GIT_ID),
+    snapshotSha256: shaped(a.snapshotSha256, SHA256), seed: Number.isSafeInteger(a.seed) ? a.seed : null, labelSha256: sha256(String(a.label ?? "")), retryOf: shaped(a.retryOf, ATTEMPT_ID), status: a.status, stage: a.stage, ...(reason ? { reasonClass: reason } : {}),
+    durationMs: duration(a.startedAt, a.endedAt), stages,
+    metrics: (Array.isArray(a.metrics) ? a.metrics : []).map(m => ({ name: m.name, unit: m.unit, value: finite(m.value), provenance: m.provenance === "ares-observed" ? "ares-observed" : "other" })),
+    outputs: (Array.isArray(a.outputs) ? a.outputs : []).map(o => ({ sha256: shaped(o.sha256, SHA256), bytes: finite(o.bytes) })),
+    sealing: plain(a.sealing) ? { separateContainers: a.sealing.separateContainers === true, evaluatorReadOnly: a.sealing.evaluatorReadOnly === true, candidateHasNoEvaluator: a.sealing.candidateHasNoEvaluator === true } : null,
+  };
+}
+function closedResult<T>(name: string, read: () => { result: T }): unknown {
+  try { return project(read().result); }
+  catch (error) { throw new Error(`study export: ${name} result is not a verified closed result (${(error as Error).message}); fix it as that message says, then export again`); }
+}
+function reviews(events: LedgerEvent[]) {
+  const resolved = new Map<string, number>();
+  for (const e of events) if (e.type === "review.resolved" && typeof e.data.reviewId === "string") resolved.set(e.data.reviewId, (resolved.get(e.data.reviewId) ?? 0) + 1);
+  return events.filter(e => e.type === "review.added" && plain(e.data.review)).map(e => {
+    const review = e.data.review as Record<string, unknown>, findings = Array.isArray(review.findings) ? review.findings as Record<string, unknown>[] : [];
+    const reviewer = plain(review.reviewer) ? review.reviewer : {}, kinds: Record<string, number> = {};
+    for (const f of findings) { const kind = typeof f.kind === "string" && TOKEN.test(f.kind) ? f.kind : "other"; kinds[kind] = (kinds[kind] ?? 0) + 1; }
+    const id = typeof e.data.id === "string" ? e.data.id : "";
+    const family = typeof reviewer.modelFamily === "string" ? reviewer.modelFamily.trim().toLowerCase() : "";
+    return { idSha256: sha256(id), at: isoAt(e.at), modelFamily: /^[a-z0-9][a-z0-9 ._-]{0,47}$/.test(family) ? family : "other", buildSha256: typeof review.buildSha256 === "string" && HEX.test(review.buildSha256) ? review.buildSha256 : null, findings: findings.length, blocking: findings.filter(f => f.blocking === true).length, kinds, resolved: resolved.get(id) ?? 0 };
+  });
+}
+function evidence(dir: string) {
+  const path = paperBuildPaths(dir).evidence;
+  if (!existsSync(path)) return null;
+  let raw: unknown;
+  try { raw = JSON.parse(readTextBounded(path, PAPER_EVIDENCE_BYTES)); } catch { throw new Error("study export: paper/build/evidence.json is unreadable, invalid JSON or oversized; rebuild the paper before exporting"); }
+  if (!plain(raw) || raw.v !== 1 || !Array.isArray(raw.placeholders)) throw new Error("study export: paper/build/evidence.json has an unsupported shape; rebuild the paper before exporting");
+  return {
+    v: 1, manuscriptSha256: typeof raw.manuscriptSha256 === "string" && SHA256.test(raw.manuscriptSha256) ? raw.manuscriptSha256 : null,
+    placeholders: (raw.placeholders as Record<string, unknown>[]).filter(p => p.kind === "number").map(p => {
+      const ref = typeof p.ref === "string" ? p.ref : "", attempt = /^(?:attempt|posthoc):([a-f0-9]{16})\./.exec(ref)?.[1];
+      const source = plain(p.source) ? p.source : {};
+      return { refSha256: sha256(ref), family: ((f: string | undefined) => f && EVIDENCE_FAMILIES.has(f) ? f : "other")(/^[a-z]+/.exec(ref)?.[0]), ...(attempt ? { attempt } : {}), sourceSha256: typeof source.sha256 === "string" && SHA256.test(source.sha256) ? source.sha256 : null };
+    }),
+  };
+}
+
+/** Path rules run on decoded keys and string values, so a boundary is a real character (a raw newline or tab included). */
+const PATH_SCANS: RegExp[] = [
+  // POSIX: `/` or `~/` not preceded by a letter, digit or underscore; units such as tokens/s keep a word character there.
+  /(?<![\p{L}\p{N}_])(?:\/|~\/)/u,
+  /\b[A-Za-z]:\\/,
+  // Windows root-relative (\Users\x), bare \ and UNC (\\server): any backslash not preceded by a word character or backslash.
+  /(?<![\p{L}\p{N}_\\])\\/u,
+];
+/** URL, key-like and env rules, also run on decoded strings. */
+const SCANS: [string, RegExp][] = [
+  ["url", /\b[a-z][a-z0-9+.-]*:\/\/|\b(?:mailto|urn|file|data):/i],
+  ["key-like token", /\b(?:sk|pk|rk)[-_][A-Za-z0-9_-]{12,}|\b(?:ghp|gho|ghs|ghu|github_pat)_[A-Za-z0-9_]{12,}|\bxox[abprs]-[A-Za-z0-9-]{8,}|\bAKIA[0-9A-Z]{12,}|\beyJ[A-Za-z0-9_-]{16,}/],
+  ["key-like token", /(?<![A-Za-z0-9_-])(?=[A-Za-z0-9_-]*[A-Z])(?=[A-Za-z0-9_-]*[a-z])(?=[A-Za-z0-9_-]*\d)[A-Za-z0-9_-]{32,}(?![A-Za-z0-9_-])/],
+  ["env value", /(?<![A-Za-z0-9_])[A-Za-z_][A-Za-z0-9_]*=[^\s"]/],
+];
+/** Every key and string value of a JSON document, or of each JSONL line; text that is not JSON is scanned as one string. */
+function* decodedStrings(text: string): Generator<string> {
+  const walk = function* (value: unknown): Generator<string> {
+    if (typeof value === "string") yield value;
+    else if (Array.isArray(value)) for (const item of value) yield* walk(item);
+    else if (value && typeof value === "object") for (const [key, item] of Object.entries(value)) { yield key; yield* walk(item); }
+  };
+  let whole: unknown, parsed = false;
+  try { whole = JSON.parse(text); parsed = true; } catch { /* JSONL or plain text */ }
+  if (parsed) { yield* walk(whole); return; }
+  for (const line of text.split("\n")) {
+    if (!line) continue;
+    try { yield* walk(JSON.parse(line)); } catch { yield line; }
+  }
+}
+/** Refuse the whole bundle if any file carries a path, URL, env assignment or key-like token. */
+export function scanBundle(files: Record<string, string>): void {
+  const refuse = (name: string, kind: string): never => { throw new Error(`study export: refused; ${name} would contain a ${kind}. Remove it from the study record (for example an attempt label or ledger field) and retry; nothing was written`); };
+  for (const [name, text] of Object.entries(files)) {
+    for (const value of decodedStrings(text)) {
+      if (PATH_SCANS.some(pattern => pattern.test(value))) refuse(name, "absolute path");
+      for (const [kind, pattern] of SCANS) if (pattern.test(value)) refuse(name, kind);
+    }
+  }
+}
+
+function emptyDir(path: string): void {
+  if (existsSync(path)) { if (!lstatSync(path).isDirectory()) throw new Error("study export: --bundle exists and is not a directory; choose a new or empty directory"); if (readdirSync(path).length) throw new Error("study export: --bundle directory is not empty; choose a new or empty directory"); }
+  else mkdirSync(path, { recursive: true });
+}
+
+/** Real path of the nearest existing ancestor with the missing tail re-appended, so symlinks cannot hide containment. */
+function realTarget(path: string): string {
+  const tail: string[] = [];
+  let current = path;
+  while (!existsSync(current)) { const parent = dirname(current); if (parent === current) break; tail.unshift(basename(current)); current = parent; }
+  return join(realpathSync(current), ...tail);
+}
+/** Caller holds the study lock across every bounded source read. */
+function readBundle(dirArg: string, maxFileBytes: number) {
+  const { dir, study } = openStudy(dirArg);
+  const events = readLedger(dir);
+  const zero = () => Object.fromEntries(STATUSES.map(s => [s, 0])) as Record<AttemptStatus, number>;
+  const byStatus = zero(), runCounts = new Map<string, Record<AttemptStatus, number>>(), attemptLines: string[] = [];
+  let attemptBytes = 0;
+  // One pass; only the projected row and counts outlive each raw record.
+  for (const a of study.mode === "experiment" ? readAttemptRecords(dir) : []) {
+    const line = JSON.stringify(attemptRow(a)) + "\n";
+    attemptBytes += Buffer.byteLength(line);
+    if (attemptBytes > maxFileBytes) throw new Error(`study export: attempts.jsonl would exceed ${maxFileBytes} bytes; nothing was written`);
+    attemptLines.push(line);
+    byStatus[a.status]++;
+    let row = runCounts.get(a.run); if (!row) runCounts.set(a.run, row = zero()); row[a.status]++;
+  }
+  const byRun: Record<string, Record<AttemptStatus, number>> = Object.create(null);
+  for (const [run, row] of [...runCounts].sort(([x], [y]) => x < y ? -1 : 1)) byRun[run] = row;
+  const experiment = study.mode === "experiment", current = experiment ? readProtocol(dir) : undefined, rule = current ? readSelection(dir, current) : undefined;
+  const investigate: Record<string, unknown> = {};
+  if (rule && existsSync(join(dir, "runs", rule.run, "investigate.json"))) investigate[rule.run] = closedResult("investigate", () => readClosedInvestigation(dir));
+  const reviewRows = reviews(events), protocol = study.mode === "experiment" ? readProtocol(dir) : undefined;
+  const lines = (rows: unknown[]) => rows.map(r => JSON.stringify(r)).join("\n") + (rows.length ? "\n" : "");
+  const files: Record<string, string> = {
+    "ledger.jsonl": lines(events.map(reduceEvent)),
+    "attempts.jsonl": attemptLines.join(""),
+    "results.json": JSON.stringify({
+      investigate,
+      ablate: experiment && existsSync(ablateResultPath(dir)) ? closedResult("ablate", () => readClosedAblate(dir)) : null,
+      final: experiment && existsSync(finalResultPath(dir)) ? closedResult("final", () => readClosedFinal(dir)) : null,
+    }, null, 2) + "\n",
+    "reviews.jsonl": lines(reviewRows),
+    "evidence.json": JSON.stringify(evidence(dir), null, 2) + "\n",
+  };
+  const manifest: BundleManifest = {
+    bundle: 1, formats: { ...FORMAT_VERSIONS }, studyIdSha256: sha256(study.id), mode: study.mode,
+    protocolHash: protocol ? protocolHash(protocol) : null, sealBinding: study.mode === "experiment" ? designBinding(dir) ?? null : null,
+    window: (() => { const ats = events.map(e => isoAt(e.at)).filter((v): v is string => v !== null); return { from: ats[0] ?? null, to: ats.at(-1) ?? null }; })(),
+    counts: { attempts: attemptLines.length, byStatus, byRun, ledgerEvents: events.length, reviews: reviewRows.length },
+    files: Object.fromEntries(Object.entries(files).map(([name, text]) => [name, sha256(text)])),
+  };
+  files["manifest.json"] = JSON.stringify(manifest, null, 2) + "\n";
+  return { files, manifest };
+}
+
+/** Read one locked study snapshot, then validate and publish without holding the study lock. */
+export async function exportBundle(dirArg: string, options: { bundle: string; list?: boolean }, maxFileBytes = BUNDLE_FILE_BYTES): Promise<BundleManifest | BundleListing> {
+  const dir = resolve(dirArg), target = resolve(options.bundle), inside = relative(realpathSync(dir), realTarget(target));
+  if (inside === "" || (!(inside === ".." || inside.startsWith(".." + sep)) && !isAbsolute(inside))) throw new Error("study export: --bundle is inside the study directory; choose a directory outside the study");
+  if (options.list) {
+    await withLock(dir, () => openStudy(dir));
+    return { bundle: options.bundle, files: [...BUNDLE_FILES], wouldWrite: true };
+  }
+  const { files, manifest } = await withLock(dir, () => readBundle(dir, maxFileBytes));
+  scanBundle(files);
+  for (const name of BUNDLE_FILES) assertWritable(files[name]!, maxFileBytes, `study export: ${name}; nothing was written`);
+  emptyDir(target);
+  for (const name of BUNDLE_FILES) writeAtomic(join(target, name), files[name]!, maxFileBytes);
+  return manifest;
+}