daftari 3.1.0 → 3.3.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 (152) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/dist/access/rbac.d.ts +1 -0
  3. package/dist/access/rbac.d.ts.map +1 -1
  4. package/dist/access/rbac.js +8 -0
  5. package/dist/access/rbac.js.map +1 -1
  6. package/dist/audit/describes.d.ts +7 -0
  7. package/dist/audit/describes.d.ts.map +1 -1
  8. package/dist/audit/describes.js +48 -16
  9. package/dist/audit/describes.js.map +1 -1
  10. package/dist/backfill/derive.d.ts.map +1 -1
  11. package/dist/backfill/derive.js +2 -0
  12. package/dist/backfill/derive.js.map +1 -1
  13. package/dist/cli.d.ts.map +1 -1
  14. package/dist/cli.js +12 -0
  15. package/dist/cli.js.map +1 -1
  16. package/dist/consolidate/call-budget.d.ts +2 -0
  17. package/dist/consolidate/call-budget.d.ts.map +1 -1
  18. package/dist/consolidate/call-budget.js +8 -1
  19. package/dist/consolidate/call-budget.js.map +1 -1
  20. package/dist/curation/lint-voice.d.ts.map +1 -1
  21. package/dist/curation/lint-voice.js +2 -0
  22. package/dist/curation/lint-voice.js.map +1 -1
  23. package/dist/curation/lint.d.ts +2 -1
  24. package/dist/curation/lint.d.ts.map +1 -1
  25. package/dist/curation/lint.js +57 -0
  26. package/dist/curation/lint.js.map +1 -1
  27. package/dist/curation/staged-actions.d.ts +1 -1
  28. package/dist/curation/staged-actions.d.ts.map +1 -1
  29. package/dist/curation/staged-actions.js +1 -0
  30. package/dist/curation/staged-actions.js.map +1 -1
  31. package/dist/distill/adapters/chat-transcript.d.ts +15 -0
  32. package/dist/distill/adapters/chat-transcript.d.ts.map +1 -0
  33. package/dist/distill/adapters/chat-transcript.js +182 -0
  34. package/dist/distill/adapters/chat-transcript.js.map +1 -0
  35. package/dist/distill/adapters/types.d.ts +39 -0
  36. package/dist/distill/adapters/types.d.ts.map +1 -0
  37. package/dist/distill/adapters/types.js +7 -0
  38. package/dist/distill/adapters/types.js.map +1 -0
  39. package/dist/distill/chunk.d.ts +34 -0
  40. package/dist/distill/chunk.d.ts.map +1 -0
  41. package/dist/distill/chunk.js +46 -0
  42. package/dist/distill/chunk.js.map +1 -0
  43. package/dist/distill/cli.d.ts +13 -0
  44. package/dist/distill/cli.d.ts.map +1 -0
  45. package/dist/distill/cli.js +568 -0
  46. package/dist/distill/cli.js.map +1 -0
  47. package/dist/distill/cost.d.ts +105 -0
  48. package/dist/distill/cost.d.ts.map +1 -0
  49. package/dist/distill/cost.js +168 -0
  50. package/dist/distill/cost.js.map +1 -0
  51. package/dist/distill/extract.d.ts +44 -0
  52. package/dist/distill/extract.d.ts.map +1 -0
  53. package/dist/distill/extract.js +153 -0
  54. package/dist/distill/extract.js.map +1 -0
  55. package/dist/distill/index.d.ts +73 -0
  56. package/dist/distill/index.d.ts.map +1 -0
  57. package/dist/distill/index.js +112 -0
  58. package/dist/distill/index.js.map +1 -0
  59. package/dist/distill/output-fence.d.ts +16 -0
  60. package/dist/distill/output-fence.d.ts.map +1 -0
  61. package/dist/distill/output-fence.js +38 -0
  62. package/dist/distill/output-fence.js.map +1 -0
  63. package/dist/distill/propose.d.ts +95 -0
  64. package/dist/distill/propose.d.ts.map +1 -0
  65. package/dist/distill/propose.js +237 -0
  66. package/dist/distill/propose.js.map +1 -0
  67. package/dist/distill/state.d.ts +92 -0
  68. package/dist/distill/state.d.ts.map +1 -0
  69. package/dist/distill/state.js +198 -0
  70. package/dist/distill/state.js.map +1 -0
  71. package/dist/frontmatter/schema.d.ts.map +1 -1
  72. package/dist/frontmatter/schema.js +1 -0
  73. package/dist/frontmatter/schema.js.map +1 -1
  74. package/dist/frontmatter/types.d.ts +2 -1
  75. package/dist/frontmatter/types.d.ts.map +1 -1
  76. package/dist/frontmatter/types.js +1 -0
  77. package/dist/frontmatter/types.js.map +1 -1
  78. package/dist/interview/transcript.d.ts.map +1 -1
  79. package/dist/interview/transcript.js +1 -0
  80. package/dist/interview/transcript.js.map +1 -1
  81. package/dist/okf/map.d.ts.map +1 -1
  82. package/dist/okf/map.js +1 -0
  83. package/dist/okf/map.js.map +1 -1
  84. package/dist/server.d.ts.map +1 -1
  85. package/dist/server.js +2 -0
  86. package/dist/server.js.map +1 -1
  87. package/dist/sleep/cycle.d.ts +12 -0
  88. package/dist/sleep/cycle.d.ts.map +1 -1
  89. package/dist/sleep/cycle.js +98 -2
  90. package/dist/sleep/cycle.js.map +1 -1
  91. package/dist/sleep/index.d.ts.map +1 -1
  92. package/dist/sleep/index.js +14 -0
  93. package/dist/sleep/index.js.map +1 -1
  94. package/dist/sleep/report.d.ts.map +1 -1
  95. package/dist/sleep/report.js +31 -0
  96. package/dist/sleep/report.js.map +1 -1
  97. package/dist/sleep/run-ledger.d.ts +17 -0
  98. package/dist/sleep/run-ledger.d.ts.map +1 -0
  99. package/dist/sleep/run-ledger.js +119 -0
  100. package/dist/sleep/run-ledger.js.map +1 -0
  101. package/dist/sleep/runs-cli.d.ts +2 -0
  102. package/dist/sleep/runs-cli.d.ts.map +1 -0
  103. package/dist/sleep/runs-cli.js +69 -0
  104. package/dist/sleep/runs-cli.js.map +1 -0
  105. package/dist/tools/anchors.d.ts +12 -0
  106. package/dist/tools/anchors.d.ts.map +1 -0
  107. package/dist/tools/anchors.js +64 -0
  108. package/dist/tools/anchors.js.map +1 -0
  109. package/dist/tools/backlinks.d.ts +28 -0
  110. package/dist/tools/backlinks.d.ts.map +1 -0
  111. package/dist/tools/backlinks.js +207 -0
  112. package/dist/tools/backlinks.js.map +1 -0
  113. package/dist/tools/erase.d.ts +15 -0
  114. package/dist/tools/erase.d.ts.map +1 -0
  115. package/dist/tools/erase.js +127 -0
  116. package/dist/tools/erase.js.map +1 -0
  117. package/dist/tools/pin-mint.d.ts +49 -0
  118. package/dist/tools/pin-mint.d.ts.map +1 -0
  119. package/dist/tools/pin-mint.js +157 -0
  120. package/dist/tools/pin-mint.js.map +1 -0
  121. package/dist/tools/read.d.ts +22 -0
  122. package/dist/tools/read.d.ts.map +1 -1
  123. package/dist/tools/read.js +118 -1
  124. package/dist/tools/read.js.map +1 -1
  125. package/dist/tools/repin.d.ts +29 -0
  126. package/dist/tools/repin.d.ts.map +1 -0
  127. package/dist/tools/repin.js +140 -0
  128. package/dist/tools/repin.js.map +1 -0
  129. package/dist/tools/staged-actions.d.ts.map +1 -1
  130. package/dist/tools/staged-actions.js +102 -6
  131. package/dist/tools/staged-actions.js.map +1 -1
  132. package/dist/tools/write.d.ts +5 -0
  133. package/dist/tools/write.d.ts.map +1 -1
  134. package/dist/tools/write.js +87 -2
  135. package/dist/tools/write.js.map +1 -1
  136. package/dist/utils/config.d.ts +21 -0
  137. package/dist/utils/config.d.ts.map +1 -1
  138. package/dist/utils/config.js +116 -0
  139. package/dist/utils/config.js.map +1 -1
  140. package/dist/utils/git-erase.d.ts +35 -0
  141. package/dist/utils/git-erase.d.ts.map +1 -0
  142. package/dist/utils/git-erase.js +179 -0
  143. package/dist/utils/git-erase.js.map +1 -0
  144. package/dist/utils/git.d.ts +3 -0
  145. package/dist/utils/git.d.ts.map +1 -1
  146. package/dist/utils/git.js +29 -0
  147. package/dist/utils/git.js.map +1 -1
  148. package/dist/utils/vault-gitignore.d.ts +1 -1
  149. package/dist/utils/vault-gitignore.d.ts.map +1 -1
  150. package/dist/utils/vault-gitignore.js +5 -0
  151. package/dist/utils/vault-gitignore.js.map +1 -1
  152. package/package.json +1 -1
@@ -0,0 +1,64 @@
1
+ // src/tools/anchors.ts
2
+ // Pin classifier for JIT anchors (citation-anchors spec, Decision 2). Given one
3
+ // pinned `describes` binding and the code repo it resolves to, classify the pin
4
+ // against the current working tree using local git plumbing only — no network,
5
+ // no LLM. The read path attaches the result as an advisory annotation; nothing
6
+ // here mutates any file or state.
7
+ import { stat } from "node:fs/promises";
8
+ import { join } from "node:path";
9
+ import { readTextFile } from "../audit/readtext.js";
10
+ import { catFileBlob, hashObjectFile } from "../utils/git.js";
11
+ // At most this many pinned describes entries are classified per read/repin call —
12
+ // a fixed bound on the git work a single vault operation can trigger.
13
+ export const ANCHOR_PIN_CAP = 24;
14
+ // Classify one pin against `repoRoot`'s working tree. Returns null — meaning
15
+ // "cannot classify, skip this binding" — when the file exists but a git or read
16
+ // helper fails; the caller degrades a null to absent (no annotation entry),
17
+ // never surfacing a false state. `missing` and `moved` ARE classifications and
18
+ // are returned as such.
19
+ export async function classifyPin(repoRoot, relPath, pin) {
20
+ const absPath = join(repoRoot, relPath);
21
+ // Step 1 — target path absent from the working tree → missing.
22
+ try {
23
+ const st = await stat(absPath);
24
+ if (!st.isFile())
25
+ return { state: "missing" };
26
+ }
27
+ catch {
28
+ return { state: "missing" };
29
+ }
30
+ // Step 2 — current working-tree blob id; a pin-sha prefix match → intact
31
+ // (blob unchanged since the pin was written). A git failure on a file that
32
+ // exists is not a classification — skip.
33
+ const current = await hashObjectFile(repoRoot, relPath);
34
+ if (!current.ok)
35
+ return null;
36
+ if (current.value.startsWith(pin.sha))
37
+ return { state: "intact" };
38
+ // Blob differs from here on.
39
+ // Step 4 short-circuit — a whole-file pin (no range) over a differing blob is
40
+ // moved; there is no pinned line span to search for.
41
+ if (pin.start === null || pin.end === null)
42
+ return { state: "moved" };
43
+ // Step 3 — retrieve the pinned content and search the current file for it.
44
+ const pinnedBlob = await catFileBlob(repoRoot, pin.sha);
45
+ if (!pinnedBlob.ok)
46
+ return { state: "moved" }; // blob not in odb → moved
47
+ // 1-based inclusive line slice of the pinned content.
48
+ const pinnedLines = pinnedBlob.value.split("\n");
49
+ const block = pinnedLines.slice(pin.start - 1, pin.end).join("\n");
50
+ if (block.length === 0)
51
+ return { state: "moved" }; // range past the pinned content
52
+ const currentText = await readTextFile(absPath);
53
+ if (!currentText.ok)
54
+ return null; // guarded read rejected (too large / binary) → skip
55
+ const idx = currentText.value.text.indexOf(block);
56
+ if (idx === -1)
57
+ return { state: "moved" };
58
+ // Relocated line numbers: complete lines before the match = count of newlines
59
+ // in the preceding slice; the new 1-based start is that count + 1.
60
+ const newStart = (currentText.value.text.slice(0, idx).match(/\n/g)?.length ?? 0) + 1;
61
+ const span = pin.end - pin.start;
62
+ return { state: "intact", relocated: { start: newStart, end: newStart + span } };
63
+ }
64
+ //# sourceMappingURL=anchors.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"anchors.js","sourceRoot":"","sources":["../../src/tools/anchors.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,28 @@
1
+ import { type AccessContext } from "../access/rbac.js";
2
+ import { type Result } from "../frontmatter/types.js";
3
+ import type { ToolDefinition } from "./read.js";
4
+ export type BacklinkKind = "doc" | "code";
5
+ export interface DocBacklink {
6
+ doc: string;
7
+ via: "source" | "link";
8
+ }
9
+ export interface CodeBacklink {
10
+ doc: string;
11
+ raw: string;
12
+ repo: string;
13
+ path: string;
14
+ pin?: {
15
+ start: number | null;
16
+ end: number | null;
17
+ sha: string;
18
+ };
19
+ }
20
+ export interface BacklinksResult {
21
+ target: string;
22
+ kind: BacklinkKind;
23
+ references: (DocBacklink | CodeBacklink)[];
24
+ total: number;
25
+ }
26
+ export declare function vaultBacklinks(vaultRoot: string, args: Record<string, unknown>, access?: AccessContext): Promise<Result<BacklinksResult, Error>>;
27
+ export declare const backlinksTools: ToolDefinition[];
28
+ //# sourceMappingURL=backlinks.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"backlinks.d.ts","sourceRoot":"","sources":["../../src/tools/backlinks.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,KAAK,aAAa,EAAc,MAAM,mBAAmB,CAAC;AAKnE,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhD,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,MAAM,CAAC;AAG1C,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,QAAQ,GAAG,MAAM,CAAC;CACxB;AAGD,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,YAAY,CAAC;IACnB,UAAU,EAAE,CAAC,WAAW,GAAG,YAAY,CAAC,EAAE,CAAC;IAC3C,KAAK,EAAE,MAAM,CAAC;CACf;AAUD,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC,CAmFzC;AA0CD,eAAO,MAAM,cAAc,EAAE,cAAc,EAqD1C,CAAC"}
@@ -0,0 +1,207 @@
1
+ // vault_backlinks — the reverse of the knowledge graph. Given a target, list
2
+ // the documents that reference it. Two facets, inferred from the target:
3
+ // - doc facet: a vault-relative doc path → docs that cite it in `sources`
4
+ // ('source' edge) or link to it in their body ('link' edge). Computed from
5
+ // the same reverse maps blast-radius already builds, so the two cannot
6
+ // drift.
7
+ // - code facet: a repo code path (optionally `repo:path`) → docs whose
8
+ // `describes` frontmatter binds that file. Inverts the describes edges.
9
+ //
10
+ // Read-only, no mutation. RBAC mirrors vault_consumes: gate on any-read, then
11
+ // omit any referencing document the caller cannot read (plain omission, never
12
+ // redaction, never counted). A target that matches nothing returns an empty
13
+ // listing — identical to an unreadable or nonexistent one, no existence
14
+ // disclosure.
15
+ import { hasAnyRead } from "../access/rbac.js";
16
+ import { parseDescribesEntry } from "../audit/describes.js";
17
+ import { sourceReadable } from "../curation/tension-access.js";
18
+ import { buildReverseLinkMap, buildReverseSourceMap } from "../curation/tension-blast.js";
19
+ import { loadDocuments } from "../curation/vault-docs.js";
20
+ import { err, ok } from "../frontmatter/types.js";
21
+ import { canonicalVaultRelPath } from "../storage/local.js";
22
+ import { openIndexForAccessOrNull } from "./search.js";
23
+ // Split an optional `repo:` prefix off a code target. A path with no single
24
+ // leading colon segment resolves repo to null (match on path alone).
25
+ function splitCodeTarget(raw) {
26
+ const colon = raw.indexOf(":");
27
+ if (colon === -1)
28
+ return { repo: null, path: raw.trim() };
29
+ return { repo: raw.slice(0, colon).trim(), path: raw.slice(colon + 1).trim() };
30
+ }
31
+ export async function vaultBacklinks(vaultRoot, args, access) {
32
+ if (access && !hasAnyRead(access.role)) {
33
+ return err(new Error(`access denied: role '${access.roleName}' cannot use vault_backlinks`));
34
+ }
35
+ const targetRaw = args.target;
36
+ if (typeof targetRaw !== "string" || targetRaw.trim().length === 0) {
37
+ return err(new Error("vault_backlinks requires 'target' as a non-empty string"));
38
+ }
39
+ const target = targetRaw.trim();
40
+ let kind;
41
+ if (args.kind !== undefined && args.kind !== null) {
42
+ if (args.kind !== "doc" && args.kind !== "code") {
43
+ return err(new Error("vault_backlinks 'kind' must be 'doc' or 'code'"));
44
+ }
45
+ kind = args.kind;
46
+ }
47
+ const loaded = await loadDocuments(vaultRoot);
48
+ if (!loaded.ok)
49
+ return loaded;
50
+ const docs = loaded.value;
51
+ const docPaths = new Set(docs.map((d) => d.path));
52
+ // Infer the facet when not overridden: a target that resolves to an existing
53
+ // vault document is the doc facet; anything else is a code path.
54
+ let canonicalTarget = target;
55
+ if (kind === undefined) {
56
+ const canon = canonicalVaultRelPath(vaultRoot, target);
57
+ if (canon.ok && docPaths.has(canon.value)) {
58
+ kind = "doc";
59
+ canonicalTarget = canon.value;
60
+ }
61
+ else {
62
+ kind = "code";
63
+ }
64
+ }
65
+ else if (kind === "doc") {
66
+ const canon = canonicalVaultRelPath(vaultRoot, target);
67
+ if (canon.ok)
68
+ canonicalTarget = canon.value;
69
+ }
70
+ const db = access ? openIndexForAccessOrNull(vaultRoot) : null;
71
+ const readable = (docPath) => !access || sourceReadable(db, access, docPath);
72
+ try {
73
+ if (kind === "doc") {
74
+ const reverseSource = buildReverseSourceMap(docs);
75
+ const reverseLink = buildReverseLinkMap(docs);
76
+ const references = [];
77
+ for (const doc of reverseSource.get(canonicalTarget) ?? []) {
78
+ if (readable(doc))
79
+ references.push({ doc, via: "source" });
80
+ }
81
+ for (const doc of reverseLink.get(canonicalTarget) ?? []) {
82
+ if (readable(doc))
83
+ references.push({ doc, via: "link" });
84
+ }
85
+ references.sort((a, b) => a.doc.localeCompare(b.doc) || a.via.localeCompare(b.via));
86
+ return ok({ target: canonicalTarget, kind, references, total: references.length });
87
+ }
88
+ // code facet
89
+ const { repo: wantRepo, path: wantPath } = splitCodeTarget(target);
90
+ const references = [];
91
+ for (const d of docs) {
92
+ if (!readable(d.path))
93
+ continue;
94
+ for (const raw of d.frontmatter.describes ?? []) {
95
+ // sourceRepo is a config concept absent from a pure vault query; a bare
96
+ // entry keeps repo === "" and is matched on path alone.
97
+ const parsed = parseDescribesEntry(raw, "");
98
+ if (parsed.path.length === 0 || parsed.path !== wantPath)
99
+ continue;
100
+ if (wantRepo !== null && parsed.repo !== wantRepo)
101
+ continue;
102
+ references.push({
103
+ doc: d.path,
104
+ raw,
105
+ repo: parsed.repo,
106
+ path: parsed.path,
107
+ ...(parsed.pin ? { pin: parsed.pin } : {}),
108
+ });
109
+ }
110
+ }
111
+ references.sort((a, b) => a.doc.localeCompare(b.doc) || a.raw.localeCompare(b.raw));
112
+ return ok({ target, kind, references, total: references.length });
113
+ }
114
+ finally {
115
+ db?.close();
116
+ }
117
+ }
118
+ const docBacklinkSchema = {
119
+ type: "object",
120
+ properties: {
121
+ doc: { type: "string", description: "Vault-relative path of the referencing document" },
122
+ via: {
123
+ type: "string",
124
+ enum: ["source", "link"],
125
+ description: "'source': cited in frontmatter sources; 'link': linked in the body",
126
+ },
127
+ },
128
+ required: ["doc", "via"],
129
+ };
130
+ const codeBacklinkSchema = {
131
+ type: "object",
132
+ properties: {
133
+ doc: {
134
+ type: "string",
135
+ description: "Vault-relative path of the document that describes the file",
136
+ },
137
+ raw: { type: "string", description: "The describes entry exactly as written" },
138
+ repo: {
139
+ type: "string",
140
+ description: "Resolved repo name (empty for a bare, unqualified entry)",
141
+ },
142
+ path: { type: "string", description: "Repo-relative code path the entry resolved to" },
143
+ pin: {
144
+ type: "object",
145
+ description: "JIT anchor pin, present only when the entry carried a well-formed pin suffix",
146
+ properties: {
147
+ start: { type: ["integer", "null"] },
148
+ end: { type: ["integer", "null"] },
149
+ sha: { type: "string" },
150
+ },
151
+ required: ["start", "end", "sha"],
152
+ },
153
+ },
154
+ required: ["doc", "raw", "repo", "path"],
155
+ };
156
+ export const backlinksTools = [
157
+ {
158
+ name: "vault_backlinks",
159
+ title: "List documents that reference a target",
160
+ annotations: { readOnlyHint: true },
161
+ description: "The reverse of the knowledge graph: given a target, list the documents " +
162
+ "that reference it. The facet is inferred from the target (override with " +
163
+ "'kind'). A vault-relative DOC path returns docs that cite it in their " +
164
+ "'sources' ('source' edge) or link to it in their body ('link' edge). A " +
165
+ "repo CODE path (optionally 'repo:path') returns docs whose 'describes' " +
166
+ "frontmatter binds that file — 'which beliefs touch this file'. Read-only; " +
167
+ "an unreadable referencing document is omitted from the list and the count.",
168
+ inputSchema: {
169
+ type: "object",
170
+ properties: {
171
+ target: {
172
+ type: "string",
173
+ description: "A vault-relative doc path, or a repo code path (optionally 'repo:path')",
174
+ },
175
+ kind: {
176
+ type: "string",
177
+ enum: ["doc", "code"],
178
+ description: "Override the inferred facet: 'doc' (vault doc target) or 'code' (code file)",
179
+ },
180
+ },
181
+ required: ["target"],
182
+ additionalProperties: false,
183
+ },
184
+ outputSchema: {
185
+ type: "object",
186
+ properties: {
187
+ target: {
188
+ type: "string",
189
+ description: "The resolved target (canonicalized for the doc facet)",
190
+ },
191
+ kind: { type: "string", enum: ["doc", "code"], description: "Which facet ran" },
192
+ references: {
193
+ type: "array",
194
+ items: { anyOf: [docBacklinkSchema, codeBacklinkSchema] },
195
+ },
196
+ total: {
197
+ type: "integer",
198
+ description: "Number of listed references. An unreadable referencing document is " +
199
+ "omitted from the list AND from this count (plain omission).",
200
+ },
201
+ },
202
+ required: ["target", "kind", "references", "total"],
203
+ },
204
+ handler: (vaultRoot, args, access) => vaultBacklinks(vaultRoot, args, access),
205
+ },
206
+ ];
207
+ //# sourceMappingURL=backlinks.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"backlinks.js","sourceRoot":"","sources":["../../src/tools/backlinks.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,15 @@
1
+ import type { AccessContext } from "../access/rbac.js";
2
+ import { type Result } from "../frontmatter/types.js";
3
+ import { type GitEraseDeps } from "../utils/git-erase.js";
4
+ export interface EraseOutcome {
5
+ /** Vault-relative paths that were scrubbed. Empty when the erase was refused. */
6
+ erased: string[];
7
+ /** Anything the scrub could not guarantee (see EraseResult.incomplete). */
8
+ incomplete: string[];
9
+ /** True when the history op was refused (filter-repo absent) — nothing erased. */
10
+ refused: boolean;
11
+ /** Present only when the target looks secret-shaped: rotate-first guidance. */
12
+ guidance?: string;
13
+ }
14
+ export declare function vaultErase(vaultRoot: string, args: Record<string, unknown>, access?: AccessContext, deps?: GitEraseDeps): Promise<Result<EraseOutcome, Error>>;
15
+ //# sourceMappingURL=erase.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"erase.d.ts","sourceRoot":"","sources":["../../src/tools/erase.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvD,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE5E,MAAM,WAAW,YAAY;IAC3B,iFAAiF;IACjF,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,kFAAkF;IAClF,OAAO,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA4CD,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,CAAC,EAAE,aAAa,EACtB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC,CAqFtC"}
@@ -0,0 +1,127 @@
1
+ // src/tools/erase.ts
2
+ //
3
+ // vault_erase — a path/source-keyed history scrub for the accidental sensitive
4
+ // commit (R11-R13). This is the deliberate, destructive counterpart to
5
+ // distill-and-discard: distill-and-discard keeps raw from LANDING; vault_erase
6
+ // removes something that already landed, from the git history, not just the
7
+ // worktree.
8
+ //
9
+ // Guardrails, in order:
10
+ // 1. RBAC — the caller's role must hold the `erase` capability (off by default).
11
+ // 2. Target — exactly one of `path` or `source_ref`.
12
+ // 3. Confirmation — `confirm` must echo the target string exactly.
13
+ // Only then does it dispatch the history rewrite (src/utils/git-erase.ts) and
14
+ // append a content-free receipt to .daftari/erasures.jsonl. For a secret-shaped
15
+ // target it returns rotate-first guidance: a history rewrite cannot un-disclose
16
+ // what was already pushed.
17
+ import { appendFile, mkdir } from "node:fs/promises";
18
+ import { join } from "node:path";
19
+ import { canErase } from "../access/rbac.js";
20
+ import { loadDocuments } from "../curation/vault-docs.js";
21
+ import { err, ok } from "../frontmatter/types.js";
22
+ import { eraseFromHistory } from "../utils/git-erase.js";
23
+ // A conservative "does this look like a secret?" heuristic — errs toward
24
+ // warning. It gates only GUIDANCE (never the erase itself), so a false positive
25
+ // costs a rotate-first sentence, never a blocked scrub.
26
+ function looksSecretShaped(s) {
27
+ return (/(?:secret|token|passw(?:or)?d|credential|api[-_]?key|private[-_]?key)/i.test(s) ||
28
+ /-----BEGIN [A-Z ]+PRIVATE KEY-----/.test(s) ||
29
+ /\b[A-Za-z0-9+/]{32,}={0,2}\b/.test(s));
30
+ }
31
+ async function resolveSourceRefToPaths(vaultRoot, sourceRef) {
32
+ const loaded = await loadDocuments(vaultRoot);
33
+ if (!loaded.ok)
34
+ return loaded;
35
+ const paths = loaded.value
36
+ .filter((d) => (d.frontmatter.sources ?? []).includes(sourceRef))
37
+ .map((d) => d.path);
38
+ return ok(paths);
39
+ }
40
+ // A content-free receipt line: the path (a breadcrumb, not the erased content),
41
+ // the principal, the instant, and what remained incomplete. Appended to an
42
+ // audit log so an erase is itself an auditable event.
43
+ async function appendReceipt(vaultRoot, record) {
44
+ const dir = join(vaultRoot, ".daftari");
45
+ await mkdir(dir, { recursive: true });
46
+ const line = `${JSON.stringify({
47
+ kind: record.refused ? "erasure_refused" : "erasure",
48
+ at: new Date().toISOString(),
49
+ principal: record.principal,
50
+ paths: record.erased,
51
+ incomplete: record.incomplete,
52
+ })}\n`;
53
+ await appendFile(join(dir, "erasures.jsonl"), line, "utf8");
54
+ }
55
+ export async function vaultErase(vaultRoot, args, access, deps = {}) {
56
+ // 1. RBAC: the most destructive capability, checked first — and FAIL-CLOSED.
57
+ // Every softer tool defaults to allow when no access context is present;
58
+ // erase does not. An irreversible history rewrite + force-push is the one tool
59
+ // where a missing identity must DENY, so a future wiring cannot inherit a
60
+ // silent fail-open.
61
+ if (!access) {
62
+ return err(new Error("vault_erase requires an authenticated access context (fail-closed — no default)"));
63
+ }
64
+ if (!canErase(access.role)) {
65
+ return err(new Error(`access denied: role '${access.roleName}' cannot erase from history`));
66
+ }
67
+ // 2. Exactly one target.
68
+ const path = typeof args.path === "string" ? args.path : undefined;
69
+ const sourceRef = typeof args.source_ref === "string" ? args.source_ref : undefined;
70
+ if ((path && sourceRef) || (!path && !sourceRef)) {
71
+ return err(new Error("vault_erase requires exactly one of 'path' or 'source_ref'"));
72
+ }
73
+ const target = (path ?? sourceRef);
74
+ // 3. Confirmation: the caller must echo the exact target — a typo aborts. The
75
+ // expected value is NOT echoed in the error, so an agent caller cannot copy it
76
+ // verbatim on retry (the confirmation must come from the caller's own intent).
77
+ const confirm = typeof args.confirm === "string" ? args.confirm : undefined;
78
+ if (confirm !== target) {
79
+ return err(new Error("vault_erase aborted: 'confirm' did not match — re-issue with 'confirm' set to the exact " +
80
+ "path or source_ref you intend to erase (the expected value is not echoed here on purpose)"));
81
+ }
82
+ // Resolve to the concrete path set to scrub.
83
+ let paths;
84
+ if (path !== undefined) {
85
+ paths = [path];
86
+ }
87
+ else {
88
+ const resolved = await resolveSourceRefToPaths(vaultRoot, sourceRef);
89
+ if (!resolved.ok)
90
+ return resolved;
91
+ if (resolved.value.length === 0) {
92
+ return err(new Error(`vault_erase: no documents cite source_ref '${sourceRef}'`));
93
+ }
94
+ paths = resolved.value;
95
+ }
96
+ const scrub = await eraseFromHistory(vaultRoot, paths, deps);
97
+ if (!scrub.ok)
98
+ return scrub;
99
+ const { refused } = scrub.value;
100
+ const incomplete = [...scrub.value.incomplete];
101
+ // H3: source_ref resolves against the CURRENT worktree only — history copies
102
+ // of docs that cited the ref but were later deleted/superseded are not
103
+ // covered. Say so loudly; those must be erased by path per historical name.
104
+ if (sourceRef !== undefined) {
105
+ incomplete.push("source-ref: resolved against the current worktree only — history copies of deleted or " +
106
+ "superseded docs citing this ref are NOT covered; erase those by path");
107
+ }
108
+ // On refuse, nothing was erased — the result must not read as a success.
109
+ const erased = refused ? [] : scrub.value.paths;
110
+ await appendReceipt(vaultRoot, {
111
+ erased,
112
+ incomplete,
113
+ principal: access.user,
114
+ refused,
115
+ });
116
+ const guidance = looksSecretShaped(target)
117
+ ? "The erased target looks secret-shaped: a history rewrite cannot un-disclose what was " +
118
+ "already pushed or cloned. ROTATE the secret now, then treat the old value as compromised."
119
+ : undefined;
120
+ return ok({
121
+ erased,
122
+ incomplete,
123
+ refused,
124
+ ...(guidance ? { guidance } : {}),
125
+ });
126
+ }
127
+ //# sourceMappingURL=erase.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"erase.js","sourceRoot":"","sources":["../../src/tools/erase.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,49 @@
1
+ export interface MintedEntry {
2
+ /** The original (input) entry string. */
3
+ entry: string;
4
+ /** The rewritten entry with the @sha12 pin appended. */
5
+ pinned: string;
6
+ /** True when the blob is reachable in the odb (was committed); false when
7
+ * minted from uncommitted working-tree bytes. */
8
+ committed: boolean;
9
+ }
10
+ export interface UnresolvedEntry {
11
+ /** The original (input) entry string. */
12
+ entry: string;
13
+ /** Human-readable reason the entry could not be minted. */
14
+ reason: string;
15
+ }
16
+ export interface MintOutcome {
17
+ /** The (possibly enriched) entry array, parallel to the input. */
18
+ entries: string[];
19
+ /** One record per entry that was successfully minted. */
20
+ minted: MintedEntry[];
21
+ /** One record per entry that could not be minted. */
22
+ unresolved: UnresolvedEntry[];
23
+ }
24
+ /**
25
+ * Build the minted entry string: `<head>#L<start>-<end>@<sha12>`.
26
+ * `head` is the portion of the entry before any `#L` tail (may include a
27
+ * `::symbol` suffix). `sha` should be exactly 12 hex characters.
28
+ */
29
+ export declare function formatPin(head: string, start: number, end: number, sha: string): string;
30
+ /**
31
+ * Enrich shaless `describes` entries with a working-tree blob sha prefix.
32
+ *
33
+ * For each entry:
34
+ * - If it already has a pin (`@sha` tail) or no `#L` tail → pass through
35
+ * (not counted in minted or unresolved).
36
+ * - If it has a `#L<start>[-<end>]` tail with no `@sha`:
37
+ * - Look up `repo` in `cfg.codeRepos`; absent → unresolved ("no configured repo").
38
+ * - Validate line numbers; end < start → unresolved ("inverted range").
39
+ * - Call `hashObjectFile`; failure (path absent, repo absent, etc.) → unresolved.
40
+ * - Rewrite to `<head>#L<start>-<end>@<sha12>`; check blob presence (committed flag).
41
+ *
42
+ * When `jitAnchors === false` the function returns the input array unchanged
43
+ * with empty minted/unresolved lists (kill-switch, R2 advisory posture).
44
+ *
45
+ * This function is pure with respect to the vault and any code repos —
46
+ * no file is written anywhere (R7).
47
+ */
48
+ export declare function mintDescribesPins(vaultRoot: string, entries: string[]): Promise<MintOutcome>;
49
+ //# sourceMappingURL=pin-mint.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"pin-mint.d.ts","sourceRoot":"","sources":["../../src/tools/pin-mint.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf;sDACkD;IAClD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yDAAyD;IACzD,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,qDAAqD;IACrD,UAAU,EAAE,eAAe,EAAE,CAAC;CAC/B;AAMD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvF;AAcD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,WAAW,CAAC,CAoHtB"}