@staix/vault-mem 0.3.3 → 0.5.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 (45) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/README.md +45 -20
  3. package/bin/vmem.js +9 -3
  4. package/package.json +2 -2
  5. package/src/analysis-commands.ts +22 -13
  6. package/src/analysis-input.ts +2 -2
  7. package/src/analysis-types.ts +2 -0
  8. package/src/cli-output.ts +140 -0
  9. package/src/cli.ts +91 -45
  10. package/src/commands-table.ts +85 -43
  11. package/src/config.ts +22 -3
  12. package/src/links.ts +2 -0
  13. package/src/log-commands.ts +10 -5
  14. package/src/log-format.ts +3 -0
  15. package/src/log-types.ts +5 -1
  16. package/src/mcp-spec.ts +10 -4
  17. package/src/mcp-vault.ts +27 -15
  18. package/src/org-commands.ts +5 -3
  19. package/src/org-promote.ts +3 -0
  20. package/src/promote-command.ts +6 -4
  21. package/src/read-commands.ts +12 -2
  22. package/src/read-output.ts +99 -0
  23. package/src/registry.ts +3 -2
  24. package/src/setup.ts +58 -12
  25. package/src/skills-mine.ts +3 -2
  26. package/src/spec-git.ts +7 -4
  27. package/src/spec-output.ts +119 -0
  28. package/src/sync.ts +62 -18
  29. package/src/text-output.ts +120 -0
  30. package/src/ui/panel.css +1 -5
  31. package/src/ui/panel.js +60 -70
  32. package/src/ui/plugin.ts +33 -2
  33. package/src/vault-files.ts +74 -0
  34. package/src/vault-graph.ts +21 -2
  35. package/src/vault-index.ts +121 -19
  36. package/src/vault-lint.ts +8 -2
  37. package/src/vault-log.ts +109 -1
  38. package/src/vault-stats.ts +50 -0
  39. package/src/workspace-graph.ts +9 -1
  40. package/src/write-commands.ts +32 -9
  41. package/src/write-operations.ts +48 -8
  42. package/src/write-output.ts +151 -0
  43. package/src/write-types.ts +3 -1
  44. package/src/write-validation.ts +30 -8
  45. package/src/writer.ts +19 -7
@@ -1,8 +1,8 @@
1
1
  import { isDeepStrictEqual } from "node:util";
2
2
  import { normalizeSource } from "./source.ts";
3
3
  import { parseFrontmatter, emitFrontmatter } from "./frontmatter.ts";
4
- import { normalizeTarget, proseLines, rewriteLinkTargets, extractLinks, resolveLinks, type LinkNote } from "./links.ts";
5
- import type { PlannedChange, WriteIssue, WriteOp } from "./write-types.ts";
4
+ import { LINK_RELATIONS, normalizeTarget, proseLines, rewriteLinkTargets, extractLinks, resolveLinks, type LinkNote } from "./links.ts";
5
+ import type { PatchEdit, PlannedChange, WriteIssue, WriteOp } from "./write-types.ts";
6
6
  export class WriteRefusal extends Error {
7
7
  constructor(readonly issues: WriteIssue[]) { super(issues[0]?.message ?? "write refused"); }
8
8
  }
@@ -119,11 +119,32 @@ function bodyAlreadyLinks(notes:Map<string,string>,from:string,to:string):boolea
119
119
  }catch{ /* Unrelated malformed legacy YAML cannot resolve an alias. */ }
120
120
  return resolveLinks(metadata,new Map([[from,references]])).some(link=>link.source===from&&link.resolved===to);
121
121
  }
122
+ /** Conservative lexical fast path; escaped, tagged or anchored YAML keys still take semantic parsing. */
123
+ function mayHaveDoi(source: string): boolean {
124
+ const closing = /^(?:---|\.\.\.)[ \t]*\r?$/gm;
125
+ closing.lastIndex = source.indexOf("\n") + 1;
126
+ const header = source.slice(0, closing.exec(source)?.index ?? source.length);
127
+ return /(?:^|[{\n,])[ \t]*(?:doi|["']doi["'])[ \t]*:|[\\!&*?]/.test(header);
128
+ }
122
129
  /** Plan transformations in memory. This function never touches files. */
123
130
  export function planOperation(operation: WriteOp, notes: Map<string, string>, reportBefore?: string | null): PlannedChange[] {
124
131
  const planned = new Map<string, PlannedChange>();
125
132
  const set = (path: string, after: string | null) => {
126
133
  const before = notes.get(path) ?? (operation.op === "report" ? reportBefore ?? null : null);
134
+ if (after === before) return;
135
+ if (after !== null && operation.op !== "report" && mayHaveDoi(after)) {
136
+ try {
137
+ const previousText = operation.op === "move" && path === notePath(operation.to)
138
+ ? needed(notes, moveSourcePath(operation.from, notes)) : before;
139
+ const doc = parseFrontmatter(after), previous = previousText === null ? undefined : parseFrontmatter(previousText).data;
140
+ // Normalize newly assigned identifiers; edits and moves leave untouched legacy metadata byte-identical.
141
+ if (doc.data.type === "reference" && typeof doc.data.doi === "string" &&
142
+ (previous?.type !== "reference" || previous.doi !== doc.data.doi ||
143
+ (operation.op === "frontmatter" && Object.hasOwn(operation.set, "doi")))) {
144
+ after = emitFrontmatter(doc, { doi: doc.data.doi.toLowerCase() });
145
+ }
146
+ } catch { /* Invalid YAML is reported by validation, without obscuring its named issue. */ }
147
+ }
127
148
  if (after !== before) planned.set(path, { path, before, after });
128
149
  };
129
150
  const existing = (value: string) => { const path = notePath(value); return { path, source: needed(notes, path) }; };
@@ -149,11 +170,28 @@ export function planOperation(operation: WriteOp, notes: Map<string, string>, re
149
170
  }
150
171
  case "patch": {
151
172
  const { path, source } = existing(operation.path);
152
- if (typeof operation.oldString !== "string" || !operation.oldString || typeof operation.newString !== "string" || Buffer.byteLength(operation.oldString) > 8192 || Buffer.byteLength(operation.newString) > 8192) refuse("V09", "patch strings must be bounded and oldString nonempty", path);
153
- const first = source.indexOf(operation.oldString);
154
- if (first < 0 || source.indexOf(operation.oldString, first + 1) >= 0) refuse("V09", "oldString must match exactly once", path);
155
- if(first < (document(source,path).frontmatter?.length ?? 0))refuse("V01","patch cannot target frontmatter; use vmem_set_frontmatter or the frontmatter command",path);
156
- set(path, source.slice(0, first) + operation.newString + source.slice(first + operation.oldString.length));
173
+ const single = operation.oldString !== undefined || operation.newString !== undefined;
174
+ if (single === (operation.edits !== undefined)) refuse("V01", "patch takes either oldString/newString or edits, not both or neither; send one form", path);
175
+ const edits: unknown[] = single ? [{ oldString: operation.oldString, newString: operation.newString }] : Array.isArray(operation.edits) ? operation.edits : [];
176
+ if (edits.length < 1 || edits.length > 32) refuse("V09", "edits must list 1 to 32 replacements; split a larger change into several patches", path);
177
+ const frontmatterEnd = document(source, path).frontmatter?.length ?? 0;
178
+ // Every edit is located in the original text, so earlier edits cannot create or remove a later match.
179
+ const spans = edits.map((edit, index) => {
180
+ const at = single ? "" : `edits[${index}]: `;
181
+ if (!edit || typeof edit !== "object" || Array.isArray(edit) || Object.keys(edit).some(key => key !== "oldString" && key !== "newString")) refuse("V01", `${at}an edit is exactly {oldString, newString}`, path);
182
+ const { oldString, newString } = edit as Partial<PatchEdit>;
183
+ if (typeof oldString !== "string" || !oldString || typeof newString !== "string" || Buffer.byteLength(oldString) > 8192 || Buffer.byteLength(newString) > 8192) refuse("V09", `${at}patch strings must be bounded and oldString nonempty`, path);
184
+ const first = source.indexOf(oldString);
185
+ if (first < 0 || source.indexOf(oldString, first + 1) >= 0) refuse("V09", single ? "oldString must match exactly once" : `${at}oldString must match exactly once in the original note; re-read the note and widen the string`, path);
186
+ if (first < frontmatterEnd) refuse("V01", `${at}patch cannot target frontmatter; use vmem_set_frontmatter or the frontmatter command`, path);
187
+ return { start: first, end: first + oldString.length, text: newString, index };
188
+ }).sort((a, b) => a.start - b.start);
189
+ let after = "", cursor = 0;
190
+ for (const span of spans) {
191
+ if (span.start < cursor) refuse("V09", `edits[${span.index}]: oldString overlaps another edit; merge overlapping edits into one`, path);
192
+ after += source.slice(cursor, span.start) + span.text; cursor = span.end;
193
+ }
194
+ set(path, after + source.slice(cursor));
157
195
  break;
158
196
  }
159
197
  case "append": { const { path, source } = existing(operation.path); set(path, appendSection(source, operation.section, operation.markdown, path)); break; }
@@ -164,6 +202,8 @@ export function planOperation(operation: WriteOp, notes: Map<string, string>, re
164
202
  for (const key of operation.unset ?? []) changes[key] = undefined;
165
203
  try {
166
204
  const before = document(source, path);
205
+ // An explicit equal legacy DOI assignment still canonicalizes before the unchanged-text fast path.
206
+ if ((Object.hasOwn(changes, "type") ? changes.type : before.data.type) === "reference" && typeof changes.doi === "string") changes.doi = changes.doi.toLowerCase();
167
207
  let after = emitFrontmatter(before, normalizedSourceChanges(changes));
168
208
  if (Object.hasOwn(operation.set, "topics") && !isDeepStrictEqual(changes.topics, before.data.topics) && Array.isArray(changes.topics) && changes.topics.every((value): value is string => typeof value === "string")) {
169
209
  const doc = document(after, path);
@@ -175,7 +215,7 @@ export function planOperation(operation: WriteOp, notes: Map<string, string>, re
175
215
  }
176
216
  case "link": {
177
217
  const from = existing(operation.from), to = existing(operation.to);
178
- if (!["supports", "contradicts", "extends", "applies-to", "context-for"].includes(operation.relation)) refuse("V01", "invalid relation");
218
+ if (!(LINK_RELATIONS as readonly string[]).includes(operation.relation)) refuse("V01", "invalid relation");
179
219
  if (operation.context !== undefined && (typeof operation.context !== "string" || /[\r\n]/.test(operation.context) || operation.context.length > 500)) refuse("V01", "link context must be one line <=500 characters");
180
220
  if (from.path === to.path) refuse("V01", "link endpoints must differ");
181
221
  const line = (path: string) => `- [[${path.slice(6, -3)}]] (${operation.relation})${operation.context ? `: ${operation.context}` : ""}`;
@@ -0,0 +1,151 @@
1
+ /**
2
+ * Text renderers for writes, two-step previews and promotion (#114): one result line, then changes, issues, the
3
+ * log receipt and, for a preview, the exact confirm command. Note bodies and drafts are never printed; `--json` has them.
4
+ */
5
+ import type { ChangeReceipt, WriteIssue, WriteReceipt } from "./write-types.ts";
6
+ import type { LogReceipt } from "./log-types.ts";
7
+ import type { TidyResult } from "./tidy.ts";
8
+ import type { OrgPromoteResult } from "./org-promote.ts";
9
+ import type { SyncResult } from "./sync.ts";
10
+ import type { PromoteResult } from "./promote.ts";
11
+ import { notePath } from "./write-operations.ts";
12
+ import { blocks, clean, fields, issueTable, nextCommand, paragraph, plural, shellWord, table, type TextOptions, type Tone } from "./text-output.ts";
13
+
14
+ /** The words the command was run with (`[command, ...args]`, no `--color`) and its positional arguments. */
15
+ export interface WriteContext { argv: string[]; positional: string[] }
16
+ type Candidates = { projects: { project: string; candidates: { id: string; project: string; kind: string; title: string | null; at: string }[] }[] };
17
+
18
+ const line = (text: string, o: TextOptions, t?: Tone) => paragraph(text, o, t);
19
+ const list = (label: string, items: readonly string[] | undefined) => items?.length ? [`${label}:`, ...items.map(item => ` - ${clean(item)}`)].join("\n") : undefined;
20
+ const short = (sha: string | null) => sha ? sha.slice(0, 12) : "-";
21
+ const action = (c: ChangeReceipt) => c.beforeSha === null ? "create" : c.sha256 === null ? "delete" : "update";
22
+ const errors = (issues: readonly WriteIssue[]) => issues.filter(issue => issue.severity === "error").length;
23
+ const stem = (target: string | undefined) => { try { return notePath(target ?? ""); } catch { return target ?? "?"; } };
24
+
25
+ /** The preview's own words with `--confirm --fingerprint <sha>`, quoted so it can be pasted. */
26
+ export function confirmCommand(argv: readonly string[], fingerprint: string, drop: readonly string[] = []): string {
27
+ const kept: string[] = [];
28
+ for (let i = 0; i < argv.length; i++) {
29
+ const word = argv[i]!;
30
+ if (word === "--fingerprint") { i++; continue; }
31
+ if (!["--json", "--dry-run", "--confirm", ...drop].includes(word)) kept.push(word);
32
+ }
33
+ return ["vmem", ...kept, "--confirm", "--fingerprint", fingerprint].map(shellWord).join(" ");
34
+ }
35
+ function logLine(log: LogReceipt | undefined, o: TextOptions, label = "log"): string | undefined {
36
+ if (!log) return undefined;
37
+ if (log.ok && log.appended) return line(`${label}: appended${log.bytesWritten !== null ? ` (${plural(log.bytesWritten, "byte")})` : ""}${log.synced ? "" : ", not yet synced to disk"}`, o);
38
+ return blocks(line(`${label}: not appended${log.rolledBack ? " (rolled back)" : ""}`, o, "fail"), issueTable(log.issues, o));
39
+ }
40
+
41
+ const VERBS: Record<string, [string, string]> = {
42
+ new: ["create", "created"], patch: ["patch", "patched"], append: ["append to", "appended to"], frontmatter: ["update the frontmatter of", "updated the frontmatter of"],
43
+ link: ["link", "linked"], supersede: ["supersede", "superseded"], move: ["move", "moved"], delete: ["delete", "deleted"], report: ["write", "wrote"],
44
+ };
45
+ function what(command: string, changes: ChangeReceipt[], targets: string[], past: boolean): string {
46
+ const verb = VERBS[command]?.[past ? 1 : 0] ?? command;
47
+ const others = (paths: string[], how: string) => paths.length ? ` and ${how} ${plural(paths.length, "note")}` : "";
48
+ const deleted = changes.filter(c => action(c) === "delete").map(c => c.path), created = changes.filter(c => action(c) === "create").map(c => c.path);
49
+ const updated = changes.filter(c => action(c) === "update").map(c => c.path);
50
+ if (command === "move") return `${verb} ${deleted[0] ?? stem(targets[0])} to ${created[0] ?? stem(targets[1])}${others(updated, past ? "rewrote links in" : "rewrite links in")}`;
51
+ if (command === "delete") return `${verb} ${deleted[0] ?? stem(targets[0])}${others(updated, past ? "updated" : "update")}`;
52
+ if (command === "link") return `${verb} ${stem(targets[0])} and ${stem(targets[1])}`;
53
+ if (command === "supersede") return `${verb} ${stem(targets[0])} with ${stem(targets[1])}`;
54
+ return `${verb} ${changes[0]?.path ?? (command === "report" ? targets[0] : stem(targets[0]))}`;
55
+ }
56
+
57
+ /** `new`, `patch`, `append`, `frontmatter`, `link`, `supersede`, `move`, `delete`, `report` and `check`. */
58
+ export function renderWriteReceipt(r: WriteReceipt, o: TextOptions, ctx: WriteContext): string {
59
+ const command = ctx.argv[0]!, targets = ctx.positional.slice(1), issues = issueTable(r.issues, o);
60
+ if (command === "check") {
61
+ const path = r.changes[0]?.path ?? r.issues.find(issue => issue.path)?.path ?? "the note", e = errors(r.issues), w = r.issues.length - e;
62
+ const verdict = r.ok ? `ok: ${path} passes validation${w ? ` (${plural(w, "warning")})` : ""}` : `fail: ${path} has ${plural(e, "error")}${w ? ` and ${plural(w, "warning")}` : ""}`;
63
+ return blocks(issues, line(verdict, o, r.ok ? "ok" : "fail"));
64
+ }
65
+ const twoStep = command === "move" || command === "delete";
66
+ let head: string, t: Tone;
67
+ if (!r.ok) [head, t] = r.applied ? [`failed after writing: ${what(command, r.changes, targets, true)}; see the issues`, "fail"] : ["refused: nothing written", "fail"];
68
+ else if (r.preview) [head, t] = [`dry run: would ${what(command, r.changes, targets, false)}`, "info"];
69
+ else if (r.unchanged) [head, t] = ["unchanged: links already present", "muted"];
70
+ else if (!r.applied) [head, t] = ["unchanged: nothing to write", "muted"];
71
+ else [head, t] = [what(command, r.changes, targets, true), "ok"];
72
+ const one = r.changes.length === 1 && r.ok && !r.preview && r.changes[0]!.sha256 ? fields([["sha256", r.changes[0]!.sha256]], o) : undefined;
73
+ const changes = r.changes.length > 1 ? table(["PATH", "ACTION", "BYTES", "SHA"], r.changes.map(c => [c.path, action(c), c.sha256 === null ? "-" : c.bytes, short(c.sha256)]), o) : undefined;
74
+ const log = r.log ? logLine(r.log, o) : r.ok && r.preview ? line(twoStep ? "log: written on confirm" : "log: none (dry run)", o, "muted") : undefined;
75
+ const confirm = twoStep && r.ok && r.preview && r.fingerprint ? nextCommand("confirm", confirmCommand(ctx.argv, r.fingerprint), o) : undefined;
76
+ return blocks([line(head, o, t), one].filter(Boolean).join("\n"), changes, issues, list("possible duplicates", r.possibleDuplicates), log, confirm);
77
+ }
78
+
79
+ /** `tidy`: counts per rule and the notes touched, then the confirm command. */
80
+ export function renderTidy(r: TidyResult, o: TextOptions, ctx: WriteContext): string {
81
+ const vault = ctx.positional[0] ?? "?", notes = r.notes.length, logChanges = r.counts.log ?? 0;
82
+ const touched = [notes ? plural(notes, "note") : "", logChanges ? "the log" : ""].filter(Boolean).join(" and ");
83
+ let head: string, t: Tone;
84
+ if (!r.ok) [head, t] = r.applied ? [`failed after writing ${plural(r.written.length, "file")} in ${vault}; rerun to finish`, "fail"] : ["refused: nothing written", "fail"];
85
+ else if (!touched) [head, t] = [`unchanged: nothing to tidy in ${vault}`, "muted"];
86
+ else if (r.preview) [head, t] = [`dry run: would tidy ${touched} in ${vault}`, "info"];
87
+ else [head, t] = [`tidied ${touched} in ${vault}`, "ok"];
88
+ const counted = r.rules.filter(rule => (r.counts[rule] ?? 0) > 0);
89
+ const rules = counted.length ? table(["RULE", "CHANGES"], counted.map(rule => [rule, r.counts[rule]!]), o) : undefined;
90
+ const noteTable = notes ? table(["NOTE", "CHANGES"], r.notes.map(note => [note.path, note.changes.length]), o) : undefined;
91
+ const reported = r.reported.length ? table(["LEFT UNCHANGED", "REASON"], r.reported.map(item => [item.path, item.message]), o) : undefined;
92
+ const log = r.log && (r.log.redactions || r.log.formats) ? line(`log: ${plural(r.log.redactions, "redaction")} on ${plural(r.log.lines, "line")}, ${plural(r.log.formats, "format fix", "format fixes")}`, o) : undefined;
93
+ const event = r.ok && r.applied && r.event ? line(`logged: LINT ${r.event}`, o) : undefined;
94
+ const confirm = r.ok && r.preview && touched && r.fingerprint ? nextCommand("confirm", confirmCommand(ctx.argv, r.fingerprint), o) : undefined;
95
+ return blocks(line(head, o, t), rules, noteTable, reported, issueTable(r.issues, o), log, event, confirm);
96
+ }
97
+
98
+ /** `promote <vault> <note> --to <org>`. */
99
+ export function renderOrgPromote(r: OrgPromoteResult, o: TextOptions, ctx: WriteContext): string {
100
+ const source = r.source ?? ctx.positional[1] ?? "?", target = r.target ?? "the org vault";
101
+ let head: string, t: Tone;
102
+ if (!r.ok) [head, t] = r.applied ? [`promoted ${source} to ${target} with problems; see the issues`, "fail"] : ["refused: nothing written", "fail"];
103
+ else if (r.preview) [head, t] = [r.recovery ? `dry run: would record on ${source} that ${target} already holds it` : `dry run: would promote ${source} to ${target}`, "info"];
104
+ else [head, t] = [r.recovery ? `recorded on ${source} that ${target} holds it` : `promoted ${source} to ${target}`, "ok"];
105
+ const seen = new Set<string>(), issues = [...r.issues, ...r.screen.issues, ...(r.lint?.issues ?? [])].filter(issue => !seen.has(JSON.stringify(issue)) && !!seen.add(JSON.stringify(issue)));
106
+ const lint = r.lint ? line(`org lint: ${r.lint.passed ? "passed" : "failed"}${r.lint.summary ? ` (${r.lint.summary})` : ""}`, o, r.lint.passed ? "ok" : "fail") : undefined;
107
+ const logs = r.logs ? [logLine(r.logs.target ?? undefined, o, "target log"), logLine(r.logs.source ?? undefined, o, "source log")].filter(Boolean).join("\n") : undefined;
108
+ const confirm = r.ok && r.preview && r.fingerprint ? nextCommand("confirm", confirmCommand(ctx.argv, r.fingerprint), o) : undefined;
109
+ return blocks(line(head, o, t), issueTable(issues, o), list("dropped links", r.droppedLinks), lint, logs, confirm);
110
+ }
111
+
112
+ /** `sync <vault>`. */
113
+ export function renderSync(r: SyncResult, o: TextOptions, ctx: WriteContext): string {
114
+ const branch = r.branch ?? "?", origin = r.remote.origin ?? r.remote.configured ?? "origin";
115
+ const work = [r.paths.length ? `commit ${plural(r.paths.length, "path")}` : "", r.behind ? `rebase onto origin/${branch}` : "", r.paths.length || r.ahead ? `push ${branch} to ${origin}` : ""].filter(Boolean).join(", ");
116
+ let head: string, t: Tone;
117
+ if (!r.ok) [head, t] = r.commit ? [`committed ${short(r.commit)} in ${r.vault}; not pushed`, "fail"] : ["refused: nothing synced", "fail"];
118
+ else if (r.preview) [head, t] = work ? [`dry run: would ${work}`, "info"] : [`unchanged: ${r.vault} has nothing to sync`, "muted"];
119
+ else if (!r.applied) [head, t] = [`unchanged: ${r.vault} is up to date with origin/${branch}`, "muted"];
120
+ else [head, t] = [`synced ${r.vault}: ${r.commit ? `${short(r.commit)} ` : ""}pushed to ${origin} ${branch}`, "ok"];
121
+ const info = r.branch === null ? "" : fields([["vault", r.vault], ["branch", r.branch], ["remote", r.remote.configured], ["origin", r.remote.origin], ["ahead", r.ahead], ["behind", r.behind]], o);
122
+ const paths = r.paths.length ? table(["PATH"], r.paths.map(path => [path]), o) : undefined;
123
+ const confirm = r.ok && r.preview && work && r.fingerprint ? nextCommand("confirm", confirmCommand(ctx.argv, r.fingerprint), o) : undefined;
124
+ return blocks([line(head, o, t), info].filter(Boolean).join("\n"), paths, list("not synced (outside notes/, reports/ and log)", r.ignored), issueTable(r.issues, o), confirm);
125
+ }
126
+
127
+ /** `promote-from-amem <vault>`: the candidate table per project. */
128
+ export function renderCandidates(r: Candidates, o: TextOptions, ctx: WriteContext): string {
129
+ const vault = ctx.positional[0] ?? "?", found = r.projects.filter(p => p.candidates.length);
130
+ if (!found.length) return line("no promotion candidates", o, "muted");
131
+ const first = found[0]!.candidates[0]!;
132
+ return blocks(...found.map(p => [line(`${p.project}: ${plural(p.candidates.length, "candidate")}`, o, "bold"), table(["ID", "KIND", "AT", "TITLE"], p.candidates.map(c => [c.id, c.kind, c.at, c.title ?? "-"]), o)].join("\n")),
133
+ nextCommand("preview one", ["vmem", "promote-from-amem", vault, first.id, "--project", first.project].map(shellWord).join(" "), o));
134
+ }
135
+
136
+ /** `promote-from-amem <vault> <mem-id>`: preview or confirm one promotion; `edited` when `--edit` changed the draft. */
137
+ export function renderPromote(r: PromoteResult, o: TextOptions, ctx: WriteContext, edited = false): string {
138
+ const mem = `mem:${r.id}`, path = r.path ?? "a new note";
139
+ let head: string, t: Tone;
140
+ if (!r.ok) [head, t] = r.applied ? [`created ${path} from ${mem}, but the promotion is incomplete; see the issues`, "fail"] : ["refused: nothing written", "fail"];
141
+ else if (r.preview && r.action === "link") [head, t] = r.alreadyLinked ? [`unchanged: ${mem} already links ${path}`, "muted"] : [`dry run: would link ${mem} to ${path}`, "info"];
142
+ else if (r.preview) [head, t] = [`dry run: would create ${path} from ${mem}`, "info"];
143
+ else if (!r.applied) [head, t] = [`unchanged: ${mem} already links ${path}`, "muted"];
144
+ else [head, t] = [r.action === "link" ? `linked ${mem} to ${path}` : `created ${path} from ${mem}`, "ok"];
145
+ const draft = r.text !== undefined && r.preview ? line(`draft: ${plural(Buffer.byteLength(r.text), "byte")}; --json shows the text, --edit opens it in $EDITOR`, o, "muted") : undefined;
146
+ const info = fields([["linked", r.linked ?? ""]], o);
147
+ const hint = edited && r.preview ? line("edited text is only previewed: save it and confirm with --body <file> and this fingerprint", o, "warn") : undefined;
148
+ const command = r.ok && r.preview && !r.alreadyLinked && r.fingerprint ? confirmCommand(ctx.argv, r.fingerprint, edited ? ["--edit"] : []) : undefined;
149
+ return blocks([line(head, o, t), info].filter(Boolean).join("\n"), draft, issueTable(r.issues, o), list("possible duplicates", r.possibleDuplicates), list("choices", r.choices),
150
+ logLine(r.note?.log, o), hint, command && nextCommand("confirm", edited ? command.replace(/ --confirm /, " --body <file> --confirm ") : command, o));
151
+ }
@@ -1,10 +1,12 @@
1
1
  import type { PiiSurface } from "./config.ts";
2
2
  import type { LogEvent, LogReceipt } from "./log-types.ts";
3
3
  import type { VaultSpec, VmemConfig } from "./config.ts";
4
+ export interface PatchEdit { oldString: string; newString: string }
4
5
  export type WriteOp =
5
6
  | { op: "check"; path: string; text: string }
6
7
  | { op: "create"; path: string; frontmatter: Record<string, unknown>; body?: string }
7
- | { op: "patch"; path: string; oldString: string; newString: string; expectedSha?: string }
8
+ /** One `oldString`/`newString` pair or `edits` (1..32 pairs), never both; edits apply all-or-nothing against the original text. */
9
+ | { op: "patch"; path: string; oldString?: string; newString?: string; edits?: PatchEdit[]; expectedSha?: string }
8
10
  | { op: "append"; path: string; section: string; markdown: string; expectedSha?: string }
9
11
  | { op: "frontmatter"; path: string; set: Record<string, unknown>; unset?: string[]; expectedSha?: string }
10
12
  | { op: "link"; from: string; to: string; relation: "supports" | "contradicts" | "extends" | "applies-to" | "context-for"; context?: string; bidirectional?: boolean }
@@ -1,7 +1,7 @@
1
1
  import { isDeepStrictEqual } from "node:util";
2
2
  import { sourceReferences, sourceWorkspaceRoot, missingSourceWarnings } from "./source.ts";
3
3
  import { basename, resolve } from "node:path";
4
- import type { VaultSpec, VmemConfig } from "./config.ts";
4
+ import { domainProblem, type VaultSpec, type VmemConfig } from "./config.ts";
5
5
  import { parseFrontmatter } from "./frontmatter.ts";
6
6
  import { extractLinks, normalizeTarget, proseLines, resolveLinks, type Link, type LinkNote, type ResolvedLink } from "./links.ts";
7
7
  import { canonicalPath, isDenied } from "./platform.ts";
@@ -11,7 +11,6 @@ import { screenPii } from "./pii.ts";
11
11
  import { moveSourcePath } from "./write-operations.ts";
12
12
 
13
13
  const TYPES = new Set(["insight", "decision", "observation", "person", "project", "method", "moc", "reference"]);
14
- const DOMAINS = new Set(["research", "projects", "teaching", "operations", "people", "ai-practice"]);
15
14
  const CONFIDENCE = new Set(["proven", "likely", "experimental"]);
16
15
  const STATUS = new Set(["active", "superseded", "archived"]);
17
16
  const CATEGORY = new Set(["gap", "prompt", "workflow"]);
@@ -23,9 +22,11 @@ const KEYS = new Set([
23
22
  "promoted_from", "promoted_at", "promoted_to", "source_ref",
24
23
  // Adopted in the V2 cutover (#22): decision dates/owners and person contact fields.
25
24
  "decided_at", "decided_by", "email", "phone",
25
+ "citekey", "doi", "arxiv_id", "authors", "year", "venue",
26
26
  ]);
27
27
  /** Adopted keys valid only on one note type (contact fields additionally only in personal vaults, by PII policy). */
28
- export const TYPED_KEYS: Readonly<Record<string, string>> = { decided_at: "decision", decided_by: "decision", email: "person", phone: "person" };
28
+ export const TYPED_KEYS: Readonly<Record<string, string>> = { decided_at: "decision", decided_by: "decision", email: "person", phone: "person",
29
+ citekey: "reference", doi: "reference", arxiv_id: "reference", authors: "reference", year: "reference", venue: "reference" };
29
30
  export const SCHEMA_KEYS: ReadonlySet<string> = KEYS;
30
31
  const WIKI_FIELDS = ["topics", "project", "superseded_by", "supersedes", "source_ref"];
31
32
  // Exact regex set from @staix/agent-mem v0.17.0 src/memory/screen.ts; parity-tested against its root export.
@@ -143,29 +144,38 @@ function changedBrokenLinks(oldNotes: Map<string, ParsedNote>, newNotes: Map<str
143
144
  return issues;
144
145
  }
145
146
  interface SchemaIssue extends WriteIssue { fields: string[] }
146
- function schema(note: ParsedNote): SchemaIssue[] {
147
+ function schema(note: ParsedNote, vault: VaultSpec): SchemaIssue[] {
147
148
  const issues: SchemaIssue[] = [], { data, path } = note;
148
149
  const add=(field:string,message:string,dependencies=[field])=>issues.push({...issue("V01",message,"error",path),fields:dependencies});
149
- for(const key of Object.keys(data))if(!KEYS.has(key)||(TYPED_KEYS[key]!==undefined&&data.type!==TYPED_KEYS[key]))add(key,"unknown frontmatter key",[key,"type"]);
150
+ for(const key of Object.keys(data))if(!KEYS.has(key)||(TYPED_KEYS[key]!==undefined&&data.type!==TYPED_KEYS[key]))add(key,TYPED_KEYS[key] === "reference" ? `${key} is only valid on reference notes; set type: reference or unset ${key}` : "unknown frontmatter key",[key,"type"]);
150
151
  const description = data.description;
151
152
  if (typeof description !== "string" || !description.trim() || [...description].length > 200) add("description","description must contain 1..200 Unicode characters");
152
153
  else if ([note.title, note.h1, basename(path, ".md")].some(value => value && fold(description) === fold(value))) add("description","description must supplement the title");
153
154
  if (typeof data.type !== "string" || !TYPES.has(data.type)) add("type","invalid or missing note type");
154
155
  if (data.type !== "moc" || data.domain !== undefined) {
155
- if (typeof data.domain !== "string" || !DOMAINS.has(data.domain)) add("domain","invalid or missing domain");
156
+ const problem = domainProblem(data.domain, vault);
157
+ if (problem) add("domain", problem);
156
158
  }
157
159
  for (const [key, allowed] of [["confidence", CONFIDENCE], ["status", STATUS], ["category", CATEGORY]] as const) {
158
160
  if (data[key] !== undefined && (typeof data[key] !== "string" || !allowed.has(data[key]))) add(key,`invalid ${key} enum`);
159
161
  }
160
162
  if(data.source!==undefined)try{sourceReferences(data.source);}catch{add("source","source must contain workspace-relative paths, mem ids or URLs");}
163
+ if (data.type === "reference") {
164
+ if (data.citekey !== undefined && (typeof data.citekey !== "string" || !/^[A-Za-z0-9_:-]{1,64}(?![\s\S])/.test(data.citekey))) add("citekey", "citekey must match [A-Za-z0-9_:-]{1,64}");
165
+ if (data.doi !== undefined && (typeof data.doi !== "string" || !/^10\.[0-9]{4,9}\/[^\s\p{C}]+(?![\s\S])/u.test(data.doi))) add("doi", "doi must be 10.<4..9 digit registrant>/<nonempty suffix>, without whitespace or control characters");
166
+ if (data.arxiv_id !== undefined && (typeof data.arxiv_id !== "string" || !/^(?:(?:0[0-9]|1[0-4])(?:0[1-9]|1[0-2])\.[0-9]{4}|(?:1[5-9]|[2-9][0-9])(?:0[1-9]|1[0-2])\.[0-9]{5}|[a-z]+(?:[.-][A-Za-z]+)*\/[0-9]{2}(?:0[1-9]|1[0-2])[0-9]{3})(?:v[1-9][0-9]*)?(?![\s\S])/.test(data.arxiv_id))) add("arxiv_id", "arxiv_id must use 4 digits after YYMM. for YY < 15, 5 digits for YY >= 15, or archive/YYMMNNN; month 01..12 and optional vN (N >= 1)");
167
+ if (data.authors !== undefined && (!Array.isArray(data.authors) || data.authors.length < 1 || data.authors.length > 100 || data.authors.some(author => typeof author !== "string" || !author.trim()))) add("authors", "authors must be a list of 1..100 nonempty strings");
168
+ if (data.year !== undefined && (typeof data.year !== "number" || !Number.isInteger(data.year) || data.year < 1000 || data.year > 2100)) add("year", "year must be an integer from 1000 to 2100");
169
+ if (data.venue !== undefined && (typeof data.venue !== "string" || [...data.venue].length < 1 || [...data.venue].length > 200)) add("venue", "venue must contain 1..200 Unicode characters");
170
+ }
161
171
  return issues;
162
172
  }
163
173
  function schemaIssues(note:ParsedNote,old:ParsedNote|undefined,context:ValidationContext):WriteIssue[]{
164
174
  const op=context.operation;
165
175
  const explicit=op.op==="frontmatter"&&noteKey(op.path)===noteKey(note.path)?new Set(Object.keys(op.set)):new Set<string>();
166
176
  const value=(n:ParsedNote,key:string)=>n.data[key];
167
- const previous=old?schema(old):[];
168
- return schema(note).map(({fields,...finding})=>{
177
+ const previous=old?schema(old,context.vault):[];
178
+ return schema(note,context.vault).map(({fields,...finding})=>{
169
179
  const retained=op.op!=="create"&&old&&!fields.some(key=>explicit.has(key))&&fields.every(key=>isDeepStrictEqual(value(note,key),value(old,key)))&&previous.some(before=>before.message===finding.message&&isDeepStrictEqual(before.fields,fields));
170
180
  return {...finding,severity:retained?"warning":"error"};
171
181
  });
@@ -228,6 +238,11 @@ export function validateWrite(changes: PlannedChange[], context: ValidationConte
228
238
  }
229
239
  const sourceRoot=sourceWorkspaceRoot(context.vault);
230
240
  const oldNotes = parseNotes(context.notes), newNotes = parseNotes(final, oldNotes), oldNames = names(oldNotes), newNames = names(newNotes);
241
+ const citekeys = new Map<string, ParsedNote[]>();
242
+ for (const note of newNotes.values()) if (typeof note.data.citekey === "string") {
243
+ const peers = citekeys.get(note.data.citekey.toLowerCase()) ?? [];
244
+ peers.push(note); citekeys.set(note.data.citekey.toLowerCase(), peers);
245
+ }
231
246
  const candidates=[...changes];
232
247
  if(context.operation.op==="frontmatter"){
233
248
  const key=noteKey(context.operation.path),existing=[...newNotes.values()].find(note=>noteKey(note.path)===key);
@@ -239,6 +254,13 @@ export function validateWrite(changes: PlannedChange[], context: ValidationConte
239
254
  if (!note) { issues.push(issue("V01", "invalid frontmatter", "error", change.path)); continue; }
240
255
  const prior=context.operation.op==="move"&&noteKey(context.operation.to)===noteKey(note.path)?oldNotes.get(movedFrom(context.operation.from, context)):oldNotes.get(note.path);
241
256
  issues.push(...schemaIssues(note,prior,context), ...topicPlacement(note,prior,context));
257
+ if (typeof note.data.citekey === "string" && (citekeys.get(note.data.citekey.toLowerCase())?.length ?? 0) > 1) {
258
+ const explicit = context.operation.op === "frontmatter" && noteKey(context.operation.path) === noteKey(note.path) && Object.hasOwn(context.operation.set, "citekey");
259
+ const retained = context.operation.op !== "create" && !explicit && prior?.data.citekey === note.data.citekey &&
260
+ [...oldNotes.values()].some(other => other.path !== prior.path && typeof other.data.citekey === "string" && other.data.citekey.toLowerCase() === (note.data.citekey as string).toLowerCase());
261
+ const holder = citekeys.get(note.data.citekey.toLowerCase())!.find(other => other.path !== note.path)!;
262
+ issues.push(issue("V08", `citekey is already used by ${holder.path}; choose another citekey`, retained ? "warning" : "error", change.path));
263
+ }
242
264
  const source = note.data.source;
243
265
  let sourceDenied=strings(source).some(entry=>isDenied(entry.replaceAll("\\","/"),context.config.denyPaths));
244
266
  if(source!==undefined&&!sourceDenied)try{
package/src/writer.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { appendLog, matchesBinding } from "./vault-log.ts";
1
+ import { appendLog, checkLogEvent, matchesBinding } from "./vault-log.ts";
2
2
  import type { LogEvent } from "./log-types.ts";
3
3
  import { closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, readdirSync, realpathSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
4
4
  import { createHash, randomUUID } from "node:crypto";
@@ -6,7 +6,7 @@ import { dirname, join } from "node:path";
6
6
  import { hostname } from "node:os";
7
7
  import { Database } from "bun:sqlite";
8
8
  import { loadRegistry, syncDirectory } from "./registry.ts";
9
- import { VaultIndex, MAX_NOTE_BYTES } from "./vault-index.ts";
9
+ import { VaultIndex, MAX_NOTE_BYTES, GRAMS_COLUMNS, gramPhrase, grams, splitTerms } from "./vault-index.ts";
10
10
  import { parseFrontmatter } from "./frontmatter.ts";
11
11
  import { canonicalPath, isDenied } from "./platform.ts";
12
12
  import { moveSourcePath, notePath, planOperation, refuse, WriteRefusal } from "./write-operations.ts";
@@ -102,14 +102,20 @@ function duplicateWarnings(request: WriteRequest, notes: Map<string, string>, ch
102
102
  // Disposable FTS preserves dry-run's no-disk-write contract, including on a fresh home.
103
103
  const db = new Database(":memory:");
104
104
  try {
105
- db.run("CREATE VIRTUAL TABLE candidates USING fts5(path UNINDEXED,title,description,body,tokenize='unicode61')");
106
- const insert = db.query("INSERT INTO candidates VALUES (?,?,?,?)");
105
+ db.run(`CREATE VIRTUAL TABLE candidates USING fts5(path UNINDEXED,title,description,body,tokenize='unicode61');
106
+ CREATE VIRTUAL TABLE grams USING fts5(${GRAMS_COLUMNS},tokenize='unicode61');`);
107
+ const insert = db.query("INSERT INTO candidates VALUES (?,?,?,?)"), insertGrams = db.query("INSERT INTO grams VALUES (?,?,?,?)");
107
108
  for (const [path, source] of notes) {
108
109
  let value: ReturnType<typeof parseFrontmatter>;
109
110
  try { value = parseFrontmatter(source); } catch { continue; } // Unrelated legacy YAML is not a duplicate candidate.
110
- insert.run(path, typeof value.data.title === "string" ? value.data.title : path, typeof value.data.description === "string" ? value.data.description : "", value.body);
111
+ const title = typeof value.data.title === "string" ? value.data.title : path, description = typeof value.data.description === "string" ? value.data.description : "";
112
+ insert.run(path, title, description, value.body); insertGrams.run(path, grams(title), grams(description), grams(value.body));
111
113
  }
112
- const hits = db.query<{ path: string; score: number }, [string]>("SELECT path,bm25(candidates,0,5,2,1) AS score FROM candidates WHERE candidates MATCH ? ORDER BY score,path LIMIT 3").all(terms.map(term => `"${term}"`).join(" AND "));
114
+ // Same term split as VaultIndex.search: CJK terms match substrings through the bigram table.
115
+ const { tokens, runs } = splitTerms(terms);
116
+ const hits = runs.length
117
+ ? db.query<{ path: string; score: number }, string[]>(`SELECT path,bm25(grams,0,5,2,1) AS score FROM grams WHERE grams MATCH ? ${tokens.length ? "AND path IN (SELECT path FROM candidates WHERE candidates MATCH ?)" : ""} ORDER BY score,path LIMIT 3`).all(runs.map(gramPhrase).join(" AND "), ...(tokens.length ? [tokens.join(" AND ")] : []))
118
+ : db.query<{ path: string; score: number }, [string]>("SELECT path,bm25(candidates,0,5,2,1) AS score FROM candidates WHERE candidates MATCH ? ORDER BY score,path LIMIT 3").all(tokens.join(" AND "));
113
119
  return hits.filter(hit => hit.score <= -0.000001).map(hit => ({ code: "V08", severity: "warning", path: hit.path, message: "possible duplicate: FTS title terms match an existing note" }));
114
120
  } finally { db.close(); }
115
121
  }
@@ -136,6 +142,11 @@ export function applyWrite(home: string, request: WriteRequest, options: { env?:
136
142
  root = realpathSync(vault.path);
137
143
  if (root !== vault.path || isDenied(root, config.denyPaths)) refuse("V06", "vault path denied or changed");
138
144
  if (config.vaults.some(value => canonicalPath(home) === value.path || canonicalPath(home).startsWith(`${value.path}/`))) refuse("V04", "VMEM_HOME must be outside registered vaults");
145
+ // A given event is checked like `log append` before any lock or note change, so a bad event never leaves an unlogged write.
146
+ if (request.log !== undefined && request.log !== false && request.operation.op !== "check") {
147
+ const logIssues = checkLogEvent(home, { vault: request.vault, event: request.log, channel: request.channel }, options.env);
148
+ if (logIssues.length) throw new WriteRefusal(logIssues.map(issue => ({ ...issue, message: `log event refused, nothing written: ${issue.message}; fix the event fields (rules as for \`log append\`) or omit the event for the default line` })));
149
+ }
139
150
  const twoStep = ["move", "delete", "tidy"].includes(request.operation.op);
140
151
  const preview = request.operation.op === "check" || request.dryRun === true || (twoStep && request.confirm !== true);
141
152
  if (!preview) {
@@ -159,7 +170,8 @@ export function applyWrite(home: string, request: WriteRequest, options: { env?:
159
170
  for (const change of changes) if (isDenied(join(root, change.path), config.denyPaths)) refuse("V06", "planned mutation path is denied", change.path);
160
171
  issues = validateWrite(changes, { vault, config, notes, operation: request.operation, ...(options.piiSurface ? { piiSurface: options.piiSurface } : {}) });
161
172
  if (!issues.some(issue => issue.severity === "error")) issues.push(...duplicateWarnings(request, notes, changes));
162
- const input = { vault: request.vault, channel: request.channel ?? "cli", operation: request.operation, expectedShas: request.expectedShas ?? {}, log: request.log ?? null };
173
+ // The log event is not part of the fingerprint: move/delete take it on the confirm call only.
174
+ const input = { vault: request.vault, channel: request.channel ?? "cli", operation: request.operation, expectedShas: request.expectedShas ?? {} };
163
175
  const identity = lstatSync(root);
164
176
  // The identity every later commit check uses must still be the bound root, not a directory swapped in meanwhile.
165
177
  if (options.binding && (Number(identity.dev) !== options.binding.dev || Number(identity.ino) !== options.binding.ino)) refuse("VAULT_DRIFT", "vault root changed since the run started; nothing written");