@staix/vault-mem 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/README.md +19 -6
  3. package/bin/vmem.js +2 -2
  4. package/package.json +2 -2
  5. package/src/analysis-commands.ts +24 -14
  6. package/src/analysis-input.ts +12 -0
  7. package/src/analysis-types.ts +5 -1
  8. package/src/assert-command.ts +48 -0
  9. package/src/assertion-exposure.ts +367 -0
  10. package/src/assertion-index.ts +86 -0
  11. package/src/assertion-policy.ts +63 -0
  12. package/src/assertion-read.ts +170 -0
  13. package/src/assertions-command.ts +123 -0
  14. package/src/assertions.ts +1013 -0
  15. package/src/cli-output.ts +9 -3
  16. package/src/cli.ts +44 -23
  17. package/src/commands-table.ts +16 -2
  18. package/src/evidence.ts +222 -0
  19. package/src/graph-evidence.ts +169 -0
  20. package/src/index.ts +14 -0
  21. package/src/links.ts +18 -0
  22. package/src/log-commands.ts +7 -7
  23. package/src/mcp-spec.ts +11 -11
  24. package/src/mcp-vault.ts +105 -6
  25. package/src/mcp.ts +4 -0
  26. package/src/org-commands.ts +5 -5
  27. package/src/org-promote.ts +9 -0
  28. package/src/promote-command.ts +6 -6
  29. package/src/proposal-commands.ts +100 -0
  30. package/src/proposal-provider.ts +335 -0
  31. package/src/proposal-storage.ts +334 -0
  32. package/src/proposals.ts +170 -0
  33. package/src/read-commands.ts +44 -12
  34. package/src/read-output.ts +42 -14
  35. package/src/skills-mine.ts +12 -7
  36. package/src/source-age.ts +131 -0
  37. package/src/spec-output.ts +14 -13
  38. package/src/sync.ts +14 -7
  39. package/src/text-output.ts +86 -21
  40. package/src/vault-brief.ts +8 -4
  41. package/src/vault-graph.ts +12 -3
  42. package/src/vault-history.ts +662 -0
  43. package/src/vault-index.ts +2 -0
  44. package/src/vault-lint.ts +15 -4
  45. package/src/write-commands.ts +18 -17
  46. package/src/write-output.ts +6 -6
  47. package/src/write-types.ts +1 -0
  48. package/src/write-validation.ts +3 -1
  49. package/src/writer.ts +257 -11
@@ -8,7 +8,9 @@ import type { LogReadResult, LogReceipt } from "./log-types.ts";
8
8
  import type { LintCode, LintReport } from "./analysis-types.ts";
9
9
  import type { GraphNeighborhood, GraphPath } from "./vault-graph.ts";
10
10
  import type { WriteIssue, WriteReceipt } from "./write-types.ts";
11
- import { blocks, clean, fields, heading, issueTable, nextCommand, paint, paragraph, plural, shellWord, table, tone, type CellInput, type TextOptions, stripTerminal } from "./text-output.ts";
11
+ import type { EvidenceReport } from "./evidence.ts";
12
+ import type { GraphExplanation } from "./graph-evidence.ts";
13
+ import { blocks, clean, fields, heading, issueTable, marker, nextCommand, paint, paragraph, plural, shellWord, status, summary, table, tableParts, tone, type CellInput, type TextOptions, stripTerminal } from "./text-output.ts";
12
14
 
13
15
  const command = (...words: string[]) => ["vmem", ...words].map(shellWord).join(" ");
14
16
 
@@ -16,7 +18,7 @@ export function searchText(hits: SearchResult[], o: TextOptions, c: { vault: str
16
18
  const count = `${plural(hits.length, "result")} for ${JSON.stringify(clean(c.query))}`;
17
19
  if (!hits.length) return count;
18
20
  // Rows stay on one line so each snippet sits under its own hit.
19
- const rows = table(["PATH", "TITLE", "TYPE"], hits.map(h => [h.path, h.title, h.type]), { ...o, columns: undefined }).split("\n");
21
+ const rows = tableParts(["PATH", "TITLE", "TYPE"], hits.map(h => [h.path, h.title, h.type]), { ...o, columns: undefined });
20
22
  const list = [rows[0]!, ...hits.flatMap((h, i) => [rows[i + 1]!, ...(stripTerminal(h.snippet).trim() ? [paragraph(stripTerminal(h.snippet).trim(), o, "muted", " ")] : [])])].join("\n");
21
23
  const filters = [...(c.type ? ["--type", c.type] : []), ...(c.domain ? ["--domain", c.domain] : [])];
22
24
  const more = hits.length >= c.limit && c.limit < 500 ? nextCommand("next", command("search", c.vault, c.query, ...filters, "--limit", String(Math.min(500, c.limit * 2))), o) : undefined;
@@ -27,7 +29,7 @@ export function showText(r: NoteReadResult, o: TextOptions, c: { vault: string;
27
29
  const head = [heading(r.path, o), fields([["section", r.section], ["sha256", r.hash.slice(0, 12)], ["bytes", Buffer.byteLength(r.content)], ["offset", r.offset]], o)].join("\n");
28
30
  if (!r.truncated) return blocks(head, stripTerminal(r.content).replace(/\n+$/, ""));
29
31
  const words = ["show", c.vault, c.target, ...(r.section ? ["--section", r.section] : []), ...(c.maxBytes !== undefined ? ["--max-bytes", String(c.maxBytes)] : []), "--offset", String(r.nextOffset)];
30
- const tail = [paint("truncated", "warn", o), ...(r.nextOffset !== undefined ? [nextCommand("next", command(...words), o)] : [])];
32
+ const tail = [status("warn", "truncated", o), ...(r.nextOffset !== undefined ? [nextCommand("next", command(...words), o)] : [])];
31
33
  const headings = r.headings?.length ? ["H2 headings (read one with --section):", ...r.headings.map(h => ` ${clean(h)}`), ...(r.headingsTruncated ? [paint(" ... more headings", "muted", o)] : [])].join("\n") : undefined;
32
34
  return blocks(head, stripTerminal(r.content).replace(/\n+$/, ""), tail.join("\n"), headings);
33
35
  }
@@ -38,7 +40,7 @@ export function linksText(links: SuggestedLink[], o: TextOptions, c: { vault: st
38
40
  const count = `${plural(links.length, "link")} from ${clean(from)}`;
39
41
  if (!links.length) return count;
40
42
  const target = (l: ResolvedLink) => l.target + (l.heading !== null ? `#${l.heading}` : "") + (l.block !== null ? `#^${l.block}` : "");
41
- const resolution = (l: SuggestedLink): CellInput => l.resolved ?? tone(`${l.reason ?? "unresolved"}${l.suggested ? `; suggested ${clean(l.suggested.path)} (${l.suggested.score.toFixed(3)})` : ""}`, "warn");
43
+ const resolution = (l: SuggestedLink): CellInput => l.resolved ?? tone(`${marker("warn", { ...o, color: false })} ${l.reason ?? "unresolved"}${l.suggested ? `; suggested ${clean(l.suggested.path)} (${l.suggested.score.toFixed(3)})` : ""}`, "warn");
42
44
  const rows = links.map(l => [target(l), resolution(l), l.line]);
43
45
  const more = links.length >= c.limit && c.limit < 500 ? nextCommand("next", command("links", c.vault, c.target, "--limit", String(Math.min(500, c.limit * 2))), o) : undefined;
44
46
  return blocks(heading("OUT", o) + "\n" + table(["TARGET", "RESOLVED", "LINE"], rows, o), [count, more].filter(Boolean).join("\n"));
@@ -48,41 +50,43 @@ export function rebuildText(r: { vault: string; notes: number; changed: number;
48
50
  return `rebuilt ${clean(r.vault)}: ${plural(r.notes, "note")}, ${r.changed} changed, ${r.removed} removed${r.skipped?.length ? `, ${r.skipped.length} skipped` : ""}`;
49
51
  }
50
52
 
51
- const warnings = (list: string[], o: TextOptions) => list.length ? list.map(w => paint(`warning: ${clean(w)}`, "warn", o)).join("\n") : undefined;
53
+ const warnings = (list: string[], o: TextOptions) => list.length ? list.map(w => status("warn", `warning: ${w}`, o)).join("\n") : undefined;
52
54
  export function logReadText(r: LogReadResult, o: TextOptions, c: { command: "tail" | "grep"; vault: string; pattern?: string; limit: number; type?: string }): string {
53
- if (!r.ok) return blocks(paint(`log ${c.command}: not read`, "fail", o), issueTable(r.issues, o), warnings(r.warnings, o));
55
+ if (!r.ok) return blocks(status("fail", `log ${c.command}: not read`, o), issueTable(r.issues, o), warnings(r.warnings, o));
54
56
  const count = `${plural(r.lines.length, "line")}${r.dataLines !== null ? ` (log has ${r.dataLines})` : ""}`;
55
57
  const words = ["log", c.command, c.vault, ...(c.pattern !== undefined ? [c.pattern] : []), ...(c.type ? ["--type", c.type] : []), "--limit", String(Math.min(200, c.limit * 2))];
56
58
  const more = r.lines.length >= c.limit && c.limit < 200 ? nextCommand("next", command(...words), o) : undefined;
57
59
  return blocks(r.lines.length ? r.lines.map(clean).join("\n") : undefined, [count, more].filter(Boolean).join("\n"), warnings(r.warnings, o), issueTable(r.issues, o));
58
60
  }
59
61
  export function logAppendText(r: LogReceipt, o: TextOptions, c: { vault: string; type: string }): string {
60
- const line = r.ok && r.appended ? paint(`appended ${clean(c.type)} to the ${clean(c.vault)} log${r.bytesWritten ? ` (${plural(r.bytesWritten, "byte")})` : ""}`, "ok", o)
61
- : paint(`log append: ${clean(c.type)} not appended${r.rolledBack ? " (rolled back)" : ""}`, "fail", o);
62
+ const line = r.ok && r.appended ? status("ok", `appended ${clean(c.type)} to the ${clean(c.vault)} log${r.bytesWritten ? ` (${plural(r.bytesWritten, "byte")})` : ""}`, o)
63
+ : status("fail", `log append: ${clean(c.type)} not appended${r.rolledBack ? " (rolled back)" : ""}`, o);
62
64
  return blocks(line, issueTable(r.issues, o));
63
65
  }
64
66
 
65
- const LEVELS: Record<LintCode, "error" | "warn"> = { L01: "error", L02: "error", L03: "warn", L09: "warn", L10: "warn", L11: "warn", L12: "warn", L13: "error", L14: "warn", L15: "warn" };
67
+ const LEVELS: Record<LintCode, "error" | "warn"> = { L01: "error", L02: "error", L03: "warn", L09: "warn", L10: "warn", L11: "warn", L12: "warn", L13: "error", L14: "warn", L15: "warn", L16: "warn", L17: "warn" };
66
68
  const verdict = (r: { errors: number; warnings: number; summary: string }, o: TextOptions) => paint(clean(r.summary), r.errors ? "fail" : r.warnings ? "warn" : "ok", o);
67
69
  export function lintText(d: { report: LintReport; notes: number; titles: Record<LintCode, string>; info: Partial<Record<LintCode, string>> }, o: TextOptions, c: { vault: string; note?: string }): string {
68
70
  const rows = (Object.keys(d.report.findings) as LintCode[]).flatMap(code => {
69
71
  const check = d.titles[code].replace(" — ", " "), found = d.report.findings[code];
70
- return [...(found.length ? found.map(f => [tone(LEVELS[code], LEVELS[code] === "error" ? "fail" : "warn"), check, f]) : [[tone("ok", "ok"), check, "위반 없음"]]),
72
+ return [...(found.length ? found.map(f => [tone(`${marker(LEVELS[code] === "error" ? "fail" : "warn", { ...o, color: false })} ${LEVELS[code]}`, LEVELS[code] === "error" ? "fail" : "warn"), check, f]) : [[tone(`${marker("ok", { ...o, color: false })} ok`, "ok"), check, "위반 없음"]]),
71
73
  ...(d.info[code] ? [[tone("info", "muted"), check, d.info[code]]] : [])];
72
74
  });
73
- return blocks(heading(`lint ${c.vault}${c.note ? ` ${c.note}` : ""}: ${plural(d.notes, "note")}`, o), table(["LEVEL", "CHECK", "FINDING"], rows, o), verdict(d.report, o));
75
+ const ok = (Object.keys(d.report.findings) as LintCode[]).filter(code => !d.report.findings[code].length).length;
76
+ return blocks(heading(`lint ${c.vault}${c.note ? ` ${c.note}` : ""}: ${plural(d.notes, "note")}`, o), table(["LEVEL", "CHECK", "FINDING"], rows, o), verdict(d.report, o), summary({ failed: d.report.errors, warnings: d.report.warnings, ok }, o));
74
77
  }
75
78
 
76
79
  /** `lint --write` and `graph build`: what was written or would be, then issues and the log event. */
77
80
  export function analysisWriteText(r: { ok: boolean; applied: boolean; summary: unknown; paths: string[]; receipts: WriteReceipt[]; log?: LogReceipt }, o: TextOptions, c: { kind: "lint" | "graph"; dryRun: boolean }): string {
78
81
  const verb = c.dryRun && r.ok ? "would write" : r.applied ? "wrote" : "did not write";
79
- const line = paint(`${c.kind === "lint" ? "lint" : "graph build"}: ${verb} ${plural(r.paths.length, "report")}`, r.ok ? "ok" : "fail", o);
82
+ const line = status(r.ok ? "ok" : "fail", `${c.kind === "lint" ? "lint" : "graph build"}: ${verb} ${plural(r.paths.length, "report")}`, o);
80
83
  const s = (r.summary ?? {}) as Record<string, unknown>;
81
84
  const counts = c.kind === "lint" ? verdict(s as { errors: number; warnings: number; summary: string }, o)
82
85
  : fields((["nodes", "edges", "communities", "work_docs"] as const).map(k => [k.replace("_", " "), typeof s[k] === "number" ? s[k] : undefined]), o);
83
86
  const issues: WriteIssue[] = [...r.receipts.flatMap(x => x.issues), ...(r.log?.issues ?? [])];
84
- const logged = r.log ? (r.log.ok ? `logged ${c.kind === "lint" ? "LINT" : "GRAPH"} event` : paint("log event not appended", "fail", o)) : undefined;
85
- return blocks(line, r.paths.map(p => ` ${clean(p)}`).join("\n"), counts, issueTable(issues, o), logged);
87
+ const logged = r.log ? (r.log.ok ? `logged ${c.kind === "lint" ? "LINT" : "GRAPH"} event` : status("fail", "log event not appended", o)) : undefined;
88
+ const lintSummary = c.kind === "lint" ? summary({ failed: Number(s.errors ?? 0) || (r.ok ? 0 : 1), warnings: Number(s.warnings ?? 0), ok: r.ok && !s.errors && !s.warnings ? 1 : 0 }, o) : undefined;
89
+ return blocks(line, r.paths.map(p => ` ${clean(p)}`).join("\n"), counts, issueTable(issues, o), logged, lintSummary);
86
90
  }
87
91
 
88
92
  export function neighborsText(r: GraphNeighborhood, o: TextOptions, c: { vault: string; limit: number; relation?: string }): string {
@@ -110,3 +114,27 @@ export function pathText(r: GraphPath, o: TextOptions, c: { vault: string; maxHo
110
114
  const lines = r.edges.map(e => `${clean(e.source)} -[${e.relation === "wiki_link" ? e.rel ?? e.relation : e.relation}]-> ${clean(e.target)}`);
111
115
  return [...lines, `path from ${clean(r.from)} to ${clean(r.to)}: ${plural(r.length, "hop")}`].join("\n");
112
116
  }
117
+
118
+ /** `vmem evidence`: one row per entry with status, reason and byte offsets. Quotes are not echoed. */
119
+ export function evidenceText(r: EvidenceReport, o: TextOptions): string {
120
+ const head = heading(`evidence ${r.vault} ${r.note.path}: ${plural(r.evidence.length, "entry", "entries")}`, o);
121
+ if (!r.evidence.length) return blocks(head, paint("no evidence metadata", "muted", o));
122
+ const t = (s: EvidenceReport["evidence"][number]["status"]) => s === "verified" ? "ok" : s === "unverified_external" ? "muted" : s === "unsupported" ? "fail" : "warn";
123
+ const rows = r.evidence.map(e => {
124
+ const name = t(e.status), glyph = name === "muted" ? "unknown" : name;
125
+ return [String(e.index), tone(`${marker(glyph, { ...o, color: false })} ${e.status}`, name), e.reason ?? "", e.match ? `${e.match.start}..${e.match.end}` : "", e.source ?? ""];
126
+ });
127
+ return blocks(head, table(["#", "STATUS", "REASON", "BYTES", "SOURCE"], rows, o));
128
+ }
129
+
130
+ /** `vmem graph explain`: each hop, then its occurrences as rows. Structural metadata only; never a probability. */
131
+ export function explainText(r: GraphExplanation, o: TextOptions, c: { vault: string }): string {
132
+ if (!r.path.found) return `no path from ${clean(r.path.from)} to ${clean(r.path.to)} within ${plural(r.path.options.maxHops, "hop")}`;
133
+ const parts = r.hops.map(hop => {
134
+ const head = heading(`hop ${hop.index + 1}: ${hop.from} -> ${hop.to} (structural ${hop.edge.rel ?? hop.edge.relation})`, o);
135
+ const rows = hop.occurrences.map(x => [x.kind === "legacy_graph_match" && x.authored ? tone(`${marker("ok", { ...o, color: false })} link`, "ok") : tone(`${marker("unknown", { ...o, color: false })} ${x.kind === "legacy_graph_match" ? "legacy" : "note"}`, "muted"),
136
+ x.relation, x.traversal, `${x.origin.path}:${x.line}`, `${x.bytes.start}..${x.bytes.end}`, x.source === "frontmatter" ? `frontmatter ${x.field ?? ""}` : "body"]);
137
+ return blocks(head, rows.length ? table(["KIND", "RELATION", "WALK", "AT", "BYTES", "SOURCE"], rows, o) : paint("no occurrences found", "warn", o), hop.omitted ? status("warn", `${plural(hop.omitted, "occurrence")} omitted`, o) : undefined);
138
+ });
139
+ return blocks(...parts, `explained path ${clean(r.path.from)} to ${clean(r.path.to)} in ${clean(c.vault)}: ${plural(r.path.length, "hop")}${r.truncated ? " (truncated)" : ""}`);
140
+ }
@@ -8,7 +8,7 @@ import { parseFrontmatter } from "./frontmatter.ts";
8
8
  import { canonicalPath, isDenied } from "./platform.ts";
9
9
  import { codePointCompare as compare, labelCommunities } from "./vault-graph.ts";
10
10
  import { SECRET_PATTERNS } from "./write-validation.ts";
11
- import { PLAIN, stripTerminal, type TextOptions } from "./text-output.ts";
11
+ import { PLAIN, UsageError, stripTerminal, type TextOptions } from "./text-output.ts";
12
12
 
13
13
  /**
14
14
  * `vmem skills mine`: read-only skill-candidate mining over amem memory and vault notes, a port of the skill-mine
@@ -461,25 +461,30 @@ const VALUES = ["--days", "--project", "--vocab", "--skills", "--min-size", "--m
461
461
  const BOOLEANS = ["--all-projects", "--json"];
462
462
  /** `vmem skills mine <vault> ...`. Prints the JSON result, or the markdown report without --json. */
463
463
  export async function runSkillsCommand(args: string[], home: string, env: NodeJS.ProcessEnv, text: TextOptions = PLAIN): Promise<{ text: string; code: number }> {
464
- if (args[0] !== "mine") throw new Error("skills: use `vmem skills mine <vault>`");
464
+ if (args[0] !== "mine") throw new UsageError("skills: use `vmem skills mine <vault>`");
465
465
  const flags: Record<string, string | boolean> = {}, skills: string[] = [], positional: string[] = [];
466
466
  for (let i = 1; i < args.length; i++) {
467
467
  const arg = args[i]!;
468
468
  if (!arg.startsWith("--")) { positional.push(arg); continue; }
469
- if (!VALUES.includes(arg) && !BOOLEANS.includes(arg)) throw new Error(`skills mine: unknown option ${arg}`);
470
- if (arg !== "--skills" && Object.hasOwn(flags, arg)) throw new Error(`skills mine: repeated option ${arg}`);
469
+ if (!VALUES.includes(arg) && !BOOLEANS.includes(arg)) throw new UsageError(`skills mine: unknown option ${arg}`);
470
+ if (arg !== "--skills" && Object.hasOwn(flags, arg)) throw new UsageError(`skills mine: repeated option ${arg}`);
471
471
  if (BOOLEANS.includes(arg)) { flags[arg] = true; continue; }
472
472
  const value = args[++i];
473
- if (value === undefined || value.startsWith("--")) throw new Error(`${arg}: value required`);
473
+ if (value === undefined || value.startsWith("--")) throw new UsageError(`${arg}: value required`);
474
474
  if (arg === "--skills") skills.push(value); else flags[arg] = value;
475
475
  }
476
- if (positional.length !== 1) throw new Error("skills mine: requires one vault id");
476
+ if (positional.length !== 1) throw new UsageError("skills mine: requires one vault id");
477
477
  const number = (flag: string) => {
478
478
  const value = flags[flag];
479
479
  if (typeof value !== "string") return undefined;
480
- if (!/^\d+(\.\d+)?$/.test(value)) throw new Error(`${flag}: expected a number`);
480
+ if (!/^\d+(\.\d+)?$/.test(value)) throw new UsageError(`${flag}: expected a number`);
481
481
  return Number(value);
482
482
  };
483
+ const days = number("--days"), minSize = number("--min-size"), novelty = number("--min-novelty");
484
+ if (days !== undefined && (!Number.isInteger(days) || days < 1 || days > 3650)) throw new UsageError("skills mine: --days takes 1..3650");
485
+ if (minSize !== undefined && (!Number.isInteger(minSize) || minSize < 1 || minSize > 10000)) throw new UsageError("skills mine: --min-size takes 1..10000");
486
+ if (novelty !== undefined && (novelty < 0 || novelty > 1)) throw new UsageError("skills mine: --min-novelty takes 0..1");
487
+ if (flags["--all-projects"] && flags["--project"]) throw new UsageError("skills mine: choose either --all-projects or --project");
483
488
  const result = await mineSkills(home, {
484
489
  vault: positional[0]!, env, skills, allProjects: flags["--all-projects"] === true,
485
490
  ...(typeof flags["--project"] === "string" ? { project: flags["--project"] } : {}),
@@ -0,0 +1,131 @@
1
+ import { lstatSync, realpathSync } from "node:fs";
2
+ import { resolve, sep } from "node:path";
3
+ import { parseFrontmatter } from "./frontmatter.ts";
4
+ import { canonicalPath, isDenied } from "./platform.ts";
5
+ import { sourceReferences } from "./source.ts";
6
+ import { specGit } from "./spec-git.ts";
7
+
8
+ /** Source paths checked per lint run; later ones are counted as skipped, never checked unboundedly. */
9
+ export const SOURCE_AGE_MAX_PATHS = 2000;
10
+ /** Bound on one batched `git log` name listing; past it the tracked check is skipped and reported. */
11
+ const LOG_OUTPUT_BYTES = 8 * 1024 * 1024, LIST_OUTPUT_BYTES = 1024 * 1024;
12
+ /** Total literal pathspec bytes per git call, well under the smallest ARG_MAX (macOS, ~1 MiB with the environment). */
13
+ export const SOURCE_AGE_MAX_ARGV_BYTES = 256 * 1024;
14
+ /** Hardened read-only `git log`: no signature verification programs, no rename following from repo config. */
15
+ const LOG_FLAGS = ["-c", "log.showSignature=false", "-c", "log.follow=false"];
16
+
17
+ export interface SourceAge {
18
+ /** Finding lines by note path (relative to notes/): source path and commit count, or `modified`. */
19
+ findings: Record<string, string[]>;
20
+ /** Notes with a workspace source path but no valid `updated` date: counted, never flagged. */
21
+ unknownAge: number;
22
+ /** Source paths not checked because of the per-run cap, or because git could not be inspected. */
23
+ skipped: number;
24
+ /** Why tracked sources were not checked, when that happened, with a next step. */
25
+ gitUnavailable?: string;
26
+ }
27
+
28
+ /** The first moment after the note's `updated` local calendar day; a change at or after it is newer than the note. */
29
+ function dayAfter(updated: unknown): number | undefined {
30
+ const text = updated instanceof Date ? updated.toISOString().slice(0, 10) : typeof updated === "string" ? updated.trim() : "";
31
+ const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(text);
32
+ if (!match) return undefined;
33
+ const [y, m, d] = [Number(match[1]), Number(match[2]), Number(match[3])], next = new Date(y, m - 1, d + 1);
34
+ return new Date(y, m - 1, d).getDate() === d ? next.getTime() : undefined;
35
+ }
36
+
37
+ /**
38
+ * L17 input: notes whose workspace source changed after the note's `updated` day. Metadata only: git history,
39
+ * `git ls-files` and `lstat`; no source file is opened and nothing is written. Missing paths (L14), denied paths, URLs,
40
+ * memory ids and paths that resolve outside the workspace root are skipped. Git work is two batched calls per run.
41
+ */
42
+ export function sourceAgeFindings(notes: readonly { path: string; source: string }[], root: string, denyPaths: readonly string[], options: { env?: NodeJS.ProcessEnv; maxPaths?: number; maxArgvBytes?: number } = {}): SourceAge {
43
+ const result: SourceAge = { findings: Object.create(null) as Record<string, string[]>, unknownAge: 0, skipped: 0 };
44
+ let rootReal: string;
45
+ try { rootReal = realpathSync(root); } catch { return result; }
46
+ const maxPaths = options.maxPaths ?? SOURCE_AGE_MAX_PATHS, maxArgv = options.maxArgvBytes ?? SOURCE_AGE_MAX_ARGV_BYTES;
47
+ let argvBytes = 0;
48
+ // Per note: its threshold and the existing, allowed source paths, in source order without duplicates.
49
+ const plan: { note: string; after: number; paths: string[] }[] = [], all = new Set<string>();
50
+ for (const note of notes) {
51
+ let data: Record<string, unknown>;
52
+ try { data = parseFrontmatter(note.source).data; } catch { continue; }
53
+ if (data.source === undefined) continue;
54
+ let refs;
55
+ try { refs = sourceReferences(data.source); } catch { continue; }
56
+ const paths: string[] = [];
57
+ for (const ref of refs) {
58
+ if (ref.kind !== "path" || paths.includes(ref.value)) continue;
59
+ const file = resolve(rootReal, ref.value);
60
+ if (isDenied(ref.value, [...denyPaths]) || isDenied(canonicalPath(file), [...denyPaths])) continue;
61
+ let real: string;
62
+ try { lstatSync(file); real = realpathSync(file); } catch { continue; } // missing: L14 reports it
63
+ if (real !== rootReal && !real.startsWith(rootReal + sep)) continue;
64
+ paths.push(ref.value);
65
+ }
66
+ if (!paths.length) continue;
67
+ const after = dayAfter(data.updated);
68
+ if (after === undefined) { result.unknownAge++; continue; }
69
+ const kept: string[] = [];
70
+ for (const path of paths) {
71
+ const cost = Buffer.byteLength(path) + 11; // ":(literal)" plus the argv terminator
72
+ if (all.has(path)) kept.push(path);
73
+ else if (all.size < maxPaths && argvBytes + cost <= maxArgv) { all.add(path); argvBytes += cost; kept.push(path); }
74
+ else result.skipped++;
75
+ }
76
+ if (kept.length) plan.push({ note: note.path, after, paths: kept });
77
+ }
78
+ if (!plan.length) return result;
79
+ // Tracked set: one `ls-files` over literal pathspecs (argv, never stdin), relative to the workspace root.
80
+ const literal = [...all].map(path => `:(literal)${path}`);
81
+ let tracked = new Set<string>(), commits: { time: number; files: string[] }[] = [];
82
+ let inRepo = false;
83
+ try {
84
+ inRepo = specGit(rootReal, ["rev-parse", "--is-inside-work-tree"], { env: options.env, allowedExitCodes: [0, 128] }).status === 0;
85
+ if (inRepo) {
86
+ const listed = specGit(rootReal, ["ls-files", "--cached", "-z", "--", ...literal], { env: options.env, maxBuffer: LIST_OUTPUT_BYTES }).stdout.toString("utf8");
87
+ tracked = new Set(listed.split("\0").filter(Boolean));
88
+ if (tracked.size) {
89
+ const since = Math.min(...plan.map(item => item.after));
90
+ // The mainline only, each commit (merges included) diffed against its first parent: a change that reached the
91
+ // workspace through a merge after `updated` counts once, at the merge, even when the branch commits are older.
92
+ const log = specGit(rootReal, [...LOG_FLAGS, "log", "--no-show-signature", "--no-renames", "--first-parent", "--diff-merges=first-parent", "--relative", "-z", "--format=%x01%ct", "--name-only", `--since=@${Math.floor(since / 1000)}`, "--", ...literal], { env: options.env, maxBuffer: LOG_OUTPUT_BYTES }).stdout.toString("utf8");
93
+ for (const record of log.split("\x01").slice(1)) {
94
+ const [time, ...files] = record.split(/\0\n?|\n/).filter(Boolean);
95
+ commits.push({ time: Number(time) * 1000, files });
96
+ }
97
+ }
98
+ }
99
+ } catch (error) {
100
+ result.gitUnavailable = `${error instanceof Error ? error.message.slice(0, 200) : "git inspection failed"}; no source was checked. Check that git is installed and that the registry's workspace root is a readable repository, then rerun lint`;
101
+ result.skipped += all.size;
102
+ return result;
103
+ }
104
+ // One pass over listed files: each file credits every planned path that is it or one of its directories.
105
+ const planned = new Set(all), prefixes = (file: string) => {
106
+ const out = [file], parts = file.split("/");
107
+ for (let i = parts.length - 1; i > 0; i--) out.push(parts.slice(0, i).join("/"));
108
+ return out.filter(path => planned.has(path) || planned.has(path + "/"));
109
+ };
110
+ const key = (path: string) => path.replace(/\/$/, "");
111
+ const trackedPaths = new Set<string>();
112
+ for (const file of tracked) for (const path of prefixes(file)) trackedPaths.add(key(path));
113
+ /** Commit times per planned path (one entry per commit). */
114
+ const times = new Map<string, number[]>();
115
+ for (const commit of commits) for (const path of new Set(commit.files.flatMap(prefixes).map(key))) (times.get(path) ?? times.set(path, []).get(path)!).push(commit.time);
116
+ for (const item of plan) {
117
+ const lines: string[] = [];
118
+ for (const path of item.paths) {
119
+ if (inRepo && trackedPaths.has(key(path))) {
120
+ const count = (times.get(key(path)) ?? []).filter(time => time >= item.after).length;
121
+ if (count) lines.push(`source \`${path}\` has ${count} commit${count === 1 ? "" : "s"} after updated; re-check the note against it, then save it to refresh updated`);
122
+ } else {
123
+ let mtime: number;
124
+ try { mtime = lstatSync(resolve(rootReal, path)).mtimeMs; } catch { continue; }
125
+ if (mtime >= item.after) lines.push(`source \`${path}\` modified after updated (not tracked by the workspace repository, judged by mtime); re-check the note against it, then save it to refresh updated`);
126
+ }
127
+ }
128
+ if (lines.length) result.findings[item.note] = lines;
129
+ }
130
+ return result;
131
+ }
@@ -9,7 +9,7 @@ import type { SpecEdge, SpecNode } from "./spec-graph.ts";
9
9
  import type { SpecFreshnessEntry } from "./spec-freshness.ts";
10
10
  import type { SpecValidationIssue, SpecValidationReport } from "./spec-validate.ts";
11
11
  import type { SpecDiagnostic } from "./spec-source.ts";
12
- import { blocks, fields, heading, issueTable, nextCommand, paint, paragraph, plural, shellWord, table, tone, type CellInput, type TextOptions, stripTerminal } from "./text-output.ts";
12
+ import { blocks, fields, heading, issueTable, marker, nextCommand, paragraph, plural, shellWord, status, table, tableParts, tone, type CellInput, type TextOptions, stripTerminal } from "./text-output.ts";
13
13
 
14
14
  /** What the renderers need from the command line: the spec arguments (`get root --body`) and their parsed values. */
15
15
  export interface SpecTextContext { args: readonly string[]; values: Record<string, unknown>; repo?: string }
@@ -25,7 +25,8 @@ export interface SpecGrepResult { source: string; worktree: string; hits: SpecGr
25
25
  export type SpecValidateResult = SpecValidationReport & { source?: string; worktree?: string };
26
26
 
27
27
  const value = (data: unknown): string => typeof data === "string" ? data : Array.isArray(data) ? data.map(value).join(", ") : data === undefined || data === null ? "" : JSON.stringify(data);
28
- const statusTone = (status: string | undefined): CellInput => status === "active" ? tone(status, "ok") : status === "deprecated" ? tone(status, "warn") : status ?? "-";
28
+ const markedCell = (name: "ok" | "warn" | "fail", text: string, o: TextOptions) => tone(`${marker(name, { ...o, color: false })} ${text}`, name);
29
+ const statusTone = (value: string | undefined, o: TextOptions): CellInput => value === "active" ? markedCell("ok", value, o) : value === "deprecated" ? markedCell("warn", value, o) : value ?? "-";
29
30
  const counted = (shown: number, total: number) => shown < total ? ` (${shown} of ${total})` : "";
30
31
  /** The same command with `--offset` set, inserted before a `--` separator so it stays an option. */
31
32
  export function offsetCommand(args: readonly string[], offset: number): string {
@@ -33,19 +34,19 @@ export function offsetCommand(args: readonly string[], offset: number): string {
33
34
  const head = args.slice(0, end).filter((arg, i, all) => arg !== "--offset" && all[i - 1] !== "--offset");
34
35
  return ["vmem", "spec", ...head, "--offset", String(offset), ...args.slice(end)].map(shellWord).join(" ");
35
36
  }
36
- function freshnessText(entry: SpecFreshnessEntry | null): CellInput {
37
+ function freshnessText(entry: SpecFreshnessEntry | null, o: TextOptions): CellInput {
37
38
  if (!entry) return undefined;
38
- if (entry.state === "fresh") return tone(entry.dirty ? "fresh, uncommitted changes" : "fresh", entry.dirty ? "warn" : "ok");
39
- return tone(`stale: ${staleText(entry)}`, "warn");
39
+ if (entry.state === "fresh") return markedCell(entry.dirty ? "warn" : "ok", entry.dirty ? "fresh, uncommitted changes" : "fresh", o);
40
+ return markedCell("warn", `stale: ${staleText(entry)}`, o);
40
41
  }
41
42
  const staleText = (entry: SpecFreshnessEntry) => [entry.commits > 0 && `${plural(entry.commits, "commit")} since verified-against`, entry.dirty && "uncommitted changes"].filter(Boolean).join(", ") || "source scope changed";
42
43
 
43
44
  export function renderSpecGet(r: SpecGetResult, o: TextOptions, context: SpecTextContext): string {
44
45
  const data = r.frontmatter, title = typeof data.title === "string" ? data.title : "";
45
46
  const info = fields([
46
- ["type", value(data.type)], ["status", typeof data.status === "string" ? statusTone(data.status) : value(data.status)],
47
+ ["type", value(data.type)], ["status", typeof data.status === "string" ? statusTone(data.status, o) : value(data.status)],
47
48
  ["parent", value(data.parent)], ["depends-on", value(data["depends-on"])], ["covers", value(data.covers)], ["paths", value(data.paths)],
48
- ["path", r.path], ["source", r.source], ["freshness", freshnessText(r.freshness)],
49
+ ["path", r.path], ["source", r.source], ["freshness", freshnessText(r.freshness, o)],
49
50
  ["links", r.links.map(edge => `${edge.kind} ${edge.target}`).join(", ") + counted(r.links.length, r.totals.links)],
50
51
  ["backlinks", r.backlinks.map(edge => `${edge.kind} ${edge.source}`).join(", ") + counted(r.backlinks.length, r.totals.backlinks)],
51
52
  ["children", r.children.map(node => node.id).join(", ") + counted(r.children.length, r.totals.children)],
@@ -72,7 +73,7 @@ export function renderSpecGraph(r: SpecGraphResult, o: TextOptions, context: Spe
72
73
  }
73
74
  const order = (node: SpecNode) => reached.get(node.id)?.depth ?? 9;
74
75
  const nodes = [...r.nodes].sort((a, b) => order(a) - order(b));
75
- const rows = nodes.map(node => { const how = reached.get(node.id); return [tone(node.id, "info"), node.type || "-", statusTone(node.status), how?.edge?.kind ?? "-", how ? how.depth : "-", node.title]; });
76
+ const rows = nodes.map(node => { const how = reached.get(node.id); return [tone(node.id, "info"), node.type || "-", statusTone(node.status, o), how?.edge?.kind ?? "-", how ? how.depth : "-", node.title]; });
76
77
  const tree = new Set([...reached.values()].flatMap(how => how.edge ? [how.edge] : []));
77
78
  const other = r.edges.filter(edge => !tree.has(edge));
78
79
  const edge = typeof context.values.edge === "string" ? `${context.values.edge} edges` : direction === "neighbors" ? "all edges" : "parent edges";
@@ -86,7 +87,7 @@ export function renderSpecGraph(r: SpecGraphResult, o: TextOptions, context: Spe
86
87
  /** One hit per row, its snippet on the next line; rows never wrap so each snippet stays under its row. */
87
88
  export function renderSpecGrep(r: SpecGrepResult, o: TextOptions, context: SpecTextContext): string {
88
89
  if (!r.hits.length) return paragraph(r.offset ? `no more hits after offset ${r.offset}` : "no specs matched", o);
89
- const lines = table(["ID", "TYPE", "STATUS", "TITLE"], r.hits.map(hit => [tone(hit.id, "info"), hit.type || "-", statusTone(hit.status), hit.title]), { color: o.color }).split("\n");
90
+ const lines = tableParts(["ID", "TYPE", "STATUS", "TITLE"], r.hits.map(hit => [tone(hit.id, "info"), hit.type || "-", statusTone(hit.status, o), hit.title]), { ...o, columns: undefined });
90
91
  const body = [lines[0]!, ...r.hits.flatMap((hit, i) => [lines[i + 1]!, paragraph(stripTerminal(hit.snippet).replace(/\s+/g, " ").trim(), o, "muted", " ")])].join("\n");
91
92
  const range = r.offset || r.truncated ? `hits ${r.offset + 1}-${r.offset + r.hits.length}` : plural(r.hits.length, "hit");
92
93
  return blocks(body, [paragraph(range + (r.truncated ? ", more remain" : ""), o),
@@ -95,7 +96,7 @@ export function renderSpecGrep(r: SpecGrepResult, o: TextOptions, context: SpecT
95
96
 
96
97
  const finding = (item: { path: string; field?: string; target?: string; firstPath?: string; message: string }) =>
97
98
  `${item.path}${item.field ? ` ${item.field}` : ""}${item.target ?? item.firstPath ? ` -> ${item.target ?? item.firstPath}` : ""}: ${item.message}`;
98
- const levelCell = (severity: SpecValidationIssue["severity"]) => tone(severity, severity === "error" ? "fail" : "warn");
99
+ const levelCell = (severity: SpecValidationIssue["severity"], o: TextOptions) => markedCell(severity === "error" ? "fail" : "warn", severity, o);
99
100
 
100
101
  /** LEVEL/CHECK/FINDING rows per section, then a verdict line. Stale scopes are their own section unless --require-fresh made them errors. */
101
102
  export function renderSpecValidate(r: SpecValidateResult, o: TextOptions, context: SpecTextContext): string {
@@ -104,12 +105,12 @@ export function renderSpecValidate(r: SpecValidateResult, o: TextOptions, contex
104
105
  const target = context.repo !== undefined ? `--repo ${context.repo}` : r.source ?? "";
105
106
  const verdict = `${r.ok ? "ok" : "fail"}: ${plural(r.errors, "error")}, ${plural(r.warnings, "warning")}, ${plural(stale.length, "stale scope")}`;
106
107
  return blocks(heading(`spec validate ${target}`.trim(), o),
107
- section("Findings", r.items.map(item => [levelCell(item.severity), item.code, finding(item)])),
108
+ section("Findings", r.items.map(item => [levelCell(item.severity, o), item.code, finding(item)])),
108
109
  section("Discovery", r.diagnostics.map((item: SpecDiagnostic) => [tone("note", "muted"), item.code, finding(item)])),
109
- context.values.requireFresh !== true && section("Freshness", stale.map(entry => [tone("warning", "warn"), "stale",
110
+ context.values.requireFresh !== true && section("Freshness", stale.map(entry => [markedCell("warn", "warning", o), "stale",
110
111
  `${entry.path}${entry.id ? ` (${entry.id})` : ""}: ${staleText(entry)}; review the scope and refresh verified-against`])),
111
112
  [r.truncated && paragraph(`truncated: ${r.items.length} of ${r.errors + r.warnings} findings shown; raise --limit (up to 500) or fix the listed findings and rerun`, o, "warn"),
112
- paint(verdict, r.ok ? "ok" : "fail", o)].filter(Boolean).join("\n"));
113
+ status(r.ok ? "ok" : "fail", verdict, o)].filter(Boolean).join("\n"));
113
114
  }
114
115
 
115
116
  /** A frontmatter mutation receipt shows the verdict and SHA without repeating authored content. */
package/src/sync.ts CHANGED
@@ -8,6 +8,12 @@ import type { WriteIssue } from "./write-types.ts";
8
8
 
9
9
  /** Paths sync may stage; everything else in the clone is left alone (and reported). */
10
10
  const STAGE_PREFIXES = ["notes/", "reports/"];
11
+ /**
12
+ * The assertion journal's segments, `assertions/<16 lowercase hex>.jsonl` directly under `assertions/`. A prefix
13
+ * would stage the journal's `assertions.lock` and any stray or nested path with it, so the file's shape decides.
14
+ */
15
+ const ASSERTION_SEGMENT = /^assertions\/[0-9a-f]{16}\.jsonl$/;
16
+ const STAGE_PATTERNS = ["assertions/<segment>.jsonl"];
11
17
  const STAGE_FILES = ["log"];
12
18
  const GIT_TIMEOUT_MS = 60_000;
13
19
  export interface SyncResult {
@@ -19,7 +25,7 @@ export interface SyncResult {
19
25
  branch: string | null;
20
26
  /** Planned changed paths that will be staged and committed. */
21
27
  paths: string[];
22
- /** Changed paths outside STAGE_PREFIXES and STAGE_FILES: never staged. */
28
+ /** Changed paths outside the staged prefixes, patterns and files: never staged. */
23
29
  ignored: string[];
24
30
  ahead: number;
25
31
  behind: number;
@@ -46,8 +52,8 @@ export function sameRemote(a: string, b: string): boolean {
46
52
  }
47
53
  /** Time budget of the console's local sync check. */
48
54
  const GIT_TIMEOUT_BUDGET_MS = 1000;
49
- /** The paths `vmem sync` stages (STAGE_PREFIXES, then STAGE_FILES), as people read them. */
50
- export const STAGED_DESCRIPTION = ((items: string[]) => items.length > 1 ? `${items.slice(0, -1).join(", ")} and ${items.at(-1)}` : items.join(""))([...STAGE_PREFIXES, ...STAGE_FILES]);
55
+ /** The paths `vmem sync` stages (STAGE_PREFIXES, STAGE_PATTERNS, then STAGE_FILES), as people read them. */
56
+ export const STAGED_DESCRIPTION = ((items: string[]) => items.length > 1 ? `${items.slice(0, -1).join(", ")} and ${items.at(-1)}` : items.join(""))([...STAGE_PREFIXES, ...STAGE_PATTERNS, ...STAGE_FILES]);
51
57
  type SpawnResult = { exitCode: number | null; signalCode?: string | number | null; exitedDueToTimeout?: boolean; stderr: { toString(): string } };
52
58
  /** Why a git call failed: its timeout or signal when it left no exit code, else the last stderr line. */
53
59
  function failureCause(result: SpawnResult, budgetMs: number): string {
@@ -94,7 +100,7 @@ export function originCheck(root: string, remote: string, env: NodeJS.ProcessEnv
94
100
  const ok = originUrl !== null && rewrites.length === 0 && fetchUrls.length > 0 && pushUrls.length > 0 && [...fetchUrls, ...pushUrls].every(url => sameRemote(url, remote));
95
101
  return { ok, origin: originUrl, fetchUrls, pushUrls, ...(!ok ? { issue: originUrl === null ? "repository has no origin remote" : rewrites.length ? `git url rewrite ${rewrites[0]} applies to the vault remote; refusing because the push destination cannot be verified` : "an origin fetch or push URL does not match the configured remote; nothing was fetched or pushed" } : {}) };
96
102
  }
97
- function planned(path: string): boolean { return STAGE_FILES.includes(path) || STAGE_PREFIXES.some(prefix => path.startsWith(prefix)); }
103
+ function planned(path: string): boolean { return STAGE_FILES.includes(path) || STAGE_PREFIXES.some(prefix => path.startsWith(prefix)) || ASSERTION_SEGMENT.test(path); }
98
104
  /** Parse `status --porcelain=v1 -z` into one entry per change; a rename or copy is one entry with both sides. */
99
105
  function changedEntries(git: Git): string[][] {
100
106
  const parts = git(["status", "--porcelain=v1", "-z", "--untracked-files=all"]).stdout.split("\0").filter(Boolean), entries: string[][] = [];
@@ -136,9 +142,10 @@ export function localSyncPending(root: string, env: NodeJS.ProcessEnv = process.
136
142
  /**
137
143
  * Explicit, never scheduled publication of one vault clone. Without `confirm` it fetches, checks the
138
144
  * configured remote against `origin`, and previews what would be staged; nothing is committed or pushed.
139
- * With `confirm` and the current fingerprint it stages only notes/, reports/ and log, commits, rebases on
140
- * the upstream and pushes. Any failure (remote mismatch, divergence that cannot rebase, push refused,
141
- * missing credentials) is reported with `ok: false`; it never reports success it did not observe.
145
+ * With `confirm` and the current fingerprint it stages only notes/, reports/, assertion journal segments
146
+ * and log, commits, rebases on the upstream and pushes. Any failure (remote mismatch, divergence that
147
+ * cannot rebase, push refused, missing credentials) is reported with `ok: false`; it never reports
148
+ * success it did not observe.
142
149
  */
143
150
  export function syncVault(home: string, request: { vault: string; confirm?: boolean; fingerprint?: string; message?: string }, options: { env?: NodeJS.ProcessEnv } = {}): SyncResult {
144
151
  const config = loadRegistry(home), spec = config.vaults.find(v => v.id === request.vault);