@staix/vault-mem 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/CHANGELOG.md +66 -0
  2. package/README.md +140 -23
  3. package/package.json +5 -4
  4. package/src/amem/seam.ts +15 -6
  5. package/src/analysis-commands.ts +1 -1
  6. package/src/analysis-input.ts +24 -3
  7. package/src/analysis-reports.ts +1 -1
  8. package/src/analysis-types.ts +13 -1
  9. package/src/canon-tables.ts +190 -0
  10. package/src/cli-output.ts +15 -1
  11. package/src/cli.ts +1 -1
  12. package/src/commands-table.ts +6 -2
  13. package/src/config.ts +31 -3
  14. package/src/frontmatter.ts +10 -3
  15. package/src/links.ts +13 -1
  16. package/src/mcp-spec.ts +19 -11
  17. package/src/mcp-vault.ts +14 -9
  18. package/src/mcp.ts +4 -2
  19. package/src/org-promote.ts +29 -12
  20. package/src/promote.ts +24 -12
  21. package/src/read-commands.ts +1 -2
  22. package/src/read-output.ts +7 -5
  23. package/src/registry.ts +1 -0
  24. package/src/skills-mine.ts +5 -4
  25. package/src/spec-command-table.ts +10 -1
  26. package/src/spec-commands.ts +7 -3
  27. package/src/spec-gitlinks.ts +106 -0
  28. package/src/spec-output.ts +30 -0
  29. package/src/spec-source.ts +9 -3
  30. package/src/spec-validate.ts +6 -3
  31. package/src/spec-write.ts +469 -0
  32. package/src/ui/inbox-source.ts +46 -0
  33. package/src/ui/inbox-worker.ts +8 -0
  34. package/src/ui/inbox.ts +152 -0
  35. package/src/ui/panel.js +26 -5
  36. package/src/ui/plugin.ts +42 -65
  37. package/src/ui/snapshot-cache.ts +123 -0
  38. package/src/vault-index.ts +109 -19
  39. package/src/vault-lint.ts +53 -5
  40. package/src/vault-log.ts +3 -2
  41. package/src/vault-stats.ts +110 -5
  42. package/src/write-commands.ts +4 -3
  43. package/src/write-files.ts +63 -0
  44. package/src/write-operations.ts +175 -25
  45. package/src/write-output.ts +20 -9
  46. package/src/write-types.ts +8 -1
  47. package/src/write-validation.ts +46 -17
  48. package/src/writer.ts +137 -41
  49. package/src/yaml-quoted.ts +12 -2
@@ -1,4 +1,5 @@
1
1
  import { isDeepStrictEqual } from "node:util";
2
+ import { createSpec, deleteSpec, updateSpec, type SpecCreateRequest, type SpecDeleteRequest, type SpecUpdateRequest, type SpecWriteOptions } from "./spec-write.ts";
2
3
  import { argumentError } from "./mcp.ts";
3
4
  import { specCommandSchema, type SpecCommand } from "./spec-command-table.ts";
4
5
  import { loadRegistry } from "./registry.ts";
@@ -108,11 +109,14 @@ function grep(index: SpecIndex, snapshot: SpecSnapshot, args: Record<string, unk
108
109
  return result;
109
110
  }
110
111
 
111
- /** Shared read-only provider for CLI and MCP; caches may be derived outside all registered sources. */
112
- export function executeSpecCommand(home: string, command: SpecCommand, args: Record<string, unknown>, env: NodeJS.ProcessEnv = process.env): unknown {
113
- if (!["get", "graph", "grep", "validate"].includes(command)) throw new Error("spec provider: unknown command; choose get, graph, grep or validate");
112
+ /** Shared provider for CLI and MCP; read caches and mutation locks stay outside registered sources. */
113
+ export function executeSpecCommand(home: string, command: SpecCommand, args: Record<string, unknown>, env: NodeJS.ProcessEnv = process.env, options: Pick<SpecWriteOptions, "channel" | "binding"> = {}): unknown {
114
+ if (!["get", "graph", "grep", "validate", "create", "update", "delete"].includes(command)) throw new Error("spec provider: unknown command; choose get, graph, grep, validate, create, update or delete");
114
115
  const invalid = argumentError(args, specCommandSchema(command));
115
116
  if (invalid) throw new Error(`spec ${command}: ${invalid}; use vmem spec ${command} --help to correct the arguments`);
117
+ if (command === "update") return updateSpec(home, args as unknown as SpecUpdateRequest, { env, ...options });
118
+ if (command === "create") return createSpec(home, args as unknown as SpecCreateRequest, { env, ...options });
119
+ if (command === "delete") return deleteSpec(home, args as unknown as SpecDeleteRequest, { env, ...options });
116
120
  if (command === "grep") for (const field of ["parent", "dependsOn"] as const) {
117
121
  if (args[field] !== undefined && specReference(args[field]) === undefined) throw new Error(`spec grep: ${field} filter resolves to no id; pass an id or [[id]]`);
118
122
  }
@@ -0,0 +1,106 @@
1
+ import { spawn, spawnSync, type SpawnSyncOptions } from "node:child_process";
2
+ import { join } from "node:path";
3
+ import { fileURLToPath } from "node:url";
4
+ import { canonicalPath, memoryGitArgv, memoryGitEnv } from "./platform.ts";
5
+
6
+ export interface GitlinkScan { matched: boolean; bytes: number; records: number }
7
+ interface ScanLimits { bytes: number; records: number; recordBytes: number; timeout: number }
8
+ const LIMITS: ScanLimits = { bytes: 128 * 1024 * 1024, records: 1_000_000, recordBytes: 64 * 1024, timeout: 10_000 };
9
+ const key = (value: string) => canonicalPath(value).normalize("NFC").toLowerCase();
10
+ const advice = "inspect git ls-files --stage for an oversized or slow index, reduce or repair index entries, then retry the create";
11
+ function failure(code: "LIMIT" | "IO", message: string): Error & { code: string } { return Object.assign(new Error(message), { code }); }
12
+
13
+ /** Stream the native index, retaining one bounded record and only the ancestor match. */
14
+ export function scanGitlinkAncestors(root: string, ancestors: string[], env: NodeJS.ProcessEnv, limits: ScanLimits = LIMITS): Promise<GitlinkScan> {
15
+ const keys = new Set(ancestors.map(ancestor => key(join(root, ancestor))));
16
+ const argv = memoryGitArgv(["-C", root, "ls-files", "--stage", "-z"]);
17
+ const gitEnv = memoryGitEnv({ ...env, GIT_OPTIONAL_LOCKS: "0", LC_ALL: "C" }, { repositoryIsolation: true });
18
+ return new Promise((resolve, reject) => {
19
+ const child = spawn(argv[0]!, argv.slice(1), { env: gitEnv, stdio: ["ignore", "pipe", "pipe"] });
20
+ const result: GitlinkScan = { matched: false, bytes: 0, records: 0 };
21
+ let pending = Buffer.alloc(0), diagnostic = "", error: Error | undefined;
22
+ const stop = (cause: Error) => { if (!error) { error = cause; child.kill("SIGKILL"); } };
23
+ const timer = setTimeout(() => stop(failure("LIMIT", `gitlink index scan exceeded its ${limits.timeout} ms time bound; ${advice}`)), limits.timeout);
24
+ child.on("error", cause => stop(failure("IO", `gitlink index scan could not start (${(cause as NodeJS.ErrnoException).code ?? "spawn failure"}); check Git installation and PATH before retrying the create`)));
25
+ child.stdout.on("error", cause => stop(failure("IO", `gitlink index stream failed (${(cause as NodeJS.ErrnoException).code ?? "read failure"}); inspect repository access and retry the create`)));
26
+ child.stderr.on("error", cause => stop(failure("IO", `gitlink diagnostic stream failed (${(cause as NodeJS.ErrnoException).code ?? "read failure"}); inspect repository access and retry the create`)));
27
+ child.stderr.on("data", (chunk: Buffer) => { if (diagnostic.length < 1024) diagnostic += chunk.subarray(0, 1024 - diagnostic.length).toString("utf8"); });
28
+ child.stdout.on("data", (chunk: Buffer) => {
29
+ if (error) return;
30
+ result.bytes += chunk.length;
31
+ if (result.bytes > limits.bytes) return stop(failure("LIMIT", `gitlink index scan exceeded its ${limits.bytes}-byte index bound; ${advice}`));
32
+ const data = pending.length ? Buffer.concat([pending, chunk]) : chunk;
33
+ let start = 0, end: number;
34
+ while ((end = data.indexOf(0, start)) !== -1) {
35
+ if (end - start > limits.recordBytes) return stop(failure("LIMIT", `gitlink index record exceeded its ${limits.recordBytes}-byte bound; ${advice}`));
36
+ if (++result.records > limits.records) return stop(failure("LIMIT", `gitlink index scan exceeded its ${limits.records}-entry index bound; ${advice}`));
37
+ const entry = data.subarray(start, end);
38
+ if (entry.subarray(0, 7).toString() === "160000 ") {
39
+ const tab = entry.indexOf(9);
40
+ if (tab < 0) return stop(failure("IO", "gitlink index record has no path separator; repair the Git index and retry the create"));
41
+ if (keys.has(key(join(root, entry.subarray(tab + 1).toString("utf8"))))) result.matched = true;
42
+ }
43
+ start = end + 1;
44
+ }
45
+ pending = Buffer.from(data.subarray(start));
46
+ if (pending.length > limits.recordBytes) stop(failure("LIMIT", `gitlink index record exceeded its ${limits.recordBytes}-byte bound; ${advice}`));
47
+ });
48
+ child.on("close", (status, signal) => {
49
+ clearTimeout(timer);
50
+ if (error) return reject(error);
51
+ if (status !== 0) return reject(failure("IO", `gitlink index scan failed (exit ${status ?? "unavailable"}, signal ${signal ?? "none"}): ${diagnostic.split(/\r?\n/, 1)[0]?.split(root).join("<path>") || "no diagnostic"}; inspect git ls-files --stage and repair repository access or the index before retrying the create`));
52
+ if (pending.length) return reject(failure("IO", "gitlink index stream ended with an incomplete record; repair the Git index and retry the create"));
53
+ resolve(result);
54
+ });
55
+ });
56
+ }
57
+
58
+ /** Keep the synchronous writer API; the child drains Git asynchronously and returns a compact receipt. */
59
+ export function specGitlinkAncestors(root: string, ancestors: string[], env: NodeJS.ProcessEnv): GitlinkScan {
60
+ // Bun supports detached for spawnSync; the owned-group timeout fixture pins it.
61
+ const options: SpawnSyncOptions & { detached: true } = { input: JSON.stringify(ancestors.at(-1) ?? ""), env, timeout: LIMITS.timeout + 5000, detached: true, maxBuffer: 16 * 1024, stdio: ["pipe", "pipe", "pipe"] };
62
+ const child = spawnSync(process.execPath, [fileURLToPath(import.meta.url), root], options);
63
+ // The worker owns this process group. Reap descendants even if its event loop
64
+ // could not run the inner timeout (for example during a slow filesystem call).
65
+ if (child.pid) {
66
+ try { process.kill(-child.pid, "SIGKILL"); }
67
+ catch (error) {
68
+ if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw failure("IO", `gitlink worker process-group cleanup failed (${(error as NodeJS.ErrnoException).code ?? "signal failure"}); inspect owned process group ${child.pid} and end its remaining Git processes before retrying the create`);
69
+ }
70
+ }
71
+ if (child.error) {
72
+ const code = (child.error as NodeJS.ErrnoException).code;
73
+ throw failure(code === "ETIMEDOUT" ? "LIMIT" : "IO", `gitlink scan worker failed (${code ?? "spawn failure"}); inspect runtime availability and the repository index, then retry the create`);
74
+ }
75
+ try {
76
+ const reply = JSON.parse(child.stdout.toString("utf8"));
77
+ if (child.status !== 0 || !reply || typeof reply.matched !== "boolean" || !Number.isSafeInteger(reply.bytes) || !Number.isSafeInteger(reply.records)) {
78
+ if (reply?.code === "LIMIT" || reply?.code === "IO") throw failure(reply.code, String(reply.message));
79
+ throw new Error("invalid worker receipt");
80
+ }
81
+ return reply as GitlinkScan;
82
+ } catch (error) {
83
+ if ((error as { code?: unknown })?.code) throw error;
84
+ throw failure("IO", "gitlink scan worker returned an invalid receipt; inspect the runtime installation and Git index before retrying the create");
85
+ }
86
+ }
87
+
88
+ if (import.meta.main) {
89
+ try {
90
+ const root = process.argv[2];
91
+ const chunks: Buffer[] = []; let size = 0;
92
+ for await (const chunk of process.stdin) {
93
+ size += chunk.length;
94
+ if (size > 1024 * 1024) throw failure("IO", "gitlink scan request exceeds its protocol size; check the runtime installation before retrying the create");
95
+ chunks.push(chunk);
96
+ }
97
+ const deepest: unknown = JSON.parse(Buffer.concat(chunks).toString("utf8"));
98
+ if (!root || typeof deepest !== "string") throw failure("IO", "gitlink scan request is invalid; check the runtime installation before retrying the create");
99
+ const parts = deepest.split("/");
100
+ const ancestors = deepest ? parts.map((_, index) => parts.slice(0, index + 1).join("/")) : [];
101
+ console.log(JSON.stringify(await scanGitlinkAncestors(root, ancestors, process.env)));
102
+ } catch (error) {
103
+ console.log(JSON.stringify({ code: (error as { code?: unknown })?.code === "LIMIT" ? "LIMIT" : "IO", message: error instanceof Error ? error.message : "gitlink scan failed; inspect the Git index before retrying the create" }));
104
+ process.exitCode = 1;
105
+ }
106
+ }
@@ -3,6 +3,7 @@
3
3
  * and never adds content to it; data goes through `clean()` in tables and fields, and bodies keep their lines with
4
4
  * terminal escape sequences stripped.
5
5
  */
6
+ import type { SpecDeleteResult, SpecWriteResult } from "./spec-write.ts";
6
7
  import type { SpecCommand } from "./spec-command-table.ts";
7
8
  import type { SpecEdge, SpecNode } from "./spec-graph.ts";
8
9
  import type { SpecFreshnessEntry } from "./spec-freshness.ts";
@@ -111,7 +112,36 @@ export function renderSpecValidate(r: SpecValidateResult, o: TextOptions, contex
111
112
  paint(verdict, r.ok ? "ok" : "fail", o)].filter(Boolean).join("\n"));
112
113
  }
113
114
 
115
+ /** A frontmatter mutation receipt shows the verdict and SHA without repeating authored content. */
116
+ function specWriteIssues(issues: SpecWriteResult["issues"], o: TextOptions): string | undefined {
117
+ return issueTable(issues.map(issue => ({ ...issue, message: [issue.message,
118
+ issue.target !== undefined ? `target: ${issue.target}` : undefined,
119
+ issue.originalTarget !== undefined ? `original target: ${issue.originalTarget}` : undefined].filter(Boolean).join("; ") })), o);
120
+ }
121
+ export function renderSpecUpdate(r: SpecWriteResult, o: TextOptions, command: "create" | "update" = "update"): string {
122
+ const applied = command === "create" ? "created" : "updated";
123
+ const verdict = r.changed ? r.ok ? applied : `${applied} with errors` : r.ok ? "unchanged" : "refused";
124
+ return blocks(heading(`spec ${command} ${r.id ?? ""}: ${verdict}`.trim(), o),
125
+ fields([["source", r.source], ["worktree", r.worktree], ["path", r.path], ["sha256", r.sha256], ["actor", r.actor]], o),
126
+ specWriteIssues(r.issues, o));
127
+ }
128
+
129
+ /** Deletion previews show every acknowledged relation and a command bound to that exact preview. */
130
+ export function renderSpecDelete(r: SpecDeleteResult, o: TextOptions): string {
131
+ const verdict = r.changed ? r.ok ? "deleted" : "deleted with errors" : !r.ok ? "refused" : r.preview ? "preview" : "unchanged";
132
+ const backlinks = r.backlinks ?? [], children = r.children ?? [];
133
+ const confirm = r.ok && r.preview && r.fingerprint && r.id !== undefined
134
+ ? ["vmem", "spec", "delete", ...(r.source ? ["--source", r.source] : []), ...(r.worktree ? ["--worktree", r.worktree] : []), "--confirm", "--fingerprint", r.fingerprint, "--", r.id].map(shellWord).join(" ") : undefined;
135
+ return blocks(heading(`spec delete ${r.id ?? ""}: ${verdict}`.trim(), o),
136
+ fields([["source", r.source], ["worktree", r.worktree], ["path", r.path], ["sha256", r.sha256], ["actor", r.actor], ["fingerprint", r.fingerprint]], o),
137
+ r.preview && (backlinks.length ? blocks(heading("Backlinks", o), table(["SOURCE", "EDGE", "TARGET"], backlinks.map(edge => [edge.source, edge.kind, edge.target]), o)) : paragraph("Backlinks: none", o)),
138
+ r.preview && (children.length ? blocks(heading("Children", o), table(["ID", "TYPE", "PATH", "TITLE"], children.map(child => [child.id, child.type, child.path, child.title]), o)) : paragraph("Children: none", o)),
139
+ specWriteIssues(r.issues, o), confirm && nextCommand("confirm", confirm, o));
140
+ }
141
+
114
142
  export function renderSpec(command: SpecCommand, result: unknown, o: TextOptions, context: SpecTextContext): string {
143
+ if (command === "delete") return renderSpecDelete(result as SpecDeleteResult, o);
144
+ if (command === "update" || command === "create") return renderSpecUpdate(result as SpecWriteResult, o, command);
115
145
  if (command === "get") return renderSpecGet(result as SpecGetResult, o, context);
116
146
  if (command === "graph") return renderSpecGraph(result as SpecGraphResult, o, context);
117
147
  if (command === "grep") return renderSpecGrep(result as SpecGrepResult, o, context);
@@ -7,6 +7,8 @@ import { specGit } from "./spec-git.ts";
7
7
  import { parseFrontmatter } from "./frontmatter.ts";
8
8
  import { VaultIndex, IndexCacheError, type IndexSourceAdapter, type SearchOptions, type SearchResult } from "./vault-index.ts";
9
9
 
10
+ export const MAX_SPEC_MARKDOWN_PATHS = 10000;
11
+
10
12
  /** Private spec input snapshot; raw sources are for library transforms, never graph results. */
11
13
  export interface SpecCandidate {
12
14
  path: string;
@@ -29,6 +31,8 @@ export interface SpecSnapshot {
29
31
  commonDir: string;
30
32
  specs: SpecDocument[];
31
33
  candidates?: SpecCandidate[];
34
+ /** Git-listed inputs before path filtering, including ordinary Markdown and skipped files. */
35
+ markdownPaths?: readonly string[];
32
36
  diagnostics: SpecDiagnostic[];
33
37
  }
34
38
 
@@ -121,18 +125,20 @@ function candidateProbe(path: string, reason: "oversized" | "invalid_utf8", byte
121
125
  }
122
126
  function adapter(binding: Binding) {
123
127
  let specs: SpecDocument[] = [], candidates: SpecCandidate[] = [], diagnostics: SpecDiagnostic[] = [];
128
+ let markdownPaths: string[] = [];
124
129
  const seen = new Map<string, string>();
125
130
  const source: IndexSourceAdapter = {
126
131
  validate: () => validate(binding),
127
132
  paths: () => {
128
- specs = []; candidates = []; diagnostics = []; seen.clear();
133
+ specs = []; candidates = []; diagnostics = []; markdownPaths = []; seen.clear();
129
134
  const bytes = git(binding.root, ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", "*.md"], binding.env, 8 * 1024 * 1024);
130
135
  let output: string;
131
136
  try { output = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes); }
132
137
  catch { throw new Error("spec source: Git paths are not valid UTF-8; repair the filenames before retrying discovery"); }
133
138
  if (output && !output.endsWith("\0")) throw new Error("spec source: git returned incomplete NUL-delimited paths; retry discovery on a stable repository");
134
139
  const paths = [...new Set(output.split("\0").filter(Boolean))].sort(pathOrder);
135
- if (paths.length > 10000) throw new Error("spec source: more than 10000 Markdown paths; ignore large or vendored Markdown via .gitignore and untrack already-tracked excluded files with git rm --cached before rebuilding");
140
+ if (paths.length > MAX_SPEC_MARKDOWN_PATHS) throw new Error(`spec source: more than ${MAX_SPEC_MARKDOWN_PATHS} Markdown paths; ignore large or vendored Markdown via .gitignore and untrack already-tracked excluded files with git rm --cached before rebuilding`);
141
+ markdownPaths = paths;
136
142
  return paths.filter(path => {
137
143
  const problem = pathProblem(binding, path);
138
144
  if (problem === undefined) return true;
@@ -172,7 +178,7 @@ function adapter(binding: Binding) {
172
178
  return true;
173
179
  },
174
180
  };
175
- return { source, snapshot: (): SpecSnapshot => ({ root: binding.root, commonDir: binding.commonDir, specs: [...specs], candidates: [...candidates], diagnostics: [...diagnostics] }) };
181
+ return { source, snapshot: (): SpecSnapshot => ({ root: binding.root, commonDir: binding.commonDir, specs: [...specs], candidates: [...candidates], markdownPaths: [...markdownPaths], diagnostics: [...diagnostics] }) };
176
182
  }
177
183
  /** Call scan() to refresh. Search and snapshots use the last completed scan, like VaultIndex. */
178
184
  export class SpecIndex {
@@ -185,7 +185,7 @@ export function validateSpecs(snapshot: SpecSnapshot, options: SpecValidationOpt
185
185
  get truncated() { return budget.truncated; } };
186
186
  }
187
187
  /** Existing error identities are retained even when their display sample was truncated. */
188
- export function introducedSpecErrors(current: SpecSnapshot, prospective: SpecSnapshot, options: SpecValidationOptions = {}): SpecValidationIssue[] {
188
+ export function introducedSpecErrors(current: SpecSnapshot, prospective: SpecSnapshot, options: SpecValidationOptions = {}, allowedDanglingLinks: readonly { path: string; field: string; target: string }[] = []): SpecValidationIssue[] {
189
189
  const limit = reportLimit(options.limit);
190
190
  const pathsById = (input: SpecSnapshot) => {
191
191
  const paths = new Map<string, Set<string>>();
@@ -227,8 +227,11 @@ export function introducedSpecErrors(current: SpecSnapshot, prospective: SpecSna
227
227
  if (count === 0) return true;
228
228
  old.set(key, count - 1); return false;
229
229
  });
230
- const result = display(next.map(record => record.issue), limit, { bytes: 1024, truncated: false });
231
- if (next.length && !result.length) throw new Error("spec validation: introduced error metadata exceeds the report budget; reduce metadata before writing");
230
+ // Deletion acknowledgements apply before display limits, never to a sampled result.
231
+ const allowed = new Set(allowedDanglingLinks.map(link => JSON.stringify([link.path, link.field, link.target])));
232
+ const reportable = next.map(record => record.issue).filter(issue => issue.code !== "dangling_link" || !allowed.has(JSON.stringify([issue.path, issue.field, issue.target])));
233
+ const result = display(reportable, limit, { bytes: 1024, truncated: false });
234
+ if (reportable.length && !result.length) throw new Error("spec validation: introduced error metadata exceeds the report budget; reduce metadata before writing");
232
235
  return result;
233
236
  }
234
237
  /** Registry-free CI logic; no home/config/cache creation and no authored freshness fields. */