@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.
Files changed (60) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +17 -2
  3. package/bin/vmem.js +5 -1
  4. package/package.json +2 -1
  5. package/skills/_shared/vault-adapter.md +131 -0
  6. package/skills/skill-mine/SKILL.md +52 -0
  7. package/skills/skill-mine/vocab/actions.yaml +110 -0
  8. package/skills/skill-mine/vocab/objects.yaml +123 -0
  9. package/skills/vault-connect/SKILL.md +75 -0
  10. package/skills/vault-extract/README.md +20 -0
  11. package/skills/vault-extract/SKILL.md +139 -0
  12. package/skills/vault-graph/SKILL.md +120 -0
  13. package/skills/vault-learn/SKILL.md +111 -0
  14. package/skills/vault-lint/README.md +32 -0
  15. package/skills/vault-lint/SKILL.md +137 -0
  16. package/skills/vault-lint/references/lint-output.md +97 -0
  17. package/skills/vault-lint/references/vault-scope-rules.md +26 -0
  18. package/skills/vault-lint/references/work-scope-checks.md +71 -0
  19. package/skills/vault-refactor/SKILL.md +112 -0
  20. package/skills/vault-remember/SKILL.md +38 -0
  21. package/skills/vault-rethink/README.md +15 -0
  22. package/skills/vault-rethink/SKILL.md +58 -0
  23. package/skills/vault-stats/SKILL.md +49 -0
  24. package/skills/vault-sync/README.md +15 -0
  25. package/skills/vault-sync/SKILL.md +195 -0
  26. package/skills/vault-sync/references/r4-method-evidence.md +12 -0
  27. package/skills/vault-update/SKILL.md +68 -0
  28. package/skills/vmem-status/SKILL.md +30 -0
  29. package/src/amem/host-api.ts +5 -1
  30. package/src/analysis-input.ts +15 -0
  31. package/src/analysis-types.ts +3 -1
  32. package/src/assertion-policy.ts +4 -2
  33. package/src/assertions.ts +48 -8
  34. package/src/cli-output.ts +10 -3
  35. package/src/cli.ts +29 -3
  36. package/src/commands-table.ts +3 -1
  37. package/src/config.ts +21 -7
  38. package/src/enrichment-query.ts +65 -0
  39. package/src/enrichment-search.ts +69 -0
  40. package/src/enrichment-store.ts +197 -0
  41. package/src/enrichment.ts +245 -0
  42. package/src/graph-evidence.ts +2 -2
  43. package/src/index.ts +9 -0
  44. package/src/mcp-vault.ts +46 -8
  45. package/src/proposal-provider.ts +3 -2
  46. package/src/proposals.ts +10 -4
  47. package/src/read-output.ts +1 -1
  48. package/src/registry.ts +57 -2
  49. package/src/setup.ts +12 -3
  50. package/src/skills-install.ts +216 -0
  51. package/src/ui/panel-types.ts +55 -0
  52. package/src/ui/panel.js +76 -0
  53. package/src/ui/plugin.ts +95 -5
  54. package/src/vault-graph.ts +15 -7
  55. package/src/vault-index.ts +17 -0
  56. package/src/vault-lint.ts +12 -4
  57. package/src/write-operations.ts +38 -1
  58. package/src/write-types.ts +1 -0
  59. package/src/write-validation.ts +2 -1
  60. 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 or exact-patch proposal without modifying vault notes or the log. Agent labels are unverified.", object({ vault, operation: proposalOperation, agentLabel: string(256) }, ["operation"]), "write"),
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 => read(args, index => ({ hits: index.search(str(args.query)!, { limit: (args.limit as number | undefined) ?? 20, type: str(args.type), domain: str(args.domain) }) })),
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)!,
@@ -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
- /** Only create and exact-replacement patch operations are admissible, with one canonical flat note target. */
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: expected one create or patch operation and note target");
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
- throw new Error("proposal: unsupported operation; choose create or patch");
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. */
@@ -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
+ }