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
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
const fs = require("node:fs");
|
|
6
6
|
const path = require("node:path");
|
|
7
7
|
const { spawnSync } = require("node:child_process");
|
|
8
|
+
const crypto = require("node:crypto");
|
|
8
9
|
|
|
9
10
|
const MARKER = /<!--\s*journal-status:\s*(closed|not-needed|off)(?:\s+([^>]*?))?\s*-->\s*$/i;
|
|
10
11
|
const PROJECT_MARKER_PATH = ".djournal.json";
|
|
@@ -47,27 +48,58 @@ function parseFrontmatter(text) {
|
|
|
47
48
|
function projectContext(root) {
|
|
48
49
|
try {
|
|
49
50
|
const markerFile = path.join(root, PROJECT_MARKER_PATH);
|
|
50
|
-
if (!fs.existsSync(markerFile)) return { root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, ".journal", "config.json"), global: false };
|
|
51
|
+
if (!fs.existsSync(markerFile)) return { root, storeRoot: root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, ".journal", "config.json"), global: false };
|
|
51
52
|
const marker = JSON.parse(fs.readFileSync(markerFile, "utf8"));
|
|
52
|
-
if (!marker.journalStore) return { root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, ".journal", "config.json"), global: false };
|
|
53
|
+
if (!marker.journalStore) return { root, storeRoot: root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, ".journal", "config.json"), global: false };
|
|
53
54
|
const store = path.resolve(marker.journalStore);
|
|
54
|
-
return { root, journalRoot: path.join(store, ".journal"), configFile: path.join(store, "config.json"), global: true };
|
|
55
|
+
return { root, storeRoot: store, journalRoot: path.join(store, ".journal"), configFile: path.join(store, "config.json"), global: true };
|
|
55
56
|
} catch {
|
|
56
|
-
return { root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, ".journal", "config.json"), global: false };
|
|
57
|
+
return { root, storeRoot: root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, ".journal", "config.json"), global: false };
|
|
57
58
|
}
|
|
58
59
|
}
|
|
59
60
|
|
|
60
|
-
function
|
|
61
|
+
function workMetadata(root, slug) {
|
|
62
|
+
const work = workBySlug(root, slug);
|
|
63
|
+
return work && work.status === "active" ? work : null;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
function sessionId(payload, env = process.env) {
|
|
67
|
+
return payload.session_id || payload.sessionId || env.DJOURNAL_SESSION_ID || "";
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
function sessionBinding(context, id) {
|
|
71
|
+
if (typeof id !== "string" || !id.trim()) return null;
|
|
72
|
+
try {
|
|
73
|
+
const file = path.join(context.storeRoot, "sessions", `${sha256(id.trim())}.json`);
|
|
74
|
+
const value = JSON.parse(fs.readFileSync(file, "utf8"));
|
|
75
|
+
return typeof value.activeWorkName === "string" ? value.activeWorkName : null;
|
|
76
|
+
} catch {
|
|
77
|
+
return null;
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
function activeWork(root, options = {}) {
|
|
61
82
|
try {
|
|
62
83
|
const context = projectContext(root);
|
|
84
|
+
const bound = sessionBinding(context, options.sessionId);
|
|
85
|
+
if (bound) {
|
|
86
|
+
const work = workMetadata(root, bound);
|
|
87
|
+
if (work) return { work, source: "session" };
|
|
88
|
+
}
|
|
89
|
+
if (options.state === false) return null;
|
|
63
90
|
const state = JSON.parse(fs.readFileSync(path.join(context.journalRoot, "state.json"), "utf8"));
|
|
64
91
|
if (typeof state.active_work_name !== "string" || !state.active_work_name) return null;
|
|
65
|
-
|
|
92
|
+
const work = workBySlug(root, state.active_work_name);
|
|
93
|
+
return work ? { work, source: "state" } : null;
|
|
66
94
|
} catch {
|
|
67
95
|
return null;
|
|
68
96
|
}
|
|
69
97
|
}
|
|
70
98
|
|
|
99
|
+
function sha256(value) {
|
|
100
|
+
return crypto.createHash("sha256").update(value).digest("hex");
|
|
101
|
+
}
|
|
102
|
+
|
|
71
103
|
function workBySlug(root, slug) {
|
|
72
104
|
try {
|
|
73
105
|
if (typeof slug !== "string" || !slug || slug.includes("/") || slug.includes("\\") || slug === "." || slug === "..") return null;
|
|
@@ -77,12 +109,44 @@ function workBySlug(root, slug) {
|
|
|
77
109
|
const metadata = parseFrontmatter(fs.readFileSync(work, "utf8"));
|
|
78
110
|
const config = readConfig(context);
|
|
79
111
|
const shared = config.sharing?.sharedWorkItems && Object.prototype.hasOwnProperty.call(config.sharing.sharedWorkItems, slug);
|
|
80
|
-
return { slug, visibility: metadata.visibility || "local_only", shared: !!shared, path: work };
|
|
112
|
+
return { slug, title: metadata.title || slug, status: metadata.status || "unknown", visibility: metadata.visibility || "local_only", shared: !!shared, path: work };
|
|
81
113
|
} catch {
|
|
82
114
|
return null;
|
|
83
115
|
}
|
|
84
116
|
}
|
|
85
117
|
|
|
118
|
+
function activeWorkItems(root) {
|
|
119
|
+
try {
|
|
120
|
+
const context = projectContext(root);
|
|
121
|
+
const workRoot = path.join(context.journalRoot, "work");
|
|
122
|
+
if (!fs.existsSync(workRoot)) return [];
|
|
123
|
+
return fs.readdirSync(workRoot, { withFileTypes: true })
|
|
124
|
+
.filter((entry) => entry.isDirectory() && !entry.isSymbolicLink())
|
|
125
|
+
.map((entry) => workBySlug(root, entry.name))
|
|
126
|
+
.filter((work) => work?.status === "active")
|
|
127
|
+
.sort((left, right) => left.slug.localeCompare(right.slug));
|
|
128
|
+
} catch {
|
|
129
|
+
return [];
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
function selectionSuffix(root, payload, env) {
|
|
134
|
+
const id = sessionId(payload, env);
|
|
135
|
+
const selected = activeWork(root, { sessionId: id, state: false });
|
|
136
|
+
if (selected?.work) {
|
|
137
|
+
return ` Session-bound active work: ${selected.work.slug}.`;
|
|
138
|
+
}
|
|
139
|
+
const candidates = activeWorkItems(root);
|
|
140
|
+
if (candidates.length > 1) {
|
|
141
|
+
const list = candidates.map((work) => `${work.slug} (${work.title})`).join("; ");
|
|
142
|
+
return ` Multiple active work items are available: ${list}. Ask the user to choose one before meaningful work, then bind this session with \`djournal work bind <slug> --session <id>\` when a session id is available.`;
|
|
143
|
+
}
|
|
144
|
+
if (candidates.length === 1) return ` Active work: ${candidates[0].slug}.`;
|
|
145
|
+
const fallback = activeWork(root, { state: true });
|
|
146
|
+
if (fallback?.work) return ` Active work: ${fallback.work.slug}.`;
|
|
147
|
+
return " No valid active work is selected.";
|
|
148
|
+
}
|
|
149
|
+
|
|
86
150
|
function readConfig(context) {
|
|
87
151
|
try {
|
|
88
152
|
if (!fs.existsSync(context.configFile)) return {};
|
|
@@ -238,8 +302,7 @@ function handle(payload, options = {}) {
|
|
|
238
302
|
const updateMessage = shouldCheckUpdates(root, env, { allowTest })
|
|
239
303
|
? updateNotice(runUpdateCheck(root, options.updateRunner))
|
|
240
304
|
: "";
|
|
241
|
-
const
|
|
242
|
-
const suffix = work ? ` Active work: ${work.slug}.` : " No valid active work is selected.";
|
|
305
|
+
const suffix = selectionSuffix(root, payload, env);
|
|
243
306
|
return context(event, `Follow AGENTS.md and .agents/rules/AUTOMATION.md.${pullMessage}${updateMessage}${suffix}`);
|
|
244
307
|
}
|
|
245
308
|
|
package/.agents/rules/FEAT.md
CHANGED
|
@@ -71,9 +71,11 @@ Allowed status values:
|
|
|
71
71
|
Status updates preserve `createdAt`, update `updatedAt`, and never alter `id` or
|
|
72
72
|
`slug`. Visibility changes require an explicit user request.
|
|
73
73
|
|
|
74
|
-
Only one work item is selected as active in
|
|
75
|
-
other work items may remain in `active` status.
|
|
76
|
-
|
|
74
|
+
Only one work item is selected as the fallback active work in
|
|
75
|
+
`<journal-root>/state.json`, but other work items may remain in `active` status.
|
|
76
|
+
Parallel sessions may bind themselves to different active work items through
|
|
77
|
+
local session state. Active selection and lifecycle status are different
|
|
78
|
+
concepts.
|
|
77
79
|
|
|
78
80
|
## Legacy work items
|
|
79
81
|
|
package/.agents/rules/STATE.md
CHANGED
|
@@ -24,15 +24,22 @@ The state file contains exactly one field:
|
|
|
24
24
|
}
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
+
This file is the global fallback selection. A session may also bind to a work
|
|
28
|
+
item through local operational session state created by `djournal work bind`.
|
|
29
|
+
Session binding does not change this file and is not durable journal history.
|
|
30
|
+
|
|
27
31
|
## Invariants
|
|
28
32
|
|
|
29
33
|
- The file MUST be valid JSON with no trailing comma.
|
|
30
34
|
- `active_work_name` MUST be a non-empty string.
|
|
31
35
|
- Its value MUST exactly match a folder under `<journal-root>/work/`.
|
|
32
36
|
- That folder SHOULD contain a `work.md` whose `slug` matches the folder name.
|
|
33
|
-
- State selects the current work item; it does not encode lifecycle
|
|
34
|
-
visibility, repository, branch, session, or user identity.
|
|
37
|
+
- State selects the fallback current work item; it does not encode lifecycle
|
|
38
|
+
status, visibility, repository, branch, session, or user identity.
|
|
35
39
|
- Update the file atomically when switching active work.
|
|
40
|
+
- When multiple work items have `status: active` and no valid session binding is
|
|
41
|
+
available, do not guess from this fallback. Prompt the user to choose the work
|
|
42
|
+
item for the session before meaningful writes.
|
|
36
43
|
|
|
37
44
|
## Missing or invalid state
|
|
38
45
|
|
|
@@ -52,8 +52,9 @@ Create one project-level work item. Work items may span repositories.
|
|
|
52
52
|
<What outcome this work item exists to achieve.>
|
|
53
53
|
```
|
|
54
54
|
|
|
55
|
-
10. Create or update `<journal-root>/state.json` to select the new slug
|
|
56
|
-
|
|
55
|
+
10. Create or update `<journal-root>/state.json` to select the new slug as the
|
|
56
|
+
global fallback work item. Preserve the exact state shape from `STATE.md`
|
|
57
|
+
and make the update safely.
|
|
57
58
|
11. Re-read `work.md` and state. Verify slug, IDs, directories, timestamps,
|
|
58
59
|
status, visibility, and JSON validity.
|
|
59
60
|
|
|
@@ -26,13 +26,17 @@ Default to Overview when unclear.
|
|
|
26
26
|
|
|
27
27
|
## Discover cheaply
|
|
28
28
|
|
|
29
|
-
1.
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
29
|
+
1. Run `djournal recall search "<query>" --json` from the project. Add `--work`,
|
|
30
|
+
`--type`, `--status`, or `--visibility` only when the request supplies that
|
|
31
|
+
constraint. Use the ranked paths, IDs, matched fields, summaries, and links
|
|
32
|
+
to choose canonical files for deep reads. The cache is a disposable local
|
|
33
|
+
projection; never cite it instead of the Markdown source.
|
|
34
|
+
2. If the command is unavailable, fails, or returns a recoverable cache warning
|
|
35
|
+
without results, resolve the journal root according to `STATE.md` and use the
|
|
36
|
+
canonical fallback: enumerate `<journal-root>/work/*/work.md`, rank work-item
|
|
37
|
+
metadata, then read entry frontmatter under `journal/`, `_research/`, `docs/`,
|
|
38
|
+
and `decisions/`. Infer legacy metadata best-effort.
|
|
39
|
+
3. For legacy work items, use folder names without rejecting them.
|
|
36
40
|
4. If no candidate matches, say so and list plausible work items. If more than
|
|
37
41
|
three match, use their plan/latest summaries to narrow before deep reads.
|
|
38
42
|
|
|
@@ -15,8 +15,15 @@ Operate read-only.
|
|
|
15
15
|
- `.agents/rules/LINKS.md`
|
|
16
16
|
- `.agents/rules/SAFETY.md`
|
|
17
17
|
- `.agents/rules/STATE.md`
|
|
18
|
-
2. Resolve the journal root according to `STATE.md`; read
|
|
19
|
-
then the
|
|
18
|
+
2. Resolve the journal root according to `STATE.md`; read active work
|
|
19
|
+
candidates under `<journal-root>/work/`, then resolve the session-bound work
|
|
20
|
+
item when the session has one, otherwise use `<journal-root>/state.json` only
|
|
21
|
+
as a fallback.
|
|
22
|
+
- If multiple work items have `status: active` and no valid session binding
|
|
23
|
+
is available, ask the user to choose one before doing meaningful writes.
|
|
24
|
+
After the user chooses, bind the session with
|
|
25
|
+
`djournal work bind <slug> --session <id>` when a session id is available,
|
|
26
|
+
or use `switch` only when the user wants to change the global fallback.
|
|
20
27
|
3. If `work.md` is legacy/missing, infer a temporary title/slug and clearly mark
|
|
21
28
|
metadata as incomplete. Do not repair it.
|
|
22
29
|
4. Index entry frontmatter under `journal/`, `_research/`, `docs/`, and
|
|
@@ -5,7 +5,9 @@ description: Change the active filesystem journal work item without changing Git
|
|
|
5
5
|
|
|
6
6
|
# Switch active work
|
|
7
7
|
|
|
8
|
-
Switch journal context only. Work items are projects and are
|
|
8
|
+
Switch the global fallback journal context only. Work items are projects and are
|
|
9
|
+
not Git branches. For parallel sessions, prefer binding the session with
|
|
10
|
+
`djournal work bind <slug> --session <id>` when a session id is available.
|
|
9
11
|
|
|
10
12
|
## Procedure
|
|
11
13
|
|
|
@@ -22,8 +24,8 @@ Switch journal context only. Work items are projects and are not Git branches.
|
|
|
22
24
|
6. If already selected, report that and stop.
|
|
23
25
|
7. Optionally inspect Git status read-only and mention uncommitted changes, but do
|
|
24
26
|
not commit, stash, switch branches, or block the journal switch.
|
|
25
|
-
8. Update `<journal-root>/state.json` atomically to the selected slug
|
|
26
|
-
exact shape in `STATE.md`.
|
|
27
|
+
8. Update `<journal-root>/state.json` atomically to the selected fallback slug
|
|
28
|
+
using the exact shape in `STATE.md`.
|
|
27
29
|
9. Re-read state and verify the target folder and `work.md` slug.
|
|
28
30
|
10. Present the selected work's latest spine summary and next steps using the
|
|
29
31
|
`resume` retrieval procedure.
|
package/README.md
CHANGED
|
@@ -238,6 +238,38 @@ three-way reconciliation. `sync` pulls first, then projects and publishes
|
|
|
238
238
|
shared work. Colocated mode leaves product-repository Git operations to the
|
|
239
239
|
user; standalone mode performs the configured Git pull and push.
|
|
240
240
|
|
|
241
|
+
Parallel sessions can bind themselves to different active work items:
|
|
242
|
+
|
|
243
|
+
```bash
|
|
244
|
+
djournal work list --active
|
|
245
|
+
djournal work bind 2026-08-14-01-example --session "$DJOURNAL_SESSION_ID"
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
If several work items are active and no session binding exists, the session-start
|
|
249
|
+
hook asks the agent to prompt for a choice instead of guessing from recency.
|
|
250
|
+
|
|
251
|
+
## Fast recall
|
|
252
|
+
|
|
253
|
+
Use recall directly as a search CLI:
|
|
254
|
+
|
|
255
|
+
```bash
|
|
256
|
+
djournal recall search "billing webhook retries"
|
|
257
|
+
djournal recall search "billing webhook retries" --type decision,research --limit 5 --json
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
Or install a harness and ask its agent naturally: “Recall why we chose the
|
|
261
|
+
current billing webhook retry strategy.” The bundled `recall` skill calls the
|
|
262
|
+
same CLI, selects the best journal paths, reads the canonical Markdown, follows
|
|
263
|
+
relevant links, and returns an evidence-backed answer.
|
|
264
|
+
|
|
265
|
+
Recall uses a private, per-project MiniSearch snapshot to rank relevant work
|
|
266
|
+
items and entry paths before reading canonical Markdown. Warm queries reuse the
|
|
267
|
+
snapshot; additions, edits, deletes, and work-metadata changes refresh it on the
|
|
268
|
+
next search. Use `--no-cache` for a one-call in-memory index. Cache corruption or
|
|
269
|
+
write denial is recoverable and never triggers a share, sync, commit, or push.
|
|
270
|
+
See [Fast recall](docs/recall.md) for standalone CLI examples, agent behavior,
|
|
271
|
+
filters, and cache lifecycle details.
|
|
272
|
+
|
|
241
273
|
At session start, djournal reads a user-local npm release cache and reports a
|
|
242
274
|
known CLI or project-asset update every session until it is installed. Stale
|
|
243
275
|
release data is refreshed in the background at most once every 24 hours. Run
|
|
@@ -264,6 +296,7 @@ djournal is licensed under the [Apache License 2.0](LICENSE).
|
|
|
264
296
|
## Documentation
|
|
265
297
|
|
|
266
298
|
- [Installation and repository layouts](docs/installation.md)
|
|
299
|
+
- [Fast recall: CLI and agent usage](docs/recall.md)
|
|
267
300
|
- [Remote Git sync setup](docs/remote-sync.md)
|
|
268
301
|
- [Read-only team journal access](docs/read-only-team-journal.md)
|
|
269
302
|
- [Architecture and data model](docs/architecture.md)
|
package/bin/journal.js
CHANGED
|
@@ -7,9 +7,11 @@ const { spawn } = require("node:child_process");
|
|
|
7
7
|
const {
|
|
8
8
|
InstallerError,
|
|
9
9
|
checkUpdates,
|
|
10
|
+
bindWork,
|
|
10
11
|
configure,
|
|
11
12
|
doctor,
|
|
12
13
|
install,
|
|
14
|
+
listWork,
|
|
13
15
|
pull,
|
|
14
16
|
share,
|
|
15
17
|
sync,
|
|
@@ -17,6 +19,7 @@ const {
|
|
|
17
19
|
uninstall,
|
|
18
20
|
upgrade,
|
|
19
21
|
} = require("../lib/installer/index.js");
|
|
22
|
+
const { buildRecallIndex, searchRecall } = require("../lib/recall/index.js");
|
|
20
23
|
|
|
21
24
|
const sourceRoot = path.resolve(__dirname, "..");
|
|
22
25
|
|
|
@@ -31,6 +34,10 @@ function usage() {
|
|
|
31
34
|
journal share [--target DIR] [--work SLUG | --all] [--dry-run] [--json]
|
|
32
35
|
journal pull [--target DIR] [--work SLUG] [--dry-run] [--json]
|
|
33
36
|
journal sync [--target DIR] [--work SLUG] [--dry-run] [--json]
|
|
37
|
+
journal work list [--target DIR] [--active] [--json]
|
|
38
|
+
journal work bind SLUG [--target DIR] [--session ID] [--dry-run] [--json]
|
|
39
|
+
journal recall index [--target DIR] [--rebuild] [--no-cache] [--json]
|
|
40
|
+
journal recall search QUERY [--target DIR] [--work SLUG] [--type LIST] [--kind LIST] [--status LIST] [--visibility LIST] [--limit N] [--no-cache] [--json]
|
|
34
41
|
journal update check [--target DIR] [--json]
|
|
35
42
|
|
|
36
43
|
Options:
|
|
@@ -38,6 +45,15 @@ Options:
|
|
|
38
45
|
--yes Disable interactive harness selection
|
|
39
46
|
--json Emit JSON
|
|
40
47
|
--work SLUG Select a journal work item instead of active state
|
|
48
|
+
--session ID Bind a journal work item to a specific session
|
|
49
|
+
--active Show only lifecycle-active work items for work list
|
|
50
|
+
--type LIST Filter recall entries by comma-separated entry types
|
|
51
|
+
--kind LIST Filter recall results by comma-separated work,entry kinds
|
|
52
|
+
--status LIST Filter recall results by work-item status
|
|
53
|
+
--visibility LIST Filter recall results by visibility
|
|
54
|
+
--limit N Limit recall results per kind (1-100)
|
|
55
|
+
--rebuild Rebuild the persistent recall cache from scratch
|
|
56
|
+
--no-cache Search with an ephemeral in-memory index
|
|
41
57
|
--harness LIST Comma-separated codex,claude-code,pi selection
|
|
42
58
|
--all Select all work items for share, or every harness
|
|
43
59
|
--instructions-only Install core instructions without harness hooks
|
|
@@ -47,13 +63,27 @@ Options:
|
|
|
47
63
|
function parseArgs(argv) {
|
|
48
64
|
const args = [...argv];
|
|
49
65
|
const command = args.shift();
|
|
50
|
-
if (!command || !["install", "upgrade", "uninstall", "status", "doctor", "config", "share", "pull", "sync", "update"].includes(command)) {
|
|
66
|
+
if (!command || !["install", "upgrade", "uninstall", "status", "doctor", "config", "share", "pull", "sync", "update", "work", "recall"].includes(command)) {
|
|
51
67
|
throw new InstallerError(usage(), "USAGE");
|
|
52
68
|
}
|
|
53
69
|
const options = { command, harnesses: [] };
|
|
54
70
|
if (command === "update") {
|
|
55
71
|
options.subcommand = args.shift();
|
|
56
72
|
if (options.subcommand !== "check") throw new InstallerError("update requires the check subcommand", "USAGE");
|
|
73
|
+
} else if (command === "work") {
|
|
74
|
+
options.subcommand = args.shift();
|
|
75
|
+
if (!["list", "bind"].includes(options.subcommand)) throw new InstallerError("work requires the list or bind subcommand", "USAGE");
|
|
76
|
+
if (options.subcommand === "bind") {
|
|
77
|
+
if (!args.length || args[0].startsWith("-")) throw new InstallerError("work bind requires a work slug", "USAGE");
|
|
78
|
+
options.work = args.shift();
|
|
79
|
+
}
|
|
80
|
+
} else if (command === "recall") {
|
|
81
|
+
options.subcommand = args.shift();
|
|
82
|
+
if (!["index", "search"].includes(options.subcommand)) throw new InstallerError("recall requires the index or search subcommand", "USAGE");
|
|
83
|
+
if (options.subcommand === "search") {
|
|
84
|
+
if (!args.length || args[0].startsWith("-")) throw new InstallerError("recall search requires a query", "USAGE");
|
|
85
|
+
options.query = args.shift();
|
|
86
|
+
}
|
|
57
87
|
}
|
|
58
88
|
while (args.length) {
|
|
59
89
|
const arg = args.shift();
|
|
@@ -65,16 +95,43 @@ function parseArgs(argv) {
|
|
|
65
95
|
if (!args.length) throw new InstallerError("--work requires a value", "USAGE");
|
|
66
96
|
options.work = args.shift();
|
|
67
97
|
} else if (arg.startsWith("--work=")) options.work = arg.slice(7);
|
|
98
|
+
else if (arg === "--session") {
|
|
99
|
+
if (!args.length) throw new InstallerError("--session requires a value", "USAGE");
|
|
100
|
+
options.session = args.shift();
|
|
101
|
+
} else if (arg.startsWith("--session=")) options.session = arg.slice(10);
|
|
102
|
+
else if (arg === "--type") {
|
|
103
|
+
if (!args.length) throw new InstallerError("--type requires a value", "USAGE");
|
|
104
|
+
options.type = args.shift();
|
|
105
|
+
} else if (arg.startsWith("--type=")) options.type = arg.slice(7);
|
|
106
|
+
else if (arg === "--kind") {
|
|
107
|
+
if (!args.length) throw new InstallerError("--kind requires a value", "USAGE");
|
|
108
|
+
options.kind = args.shift();
|
|
109
|
+
} else if (arg.startsWith("--kind=")) options.kind = arg.slice(7);
|
|
110
|
+
else if (arg === "--status") {
|
|
111
|
+
if (!args.length) throw new InstallerError("--status requires a value", "USAGE");
|
|
112
|
+
options.status = args.shift();
|
|
113
|
+
} else if (arg.startsWith("--status=")) options.status = arg.slice(9);
|
|
114
|
+
else if (arg === "--visibility") {
|
|
115
|
+
if (!args.length) throw new InstallerError("--visibility requires a value", "USAGE");
|
|
116
|
+
options.visibility = args.shift();
|
|
117
|
+
} else if (arg.startsWith("--visibility=")) options.visibility = arg.slice(13);
|
|
118
|
+
else if (arg === "--limit") {
|
|
119
|
+
if (!args.length) throw new InstallerError("--limit requires a value", "USAGE");
|
|
120
|
+
options.limit = Number(args.shift());
|
|
121
|
+
} else if (arg.startsWith("--limit=")) options.limit = Number(arg.slice(8));
|
|
68
122
|
else if (arg === "--harness") {
|
|
69
123
|
if (!args.length) throw new InstallerError("--harness requires a value", "USAGE");
|
|
70
124
|
options.harnesses.push(...args.shift().split(",").filter(Boolean));
|
|
71
125
|
} else if (arg.startsWith("--harness=")) options.harnesses.push(...arg.slice(10).split(",").filter(Boolean));
|
|
72
126
|
else if (arg === "--all") options.all = true;
|
|
127
|
+
else if (arg === "--active") options.active = true;
|
|
73
128
|
else if (arg === "--instructions-only") options.instructionsOnly = true;
|
|
74
129
|
else if (arg === "--dry-run") options.dryRun = true;
|
|
75
130
|
else if (arg === "--auto") options.auto = true;
|
|
76
131
|
else if (arg === "--yes") options.yes = true;
|
|
77
132
|
else if (arg === "--json") options.json = true;
|
|
133
|
+
else if (arg === "--rebuild" && command === "recall") options.rebuild = true;
|
|
134
|
+
else if (arg === "--no-cache" && command === "recall") options.noCache = true;
|
|
78
135
|
else if (arg === "--passive" && command === "update") options.passive = true;
|
|
79
136
|
else if (arg === "--refresh-cache" && command === "update") options.refreshCache = true;
|
|
80
137
|
else if (arg === "--help" || arg === "-h") throw new InstallerError(usage(), "HELP");
|
|
@@ -90,6 +147,20 @@ function parseArgs(argv) {
|
|
|
90
147
|
if (options.instructionsOnly && (options.all || options.harnesses.length)) {
|
|
91
148
|
throw new InstallerError("--instructions-only cannot be combined with harness selection", "USAGE");
|
|
92
149
|
}
|
|
150
|
+
if (options.active && !(command === "work" && options.subcommand === "list")) {
|
|
151
|
+
throw new InstallerError("--active is only supported for work list", "USAGE");
|
|
152
|
+
}
|
|
153
|
+
if (command === "recall") {
|
|
154
|
+
if (typeof options.limit !== "undefined" && (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 100)) {
|
|
155
|
+
throw new InstallerError("--limit must be an integer from 1 to 100", "USAGE");
|
|
156
|
+
}
|
|
157
|
+
if (options.rebuild && options.subcommand !== "index") throw new InstallerError("--rebuild is only supported for recall index", "USAGE");
|
|
158
|
+
if (options.subcommand === "index" && ["work", "type", "kind", "status", "visibility", "limit"].some((key) => typeof options[key] !== "undefined")) {
|
|
159
|
+
throw new InstallerError("recall filters are only supported for recall search", "USAGE");
|
|
160
|
+
}
|
|
161
|
+
} else if (["type", "kind", "status", "visibility", "limit", "rebuild", "noCache"].some((key) => typeof options[key] !== "undefined")) {
|
|
162
|
+
throw new InstallerError("recall filters are only supported for recall commands", "USAGE");
|
|
163
|
+
}
|
|
93
164
|
options.target = path.resolve(options.target || process.cwd());
|
|
94
165
|
options.sourceRoot = sourceRoot;
|
|
95
166
|
options.interactive = !options.yes && process.stdin.isTTY && process.stdout.isTTY;
|
|
@@ -111,6 +182,33 @@ function print(value, json) {
|
|
|
111
182
|
if (value.checkedAt) process.stdout.write(`checked: ${value.checkedAt}\n`);
|
|
112
183
|
return;
|
|
113
184
|
}
|
|
185
|
+
if (value.action === "work-list") {
|
|
186
|
+
if (value.selected) process.stdout.write(`selected: ${value.selected}\n`);
|
|
187
|
+
for (const item of value.workItems || []) {
|
|
188
|
+
const marker = item.selected ? "*" : " ";
|
|
189
|
+
process.stdout.write(`${marker} ${item.slug} [${item.status}] ${item.title}\n`);
|
|
190
|
+
}
|
|
191
|
+
return;
|
|
192
|
+
}
|
|
193
|
+
if (value.action === "work-bind") {
|
|
194
|
+
process.stdout.write(`bound ${value.work} to session ${value.sessionHash}\n`);
|
|
195
|
+
return;
|
|
196
|
+
}
|
|
197
|
+
if (value.action === "recall-index") {
|
|
198
|
+
process.stdout.write(`recall index: ${value.cache.status} (${value.cache.mode})\n`);
|
|
199
|
+
process.stdout.write(`documents: ${value.cache.documentCount}\n`);
|
|
200
|
+
process.stdout.write(`elapsed: ${value.cache.totalMs.toFixed(1)} ms\n`);
|
|
201
|
+
for (const item of value.warnings || []) process.stdout.write(`warning: ${item.code}${item.path ? ` ${item.path}` : ""}${item.detail ? ` - ${item.detail}` : ""}\n`);
|
|
202
|
+
return;
|
|
203
|
+
}
|
|
204
|
+
if (value.action === "recall-search") {
|
|
205
|
+
process.stdout.write(`recall search: ${value.cache.status} (${value.cache.mode}), ${value.cache.totalMs.toFixed(1)} ms\n`);
|
|
206
|
+
for (const item of [...(value.workItems || []), ...(value.entries || [])]) {
|
|
207
|
+
process.stdout.write(`${item.score.toFixed(2).padStart(8)} ${item.path} ${item.title}\n`);
|
|
208
|
+
}
|
|
209
|
+
for (const item of value.warnings || []) process.stdout.write(`warning: ${item.code}${item.path ? ` ${item.path}` : ""}${item.detail ? ` - ${item.detail}` : ""}\n`);
|
|
210
|
+
return;
|
|
211
|
+
}
|
|
114
212
|
if (value.action) process.stdout.write(`${value.action}: ${value.target}\n`);
|
|
115
213
|
else if (typeof value.installed === "boolean") process.stdout.write(value.installed ? `installed: ${value.target}\n` : `not installed: ${value.target}\n`);
|
|
116
214
|
else process.stdout.write(`${value.ok ? "ok" : "failed"}: ${value.target}\n`);
|
|
@@ -122,6 +220,10 @@ function print(value, json) {
|
|
|
122
220
|
if (value.latestVersion) process.stdout.write(`latest version: ${value.latestVersion}\n`);
|
|
123
221
|
if (value.updateAvailable) process.stdout.write("update available: yes\n");
|
|
124
222
|
if (value.projectUpdateAvailable) process.stdout.write("project upgrade available: yes\n");
|
|
223
|
+
if (value.recallCache) {
|
|
224
|
+
const cache = value.recallCache;
|
|
225
|
+
process.stdout.write(`recall cache: ${cache.valid ? `${cache.documentCount} documents, ${cache.indexVersion}` : (cache.exists ? "invalid; rebuilds on next recall" : "not built")}\n`);
|
|
226
|
+
}
|
|
125
227
|
if (value.workItems) {
|
|
126
228
|
for (const item of value.workItems) {
|
|
127
229
|
process.stdout.write(`${item.changed ? "shared" : "unchanged"} ${item.work}\n`);
|
|
@@ -182,6 +284,10 @@ async function main() {
|
|
|
182
284
|
else if (options.command === "share") result = share(options);
|
|
183
285
|
else if (options.command === "pull") result = pull(options);
|
|
184
286
|
else if (options.command === "sync") result = sync(options);
|
|
287
|
+
else if (options.command === "work" && options.subcommand === "list") result = listWork(options);
|
|
288
|
+
else if (options.command === "work" && options.subcommand === "bind") result = bindWork(options);
|
|
289
|
+
else if (options.command === "recall" && options.subcommand === "index") result = buildRecallIndex(options);
|
|
290
|
+
else if (options.command === "recall" && options.subcommand === "search") result = searchRecall(options.query, options);
|
|
185
291
|
else if (options.command === "update") {
|
|
186
292
|
result = await checkUpdates(options);
|
|
187
293
|
if (result.refreshNeeded) result.backgroundRefreshStarted = launchUpdateRefresh(options);
|
|
@@ -190,7 +296,7 @@ async function main() {
|
|
|
190
296
|
print(result, options.json);
|
|
191
297
|
if (result.ok === false || result.installed === false || result.clean === false || result.conflicts?.length) process.exitCode = 2;
|
|
192
298
|
} catch (error) {
|
|
193
|
-
const code = error instanceof InstallerError ? error.code : "UNEXPECTED";
|
|
299
|
+
const code = error instanceof InstallerError ? error.code : (error?.code || "UNEXPECTED");
|
|
194
300
|
if (process.argv.includes("--json")) {
|
|
195
301
|
process.stderr.write(`${JSON.stringify({ ok: false, code, message: error.message }, null, 2)}\n`);
|
|
196
302
|
} else process.stderr.write(`${code}: ${error.message}\n`);
|
package/docs/architecture.md
CHANGED
|
@@ -10,6 +10,8 @@ The canonical journal lives in the user's djournal home, keyed by project:
|
|
|
10
10
|
```text
|
|
11
11
|
~/.djournal/projects/<project-key>/
|
|
12
12
|
config.json
|
|
13
|
+
sessions/ # local operational session bindings
|
|
14
|
+
cache/recall/ # disposable private recall index
|
|
13
15
|
.journal/
|
|
14
16
|
state.json
|
|
15
17
|
work/<work-item>/
|
|
@@ -26,6 +28,29 @@ The installed project contains a marker that points back to that store:
|
|
|
26
28
|
.djournal.json
|
|
27
29
|
```
|
|
28
30
|
|
|
31
|
+
## Recall index
|
|
32
|
+
|
|
33
|
+
`djournal recall search` uses a serialized MiniSearch inverted index at
|
|
34
|
+
`<project-store>/cache/recall/snapshot.json`. It indexes work metadata, entry
|
|
35
|
+
metadata, headings, and body terms, while storing only the metadata needed to
|
|
36
|
+
return explainable ranked paths. The complete Markdown body is not a stored
|
|
37
|
+
result field, and every final answer still reads the selected canonical files.
|
|
38
|
+
|
|
39
|
+
The snapshot is schema-, index-option-, and project-versioned. Each search compares a
|
|
40
|
+
manifest of source paths, sizes, and modification times; changed work metadata
|
|
41
|
+
reindexes its entries, and additions, edits, renames, and deletions are applied
|
|
42
|
+
incrementally. Missing, incompatible, oversized, or malformed snapshots rebuild
|
|
43
|
+
from Markdown. Writes use a private directory, a short-lived lock, and atomic
|
|
44
|
+
rename. If persistence is unavailable, the same query runs with an ephemeral
|
|
45
|
+
in-memory index.
|
|
46
|
+
|
|
47
|
+
The cache is outside `.journal/`, is never shared, and may be removed at any
|
|
48
|
+
time. `djournal recall index --rebuild` recreates it explicitly, while
|
|
49
|
+
`djournal recall search "query" --no-cache` bypasses it for one invocation.
|
|
50
|
+
Pull and sync do not block on prewarming: the next search performs authoritative
|
|
51
|
+
reconciliation. This keeps publication latency predictable while preserving a
|
|
52
|
+
warm snapshot whenever prior recall has already built one.
|
|
53
|
+
|
|
29
54
|
When sync is enabled, a repository-local `.journal/` is a projection containing
|
|
30
55
|
the shared work items copied out of the global store.
|
|
31
56
|
|
|
@@ -47,7 +72,13 @@ Every work item has:
|
|
|
47
72
|
```
|
|
48
73
|
|
|
49
74
|
The frontmatter stores stable identity, title, status, visibility, authorship,
|
|
50
|
-
and timestamps.
|
|
75
|
+
and timestamps. Several work items may have lifecycle `status: active` at the
|
|
76
|
+
same time.
|
|
77
|
+
|
|
78
|
+
`state.json` stores the global fallback selected work item for backward
|
|
79
|
+
compatibility. Parallel sessions can bind to a different active work item using
|
|
80
|
+
local operational state under `sessions/`; those bindings are not durable
|
|
81
|
+
journal history and are not projected into shared `.journal/` content.
|
|
51
82
|
|
|
52
83
|
## Configuration
|
|
53
84
|
|
|
@@ -160,8 +191,11 @@ audit, reconciliation, and closure.
|
|
|
160
191
|
|
|
161
192
|
Hooks remind agents about the workflow, delegate configured synchronization
|
|
162
193
|
transport to the CLI, and validate final status markers. Hooks do not create
|
|
163
|
-
semantic journal entries. When `.djournal.json` exists, hooks read
|
|
164
|
-
and sync config from the global project store.
|
|
194
|
+
semantic journal entries. When `.djournal.json` exists, hooks read work context
|
|
195
|
+
and sync config from the global project store. If a session binding exists, the
|
|
196
|
+
hook reports that bound work item. If several work items are lifecycle-active and
|
|
197
|
+
no binding exists, the hook asks the agent to prompt the user before meaningful
|
|
198
|
+
work.
|
|
165
199
|
|
|
166
200
|
For Claude Code, install also injects a narrow permission grant into
|
|
167
201
|
`.claude/settings.json` for the exact global project store path and safe
|
|
@@ -18,6 +18,19 @@ At session start, the active work item gives the agent a compact context pack:
|
|
|
18
18
|
This lets future sessions start from shaped history rather than broad
|
|
19
19
|
exploration.
|
|
20
20
|
|
|
21
|
+
When several work items are still `active`, a new session should choose the one
|
|
22
|
+
it is working on before making meaningful changes. Bind a known session id to a
|
|
23
|
+
work item:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
djournal work list --active
|
|
27
|
+
djournal work bind 2026-08-14-01-example --session "$DJOURNAL_SESSION_ID"
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
If no session id is available, the agent should ask which active work item to
|
|
31
|
+
use and avoid guessing from recency. The global `state.json` selection remains a
|
|
32
|
+
fallback for older workflows.
|
|
33
|
+
|
|
21
34
|
When standalone automatic sync is enabled, session startup first pulls the
|
|
22
35
|
Git-backed journal and reconciles it into canonical storage. Work initialization
|
|
23
36
|
and switching also pull before enumerating available work, so a colleague can
|
|
@@ -22,6 +22,14 @@ This still writes local files under the user's djournal home. "Read-only" means
|
|
|
22
22
|
read-only with respect to the organization remote, not a filesystem mode that
|
|
23
23
|
prevents local cache or canonical-store hydration.
|
|
24
24
|
|
|
25
|
+
Recall also writes a private derived index under
|
|
26
|
+
`~/.djournal/projects/<project-key>/cache/recall/`. It is not placed in the Git
|
|
27
|
+
projection and is never published. Every CLI invocation loads the serialized
|
|
28
|
+
index, checks source-file metadata, and incrementally refreshes only stale
|
|
29
|
+
documents before searching; it does not keep a daemon or a process permanently
|
|
30
|
+
in memory. If the local store is not writable, recall builds the index in memory
|
|
31
|
+
for that invocation and returns results without attempting a remote write.
|
|
32
|
+
|
|
25
33
|
## Setup for a Non-Technical Reader
|
|
26
34
|
|
|
27
35
|
Ask the organization admin for the team journal repository URL and read-only Git
|
|
@@ -37,6 +45,8 @@ djournal config sync.mode standalone
|
|
|
37
45
|
djournal config sync.path .
|
|
38
46
|
djournal config sync.auto false
|
|
39
47
|
djournal pull
|
|
48
|
+
djournal recall index
|
|
49
|
+
djournal recall search "onboarding decisions"
|
|
40
50
|
djournal status
|
|
41
51
|
```
|
|
42
52
|
|
|
@@ -60,6 +70,12 @@ djournal sync
|
|
|
60
70
|
If read-only Git permissions are configured correctly, accidental pushes should
|
|
61
71
|
fail at the remote even if someone runs a publication command.
|
|
62
72
|
|
|
73
|
+
To avoid persistent local cache writes as well, add `--no-cache` to a recall
|
|
74
|
+
search. To clear a persistent cache, delete only the project store's
|
|
75
|
+
`cache/recall/` directory or run `djournal recall index --rebuild`; canonical
|
|
76
|
+
journal history is unaffected. A malformed or incompatible cache is ignored and
|
|
77
|
+
rebuilt automatically.
|
|
78
|
+
|
|
63
79
|
## Copy/Paste Agent Prompt
|
|
64
80
|
|
|
65
81
|
Use this prompt after installation when asking an LLM agent to connect the local
|