@staix/vault-mem 0.0.0-stage → 0.1.1

package/src/analysis-reports.ts

@@ -0,0 +1,69 @@
+import type { VaultSpec } from "./config.ts";
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+import { loadRegistry } from "./registry.ts";
+import { analysisRead } from "./analysis-input.ts";
+import { appendLog } from "./vault-log.ts";
+import type { AnalysisSnapshot } from "./analysis-types.ts";
+import type { WriteReceipt } from "./write-types.ts";
+import { applyWrite, sha256 } from "./writer.ts";
+import { analysisInput } from "./analysis-input.ts";
+import { lintVault } from "./vault-lint.ts";
+import { buildGraph, graphReport } from "./vault-graph.ts";
+
+export interface AnalysisRequest { vault: string; kind: "lint" | "graph"; dryRun?: boolean; channel?: "cli" | "mcp"; today?: string; note?: string; expectedVault?: VaultSpec }
+function trend(snapshot: AnalysisSnapshot, nodes: number, edges: number, communities: number, top: string): string {
+  const seed = "---\ntype: report\nkind: graph-trend\n---\n\n# Graph Trend (vault layer)\n\n| 빌드 | Nodes | Edges | Communities | Density | Top hub (degree 1위) |\n|---|---|---|---|---|---|\n";
+  const source = snapshot.reports["graph-trend.md"] ?? seed;
+  const lines = source.trimEnd().split("\n");
+  const density = nodes > 1 ? 2*edges/(nodes*(nodes-1)) : 0;
+  const row = `| ${snapshot.today} | ${nodes} | ${edges} | ${communities} | ${density.toFixed(4)} | ${top ? `\`${top}\`` : "-"} |`;
+  let insert = -1;
+  for (const [i,line] of lines.entries()) if (/^\| (?:\d{4}-\d{2}-\d{2}) \|/.test(line) || line.startsWith("|---")) insert = i;
+  if (insert < 0) { lines.push("", ...seed.trimEnd().split("\n").slice(-2)); insert = lines.length-1; }
+  lines.splice(insert+1,0,row);
+  return lines.join("\n")+"\n";
+}
+export function writeAnalysisReports(home: string, request: AnalysisRequest, env: NodeJS.ProcessEnv = process.env) {
+  const {snapshot,vault,config,identity} = analysisInput(home,request.vault,{today:request.today,expectedVault:request.expectedVault});
+  const binding = {vault,denyPaths:config.denyPaths ?? [],piiPatterns:config.piiPatterns ?? [],dev:Number(identity.dev),ino:Number(identity.ino)};
+  const unchanged = () => {
+    const current = loadRegistry(home), stat = lstatSync(vault.path);
+    if (JSON.stringify(current) !== JSON.stringify(config) || stat.dev !== identity.dev || stat.ino !== identity.ino || stat.isSymbolicLink()) throw new Error("analysis: vault or policy changed during build");
+  };
+  const outputs: {path:string;text:string}[] = [];
+  let summary: unknown;
+  if (request.kind === "lint") {
+    const lint = lintVault(snapshot,request.note); summary = {findings:lint.findings,errors:lint.errors,warnings:lint.warnings,summary:lint.summary};
+    outputs.push({path:`reports/lint-report-${snapshot.today.slice(2).replaceAll("-","")}.md`,text:lint.markdown+"\n"+lint.summary+"\n"});
+  } else {
+    const graph = buildGraph(snapshot), communities = new Set(graph.nodes.flatMap(n => n.community === null ? [] : [n.community])).size;
+    summary = {nodes:graph.nodes.length,edges:graph.edges.length,communities};
+    const top = [...graph.nodes].filter(n => n.type !== "moc").sort((a,b) => b.degree-a.degree || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))[0]?.id ?? "";
+    outputs.push({path:"reports/vault-graph.json",text:JSON.stringify(graph,null,2)+"\n"},
+      {path:`reports/graph-report-${snapshot.today.slice(2).replaceAll("-","")}.md`,text:graphReport(graph,snapshot.today)},
+      {path:"reports/graph-trend.md",text:trend(snapshot,graph.nodes.length,graph.edges.length,communities,top)});
+  }
+  const originals = new Map(outputs.map(out => {
+    const name = out.path.slice("reports/".length);
+    return [out.path, request.kind === "graph" ? snapshot.reports[name] ?? null : analysisRead(join(vault.path,out.path))] as const;
+  }));
+  unchanged();
+  for (const out of outputs) if (analysisRead(join(vault.path,out.path)) !== originals.get(out.path)) throw new Error("analysis: report changed during build");
+  const expectedShas = Object.fromEntries(snapshot.notes.map(n => ["notes/"+n.path.replace(/^notes\//,""),sha256(n.source)]));
+  // Preflight every output through the same validation pipeline, before any output is written.
+  const previews = outputs.map(out => applyWrite(home,{vault:request.vault,operation:{op:"report",...out},dryRun:true,channel:request.channel,expectedShas,log:false},{env}));
+  if (request.dryRun || previews.some(r => !r.ok)) return {ok:previews.every(r => r.ok),applied:false,summary,paths:outputs.map(o => o.path),receipts:previews};
+  const receipts: WriteReceipt[] = [];
+  for (const out of outputs) {
+    unchanged();
+    if (analysisRead(join(vault.path,out.path)) !== originals.get(out.path)) throw new Error("analysis: report changed during build");
+    const receipt = applyWrite(home,{vault:request.vault,operation:{op:"report",...out},channel:request.channel,expectedShas,log:false},{env});
+    receipts.push(receipt);
+    if (!receipt.ok) break;
+  }
+  const complete = receipts.length === outputs.length && receipts.every(r => r.ok);
+  unchanged();
+  const log = complete ? appendLog(home,{vault:request.vault,channel:request.channel,event:{type:request.kind === "lint" ? "LINT" : "GRAPH",project:"-",source:"vmem",dest:outputs[0]!.path,note:request.kind === "lint" ? "Vault lint report" : "Vault graph reports"}},{env,binding}) : undefined;
+  return {ok:complete && log?.ok === true,applied:receipts.some(r => r.applied),summary,paths:outputs.map(o => o.path),receipts,log};
+}

package/src/analysis-types.ts

@@ -0,0 +1,19 @@
+/** Private provider input. Never serialize a snapshot into CLI/MCP results or public evidence. */
+export interface AnalysisSnapshot {
+  notes: { path: string; source: string }[];
+  today: string;
+  logPath: string;
+  log: string | null;
+  registryIds: string[] | null;
+  reports: Record<string, string>;
+  /** Bounded auxiliary source-path existence warnings captured outside the pure lint transform. */
+  sourceWarnings?: Record<string,string[]>;
+}
+export type LintCode = "L01" | "L02" | "L03" | "L09" | "L10" | "L11" | "L12" | "L13" | "L14";
+export interface LintReport {
+  findings: Record<LintCode, string[]>;
+  errors: number;
+  warnings: number;
+  markdown: string;
+  summary: string;
+}

package/src/analysis-yaml.ts

@@ -0,0 +1,178 @@
+import { parseYamlWithQuotedEscapes } from "./yaml-quoted.ts";
+import { randomUUID } from "node:crypto";
+
+/** Preserve Python scalar display and type tests without introducing a YAML runtime dependency. */
+export class AnalysisYamlScalar {
+  constructor(readonly kind: "timestamp" | "float", readonly text: string, readonly truthy = true) {}
+  toString(): string { return this.text; }
+}
+export class AnalysisYamlUnsupported extends Error {
+  constructor(message: string) { super(`analysis YAML: unsupported ${message}`); }
+}
+export function scalarText(value: unknown): string | undefined { return value instanceof AnalysisYamlScalar ? value.text : undefined; }
+export function yamlTruthy(value: unknown): boolean {
+  if (value instanceof AnalysisYamlScalar) return value.truthy;
+  if (Array.isArray(value)) return value.length > 0;
+  if (value !== null && typeof value === "object") return Object.keys(value).length > 0;
+  return Boolean(value);
+}
+function float(value: number): AnalysisYamlScalar {
+  let text: string;
+  if (Number.isNaN(value)) text = "nan";
+  else if (!Number.isFinite(value)) text = value < 0 ? "-inf" : "inf";
+  else if (Object.is(value, -0)) text = "-0.0";
+  else {
+    const absolute = Math.abs(value);
+    text = absolute !== 0 && (absolute < 0.0001 || absolute >= 1e16) ? value.toExponential() : String(value);
+    if (text.includes("e")) text = text.replace(/e([+-]?)(\d+)$/, (_, sign: string, exponent: string) => `e${sign || "+"}${exponent.padStart(2,"0")}`);
+    else if (!text.includes(".")) text += ".0";
+  }
+  return new AnalysisYamlScalar("float",text,value !== 0);
+}
+function integer(value: string): number | bigint {
+  const raw = value.replaceAll("_", ""), sign = raw.startsWith("-") ? -1 : 1, unsigned = raw.replace(/^[+-]/, "");
+  let number: bigint;
+  if (unsigned.includes(":")) number = unsigned.split(":").reduce((n, part) => n * 60n + BigInt(part),0n);
+  else if (/^0[0-7]+$/.test(unsigned)) number = BigInt("0o"+unsigned.slice(1));
+  else number = BigInt(unsigned);
+  number *= BigInt(sign);
+  return number >= BigInt(Number.MIN_SAFE_INTEGER) && number <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(number) : number;
+}
+function timestamp(value: string): AnalysisYamlScalar | null {
+  const match = /^(\d{4})-(\d{1,2})-(\d{1,2})(?:[Tt \t]+(\d{1,2}):(\d{2}):(\d{2})(?:\.(\d*))?(?:[ \t]*(Z|([+-])(\d{1,2})(?::(\d{2}))?))?)?$/.exec(value);
+  if (!match || (!match[4] && !/^\d{4}-\d{2}-\d{2}$/.test(value))) return null;
+  const year = Number(match[1]), month = Number(match[2]), day = Number(match[3]);
+  const date = `${match[1]}-${match[2]!.padStart(2,"0")}-${match[3]!.padStart(2,"0")}`;
+  const parsed = new Date(date + "T00:00:00Z");
+  if (year < 1 || month < 1 || day < 1 || !Number.isFinite(parsed.getTime()) || parsed.toISOString().slice(0,10) !== date) throw new Error("analysis YAML: invalid timestamp");
+  if (!match[4]) return new AnalysisYamlScalar("timestamp",date);
+  if (Number(match[4]) > 23 || Number(match[5]) > 59 || Number(match[6]) > 59) throw new Error("analysis YAML: invalid timestamp");
+  const fraction = (match[7] ?? "").slice(0,6).padEnd(6,"0");
+  let zone = "";
+  if (match[8]) {
+    const minutes = match[8] === "Z" ? 0 : Number(match[10]) * 60 + Number(match[11] ?? 0);
+    if (minutes >= 24*60) throw new Error("analysis YAML: invalid timestamp timezone");
+    zone = `${minutes === 0 || match[9] !== "-" ? "+" : "-"}${String(Math.floor(minutes/60)).padStart(2,"0")}:${String(minutes%60).padStart(2,"0")}`;
+  }
+  return new AnalysisYamlScalar("timestamp",`${date} ${match[4]!.padStart(2,"0")}:${match[5]}:${match[6]}${Number(fraction) ? "."+fraction : ""}${zone}`);
+}
+function resolveScalar(value: string): unknown {
+  if (/^(?:yes|Yes|YES|true|True|TRUE|on|On|ON)$/.test(value)) return true;
+  if (/^(?:no|No|NO|false|False|FALSE|off|Off|OFF)$/.test(value)) return false;
+  if (/^(?:~|null|Null|NULL)$/.test(value)) return null;
+  if (/^(?:[-+]?(?:[0-9][0-9_]*)\.[0-9_]*(?:[eE][-+][0-9]+)?|\.[0-9][0-9_]*(?:[eE][-+][0-9]+)?|[-+]?[0-9][0-9_]*(?::[0-5]?[0-9])+\.[0-9_]*|[-+]?\.(?:inf|Inf|INF)|\.(?:nan|NaN|NAN))$/.test(value)) {
+    const raw = value.replaceAll("_", "");
+    const number = /nan/i.test(raw) ? NaN : /inf/i.test(raw) ? (raw.startsWith("-") ? -Infinity : Infinity)
+      : raw.includes(":") ? raw.replace(/^[+-]/,"").split(":").reduce((n,part)=>n*60+Number(part),0)*(raw.startsWith("-")?-1:1) : Number(raw);
+    return float(number);
+  }
+  if (/^(?:[-+]?0b[0-1_]+|[-+]?0[0-7_]+|[-+]?(?:0|[1-9][0-9_]*)|[-+]?0x[0-9a-fA-F_]+|[-+]?[1-9][0-9_]*(?::[0-5]?[0-9])+)$/.test(value)) return integer(value);
+  return timestamp(value) ?? value;
+}
+
+/** Resolve YAML 1.1 plain scalars, leaving quoted and literal/folded strings byte-for-byte to Bun. */
+export function parseAnalysisYaml(source: string): unknown {
+  const prefix = `vmem-yaml-${randomUUID()}-`, replacements = new Map<string,unknown>();
+  let out = "", offset = 0, flow = 0, blockIndent: number | null = null;
+  let lineIndent = 0, effectiveIndent = 0, atLineStart = true, mappingOnLine = false, previousPlain: number | null = null;
+  const placeholder = (token: string): string => { const key = prefix+replacements.size; replacements.set(key,resolveScalar(token)); return JSON.stringify(key); };
+  while (offset < source.length) {
+    if (atLineStart) {
+      const end = source.indexOf("\n",offset), line = source.slice(offset,end === -1 ? undefined : end);
+      lineIndent = line.match(/^[ \t]*/)![0].length; effectiveIndent = lineIndent;mappingOnLine=false;
+      if (blockIndent !== null && (!line.trim() || lineIndent > blockIndent)) { out += line; offset += line.length; if (source[offset] === "\n") { out += "\n";offset++; } continue; }
+      blockIndent = null;
+      if (previousPlain !== null && line.trim() && !line.trimStart().startsWith("#") && lineIndent > previousPlain && !flow) throw new AnalysisYamlUnsupported("multiline plain scalar (use a quoted or block scalar)");
+      if (line.trim() && !line.trimStart().startsWith("#")) previousPlain = null;
+      atLineStart = false;
+    }
+    const character = source[offset]!;
+    if (character === "\n") { out += character;offset++;atLineStart = true;continue; }
+    if (/[ \t\r]/.test(character)) { out += character;offset++;continue; }
+    if (character === "#") { const end = source.indexOf("\n",offset); const stop = end === -1 ? source.length : end; out += source.slice(offset,stop);offset=stop;continue; }
+    if (character === '"' || character === "'") {
+      const start = offset++, quote = character;
+      while (offset < source.length) {
+        const next = source[offset++]!;
+        if (quote === '"' && next === "\\") { offset++;continue; }
+        if (next === quote) { if (quote === "'" && source[offset] === "'") {offset++;continue;} break; }
+      }
+      out += source.slice(start,offset);continue;
+    }
+    if (!flow && (character === "|" || character === ">") && /^(?:[|>])(?:[+-][1-9]?|[1-9][+-]?)?[ \t]*(?:#[^\n]*)?\r?(?:\n|$)/.test(source.slice(offset))) {
+      const end = source.indexOf("\n",offset), stop = end === -1 ? source.length : end;
+      out += source.slice(offset,stop);offset=stop;blockIndent=mappingOnLine ? effectiveIndent : lineIndent;previousPlain=null;continue;
+    }
+    if (character === "!") throw new AnalysisYamlUnsupported("explicit tags");
+    if (character === "?" && /\s/.test(source[offset+1] ?? "\n")) throw new AnalysisYamlUnsupported("complex mapping keys");
+    if (character === "&" || character === "*") { const match = /^[&*][^\s,[\]{}]+/.exec(source.slice(offset)); if (!match) throw new Error("analysis YAML: invalid anchor");out+=match[0];offset+=match[0].length;continue; }
+    if ("[{".includes(character)) { flow++;out+=character;offset++;previousPlain=null;continue; }
+    if ("]}".includes(character)) { flow--;out+=character;offset++;continue; }
+    if ((flow && character === ",") || character === ":") { if(character === ":" && !flow)mappingOnLine=true;out+=character;offset++;previousPlain=null;continue; }
+    if (!flow && character === "-" && /\s/.test(source[offset+1] ?? "\n")) { out+=character;offset++;effectiveIndent=offset-(source.lastIndexOf("\n",offset-1)+1)+1;previousPlain=null;continue; }
+    const start = offset;
+    while (offset < source.length) {
+      const next = source[offset]!;
+      if (next === "\n" || (flow && ",[]{}".includes(next)) || (next === ":" && /[\s,\]}]/.test(source[offset+1] ?? "\n")) || (next === "#" && /\s/.test(source[offset-1] ?? " "))) break;
+      offset++;
+    }
+    if (offset === start) throw new Error("analysis YAML: invalid token");
+    const raw = source.slice(start,offset);
+    let token = raw.trimEnd(), consumed = offset;
+    if (source[offset] === "\n") {
+      let cursor=offset, blanks=0;
+      while(source[cursor] === "\n") {
+        const next=cursor+1, end=source.indexOf("\n",next), line=source.slice(next,end===-1 ? undefined : end), indent=line.match(/^[ \t]*/)![0].length;
+        if(!line.trim()) {blanks++;cursor=end===-1 ? source.length : end;continue;}
+        if ((!flow && indent <= effectiveIndent) || line.trimStart().startsWith("#") || (flow && /^[,\]}]/.test(line.trimStart()))) break;
+        const stop = flow ? line.search(/[,\]}]/) : -1;
+        const part=(stop===-1 ? line : line.slice(0,stop)).trim();
+        if (!part || /:\s|\s#/.test(part)) break;
+        token+=(blanks ? "\n".repeat(blanks) : " ")+part;blanks=0;
+        consumed=stop===-1 ? next+line.length : next+stop;
+        cursor=consumed;
+        if(stop!==-1)break;
+      }
+    }
+    if (token === "---" || token === "..." || token.startsWith("%")) throw new AnalysisYamlUnsupported("document directives or multiple documents");
+    out += placeholder(token)+(consumed===offset ? raw.slice(token.length) : "");
+    offset=consumed;
+    if (!flow && source[offset] !== ":") previousPlain=effectiveIndent;
+  }
+  let parsed: unknown;
+  try { parsed=parseYamlWithQuotedEscapes(out); }
+  catch(error) {
+    try { parseYamlWithQuotedEscapes(source); } catch { throw error; }
+    throw new AnalysisYamlUnsupported("plain scalar layout (use a quoted or block scalar)");
+  }
+  const active = new Set<object>();
+  function restore(value: unknown, depth: number): unknown {
+    if (depth > 64) throw new AnalysisYamlUnsupported("nesting deeper than 64 levels");
+    if (typeof value === "string") return replacements.has(value) ? replacements.get(value) : value;
+    if (value === null || typeof value !== "object") return value;
+    if (active.has(value)) throw new AnalysisYamlUnsupported("recursive aliases");
+    active.add(value);
+    let result: unknown;
+    if (Array.isArray(value)) result=value.map(item=>restore(item,depth+1));
+    else {
+      const mapping: Record<string,unknown> = Object.create(null) as Record<string,unknown>;
+      const explicit:[string,unknown][]=[];
+      for (const [key,item] of Object.entries(value)) {
+        const resolvedKey=restore(key,depth+1);
+        if (typeof resolvedKey !== "string") throw new AnalysisYamlUnsupported("non-string mapping keys");
+        const restored=restore(item,depth+1);
+        if (replacements.get(key)==="<<") {
+          const merged=Array.isArray(restored) ? [...restored].reverse() : [restored];
+          for(const entry of merged) {
+            if(entry===null || typeof entry!=="object" || Array.isArray(entry) || entry instanceof AnalysisYamlScalar)throw new Error("analysis YAML: merge source must be a mapping");
+            Object.assign(mapping,entry);
+          }
+        } else explicit.push([resolvedKey,restored]);
+      }
+      for(const [key,item] of explicit)mapping[key]=item;
+      result=mapping;
+    }
+    active.delete(value);return result;
+  }
+  return restore(parsed,0);
+}

package/src/cli.ts

@@ -0,0 +1,101 @@
+import { runAnalysisCommand } from "./analysis-commands.ts";
+import { runLogCommand } from "./log-commands.ts";
+import { runOrgCommand } from "./org-commands.ts";
+import { isWriteCommand, runWriteCommand } from "./write-commands.ts";
+import { isReadCommand, runReadCommand } from "./read-commands.ts";
+import { version } from "../package.json";
+import { completionScript, help } from "./commands-table.ts";
+import { runSetup, type SetupMode } from "./setup.ts";
+import { resolveHome } from "./home.ts";
+import { addVault, effectivePii, loadRegistry, recoverRegistry, registryStatus, removeVault } from "./registry.ts";
+function parse(args: string[], allowed: string[], values: string[]) {
+  const flags: Record<string, string | boolean> = {}, positional: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const word = args[i]!;
+    if (!word.startsWith("-")) { positional.push(word); continue; }
+    if (!allowed.includes(word) || word in flags) throw new Error(`unknown or repeated option: ${word}`);
+    if (values.includes(word)) {
+      const value = args[++i];
+      if (!value || value.startsWith("--")) throw new Error(`${word}: value required`);
+      flags[word] = value;
+    } else flags[word] = true;
+  }
+  return { flags, positional };
+}
+export function run(args: string[], env: NodeJS.ProcessEnv = process.env): { text: string; code: number } {
+  if (!args.length || (args.length === 1 && ["--help", "-h", "help"].includes(args[0]!))) return { text: help(), code: 0 };
+  if (args.length === 1 && args[0] === "--version") return { text: version, code: 0 };
+  if (args[0] === "setup") {
+    const rest = args.slice(1), flags = rest.filter(a => a.startsWith("--")), positional = rest.filter(a => !a.startsWith("--"));
+    if (positional.length !== 1 || flags.some(f => !["--apply", "--undo", "--json"].includes(f)) || new Set(flags).size !== flags.length || (flags.includes("--apply") && flags.includes("--undo"))) throw new Error("setup: requires one target and at most one of --apply/--undo");
+    const mode: SetupMode = flags.includes("--apply") ? "apply" : flags.includes("--undo") ? "undo" : "dry-run";
+    const report = runSetup(positional[0]!, mode, { home: resolveHome(env).home, env });
+    return { text: JSON.stringify(report, null, flags.includes("--json") ? undefined : 2), code: report.actions.some(a => a.change === "refused") ? 1 : 0 };
+  }
+  if (args[0] === "completion") {
+    if (args.length !== 2) throw new Error("completion: requires bash, zsh or fish");
+    return { text: completionScript(args[1]!).trimEnd(), code: 0 };
+  }
+  if (args[0] === "lint" || args[0] === "graph") return runAnalysisCommand(args[0],args.slice(1),resolveHome(env).home,env);
+  if (args[0] === "promote" || args[0] === "sync") return runOrgCommand(args[0], args.slice(1), resolveHome(env).home, env);
+  if (args[0] === "log") return runLogCommand(args.slice(1), resolveHome(env).home, env);
+  if (isWriteCommand(args[0]!)) return runWriteCommand(args[0]!, args.slice(1), resolveHome(env).home, env);
+  if (isReadCommand(args[0]!)) return runReadCommand(args[0]!, args.slice(1), resolveHome(env).home);
+  const command = args[0] === "vaults" ? `vaults ${args[1] ?? ""}` : args[0];
+  const tail = args.slice(args[0] === "vaults" ? 2 : 1);
+  const options = command === "vaults add" ? ["--kind", "--write", "--pii", "--remote", "--registry"] : [];
+  const { flags, positional } = parse(tail, ["--json", ...options, ...(command === "vaults remove" || command === "recover" ? ["--confirm"] : [])], options);
+  const home = resolveHome(env);
+  let result: unknown, code = 0;
+  switch (command) {
+    case "status": case "doctor": {
+      if (positional.length) throw new Error(`${command}: unexpected arguments`);
+      const vaults = registryStatus(home.home), healthy = vaults.every(v => v.healthy);
+      result = { ...home, version, stage: "foundation", healthy, vaults };
+      if (command === "doctor" && !healthy) code = 1;
+      break;
+    }
+    case "recover":
+      if (positional.length) throw new Error("recover: unexpected arguments");
+      result = recoverRegistry(home.home, flags["--confirm"] === true);
+      if ((result as { blocked?: string }).blocked) code = 1;
+      break;
+    case "vaults list":
+      if (positional.length) throw new Error("vaults list: unexpected arguments");
+      result = loadRegistry(home.home).vaults.map(v => ({ ...v, pii: effectivePii(v) }));
+      break;
+    case "vaults add": {
+      if (positional.length !== 2) throw new Error("vaults add: requires id and absolute path");
+      const value: Record<string, unknown> = { id: positional[0], path: positional[1] };
+      for (const option of options) if (flags[option] !== undefined) value[option.slice(2)] = flags[option];
+      result = { applied: true, vault: addVault(home.home, value) };
+      break;
+    }
+    case "vaults remove":
+      if (positional.length !== 1) throw new Error("vaults remove: requires id");
+      result = removeVault(home.home, positional[0]!, flags["--confirm"] === true);
+      break;
+    default: throw new Error(`unknown command: ${command}; use --help`);
+  }
+  return { text: JSON.stringify(result, null, flags["--json"] ? undefined : 2), code };
+}
+/** `vmem mcp`: the vault set is fixed now; stdout carries protocol frames only. */
+export async function runMcp(env: NodeJS.ProcessEnv = process.env): Promise<void> {
+  const [{ serveMcp }, { createVaultMcp }] = await Promise.all([import("./mcp.ts"), import("./mcp-vault.ts")]);
+  const server = createVaultMcp(resolveHome(env).home, env);
+  await serveMcp({ tools: server.tools, handlers: server.handlers, name: "vmem", version });
+}
+/** Async commands. Only `promote-from-amem` loads the agent-mem seam, and only when it runs. */
+export async function runAsync(args: string[], env: NodeJS.ProcessEnv = process.env, io: { stdinIsTTY?: boolean } = {}): Promise<{ text: string; code: number }> {
+  if (args[0] !== "promote-from-amem") return run(args, env);
+  const { runPromoteCommand } = await import("./promote-command.ts");
+  return runPromoteCommand(args.slice(1), resolveHome(env).home, env, io);
+}
+export async function mainAsync(args: string[]): Promise<number> {
+  try { const output = await runAsync(args, process.env, { stdinIsTTY: process.stdin.isTTY === true }); console.log(output.text); return output.code; }
+  catch (error) { console.error(`vmem: ${error instanceof Error ? error.message : "operation failed"}`); return 1; }
+}
+export function main(args: string[]): number {
+  try { const output = run(args); console.log(output.text); return output.code; }
+  catch (error) { console.error(`vmem: ${error instanceof Error ? error.message : "operation failed"}`); return 1; }
+}

package/src/commands-table.ts

@@ -0,0 +1,88 @@
+export const COMMANDS = [
+  { name: "lint", usage: "lint <vault> [--note PATH] [--write] [--dry-run] [--json]", mutates: "write" },
+  { name: "graph build", usage: "graph build <vault> [--dry-run] [--json]", mutates: true },
+  { name: "graph neighbors", usage: "graph neighbors <vault> <stem> [--hops 1..2] [--limit 1..500] [--json]", mutates: false },
+  { name: "rebuild", usage: "rebuild <vault> [--json]", mutates: "cache" },
+  { name: "search", usage: "search <vault> <query> [--type TYPE] [--domain DOMAIN] [--limit 1..500] [--json]", mutates: "cache" },
+  { name: "show", usage: "show <vault> <target> [--section TEXT] [--offset 0..2097152] [--max-bytes 1..65536] [--json]", mutates: "cache" },
+  { name: "links", usage: "links <vault> <target> [--limit 1..500] [--json]", mutates: "cache" },
+  { name: "status", usage: "status [--json]", mutates: false },
+  { name: "doctor", usage: "doctor [--json]", mutates: false },
+  { name: "recover", usage: "recover [--confirm] [--json]", mutates: "confirm" },
+  { name: "vaults list", usage: "vaults list [--json]", mutates: false },
+  { name: "vaults add", usage: "vaults add <id> <absolute-path> --kind personal|org --write mcp|cli|none [--pii allow|deny] [--remote URL] [--registry PATH] [--json]", mutates: true },
+  { name: "vaults remove", usage: "vaults remove <id> [--confirm] [--json]", mutates: "confirm" },
+  { name: "new", usage: "new <vault> <stem> --type TYPE --domain DOMAIN --topics a,b --description TEXT [--title TEXT] [--source TEXT|JSON] [--confidence TEXT] [--status TEXT] [--body file|-] [--extra JSON] [--dry-run] [--json]", mutates: true },
+  { name: "patch", usage: "patch <vault> <note> --old TEXT --new TEXT [--expected-sha SHA] [--dry-run] [--json]", mutates: true },
+  { name: "append", usage: "append <vault> <note> --section SECTION --markdown TEXT [--expected-sha SHA] [--dry-run] [--json]", mutates: true },
+  { name: "frontmatter", usage: "frontmatter <vault> <note> [--set JSON] [--unset key,key] [--expected-sha SHA] [--dry-run] [--json]", mutates: true },
+  { name: "link", usage: "link <vault> <from> <to> --relation R [--context TEXT] [--one-way] [--dry-run] [--json]", mutates: true },
+  { name: "supersede", usage: "supersede <vault> <old> <next> [--dry-run] [--json]", mutates: true },
+  { name: "move", usage: "move <vault> <from> <to> [--confirm --fingerprint SHA] [--dry-run] [--json]", mutates: "confirm" },
+  { name: "delete", usage: "delete <vault> <note> [--confirm --fingerprint SHA] [--dry-run] [--json]", mutates: "confirm" },
+  { name: "tidy", usage: "tidy <vault> [--connections] [--escapes] [--enums] [--keys] [--sources] [--topics] [--secrets] [--log] [--all] [--map file] [--confirm --fingerprint SHA] [--dry-run] [--json]", mutates: "confirm" },
+  { name: "report", usage: "report <vault> <reports/path|ops/path> --body file|- [--dry-run] [--json]", mutates: true },
+  { name: "check", usage: "check <vault> <file|-> [--path stem] [--json]", mutates: false },
+  { name: "log tail", usage: "log tail <vault> [--limit 1..200] [--type TYPE] [--json]", mutates: false },
+  { name: "log grep", usage: "log grep <vault> <pattern> [--limit 1..200] [--type TYPE] [--json]", mutates: false },
+  { name: "log append", usage: "log append <vault> <TYPE> <project> <source> <note> [--dest PATH] [--json]", mutates: true },
+  { name: "promote-from-amem", usage: "promote-from-amem <vault> [<mem-id>] [--project KEY|--all-projects] [--limit 1..200] [--stem STEM] [--type TYPE] [--domain DOMAIN] [--topics a,b] [--description TEXT] [--title TEXT] [--body file|-] [--link-to NOTE] [--log-project ID] [--edit] [--confirm --fingerprint SHA] [--json]", mutates: "confirm" },
+  { name: "promote", usage: "promote <personal-vault> <note> --to ORG [--topics a,b] [--again] [--log-project ID] [--confirm --fingerprint SHA] [--json]", mutates: "confirm" },
+  { name: "sync", usage: "sync <vault> [--message TEXT] [--confirm --fingerprint SHA] [--json]", mutates: "confirm" },
+  { name: "mcp", usage: "mcp", mutates: false },
+  { name: "setup", usage: "setup <claude|codex|kimi|pi|qwen|jcode|agy|all> [--apply|--undo] [--json]", mutates: "apply" },
+  { name: "completion", usage: "completion <bash|zsh|fish>", mutates: false },
+] as const;
+const RELATIONS = ["supports", "contradicts", "extends", "applies-to", "context-for"] as const;
+const LOG_EVENT_TYPES = ["INGEST", "ROUTE", "EXTRACT", "CONNECT", "DIGEST", "LEARN", "LINT", "TASK", "GRAPH", "SYNC", "RETHINK", "SOURCE"] as const;
+const VALUE = /^--[a-z-]+ (?!\.\.\.)([A-Z]|[a-z0-9.|,-]+|file\|-|JSON|SHA|URL|PATH|TEXT)/;
+export interface CompletionDefinition { path: string[]; options: Record<string, { value?: string | string[] }>; args: string[] }
+/** Completion metadata derived from the usage strings, so help and completion cannot drift. */
+export function completionDefinitions(): CompletionDefinition[] {
+  return COMMANDS.map(command => {
+    const words = command.name.split(" "), usage = command.usage.slice(command.name.length).trim();
+    const options: CompletionDefinition["options"] = {}, args: string[] = [];
+    for (const match of usage.matchAll(/--[a-z-]+(?: (?:[A-Za-z0-9.|,/][A-Za-z0-9.|,/-]*|-(?![-\w])))?|<([^>]+)>/g)) {
+      if (match[1] !== undefined) { args.push(match[1]); continue; }
+      const [flag, value] = match[0].split(" ") as [string, string | undefined];
+      if (Object.hasOwn(options, flag)) continue;
+      const nextFlag = value?.startsWith("--");
+      options[flag] = value && !nextFlag && VALUE.test(match[0]) ? { value: /^[a-z]+(\|[a-z]+)+$/.test(value) ? value.split("|") : value } : {};
+    }
+    if (!["mcp", "completion"].includes(command.name)) options["--json"] ??= {};
+    if (options["--relation"]) options["--relation"] = { value: [...RELATIONS] };
+    if (command.name.startsWith("log ") && options["--type"]) options["--type"] = { value: [...LOG_EVENT_TYPES] };
+    return { path: words, options, args };
+  });
+}
+/** Static completion script. Lists subcommands, then the options of the typed command. */
+export function completionScript(shell: string): string {
+  if (!["bash", "zsh", "fish"].includes(shell)) throw new Error("completion: use bash, zsh or fish");
+  const defs = completionDefinitions(), top = [...new Set(defs.map(d => d.path[0]!))].sort();
+  const quote = (text: string) => `'${text.replace(/'/g, `'"'"'`)}'`;
+  if (shell === "fish") {
+    const lines = [`complete -c vmem -f`, `complete -c vmem -n '__fish_use_subcommand' -a ${quote(top.join(" "))}`];
+    for (const d of defs) {
+      const cond = d.path.length === 1 ? `__fish_seen_subcommand_from ${d.path[0]}` : `__fish_seen_subcommand_from ${d.path[1]}`;
+      for (const flag of Object.keys(d.options)) lines.push(`complete -c vmem -n ${quote(cond)} -l ${flag.slice(2)}`);
+    }
+    for (const parent of ["vaults", "log", "graph"]) lines.push(`complete -c vmem -n '__fish_seen_subcommand_from ${parent}' -a ${quote(defs.filter(d => d.path[0] === parent).map(d => d.path[1]).join(" "))}`);
+    return lines.join("\n") + "\n";
+  }
+  const cases = defs.map(d => `    ${quote(d.path.join(" "))}) words=${quote(Object.keys(d.options).join(" "))} ;;`);
+  const fn = `_vmem() {
+  local cur key words
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=($(compgen -W ${quote(top.join(" "))} -- "$cur")); return; fi
+  key="\${COMP_WORDS[1]}"
+  case "$key" in graph) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'build neighbors' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; vaults|log) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W "$( [ "$key" = vaults ] && echo 'list add remove' || echo 'tail grep append')" -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; esac
+  case "$key" in
+${cases.join("\n")}
+    *) words='' ;;
+  esac
+  COMPREPLY=($(compgen -W "$words" -- "$cur"))
+}
+`;
+  return shell === "zsh" ? `autoload -U +X bashcompinit && bashcompinit\n${fn}complete -F _vmem vmem\n` : `${fn}complete -F _vmem vmem\n`;
+}
+export function help(): string { return "vmem - validated knowledge vaults for agents and people\n\n" + COMMANDS.map(c => `  vmem ${c.usage}`).join("\n") + "\n\n  vmem --help | --version\n"; }

package/src/config.ts

@@ -0,0 +1,99 @@
+import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
+export const CONFIG_FILE = "vmem.config.json";
+export const MAX_CONFIG_BYTES = 64 * 1024;
+export interface VaultSpec {
+  id: string;
+  path: string;
+  kind: "personal" | "org";
+  write: "mcp" | "cli" | "none";
+  pii?: "allow" | "deny";
+  remote?: string;
+  registry?: string;
+}
+export interface VmemConfig { home?: string; vaults: VaultSpec[]; denyPaths?: string[]; piiPatterns?: string[] }
+const controls = /[\x00-\x1f\x7f]/;
+function object(value: unknown, keys: string[], label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label}: expected object`);
+  const record = value as Record<string, unknown>;
+  for (const key of Object.keys(record)) if (!keys.includes(key)) throw new Error(`${label}: unknown key ${key}`);
+  return record;
+}
+function string(value: unknown, label: string): string {
+  if (typeof value !== "string" || !value.trim() || controls.test(value)) throw new Error(`${label}: expected nonempty string without control characters`);
+  return value;
+}
+export function absolute(value: unknown, label: string): string {
+  const text = string(value, label);
+  if (!isAbsolute(text)) throw new Error(`${label}: expected absolute path`);
+  return text;
+}
+function strings(value: unknown, label: string): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length > 64) throw new Error(`${label}: expected at most 64 strings`);
+  return value.map((item) => {
+    const text = string(item, label);
+    if (Buffer.byteLength(text) > 256) throw new Error(`${label}: item exceeds 256 bytes`);
+    return text;
+  });
+}
+export function parseVault(value: unknown): VaultSpec {
+  const v = object(value, ["id", "path", "kind", "write", "pii", "remote", "registry"], "vault");
+  const id = string(v.id, "vault.id");
+  if (!/^[a-z][a-z0-9-]{0,31}$/.test(id)) throw new Error("vault.id: invalid id");
+  if (v.kind !== "personal" && v.kind !== "org") throw new Error("vault.kind: expected personal or org");
+  if (v.write !== "mcp" && v.write !== "cli" && v.write !== "none") throw new Error("vault.write: expected mcp, cli or none");
+  const result: VaultSpec = { id, path: absolute(v.path, "vault.path"), kind: v.kind, write: v.write };
+  if (v.pii !== undefined) {
+    if (v.pii !== "allow" && v.pii !== "deny") throw new Error("vault.pii: expected allow or deny");
+    result.pii = v.pii;
+  }
+  if (v.remote !== undefined) result.remote = string(v.remote, "vault.remote");
+  if (v.registry !== undefined) result.registry = absolute(v.registry, "vault.registry");
+  return result;
+}
+export function parseConfig(value: unknown): VmemConfig {
+  const raw = object(value, ["home", "vaults", "denyPaths", "piiPatterns"], "config");
+  if (raw.home !== undefined) {
+    if (Object.keys(raw).length !== 1) throw new Error("config: home pointer must not contain vaults or policy");
+    return { home: absolute(raw.home, "config.home"), vaults: [] };
+  }
+  if (!Array.isArray(raw.vaults)) throw new Error("config.vaults: expected array");
+  const vaults = raw.vaults.map(parseVault);
+  if (new Set(vaults.map(v => v.id)).size !== vaults.length) throw new Error("config: duplicate vault id");
+  if (new Set(vaults.map(v => v.path)).size !== vaults.length) throw new Error("config: duplicate vault path");
+  const denyPaths = strings(raw.denyPaths, "denyPaths"), piiPatterns = strings(raw.piiPatterns, "piiPatterns");
+  for (const pattern of piiPatterns ?? []) {
+    try { new RegExp(pattern); } catch { throw new Error("piiPatterns: invalid regular expression"); }
+  }
+  return { vaults, ...(denyPaths ? { denyPaths } : {}), ...(piiPatterns ? { piiPatterns } : {}) };
+}
+/** Bounded descriptor read: reject links, devices and oversized/growing files. */
+export function readConfig(home: string): VmemConfig {
+  const file = join(home, CONFIG_FILE);
+  let fd: number;
+  try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { vaults: [] };
+    throw new Error(`${file}: cannot read plain config file`, { cause: error });
+  }
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > MAX_CONFIG_BYTES) throw new Error(`${file}: expected plain file <= ${MAX_CONFIG_BYTES} bytes`);
+    const buffer = Buffer.alloc(MAX_CONFIG_BYTES + 1);
+    let size = 0;
+    while (size < buffer.length) {
+      const n = readSync(fd, buffer, size, buffer.length - size, null);
+      if (!n) break;
+      size += n;
+    }
+    if (size > MAX_CONFIG_BYTES) throw new Error(`${file}: config too large`);
+    let parsed: unknown;
+    // Do not echo parser messages: they can quote config content.
+    try { parsed = JSON.parse(buffer.subarray(0, size).toString("utf8")); }
+    catch { throw new Error(`${file}: invalid JSON`); }
+    try { return parseConfig(parsed); }
+    catch (error) { throw new Error(`${file}: ${error instanceof Error ? error.message : "invalid config"}`, { cause: error }); }
+  } finally { closeSync(fd); }
+}