@staix/vault-mem 0.9.1 → 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.
- package/CHANGELOG.md +27 -0
- package/README.md +19 -6
- package/bin/vmem.js +2 -2
- package/package.json +2 -2
- package/src/analysis-commands.ts +24 -14
- package/src/analysis-input.ts +12 -0
- package/src/analysis-types.ts +5 -1
- package/src/assert-command.ts +48 -0
- package/src/assertion-exposure.ts +367 -0
- package/src/assertion-index.ts +86 -0
- package/src/assertion-policy.ts +63 -0
- package/src/assertion-read.ts +170 -0
- package/src/assertions-command.ts +123 -0
- package/src/assertions.ts +1013 -0
- package/src/cli-output.ts +9 -3
- package/src/cli.ts +44 -23
- package/src/commands-table.ts +16 -2
- package/src/evidence.ts +222 -0
- package/src/graph-evidence.ts +169 -0
- package/src/index.ts +14 -0
- package/src/links.ts +18 -0
- package/src/log-commands.ts +7 -7
- package/src/mcp-spec.ts +11 -11
- package/src/mcp-vault.ts +105 -6
- package/src/mcp.ts +4 -0
- package/src/org-commands.ts +5 -5
- package/src/org-promote.ts +9 -0
- package/src/promote-command.ts +6 -6
- package/src/proposal-commands.ts +100 -0
- package/src/proposal-provider.ts +335 -0
- package/src/proposal-storage.ts +334 -0
- package/src/proposals.ts +170 -0
- package/src/read-commands.ts +44 -12
- package/src/read-output.ts +42 -14
- package/src/skills-mine.ts +12 -7
- package/src/source-age.ts +131 -0
- package/src/spec-output.ts +14 -13
- package/src/sync.ts +14 -7
- package/src/text-output.ts +86 -21
- package/src/vault-brief.ts +8 -4
- package/src/vault-graph.ts +12 -3
- package/src/vault-history.ts +662 -0
- package/src/vault-index.ts +2 -0
- package/src/vault-lint.ts +15 -4
- package/src/write-commands.ts +18 -17
- package/src/write-output.ts +6 -6
- package/src/write-types.ts +1 -0
- package/src/write-validation.ts +3 -1
- package/src/writer.ts +257 -11
package/src/cli-output.ts
CHANGED
|
@@ -7,7 +7,7 @@ import type { ResolvedHome } from "./home.ts";
|
|
|
7
7
|
import type { PiiMatrix, PiiRow } from "./pii.ts";
|
|
8
8
|
import { effectivePii, type RecoveryReport } from "./registry.ts";
|
|
9
9
|
import type { SetupReport } from "./setup.ts";
|
|
10
|
-
import { blocks, clean, fields, heading, issueTable,
|
|
10
|
+
import { blocks, clean, fields, heading, issueTable, marker, nextCommand, paragraph as formatParagraph, plural, shellWord, status, table, tone, type CellInput, type TextOptions, type Tone } from "./text-output.ts";
|
|
11
11
|
import { MAX_RATIO_NOTES } from "./vault-index.ts";
|
|
12
12
|
import type { VaultStats } from "./vault-stats.ts";
|
|
13
13
|
|
|
@@ -18,12 +18,17 @@ export type SpecRow = SpecSourceSpec & { healthy?: boolean; issue?: string };
|
|
|
18
18
|
export interface StatusResult extends ResolvedHome { version: string; healthy: boolean; vaults: VaultRow[]; specs?: SpecRow[] }
|
|
19
19
|
export interface Manifest { name: string; version: string; configVersion: number; mcp: { server: string; tools: (string | { name: string; readOnly: boolean })[] }; commands: string[] }
|
|
20
20
|
|
|
21
|
-
const
|
|
21
|
+
const statuses = (o: TextOptions) => {
|
|
22
|
+
const plain = { ...o, color: false };
|
|
23
|
+
return { OK: tone(`${marker("ok", plain)} ok`, "ok"), WARN: tone(`${marker("warn", plain)} warn`, "warn"), FAIL: tone(`${marker("fail", plain)} fail`, "fail") };
|
|
24
|
+
};
|
|
25
|
+
const paragraph = (text: string, o: TextOptions, toneName?: Tone, indent = "") => formatParagraph(toneName === "ok" || toneName === "warn" || toneName === "fail" ? `${marker(toneName, { ...o, color: false })} ${text}` : text, o, toneName, indent);
|
|
22
26
|
const homeLine = (r: StatusResult, o: TextOptions) => `${heading(`vmem ${r.version}`, o)} home ${clean(r.home)} (${r.source})`;
|
|
23
27
|
const NO_VAULTS = "no vaults registered; add one with vmem vaults add <id> <absolute-path> --kind personal|org --write mcp|cli|none";
|
|
24
28
|
|
|
25
29
|
export function renderStatus(r: StatusResult, o: TextOptions): string {
|
|
26
|
-
const
|
|
30
|
+
const { OK, FAIL } = statuses(o);
|
|
31
|
+
const title = `${homeLine(r, o)} ${status(r.healthy ? "ok" : "fail", r.healthy ? "healthy" : "unhealthy", o)}`;
|
|
27
32
|
const vaults = r.vaults.length ? table(["VAULT", "KIND", "WRITE", "PII", "HEALTH", "PATH"], r.vaults.map(v => [v.id, v.kind, v.write, v.pii, v.healthy ? OK : FAIL, v.path]), o) : paragraph(NO_VAULTS, o);
|
|
28
33
|
const issues = r.vaults.filter(v => v.issue).map(v => paragraph(`${v.id}: ${v.issue}`, o, "fail")).join("\n");
|
|
29
34
|
const specs = r.specs?.length ? table(["SOURCE", "WRITE", "PII", "PATH"], r.specs.map(s => [s.id, s.write, s.pii, s.path]), o) : undefined;
|
|
@@ -35,6 +40,7 @@ function tidyFinding(t: NonNullable<VaultRow["tidy"]>): string {
|
|
|
35
40
|
return [`${plural(t.notes, "note")} to migrate${pending ? ` (${pending})` : ""}`, t.unparsable.length ? `${plural(t.unparsable.length, "unparsable note")} skipped` : ""].filter(Boolean).join("; ");
|
|
36
41
|
}
|
|
37
42
|
export function renderDoctor(r: StatusResult, o: TextOptions): string {
|
|
43
|
+
const { OK, WARN, FAIL } = statuses(o);
|
|
38
44
|
let failed = 0;
|
|
39
45
|
const vaults = r.vaults.map(v => {
|
|
40
46
|
const rows: CellInput[][] = [[v.healthy ? OK : FAIL, "path", v.healthy ? v.path : `${v.path}: ${v.issue ?? "unavailable"}`]];
|
package/src/cli.ts
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
1
|
import { runBriefCommand } from "./vault-brief.ts";
|
|
2
|
+
import { runProposalCommand } from "./proposal-commands.ts";
|
|
2
3
|
import { runSpecCommand, specTools } from "./mcp-spec.ts";
|
|
3
4
|
import { tidyVault, TIDY_RULES } from "./tidy.ts";
|
|
4
5
|
import { originCheck } from "./sync.ts";
|
|
5
6
|
import { registryIds } from "./vault-log.ts";
|
|
6
7
|
import { runAnalysisCommand } from "./analysis-commands.ts";
|
|
7
8
|
import { runLogCommand } from "./log-commands.ts";
|
|
9
|
+
import { runAssertCommand } from "./assert-command.ts";
|
|
10
|
+
import { runAssertionsCommand } from "./assertions-command.ts";
|
|
8
11
|
import { runOrgCommand } from "./org-commands.ts";
|
|
9
12
|
import { isWriteCommand, runWriteCommand } from "./write-commands.ts";
|
|
10
13
|
import { isReadCommand, runReadCommand } from "./read-commands.ts";
|
|
@@ -17,17 +20,17 @@ import { resolveHome } from "./home.ts";
|
|
|
17
20
|
import { addVault, addSpec, removeSpec, specStatus, effectivePii, loadRegistry, recoverRegistry, registryStatus, removeVault, setVaultPii } from "./registry.ts";
|
|
18
21
|
import { piiPolicy } from "./pii.ts";
|
|
19
22
|
import { vaultStats } from "./vault-stats.ts";
|
|
20
|
-
import { PLAIN, shellWord, takeColorFlag, textOptions, type TextOptions } from "./text-output.ts";
|
|
23
|
+
import { PLAIN, UsageError, errorLine, shellWord, takeColorFlag, textOptions, type TextOptions } from "./text-output.ts";
|
|
21
24
|
import { renderDoctor, renderManifest, renderRecover, renderRemove, renderSetup, renderSpecAdd, renderSpecsList, renderStats, renderStatus, renderVaultAdd, renderVaultPii, renderVaultsList, type StatusResult } from "./cli-output.ts";
|
|
22
25
|
function parse(args: string[], allowed: string[], values: string[]) {
|
|
23
26
|
const flags: Record<string, string | boolean> = {}, positional: string[] = [];
|
|
24
27
|
for (let i = 0; i < args.length; i++) {
|
|
25
28
|
const word = args[i]!;
|
|
26
29
|
if (!word.startsWith("-")) { positional.push(word); continue; }
|
|
27
|
-
if (!allowed.includes(word) || word in flags) throw new
|
|
30
|
+
if (!allowed.includes(word) || word in flags) throw new UsageError(`unknown or repeated option: ${word}`);
|
|
28
31
|
if (values.includes(word)) {
|
|
29
32
|
const value = args[++i];
|
|
30
|
-
if (!value || value.startsWith("--")) throw new
|
|
33
|
+
if (!value || value.startsWith("--")) throw new UsageError(`${word}: value required`);
|
|
31
34
|
flags[word] = value;
|
|
32
35
|
} else flags[word] = true;
|
|
33
36
|
}
|
|
@@ -38,7 +41,7 @@ function commandHelp(args: string[], o: TextOptions): string | undefined {
|
|
|
38
41
|
if (args[0] === "help" && args.length > 1) {
|
|
39
42
|
const name = args.slice(1).join(" ");
|
|
40
43
|
const text = commandUsage(name, o);
|
|
41
|
-
if (!text) throw new
|
|
44
|
+
if (!text) throw new UsageError(`help: unknown command ${name}; run vmem help for the command list`);
|
|
42
45
|
return text;
|
|
43
46
|
}
|
|
44
47
|
if (args.includes("--")) return undefined;
|
|
@@ -61,7 +64,7 @@ function runWith(args: string[], env: NodeJS.ProcessEnv, text: TextOptions = PLA
|
|
|
61
64
|
if (args.length === 1 && args[0] === "--version") return { text: version, code: 0 };
|
|
62
65
|
if (args[0] === "manifest") {
|
|
63
66
|
const { flags, positional } = parse(args.slice(1), ["--json"], []);
|
|
64
|
-
if (positional.length) throw new
|
|
67
|
+
if (positional.length) throw new UsageError("manifest: unexpected arguments");
|
|
65
68
|
// Read-only tools are published as { name, readOnly: true } so installers can approve them without a hard-coded list.
|
|
66
69
|
const readOnly = new Set([...vaultTools([]), ...specTools()].filter(t => t.annotations.readOnlyHint).map(t => t.name));
|
|
67
70
|
const tools = VMEM_TOOL_NAMES.map(name => readOnly.has(name) ? { name, readOnly: true } : name);
|
|
@@ -70,20 +73,23 @@ function runWith(args: string[], env: NodeJS.ProcessEnv, text: TextOptions = PLA
|
|
|
70
73
|
}
|
|
71
74
|
if (args[0] === "setup") {
|
|
72
75
|
const { flags, positional } = parse(args.slice(1), ["--apply", "--undo", "--json", "--root"], ["--root"]);
|
|
73
|
-
if (positional.length !== 1 || (flags["--apply"] && flags["--undo"])) throw new
|
|
76
|
+
if (positional.length !== 1 || (flags["--apply"] && flags["--undo"])) throw new UsageError("setup: requires one target and at most one of --apply/--undo");
|
|
74
77
|
const mode: SetupMode = flags["--apply"] ? "apply" : flags["--undo"] ? "undo" : "dry-run";
|
|
75
78
|
const report = runSetup(positional[0]!, mode, { home: resolveHome(env).home, env, ...(typeof flags["--root"] === "string" ? { root: flags["--root"] } : {}) });
|
|
76
79
|
const apply = ["vmem", "setup", positional[0]!, "--apply", ...(typeof flags["--root"] === "string" ? ["--root", flags["--root"]] : [])].map(shellWord).join(" ");
|
|
77
80
|
return { text: flags["--json"] ? JSON.stringify(report) : renderSetup(report, text, apply), code: [...report.actions, report.console].some(a => a?.change === "refused") ? 1 : 0 };
|
|
78
81
|
}
|
|
79
82
|
if (args[0] === "completion") {
|
|
80
|
-
if (args.length !== 2) throw new
|
|
83
|
+
if (args.length !== 2) throw new UsageError("completion: requires bash, zsh or fish");
|
|
81
84
|
return { text: completionScript(args[1]!).trimEnd(), code: 0 };
|
|
82
85
|
}
|
|
83
86
|
if (args[0] === "spec") return runSpecCommand(args.slice(1), env, text);
|
|
87
|
+
if (args[0] === "proposal") return runProposalCommand(args.slice(1), resolveHome(env).home, env, text);
|
|
84
88
|
if (args[0] === "lint" || args[0] === "graph") return runAnalysisCommand(args[0],args.slice(1),resolveHome(env).home,env,text);
|
|
85
89
|
if (args[0] === "promote" || args[0] === "sync") return runOrgCommand(args[0], args.slice(1), resolveHome(env).home, env, text);
|
|
86
90
|
if (args[0] === "log") return runLogCommand(args.slice(1), resolveHome(env).home, env, text);
|
|
91
|
+
if (args[0] === "assertions") return runAssertionsCommand(args.slice(1), resolveHome(env).home, env, text);
|
|
92
|
+
if (args[0] === "assert") return runAssertCommand(args.slice(1), resolveHome(env).home, env, text);
|
|
87
93
|
if (isWriteCommand(args[0]!)) return runWriteCommand(args[0]!, args.slice(1), resolveHome(env).home, env, text);
|
|
88
94
|
if (args[0] === "brief") return runBriefCommand(args.slice(1), resolveHome(env).home);
|
|
89
95
|
if (isReadCommand(args[0]!)) return runReadCommand(args[0]!, args.slice(1), resolveHome(env).home, text);
|
|
@@ -96,7 +102,7 @@ function runWith(args: string[], env: NodeJS.ProcessEnv, text: TextOptions = PLA
|
|
|
96
102
|
let result: unknown, code = 0, render: () => string;
|
|
97
103
|
switch (command) {
|
|
98
104
|
case "status": case "doctor": {
|
|
99
|
-
if (positional.length) throw new
|
|
105
|
+
if (positional.length) throw new UsageError(`${command}: unexpected arguments`);
|
|
100
106
|
const config = loadRegistry(home.home);
|
|
101
107
|
const vaults = registryStatus(home.home).map(vault => {
|
|
102
108
|
if (command !== "doctor" || !vault.healthy) return { ...vault, checks: undefined };
|
|
@@ -134,29 +140,29 @@ function runWith(args: string[], env: NodeJS.ProcessEnv, text: TextOptions = PLA
|
|
|
134
140
|
break;
|
|
135
141
|
}
|
|
136
142
|
case "stats": {
|
|
137
|
-
if (positional.length !== 1) throw new
|
|
143
|
+
if (positional.length !== 1) throw new UsageError("stats: requires one vault id; use vmem stats <vault> [--days 1..3650]");
|
|
138
144
|
const days = flags["--days"];
|
|
139
|
-
if (days !== undefined && !/^[0-9]+$/.test(String(days))) throw new
|
|
145
|
+
if (days !== undefined && !/^[0-9]+$/.test(String(days))) throw new UsageError("stats: --days expects an integer 1..3650; omit it for the 30-day default");
|
|
140
146
|
const stats = vaultStats(home.home, positional[0]!, days === undefined ? {} : { days: Number(days) });
|
|
141
147
|
result = stats; render = () => renderStats(stats, text);
|
|
142
148
|
if (stats.log.issues.length) code = 1;
|
|
143
149
|
break;
|
|
144
150
|
}
|
|
145
151
|
case "recover": {
|
|
146
|
-
if (positional.length) throw new
|
|
152
|
+
if (positional.length) throw new UsageError("recover: unexpected arguments");
|
|
147
153
|
const report = recoverRegistry(home.home, flags["--confirm"] === true);
|
|
148
154
|
result = report; render = () => renderRecover(report, text);
|
|
149
155
|
if (report.blocked) code = 1;
|
|
150
156
|
break;
|
|
151
157
|
}
|
|
152
158
|
case "specs list": {
|
|
153
|
-
if (positional.length) throw new
|
|
159
|
+
if (positional.length) throw new UsageError("specs list: unexpected targets; use vmem specs list [--json]");
|
|
154
160
|
const specs = loadRegistry(home.home).specs ?? [];
|
|
155
161
|
result = specs; render = () => renderSpecsList(specs, text);
|
|
156
162
|
break;
|
|
157
163
|
}
|
|
158
164
|
case "specs add": {
|
|
159
|
-
if (positional.length !== 2) throw new
|
|
165
|
+
if (positional.length !== 2) throw new UsageError("specs add: requires id and absolute repository root; use vmem specs add <id> <absolute-path> [--write mcp|cli|none] [--pii allow|deny]");
|
|
160
166
|
const value: Record<string, unknown> = { id: positional[0], path: positional[1] };
|
|
161
167
|
for (const option of options) if (flags[option] !== undefined) value[option.slice(2)] = flags[option];
|
|
162
168
|
const added = { applied: true, spec: addSpec(home.home, value, env) };
|
|
@@ -164,19 +170,19 @@ function runWith(args: string[], env: NodeJS.ProcessEnv, text: TextOptions = PLA
|
|
|
164
170
|
break;
|
|
165
171
|
}
|
|
166
172
|
case "specs remove": {
|
|
167
|
-
if (positional.length !== 1) throw new
|
|
173
|
+
if (positional.length !== 1) throw new UsageError("specs remove: requires one id; use vmem specs list, then vmem specs remove <id> [--confirm]");
|
|
168
174
|
const removed = removeSpec(home.home, positional[0]!, flags["--confirm"] === true);
|
|
169
175
|
result = removed; render = () => renderRemove("specs", removed, text);
|
|
170
176
|
break;
|
|
171
177
|
}
|
|
172
178
|
case "vaults list": {
|
|
173
|
-
if (positional.length) throw new
|
|
179
|
+
if (positional.length) throw new UsageError("vaults list: unexpected arguments");
|
|
174
180
|
const vaults = loadRegistry(home.home).vaults.map(v => ({ ...v, domains: effectiveDomains(v), pii: effectivePii(v), piiPolicy: piiPolicy(v) }));
|
|
175
181
|
result = vaults; render = () => renderVaultsList(vaults, text);
|
|
176
182
|
break;
|
|
177
183
|
}
|
|
178
184
|
case "vaults add": {
|
|
179
|
-
if (positional.length !== 2) throw new
|
|
185
|
+
if (positional.length !== 2) throw new UsageError("vaults add: requires id and absolute path");
|
|
180
186
|
const value: Record<string, unknown> = { id: positional[0], path: positional[1] };
|
|
181
187
|
for (const option of options) if (flags[option] !== undefined) value[option.slice(2)] = flags[option];
|
|
182
188
|
const added = { applied: true, vault: addVault(home.home, value) };
|
|
@@ -184,23 +190,23 @@ function runWith(args: string[], env: NodeJS.ProcessEnv, text: TextOptions = PLA
|
|
|
184
190
|
break;
|
|
185
191
|
}
|
|
186
192
|
case "vaults pii": {
|
|
187
|
-
if (positional.length !== 1) throw new
|
|
193
|
+
if (positional.length !== 1) throw new UsageError("vaults pii: requires id");
|
|
188
194
|
const raw = flags["--set"];
|
|
189
|
-
if (raw === undefined && flags["--confirm"] === true) throw new
|
|
195
|
+
if (raw === undefined && flags["--confirm"] === true) throw new UsageError("vaults pii: --confirm requires --set");
|
|
190
196
|
let value: unknown;
|
|
191
|
-
if (typeof raw === "string") { if (raw === "allow" || raw === "deny") value = raw; else { try { value = JSON.parse(raw); } catch { throw new
|
|
197
|
+
if (typeof raw === "string") { if (raw === "allow" || raw === "deny") value = raw; else { try { value = JSON.parse(raw); } catch { throw new UsageError("vaults pii: --set expects allow, deny or a JSON policy object"); } } }
|
|
192
198
|
const pii = setVaultPii(home.home, positional[0]!, value, flags["--confirm"] === true);
|
|
193
199
|
const confirm = typeof raw === "string" ? ["vmem", "vaults", "pii", positional[0]!, "--set", raw, "--confirm"].map(shellWord).join(" ") : undefined;
|
|
194
200
|
result = pii; render = () => renderVaultPii(pii, text, confirm);
|
|
195
201
|
break;
|
|
196
202
|
}
|
|
197
203
|
case "vaults remove": {
|
|
198
|
-
if (positional.length !== 1) throw new
|
|
204
|
+
if (positional.length !== 1) throw new UsageError("vaults remove: requires id");
|
|
199
205
|
const removed = removeVault(home.home, positional[0]!, flags["--confirm"] === true);
|
|
200
206
|
result = removed; render = () => renderRemove("vaults", removed, text);
|
|
201
207
|
break;
|
|
202
208
|
}
|
|
203
|
-
default: throw new
|
|
209
|
+
default: throw new UsageError(`unknown command: ${command}; use --help`);
|
|
204
210
|
}
|
|
205
211
|
return { text: flags["--json"] ? JSON.stringify(result) : render(), code };
|
|
206
212
|
}
|
|
@@ -231,9 +237,24 @@ export async function runAsync(argv: string[], env: NodeJS.ProcessEnv = process.
|
|
|
231
237
|
}
|
|
232
238
|
export async function mainAsync(args: string[]): Promise<number> {
|
|
233
239
|
try { const output = await runAsync(args, process.env, { stdinIsTTY: process.stdin.isTTY === true, stdout: process.stdout }); console.log(output.text); return output.code; }
|
|
234
|
-
catch (error) {
|
|
240
|
+
catch (error) { return reportError(error, args); }
|
|
235
241
|
}
|
|
236
242
|
export function main(args: string[]): number {
|
|
237
243
|
try { const output = run(args, process.env, process.stdout); console.log(output.text); return output.code; }
|
|
238
|
-
catch (error) {
|
|
244
|
+
catch (error) { return reportError(error, args); }
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
export function reportError(error: unknown, args: string[]): number {
|
|
248
|
+
let color: string | undefined;
|
|
249
|
+
try { color = takeColorFlag(args).color; } catch { color = "never"; }
|
|
250
|
+
let options: TextOptions;
|
|
251
|
+
try { options = textOptions(color, process.env, process.stderr); } catch { options = PLAIN; }
|
|
252
|
+
console.error(errorLine(error instanceof Error ? error.message : "operation failed", options, process.stderr.isTTY === true));
|
|
253
|
+
if (!(error instanceof UsageError)) return 1;
|
|
254
|
+
let words = args;
|
|
255
|
+
try { words = takeColorFlag(args).args; } catch { /* invalid color still receives a general usage */ }
|
|
256
|
+
const entry = [...COMMANDS].sort((a, b) => b.name.length - a.name.length).find(item => item.name.split(" ").every((word, i) => words[i] === word));
|
|
257
|
+
console.error(`Usage: vmem ${entry?.usage ?? "<command> [args]"}`);
|
|
258
|
+
console.error(`Run 'vmem help${entry ? ` ${entry.name}` : ""}' for details.`);
|
|
259
|
+
return 2;
|
|
239
260
|
}
|
package/src/commands-table.ts
CHANGED
|
@@ -16,16 +16,29 @@ export const HELP_SECTIONS = ["Registry", "Read", "Write", "Log", "Analysis", "P
|
|
|
16
16
|
interface CommandEntry { name: string; usage: string; mutates: boolean | string; section: typeof HELP_SECTIONS[number]; description: string }
|
|
17
17
|
export const COMMANDS = [
|
|
18
18
|
...SPEC_COMMANDS.map(item => ({ name: `spec ${item.command}`, usage: item.usage, mutates: ["create", "update", "delete"].includes(item.command), section: "Design specs" as const, description: SPEC_HELP[item.command] })),
|
|
19
|
+
{ name: "proposal submit", usage: "proposal submit <vault> <file|-> [--agent-label TEXT] [--json]", mutates: true, section: "Write", description: "screen and save one create or exact-patch proposal from JSON" },
|
|
20
|
+
{ name: "proposal list", usage: "proposal list <vault> [--state STATE] [--limit 1..100] [--after ID] [--json]", mutates: false, section: "Read", description: "list screened proposal summaries, pending by default" },
|
|
21
|
+
{ name: "proposal show", usage: "proposal show <vault> <id> [--offset N] [--max-bytes 1..16384] [--json]", mutates: false, section: "Read", description: "read a screened proposal operation in bounded pages" },
|
|
22
|
+
{ name: "proposal apply", usage: "proposal apply <vault> <id> [--confirm --fingerprint SHA] [--json]", mutates: "confirm", section: "Write", description: "preview or confirm a proposal using the current writer plan" },
|
|
23
|
+
{ name: "proposal reject", usage: "proposal reject <vault> <id> --reason TEXT [--confirm --fingerprint SHA] [--json]", mutates: "confirm", section: "Write", description: "preview or confirm a rejection without changing the vault" },
|
|
24
|
+
{ name: "proposal reconcile", usage: "proposal reconcile <vault> <id> [--confirm --fingerprint SHA] [--json]", mutates: "confirm", section: "Write", description: "preview or confirm receipt-backed reconciliation of an uncertain apply" },
|
|
19
25
|
{ name: "lint", usage: "lint <vault> [--note PATH] [--write] [--dry-run] [--json]", mutates: "write", section: "Analysis", description: "lint links, schema, filenames and the log; --write saves a screened report" },
|
|
20
26
|
{ name: "graph build", usage: "graph build <vault> [--workspace] [--dry-run] [--json]", mutates: true, section: "Analysis", description: "build the vault graph, or the workspace graph with --workspace, under reports/" },
|
|
21
27
|
{ name: "graph neighbors", usage: "graph neighbors <vault> <stem> [--hops 1..2] [--limit 1..500] [--relation REL] [--json]", mutates: false, section: "Analysis", description: "read a note's graph neighborhood up to two hops, optionally over one link relation" },
|
|
22
28
|
{ name: "graph path", usage: "graph path <vault> <from> <to> [--max-hops 1..6] [--relation REL] [--via-hubs] [--json]", mutates: false, section: "Analysis", description: "read the shortest link path between two notes, skipping MOC/bu hubs unless --via-hubs" },
|
|
29
|
+
{ name: "graph explain", usage: "graph explain <vault> <from> <to> [--max-hops 1..6] [--relation REL] [--via-hubs] [--json]", mutates: false, section: "Analysis", description: "explain each hop of the shortest path by its source link occurrences; structural only" },
|
|
23
30
|
{ name: "skills mine", usage: "skills mine <vault> [--days N] [--project KEY|--all-projects] [--vocab DIR] [--skills DIR] [--min-size N] [--min-novelty X] [--json]", mutates: false, section: "Analysis", description: "rank repeated work patterns in agent memory as new-skill candidates" },
|
|
24
31
|
{ name: "rebuild", usage: "rebuild <vault> [--json]", mutates: "cache", section: "Read", description: "rebuild the derived search index from the vault files" },
|
|
25
32
|
{ name: "brief", usage: "brief <vault> --for INTENT [--paths PATH]... [--bytes 256..4096] [--json]", mutates: "cache", section: "Read", description: "rank screened note pointers and one-hop neighbors within a byte cap" },
|
|
26
33
|
{ name: "search", usage: "search <vault> <query> [--type TYPE] [--domain DOMAIN] [--limit 1..500] [--json]", mutates: "cache", section: "Read", description: "full-text search notes, optionally by type and domain" },
|
|
27
|
-
{ name: "show", usage: "show <vault> <target> [--section TEXT] [--offset 0..2097152] [--max-bytes 1..65536] [--json]", mutates: "cache", section: "Read", description: "print a note's fields and body, paged by section, offset and size" },
|
|
34
|
+
{ name: "show", usage: "show <vault> <target> [--revision OID] [--section TEXT] [--offset 0..2097152] [--max-bytes 1..65536] [--json]", mutates: "cache", section: "Read", description: "print a note's fields and body, paged by section, offset and size, or one historical Git blob with --revision" },
|
|
35
|
+
{ name: "assertions", usage: "assertions <vault> [--subject S] [--relation R] [--at DATE] [--as-of INSTANT|DATE] [--history] [--limit N] [--cursor C] [--json]", mutates: false, section: "Read", description: "read verified temporal assertions with current policy and bounded pages" },
|
|
36
|
+
{ name: "assertions purge", usage: "assertions purge <vault> <assertion-id> --reason TEXT [--confirm --fingerprint SHA] [--json]", mutates: "confirm", section: "Write", description: "preview, then confirm with the fingerprint, removal of one assertion's payloads from the journal" },
|
|
37
|
+
{ name: "assertions exposure", usage: "assertions exposure <vault> [<assertion-id>] [--replace-file PATH] [--json]", mutates: false, section: "Read", description: "report purged payloads still reachable in Git history, and write a git-filter-repo replace file on request" },
|
|
38
|
+
{ name: "evidence", usage: "evidence <vault> <note> [--json]", mutates: false, section: "Read", description: "verify a note's evidence quotes against same-vault source notes; read-only, no cache" },
|
|
28
39
|
{ name: "links", usage: "links <vault> <target> [--limit 1..500] [--json]", mutates: "cache", section: "Read", description: "list a note's outgoing, dead and incoming links" },
|
|
40
|
+
{ name: "history", usage: "history <vault> <note> [--limit 1..100] [--cursor C] [--json]", mutates: false, section: "Read", description: "list one note path's Git snapshot revisions newest first, pinned to the HEAD the page started from" },
|
|
41
|
+
{ name: "changes", usage: "changes <vault> --from OID --to OID [--limit 1..500] [--cursor C] [--json]", mutates: false, section: "Read", description: "compare two pinned Git snapshots over notes/ with before/after blob ids and status" },
|
|
29
42
|
{ name: "status", usage: "status [--json]", mutates: false, section: "Registry", description: "show the home, registered vaults and spec sources, and vault health" },
|
|
30
43
|
{ name: "doctor", usage: "doctor [--json]", mutates: false, section: "Registry", description: "check vault paths, remotes, project registries, pending tidy and spec sources; exits 1 when unhealthy" },
|
|
31
44
|
{ name: "recover", usage: "recover [--confirm] [--json]", mutates: "confirm", section: "Registry", description: "preview, then remove with --confirm, a stale registry lock and leftover temporary files" },
|
|
@@ -47,6 +60,7 @@ export const COMMANDS = [
|
|
|
47
60
|
{ name: "delete", usage: "delete <vault> <note> [--confirm --fingerprint SHA] [--log JSON] [--dry-run] [--json]", mutates: "confirm", section: "Write", description: "preview backlinks, then confirm with the fingerprint, a note deletion" },
|
|
48
61
|
{ name: "tidy", usage: "tidy <vault> [--connections] [--escapes] [--enums] [--keys] [--sources] [--topics] [--secrets] [--log] [--all] [--map file] [--confirm --fingerprint SHA] [--dry-run] [--json]", mutates: "confirm", section: "Write", description: "preview, then confirm with the fingerprint, migration tidy of notes and the log" },
|
|
49
62
|
{ name: "report", usage: "report <vault> <reports/path|ops/path> --body file|- [--log JSON] [--dry-run] [--json]", mutates: true, section: "Write", description: "write a screened file under reports/ or ops/" },
|
|
63
|
+
{ name: "assert", usage: "assert <vault> --batch FILE|- [--dry-run] [--log JSON] [--json]", mutates: true, section: "Write", description: "append a validated batch of temporal assertions to the vault's assertions/ journal; writes no note" },
|
|
50
64
|
{ name: "check", usage: "check <vault> <file|-> [--path stem] [--json]", mutates: false, section: "Read", description: "validate a note file or stdin without writing it" },
|
|
51
65
|
{ name: "log tail", usage: "log tail <vault> [--limit 1..200] [--type TYPE] [--json]", mutates: false, section: "Log", description: "print the latest log events" },
|
|
52
66
|
{ name: "log grep", usage: "log grep <vault> <pattern> [--limit 1..200] [--type TYPE] [--json]", mutates: false, section: "Log", description: "search log events by pattern" },
|
|
@@ -102,7 +116,7 @@ export function completionScript(shell: string): string {
|
|
|
102
116
|
cur="\${COMP_WORDS[COMP_CWORD]}"
|
|
103
117
|
if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=($(compgen -W ${quote(top.join(" "))} -- "$cur")); return; fi
|
|
104
118
|
key="\${COMP_WORDS[1]}"
|
|
105
|
-
case "$key" in spec) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W '${SPEC_COMMANDS.map(item => item.command).join(" ")}' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; graph) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'build neighbors path' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; skills) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'mine' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; specs) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'list add remove' -- "$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
|
|
119
|
+
case "$key" in spec) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W '${SPEC_COMMANDS.map(item => item.command).join(" ")}' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; graph) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'build neighbors path explain' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; skills) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'mine' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; specs) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'list add remove' -- "$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
|
|
106
120
|
case "$key" in
|
|
107
121
|
${cases.join("\n")}
|
|
108
122
|
*) words='' ;;
|
package/src/evidence.ts
ADDED
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync } from "node:fs";
|
|
3
|
+
import { join, resolve, sep } from "node:path";
|
|
4
|
+
import type { VaultSpec } from "./config.ts";
|
|
5
|
+
import { parseFrontmatter } from "./frontmatter.ts";
|
|
6
|
+
import { canonicalPath, isDenied } from "./platform.ts";
|
|
7
|
+
import { sourceReferences, sourceWorkspaceRoot, type SourceReference } from "./source.ts";
|
|
8
|
+
import { MAX_NOTE_BYTES, h2Sections } from "./vault-index.ts";
|
|
9
|
+
|
|
10
|
+
/** Version-1 evidence entry: quoted bytes that occur in one version of one source. Not a claim of truth. */
|
|
11
|
+
export interface EvidenceEntry { source: string; sha256: string; quote: string; section?: string }
|
|
12
|
+
export const EVIDENCE_SCHEMA_VERSION = 1;
|
|
13
|
+
export const MAX_EVIDENCE_ENTRIES = 16, MAX_EVIDENCE_BYTES = 16 * 1024, MAX_QUOTE_BYTES = 2048, MAX_SECTION_BYTES = 1024;
|
|
14
|
+
export type EvidenceStatus = "verified" | "stale" | "missing" | "ambiguous" | "unverified_external" | "unsupported";
|
|
15
|
+
export type EvidenceReason = "sha_mismatch" | "source_not_found" | "quote_not_found" | "section_not_found" | "section_ambiguous" | "quote_ambiguous"
|
|
16
|
+
| "outside_vault" | "denied" | "oversized" | "invalid_utf8" | "not_a_file" | "unresolved_source_root" | "invalid_metadata" | "external_reference" | "read_budget";
|
|
17
|
+
export interface EvidenceResult {
|
|
18
|
+
index: number;
|
|
19
|
+
source: string | null;
|
|
20
|
+
kind: SourceReference["kind"] | null;
|
|
21
|
+
section?: string;
|
|
22
|
+
expectedSha256: string | null;
|
|
23
|
+
observedSha256?: string;
|
|
24
|
+
status: EvidenceStatus;
|
|
25
|
+
reason?: EvidenceReason;
|
|
26
|
+
/** Zero-based UTF-8 byte offsets of the single match in the full source file. */
|
|
27
|
+
match?: { start: number; end: number };
|
|
28
|
+
matches?: number;
|
|
29
|
+
}
|
|
30
|
+
export interface EvidenceReport {
|
|
31
|
+
schemaVersion: 1;
|
|
32
|
+
vault: string;
|
|
33
|
+
note: { path: string; sha256: string };
|
|
34
|
+
evidence: EvidenceResult[];
|
|
35
|
+
truncated: false;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
const KEYS = new Set(["source", "sha256", "quote", "section"]);
|
|
39
|
+
const sha256 = (data: Buffer | string) => createHash("sha256").update(data).digest("hex");
|
|
40
|
+
const bytes = (text: string) => Buffer.byteLength(text);
|
|
41
|
+
|
|
42
|
+
/** One entry's problem, or the entry. `sources` are the note's normalized source references. */
|
|
43
|
+
function entryProblem(value: unknown, sources: Set<string>): string | EvidenceEntry {
|
|
44
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) return "entry must be an object";
|
|
45
|
+
const entry = value as Record<string, unknown>;
|
|
46
|
+
for (const key of Object.keys(entry)) if (!KEYS.has(key)) return `unknown key ${key.slice(0, 32)}`;
|
|
47
|
+
if (typeof entry.source !== "string") return "source must be a string";
|
|
48
|
+
let ref: SourceReference;
|
|
49
|
+
try { [ref] = sourceReferences(entry.source) as [SourceReference]; } catch { return "source must be one valid source reference"; }
|
|
50
|
+
if (!sources.has(ref.value)) return "source must also be listed in the note source field";
|
|
51
|
+
if (typeof entry.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(entry.sha256)) return "sha256 must be 64 lowercase hex characters";
|
|
52
|
+
if (typeof entry.quote === "string" && !entry.quote.isWellFormed()) return "quote must be well-formed Unicode (no unpaired surrogates)";
|
|
53
|
+
if (typeof entry.section === "string" && !entry.section.isWellFormed()) return "section must be well-formed Unicode (no unpaired surrogates)";
|
|
54
|
+
if (typeof entry.quote !== "string" || !entry.quote || bytes(entry.quote) > MAX_QUOTE_BYTES) return `quote must be 1..${MAX_QUOTE_BYTES} UTF-8 bytes`;
|
|
55
|
+
if (entry.section !== undefined && (typeof entry.section !== "string" || !entry.section.trim() || /[\r\n]/.test(entry.section) || bytes(entry.section) > MAX_SECTION_BYTES)) return `section must be one exact H2 heading <=${MAX_SECTION_BYTES} bytes`;
|
|
56
|
+
return { source: ref.value, sha256: entry.sha256, quote: entry.quote, ...(entry.section !== undefined ? { section: entry.section as string } : {}) };
|
|
57
|
+
}
|
|
58
|
+
function noteSources(source: unknown): Set<string> {
|
|
59
|
+
try { return new Set(source === undefined ? [] : sourceReferences(source).map(ref => ref.value)); } catch { return new Set(); }
|
|
60
|
+
}
|
|
61
|
+
/** The first schema problem of an `evidence` field, or undefined when valid. Used by write validation. */
|
|
62
|
+
export function evidenceProblem(value: unknown, source: unknown): string | undefined {
|
|
63
|
+
if (!Array.isArray(value) || value.length < 1 || value.length > MAX_EVIDENCE_ENTRIES) return `evidence must be a list of 1..${MAX_EVIDENCE_ENTRIES} entries`;
|
|
64
|
+
if (bytes(JSON.stringify(value)) > MAX_EVIDENCE_BYTES) return `evidence must serialize to at most ${MAX_EVIDENCE_BYTES} bytes`;
|
|
65
|
+
const sources = noteSources(source);
|
|
66
|
+
for (const [index, item] of value.entries()) {
|
|
67
|
+
const found = entryProblem(item, sources);
|
|
68
|
+
if (typeof found === "string") return `evidence[${index}]: ${found}`;
|
|
69
|
+
}
|
|
70
|
+
return undefined;
|
|
71
|
+
}
|
|
72
|
+
/** Parse evidence leniently: valid entries, or the problem per entry. A non-list or oversized field is one problem. */
|
|
73
|
+
export function parseEvidence(value: unknown, source: unknown): { entries: (EvidenceEntry | { problem: string })[]; problem?: string } {
|
|
74
|
+
if (value === undefined) return { entries: [] };
|
|
75
|
+
if (!Array.isArray(value) || value.length < 1 || value.length > MAX_EVIDENCE_ENTRIES || bytes(JSON.stringify(value)) > MAX_EVIDENCE_BYTES)
|
|
76
|
+
return { entries: [], problem: `evidence must be a list of 1..${MAX_EVIDENCE_ENTRIES} entries within ${MAX_EVIDENCE_BYTES} bytes` };
|
|
77
|
+
const sources = noteSources(source);
|
|
78
|
+
return { entries: value.map(item => { const found = entryProblem(item, sources); return typeof found === "string" ? { problem: found } : found; }) };
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** Read a plain file without following a final symlink, refusing over the note bound. */
|
|
82
|
+
export interface EvidenceReadBudget { remainingBytes: number; remainingFiles: number }
|
|
83
|
+
function boundedRead(file: string, budget?: EvidenceReadBudget): Buffer | "not_a_file" | "oversized" | "read_budget" {
|
|
84
|
+
if (budget && budget.remainingBytes <= 0) return "read_budget";
|
|
85
|
+
const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
|
|
86
|
+
try {
|
|
87
|
+
const stat = fstatSync(fd);
|
|
88
|
+
if (!stat.isFile()) return "not_a_file";
|
|
89
|
+
if (stat.size > MAX_NOTE_BYTES) return "oversized";
|
|
90
|
+
if (budget && stat.size > budget.remainingBytes) return "read_budget";
|
|
91
|
+
if (budget) budget.remainingBytes -= stat.size;
|
|
92
|
+
const buffer = Buffer.alloc(stat.size); let read = 0;
|
|
93
|
+
while (read < stat.size) { const n = readSync(fd, buffer, read, stat.size - read, null); if (!n) break; read += n; }
|
|
94
|
+
if (fstatSync(fd).size !== stat.size) return "oversized";
|
|
95
|
+
return buffer.subarray(0, read);
|
|
96
|
+
} finally { closeSync(fd); }
|
|
97
|
+
}
|
|
98
|
+
const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
|
|
99
|
+
|
|
100
|
+
/** Resolve a workspace-relative path reference to a flat `notes/*.md` of `vault`, or the reason it is not one. */
|
|
101
|
+
type Resolved = { ok: true; path: string } | { ok: false; reason: EvidenceReason };
|
|
102
|
+
function resolveVaultNote(vault: VaultSpec, root: string, value: string, denyPaths: readonly string[]): Resolved {
|
|
103
|
+
const lexical = resolve(root, value);
|
|
104
|
+
if (isDenied(canonicalPath(lexical), [...denyPaths]) || isDenied(value, [...denyPaths])) return { ok: false, reason: "denied" };
|
|
105
|
+
let real: string, vaultReal: string;
|
|
106
|
+
try { vaultReal = realpathSync(vault.path); } catch { return { ok: false, reason: "source_not_found" }; }
|
|
107
|
+
try { real = realpathSync(lexical); } catch { return { ok: false, reason: "source_not_found" }; }
|
|
108
|
+
const notes = join(vaultReal, "notes") + sep;
|
|
109
|
+
if (!real.startsWith(notes) || real.slice(notes.length).includes(sep) || !/^[^/\\]+\.md$/.test(real.slice(notes.length))) return { ok: false, reason: "outside_vault" };
|
|
110
|
+
if (isDenied(real, [...denyPaths])) return { ok: false, reason: "denied" };
|
|
111
|
+
try { if (lstatSync(real).isSymbolicLink()) return { ok: false, reason: "outside_vault" }; } catch { return { ok: false, reason: "source_not_found" }; }
|
|
112
|
+
return { ok: true, path: real };
|
|
113
|
+
}
|
|
114
|
+
/** Literal occurrence count (overlapping) and the first index, capped at two. */
|
|
115
|
+
function occurrences(haystack: string, needle: string): { count: number; first: number } {
|
|
116
|
+
const first = haystack.indexOf(needle);
|
|
117
|
+
if (first < 0) return { count: 0, first };
|
|
118
|
+
return { count: haystack.indexOf(needle, first + 1) < 0 ? 1 : 2, first };
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/** Verify one parsed entry. Every call reads the source afresh; nothing is cached. */
|
|
122
|
+
/** Per-run read memo keyed by resolved real path. Callers create one per run; it is never kept across calls. */
|
|
123
|
+
export type EvidenceReads = Map<string, ReturnType<typeof boundedRead>>;
|
|
124
|
+
export function verifyEvidenceEntry(vault: VaultSpec, entry: EvidenceEntry, index: number, denyPaths: readonly string[] = [], reads?: EvidenceReads, budget?: EvidenceReadBudget): EvidenceResult {
|
|
125
|
+
const ref = sourceReferences(entry.source)[0]!;
|
|
126
|
+
const base: EvidenceResult = { index, source: ref.value, kind: ref.kind, ...(entry.section !== undefined ? { section: entry.section } : {}), expectedSha256: entry.sha256, status: "unsupported" };
|
|
127
|
+
if (ref.kind !== "path") return { ...base, status: "unverified_external", reason: "external_reference" };
|
|
128
|
+
if (budget) {
|
|
129
|
+
if (budget.remainingFiles <= 0 || budget.remainingBytes <= 0) return { ...base, reason: "read_budget" };
|
|
130
|
+
budget.remainingFiles--;
|
|
131
|
+
}
|
|
132
|
+
const root = sourceWorkspaceRoot(vault);
|
|
133
|
+
if (!root) return { ...base, reason: "unresolved_source_root" };
|
|
134
|
+
const located = resolveVaultNote(vault, root, ref.value, denyPaths);
|
|
135
|
+
if (!located.ok) return located.reason === "source_not_found" ? { ...base, status: "missing", reason: located.reason } : { ...base, reason: located.reason };
|
|
136
|
+
let data: ReturnType<typeof boundedRead>;
|
|
137
|
+
try {
|
|
138
|
+
const cached = reads?.get(located.path);
|
|
139
|
+
data = cached ?? boundedRead(located.path, budget);
|
|
140
|
+
if (!cached) reads?.set(located.path, data);
|
|
141
|
+
} catch { return { ...base, status: "missing", reason: "source_not_found" }; }
|
|
142
|
+
if (data === "not_a_file" || data === "oversized" || data === "read_budget") return { ...base, reason: data };
|
|
143
|
+
let text: string;
|
|
144
|
+
try { text = utf8.decode(data); } catch { return { ...base, reason: "invalid_utf8" }; }
|
|
145
|
+
const observed = sha256(data), seen = { ...base, observedSha256: observed };
|
|
146
|
+
let start = 0, end = text.length;
|
|
147
|
+
if (entry.section !== undefined) {
|
|
148
|
+
let body: string;
|
|
149
|
+
try { body = parseFrontmatter(text).body; } catch { body = text; }
|
|
150
|
+
const offset = text.length - body.length, found = h2Sections(body).filter(s => s.name === entry.section);
|
|
151
|
+
if (!found.length) return { ...seen, status: "missing", reason: "section_not_found" };
|
|
152
|
+
if (found.length > 1) return { ...seen, status: "ambiguous", reason: "section_ambiguous" };
|
|
153
|
+
start = offset + found[0]!.start; end = offset + found[0]!.end;
|
|
154
|
+
}
|
|
155
|
+
const { count, first } = occurrences(text.slice(start, end), entry.quote);
|
|
156
|
+
if (count === 0) return { ...seen, status: observed === entry.sha256 ? "missing" : "stale", reason: observed === entry.sha256 ? "quote_not_found" : "sha_mismatch", matches: 0 };
|
|
157
|
+
if (count > 1) return { ...seen, status: observed === entry.sha256 ? "ambiguous" : "stale", reason: observed === entry.sha256 ? "quote_ambiguous" : "sha_mismatch", matches: count };
|
|
158
|
+
const byteStart = bytes(text.slice(0, start + first)), match = { start: byteStart, end: byteStart + bytes(entry.quote) };
|
|
159
|
+
if (observed !== entry.sha256) return { ...seen, status: "stale", reason: "sha_mismatch", matches: 1, match };
|
|
160
|
+
return { ...seen, status: "verified", matches: 1, match };
|
|
161
|
+
}
|
|
162
|
+
/** Verify every evidence entry of a parsed note's frontmatter, in order. Malformed entries are `unsupported`/`invalid_metadata`. */
|
|
163
|
+
export function verifyNoteEvidence(vault: VaultSpec, data: Record<string, unknown>, denyPaths: readonly string[] = [], reads?: EvidenceReads): EvidenceResult[] {
|
|
164
|
+
const parsed = parseEvidence(data.evidence, data.source);
|
|
165
|
+
if (parsed.problem) return [{ index: 0, source: null, kind: null, expectedSha256: null, status: "unsupported", reason: "invalid_metadata" }];
|
|
166
|
+
return parsed.entries.map((entry, index) => "problem" in entry
|
|
167
|
+
? { index, source: null, kind: null, expectedSha256: null, status: "unsupported", reason: "invalid_metadata" }
|
|
168
|
+
: verifyEvidenceEntry(vault, entry, index, denyPaths, reads));
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/** Locate a flat note of `vault` by stem or `notes/<stem>.md` without the index, refusing links and denied paths. */
|
|
172
|
+
function noteFile(vault: VaultSpec, target: string, denyPaths: readonly string[]): string {
|
|
173
|
+
const stem = target.replace(/^notes\//, "").replace(/\.md$/, "");
|
|
174
|
+
if (!stem || Buffer.byteLength(stem) > 200 || /[/\\\0]/.test(stem) || stem.startsWith(".")) throw Object.assign(new Error("note: expected a flat note stem or notes/<stem>.md"), { code: "V04" });
|
|
175
|
+
const root = realpathSync(vault.path);
|
|
176
|
+
if (root !== resolve(vault.path)) throw Object.assign(new Error(`vault ${vault.id}: registered path changed; re-register it with vmem vaults add and restart the MCP server`), { code: "V04" });
|
|
177
|
+
const file = join(root, "notes", `${stem}.md`);
|
|
178
|
+
if (isDenied(file, [...denyPaths])) throw Object.assign(new Error("note: denied by the denyPaths setting or built-in secret rules; check the policy with vmem status"), { code: "V06" });
|
|
179
|
+
for (const part of [join(root, "notes"), file]) {
|
|
180
|
+
let stat;
|
|
181
|
+
try { stat = lstatSync(part); } catch { throw Object.assign(new Error(`note: unknown target; find the note stem with vmem search ${vault.id} <query>`), { code: "V04" }); }
|
|
182
|
+
if (stat.isSymbolicLink()) throw Object.assign(new Error("note: symlinked paths are refused; replace the link with the note file itself"), { code: "V04" });
|
|
183
|
+
}
|
|
184
|
+
return file;
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* Shared read provider for `vmem evidence` and `vmem_evidence`. Pass the vault spec freshly loaded from the registry:
|
|
189
|
+
* the source root is rebound on every call. Writes nothing, takes no lock and keeps no cache.
|
|
190
|
+
*/
|
|
191
|
+
export function evidenceReport(vault: VaultSpec, target: string, denyPaths: readonly string[] = []): EvidenceReport {
|
|
192
|
+
const file = noteFile(vault, target, denyPaths), data = boundedRead(file);
|
|
193
|
+
if (typeof data === "string") throw Object.assign(new Error(`note: ${data === "oversized" ? "exceeds the 2 MiB read bound; split the note" : "not a regular file"}`), { code: "V09" });
|
|
194
|
+
let text: string;
|
|
195
|
+
try { text = utf8.decode(data); } catch { throw Object.assign(new Error(`note: not valid UTF-8; validate it with vmem check ${vault.id} <file>`), { code: "V01" }); }
|
|
196
|
+
let fm: Record<string, unknown>;
|
|
197
|
+
try { fm = parseFrontmatter(text).data; } catch { throw Object.assign(new Error(`note: frontmatter is not parseable; validate it with vmem check ${vault.id} <file>`), { code: "V01" }); }
|
|
198
|
+
const path = `notes/${file.slice(file.lastIndexOf(sep) + 1)}`;
|
|
199
|
+
return { schemaVersion: 1, vault: vault.id, note: { path, sha256: sha256(data) }, evidence: verifyNoteEvidence(vault, fm, denyPaths), truncated: false };
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/**
|
|
203
|
+
* Org promotion screen: keep only entries whose source stays meaningful at `target`. URLs stay unverified external;
|
|
204
|
+
* memory ids and paths that do not resolve to a target-vault note are removed. Removal reasons carry no path or quote.
|
|
205
|
+
*/
|
|
206
|
+
export function screenEvidenceForTarget(value: unknown, source: unknown, target: VaultSpec, denyPaths: readonly string[] = []): { kept: EvidenceEntry[] | undefined; removed: { index: number; reason: string }[] } {
|
|
207
|
+
if (value === undefined) return { kept: undefined, removed: [] };
|
|
208
|
+
const parsed = parseEvidence(value, source);
|
|
209
|
+
if (parsed.problem) return { kept: undefined, removed: [{ index: 0, reason: "invalid_metadata" }] };
|
|
210
|
+
const root = sourceWorkspaceRoot(target), kept: EvidenceEntry[] = [], removed: { index: number; reason: string }[] = [];
|
|
211
|
+
for (const [index, entry] of parsed.entries.entries()) {
|
|
212
|
+
if ("problem" in entry) { removed.push({ index, reason: "invalid_metadata" }); continue; }
|
|
213
|
+
const ref = sourceReferences(entry.source)[0]!;
|
|
214
|
+
if (ref.kind === "url") { kept.push(entry); continue; }
|
|
215
|
+
if (ref.kind === "memory") { removed.push({ index, reason: "memory_not_retained" }); continue; }
|
|
216
|
+
if (!root) { removed.push({ index, reason: "unresolved_source_root" }); continue; }
|
|
217
|
+
const located = resolveVaultNote(target, root, ref.value, denyPaths);
|
|
218
|
+
if (located.ok) kept.push(entry);
|
|
219
|
+
else removed.push({ index, reason: located.reason === "denied" ? "denied" : "not_in_destination" });
|
|
220
|
+
}
|
|
221
|
+
return { kept: kept.length ? kept : undefined, removed };
|
|
222
|
+
}
|