@staix/vault-mem 0.11.0 → 0.12.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 +12 -0
- package/README.md +17 -2
- package/bin/vmem.js +5 -1
- package/package.json +2 -1
- package/skills/_shared/vault-adapter.md +131 -0
- package/skills/skill-mine/SKILL.md +52 -0
- package/skills/skill-mine/vocab/actions.yaml +110 -0
- package/skills/skill-mine/vocab/objects.yaml +123 -0
- package/skills/vault-connect/SKILL.md +75 -0
- package/skills/vault-extract/README.md +20 -0
- package/skills/vault-extract/SKILL.md +139 -0
- package/skills/vault-graph/SKILL.md +120 -0
- package/skills/vault-learn/SKILL.md +111 -0
- package/skills/vault-lint/README.md +32 -0
- package/skills/vault-lint/SKILL.md +137 -0
- package/skills/vault-lint/references/lint-output.md +97 -0
- package/skills/vault-lint/references/vault-scope-rules.md +26 -0
- package/skills/vault-lint/references/work-scope-checks.md +71 -0
- package/skills/vault-refactor/SKILL.md +112 -0
- package/skills/vault-remember/SKILL.md +38 -0
- package/skills/vault-rethink/README.md +15 -0
- package/skills/vault-rethink/SKILL.md +58 -0
- package/skills/vault-stats/SKILL.md +49 -0
- package/skills/vault-sync/README.md +15 -0
- package/skills/vault-sync/SKILL.md +195 -0
- package/skills/vault-sync/references/r4-method-evidence.md +12 -0
- package/skills/vault-update/SKILL.md +68 -0
- package/skills/vmem-status/SKILL.md +30 -0
- package/src/amem/host-api.ts +5 -1
- package/src/analysis-input.ts +15 -0
- package/src/analysis-types.ts +3 -1
- package/src/assertion-policy.ts +4 -2
- package/src/assertions.ts +48 -8
- package/src/cli-output.ts +10 -3
- package/src/cli.ts +29 -3
- package/src/commands-table.ts +3 -1
- package/src/config.ts +21 -7
- package/src/enrichment-query.ts +65 -0
- package/src/enrichment-search.ts +69 -0
- package/src/enrichment-store.ts +197 -0
- package/src/enrichment.ts +245 -0
- package/src/graph-evidence.ts +2 -2
- package/src/index.ts +9 -0
- package/src/mcp-vault.ts +46 -8
- package/src/proposal-provider.ts +3 -2
- package/src/proposals.ts +10 -4
- package/src/read-output.ts +1 -1
- package/src/registry.ts +57 -2
- package/src/setup.ts +12 -3
- package/src/skills-install.ts +216 -0
- package/src/ui/panel-types.ts +55 -0
- package/src/ui/panel.js +76 -0
- package/src/ui/plugin.ts +95 -5
- package/src/vault-graph.ts +15 -7
- package/src/vault-index.ts +17 -0
- package/src/vault-lint.ts +12 -4
- package/src/write-operations.ts +38 -1
- package/src/write-types.ts +1 -0
- package/src/write-validation.ts +2 -1
- package/src/writer.ts +1 -1
package/src/index.ts
CHANGED
|
@@ -66,3 +66,12 @@ export { validateSpecs, introducedSpecErrors, validateSpecRepo } from "./spec-va
|
|
|
66
66
|
export type { SpecValidationIssue, SpecValidationOptions, SpecValidationReport, SpecRepoValidationOptions, SpecRepoValidation } from "./spec-validate.ts";
|
|
67
67
|
export { specFreshness, specsCoveringPath } from "./spec-freshness.ts";
|
|
68
68
|
export type { SpecFreshnessEntry, SpecFreshnessReport, SpecFreshnessOptions } from "./spec-freshness.ts";
|
|
69
|
+
|
|
70
|
+
export { settingsSnapshot, changeSettings } from "./registry.ts";
|
|
71
|
+
export type { SettingsChanges, SettingsRequest, SettingsSnapshot, SettingsResult } from "./registry.ts";
|
|
72
|
+
export { plugin as consolePlugin } from "./ui/plugin.ts";
|
|
73
|
+
export { listEnrichmentWork, intakeEnrichment, readEnrichment, reconcileEnrichment } from "./enrichment.ts";
|
|
74
|
+
export type { EnrichmentWorkRequest, EnrichmentIntakeRequest } from "./enrichment.ts";
|
|
75
|
+
export { hybridSearch, similarNotes } from "./enrichment-query.ts";
|
|
76
|
+
export type { QueryVector } from "./enrichment-query.ts";
|
|
77
|
+
export type { EnrichmentKind, EnrichmentProducer } from "./enrichment-store.ts";
|
package/src/mcp-vault.ts
CHANGED
|
@@ -12,12 +12,15 @@ import { buildGraph, graphNeighbors, graphPath, LINK_RELATIONS } from "./vault-g
|
|
|
12
12
|
import { lintVault } from "./vault-lint.ts";
|
|
13
13
|
import { writeAnalysisReports } from "./analysis-reports.ts";
|
|
14
14
|
import { parseFrontmatter } from "./frontmatter.ts";
|
|
15
|
+
import { listEnrichmentWork, intakeEnrichment, readEnrichment, reconcileEnrichment } from "./enrichment.ts";
|
|
16
|
+
import { hybridSearch, similarNotes } from "./enrichment-query.ts";
|
|
17
|
+
import type { EnrichmentKind } from "./enrichment-store.ts";
|
|
15
18
|
import type { VaultSpec } from "./config.ts";
|
|
16
19
|
import { loadRegistry, registryStatus } from "./registry.ts";
|
|
17
20
|
import { VaultIndex, MAX_NOTE_BYTES } from "./vault-index.ts";
|
|
18
21
|
import { CHANGES_PAGE_LIMIT, HISTORY_PAGE_LIMIT, SNAPSHOT_CURSOR_CHARS, readChanges, readHistory, readRevision } from "./vault-history.ts";
|
|
19
22
|
import { listVaultFiles, readVaultFile } from "./vault-files.ts";
|
|
20
|
-
import { appendLog, logBinding, readLog } from "./vault-log.ts";
|
|
23
|
+
import { appendLog, logBinding, matchesBinding, readLog } from "./vault-log.ts";
|
|
21
24
|
import { STATS_MAX_DAYS, vaultStats } from "./vault-stats.ts";
|
|
22
25
|
import { applyWrite } from "./writer.ts";
|
|
23
26
|
import { notePath } from "./write-operations.ts";
|
|
@@ -45,13 +48,18 @@ const ASSERT_OP = object({ op: { type: "string", enum: ["declare", "relink", "as
|
|
|
45
48
|
const oid = { type: "string", minLength: 40, maxLength: 64, pattern: "^(?:[0-9a-f]{40}|[0-9a-f]{64})$" };
|
|
46
49
|
const logEvent = LOG_EVENT_SCHEMA;
|
|
47
50
|
const scalar = { type: ["string", "number", "boolean", "null", "array"], maxLength: 4096, maxItems: 64, items: { type: ["string", "number", "boolean"], maxLength: 1024 } };
|
|
51
|
+
const enrichmentKinds = ["embedding", "summary", "community-label", "inferred-link", "fact"];
|
|
52
|
+
const enrichmentOperation = { type: "object", maxProperties: 32, properties: ASSERT_OP.properties, additionalProperties: false };
|
|
53
|
+
const enrichmentValue = { type: ["string", "array", "object"], maxLength: 8192, maxItems: 4096,
|
|
54
|
+
items: { type: ["number", "object"], maxProperties: 32, properties: enrichmentOperation.properties, additionalProperties: false },
|
|
55
|
+
maxProperties: 32, properties: { target: string(191) }, additionalProperties: scalar };
|
|
48
56
|
const metadata = { type: "object", maxProperties: 32, properties: { authors: { type: "array", minItems: 1, maxItems: 100, items: string(1024) } }, additionalProperties: scalar };
|
|
49
57
|
const proposalMetadata = { ...metadata, properties: { ...metadata.properties, evidence: { type: "array", maxItems: 16, items: object({ source: string(512), sha256: sha, quote: string(2048), section: string(1024) }, ["source", "sha256", "quote"]) } } };
|
|
50
|
-
const proposalOperation = object({ op: { type: "string", enum: ["create", "patch"] }, path: string(200), frontmatter: proposalMetadata, body: string(32768, 0), expectedSha: sha,
|
|
58
|
+
const proposalOperation = object({ op: { type: "string", enum: ["create", "patch", "infer-link"] }, path: string(200), target: string(191), frontmatter: proposalMetadata, body: string(32768, 0), expectedSha: sha,
|
|
51
59
|
edits: { type: "array", minItems: 1, maxItems: 32, items: object({ oldString: string(8192), newString: string(8192, 0) }, ["oldString", "newString"]) } }, ["op", "path"]);
|
|
52
60
|
|
|
53
61
|
/** Tool names for the implemented read, write, log, analysis and promotion providers. */
|
|
54
|
-
export const VMEM_TOOL_NAMES = ["vmem_status", "vmem_search", "vmem_brief", "vmem_read", "vmem_read_many", "vmem_list", "vmem_links", "vmem_history", "vmem_changes", "vmem_mocs", "vmem_check", "vmem_log_tail",
|
|
62
|
+
export const VMEM_TOOL_NAMES = ["vmem_status", "vmem_search", "vmem_enrichment_work", "vmem_enrichment_intake", "vmem_enrichment_get", "vmem_enrichment_reconcile", "vmem_similar", "vmem_brief", "vmem_read", "vmem_read_many", "vmem_list", "vmem_links", "vmem_history", "vmem_changes", "vmem_mocs", "vmem_check", "vmem_log_tail",
|
|
55
63
|
"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_graph_path", "vmem_graph_explain", "vmem_promote", "vmem_skills_mine", "vmem_read_file", "vmem_list_files", "vmem_report", "vmem_evidence", "vmem_stats", "vmem_proposal_submit", "vmem_proposal_list", "vmem_proposal_show", "vmem_proposal_apply", "vmem_proposal_reject", "vmem_proposal_reconcile", "vmem_assert", "vmem_assertions", "vmem_assertions_purge", "vmem_assertions_exposure", ...SPEC_COMMANDS.map(item => item.name)] as const;
|
|
56
64
|
|
|
57
65
|
/** Server `initialize` instructions: purpose, navigation order and the write contract. Pinned by a test, under 400 bytes. */
|
|
@@ -64,7 +72,12 @@ export function vaultTools(ids: readonly string[], orgIds: readonly string[] = [
|
|
|
64
72
|
const orgVault = orgIds.length ? { type: "string", enum: [...orgIds] } : string(32);
|
|
65
73
|
return [
|
|
66
74
|
tool("vmem_status", "Registered vaults with health, write policy, effective pii and the piiPolicy matrix (read-only).", object({})),
|
|
67
|
-
tool("vmem_search", "Full-text (BM25) search over indexed notes. Literal AND terms.", object({ query: string(1000), vault, limit: integer(1, 50), type: string(64), domain: string(64) }, ["query"])),
|
|
75
|
+
tool("vmem_search", "Full-text (BM25) search over indexed notes. Literal AND terms. Supply model and vector together for local hybrid ranking with stored embeddings.", object({ query: string(1000), vault, limit: integer(1, 50), type: string(64), domain: string(64), model: string(256), vector: { type: "array", minItems: 1, maxItems: 4096, items: { type: "number" } } }, ["query"])),
|
|
76
|
+
tool("vmem_enrichment_work", "List a bounded page of notes needing one implemented enrichment kind.", object({ vault, kind: { type: "string", enum: enrichmentKinds }, limit: integer(1, 100), after: string(1024) }, ["kind"])),
|
|
77
|
+
tool("vmem_enrichment_intake", "Submit bounded enrichment output for a source note. Kind-specific validation, PII screening, source hash checks and current vault write policy apply.", object({ vault, path: note, contentHash: sha, kind: { type: "string", enum: enrichmentKinds }, producer: object({ skill: string(128), version: string(64), model: string(256) }, ["skill", "version", "model"]), createdAt: string(32), value: enrichmentValue }, ["path", "contentHash", "kind", "producer", "createdAt", "value"]), "write"),
|
|
78
|
+
tool("vmem_enrichment_get", "Read one current enrichment record after rechecking its source hash and current disclosure policy.", object({ vault, path: note, kind: { type: "string", enum: enrichmentKinds } }, ["path", "kind"])),
|
|
79
|
+
tool("vmem_enrichment_reconcile", "Preview, then explicitly confirm after inspecting the journal or proposals, resolution of an uncertain intake as published or not_published. A wrong resolution can allow a duplicate or suppress work.", object({ vault, path: note, kind: { type: "string", enum: ["fact", "inferred-link"] }, resolution: { type: "string", enum: ["published", "not_published"] }, ...twoStep }, ["path", "kind", "resolution"]), "confirm"),
|
|
80
|
+
tool("vmem_similar", "Find notes nearest to a note with a current stored embedding.", object({ vault, path: note, limit: integer(1, 100) }, ["path"])),
|
|
68
81
|
tool("vmem_brief", "Intent-ranked note pointers and one-hop neighbors, with metadata PII/deny screening and whole-line byte cap including the result JSON. No note bodies; read a selected pointer with vmem_read.", object({ vault, intent: string(1024), paths: { type: "array", maxItems: 16, items: string(1024) }, bytes: integer(256, 4096) }, ["intent"])),
|
|
69
82
|
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. With revision, read that full commit id's blob for the path instead: the result carries revision, blob and content sha256 plus basis git_snapshot, within the 48 KiB transport bound.", object({ path: note, vault, maxBytes: integer(1, 65536), section: string(1024), offset: integer(0, MAX_NOTE_BYTES), revision: oid }, ["path"])),
|
|
70
83
|
tool("vmem_read_many", "Read up to 20 notes (8 KiB each).", object({ paths: { type: "array", minItems: 1, maxItems: 20, items: note }, vault }, ["paths"])),
|
|
@@ -101,7 +114,7 @@ export function vaultTools(ids: readonly string[], orgIds: readonly string[] = [
|
|
|
101
114
|
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"),
|
|
102
115
|
tool("vmem_evidence", "Verify a note's version-1 evidence entries (source, sha256, quote, optional section): flat notes/*.md sources in the same vault are re-read on every call and reported verified, stale, missing, ambiguous or unsupported with UTF-8 byte offsets; other references are unverified_external without I/O. Proves that quoted bytes occur in a source version, not that a claim is true. Writes nothing, takes no lock, keeps no cache.", object({ vault, path: note }, ["path"])),
|
|
103
116
|
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) })),
|
|
104
|
-
tool("vmem_proposal_submit", "Screen and save one create
|
|
117
|
+
tool("vmem_proposal_submit", "Screen and save one create, exact-patch or inferred-link proposal without modifying vault notes or the log. Agent labels are unverified.", object({ vault, operation: proposalOperation, agentLabel: string(256) }, ["operation"]), "write"),
|
|
105
118
|
tool("vmem_proposal_list", "List screened proposal summaries, pending by default; pass nextCursor as after.", object({ vault, state: { type: "string", enum: ["pending", "applied", "rejected", "apply_unknown"] }, limit: integer(1, 100), after: string(36) })),
|
|
106
119
|
tool("vmem_proposal_show", "Read a screened proposal operation in UTF-8 pages, with the complete encoded response bounded to 48 KiB.", object({ vault, id: string(36), offset: integer(0, 32768), maxBytes: integer(1, 16384) }, ["id"])),
|
|
107
120
|
tool("vmem_proposal_apply", "Preview an apply, then confirm with its fingerprint. An interrupted apply remains apply_unknown and is never replayed automatically.", object({ vault, id: string(36), ...twoStep }, ["id"]), "confirm"),
|
|
@@ -164,7 +177,7 @@ export function exposureReply(reply: ExposureReceipt & { refused?: true }): unkn
|
|
|
164
177
|
export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.env): { tools: McpTool[]; handlers: Record<string, McpHandler>; vaults: VaultSpec[]; defaultVault: string | undefined; instructions: string } {
|
|
165
178
|
const startup = loadRegistry(home), vaults = startup.vaults, ids = vaults.map(v => v.id);
|
|
166
179
|
const proposalBindings = new Map(vaults.map(v => { try { return [v.id, logBinding(v, startup)] as const; } catch { return [v.id, null] as const; } }));
|
|
167
|
-
const defaultVault = (vaults.find(v => v.kind === "personal") ?? vaults[0])?.id;
|
|
180
|
+
const defaultVault = vaults.find(v => v.id === startup.defaultVault)?.id ?? (vaults.find(v => v.kind === "personal") ?? vaults[0])?.id;
|
|
168
181
|
const pick = (args: Record<string, unknown>): VaultSpec => {
|
|
169
182
|
const id = str(args.vault) ?? defaultVault;
|
|
170
183
|
const spec = vaults.find(v => v.id === id);
|
|
@@ -175,6 +188,17 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
|
|
|
175
188
|
const spec = pick(args), index = new VaultIndex(home, spec, vaults.map(v => v.path));
|
|
176
189
|
try { index.scan(); return body(index); } finally { index.close(); }
|
|
177
190
|
};
|
|
191
|
+
const assertStartupBinding = (spec: VaultSpec): void => {
|
|
192
|
+
const current = loadRegistry(home).vaults.find(v => v.id === spec.id);
|
|
193
|
+
if (!current || JSON.stringify(current) !== JSON.stringify(spec)) throw new Error("enrichment: vault binding changed since MCP startup; restart the MCP server");
|
|
194
|
+
};
|
|
195
|
+
const enrichmentReadGuard = (spec: VaultSpec) => {
|
|
196
|
+
const config = loadRegistry(home), current = config.vaults.find(v => v.id === spec.id);
|
|
197
|
+
if (!current || JSON.stringify(current) !== JSON.stringify(spec)) throw new Error("enrichment: vault binding changed since MCP startup; restart the MCP server");
|
|
198
|
+
let binding: ReturnType<typeof logBinding>;
|
|
199
|
+
try { binding = logBinding(spec, config); } catch { throw new Error("enrichment: vault root is unavailable; restore the registered vault and retry"); }
|
|
200
|
+
return () => { if (!matchesBinding(loadRegistry(home), spec.id, binding)) throw new Error("enrichment: vault binding or policy changed during the read; restart the MCP server and retry"); };
|
|
201
|
+
};
|
|
178
202
|
const write = (args: Record<string, unknown>, operation: WriteOp, extra: Partial<WriteRequest> = {}): WriteReceipt | ReturnType<typeof refusal> & Partial<WriteReceipt> => {
|
|
179
203
|
const request: WriteRequest = { vault: pick(args).id, operation, channel: "mcp", ...extra, ...(args.log ? { log: args.log as LogEvent } : {}) };
|
|
180
204
|
const receipt = applyWrite(home, request, { env });
|
|
@@ -197,7 +221,7 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
|
|
|
197
221
|
vmem_brief: args => vaultBrief(home, { vault: pick(args).id, intent: args.intent as string, paths: args.paths as string[] | undefined, bytes: args.bytes as number | undefined }, pick(args)),
|
|
198
222
|
vmem_promote: async args => {
|
|
199
223
|
const { promoteToOrg } = await import("./org-promote.ts");
|
|
200
|
-
const source = vaults.find(v => v.id === defaultVault && v.kind === "personal");
|
|
224
|
+
const source = vaults.find(v => v.id === defaultVault && v.kind === "personal") ?? vaults.find(v => v.kind === "personal");
|
|
201
225
|
if (!source) return refusal("POLICY", "no personal vault registered");
|
|
202
226
|
const result = promoteToOrg(home, { from: source.id, note: str(args.path)!, to: str(args.to)!, channel: "mcp", again: args.again === true, confirm: args.confirm === true,
|
|
203
227
|
...(Array.isArray(args.topics) ? { topics: args.topics as string[] } : {}), ...(str(args.fingerprint) ? { fingerprint: str(args.fingerprint) } : {}) }, { env });
|
|
@@ -226,7 +250,21 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
|
|
|
226
250
|
vmem_graph_path: args => graphPath(buildGraph(analysisInput(home,pick(args).id,{expectedVault:pick(args)}).snapshot),str(args.from)!,str(args.to)!,{maxHops:(args.maxHops as number|undefined) ?? 6,viaHubs:args.viaHubs === true,...(str(args.relation) === undefined ? {} : {relation:str(args.relation)!})}),
|
|
227
251
|
vmem_graph_explain: args => explainGraphPath(analysisInput(home,pick(args).id,{expectedVault:pick(args)}).snapshot,str(args.from)!,str(args.to)!,{maxHops:(args.maxHops as number|undefined) ?? 6,viaHubs:args.viaHubs === true,...(str(args.relation) === undefined ? {} : {relation:str(args.relation)!})}),
|
|
228
252
|
vmem_status: () => ({ defaultVault: defaultVault ?? null, vaults: registryStatus(home).filter(v => ids.includes(v.id)) }),
|
|
229
|
-
vmem_search: args =>
|
|
253
|
+
vmem_search: args => {
|
|
254
|
+
const spec = pick(args), model = str(args.model), vector = args.vector;
|
|
255
|
+
if ((model === undefined) !== (vector === undefined)) throw new Error("enrichment: model and vector must be supplied together; provide both or omit both");
|
|
256
|
+
if (model !== undefined) {
|
|
257
|
+
const check = enrichmentReadGuard(spec);
|
|
258
|
+
const result = read(args, index => { check(); return { hits: hybridSearch(home, spec.id, index, str(args.query)!, { limit: (args.limit as number | undefined) ?? 20, type: str(args.type), domain: str(args.domain) }, { model, values: vector as number[] }) }; });
|
|
259
|
+
check(); return result;
|
|
260
|
+
}
|
|
261
|
+
return read(args, index => ({ hits: index.search(str(args.query)!, { limit: (args.limit as number | undefined) ?? 20, type: str(args.type), domain: str(args.domain) }) }));
|
|
262
|
+
},
|
|
263
|
+
vmem_enrichment_work: args => { const spec = pick(args), check = enrichmentReadGuard(spec); const result = listEnrichmentWork(home, { vault: spec.id, kind: str(args.kind) as EnrichmentKind, ...(typeof args.limit === "number" ? { limit: args.limit } : {}), ...(str(args.after) ? { after: str(args.after)! } : {}) }); check(); return result; },
|
|
264
|
+
vmem_enrichment_intake: args => { const spec = pick(args); assertStartupBinding(spec); return intakeEnrichment(home, { vault: spec.id, path: str(args.path)!, contentHash: str(args.contentHash)!, kind: str(args.kind) as EnrichmentKind, producer: args.producer as { skill: string; version: string; model: string }, createdAt: str(args.createdAt)!, value: args.value, channel: "mcp" }, { env, expectedVault: spec }); },
|
|
265
|
+
vmem_enrichment_get: args => { const spec = pick(args), check = enrichmentReadGuard(spec); const result = readEnrichment(home, { vault: spec.id, path: str(args.path)!, kind: str(args.kind) as EnrichmentKind }); check(); return result; },
|
|
266
|
+
vmem_enrichment_reconcile: args => { const spec = pick(args); assertStartupBinding(spec); return reconcileEnrichment(home, { vault: spec.id, path: str(args.path)!, kind: str(args.kind) as "fact" | "inferred-link", resolution: str(args.resolution) as "published" | "not_published", channel: "mcp", ...twoStep(args) }, { expectedVault: spec }); },
|
|
267
|
+
vmem_similar: args => { const spec = pick(args), check = enrichmentReadGuard(spec); const result = read(args, index => { check(); return { hits: similarNotes(home, spec.id, index, str(args.path)!, (args.limit as number | undefined) ?? 20) }; }); check(); return result; },
|
|
230
268
|
vmem_read: args => str(args.revision) === undefined
|
|
231
269
|
? read(args, index => { const r = index.show(str(args.path)!, (args.maxBytes as number | undefined) ?? 16384, str(args.section), args.offset as number | undefined); return document(r); })
|
|
232
270
|
: readRevision({ vault: pick(args), home, env, denyPaths: loadRegistry(home).denyPaths ?? [], note: str(args.path)!, revision: str(args.revision)!,
|
package/src/proposal-provider.ts
CHANGED
|
@@ -18,7 +18,7 @@ import { canonicalPath, isDenied } from "./platform.ts";
|
|
|
18
18
|
import { cleanupOwnedFile } from "./write-files.ts";
|
|
19
19
|
|
|
20
20
|
export interface ProposalSubmitRequest { vault: string; operation: unknown; agentLabel?: string }
|
|
21
|
-
export interface ProposalContext { channel: "cli" | "mcp"; env?: NodeJS.ProcessEnv; now?: Date; expectedVault?: VaultSpec; expectedBinding?: LogBinding | null }
|
|
21
|
+
export interface ProposalContext { channel: "cli" | "mcp"; env?: NodeJS.ProcessEnv; now?: Date; expectedVault?: VaultSpec; expectedBinding?: LogBinding | null; validateBeforeStore?: () => void; proposalId?: string }
|
|
22
22
|
export interface ProposalSubmitted { ok: boolean; stored: boolean | null; id: string; vault: string; path: string | null; state: "pending" | null; createdAt: string; payloadDigest: string | null; issues: WriteIssue[] }
|
|
23
23
|
export interface ProposalSummary { id: string; vault: string; path: string; state: ProposalRecord["state"]; createdAt: string }
|
|
24
24
|
export interface ProposalListRequest { vault: string; state?: ProposalRecord["state"]; limit?: number; after?: string }
|
|
@@ -113,7 +113,7 @@ export function submitProposal(home: string, request: ProposalSubmitRequest, opt
|
|
|
113
113
|
if (!preview.ok) throw new Error(`proposal: validation refused (${[...new Set(preview.issues.filter(issue => issue.severity === "error").map(issue => issue.code))].join(", ") || "unknown"}); correct the proposal and retry`);
|
|
114
114
|
if (preview.changes.length !== 1 || preview.changes[0]!.beforeSha === preview.changes[0]!.sha256) throw new Error("proposal: operation produces no note change; revise the proposal before submitting");
|
|
115
115
|
const createdAt = (options.now ?? new Date()).toISOString();
|
|
116
|
-
const record: ProposalRecord = { schemaVersion: 1, id: randomUUID(), vault: vault.id, bindingDigest, state: "pending", createdAt, updatedAt: createdAt, operation, payloadDigest: proposalPayloadDigest(operation), ...(request.agentLabel !== undefined ? { agentLabel: request.agentLabel } : {}) };
|
|
116
|
+
const record: ProposalRecord = { schemaVersion: 1, id: options.proposalId ?? randomUUID(), vault: vault.id, bindingDigest, state: "pending", createdAt, updatedAt: createdAt, operation, payloadDigest: proposalPayloadDigest(operation), ...(request.agentLabel !== undefined ? { agentLabel: request.agentLabel } : {}) };
|
|
117
117
|
encodeProposalRecord(record);
|
|
118
118
|
const placeholder = "0".repeat(64);
|
|
119
119
|
encodeProposalRecord({ ...record, state: "applied", intent: { fingerprint: placeholder, beforeSha: placeholder, afterSha: placeholder }, receipt: { applied: true, logged: false, beforeSha: placeholder, afterSha: placeholder } });
|
|
@@ -137,6 +137,7 @@ export function submitProposal(home: string, request: ProposalSubmitRequest, opt
|
|
|
137
137
|
const bindingIssues: WriteIssue[] = [];
|
|
138
138
|
checkStoredBinding(home, vault.id, bindingDigest, config.denyPaths ?? [], bindingIssues);
|
|
139
139
|
issues.push(...warningsOf(bindingIssues));
|
|
140
|
+
options.validateBeforeStore?.();
|
|
140
141
|
attempted = true; stored = null;
|
|
141
142
|
try { createStoredProposal(home, record, config.denyPaths ?? [], fd); stored = true; }
|
|
142
143
|
catch (error) {
|
package/src/proposals.ts
CHANGED
|
@@ -6,7 +6,7 @@ import type { PatchEdit, WriteOp } from "./write-types.ts";
|
|
|
6
6
|
export const MAX_PROPOSAL_RECORD_BYTES = 32 * 1024;
|
|
7
7
|
export const MAX_PROPOSAL_RPC_BYTES = 48 * 1024;
|
|
8
8
|
export const MAX_PROPOSAL_EDITS = 32;
|
|
9
|
-
export type ProposalOperation = Extract<WriteOp, { op: "create" | "patch" }>;
|
|
9
|
+
export type ProposalOperation = Extract<WriteOp, { op: "create" | "patch" | "infer-link" }>;
|
|
10
10
|
|
|
11
11
|
function object(value: unknown): value is Record<string, unknown> {
|
|
12
12
|
return value !== null && typeof value === "object" && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
|
|
@@ -25,9 +25,9 @@ export function proposalRpcBytes(request: unknown): number { return jsonBytes(re
|
|
|
25
25
|
export function checkProposalRpcSize(request: unknown): void {
|
|
26
26
|
if (proposalRpcBytes(request) > MAX_PROPOSAL_RPC_BYTES) throw new Error("proposal: encoded JSON-RPC request exceeds 48 KiB; shorten the proposal");
|
|
27
27
|
}
|
|
28
|
-
/**
|
|
28
|
+
/** Create, exact-replacement patch and inferred-link proposals have one canonical flat note target. */
|
|
29
29
|
export function parseProposalOperation(value: unknown): ProposalOperation {
|
|
30
|
-
if (!object(value) || typeof value.path !== "string") throw new Error("proposal:
|
|
30
|
+
if (!object(value) || typeof value.path !== "string") throw new Error("proposal: operation or note target is missing; supply a create, patch or infer-link operation with a path");
|
|
31
31
|
if (jsonBytes(value) > MAX_PROPOSAL_RECORD_BYTES) throw new Error("proposal: operation exceeds the 32 KiB record limit; shorten the payload");
|
|
32
32
|
const path = notePath(value.path);
|
|
33
33
|
if (value.op === "create") {
|
|
@@ -45,7 +45,13 @@ export function parseProposalOperation(value: unknown): ProposalOperation {
|
|
|
45
45
|
});
|
|
46
46
|
return { op: "patch", path, edits, expectedSha: value.expectedSha };
|
|
47
47
|
}
|
|
48
|
-
|
|
48
|
+
if (value.op === "infer-link") {
|
|
49
|
+
if (!exactKeys(value, ["op", "path", "target", "expectedSha"]) || typeof value.target !== "string" || typeof value.expectedSha !== "string" || !/^[a-f0-9]{64}$/.test(value.expectedSha)) throw new Error("proposal: infer-link requires a target and base SHA; select a target and reread the source for its current SHA-256");
|
|
50
|
+
const target = notePath(value.target).slice(6, -3);
|
|
51
|
+
if (path === `notes/${target}.md`) throw new Error("proposal: infer-link endpoints must differ; select another target note");
|
|
52
|
+
return { op: "infer-link", path, target, expectedSha: value.expectedSha };
|
|
53
|
+
}
|
|
54
|
+
throw new Error("proposal: unsupported operation; choose create, patch or infer-link");
|
|
49
55
|
}
|
|
50
56
|
|
|
51
57
|
/** Durable record schema: version 1 is local state, not an index or a note. */
|
package/src/read-output.ts
CHANGED
|
@@ -64,7 +64,7 @@ export function logAppendText(r: LogReceipt, o: TextOptions, c: { vault: string;
|
|
|
64
64
|
return blocks(line, issueTable(r.issues, o));
|
|
65
65
|
}
|
|
66
66
|
|
|
67
|
-
const LEVELS: Record<LintCode, "error" | "warn"> = { L01: "error", L02: "error", L03: "warn", L09: "warn", L10: "warn", L11: "warn", L12: "warn", L13: "error", L14: "warn", L15: "warn", L16: "warn", L17: "warn" };
|
|
67
|
+
const LEVELS: Record<LintCode, "error" | "warn"> = { L01: "error", L02: "error", L03: "warn", L09: "warn", L10: "warn", L11: "warn", L12: "warn", L13: "error", L14: "warn", L15: "warn", L16: "warn", L17: "warn", L18: "warn", L19: "warn" };
|
|
68
68
|
const verdict = (r: { errors: number; warnings: number; summary: string }, o: TextOptions) => paint(clean(r.summary), r.errors ? "fail" : r.warnings ? "warn" : "ok", o);
|
|
69
69
|
export function lintText(d: { report: LintReport; notes: number; titles: Record<LintCode, string>; info: Partial<Record<LintCode, string>> }, o: TextOptions, c: { vault: string; note?: string }): string {
|
|
70
70
|
const rows = (Object.keys(d.report.findings) as LintCode[]).flatMap(code => {
|
package/src/registry.ts
CHANGED
|
@@ -3,7 +3,7 @@ import { spawnSync } from "node:child_process";
|
|
|
3
3
|
import { realPath, memoryGitArgv, memoryGitEnv } from "./platform.ts";
|
|
4
4
|
import { hostname } from "node:os";
|
|
5
5
|
import { join } from "node:path";
|
|
6
|
-
import { randomUUID } from "node:crypto";
|
|
6
|
+
import { createHash, randomUUID } from "node:crypto";
|
|
7
7
|
import { CONFIG_FILE, MAX_CONFIG_BYTES, effectiveDomains, parseConfig, parsePii, parseVault, parseSpec, piiExtensions, readConfig, type VaultSpec, type SpecSourceSpec, type VmemConfig } from "./config.ts";
|
|
8
8
|
import { loosenedCells, piiPolicy, piiShorthand } from "./pii.ts";
|
|
9
9
|
export const LOCK_FILE = "config.lock";
|
|
@@ -46,6 +46,8 @@ function mutate<T>(home: string, update: (config: VmemConfig) => T): T {
|
|
|
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
48
|
if (config.vaults.some(vault => vault.canonTables !== undefined)) config.version = Math.max(config.version ?? 1, 4);
|
|
49
|
+
if (config.defaultVault !== undefined || config.vaults.some(vault => vault.graph !== undefined)) config.version = Math.max(config.version ?? 1, 5);
|
|
50
|
+
if (config.vaults.some(vault => vault.enrichment !== undefined)) config.version = Math.max(config.version ?? 1, 6);
|
|
49
51
|
parseConfig(config);
|
|
50
52
|
const text = JSON.stringify(config, null, 2) + "\n";
|
|
51
53
|
if (Buffer.byteLength(text) > MAX_CONFIG_BYTES) throw new Error(`${join(home, CONFIG_FILE)}: serialized config exceeds 64 KiB`);
|
|
@@ -170,7 +172,7 @@ export function removeVault(home: string, id: string, confirm = false): { applie
|
|
|
170
172
|
const remove = (config: VmemConfig) => {
|
|
171
173
|
const vault = config.vaults.find(v => v.id === id);
|
|
172
174
|
if (!vault) throw new Error(`${join(home, CONFIG_FILE)}: unknown vault id ${id}`);
|
|
173
|
-
if (confirm) config.vaults = config.vaults.filter(v => v.id !== id);
|
|
175
|
+
if (confirm) { config.vaults = config.vaults.filter(v => v.id !== id); if (config.defaultVault === id) delete config.defaultVault; }
|
|
174
176
|
return { applied: confirm, vault };
|
|
175
177
|
};
|
|
176
178
|
return confirm ? mutate(home, remove) : remove(loadRegistry(home));
|
|
@@ -262,3 +264,56 @@ export function specStatus(home: string, env: NodeJS.ProcessEnv = process.env) {
|
|
|
262
264
|
}
|
|
263
265
|
});
|
|
264
266
|
}
|
|
267
|
+
|
|
268
|
+
export interface SettingsChanges { defaultVault?: string; write?: VaultSpec["write"]; piiPatterns?: string[]; graphResolution?: number; enrichmentEnabled?: boolean }
|
|
269
|
+
export interface SettingsRequest { vault: string; changes: SettingsChanges; confirm?: boolean; fingerprint?: string }
|
|
270
|
+
export function settingsSnapshot(home: string, id: string) {
|
|
271
|
+
const config = loadRegistry(home), vault = config.vaults.find(v => v.id === id);
|
|
272
|
+
if (!vault) throw new Error("settings: vault is not registered; choose an id from vmem vaults list");
|
|
273
|
+
return { home, vault: vault.id, defaultVaultExplicit: config.vaults.some(v => v.id === config.defaultVault), defaultVault: config.vaults.find(v => v.id === config.defaultVault)?.id ?? (config.vaults.find(v => v.kind === "personal") ?? config.vaults[0])?.id ?? null, write: vault.write, piiPatterns: config.piiPatterns ?? [], graphResolution: vault.graph?.resolution ?? 1, enrichmentEnabled: vault.enrichment?.enabled ?? false };
|
|
274
|
+
}
|
|
275
|
+
export function changeSettings(home: string, request: SettingsRequest) {
|
|
276
|
+
if (!request || !request.changes || typeof request.changes !== "object" || Array.isArray(request.changes)) throw new Error("settings: changes must be an object; supply settings fields");
|
|
277
|
+
if (typeof request.vault !== "string" || !request.vault) throw new Error("settings: vault id is missing; select a registered vault");
|
|
278
|
+
const keys = Object.keys(request.changes);
|
|
279
|
+
if (keys.some(k => (request.changes as unknown as Record<string, unknown>)[k] === undefined)) throw new Error("settings: undefined values are invalid; supply a value for each setting");
|
|
280
|
+
if (!keys.length || keys.some(k => !["defaultVault", "write", "piiPatterns", "graphResolution", "enrichmentEnabled"].includes(k))) throw new Error("settings: missing or unknown changes; use defaultVault, write, piiPatterns, graphResolution or enrichmentEnabled");
|
|
281
|
+
const evaluate = (config: VmemConfig, apply: boolean) => {
|
|
282
|
+
const vault = config.vaults.find(v => v.id === request.vault);
|
|
283
|
+
if (!vault) throw new Error("settings: vault is not registered; choose an id from vmem vaults list");
|
|
284
|
+
const supplied = request.changes;
|
|
285
|
+
const next = structuredClone(config), selected = next.vaults.find(v => v.id === request.vault)!;
|
|
286
|
+
if (supplied.defaultVault !== undefined) {
|
|
287
|
+
if (!next.vaults.some(v => v.id === supplied.defaultVault)) throw new Error("settings: default vault is not registered; choose an id from vmem vaults list");
|
|
288
|
+
next.defaultVault = supplied.defaultVault;
|
|
289
|
+
}
|
|
290
|
+
if (supplied.write !== undefined) selected.write = supplied.write;
|
|
291
|
+
if (supplied.piiPatterns !== undefined) next.piiPatterns = supplied.piiPatterns;
|
|
292
|
+
if (supplied.graphResolution !== undefined) selected.graph = { ...selected.graph, resolution: supplied.graphResolution };
|
|
293
|
+
if (supplied.enrichmentEnabled !== undefined) selected.enrichment = { ...selected.enrichment, enabled: supplied.enrichmentEnabled };
|
|
294
|
+
try { parseConfig(next); } catch (error) { throw new Error(`settings: invalid change (${message(error)}); correct the settings and preview again`); }
|
|
295
|
+
const effectiveDefault = config.vaults.find(v => v.id === config.defaultVault)?.id ?? (config.vaults.find(v => v.kind === "personal") ?? config.vaults[0])?.id;
|
|
296
|
+
const changes: SettingsChanges = {};
|
|
297
|
+
if (supplied.defaultVault !== undefined && supplied.defaultVault !== effectiveDefault) changes.defaultVault = supplied.defaultVault;
|
|
298
|
+
if (supplied.write !== undefined && supplied.write !== vault.write) changes.write = supplied.write;
|
|
299
|
+
if (supplied.piiPatterns !== undefined && JSON.stringify(supplied.piiPatterns) !== JSON.stringify(config.piiPatterns ?? [])) changes.piiPatterns = supplied.piiPatterns;
|
|
300
|
+
if (supplied.graphResolution !== undefined && supplied.graphResolution !== (vault.graph?.resolution ?? 1)) changes.graphResolution = supplied.graphResolution;
|
|
301
|
+
if (supplied.enrichmentEnabled !== undefined && supplied.enrichmentEnabled !== (vault.enrichment?.enabled ?? false)) changes.enrichmentEnabled = supplied.enrichmentEnabled;
|
|
302
|
+
if (!Object.keys(changes).length) throw new Error("settings: no values changed; change a setting before previewing");
|
|
303
|
+
// Rebuild from the current config so unchanged effective defaults are not written explicitly.
|
|
304
|
+
const actual = structuredClone(config), target = actual.vaults.find(v => v.id === request.vault)!;
|
|
305
|
+
if (changes.defaultVault !== undefined) actual.defaultVault = changes.defaultVault;
|
|
306
|
+
if (changes.write !== undefined) target.write = changes.write;
|
|
307
|
+
if (changes.piiPatterns !== undefined) actual.piiPatterns = changes.piiPatterns;
|
|
308
|
+
if (changes.graphResolution !== undefined) target.graph = { ...target.graph, resolution: changes.graphResolution };
|
|
309
|
+
if (changes.enrichmentEnabled !== undefined) target.enrichment = { ...target.enrichment, enabled: changes.enrichmentEnabled };
|
|
310
|
+
const fingerprint = createHash("sha256").update(JSON.stringify([config, request.vault, changes])).digest("hex");
|
|
311
|
+
if (apply && request.fingerprint !== fingerprint) throw new Error("settings: preview is stale or fingerprint is missing; run the preview again and confirm its fingerprint");
|
|
312
|
+
if (apply) Object.assign(config, actual);
|
|
313
|
+
return { applied: apply, fingerprint, changes };
|
|
314
|
+
};
|
|
315
|
+
return request.confirm ? mutate(home, config => evaluate(config, true)) : evaluate(loadRegistry(home), false);
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
export type SettingsSnapshot = ReturnType<typeof settingsSnapshot>;
|
|
319
|
+
export type SettingsResult = ReturnType<typeof changeSettings>;
|
package/src/setup.ts
CHANGED
|
@@ -3,6 +3,8 @@ import { homedir } from "node:os";
|
|
|
3
3
|
import { dirname, isAbsolute, join, resolve } from "node:path";
|
|
4
4
|
import { createHash, randomUUID } from "node:crypto";
|
|
5
5
|
import { isDeepStrictEqual } from "node:util";
|
|
6
|
+
import { shellWord } from "./text-output.ts";
|
|
7
|
+
import { installSkills, skillRoot, type SkillInstallReport } from "./skills-install.ts";
|
|
6
8
|
import { fileURLToPath } from "node:url";
|
|
7
9
|
|
|
8
10
|
/** Hosts whose MCP configuration `vmem setup` can register; `all` covers every user-level host (not agy). */
|
|
@@ -15,7 +17,7 @@ export interface McpEntry { command: string; args: string[] }
|
|
|
15
17
|
interface HostFile { target: SetupTarget; file: string; format: "json" | "toml"; key: string }
|
|
16
18
|
export interface SetupAction { target: SetupTarget; file: string; change: "add" | "replace" | "unchanged" | "restore" | "remove" | "refused" | "none"; reason?: string }
|
|
17
19
|
export interface ConsoleAction { file: string; module: string; change: "add" | "replace" | "unchanged" | "remove" | "none" | "refused"; reason?: string }
|
|
18
|
-
export interface SetupReport { mode: SetupMode; applied: boolean; entry: McpEntry; root?: InstallRoot; actions: SetupAction[]; console?: ConsoleAction; notes: string[] }
|
|
20
|
+
export interface SetupReport { mode: SetupMode; applied: boolean; entry: McpEntry; root?: InstallRoot; actions: SetupAction[]; console?: ConsoleAction; skills?: { target: SetupTarget; report?: SkillInstallReport; reason?: string; refused?: boolean }[]; notes: string[] }
|
|
19
21
|
export interface InstallRoot { path: string; version: string }
|
|
20
22
|
interface Receipt { version: 1; target: SetupTarget; file: string; existed: boolean; keyExisted?: boolean; prior: unknown; priorToml?: string[]; installed: McpEntry }
|
|
21
23
|
|
|
@@ -251,7 +253,7 @@ export function runSetup(target: string, mode: SetupMode, options: { home: strin
|
|
|
251
253
|
if (!isAbsolute(entry.command) || entry.args.some(arg => arg.includes("\0"))) throw new Error("setup: MCP command must be absolute");
|
|
252
254
|
const table = hosts(env, options.cwd ?? process.cwd());
|
|
253
255
|
const targets = target === "all" ? SETUP_TARGETS.filter(t => t !== "agy") : [target as SetupTarget];
|
|
254
|
-
const report: SetupReport = { mode, applied: false, entry, ...(root ? { root } : {}), actions: [], notes: [
|
|
256
|
+
const report: SetupReport = { mode, applied: false, entry, ...(root ? { root } : {}), actions: [], skills: [], notes: [
|
|
255
257
|
"Registers the stdio server `vmem mcp`; restart the host session to load it.",
|
|
256
258
|
"Writes the acon console plugin manifest ($AGENTHUB_HOME/console/plugins/vmem.json); re-run setup after upgrading vmem.",
|
|
257
259
|
] };
|
|
@@ -298,8 +300,15 @@ export function runSetup(target: string, mode: SetupMode, options: { home: strin
|
|
|
298
300
|
action.change = "refused"; action.reason = error instanceof Error ? error.message : "setup failed";
|
|
299
301
|
}
|
|
300
302
|
}
|
|
303
|
+
for (const name of targets) {
|
|
304
|
+
try {
|
|
305
|
+
const path = skillRoot(name, env);
|
|
306
|
+
if (!path) { report.skills!.push({ target: name, reason: "skills are not installed for this host; use vmem skills export <dir>" }); continue; }
|
|
307
|
+
report.skills!.push({ target: name, report: installSkills(path, mode, root?.path, root?.version, ["vmem", "setup", name, ...(root ? ["--root", root.path] : []), mode === "undo" ? "--undo" : "--apply"].map(shellWord).join(" ")) });
|
|
308
|
+
} catch (error) { report.skills!.push({ target: name, refused: true, reason: error instanceof Error ? error.message : "skill setup failed; inspect the host configuration" }); }
|
|
309
|
+
}
|
|
301
310
|
report.console = consoleManifest(mode, env, root?.path);
|
|
302
|
-
report.applied = mode !== "dry-run" && [...report.actions, report.console].some(a => !["none", "unchanged", "refused"].includes(a.change));
|
|
311
|
+
report.applied = mode !== "dry-run" && ([...report.actions, report.console].some(a => !["none", "unchanged", "refused"].includes(a.change)) || report.skills!.some(s => s.report?.actions.some(a => ["install", "replace", "remove"].includes(a.change))));
|
|
303
312
|
return report;
|
|
304
313
|
}
|
|
305
314
|
|
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
/** Install package-owned skills without replacing foreign or locally modified trees. */
|
|
2
|
+
import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, opendirSync, readSync, realpathSync, rmSync, writeFileSync, type Stats } from "node:fs";
|
|
3
|
+
import { createHash, randomUUID } from "node:crypto";
|
|
4
|
+
import { isAbsolute, join, relative, resolve, sep } from "node:path";
|
|
5
|
+
import { homedir } from "node:os";
|
|
6
|
+
import { fileURLToPath } from "node:url";
|
|
7
|
+
import { dlopen, FFIType, ptr } from "bun:ffi";
|
|
8
|
+
import { version } from "../package.json";
|
|
9
|
+
import type { SetupMode, SetupTarget } from "./setup.ts";
|
|
10
|
+
import { shellWord } from "./text-output.ts";
|
|
11
|
+
|
|
12
|
+
export const SKILL_NAMES = ["vault-connect", "vault-extract", "vault-graph", "vault-learn", "vault-lint", "vault-refactor", "vault-remember", "vault-rethink", "vault-stats", "vault-sync", "vault-update", "vmem-status", "skill-mine"] as const;
|
|
13
|
+
const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
|
|
14
|
+
const MARKER = ".vmem-skill.json", MAX_FILE = 2 * 1024 * 1024, MAX_BYTES = 16 * 1024 * 1024, MAX_FILES = 512;
|
|
15
|
+
export interface SkillAction { name: string; path: string; change: "install" | "replace" | "remove" | "unchanged" | "absent" | "modified" | "foreign" | "refused"; reason?: string }
|
|
16
|
+
export interface SkillInstallReport { root: string; actions: SkillAction[] }
|
|
17
|
+
interface Marker { tool: "vmem"; version: string; sha256: string }
|
|
18
|
+
type Files = Map<string, Uint8Array>;
|
|
19
|
+
function safePath(root: string, path: string): boolean { const rel = relative(root, path); return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel); }
|
|
20
|
+
function boundedFile(file: string, remaining: number): Uint8Array {
|
|
21
|
+
let fd: number;
|
|
22
|
+
try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
|
|
23
|
+
catch { throw new Error("skill file is missing, unreadable or linked; inspect the skill directory"); }
|
|
24
|
+
try {
|
|
25
|
+
const before = fstatSync(fd);
|
|
26
|
+
if (!before.isFile() || before.size > MAX_FILE || before.size > remaining) throw new Error("skill file exceeds its read bound or is not regular; inspect the skill directory");
|
|
27
|
+
const bytes = Buffer.alloc(before.size + 1); let length = 0;
|
|
28
|
+
while (length < bytes.length) { const n = readSync(fd, bytes, length, bytes.length - length, null); if (!n) break; length += n; }
|
|
29
|
+
const after = fstatSync(fd), named = lstatSync(file);
|
|
30
|
+
if (named.isSymbolicLink() || before.dev !== after.dev || before.ino !== after.ino || after.dev !== named.dev || after.ino !== named.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || length !== before.size) throw new Error("skill file changed during inspection; stop concurrent edits and retry");
|
|
31
|
+
return bytes.subarray(0, length);
|
|
32
|
+
} finally { closeSync(fd); }
|
|
33
|
+
}
|
|
34
|
+
function walk(root: string): Files {
|
|
35
|
+
const files: Files = new Map(); let total = 0, count = 0;
|
|
36
|
+
const visit = (dir: string) => {
|
|
37
|
+
const stat = lstatSync(dir);
|
|
38
|
+
if (!stat.isDirectory() || stat.isSymbolicLink() || realpathSync(dir) !== dir) throw new Error("skill contains a linked or non-directory path; inspect the skill directory");
|
|
39
|
+
const entries = opendirSync(dir); let children = 0;
|
|
40
|
+
try {
|
|
41
|
+
let entry: ReturnType<typeof entries.readSync>;
|
|
42
|
+
while ((entry = entries.readSync()) !== null) {
|
|
43
|
+
if (++count > MAX_FILES) throw new Error("skill contains too many entries; inspect the skill directory");
|
|
44
|
+
const path = join(dir, entry.name), rel = relative(root, path).split(sep).join("/");
|
|
45
|
+
if (!safePath(root, path) || entry.name === "." || entry.name === "..") throw new Error("skill contains an unsafe path; inspect the skill directory");
|
|
46
|
+
if (rel === MARKER) continue;
|
|
47
|
+
children++;
|
|
48
|
+
if (entry.isDirectory()) visit(path);
|
|
49
|
+
else if (entry.isFile()) { const data = boundedFile(path, MAX_BYTES - total); total += data.length; files.set(rel, data); }
|
|
50
|
+
else throw new Error("skill contains a link or special file; inspect the skill directory");
|
|
51
|
+
}
|
|
52
|
+
} finally { entries.closeSync(); }
|
|
53
|
+
if (dir !== root && children === 0) throw new Error("skill contains an unexpected empty directory; inspect the skill directory");
|
|
54
|
+
const after = lstatSync(dir);
|
|
55
|
+
if (!identical(stat, after) || realpathSync(dir) !== dir) throw new Error("skill directory changed during inspection; stop concurrent edits and retry");
|
|
56
|
+
};
|
|
57
|
+
visit(root); return files;
|
|
58
|
+
}
|
|
59
|
+
function digest(files: Files): string {
|
|
60
|
+
const hash = createHash("sha256");
|
|
61
|
+
for (const [name, data] of [...files].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) { hash.update(`${Buffer.byteLength(name)}:${name}:${data.length}:`); hash.update(data); }
|
|
62
|
+
return hash.digest("hex");
|
|
63
|
+
}
|
|
64
|
+
function packaged(name: string, packageRoot: string): Files {
|
|
65
|
+
const root = join(packageRoot, "skills", name);
|
|
66
|
+
let files: Files, adapter: Uint8Array;
|
|
67
|
+
try { files = walk(root); adapter = boundedFile(join(packageRoot, "skills", "_shared", "vault-adapter.md"), MAX_FILE); }
|
|
68
|
+
catch (error) { throw new Error(`packaged skill ${name} is unavailable or invalid; reinstall a complete vmem package`, { cause: error }); }
|
|
69
|
+
if (!files.has("SKILL.md") || files.has("references/vault-adapter.md")) throw new Error("packaged skill is missing its entry or contains a conflicting adapter; reinstall vmem");
|
|
70
|
+
files.set("references/vault-adapter.md", adapter);
|
|
71
|
+
const dirs = new Set<string>(); let bytes = 0;
|
|
72
|
+
for (const [name, data] of files) {
|
|
73
|
+
bytes += data.length;
|
|
74
|
+
const parts = name.split("/"); for (let i = 1; i < parts.length; i++) dirs.add(parts.slice(0, i).join("/"));
|
|
75
|
+
}
|
|
76
|
+
if (bytes > MAX_BYTES || files.size + dirs.size + 1 > MAX_FILES) throw new Error("packaged skill with its adapter exceeds installation bounds; reinstall a valid vmem package");
|
|
77
|
+
return files;
|
|
78
|
+
}
|
|
79
|
+
function marker(path: string): Marker | undefined {
|
|
80
|
+
try {
|
|
81
|
+
const data: unknown = JSON.parse(Buffer.from(boundedFile(join(path, MARKER), 4096)).toString("utf8"));
|
|
82
|
+
if (!data || typeof data !== "object" || Array.isArray(data)) return undefined;
|
|
83
|
+
const m = data as Record<string, unknown>;
|
|
84
|
+
return Object.keys(m).sort().join(",") === "sha256,tool,version" && m.tool === "vmem" && typeof m.version === "string" && m.version.length <= 128 && typeof m.sha256 === "string" && /^[a-f0-9]{64}$/.test(m.sha256) ? m as unknown as Marker : undefined;
|
|
85
|
+
} catch { return undefined; }
|
|
86
|
+
}
|
|
87
|
+
/** Atomic no-replace and directory exchange. Unsupported kernels or filesystems are refused. */
|
|
88
|
+
function renameAtomic(from: string, to: string, exchange: boolean): void {
|
|
89
|
+
if (process.platform !== "linux" && process.platform !== "darwin") throw new Error("atomic skill rename is unsupported on this platform; use vmem skills export on a supported host");
|
|
90
|
+
const fromBytes = Buffer.alloc(Buffer.byteLength(from) + 1), toBytes = Buffer.alloc(Buffer.byteLength(to) + 1);
|
|
91
|
+
fromBytes.write(from); toBytes.write(to);
|
|
92
|
+
let result: number;
|
|
93
|
+
try {
|
|
94
|
+
if (process.platform === "darwin") {
|
|
95
|
+
const lib = dlopen("/usr/lib/libSystem.B.dylib", { renamex_np: { args: [FFIType.ptr, FFIType.ptr, FFIType.u32], returns: FFIType.i32 } });
|
|
96
|
+
try { result = lib.symbols.renamex_np(ptr(fromBytes), ptr(toBytes), exchange ? 2 : 4); } finally { lib.close(); }
|
|
97
|
+
} else {
|
|
98
|
+
const lib = dlopen("libc.so.6", { renameat2: { args: [FFIType.i32, FFIType.ptr, FFIType.i32, FFIType.ptr, FFIType.u32], returns: FFIType.i32 } });
|
|
99
|
+
try { result = lib.symbols.renameat2(-100, ptr(fromBytes), -100, ptr(toBytes), exchange ? 2 : 1); } finally { lib.close(); }
|
|
100
|
+
}
|
|
101
|
+
} catch (error) { throw new Error("atomic skill rename is unavailable; inspect platform and filesystem support before retrying", { cause: error }); }
|
|
102
|
+
if (result !== 0) throw new Error("atomic skill rename failed or target changed; inspect the skill root and retry on a supported filesystem");
|
|
103
|
+
}
|
|
104
|
+
function identical(a: Stats, b: Stats): boolean { return a.dev === b.dev && a.ino === b.ino && a.isDirectory() && b.isDirectory() && !a.isSymbolicLink() && !b.isSymbolicLink(); }
|
|
105
|
+
function stage(root: string, files: Files, digestValue: string, packageVersion: string): string {
|
|
106
|
+
const dir = join(root, `.vmem-skill-${randomUUID()}`); mkdirSync(dir, { mode: 0o700 });
|
|
107
|
+
try {
|
|
108
|
+
for (const [name, bytes] of files) {
|
|
109
|
+
const file = join(dir, name); if (!safePath(dir, file)) throw new Error("packaged skill has an unsafe path; reinstall vmem");
|
|
110
|
+
mkdirSync(join(file, ".."), { recursive: true, mode: 0o700 }); writeFileSync(file, bytes, { flag: "wx", mode: 0o600 });
|
|
111
|
+
}
|
|
112
|
+
writeFileSync(join(dir, MARKER), JSON.stringify({ tool: "vmem", version: packageVersion, sha256: digestValue }) + "\n", { flag: "wx", mode: 0o600 });
|
|
113
|
+
return dir;
|
|
114
|
+
} catch (error) { rmSync(dir, { recursive: true, force: true }); throw error; }
|
|
115
|
+
}
|
|
116
|
+
function existingRoot(path: string): string | undefined {
|
|
117
|
+
try { const info = lstatSync(path); if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("skill root is linked or not a directory; choose a real directory"); return realpathSync(path); }
|
|
118
|
+
catch (error) {
|
|
119
|
+
if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
|
|
120
|
+
if (error instanceof Error && error.message.startsWith("skill root is linked")) throw error;
|
|
121
|
+
throw new Error("skill root cannot be inspected; check its path and permissions", { cause: error });
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
/** Re-walk a moved-aside tree and delete it only while it still matches `sha`; false keeps it for inspection. */
|
|
125
|
+
function removeVerified(path: string, sha: string): boolean {
|
|
126
|
+
try { if (digest(walk(path)) !== sha) return false; rmSync(path, { recursive: true }); return true; }
|
|
127
|
+
catch { return false; }
|
|
128
|
+
}
|
|
129
|
+
/** Plan or install one complete skill tree per name. `root` must be an absolute target directory. */
|
|
130
|
+
export function installSkills(root: string, mode: SetupMode, packageRoot = PACKAGE_ROOT, packageVersion = version, retryCommand = ["vmem", "skills", "export", root].map(shellWord).join(" ")): SkillInstallReport {
|
|
131
|
+
if (!isAbsolute(root)) throw new Error("skills: target must be absolute; provide an absolute skill root");
|
|
132
|
+
if (mode !== "undo" && (typeof packageVersion !== "string" || !packageVersion.trim() || Buffer.byteLength(packageVersion) > 128 || /[\p{Cc}\p{Zl}\p{Zp}]/u.test(packageVersion))) throw new Error("skills: package version is invalid; reinstall a valid vmem package");
|
|
133
|
+
const requested = resolve(root), actions: SkillAction[] = [];
|
|
134
|
+
let actual = existingRoot(requested);
|
|
135
|
+
if (!actual && mode !== "dry-run" && mode !== "undo") { mkdirSync(requested, { recursive: true, mode: 0o700 }); actual = existingRoot(requested); }
|
|
136
|
+
if (!actual && mode === "apply") throw new Error("skills: target directory could not be created; inspect the target and retry");
|
|
137
|
+
for (const name of SKILL_NAMES) {
|
|
138
|
+
const target = join(actual ?? requested, name), action: SkillAction = { name, path: target, change: "absent" }; actions.push(action);
|
|
139
|
+
try {
|
|
140
|
+
let before: Stats | undefined;
|
|
141
|
+
try { before = lstatSync(target); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
|
|
142
|
+
if (before && (!before.isDirectory() || before.isSymbolicLink())) { action.change = "foreign"; action.reason = mode === "undo" ? `not a vmem-owned real directory; left untouched. Remove it by hand or keep it` : `not a vmem-owned real directory; left untouched. Remove or relocate it and rerun ${retryCommand} to let vmem manage it, or keep it`; continue; }
|
|
143
|
+
const own = before ? marker(target) : undefined;
|
|
144
|
+
if (before && !own) { action.change = "foreign"; action.reason = mode === "undo" ? `ownership marker missing or invalid; left untouched. Remove it by hand or keep it` : `ownership marker missing or invalid; left untouched. Remove or relocate it and rerun ${retryCommand} to let vmem manage it, or keep it`; continue; }
|
|
145
|
+
if (before && own) {
|
|
146
|
+
let current: string;
|
|
147
|
+
try { current = digest(walk(target)); } catch { action.change = "modified"; action.reason = mode === "undo" ? `contents cannot be safely verified; left untouched. Remove it by hand, or restore it and rerun ${retryCommand}` : `contents cannot be safely verified; left untouched. Inspect or remove it and rerun ${retryCommand}, or keep it`; continue; }
|
|
148
|
+
if (current !== own.sha256) { action.change = "modified"; action.reason = mode === "undo" ? `contents differ from the ownership marker; left untouched. Remove it by hand, or restore it and rerun ${retryCommand}` : `contents differ from the ownership marker; left untouched. Restore or remove it and rerun ${retryCommand}, or keep the local edit`; continue; }
|
|
149
|
+
}
|
|
150
|
+
if (mode === "undo") {
|
|
151
|
+
if (!before) continue;
|
|
152
|
+
action.change = "remove";
|
|
153
|
+
const moved = join(actual!, `.vmem-skill-${randomUUID()}`);
|
|
154
|
+
renameAtomic(target, moved, false);
|
|
155
|
+
let verified = false;
|
|
156
|
+
try { verified = identical(before, lstatSync(moved)) && digest(walk(moved)) === own!.sha256; } catch { /* Restore an unverifiable tree. */ }
|
|
157
|
+
if (!verified) {
|
|
158
|
+
try { renameAtomic(moved, target, false); }
|
|
159
|
+
catch { throw new Error(`skill changed during undo; inspect ${target} and ${moved} and restore the original manually`); }
|
|
160
|
+
throw new Error("skill changed during undo; inspect the skill root before retrying");
|
|
161
|
+
}
|
|
162
|
+
if (!removeVerified(moved, own!.sha256)) action.reason = `removed but the moved-aside tree changed before deletion or cleanup failed; inspect ${moved} before retrying`;
|
|
163
|
+
continue;
|
|
164
|
+
}
|
|
165
|
+
const files = packaged(name, packageRoot), sha = digest(files);
|
|
166
|
+
if (before && own?.sha256 === sha && own.version === packageVersion) { action.change = "unchanged"; continue; }
|
|
167
|
+
action.change = before ? "replace" : "install";
|
|
168
|
+
if (mode === "dry-run") continue;
|
|
169
|
+
const temp = stage(actual!, files, sha, packageVersion), staged = lstatSync(temp);
|
|
170
|
+
let preserve = false, published = false;
|
|
171
|
+
try {
|
|
172
|
+
if (!before) { renameAtomic(temp, target, false); published = true; }
|
|
173
|
+
else {
|
|
174
|
+
if (!identical(before, lstatSync(target))) throw new Error("skill changed before replacement; inspect it and retry");
|
|
175
|
+
renameAtomic(temp, target, true); published = true;
|
|
176
|
+
let verified = false;
|
|
177
|
+
try { verified = identical(before, lstatSync(temp)) && digest(walk(temp)) === own!.sha256 && identical(staged, lstatSync(target)); } catch { /* Restore an unverifiable tree. */ }
|
|
178
|
+
if (!verified) {
|
|
179
|
+
try { if (!identical(staged, lstatSync(target))) throw new Error("target changed"); renameAtomic(temp, target, true); published = false; }
|
|
180
|
+
catch { preserve = true; }
|
|
181
|
+
// The swap-back failed with the new tree published: neither tree is known good, so this is a failure.
|
|
182
|
+
if (published) { action.change = "refused"; action.reason = `replacement outcome needs inspection; inspect ${target} and ${temp} before retrying`; continue; }
|
|
183
|
+
throw new Error("skill changed during replacement; inspect it and retry");
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
} finally {
|
|
187
|
+
if (!preserve) {
|
|
188
|
+
// The moved-aside old tree is deleted only if it still matches its marker right before removal.
|
|
189
|
+
if (published && before) { if (!removeVerified(temp, own!.sha256)) action.reason = `installed, but the previous tree changed before deletion or cleanup failed; inspect ${temp}`; }
|
|
190
|
+
else try { rmSync(temp, { recursive: true, force: true }); }
|
|
191
|
+
catch (error) { if (published) action.reason = `installed but cleanup failed; inspect ${temp}`; else throw error; }
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
} catch (error) { action.change = "refused"; action.reason = error instanceof Error ? error.message : "skill operation failed; inspect the skill root and retry"; }
|
|
195
|
+
}
|
|
196
|
+
return { root: actual ?? requested, actions };
|
|
197
|
+
}
|
|
198
|
+
export function skillRoot(target: SetupTarget, env: NodeJS.ProcessEnv): string | undefined {
|
|
199
|
+
const map: Partial<Record<SetupTarget, [string, string]>> = { claude: ["CLAUDE_CONFIG_DIR", ".claude"], codex: ["CODEX_HOME", ".codex"], kimi: ["KIMI_CODE_HOME", ".kimi-code"], qwen: ["QWEN_HOME", ".qwen"] };
|
|
200
|
+
const spec = map[target]; if (!spec) return undefined;
|
|
201
|
+
const value = env[spec[0]]?.trim(), home = env.HOME?.trim() || homedir();
|
|
202
|
+
if (value && !isAbsolute(value)) throw new Error(`setup: ${spec[0]} must be absolute; set an absolute host configuration directory`);
|
|
203
|
+
return join(value ? resolve(value) : join(home, spec[1]), "skills");
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
/** Export into a dedicated directory. Unknown entries mean it is not a vmem export root. */
|
|
207
|
+
export function exportSkills(destination: string): SkillInstallReport {
|
|
208
|
+
if (typeof destination !== "string" || !destination.trim() || /[\p{Cc}\p{Zl}\p{Zp}]/u.test(destination)) throw new Error("skills export: destination is missing or invalid; choose a directory path");
|
|
209
|
+
const root = resolve(destination), existing = existingRoot(root);
|
|
210
|
+
if (existing) {
|
|
211
|
+
const entries = opendirSync(existing);
|
|
212
|
+
try { let entry: ReturnType<typeof entries.readSync>; while ((entry = entries.readSync()) !== null) if (!(SKILL_NAMES as readonly string[]).includes(entry.name)) throw new Error("skills export: destination contains foreign entries; choose an empty directory or an existing vmem export"); }
|
|
213
|
+
finally { entries.closeSync(); }
|
|
214
|
+
}
|
|
215
|
+
return installSkills(root, "apply");
|
|
216
|
+
}
|