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/.agents/adapters/shared/journal-hook.js +72 -9
- package/.agents/rules/FEAT.md +5 -3
- package/.agents/rules/STATE.md +9 -2
- package/.agents/skills/init-work/SKILL.md +3 -2
- package/.agents/skills/recall/SKILL.md +11 -7
- package/.agents/skills/resume/SKILL.md +9 -2
- package/.agents/skills/switch/SKILL.md +5 -3
- package/README.md +33 -0
- package/bin/journal.js +108 -2
- package/docs/architecture.md +37 -3
- package/docs/djournal-in-practice.md +13 -0
- package/docs/read-only-team-journal.md +16 -0
- package/docs/recall.md +102 -0
- package/lib/installer/index.js +76 -3
- package/lib/recall/corpus.js +327 -0
- package/lib/recall/index.js +56 -0
- package/lib/recall/search.js +93 -0
- package/lib/recall/snapshot.js +304 -0
- package/package.json +6 -3
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).
|
package/lib/installer/index.js
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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 };
|