djournal 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/recall.md ADDED
@@ -0,0 +1,102 @@
1
+ # Fast Recall
2
+
3
+ Recall finds the journal files most likely to answer a question before anyone
4
+ spends time opening and summarizing them. It can be used directly as a small
5
+ search CLI, or indirectly through an agent that has djournal's `recall` skill.
6
+ Both paths use the same local index and keep Markdown as the source of truth.
7
+
8
+ ## Use it as a standalone CLI
9
+
10
+ From an installed project, search in plain-text mode:
11
+
12
+ ```bash
13
+ djournal recall search "why did we choose webhook retries"
14
+ ```
15
+
16
+ The output ranks matching work items and entries by score and prints their
17
+ canonical `.journal/...` paths. Use JSON when another script or tool will consume
18
+ the results:
19
+
20
+ ```bash
21
+ djournal recall search "webhook retries" --type decision,research --limit 5 --json
22
+ ```
23
+
24
+ Available filters narrow results without changing the journal:
25
+
26
+ ```bash
27
+ djournal recall search "checkout" \
28
+ --work 2026-08-14-01-checkout \
29
+ --kind entry \
30
+ --status active \
31
+ --visibility team_shared
32
+ ```
33
+
34
+ The first search builds the private index automatically. Prebuilding is useful
35
+ after importing a large journal, and rebuilding is available for diagnostics:
36
+
37
+ ```bash
38
+ djournal recall index
39
+ djournal recall index --rebuild
40
+ ```
41
+
42
+ For a strictly no-write invocation, use an ephemeral index:
43
+
44
+ ```bash
45
+ djournal recall search "onboarding decisions" --no-cache --json
46
+ ```
47
+
48
+ CLI recall returns evidence candidates, not a generated answer. A human or
49
+ calling program decides which returned Markdown files to read next.
50
+
51
+ ## Use it through an agent
52
+
53
+ Install djournal for the agent harness you use:
54
+
55
+ ```bash
56
+ djournal install --harness codex
57
+ # or: --harness claude-code
58
+ # or: --harness pi
59
+ ```
60
+
61
+ Then ask naturally:
62
+
63
+ ```text
64
+ Recall why we chose the current billing webhook retry strategy.
65
+ ```
66
+
67
+ The `recall` skill classifies the question, calls the same CLI with `--json`,
68
+ uses the ranked paths to select a small evidence set, and reads those canonical
69
+ Markdown files before answering. It follows relevant entry links and starts
70
+ from the latest spine entry when the question needs chronology or current
71
+ status. Its final response includes the journal sources that support the answer.
72
+
73
+ If the CLI is unavailable or the cache cannot produce candidates, the skill
74
+ falls back to filesystem discovery. Recall remains read-only in either path: it
75
+ does not create entries, share work, sync, commit, or push.
76
+
77
+ ## What happens on each call
78
+
79
+ There is no daemon. Each invocation loads the serialized MiniSearch snapshot,
80
+ checks source-file metadata, refreshes changed documents, searches in memory,
81
+ and exits. Warm calls avoid reparsing unchanged Markdown; additions, edits,
82
+ renames, and deletions are reconciled before results are returned.
83
+
84
+ The persistent snapshot lives at:
85
+
86
+ ```text
87
+ ~/.djournal/projects/<project-key>/cache/recall/snapshot.json
88
+ ```
89
+
90
+ It sits outside `.journal/`, so it is not canonical history and is never shared.
91
+ If it is missing, incompatible, malformed, or unwritable, recall rebuilds it or
92
+ continues in memory for the current call. Removing `cache/recall/` is safe.
93
+
94
+ Inspect cache health with:
95
+
96
+ ```bash
97
+ djournal status
98
+ djournal doctor
99
+ ```
100
+
101
+ For the storage and freshness model, see [Architecture and data model](architecture.md).
102
+ For remote readers, see [Read-only team journal access](read-only-team-journal.md).
@@ -587,6 +587,17 @@ function readActiveWork(context, requested) {
587
587
  return { slug, relative, file, text, metadata, visibility: metadata.visibility || "local_only" };
588
588
  }
589
589
 
590
+ function workSummary(context, slug) {
591
+ const work = readActiveWork(context, slug);
592
+ return {
593
+ slug: work.slug,
594
+ title: work.metadata.title || work.slug,
595
+ status: work.metadata.status || "unknown",
596
+ visibility: work.visibility,
597
+ selected: false,
598
+ };
599
+ }
600
+
590
601
  function readAllWork(context) {
591
602
  const workRoot = path.join(context.journalRoot, "work");
592
603
  const entries = fs.existsSync(workRoot) ? fs.readdirSync(workRoot, { withFileTypes: true }) : [];
@@ -600,6 +611,53 @@ function readAllWork(context) {
600
611
  return workItems;
601
612
  }
602
613
 
614
+ function selectedWorkSlug(context) {
615
+ const state = parseJson(readOptional(path.join(context.journalRoot, "state.json")), ".journal/state.json");
616
+ return typeof state.active_work_name === "string" ? state.active_work_name : "";
617
+ }
618
+
619
+ function listWork(options) {
620
+ const target = checkTarget(options.target || process.cwd());
621
+ const context = projectContext(target, options);
622
+ const selected = selectedWorkSlug(context);
623
+ const workItems = readAllWork(context)
624
+ .map((work) => ({
625
+ slug: work.slug,
626
+ title: work.metadata.title || work.slug,
627
+ status: work.metadata.status || "unknown",
628
+ visibility: work.visibility,
629
+ selected: work.slug === selected,
630
+ }));
631
+ const filtered = options.active ? workItems.filter((work) => work.status === "active") : workItems;
632
+ return { action: "work-list", target, projectKey: context.projectKey, selected: selected || undefined, workItems: filtered };
633
+ }
634
+
635
+ function sessionId(options = {}) {
636
+ return options.session || process.env.DJOURNAL_SESSION_ID || "";
637
+ }
638
+
639
+ function sessionBindingFile(context, id) {
640
+ if (typeof id !== "string" || !id.trim()) throw new InstallerError("--session or DJOURNAL_SESSION_ID is required", "SESSION_REQUIRED");
641
+ return path.join(context.root, "sessions", `${sha256(id.trim())}.json`);
642
+ }
643
+
644
+ function bindWork(options) {
645
+ const target = checkTarget(options.target || process.cwd());
646
+ const context = projectContext(target, options);
647
+ const work = workSummary(context, options.work);
648
+ if (work.status !== "active") throw new InstallerError(`work item is not active: ${work.slug}`, "INVALID_WORK");
649
+ const id = sessionId(options);
650
+ const file = sessionBindingFile(context, id);
651
+ const binding = {
652
+ schemaVersion: SCHEMA_VERSION,
653
+ sessionHash: sha256(id.trim()),
654
+ activeWorkName: work.slug,
655
+ updatedAt: new Date().toISOString(),
656
+ };
657
+ if (!options.dryRun) writeJsonFile(file, binding);
658
+ return { action: "work-bind", target, projectKey: context.projectKey, work: work.slug, sessionHash: binding.sessionHash, dryRun: !!options.dryRun };
659
+ }
660
+
603
661
  function readJournalConfig(target) {
604
662
  const context = projectContext(target);
605
663
  return readProjectConfig(context);
@@ -1154,7 +1212,16 @@ function doctor(options) {
1154
1212
  detail: `${assetStatus}; Pi project trust required`,
1155
1213
  });
1156
1214
  }
1157
- return { ok: checks.every((check) => check.ok), target, detected, checks };
1215
+ const { inspectSnapshot } = require("../recall/snapshot.js");
1216
+ const recallCache = inspectSnapshot(projectContext(target, options), options);
1217
+ checks.push({
1218
+ name: "recall cache",
1219
+ ok: true,
1220
+ detail: recallCache.valid
1221
+ ? `${recallCache.documentCount} documents; ${recallCache.indexVersion}; ${recallCache.builtAt}`
1222
+ : (recallCache.exists ? "invalid but recoverable on next recall" : "not built; created on first recall"),
1223
+ });
1224
+ return { ok: checks.every((check) => check.ok), target, detected, recallCache, checks };
1158
1225
  }
1159
1226
 
1160
1227
  async function install(options) {
@@ -1303,7 +1370,10 @@ function recordStatus(target, record) {
1303
1370
  function status(options) {
1304
1371
  const target = checkTarget(options.target || process.cwd());
1305
1372
  const manifest = loadManifest(target);
1306
- const config = readProjectConfig(projectContext(target, options));
1373
+ const context = projectContext(target, options);
1374
+ const config = readProjectConfig(context);
1375
+ const { inspectSnapshot } = require("../recall/snapshot.js");
1376
+ const recallCache = inspectSnapshot(context, options);
1307
1377
  const cache = readUpdateCache(options);
1308
1378
  const updateState = deriveUpdateState({
1309
1379
  cliVersion: packageVersion(packageSourceRoot(options)),
@@ -1311,7 +1381,7 @@ function status(options) {
1311
1381
  cache,
1312
1382
  });
1313
1383
  const updateChecksEnabled = passiveChecksEnabled(config, options.env || process.env, { allowTest: options.allowTest });
1314
- if (!manifest) return { installed: false, target, ...updateState, updateChecksEnabled };
1384
+ if (!manifest) return { installed: false, target, ...updateState, updateChecksEnabled, recallCache };
1315
1385
  const files = manifest.files.map((record) => ({ path: record.path, mode: record.mode, status: recordStatus(target, record) }));
1316
1386
  return {
1317
1387
  installed: true,
@@ -1319,6 +1389,7 @@ function status(options) {
1319
1389
  toolVersion: manifest.toolVersion,
1320
1390
  ...updateState,
1321
1391
  updateChecksEnabled,
1392
+ recallCache,
1322
1393
  harnesses: manifest.harnesses,
1323
1394
  files,
1324
1395
  clean: files.every((file) => file.status === "clean"),
@@ -1360,12 +1431,14 @@ module.exports = {
1360
1431
  SUPPORTED_HARNESSES,
1361
1432
  applyTransaction,
1362
1433
  checkUpdates,
1434
+ bindWork,
1363
1435
  configure,
1364
1436
  detectHarnesses,
1365
1437
  doctor,
1366
1438
  djournalHome,
1367
1439
  install,
1368
1440
  loadManifest,
1441
+ listWork,
1369
1442
  pull,
1370
1443
  projectContext,
1371
1444
  recoverTransaction,
@@ -0,0 +1,327 @@
1
+ "use strict";
2
+
3
+ const crypto = require("node:crypto");
4
+ const fs = require("node:fs");
5
+ const path = require("node:path");
6
+ const YAML = require("yaml");
7
+
8
+ const ENTRY_DIRECTORIES = ["journal", "_research", "docs", "decisions"];
9
+ const MAX_MARKDOWN_BYTES = 16 * 1024 * 1024;
10
+
11
+ class RecallCorpusError extends Error {
12
+ constructor(message, code = "RECALL_CORPUS_ERROR") {
13
+ super(message);
14
+ this.name = "RecallCorpusError";
15
+ this.code = code;
16
+ }
17
+ }
18
+
19
+ function sha256(value) {
20
+ return crypto.createHash("sha256").update(value).digest("hex");
21
+ }
22
+
23
+ function posix(relative) {
24
+ return relative.split(path.sep).join("/");
25
+ }
26
+
27
+ function fingerprint(stat) {
28
+ return { size: stat.size, mtimeMs: stat.mtimeMs };
29
+ }
30
+
31
+ function sameFingerprint(left, right) {
32
+ return Boolean(left && right && left.size === right.size && left.mtimeMs === right.mtimeMs);
33
+ }
34
+
35
+ function assertWithin(root, candidate) {
36
+ const boundary = path.resolve(root);
37
+ const resolved = path.resolve(candidate);
38
+ if (resolved !== boundary && !resolved.startsWith(`${boundary}${path.sep}`)) {
39
+ throw new RecallCorpusError(`journal path escapes canonical root: ${candidate}`, "UNSAFE_PATH");
40
+ }
41
+ return resolved;
42
+ }
43
+
44
+ function listMarkdown(directory, journalRoot, workSlug, area, warnings, result) {
45
+ let entries;
46
+ try { entries = fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)); }
47
+ catch (error) {
48
+ if (error.code === "ENOENT") return;
49
+ throw error;
50
+ }
51
+ for (const entry of entries) {
52
+ const absolute = assertWithin(journalRoot, path.join(directory, entry.name));
53
+ if (entry.isSymbolicLink()) {
54
+ warnings.push({ code: "SYMLINK_IGNORED", path: posix(path.relative(journalRoot, absolute)) });
55
+ continue;
56
+ }
57
+ if (entry.isDirectory()) {
58
+ listMarkdown(absolute, journalRoot, workSlug, area, warnings, result);
59
+ continue;
60
+ }
61
+ if (!entry.isFile() || path.extname(entry.name).toLowerCase() !== ".md") continue;
62
+ const stat = fs.lstatSync(absolute);
63
+ if (!stat.isFile() || stat.isSymbolicLink()) continue;
64
+ result.push({
65
+ absolute,
66
+ relative: posix(path.relative(journalRoot, absolute)),
67
+ workSlug,
68
+ area,
69
+ kind: "entry",
70
+ ...fingerprint(stat),
71
+ });
72
+ }
73
+ }
74
+
75
+ function discoverSourceFiles(context) {
76
+ const journalRoot = path.resolve(context.journalRoot);
77
+ const workRoot = path.join(journalRoot, "work");
78
+ const warnings = [];
79
+ const files = [];
80
+ let workDirectories = [];
81
+ try { workDirectories = fs.readdirSync(workRoot, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)); }
82
+ catch (error) { if (error.code !== "ENOENT") throw error; }
83
+
84
+ for (const entry of workDirectories) {
85
+ if (!entry.isDirectory() || entry.isSymbolicLink()) {
86
+ if (entry.isSymbolicLink()) warnings.push({ code: "SYMLINK_IGNORED", path: `work/${entry.name}` });
87
+ continue;
88
+ }
89
+ const workDirectory = assertWithin(journalRoot, path.join(workRoot, entry.name));
90
+ const workFile = path.join(workDirectory, "work.md");
91
+ try {
92
+ const stat = fs.lstatSync(workFile);
93
+ if (stat.isFile() && !stat.isSymbolicLink()) {
94
+ files.push({
95
+ absolute: workFile,
96
+ relative: posix(path.relative(journalRoot, workFile)),
97
+ workSlug: entry.name,
98
+ area: "work",
99
+ kind: "work",
100
+ ...fingerprint(stat),
101
+ });
102
+ }
103
+ } catch (error) { if (error.code !== "ENOENT") throw error; }
104
+ for (const area of ENTRY_DIRECTORIES) {
105
+ listMarkdown(path.join(workDirectory, area), journalRoot, entry.name, area, warnings, files);
106
+ }
107
+ }
108
+ return { files: files.sort((a, b) => a.relative.localeCompare(b.relative)), warnings };
109
+ }
110
+
111
+ function stableRead(descriptor) {
112
+ for (let attempt = 0; attempt < 2; attempt += 1) {
113
+ const before = fs.lstatSync(descriptor.absolute);
114
+ if (!before.isFile() || before.isSymbolicLink()) {
115
+ throw new RecallCorpusError(`source is not a regular file: ${descriptor.relative}`, "UNSAFE_PATH");
116
+ }
117
+ if (before.size > MAX_MARKDOWN_BYTES) {
118
+ throw new RecallCorpusError(`journal file exceeds ${MAX_MARKDOWN_BYTES} bytes: ${descriptor.relative}`, "RECALL_FILE_TOO_LARGE");
119
+ }
120
+ const buffer = fs.readFileSync(descriptor.absolute);
121
+ const after = fs.lstatSync(descriptor.absolute);
122
+ if (sameFingerprint(fingerprint(before), fingerprint(after))) {
123
+ return { buffer, stat: fingerprint(after), sha256: sha256(buffer) };
124
+ }
125
+ }
126
+ throw new RecallCorpusError(`journal file changed while indexing: ${descriptor.relative}`, "RECALL_SOURCE_CHANGED");
127
+ }
128
+
129
+ function parseMarkdown(buffer, relative, warnings) {
130
+ const text = buffer.toString("utf8");
131
+ if (!text.startsWith("---\n") && !text.startsWith("---\r\n")) return { metadata: {}, body: text };
132
+ const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
133
+ if (!match) {
134
+ warnings.push({ code: "MALFORMED_FRONTMATTER", path: relative, detail: "unterminated" });
135
+ return { metadata: {}, body: text };
136
+ }
137
+ try {
138
+ const metadata = YAML.parse(match[1]) || {};
139
+ return { metadata: typeof metadata === "object" && !Array.isArray(metadata) ? metadata : {}, body: text.slice(match[0].length) };
140
+ } catch (error) {
141
+ warnings.push({ code: "MALFORMED_FRONTMATTER", path: relative, detail: error.message.split("\n")[0] });
142
+ return { metadata: {}, body: text.slice(match[0].length) };
143
+ }
144
+ }
145
+
146
+ function firstHeading(body, fallback) {
147
+ const match = body.match(/^#\s+(.+)$/m);
148
+ return match ? match[1].trim() : fallback;
149
+ }
150
+
151
+ function headings(body) {
152
+ return [...body.matchAll(/^#{1,6}\s+(.+)$/gm)].map((match) => match[1].trim()).join("\n");
153
+ }
154
+
155
+ function legacyTitle(relative) {
156
+ return path.basename(relative, path.extname(relative))
157
+ .replace(/^\d{4}-\d{2}-\d{2}-\d{2}-/, "")
158
+ .replace(/[-_]+/g, " ")
159
+ .replace(/\b\w/g, (letter) => letter.toUpperCase());
160
+ }
161
+
162
+ function scalar(value, fallback = "") {
163
+ return typeof value === "string" || typeof value === "number" ? String(value) : fallback;
164
+ }
165
+
166
+ function normalizeLinks(value) {
167
+ if (!Array.isArray(value)) return [];
168
+ return value.filter((link) => link && typeof link === "object").map((link) => ({
169
+ id: scalar(link.id),
170
+ fromEntryId: scalar(link.fromEntryId),
171
+ toEntryId: scalar(link.toEntryId),
172
+ relation: scalar(link.relation),
173
+ createdAt: scalar(link.createdAt),
174
+ targetPath: scalar(link.targetPath),
175
+ }));
176
+ }
177
+
178
+ function inferredEntryType(area, relative) {
179
+ if (area === "decisions") return "decision";
180
+ if (area === "docs") return "doc";
181
+ if (area === "_research") return "research";
182
+ const name = path.basename(relative).toLowerCase();
183
+ if (name.includes("plan")) return "plan";
184
+ if (name.includes("status")) return "status";
185
+ return "manual";
186
+ }
187
+
188
+ function rawId(kind, metadata, relative) {
189
+ const value = scalar(metadata.id);
190
+ return value || `path_${sha256(relative).slice(0, 24)}`;
191
+ }
192
+
193
+ function logicalPath(relative) {
194
+ return `.journal/${posix(relative)}`;
195
+ }
196
+
197
+ function readWorkContexts(files, warnings) {
198
+ const result = new Map();
199
+ for (const descriptor of files.filter((file) => file.kind === "work")) {
200
+ const read = stableRead(descriptor);
201
+ const parsed = parseMarkdown(read.buffer, descriptor.relative, warnings);
202
+ const metadata = parsed.metadata;
203
+ result.set(descriptor.workSlug, {
204
+ descriptor,
205
+ read,
206
+ metadata,
207
+ body: parsed.body,
208
+ workItemId: scalar(metadata.id),
209
+ title: scalar(metadata.title, descriptor.workSlug),
210
+ description: scalar(metadata.description),
211
+ status: scalar(metadata.status, "unknown"),
212
+ visibility: scalar(metadata.visibility, "local_only"),
213
+ });
214
+ }
215
+ return result;
216
+ }
217
+
218
+ function documentFromDescriptor(descriptor, workContexts, warnings, existingRead) {
219
+ const work = workContexts.get(descriptor.workSlug) || {
220
+ workItemId: "",
221
+ title: descriptor.workSlug,
222
+ description: "",
223
+ status: "unknown",
224
+ visibility: "local_only",
225
+ };
226
+ const read = existingRead || stableRead(descriptor);
227
+ const parsed = descriptor.kind === "work" && work.descriptor?.relative === descriptor.relative
228
+ ? { metadata: work.metadata, body: work.body }
229
+ : parseMarkdown(read.buffer, descriptor.relative, warnings);
230
+ const metadata = parsed.metadata;
231
+ const fallbackTitle = legacyTitle(descriptor.relative);
232
+ const itemId = rawId(descriptor.kind, metadata, descriptor.relative);
233
+ const kind = descriptor.kind;
234
+ const entryType = kind === "entry" ? scalar(metadata.entryType, inferredEntryType(descriptor.area, descriptor.relative)) : "work";
235
+ return {
236
+ document: {
237
+ id: `${kind}:${itemId}`,
238
+ rawId: scalar(metadata.id, itemId),
239
+ kind,
240
+ path: logicalPath(descriptor.relative),
241
+ sourceRelative: descriptor.relative,
242
+ workSlug: descriptor.workSlug,
243
+ workItemId: kind === "work" ? scalar(metadata.id, work.workItemId) : scalar(metadata.workItemId, work.workItemId),
244
+ workTitle: kind === "work" ? scalar(metadata.title, work.title) : work.title,
245
+ workDescription: kind === "work" ? scalar(metadata.description, work.description) : work.description,
246
+ title: scalar(metadata.title, firstHeading(parsed.body, fallbackTitle)),
247
+ summary: scalar(metadata.summary, kind === "work" ? scalar(metadata.description) : ""),
248
+ headings: headings(parsed.body),
249
+ body: parsed.body,
250
+ entryType,
251
+ status: work.status,
252
+ visibility: work.visibility,
253
+ createdAt: scalar(metadata.createdAt),
254
+ updatedAt: scalar(metadata.updatedAt),
255
+ links: normalizeLinks(metadata.links),
256
+ incomingLinks: [],
257
+ },
258
+ manifest: {
259
+ size: read.stat.size,
260
+ mtimeMs: read.stat.mtimeMs,
261
+ sha256: read.sha256,
262
+ documentId: `${kind}:${itemId}`,
263
+ workSlug: descriptor.workSlug,
264
+ kind,
265
+ },
266
+ };
267
+ }
268
+
269
+ function normalizeDuplicateIds(records, warnings) {
270
+ const seen = new Map();
271
+ for (const record of records) {
272
+ const prior = seen.get(record.document.id);
273
+ if (!prior) {
274
+ seen.set(record.document.id, record.document.path);
275
+ continue;
276
+ }
277
+ warnings.push({ code: "DUPLICATE_DOCUMENT_ID", path: record.document.path, detail: prior });
278
+ const replacement = `${record.document.kind}:path_${sha256(record.document.sourceRelative).slice(0, 24)}`;
279
+ record.document.id = replacement;
280
+ record.manifest.documentId = replacement;
281
+ }
282
+ }
283
+
284
+ function deriveIncomingLinks(records, warnings) {
285
+ const byRawId = new Map();
286
+ for (const record of records.filter((item) => item.document.kind === "entry")) {
287
+ if (!byRawId.has(record.document.rawId)) byRawId.set(record.document.rawId, record.document);
288
+ }
289
+ for (const record of records) {
290
+ for (const link of record.document.links) {
291
+ const target = byRawId.get(link.toEntryId);
292
+ if (!target) {
293
+ if (link.toEntryId) warnings.push({ code: "UNRESOLVED_LINK", path: record.document.path, detail: link.toEntryId });
294
+ continue;
295
+ }
296
+ target.incomingLinks.push({
297
+ fromEntryId: record.document.rawId,
298
+ relation: link.relation,
299
+ sourcePath: record.document.path,
300
+ });
301
+ }
302
+ }
303
+ }
304
+
305
+ function buildCorpus(context, discovery = discoverSourceFiles(context)) {
306
+ const warnings = [...discovery.warnings];
307
+ const workContexts = readWorkContexts(discovery.files, warnings);
308
+ const workReads = new Map([...workContexts.values()].map((work) => [work.descriptor.relative, work.read]));
309
+ const records = discovery.files.map((descriptor) => documentFromDescriptor(descriptor, workContexts, warnings, workReads.get(descriptor.relative)));
310
+ normalizeDuplicateIds(records, warnings);
311
+ deriveIncomingLinks(records, warnings);
312
+ return { records, files: discovery.files, warnings };
313
+ }
314
+
315
+ module.exports = {
316
+ ENTRY_DIRECTORIES,
317
+ MAX_MARKDOWN_BYTES,
318
+ RecallCorpusError,
319
+ buildCorpus,
320
+ documentFromDescriptor,
321
+ discoverSourceFiles,
322
+ fingerprint,
323
+ readWorkContexts,
324
+ sameFingerprint,
325
+ sha256,
326
+ stableRead,
327
+ };
@@ -0,0 +1,56 @@
1
+ "use strict";
2
+
3
+ const { performance } = require("node:perf_hooks");
4
+ const { projectContext } = require("../installer/index.js");
5
+ const { searchIndex } = require("./search.js");
6
+ const { ensureSnapshot } = require("./snapshot.js");
7
+
8
+ function contextFor(options = {}) {
9
+ const target = options.target || process.cwd();
10
+ return options.context || projectContext(target, options);
11
+ }
12
+
13
+ function cacheSummary(ensured, timings = {}) {
14
+ return {
15
+ mode: ensured.mode,
16
+ status: ensured.status,
17
+ documentCount: Object.keys(ensured.snapshot.documents || {}).length,
18
+ builtAt: ensured.snapshot.builtAt,
19
+ ...timings,
20
+ };
21
+ }
22
+
23
+ function buildRecallIndex(options = {}) {
24
+ const started = performance.now();
25
+ const context = contextFor(options);
26
+ const ensured = ensureSnapshot(context, options);
27
+ return {
28
+ action: "recall-index",
29
+ target: context.target,
30
+ projectKey: ensured.snapshot.projectKey,
31
+ cache: cacheSummary(ensured, { totalMs: performance.now() - started }),
32
+ warnings: ensured.warnings,
33
+ };
34
+ }
35
+
36
+ function searchRecall(query, options = {}) {
37
+ const started = performance.now();
38
+ const context = contextFor(options);
39
+ const ensureStarted = performance.now();
40
+ const ensured = ensureSnapshot(context, options);
41
+ const ensureMs = performance.now() - ensureStarted;
42
+ const searchStarted = performance.now();
43
+ const results = searchIndex(ensured.index, query, { ...options, incomingLinks: ensured.snapshot.incomingLinks });
44
+ const searchMs = performance.now() - searchStarted;
45
+ return {
46
+ action: "recall-search",
47
+ target: context.target,
48
+ projectKey: ensured.snapshot.projectKey,
49
+ query,
50
+ cache: cacheSummary(ensured, { ensureMs, searchMs, totalMs: performance.now() - started }),
51
+ ...results,
52
+ warnings: ensured.warnings,
53
+ };
54
+ }
55
+
56
+ module.exports = { buildRecallIndex, searchRecall };