@staix/vault-mem 0.5.1 → 0.6.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 +60 -0
- package/README.md +138 -23
- package/package.json +5 -4
- package/src/amem/seam.ts +15 -6
- package/src/analysis-commands.ts +1 -1
- package/src/analysis-input.ts +24 -3
- package/src/analysis-reports.ts +1 -1
- package/src/analysis-types.ts +13 -1
- package/src/canon-tables.ts +190 -0
- package/src/cli-output.ts +15 -1
- package/src/cli.ts +1 -1
- package/src/commands-table.ts +6 -2
- package/src/config.ts +31 -3
- package/src/frontmatter.ts +10 -3
- package/src/links.ts +13 -1
- package/src/mcp-spec.ts +19 -11
- package/src/mcp-vault.ts +14 -9
- package/src/mcp.ts +4 -2
- package/src/org-promote.ts +29 -12
- package/src/promote.ts +24 -12
- package/src/read-commands.ts +1 -2
- package/src/read-output.ts +7 -5
- package/src/registry.ts +1 -0
- package/src/skills-mine.ts +5 -4
- package/src/spec-command-table.ts +10 -1
- package/src/spec-commands.ts +7 -3
- package/src/spec-gitlinks.ts +106 -0
- package/src/spec-output.ts +30 -0
- package/src/spec-source.ts +9 -3
- package/src/spec-validate.ts +6 -3
- package/src/spec-write.ts +469 -0
- package/src/ui/inbox.ts +28 -10
- package/src/ui/panel.js +26 -5
- package/src/ui/plugin.ts +38 -12
- package/src/ui/snapshot-cache.ts +123 -0
- package/src/vault-index.ts +109 -19
- package/src/vault-lint.ts +53 -5
- package/src/vault-log.ts +3 -2
- package/src/vault-stats.ts +110 -5
- package/src/write-commands.ts +4 -3
- package/src/write-files.ts +63 -0
- package/src/write-operations.ts +175 -25
- package/src/write-output.ts +20 -9
- package/src/write-types.ts +8 -1
- package/src/write-validation.ts +46 -17
- package/src/writer.ts +137 -41
- package/src/yaml-quoted.ts +12 -2
package/src/mcp-spec.ts
CHANGED
|
@@ -6,23 +6,27 @@ import { resolveHome } from "./home.ts";
|
|
|
6
6
|
import { loadRegistry } from "./registry.ts";
|
|
7
7
|
import { PLAIN, type TextOptions } from "./text-output.ts";
|
|
8
8
|
import { renderSpec } from "./spec-output.ts";
|
|
9
|
+
import type { SpecWriteResult } from "./spec-write.ts";
|
|
9
10
|
|
|
10
|
-
/** Spec
|
|
11
|
+
/** Spec definitions retain read annotations for reads; create/update/delete are policy-gated mutations. */
|
|
11
12
|
export const specTools = (): McpTool[] => SPEC_COMMANDS.map(item => ({ name: item.name, description: item.description, inputSchema: item.inputSchema,
|
|
12
|
-
annotations: { readOnlyHint:
|
|
13
|
+
annotations: { readOnlyHint: !["create", "update", "delete"].includes(item.command), destructiveHint: item.command === "delete", idempotentHint: item.command !== "create" && item.command !== "delete", openWorldHint: false } }));
|
|
13
14
|
|
|
14
15
|
export function createSpecMcp(home: string, env: NodeJS.ProcessEnv = process.env): { tools: McpTool[]; handlers: Record<string, McpHandler> } {
|
|
15
16
|
const registered = loadRegistry(home).specs ?? [];
|
|
16
17
|
const tools = specTools();
|
|
17
18
|
const handlers: Record<string, McpHandler> = {};
|
|
18
|
-
for (const item of SPEC_COMMANDS) handlers[item.name] = args => {
|
|
19
|
+
for (const [index, item] of SPEC_COMMANDS.entries()) handlers[item.name] = args => {
|
|
19
20
|
const invalid = argumentError(args, item.inputSchema);
|
|
20
|
-
if (invalid) throw new Error(invalid);
|
|
21
|
+
if (invalid) throw new Error(`${invalid}; see vmem spec ${item.command} --help to correct the arguments`);
|
|
21
22
|
const selected = registered.find(source => source.id === (args.source ?? registered[0]?.id));
|
|
22
23
|
if (!selected) throw new Error("spec source: no matching source in the server's startup registry; pass the source argument with a registered id, or register with vmem specs add and restart the MCP server");
|
|
23
24
|
const current = loadRegistry(home).specs?.find(source => source.id === selected.id);
|
|
24
|
-
if (!current || JSON.stringify(current) !== JSON.stringify(selected)) throw new Error("spec source: registry changed since server startup; restart the MCP server before
|
|
25
|
-
|
|
25
|
+
if (!current || JSON.stringify(current) !== JSON.stringify(selected)) throw new Error("spec source: registry changed since server startup; restart the MCP server before retrying the spec command");
|
|
26
|
+
const result = executeSpecCommand(home, item.command, { ...args, source: selected.id }, env, { channel: "mcp", binding: selected });
|
|
27
|
+
if (tools[index]!.annotations.readOnlyHint !== false) return result;
|
|
28
|
+
const receipt = result as SpecWriteResult;
|
|
29
|
+
return !receipt.ok && !receipt.changed ? { ...receipt, refused: true } : receipt;
|
|
26
30
|
};
|
|
27
31
|
return { tools, handlers };
|
|
28
32
|
}
|
|
@@ -33,7 +37,9 @@ export function runSpecCommand(args: string[], env: NodeJS.ProcessEnv = process.
|
|
|
33
37
|
if (!item) throw new Error("spec: unknown command; use vmem spec --help");
|
|
34
38
|
const values: Record<string, unknown> = {}, positional: string[] = [];
|
|
35
39
|
const properties = item.inputSchema.properties as Record<string, { type: string }>;
|
|
36
|
-
const
|
|
40
|
+
const takesId = item.command === "get" || item.command === "graph" || item.command === "update" || item.command === "delete";
|
|
41
|
+
const positionalKey = item.command === "create" ? "path" : takesId ? "id" : item.command === "grep" ? "query" : undefined;
|
|
42
|
+
const flags = new Map(Object.keys(properties).filter(key => key !== positionalKey).map(key => ["--" + key.replace(/[A-Z]/g, value => "-" + value.toLowerCase()), key]));
|
|
37
43
|
const seen = new Set<string>(); let json = false, repo: string | undefined, positionalOnly = false;
|
|
38
44
|
for (let i = 1; i < args.length; i++) {
|
|
39
45
|
const flag = args[i]!;
|
|
@@ -55,17 +61,19 @@ export function runSpecCommand(args: string[], env: NodeJS.ProcessEnv = process.
|
|
|
55
61
|
if (properties[key!]!.type === "integer") {
|
|
56
62
|
if (!/^[0-9]+$/.test(value)) throw new Error(`${flag}: expected integer; see vmem spec ${item.command} --help for its bounds`);
|
|
57
63
|
values[key!] = Number(value);
|
|
64
|
+
} else if (properties[key!]!.type === "object" || properties[key!]!.type === "array") {
|
|
65
|
+
try { values[key!] = JSON.parse(value); }
|
|
66
|
+
catch { throw new Error(`${flag}: invalid JSON; supply a JSON ${properties[key!]!.type} as shown by vmem spec ${item.command} --help`); }
|
|
58
67
|
} else values[key!] = value;
|
|
59
68
|
}
|
|
60
|
-
|
|
61
|
-
if (positional
|
|
62
|
-
if (positional[0] !== undefined) values[takesId ? "id" : "query"] = positional[0];
|
|
69
|
+
if (positional.length > (item.command === "validate" ? 0 : 1) || ((takesId || item.command === "create") && positional.length !== 1)) throw new Error(`spec ${item.command}: unexpected targets; use vmem ${item.usage}`);
|
|
70
|
+
if (positional[0] !== undefined && positionalKey !== undefined) values[positionalKey] = positional[0];
|
|
63
71
|
const invalid = argumentError(values, item.inputSchema);
|
|
64
72
|
if (invalid) throw new Error(`${invalid}; see vmem spec ${item.command} --help to correct the arguments`);
|
|
65
73
|
if (repo !== undefined && (values.source !== undefined || values.worktree !== undefined)) throw new Error("--repo cannot be combined with --source or --worktree; choose registry-free or registered validation");
|
|
66
74
|
const result = repo !== undefined
|
|
67
75
|
? validateSpecRepo(repo, { requireFresh: values.requireFresh as boolean | undefined, limit: values.limit as number | undefined, env }).report
|
|
68
76
|
: executeSpecCommand(resolveHome(env).home, item.command, values, env);
|
|
69
|
-
const code =
|
|
77
|
+
const code = ["validate", "create", "update", "delete"].includes(item.command) && !(result as { ok: boolean }).ok ? 1 : 0;
|
|
70
78
|
return { text: json ? JSON.stringify(result) : renderSpec(item.command, result, text, { args, values, ...(repo !== undefined ? { repo } : {}) }), code };
|
|
71
79
|
}
|
package/src/mcp-vault.ts
CHANGED
|
@@ -33,7 +33,10 @@ const metadata = { type: "object", maxProperties: 32, properties: { authors: { t
|
|
|
33
33
|
|
|
34
34
|
/** Tool names for the implemented read, write, log, analysis and promotion providers. */
|
|
35
35
|
export const VMEM_TOOL_NAMES = ["vmem_status", "vmem_search", "vmem_read", "vmem_read_many", "vmem_list", "vmem_links", "vmem_mocs", "vmem_check", "vmem_log_tail",
|
|
36
|
-
"vmem_create", "vmem_patch", "vmem_append", "vmem_set_frontmatter", "vmem_link", "vmem_supersede", "vmem_log_append", "vmem_move", "vmem_delete", "vmem_promote_from_amem", "vmem_lint", "vmem_graph_build", "vmem_graph_neighbors", "vmem_promote", "vmem_skills_mine", "vmem_read_file", "vmem_list_files", "vmem_report", "vmem_stats", ...SPEC_COMMANDS.map(item => item.name)] as const;
|
|
36
|
+
"vmem_create", "vmem_patch", "vmem_append", "vmem_set_frontmatter", "vmem_link", "vmem_supersede", "vmem_log_append", "vmem_move", "vmem_merge", "vmem_delete", "vmem_promote_from_amem", "vmem_lint", "vmem_graph_build", "vmem_graph_neighbors", "vmem_promote", "vmem_skills_mine", "vmem_read_file", "vmem_list_files", "vmem_report", "vmem_stats", ...SPEC_COMMANDS.map(item => item.name)] as const;
|
|
37
|
+
|
|
38
|
+
/** Server `initialize` instructions: purpose, navigation order and the write contract. Pinned by a test, under 400 bytes. */
|
|
39
|
+
export const VMEM_INSTRUCTIONS = "vmem is a vault of durable, linked knowledge: notes with frontmatter, wiki-links and an append-only log. Search first with vmem_search, then read the best match with vmem_read, using section for one H2. Writes are validated and receipted: a refusal lists issues, and a failure after publication can leave changes behind, so read the receipt and its issues before retrying.";
|
|
37
40
|
|
|
38
41
|
/** Tool definitions for a fixed vault set: `vault` is an enum of the registered ids. */
|
|
39
42
|
export function vaultTools(ids: readonly string[], orgIds: readonly string[] = []): McpTool[] {
|
|
@@ -46,7 +49,7 @@ export function vaultTools(ids: readonly string[], orgIds: readonly string[] = [
|
|
|
46
49
|
tool("vmem_read", "Read one note by stem, alias or notes/ path: frontmatter, body, sha256. Bounded by maxBytes; section selects an exact H2, offset pages UTF-8 byte ranges, and truncated reads list H2 headings/nextOffset.", object({ path: note, vault, maxBytes: integer(1, 65536), section: string(1024), offset: integer(0, MAX_NOTE_BYTES) }, ["path"])),
|
|
47
50
|
tool("vmem_read_many", "Read up to 20 notes (8 KiB each).", object({ paths: { type: "array", minItems: 1, maxItems: 20, items: note }, vault }, ["paths"])),
|
|
48
51
|
tool("vmem_list", "List indexed notes under notes/ in path order, optionally by stem prefix, with each note's mtime and the filtered total. Pass the returned nextCursor as cursor for the next page.", object({ vault, prefix: string(256, 0), limit: integer(1, 500), cursor: string(1024) })),
|
|
49
|
-
tool("vmem_links", "Outgoing links (with resolution) and/or incoming backlinks of a note.", object({ path: note, vault, direction: { type: "string", enum: ["out", "in", "both"] }, limit: integer(1, 200) }, ["path"])),
|
|
52
|
+
tool("vmem_links", "Outgoing links (with resolution) and/or incoming backlinks of a note. Each dead link carries at most one suggested existing target from the title search, with its score; it is a hint and the link is never rewritten.", object({ path: note, vault, direction: { type: "string", enum: ["out", "in", "both"] }, limit: integer(1, 200) }, ["path"])),
|
|
50
53
|
tool("vmem_mocs", "MOC notes with incoming link counts.", object({ vault })),
|
|
51
54
|
tool("vmem_check", "Validate a prospective note text without writing.", object({ vault, path: string(200), text: string(262144, 0) }, ["text"])),
|
|
52
55
|
tool("vmem_log_tail", "Read the newest vault log lines, optionally filtered.", object({ vault, n: integer(1, 200), type: { type: "string", enum: LOG_TYPES }, grep: string(256) })),
|
|
@@ -58,20 +61,21 @@ export function vaultTools(ids: readonly string[], orgIds: readonly string[] = [
|
|
|
58
61
|
tool("vmem_supersede", "Mark a note superseded by another.", object({ vault, old: note, next: note, log: logEvent }, ["old", "next"]), "write"),
|
|
59
62
|
tool("vmem_log_append", "Append one validated event line to the vault log.", object({ vault, type: { type: "string", enum: LOG_TYPES }, project: string(64), source: string(512), dest: string(512), note: string(500) }, ["type", "project", "source", "note"]), "write"),
|
|
60
63
|
tool("vmem_move", "Two-step rename with link rewrites: without confirm returns preview and fingerprint; then confirm=true with that fingerprint (pass log on the confirm call).", object({ vault, from: note, to: note, ...twoStep, log: logEvent }, ["from", "to"]), "confirm"),
|
|
64
|
+
tool("vmem_merge", "Two-step note merge: without confirm returns merged body, source/topic unions, inbound link rewrites and fingerprint without writing. Then confirm=true with that fingerprint writes keep, repoints inbound links and marks absorb superseded under one mutation lock (pass log on the confirm call). Different types, person/moc notes and oversized results refuse.", object({ vault, keep: note, absorb: note, ...twoStep, log: logEvent }, ["keep", "absorb"]), "confirm"),
|
|
61
65
|
tool("vmem_delete", "Two-step delete: without confirm returns preview (or refusal), backlinks and fingerprint; then confirm=true with that fingerprint (pass log on the confirm call).", object({ vault, path: note, ...twoStep, log: logEvent }, ["path"]), "confirm"),
|
|
62
|
-
tool("vmem_promote_from_amem", "Two-step promotion of one durable agent-mem entry (id from amem_vault_candidates) into a vault note: without confirm returns the full note text, possible duplicates and fingerprint; confirm=true with that fingerprint creates the note, logs LEARN and records the agent-mem vault link. linkTo links an existing note instead.",
|
|
66
|
+
tool("vmem_promote_from_amem", "Two-step promotion of one durable agent-mem entry (id from amem_vault_candidates) into a vault note: without confirm returns the full note text, possible duplicates and fingerprint; confirm=true with that fingerprint creates the note, logs LEARN and records the agent-mem vault link. linkTo links an existing note instead. Configured canonTables add advisory canonical row matches and link-existing choices, outside the fingerprint and never blocking confirm.",
|
|
63
67
|
object({ vault, id: { type: "string", minLength: 32, maxLength: 36 }, stem: string(120), type: string(64), domain: string(64), topics: { type: "array", maxItems: 32, items: string(200) }, description: string(1000), title: string(300), body: string(65536, 0), linkTo: note, project: string(400), ...twoStep }, ["id"]), "confirm"),
|
|
64
68
|
tool("vmem_lint", "Lint a private derived snapshot; write=true writes a screened report.", object({ vault, write: { type: "boolean" }, dryRun: { type: "boolean" } }), "write"),
|
|
65
69
|
tool("vmem_graph_build", "Build a deterministic graph and screened reports; dryRun changes nothing.", object({ vault, dryRun: { type: "boolean" }, workspace: { type: "boolean" } }), "write"),
|
|
66
70
|
tool("vmem_graph_neighbors", "Read a bounded graph neighborhood.", object({ vault, path: note, hops: integer(1,2), limit: integer(1,500), relation: { type: "string", enum: ["wiki_link", ...LINK_RELATIONS] } }, ["path"])),
|
|
67
|
-
tool("vmem_promote", "Two-step promotion of a personal note into a local org vault clone (never pushes): without confirm returns the full transformed text, dropped links, screen result and fingerprint; confirm=true with that fingerprint writes the org note, source provenance and SYNC log lines. Publishing is the separate `vmem sync` CLI.",
|
|
71
|
+
tool("vmem_promote", "Two-step promotion of a personal note into a local org vault clone (never pushes): without confirm returns the full transformed text, dropped links, screen result and fingerprint; confirm=true with that fingerprint writes the org note, source provenance and SYNC log lines. Configured target-vault canonTables add advisory canonical row matches and link-existing choices; personal rows are never included and matches do not affect the fingerprint or block confirm. Publishing is the separate `vmem sync` CLI.",
|
|
68
72
|
object({ path: note, to: orgVault, topics: { type: "array", maxItems: 32, items: string(200) }, again: { type: "boolean" }, ...twoStep }, ["path", "to"]), "confirm"),
|
|
69
73
|
tool("vmem_skills_mine", "Read-only skill-candidate mining over amem curated entries, amem capture rows and vault notes: dictionary matching, deterministic communities and novelty scoring. Returns counts, masked candidates and a markdown report; writes nothing.",
|
|
70
74
|
object({ vault, days: integer(1, 3650), project: string(400), allProjects: { type: "boolean" }, vocab: string(4096), skills: { type: "array", maxItems: 16, items: string(4096) }, minSize: integer(1, 10000), minNovelty: { type: "number", minimum: 0, maximum: 1 } })),
|
|
71
75
|
tool("vmem_read_file", "Read one UTF-8 file outside notes/: ops/, reports/, self/, templates/, AGENTS.md or README.md. Same bounds and paging as vmem_read (maxBytes, offset, nextOffset); notes/ use vmem_read, the log vmem_log_tail. Never locks or writes.", object({ vault, path: string(1024), maxBytes: integer(1, 65536), offset: integer(0, MAX_NOTE_BYTES) }, ["path"])),
|
|
72
76
|
tool("vmem_list_files", "List one directory level under ops/, reports/, self/ or templates/ (up to 500 entries; dot, linked and denied entries omitted). Never locks or writes.", object({ vault, dir: string(1024) }, ["dir"])),
|
|
73
77
|
tool("vmem_report", "Write a screened report file under reports/ or ops/ (the MCP form of `vmem report`): same path rules, screening, write policy (write=mcp), receipt and EXTRACT log event; log overrides it, for example a LINT or GRAPH event. dryRun changes nothing.", object({ vault, path: string(200), body: string(65536, 0), dryRun: { type: "boolean" }, log: logEvent }, ["path", "body"]), "write"),
|
|
74
|
-
tool("vmem_stats", "Read-only vault statistics: note counts by type, domain and status, notes modified in the last 7 and 30 days, and log event counts by type over the last `days` (default 30). Writes no vault file or log and takes no vault or log lock.", object({ vault, days: integer(1, STATS_MAX_DAYS) })),
|
|
78
|
+
tool("vmem_stats", "Read-only vault statistics: note counts by type, domain and status, note bytes and words in total and by type and domain, and the note-to-source byte ratio (median, p90 and the largest notes) over the workspace files the notes cite. A source counts at its own byte size on disk, so a decoded byte count never inflates a file that is not UTF-8; non-file, unreadable and over-cap sources are skipped and counted, and `truncatedNotes` counts the sourced notes the ratio's 10000-note cap left out. Also notes modified in the last 7 and 30 days, and log event counts by type over the last `days` (default 30). Writes no vault file or log and takes no vault or log lock.", object({ vault, days: integer(1, STATS_MAX_DAYS) })),
|
|
75
79
|
];
|
|
76
80
|
}
|
|
77
81
|
type Issue = { code: string; severity: "error"; message: string };
|
|
@@ -82,7 +86,7 @@ const str = (value: unknown): string | undefined => typeof value === "string" ?
|
|
|
82
86
|
* Handlers over the shared providers (VaultIndex, applyWrite, appendLog/readLog). The vault set and
|
|
83
87
|
* the default (first personal) are fixed when the server starts; later registry changes need a restart.
|
|
84
88
|
*/
|
|
85
|
-
export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.env): { tools: McpTool[]; handlers: Record<string, McpHandler>; vaults: VaultSpec[]; defaultVault: string | undefined } {
|
|
89
|
+
export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.env): { tools: McpTool[]; handlers: Record<string, McpHandler>; vaults: VaultSpec[]; defaultVault: string | undefined; instructions: string } {
|
|
86
90
|
const vaults = loadRegistry(home).vaults, ids = vaults.map(v => v.id);
|
|
87
91
|
const defaultVault = (vaults.find(v => v.kind === "personal") ?? vaults[0])?.id;
|
|
88
92
|
const pick = (args: Record<string, unknown>): VaultSpec => {
|
|
@@ -98,7 +102,7 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
|
|
|
98
102
|
const write = (args: Record<string, unknown>, operation: WriteOp, extra: Partial<WriteRequest> = {}): WriteReceipt | ReturnType<typeof refusal> & Partial<WriteReceipt> => {
|
|
99
103
|
const request: WriteRequest = { vault: pick(args).id, operation, channel: "mcp", ...extra, ...(args.log ? { log: args.log as LogEvent } : {}) };
|
|
100
104
|
const receipt = applyWrite(home, request, { env });
|
|
101
|
-
return receipt.ok ? receipt : { ...receipt, refused: true };
|
|
105
|
+
return receipt.ok || receipt.applied ? receipt : { ...receipt, refused: true };
|
|
102
106
|
};
|
|
103
107
|
const twoStep = (args: Record<string, unknown>) => ({ confirm: args.confirm === true, ...(str(args.fingerprint) ? { fingerprint: str(args.fingerprint) } : {}) });
|
|
104
108
|
const document = (result: ReturnType<VaultIndex["show"]>) => {
|
|
@@ -133,7 +137,7 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
|
|
|
133
137
|
vmem_read_file: args => readVaultFile(pick(args), loadRegistry(home).denyPaths ?? [], str(args.path)!, (args.maxBytes as number | undefined) ?? 16384, args.offset as number | undefined),
|
|
134
138
|
vmem_list_files: args => listVaultFiles(pick(args), loadRegistry(home).denyPaths ?? [], str(args.dir)!),
|
|
135
139
|
vmem_report: args => write(args, { op: "report", path: str(args.path)!, text: str(args.body)! }, args.dryRun === true ? { dryRun: true } : {}),
|
|
136
|
-
vmem_lint: args => args.write === true ? writeAnalysisReports(home,{vault:pick(args).id,kind:"lint",channel:"mcp",expectedVault:pick(args),dryRun:args.dryRun === true},env) : lintVault(analysisInput(home,pick(args).id,{expectedVault:pick(args)}).snapshot),
|
|
140
|
+
vmem_lint: args => args.write === true ? writeAnalysisReports(home,{vault:pick(args).id,kind:"lint",channel:"mcp",expectedVault:pick(args),dryRun:args.dryRun === true},env) : lintVault(analysisInput(home,pick(args).id,{expectedVault:pick(args),hints:true}).snapshot),
|
|
137
141
|
vmem_graph_build: args => writeAnalysisReports(home,{vault:pick(args).id,kind:"graph",workspace:args.workspace === true,channel:"mcp",expectedVault:pick(args),dryRun:args.dryRun === true},env),
|
|
138
142
|
vmem_graph_neighbors: args => graphNeighbors(buildGraph(analysisInput(home,pick(args).id,{expectedVault:pick(args)}).snapshot),str(args.path)!, (args.hops as 1|2|undefined) ?? 1, (args.limit as number|undefined) ?? 50, str(args.relation)),
|
|
139
143
|
vmem_status: () => ({ defaultVault: defaultVault ?? null, vaults: registryStatus(home).filter(v => ids.includes(v.id)) }),
|
|
@@ -175,6 +179,7 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
|
|
|
175
179
|
return receipt.ok ? receipt : { ...receipt, refused: true };
|
|
176
180
|
},
|
|
177
181
|
vmem_move: args => write(args, { op: "move", from: str(args.from)!, to: str(args.to)! }, twoStep(args)),
|
|
182
|
+
vmem_merge: args => write(args, { op: "merge", keep: str(args.keep)!, absorb: str(args.absorb)! }, twoStep(args)),
|
|
178
183
|
vmem_delete: args => {
|
|
179
184
|
const receipt = write(args, { op: "delete", path: str(args.path)! }, twoStep(args));
|
|
180
185
|
if (args.confirm === true) return receipt;
|
|
@@ -191,5 +196,5 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
|
|
|
191
196
|
try { return await handler(args); }
|
|
192
197
|
catch (error) { return refusal((error as { code?: unknown }).code === "V04" ? "V04" : "REFUSED", error instanceof Error ? error.message.slice(0, 500) : "operation refused"); }
|
|
193
198
|
};
|
|
194
|
-
return { tools: [...vaultTools(ids, vaults.filter(v => v.kind === "org").map(v => v.id)), ...specs.tools], handlers: guarded, vaults, defaultVault };
|
|
199
|
+
return { tools: [...vaultTools(ids, vaults.filter(v => v.kind === "org").map(v => v.id)), ...specs.tools], handlers: guarded, vaults, defaultVault, instructions: VMEM_INSTRUCTIONS };
|
|
195
200
|
}
|
package/src/mcp.ts
CHANGED
|
@@ -5,7 +5,7 @@ import type { Readable, Writable } from "node:stream";
|
|
|
5
5
|
export const FRAME_BYTES = 65_536, RESULT_BYTES = 262_144;
|
|
6
6
|
export interface McpTool { name: string; description: string; inputSchema: Record<string, unknown>; annotations: Record<string, boolean> }
|
|
7
7
|
export type McpHandler = (args: Record<string, unknown>) => unknown | Promise<unknown>;
|
|
8
|
-
export interface McpServerOptions { tools: readonly McpTool[]; handlers: Record<string, McpHandler>; input?: Readable; output?: Writable; name?: string; version?: string }
|
|
8
|
+
export interface McpServerOptions { tools: readonly McpTool[]; handlers: Record<string, McpHandler>; input?: Readable; output?: Writable; name?: string; version?: string; instructions?: string }
|
|
9
9
|
const protocols = ["2025-06-18", "2025-03-26", "2024-11-05"];
|
|
10
10
|
const plain = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
|
|
11
11
|
|
|
@@ -22,6 +22,7 @@ export function argumentError(value: unknown, raw: unknown, path = ""): string |
|
|
|
22
22
|
if (value.length < (s.minLength ?? 0)) return fail(`shorter than ${s.minLength}`);
|
|
23
23
|
if (value.length > (s.maxLength ?? FRAME_BYTES)) return fail(`longer than ${s.maxLength ?? FRAME_BYTES}`);
|
|
24
24
|
if (value.includes("\0")) return fail("NUL is not allowed");
|
|
25
|
+
if (s.pattern && !new RegExp(s.pattern).test(value)) return fail("does not match the required pattern");
|
|
25
26
|
}
|
|
26
27
|
if (typeof value === "number") {
|
|
27
28
|
if (!Number.isFinite(value)) return fail("expected finite number");
|
|
@@ -79,7 +80,8 @@ export async function serveMcp(options: McpServerOptions): Promise<void> {
|
|
|
79
80
|
if (phase !== "new" || !plain(msg.params) || typeof msg.params.protocolVersion !== "string" || !plain(msg.params.capabilities) || !plain(msg.params.clientInfo)) { await error(id, -32602, "Invalid initialization"); return; }
|
|
80
81
|
phase = "initializing";
|
|
81
82
|
await send({ jsonrpc: "2.0", id, result: { protocolVersion: protocols.includes(msg.params.protocolVersion) ? msg.params.protocolVersion : protocols[0],
|
|
82
|
-
capabilities: { tools: { listChanged: false } }, serverInfo: { name: options.name ?? "vmem", version: options.version ?? "unreleased" }
|
|
83
|
+
capabilities: { tools: { listChanged: false } }, serverInfo: { name: options.name ?? "vmem", version: options.version ?? "unreleased" },
|
|
84
|
+
...(options.instructions !== undefined ? { instructions: options.instructions } : {}) } });
|
|
83
85
|
return;
|
|
84
86
|
}
|
|
85
87
|
if (phase !== "ready") { await error(id, -32002, "Initialize the session first"); return; }
|
package/src/org-promote.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { canonRowsForVault, matchCanonRows, type CanonRowIndex, type CanonRowMatch } from "./canon-tables.ts";
|
|
1
2
|
import { domainProblem } from "./config.ts";
|
|
2
3
|
import { localDate } from "./local-date.ts";
|
|
3
4
|
import { createHash } from "node:crypto";
|
|
@@ -9,7 +10,7 @@ import { normalizeTarget, proseLines } from "./links.ts";
|
|
|
9
10
|
import { loadRegistry } from "./registry.ts";
|
|
10
11
|
import { VaultIndex } from "./vault-index.ts";
|
|
11
12
|
import { applyWrite } from "./writer.ts";
|
|
12
|
-
import { notePath, replaceTopicsSection } from "./write-operations.ts";
|
|
13
|
+
import { planOperation, stampContentChanges, notePath, replaceTopicsSection } from "./write-operations.ts";
|
|
13
14
|
import { screenContent } from "./write-validation.ts";
|
|
14
15
|
import { appendLog, logBinding } from "./vault-log.ts";
|
|
15
16
|
import type { WriteIssue, WriteReceipt } from "./write-types.ts";
|
|
@@ -40,6 +41,10 @@ export interface OrgPromoteResult {
|
|
|
40
41
|
target: string | null;
|
|
41
42
|
text?: string;
|
|
42
43
|
droppedLinks?: string[];
|
|
44
|
+
/** Target-vault advisory data, excluded from the promotion fingerprint. */
|
|
45
|
+
canonRowMatches?: CanonRowMatch[];
|
|
46
|
+
canonTableWarnings?: string[];
|
|
47
|
+
choices?: string[];
|
|
43
48
|
screen: { passed: boolean; issues: WriteIssue[] };
|
|
44
49
|
fingerprint?: string;
|
|
45
50
|
issues: WriteIssue[];
|
|
@@ -119,13 +124,13 @@ export function dropUnresolvedLinks(body: string, resolves: (target: string) =>
|
|
|
119
124
|
}
|
|
120
125
|
|
|
121
126
|
/** Target-vault facts read once from its index: link resolution (path stems only, as Obsidian resolves), MOCs and existing paths. */
|
|
122
|
-
function targetFacts(home: string, spec: VaultSpec, all: VaultSpec[], links: string[], targetPath: string): { resolved: Set<string>; mocs: Set<string>; exists: boolean } {
|
|
127
|
+
function targetFacts(home: string, spec: VaultSpec, all: VaultSpec[], links: string[], targetPath: string, denyPaths: string[] = []): { resolved: Set<string>; mocs: Set<string>; exists: boolean; canon?: CanonRowIndex } {
|
|
123
128
|
const index = new VaultIndex(home, spec, all.map(v => v.path));
|
|
124
129
|
try {
|
|
125
130
|
index.scan();
|
|
126
131
|
const targets = index.linkTargets(), resolved = new Set([...new Set(links)].map(linkKey).filter(key => targets.has(key)));
|
|
127
132
|
// Path existence is checked without alias lookup, so another note's alias cannot hide the target.
|
|
128
|
-
return { resolved, mocs: new Set(index.mocs(500).map(moc => linkKey(moc.path))), exists: targets.has(linkKey(targetPath)) };
|
|
133
|
+
return { resolved, mocs: new Set(index.mocs(500).map(moc => linkKey(moc.path))), exists: targets.has(linkKey(targetPath)), ...(spec.canonTables !== undefined ? { canon: canonRowsForVault(index, spec, denyPaths) } : {}) };
|
|
129
134
|
} finally { index.close(); }
|
|
130
135
|
}
|
|
131
136
|
function readSource(spec: VaultSpec, path: string): string {
|
|
@@ -162,6 +167,7 @@ export function lintPromoted(home: string, target: VaultSpec, path: string, text
|
|
|
162
167
|
* Preview and refusal write nothing; confirm needs the fingerprint of the current preview.
|
|
163
168
|
*/
|
|
164
169
|
export function promoteToOrg(home: string, request: OrgPromoteRequest, options: { env?: NodeJS.ProcessEnv; now?: Date } = {}): OrgPromoteResult {
|
|
170
|
+
const now = options.now ?? new Date();
|
|
165
171
|
const result: OrgPromoteResult = { ok: false, applied: false, source: null, target: null, screen: { passed: false, issues: [] }, issues: [] };
|
|
166
172
|
const fail = (found: WriteIssue) => ({ ...result, issues: [found] });
|
|
167
173
|
const config = loadRegistry(home), all = config.vaults;
|
|
@@ -194,7 +200,8 @@ export function promoteToOrg(home: string, request: OrgPromoteRequest, options:
|
|
|
194
200
|
const topics = (request.topics ?? strings(parsed.data.topics)).map(value => value.startsWith("[[") ? value : `[[${value}]]`);
|
|
195
201
|
const bodyLinks = [...parsed.body.matchAll(/\[\[([^\]\n|#]+)/g)].map(match => match[1]!.trim());
|
|
196
202
|
const fieldLinks = ["project", "superseded_by", "supersedes", "source_ref"].flatMap(key => strings(parsed.data[key]).filter(value => value.includes("[[")).map(linkKey));
|
|
197
|
-
const targetNotes = targetFacts(home, target, all, [...bodyLinks, ...fieldLinks], targetPath);
|
|
203
|
+
const targetNotes = targetFacts(home, target, all, [...bodyLinks, ...fieldLinks], targetPath, config.denyPaths ?? []);
|
|
204
|
+
if (targetNotes.canon?.warnings.length) result.canonTableWarnings = [...targetNotes.canon.warnings];
|
|
198
205
|
// The org note is never overwritten; a repeat promotion (--again) needs the earlier org copy moved or deleted first.
|
|
199
206
|
if (targetNotes.exists) {
|
|
200
207
|
// Recovery: an earlier confirm created this org note but the source provenance write failed.
|
|
@@ -202,13 +209,13 @@ export function promoteToOrg(home: string, request: OrgPromoteRequest, options:
|
|
|
202
209
|
try { existing = parseFrontmatter(readSource(target, targetPath)).data; } catch { /* unreadable: treated as foreign */ }
|
|
203
210
|
if (existing.promoted_from !== result.source || prior.includes(promotedTo)) return fail(issue("V08", `${target.id} already has ${targetPath}; move or delete it in the org vault first`, targetPath));
|
|
204
211
|
const set = { promoted_to: prior.length ? [...prior, promotedTo] : promotedTo };
|
|
205
|
-
const plan = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set }, channel: request.channel ?? "cli", dryRun: true }, { env: options.env, binding: bindings.source });
|
|
212
|
+
const plan = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set }, channel: request.channel ?? "cli", dryRun: true }, { env: options.env, binding: bindings.source, now });
|
|
206
213
|
const fingerprint = sha({ recover: plan.fingerprint, promotedTo });
|
|
207
214
|
const recovery: OrgPromoteResult = { ...result, target: `${target.id}:${targetPath}`, screen: { passed: true, issues: [] }, fingerprint, recovery: "provenance-only" };
|
|
208
215
|
if (!plan.ok) return { ...recovery, issues: plan.issues };
|
|
209
216
|
if (request.confirm !== true) return { ...recovery, ok: true, preview: true };
|
|
210
217
|
if (request.fingerprint !== fingerprint) return { ...recovery, issues: [issue("V09", "stale or missing preview fingerprint")] };
|
|
211
|
-
const provenance = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set }, channel: request.channel ?? "cli", log: false }, { env: options.env, binding: bindings.source });
|
|
218
|
+
const provenance = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set }, channel: request.channel ?? "cli", log: false }, { env: options.env, binding: bindings.source, now });
|
|
212
219
|
return { ...recovery, ok: provenance.ok, applied: provenance.applied, provenance, issues: provenance.ok ? [] : provenance.issues };
|
|
213
220
|
}
|
|
214
221
|
const missingTopics = topics.filter(topic => !targetNotes.mocs.has(linkKey(topic)));
|
|
@@ -216,24 +223,34 @@ export function promoteToOrg(home: string, request: OrgPromoteRequest, options:
|
|
|
216
223
|
const transformed = dropUnresolvedLinks(parsed.body, value => targetNotes.resolved.has(linkKey(value)));
|
|
217
224
|
// Body Topics section follows the target topics.
|
|
218
225
|
const body = replaceTopicsSection(transformed.body, topics);
|
|
219
|
-
const day = localDate(
|
|
226
|
+
const day = localDate(now);
|
|
220
227
|
const frontmatter: Record<string, unknown> = { topics, promoted_from: result.source, promoted_at: day, promoted_to: undefined };
|
|
221
228
|
// Wiki-valued fields that point outside the target vault are dropped as well.
|
|
222
229
|
for (const key of ["project", "superseded_by", "supersedes", "source_ref"]) {
|
|
223
230
|
const values = strings(parsed.data[key]);
|
|
224
231
|
if (values.some(value => value.includes("[[") && !targetNotes.resolved.has(linkKey(value)))) { frontmatter[key] = undefined; transformed.dropped.push(`${key}:${values.join(",")}`); }
|
|
225
232
|
}
|
|
226
|
-
|
|
233
|
+
let text = emitFrontmatter(parseFrontmatter(parsed.source.slice(0, parsed.source.length - parsed.body.length) + body), frontmatter);
|
|
227
234
|
result.target = `${target.id}:${targetPath}`; result.text = text; result.droppedLinks = transformed.dropped;
|
|
228
235
|
const screen = [...screenForOrg(text, parsed.data, target, config), ...screenDroppedLinks(home, source, all, transformed.dropped.filter(link => !link.includes(":")))];
|
|
229
236
|
const refusing = screen.filter(found => found.severity === "error");
|
|
230
237
|
result.screen = { passed: refusing.length === 0, issues: screen };
|
|
231
238
|
if (refusing.length) return { ...result, issues: screen };
|
|
232
|
-
const planned = applyWrite(home, { vault: target.id, operation: { op: "create", path: targetPath, frontmatter: {}, body: text }, channel: request.channel ?? "cli", dryRun: true }, { env: options.env, piiSurface: "promotion", binding: bindings.target });
|
|
239
|
+
const planned = applyWrite(home, { vault: target.id, operation: { op: "create", path: targetPath, frontmatter: {}, body: text }, channel: request.channel ?? "cli", dryRun: true }, { env: options.env, piiSurface: "promotion", binding: bindings.target, now });
|
|
240
|
+
if (planned.ok) {
|
|
241
|
+
const operation = { op: "create" as const, path: targetPath, frontmatter: {}, body: text };
|
|
242
|
+
text = stampContentChanges(operation, planOperation(operation, new Map()), day)[0]!.after!;
|
|
243
|
+
result.text = text;
|
|
244
|
+
}
|
|
233
245
|
const provenanceSet = { promoted_to: prior.length ? [...prior.filter(p => p !== promotedTo), promotedTo] : promotedTo };
|
|
234
246
|
const provenanceText = emitFrontmatter(parsed, provenanceSet);
|
|
235
|
-
const provenancePlan = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set: provenanceSet }, channel: request.channel ?? "cli", dryRun: true }, { env: options.env, binding: bindings.source });
|
|
247
|
+
const provenancePlan = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set: provenanceSet }, channel: request.channel ?? "cli", dryRun: true }, { env: options.env, binding: bindings.source, now });
|
|
236
248
|
result.fingerprint = sha({ target: planned.fingerprint, source: provenancePlan.fingerprint, text, provenanceText });
|
|
249
|
+
if (targetNotes.canon !== undefined) {
|
|
250
|
+
const matches = planned.ok ? matchCanonRows(targetNotes.canon, `${String(parsed.data.title ?? "")}\n${parseFrontmatter(text).body}`) : [];
|
|
251
|
+
result.canonRowMatches = matches;
|
|
252
|
+
if (matches.length) result.choices = [...new Set(matches.map(row => `link-existing ${row.path}`))];
|
|
253
|
+
}
|
|
237
254
|
// Org lint runs on the preview too (the note overlaid on the org snapshot), so a note that would fail lint is never written.
|
|
238
255
|
const previewLint = lintPromoted(home, target, targetPath, text);
|
|
239
256
|
result.lint = previewLint;
|
|
@@ -242,10 +259,10 @@ export function promoteToOrg(home: string, request: OrgPromoteRequest, options:
|
|
|
242
259
|
if (request.confirm !== true) return { ...result, ok: true, preview: true, issues: [...planned.issues, ...provenancePlan.issues] };
|
|
243
260
|
if (request.fingerprint !== result.fingerprint) return { ...result, issues: [issue("V09", "stale or missing preview fingerprint")] };
|
|
244
261
|
const event = { type: "SYNC", project: request.logProject ?? "-", source: `${source.id}:${path}`, dest: `${target.id}:${targetPath}`, note: `promoted: ${typeof parsed.data.type === "string" ? parsed.data.type : "note"}` };
|
|
245
|
-
const note = applyWrite(home, { vault: target.id, operation: { op: "create", path: targetPath, frontmatter: {}, body: text }, channel: request.channel ?? "cli", log: false }, { env: options.env, piiSurface: "promotion", binding: bindings.target });
|
|
262
|
+
const note = applyWrite(home, { vault: target.id, operation: { op: "create", path: targetPath, frontmatter: {}, body: text }, channel: request.channel ?? "cli", log: false }, { env: options.env, piiSurface: "promotion", binding: bindings.target, now });
|
|
246
263
|
// A create that committed and then failed a later step (cleanup) is still a written org note.
|
|
247
264
|
if (!note.ok || !note.applied) return { ...result, applied: note.applied === true, note, issues: note.issues };
|
|
248
|
-
const provenance = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set: provenanceSet }, channel: request.channel ?? "cli", log: false }, { env: options.env, binding: bindings.source });
|
|
265
|
+
const provenance = applyWrite(home, { vault: source.id, operation: { op: "frontmatter", path, set: provenanceSet }, channel: request.channel ?? "cli", log: false }, { env: options.env, binding: bindings.source, now });
|
|
249
266
|
const logs = { source: null as LogReceipt | null, target: null as LogReceipt | null };
|
|
250
267
|
for (const [key, vault] of [["target", target], ["source", source]] as const) {
|
|
251
268
|
try { logs[key] = appendLog(home, { vault: vault.id, event, channel: request.channel ?? "cli" }, { env: options.env, binding: bindings[key] }); }
|
package/src/promote.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { canonRowsForVault, matchCanonRows, type CanonRowIndex, type CanonRowMatch } from "./canon-tables.ts";
|
|
1
2
|
import { localDate } from "./local-date.ts";
|
|
2
3
|
import { createHash } from "node:crypto";
|
|
3
4
|
import type { VaultSpec } from "./config.ts";
|
|
@@ -5,7 +6,7 @@ import { emitFrontmatter, parseFrontmatter } from "./frontmatter.ts";
|
|
|
5
6
|
import { loadRegistry } from "./registry.ts";
|
|
6
7
|
import { VaultIndex } from "./vault-index.ts";
|
|
7
8
|
import { applyWrite } from "./writer.ts";
|
|
8
|
-
import { notePath } from "./write-operations.ts";
|
|
9
|
+
import { notePath, planOperation, stampContentChanges } from "./write-operations.ts";
|
|
9
10
|
import type { WriteIssue, WriteReceipt } from "./write-types.ts";
|
|
10
11
|
import type { AmemCandidate, AmemSeam, AmemOptions } from "./amem/seam.ts";
|
|
11
12
|
|
|
@@ -31,6 +32,9 @@ export interface PromoteResult {
|
|
|
31
32
|
fingerprint?: string;
|
|
32
33
|
issues: WriteIssue[];
|
|
33
34
|
possibleDuplicates?: string[];
|
|
35
|
+
/** Advisory canonical table rows; never part of a fingerprint or a write refusal. */
|
|
36
|
+
canonRowMatches?: CanonRowMatch[];
|
|
37
|
+
canonTableWarnings?: string[];
|
|
34
38
|
/** Choices offered when the note may already exist in the vault. */
|
|
35
39
|
choices?: string[];
|
|
36
40
|
note?: WriteReceipt;
|
|
@@ -70,10 +74,10 @@ export function draftNote(entry: AmemCandidate, meta: PromoteMetadata, now = new
|
|
|
70
74
|
const body = meta.body ?? `# ${title}\n\n${entry.text.trim()}\n\n## Relevant Notes\n\n${hints}\n## Topics\n\n${topics.map(topic => `- ${topic}`).join("\n")}\n`;
|
|
71
75
|
return { stem, frontmatter, text: emitFrontmatter(parseFrontmatter(body), frontmatter) };
|
|
72
76
|
}
|
|
73
|
-
function vaultSpec(home: string, id: string): { spec: VaultSpec; all: VaultSpec[] } {
|
|
74
|
-
const
|
|
77
|
+
function vaultSpec(home: string, id: string): { spec: VaultSpec; all: VaultSpec[]; denyPaths: string[] } {
|
|
78
|
+
const config = loadRegistry(home), all = config.vaults, spec = all.find(v => v.id === id);
|
|
75
79
|
if (!spec) throw new Error("promote: unknown vault id");
|
|
76
|
-
return { spec, all };
|
|
80
|
+
return { spec, all, denyPaths: config.denyPaths ?? [] };
|
|
77
81
|
}
|
|
78
82
|
const fold = (value: string) => value.normalize("NFKC").toLowerCase().replace(/[-_\s]+/g, " ").trim();
|
|
79
83
|
/** Existing notes with the same stem or title, plus close FTS title matches: the link-existing choices. */
|
|
@@ -87,14 +91,14 @@ function similar(home: string, spec: VaultSpec, all: VaultSpec[], title: string,
|
|
|
87
91
|
return [...exact, ...hits].map(hit => `notes/${hit.path}`).filter((path, i, list) => list.indexOf(path) === i).slice(0, 5);
|
|
88
92
|
} catch { return []; } finally { index.close(); }
|
|
89
93
|
}
|
|
90
|
-
function lookup(home: string, spec: VaultSpec, all: VaultSpec[], id: string, linkTo?: string): { promoted: string[]; target?: string } {
|
|
94
|
+
function lookup(home: string, spec: VaultSpec, all: VaultSpec[], id: string, linkTo?: string, denyPaths: string[] = []): { promoted: string[]; target?: string; canon?: CanonRowIndex } {
|
|
91
95
|
const index = new VaultIndex(home, spec, all.map(v => v.path));
|
|
92
96
|
try {
|
|
93
97
|
index.scan();
|
|
94
98
|
const promoted = index.promotedFrom(`mem:${id}`).map(path => `notes/${path}`);
|
|
95
99
|
let target: string | undefined;
|
|
96
100
|
if (linkTo !== undefined) target = `notes/${index.show(linkTo, 1).path}`;
|
|
97
|
-
return { promoted, ...(target ? { target } : {}) };
|
|
101
|
+
return { promoted, ...(target ? { target } : {}), ...(spec.canonTables !== undefined ? { canon: canonRowsForVault(index, spec, denyPaths) } : {}) };
|
|
98
102
|
} finally { index.close(); }
|
|
99
103
|
}
|
|
100
104
|
|
|
@@ -106,16 +110,18 @@ function lookup(home: string, spec: VaultSpec, all: VaultSpec[], id: string, lin
|
|
|
106
110
|
* the note through `promoted_from` and offers link-only instead of a second note.
|
|
107
111
|
*/
|
|
108
112
|
export async function promoteFromAmem(home: string, request: PromoteRequest, options: { env?: NodeJS.ProcessEnv; project?: string; cwd?: string; seam?: SeamFactory; now?: Date } = {}): Promise<PromoteResult> {
|
|
113
|
+
const now = options.now ?? new Date();
|
|
109
114
|
const base: PromoteResult = { ok: false, action: "create", applied: false, id: request.id, path: null, issues: [] };
|
|
110
115
|
if (!ID.test(request.id)) return { ...base, issues: [issue("AMEM", "expected a 32-hex agent-mem entry id")] };
|
|
111
|
-
const { spec, all } = vaultSpec(home, request.vault);
|
|
116
|
+
const { spec, all, denyPaths } = vaultSpec(home, request.vault);
|
|
112
117
|
if (spec.write === "none" || (request.channel === "mcp" && spec.write !== "mcp")) return { ...base, issues: [issue("POLICY", "vault write policy refuses this channel")] };
|
|
113
118
|
const seam = await (options.seam ?? defaultSeam)({ env: options.env, ...(options.project ? { project: options.project } : {}), ...(options.cwd ? { cwd: options.cwd } : {}), piiPatterns: loadRegistry(home).piiPatterns });
|
|
114
119
|
try {
|
|
115
120
|
const entry = await seam.entry(request.id);
|
|
116
121
|
if (!entry) return { ...base, issues: [issue("AMEM", "entry is not an available curated entry of this project")] };
|
|
117
122
|
const linked = seam.linkedPath(request.id) ?? null;
|
|
118
|
-
const { promoted, target } = lookup(home, spec, all, request.id, request.linkTo);
|
|
123
|
+
const { promoted, target, canon } = lookup(home, spec, all, request.id, request.linkTo, denyPaths);
|
|
124
|
+
if (canon?.warnings.length) base.canonTableWarnings = [...canon.warnings];
|
|
119
125
|
// Link-only: an earlier promotion already created the note, or the caller chose an existing note.
|
|
120
126
|
const existing = target ?? promoted[0];
|
|
121
127
|
if (existing) {
|
|
@@ -128,21 +134,27 @@ export async function promoteFromAmem(home: string, request: PromoteRequest, opt
|
|
|
128
134
|
await seam.recordLink(request.id, existing);
|
|
129
135
|
return { ...result, applied: true, linked: existing };
|
|
130
136
|
}
|
|
131
|
-
const draft = draftNote(entry, request,
|
|
137
|
+
const draft = draftNote(entry, request, now);
|
|
132
138
|
if (!draft.stem) return { ...base, issues: [issue("V04", "cannot derive an ASCII stem from the title; pass --stem")] };
|
|
133
139
|
let path: string;
|
|
134
140
|
try { path = notePath(draft.stem); } catch { return { ...base, issues: [issue("V04", "expected a flat lowercase ASCII stem")] }; }
|
|
135
141
|
const operation = { op: "create" as const, path: draft.stem, frontmatter: {}, body: draft.text };
|
|
136
|
-
const planned = applyWrite(home, { vault: spec.id, operation, channel: request.channel ?? "cli", dryRun: true }, { env: options.env });
|
|
142
|
+
const planned = applyWrite(home, { vault: spec.id, operation, channel: request.channel ?? "cli", dryRun: true }, { env: options.env, now });
|
|
137
143
|
const v08 = planned.issues.some(i => i.code === "V08") || (planned.possibleDuplicates?.length ?? 0) > 0;
|
|
138
144
|
const possibleDuplicates = v08 ? [...new Set([...(planned.possibleDuplicates ?? []), ...similar(home, spec, all, String(draft.frontmatter.title), draft.stem)])].filter(p => p !== path) : [];
|
|
139
145
|
const fingerprint = sha({ action: "create", id: request.id, write: planned.fingerprint, text: draft.text, linked, vault: spec.id });
|
|
140
|
-
const
|
|
146
|
+
const text = planned.ok ? stampContentChanges(operation, planOperation(operation, new Map()), localDate(now))[0]!.after! : draft.text;
|
|
147
|
+
const result: PromoteResult = { ...base, ok: planned.ok, path, text, fingerprint, issues: planned.issues, linked,
|
|
141
148
|
...(possibleDuplicates.length ? { possibleDuplicates, choices: ["create", ...possibleDuplicates.map(p => `link-existing ${p}`)] } : {}) };
|
|
149
|
+
if (canon !== undefined) {
|
|
150
|
+
const matches = planned.ok ? matchCanonRows(canon, `${String(draft.frontmatter.title ?? "")}\n${parseFrontmatter(text).body}`) : [];
|
|
151
|
+
result.canonRowMatches = matches;
|
|
152
|
+
if (matches.length) result.choices = [...new Set([...(result.choices ?? ["create"]), ...matches.map(row => `link-existing ${row.path}`)])];
|
|
153
|
+
}
|
|
142
154
|
if (request.confirm !== true || !planned.ok) return { ...result, preview: request.confirm !== true };
|
|
143
155
|
if (request.fingerprint !== fingerprint) return { ...result, ok: false, issues: [issue("V09", "stale or missing preview fingerprint")] };
|
|
144
156
|
const note = applyWrite(home, { vault: spec.id, operation, channel: request.channel ?? "cli",
|
|
145
|
-
log: { type: "LEARN", project: logProjectFor(seam.project, request.logProject), source: `mem:${request.id}`, dest: path, note: `promoted: ${entry.kind}` } }, { env: options.env });
|
|
157
|
+
log: { type: "LEARN", project: logProjectFor(seam.project, request.logProject), source: `mem:${request.id}`, dest: path, note: `promoted: ${entry.kind}` } }, { env: options.env, now });
|
|
146
158
|
if (!note.ok || !note.applied) return { ...result, ok: false, note, issues: note.issues };
|
|
147
159
|
try {
|
|
148
160
|
await seam.recordLink(request.id, path);
|
package/src/read-commands.ts
CHANGED
|
@@ -3,7 +3,6 @@ import { VaultIndex, MAX_NOTE_BYTES } from "./vault-index.ts";
|
|
|
3
3
|
import { PLAIN, type TextOptions } from "./text-output.ts";
|
|
4
4
|
import { linksText, rebuildText, searchText, showText } from "./read-output.ts";
|
|
5
5
|
import type { NoteReadResult, SearchResult } from "./vault-index.ts";
|
|
6
|
-
import type { ResolvedLink } from "./links.ts";
|
|
7
6
|
const READ_COMMANDS = new Set(["rebuild", "search", "show", "links"]);
|
|
8
7
|
export function isReadCommand(command: string): boolean { return READ_COMMANDS.has(command); }
|
|
9
8
|
export function runReadCommand(command: string, args: string[], home: string, text: TextOptions = PLAIN): { text: string; code: number } {
|
|
@@ -48,6 +47,6 @@ export function runReadCommand(command: string, args: string[], home: string, te
|
|
|
48
47
|
const out = command === "rebuild" ? rebuildText(result as Parameters<typeof rebuildText>[0], text)
|
|
49
48
|
: command === "search" ? searchText(result as SearchResult[], text, { vault: vaultId, query: target, limit: limit ?? 50, type: options["--type"] as string | undefined, domain: options["--domain"] as string | undefined })
|
|
50
49
|
: command === "show" ? showText(result as NoteReadResult, text, { vault: vaultId, target, maxBytes })
|
|
51
|
-
: linksText(result as
|
|
50
|
+
: linksText(result as Parameters<typeof linksText>[0], text, { vault: vaultId, target, limit: limit ?? 50 });
|
|
52
51
|
return { text: out, code: 0 };
|
|
53
52
|
}
|
package/src/read-output.ts
CHANGED
|
@@ -3,12 +3,12 @@
|
|
|
3
3
|
* command prints with `--json`, and never shows more than that result carries.
|
|
4
4
|
*/
|
|
5
5
|
import type { SearchResult, NoteReadResult } from "./vault-index.ts";
|
|
6
|
-
import type { ResolvedLink } from "./links.ts";
|
|
6
|
+
import type { ResolvedLink, SuggestedLink } from "./links.ts";
|
|
7
7
|
import type { LogReadResult, LogReceipt } from "./log-types.ts";
|
|
8
8
|
import type { LintCode, LintReport } from "./analysis-types.ts";
|
|
9
9
|
import type { GraphNeighborhood } 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 TextOptions, stripTerminal } from "./text-output.ts";
|
|
11
|
+
import { blocks, clean, fields, heading, issueTable, nextCommand, paint, paragraph, plural, shellWord, table, tone, type CellInput, type TextOptions, stripTerminal } from "./text-output.ts";
|
|
12
12
|
|
|
13
13
|
const command = (...words: string[]) => ["vmem", ...words].map(shellWord).join(" ");
|
|
14
14
|
|
|
@@ -32,12 +32,14 @@ export function showText(r: NoteReadResult, o: TextOptions, c: { vault: string;
|
|
|
32
32
|
return blocks(head, stripTerminal(r.content).replace(/\n+$/, ""), tail.join("\n"), headings);
|
|
33
33
|
}
|
|
34
34
|
|
|
35
|
-
|
|
35
|
+
/** A listed link; a dead one may carry the one hinted target, as `vmem links --json` and `vmem_links` return it. */
|
|
36
|
+
export function linksText(links: SuggestedLink[], o: TextOptions, c: { vault: string; target: string; limit: number }): string {
|
|
36
37
|
const from = links[0]?.source ?? c.target;
|
|
37
38
|
const count = `${plural(links.length, "link")} from ${clean(from)}`;
|
|
38
39
|
if (!links.length) return count;
|
|
39
40
|
const target = (l: ResolvedLink) => l.target + (l.heading !== null ? `#${l.heading}` : "") + (l.block !== null ? `#^${l.block}` : "");
|
|
40
|
-
const
|
|
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");
|
|
42
|
+
const rows = links.map(l => [target(l), resolution(l), l.line]);
|
|
41
43
|
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;
|
|
42
44
|
return blocks(heading("OUT", o) + "\n" + table(["TARGET", "RESOLVED", "LINE"], rows, o), [count, more].filter(Boolean).join("\n"));
|
|
43
45
|
}
|
|
@@ -60,7 +62,7 @@ export function logAppendText(r: LogReceipt, o: TextOptions, c: { vault: string;
|
|
|
60
62
|
return blocks(line, issueTable(r.issues, o));
|
|
61
63
|
}
|
|
62
64
|
|
|
63
|
-
const LEVELS: Record<LintCode, "error" | "warn"> = { L01: "error", L02: "error", L03: "warn", L09: "warn", L10: "warn", L11: "warn", L12: "warn", L13: "error", L14: "warn" };
|
|
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" };
|
|
64
66
|
const verdict = (r: { errors: number; warnings: number; summary: string }, o: TextOptions) => paint(clean(r.summary), r.errors ? "fail" : r.warnings ? "warn" : "ok", o);
|
|
65
67
|
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 {
|
|
66
68
|
const rows = (Object.keys(d.report.findings) as LintCode[]).flatMap(code => {
|
package/src/registry.ts
CHANGED
|
@@ -45,6 +45,7 @@ function mutate<T>(home: string, update: (config: VmemConfig) => T): T {
|
|
|
45
45
|
const config = loadRegistry(home), result = update(config);
|
|
46
46
|
if (config.specs !== undefined) config.version = Math.max(config.version ?? 1, 2);
|
|
47
47
|
if (config.vaults.some(vault => vault.domains !== undefined)) config.version = Math.max(config.version ?? 1, 3);
|
|
48
|
+
if (config.vaults.some(vault => vault.canonTables !== undefined)) config.version = Math.max(config.version ?? 1, 4);
|
|
48
49
|
parseConfig(config);
|
|
49
50
|
const text = JSON.stringify(config, null, 2) + "\n";
|
|
50
51
|
if (Buffer.byteLength(text) > MAX_CONFIG_BYTES) throw new Error(`${join(home, CONFIG_FILE)}: serialized config exceeds 64 KiB`);
|
package/src/skills-mine.ts
CHANGED
|
@@ -47,7 +47,7 @@ export interface MineOptions {
|
|
|
47
47
|
export interface MineResult {
|
|
48
48
|
vault: string; days: number; since: string; projects: string[];
|
|
49
49
|
records: Record<RecordSource, number>;
|
|
50
|
-
dropped: { secret: number; policy: number; oversized: number; duplicate: number; unreadable: number; truncatedCapture: number };
|
|
50
|
+
dropped: { secret: number; policy: number; oversized: number; duplicate: number; unreadable: number; truncatedCapture: number; malformedRecord: number };
|
|
51
51
|
graph: { nodes: number; edges: number; communities: number; partitioner: "leiden" };
|
|
52
52
|
godNodes: { id: string; degree: number }[];
|
|
53
53
|
candidates: Candidate[];
|
|
@@ -322,7 +322,7 @@ export interface MineInputs {
|
|
|
322
322
|
}
|
|
323
323
|
/** The pure part: screen, mask, match, cluster, score and render. */
|
|
324
324
|
export function mineRecords(input: MineInputs): MineResult {
|
|
325
|
-
const dropped: MineResult["dropped"] = { secret: 0, policy: 0, oversized: 0, duplicate: 0, unreadable: 0, truncatedCapture: 0, ...input.dropped };
|
|
325
|
+
const dropped: MineResult["dropped"] = { secret: 0, policy: 0, oversized: 0, duplicate: 0, unreadable: 0, truncatedCapture: 0, malformedRecord: 0, ...input.dropped };
|
|
326
326
|
const ordered = [...input.records].sort((a, b) => compare(a.at, b.at) || compare(a.source, b.source) || compare(a.project, b.project) || compare(a.text, b.text));
|
|
327
327
|
const kept: MineRecord[] = [], texts = new Set<string>();
|
|
328
328
|
let total = 0;
|
|
@@ -397,7 +397,8 @@ export function renderReport(result: Omit<MineResult, "report">, today: string,
|
|
|
397
397
|
`# Skill Candidates (${today}, memory-based)`, "",
|
|
398
398
|
`- corpus: ${total} records / ${result.days} days (curated ${result.records.curated}, capture ${result.records.capture}, vault ${result.records.vault})`,
|
|
399
399
|
`- projects: ${result.projects.length}`,
|
|
400
|
-
`- dropped: secret ${result.dropped.secret}, policy ${result.dropped.policy}, oversized ${result.dropped.oversized}, duplicate ${result.dropped.duplicate}, unreadable ${result.dropped.unreadable}`,
|
|
400
|
+
`- dropped: secret ${result.dropped.secret}, policy ${result.dropped.policy}, oversized ${result.dropped.oversized}, duplicate ${result.dropped.duplicate}, unreadable ${result.dropped.unreadable}, malformed Record ${result.dropped.malformedRecord}`,
|
|
401
|
+
`- truncated capture machine shards: ${result.dropped.truncatedCapture}; rows of any event beyond maxReadRows were not read`,
|
|
401
402
|
`- graph: ${result.graph.nodes} nodes, ${result.graph.edges} edges, ${result.graph.communities} communities (deterministic Leiden)`, "",
|
|
402
403
|
];
|
|
403
404
|
if (result.godNodes.length) {
|
|
@@ -449,7 +450,7 @@ export async function mineSkills(home: string, options: MineOptions): Promise<Mi
|
|
|
449
450
|
const amem = await readAmemForMining({ env: options.env, since, ...(options.project ? { project: options.project } : {}), piiPatterns: local.config.piiPatterns ?? [] });
|
|
450
451
|
return mineRecords({
|
|
451
452
|
vault: options.vault, days, since, projects: amem.projects, records: [...amem.records, ...local.records], vocab, registry, skills, minSize, minNovelty, piiPatterns: local.config.piiPatterns ?? [],
|
|
452
|
-
today: localDate(now), dropped: { policy: amem.screened, unreadable: amem.unreadable + local.unreadable, truncatedCapture: amem.truncatedCapture },
|
|
453
|
+
today: localDate(now), dropped: { policy: amem.screened, unreadable: amem.unreadable + local.unreadable, truncatedCapture: amem.truncatedCapture, malformedRecord: amem.malformedRecord },
|
|
453
454
|
});
|
|
454
455
|
}
|
|
455
456
|
|
|
@@ -1,15 +1,24 @@
|
|
|
1
1
|
import { SPEC_EDGE_KINDS } from "./spec-graph.ts";
|
|
2
|
+
import { SPEC_UPDATE_LIST_FIELDS as listFields, SPEC_UPDATE_OPTIONAL_FIELDS as optionalFields } from "./spec-write.ts";
|
|
2
3
|
|
|
3
4
|
const string = (maxLength: number, minLength = 1) => ({ type: "string", minLength, maxLength });
|
|
4
5
|
const integer = (maximum: number, minimum = 0) => ({ type: "integer", minimum, maximum });
|
|
5
6
|
const common = { source: string(64), worktree: string(4096) };
|
|
6
7
|
const schema = (properties: Record<string, unknown>, required: string[] = []) => ({ type: "object", properties: { ...common, ...properties }, required, additionalProperties: false, maxProperties: 20 });
|
|
7
|
-
|
|
8
|
+
const listChanges = { type: "object", properties: Object.fromEntries(listFields.map(field => [field, { type: "array", items: string(4096), maxItems: 256 }])), additionalProperties: false, maxProperties: listFields.length };
|
|
9
|
+
const scalarChanges = { type: "object", properties: {
|
|
10
|
+
title: string(4096), type: { type: "string", enum: ["goal", "architecture", "module", "submodule"] },
|
|
11
|
+
status: { type: "string", enum: ["draft", "active", "deprecated"] }, parent: string(1024), "superseded-by": string(1024), "verified-against": { ...string(64, 40), pattern: "^(?:[a-fA-F0-9]{40}|[a-fA-F0-9]{64})$" },
|
|
12
|
+
}, additionalProperties: false, maxProperties: 6 };
|
|
13
|
+
/** Implemented commands only; CLI flags and MCP definitions share these schemas. */
|
|
8
14
|
export const SPEC_COMMANDS = [
|
|
9
15
|
{ command: "get", name: "vmem_spec_get", usage: "spec get <id> [--source ID] [--worktree PATH] [--body] [--section TEXT] [--offset N] [--max-bytes 1..65536] [--json]", description: "Read spec metadata, resolved links, backlinks, children and freshness; body reads are optional and paged.", inputSchema: schema({ id: string(1024), body: { type: "boolean" }, section: string(1024), offset: integer(2097152), maxBytes: integer(65536, 1) }, ["id"]) },
|
|
10
16
|
{ command: "graph", name: "vmem_spec_graph", usage: "spec graph <id> [--source ID] [--worktree PATH] [--direction subtree|ancestors|neighbors] [--edge KIND] [--depth 0..3] [--limit 1..500] [--json]", description: "Read a bounded spec graph slice without raw source content.", inputSchema: schema({ id: string(1024), direction: { type: "string", enum: ["subtree", "ancestors", "neighbors"] }, edge: { type: "string", enum: [...SPEC_EDGE_KINDS] }, depth: integer(3), limit: integer(500, 1) }, ["id"]) },
|
|
11
17
|
{ command: "grep", name: "vmem_spec_grep", usage: "spec grep [query] [--source ID] [--worktree PATH] [--literal] [--type TYPE] [--status STATUS] [--tag TAG] [--parent ID] [--depends-on ID] [--covers-path FILE] [--offset 0..10000] [--limit 1..500] [--json]", description: "Search specs with FTS terms or literal substring, metadata/path-scope filters and continuation offsets.", inputSchema: schema({ query: string(1024, 0), literal: { type: "boolean" }, type: string(256), status: string(256), tag: string(1024), parent: string(1024), dependsOn: string(1024), coversPath: string(4096), offset: integer(10000), limit: integer(500, 1) }) },
|
|
12
18
|
{ command: "validate", name: "vmem_spec_validate", usage: "spec validate [--source ID] [--worktree PATH] [--require-fresh] [--limit 1..500] [--json] | spec validate --repo PATH [--require-fresh] [--limit 1..500] [--json]", description: "Validate spec candidates and report bounded errors, warnings and computed freshness; requireFresh makes stale scopes fatal.", inputSchema: schema({ requireFresh: { type: "boolean" }, limit: integer(500, 1) }) },
|
|
19
|
+
{ command: "create", name: "vmem_spec_create", usage: "spec create <path> --id ID --type goal|architecture|module|submodule --title TEXT [--source ID] [--worktree PATH] [--status draft|active|deprecated] [--parent ID] [--superseded-by ID] [--depends-on JSON] [--references JSON] [--implements JSON] [--covers JSON] [--tags JSON] [--paths JSON] [--verified-against SHA] [--json]", description: "Create a new spec with ordered frontmatter and headings for its type, defaulting to draft; refuse unsafe paths, existing files, secrets and new validation errors.", inputSchema: schema({ path: string(4096), id: string(1024), ...scalarChanges.properties, ...listChanges.properties }, ["path", "id", "type", "title"]) },
|
|
20
|
+
{ command: "update", name: "vmem_spec_update", usage: "spec update <id> [--source ID] [--worktree PATH] [--set JSON] [--unset JSON] [--add JSON] [--remove JSON] [--expected-sha SHA] [--json]", description: "Update only spec frontmatter with scalar set/unset and list add/remove, preserving body bytes and refusing new validation errors; expectedSha protects a prior read.", inputSchema: schema({ id: string(1024), set: scalarChanges, unset: { type: "array", items: { type: "string", enum: [...optionalFields] }, maxItems: optionalFields.length }, add: listChanges, remove: listChanges, expectedSha: { ...string(64, 64), pattern: "^[a-f0-9]{64}$" } }, ["id"]) },
|
|
21
|
+
{ command: "delete", name: "vmem_spec_delete", usage: "spec delete <id> [--source ID] [--worktree PATH] [--confirm] [--fingerprint SHA] [--json]", description: "Preview a spec deletion with its backlinks, children and fingerprint; confirm with the current fingerprint to delete only that spec and acknowledge the listed links.", inputSchema: schema({ id: string(1024), confirm: { type: "boolean" }, fingerprint: { ...string(64, 64), pattern: "^[a-f0-9]{64}$" } }, ["id"]) },
|
|
13
22
|
] as const;
|
|
14
23
|
export type SpecCommand = typeof SPEC_COMMANDS[number]["command"];
|
|
15
24
|
export const specCommandSchema = (command: SpecCommand) => SPEC_COMMANDS.find(item => item.command === command)!.inputSchema;
|