djournal 0.6.0 → 0.8.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 +128 -11
- 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/resume/SKILL.md +9 -2
- package/.agents/skills/switch/SKILL.md +5 -3
- package/README.md +18 -0
- package/bin/journal.js +87 -2
- package/docs/architecture.md +13 -3
- package/docs/djournal-in-practice.md +13 -0
- package/docs/installation.md +47 -4
- package/docs/read-only-team-journal.md +150 -0
- package/docs/remote-sync.md +1 -0
- package/lib/installer/index.js +124 -3
- package/lib/update-checker.js +177 -0
- package/package.json +5 -2
|
@@ -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 {};
|
|
@@ -97,6 +161,18 @@ function shouldAutoSync(root) {
|
|
|
97
161
|
return config.enabled === true && config.auto === true && config.mode === "standalone";
|
|
98
162
|
}
|
|
99
163
|
|
|
164
|
+
function environmentFlag(value) {
|
|
165
|
+
return typeof value === "string" ? !["", "0", "false"].includes(value.toLowerCase()) : Boolean(value);
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
function shouldCheckUpdates(root, env = process.env, options = {}) {
|
|
169
|
+
const config = readConfig(projectContext(root));
|
|
170
|
+
if (config.updates?.enabled === false) return false;
|
|
171
|
+
if (environmentFlag(env.NO_UPDATE_NOTIFIER) || environmentFlag(env.CI)) return false;
|
|
172
|
+
if (!options.allowTest && (env.NODE_ENV === "test" || environmentFlag(env.NODE_TEST_CONTEXT))) return false;
|
|
173
|
+
return true;
|
|
174
|
+
}
|
|
175
|
+
|
|
100
176
|
function context(event, message) {
|
|
101
177
|
return {
|
|
102
178
|
hookSpecificOutput: {
|
|
@@ -173,6 +249,34 @@ function runJournal(root, args, runner) {
|
|
|
173
249
|
return { ok: true, message: (result.stdout || "").trim() };
|
|
174
250
|
}
|
|
175
251
|
|
|
252
|
+
function runUpdateCheck(root, runner) {
|
|
253
|
+
const run = runner || ((command, args, options) => spawnSync(command, args, options));
|
|
254
|
+
const result = run("journal", ["update", "check", "--passive", "--json"], {
|
|
255
|
+
cwd: root,
|
|
256
|
+
encoding: "utf8",
|
|
257
|
+
timeout: 5000,
|
|
258
|
+
});
|
|
259
|
+
if (result.error || result.status !== 0) return null;
|
|
260
|
+
try {
|
|
261
|
+
const value = JSON.parse(result.stdout || "");
|
|
262
|
+
return value && typeof value === "object" && value.enabled !== false ? value : null;
|
|
263
|
+
} catch {
|
|
264
|
+
return null;
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
function updateNotice(value) {
|
|
269
|
+
if (!value) return "";
|
|
270
|
+
const messages = [];
|
|
271
|
+
if (value.updateAvailable && value.cliVersion && value.latestVersion) {
|
|
272
|
+
messages.push(`djournal ${value.latestVersion} is available (CLI ${value.cliVersion}). Update the npm package, then run \`djournal upgrade\` in this project.`);
|
|
273
|
+
}
|
|
274
|
+
if (value.projectUpdateAvailable && value.projectVersion && value.cliVersion) {
|
|
275
|
+
messages.push(`This project uses djournal assets ${value.projectVersion}; CLI ${value.cliVersion} is installed. Run \`djournal upgrade\`.`);
|
|
276
|
+
}
|
|
277
|
+
return messages.length ? ` ${messages.join(" ")}` : "";
|
|
278
|
+
}
|
|
279
|
+
|
|
176
280
|
function requestsJournalSync(prompt) {
|
|
177
281
|
const match = prompt.match(/\b(?:sync|synchronize|pull)\s+(?:the\s+)?journal\b|\bjournal\s+(?:sync|synchronize|pull)\b/i);
|
|
178
282
|
if (!match) return false;
|
|
@@ -193,9 +297,13 @@ function handle(payload, options = {}) {
|
|
|
193
297
|
? " Journal pull completed before loading active work."
|
|
194
298
|
: ` Automatic journal pull failed: ${result.message}`;
|
|
195
299
|
}
|
|
196
|
-
const
|
|
197
|
-
const
|
|
198
|
-
|
|
300
|
+
const env = options.env || process.env;
|
|
301
|
+
const allowTest = typeof options.updateRunner === "function";
|
|
302
|
+
const updateMessage = shouldCheckUpdates(root, env, { allowTest })
|
|
303
|
+
? updateNotice(runUpdateCheck(root, options.updateRunner))
|
|
304
|
+
: "";
|
|
305
|
+
const suffix = selectionSuffix(root, payload, env);
|
|
306
|
+
return context(event, `Follow AGENTS.md and .agents/rules/AUTOMATION.md.${pullMessage}${updateMessage}${suffix}`);
|
|
199
307
|
}
|
|
200
308
|
|
|
201
309
|
if (event === "UserPromptSubmit") {
|
|
@@ -263,4 +371,13 @@ if (require.main === module) {
|
|
|
263
371
|
main();
|
|
264
372
|
}
|
|
265
373
|
|
|
266
|
-
module.exports = {
|
|
374
|
+
module.exports = {
|
|
375
|
+
handle,
|
|
376
|
+
parseFrontmatter,
|
|
377
|
+
requestsJournalSync,
|
|
378
|
+
resolveClosedEntry,
|
|
379
|
+
runUpdateCheck,
|
|
380
|
+
shouldAutoSync,
|
|
381
|
+
shouldCheckUpdates,
|
|
382
|
+
updateNotice,
|
|
383
|
+
};
|
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
|
|
|
@@ -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
|
@@ -214,6 +214,7 @@ global store referenced by `.djournal.json`.
|
|
|
214
214
|
```bash
|
|
215
215
|
djournal status
|
|
216
216
|
djournal doctor
|
|
217
|
+
djournal update check
|
|
217
218
|
djournal config sync.enabled true
|
|
218
219
|
djournal share --all
|
|
219
220
|
djournal share
|
|
@@ -237,6 +238,22 @@ three-way reconciliation. `sync` pulls first, then projects and publishes
|
|
|
237
238
|
shared work. Colocated mode leaves product-repository Git operations to the
|
|
238
239
|
user; standalone mode performs the configured Git pull and push.
|
|
239
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
|
+
At session start, djournal reads a user-local npm release cache and reports a
|
|
252
|
+
known CLI or project-asset update every session until it is installed. Stale
|
|
253
|
+
release data is refreshed in the background at most once every 24 hours. Run
|
|
254
|
+
`djournal update check` for an immediate check, or disable passive checks with
|
|
255
|
+
`djournal config updates.enabled false` or `NO_UPDATE_NOTIFIER=1`.
|
|
256
|
+
|
|
240
257
|
## Status
|
|
241
258
|
|
|
242
259
|
Codex, Claude Code, and Pi are supported. OpenCode and Zed adapters are planned.
|
|
@@ -258,6 +275,7 @@ djournal is licensed under the [Apache License 2.0](LICENSE).
|
|
|
258
275
|
|
|
259
276
|
- [Installation and repository layouts](docs/installation.md)
|
|
260
277
|
- [Remote Git sync setup](docs/remote-sync.md)
|
|
278
|
+
- [Read-only team journal access](docs/read-only-team-journal.md)
|
|
261
279
|
- [Architecture and data model](docs/architecture.md)
|
|
262
280
|
- [Visibility and sharing](docs/visibility-and-sharing.md)
|
|
263
281
|
- [Djournal in practice](docs/djournal-in-practice.md)
|
package/bin/journal.js
CHANGED
|
@@ -3,11 +3,15 @@
|
|
|
3
3
|
"use strict";
|
|
4
4
|
|
|
5
5
|
const path = require("node:path");
|
|
6
|
+
const { spawn } = require("node:child_process");
|
|
6
7
|
const {
|
|
7
8
|
InstallerError,
|
|
9
|
+
checkUpdates,
|
|
10
|
+
bindWork,
|
|
8
11
|
configure,
|
|
9
12
|
doctor,
|
|
10
13
|
install,
|
|
14
|
+
listWork,
|
|
11
15
|
pull,
|
|
12
16
|
share,
|
|
13
17
|
sync,
|
|
@@ -29,12 +33,17 @@ function usage() {
|
|
|
29
33
|
journal share [--target DIR] [--work SLUG | --all] [--dry-run] [--json]
|
|
30
34
|
journal pull [--target DIR] [--work SLUG] [--dry-run] [--json]
|
|
31
35
|
journal sync [--target DIR] [--work SLUG] [--dry-run] [--json]
|
|
36
|
+
journal work list [--target DIR] [--active] [--json]
|
|
37
|
+
journal work bind SLUG [--target DIR] [--session ID] [--dry-run] [--json]
|
|
38
|
+
journal update check [--target DIR] [--json]
|
|
32
39
|
|
|
33
40
|
Options:
|
|
34
41
|
--dry-run Show the planned operation without writing
|
|
35
42
|
--yes Disable interactive harness selection
|
|
36
43
|
--json Emit JSON
|
|
37
44
|
--work SLUG Select a journal work item instead of active state
|
|
45
|
+
--session ID Bind a journal work item to a specific session
|
|
46
|
+
--active Show only lifecycle-active work items for work list
|
|
38
47
|
--harness LIST Comma-separated codex,claude-code,pi selection
|
|
39
48
|
--all Select all work items for share, or every harness
|
|
40
49
|
--instructions-only Install core instructions without harness hooks
|
|
@@ -44,10 +53,21 @@ Options:
|
|
|
44
53
|
function parseArgs(argv) {
|
|
45
54
|
const args = [...argv];
|
|
46
55
|
const command = args.shift();
|
|
47
|
-
if (!command || !["install", "upgrade", "uninstall", "status", "doctor", "config", "share", "pull", "sync"].includes(command)) {
|
|
56
|
+
if (!command || !["install", "upgrade", "uninstall", "status", "doctor", "config", "share", "pull", "sync", "update", "work"].includes(command)) {
|
|
48
57
|
throw new InstallerError(usage(), "USAGE");
|
|
49
58
|
}
|
|
50
59
|
const options = { command, harnesses: [] };
|
|
60
|
+
if (command === "update") {
|
|
61
|
+
options.subcommand = args.shift();
|
|
62
|
+
if (options.subcommand !== "check") throw new InstallerError("update requires the check subcommand", "USAGE");
|
|
63
|
+
} else if (command === "work") {
|
|
64
|
+
options.subcommand = args.shift();
|
|
65
|
+
if (!["list", "bind"].includes(options.subcommand)) throw new InstallerError("work requires the list or bind subcommand", "USAGE");
|
|
66
|
+
if (options.subcommand === "bind") {
|
|
67
|
+
if (!args.length || args[0].startsWith("-")) throw new InstallerError("work bind requires a work slug", "USAGE");
|
|
68
|
+
options.work = args.shift();
|
|
69
|
+
}
|
|
70
|
+
}
|
|
51
71
|
while (args.length) {
|
|
52
72
|
const arg = args.shift();
|
|
53
73
|
if (arg === "--target") {
|
|
@@ -58,16 +78,23 @@ function parseArgs(argv) {
|
|
|
58
78
|
if (!args.length) throw new InstallerError("--work requires a value", "USAGE");
|
|
59
79
|
options.work = args.shift();
|
|
60
80
|
} else if (arg.startsWith("--work=")) options.work = arg.slice(7);
|
|
81
|
+
else if (arg === "--session") {
|
|
82
|
+
if (!args.length) throw new InstallerError("--session requires a value", "USAGE");
|
|
83
|
+
options.session = args.shift();
|
|
84
|
+
} else if (arg.startsWith("--session=")) options.session = arg.slice(10);
|
|
61
85
|
else if (arg === "--harness") {
|
|
62
86
|
if (!args.length) throw new InstallerError("--harness requires a value", "USAGE");
|
|
63
87
|
options.harnesses.push(...args.shift().split(",").filter(Boolean));
|
|
64
88
|
} else if (arg.startsWith("--harness=")) options.harnesses.push(...arg.slice(10).split(",").filter(Boolean));
|
|
65
89
|
else if (arg === "--all") options.all = true;
|
|
90
|
+
else if (arg === "--active") options.active = true;
|
|
66
91
|
else if (arg === "--instructions-only") options.instructionsOnly = true;
|
|
67
92
|
else if (arg === "--dry-run") options.dryRun = true;
|
|
68
93
|
else if (arg === "--auto") options.auto = true;
|
|
69
94
|
else if (arg === "--yes") options.yes = true;
|
|
70
95
|
else if (arg === "--json") options.json = true;
|
|
96
|
+
else if (arg === "--passive" && command === "update") options.passive = true;
|
|
97
|
+
else if (arg === "--refresh-cache" && command === "update") options.refreshCache = true;
|
|
71
98
|
else if (arg === "--help" || arg === "-h") throw new InstallerError(usage(), "HELP");
|
|
72
99
|
else if (command === "config" && !options.key) options.key = arg;
|
|
73
100
|
else if (command === "config" && typeof options.value === "undefined") options.value = arg;
|
|
@@ -81,6 +108,9 @@ function parseArgs(argv) {
|
|
|
81
108
|
if (options.instructionsOnly && (options.all || options.harnesses.length)) {
|
|
82
109
|
throw new InstallerError("--instructions-only cannot be combined with harness selection", "USAGE");
|
|
83
110
|
}
|
|
111
|
+
if (options.active && !(command === "work" && options.subcommand === "list")) {
|
|
112
|
+
throw new InstallerError("--active is only supported for work list", "USAGE");
|
|
113
|
+
}
|
|
84
114
|
options.target = path.resolve(options.target || process.cwd());
|
|
85
115
|
options.sourceRoot = sourceRoot;
|
|
86
116
|
options.interactive = !options.yes && process.stdin.isTTY && process.stdout.isTTY;
|
|
@@ -92,12 +122,39 @@ function print(value, json) {
|
|
|
92
122
|
process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
|
|
93
123
|
return;
|
|
94
124
|
}
|
|
125
|
+
if (value.action === "update-check") {
|
|
126
|
+
process.stdout.write(`cli version: ${value.cliVersion || "unknown"}\n`);
|
|
127
|
+
if (value.projectVersion) process.stdout.write(`project assets: ${value.projectVersion}\n`);
|
|
128
|
+
process.stdout.write(`latest version: ${value.latestVersion || "unknown"}\n`);
|
|
129
|
+
if (value.updateAvailable) process.stdout.write(`update available: ${value.cliVersion} -> ${value.latestVersion}\n`);
|
|
130
|
+
else if (value.latestVersion) process.stdout.write("djournal CLI is up to date\n");
|
|
131
|
+
if (value.projectUpdateAvailable) process.stdout.write(`project upgrade available: ${value.projectVersion} -> ${value.cliVersion}\n`);
|
|
132
|
+
if (value.checkedAt) process.stdout.write(`checked: ${value.checkedAt}\n`);
|
|
133
|
+
return;
|
|
134
|
+
}
|
|
135
|
+
if (value.action === "work-list") {
|
|
136
|
+
if (value.selected) process.stdout.write(`selected: ${value.selected}\n`);
|
|
137
|
+
for (const item of value.workItems || []) {
|
|
138
|
+
const marker = item.selected ? "*" : " ";
|
|
139
|
+
process.stdout.write(`${marker} ${item.slug} [${item.status}] ${item.title}\n`);
|
|
140
|
+
}
|
|
141
|
+
return;
|
|
142
|
+
}
|
|
143
|
+
if (value.action === "work-bind") {
|
|
144
|
+
process.stdout.write(`bound ${value.work} to session ${value.sessionHash}\n`);
|
|
145
|
+
return;
|
|
146
|
+
}
|
|
95
147
|
if (value.action) process.stdout.write(`${value.action}: ${value.target}\n`);
|
|
96
148
|
else if (typeof value.installed === "boolean") process.stdout.write(value.installed ? `installed: ${value.target}\n` : `not installed: ${value.target}\n`);
|
|
97
149
|
else process.stdout.write(`${value.ok ? "ok" : "failed"}: ${value.target}\n`);
|
|
98
150
|
if (value.harnesses) process.stdout.write(`harnesses: ${value.harnesses.join(", ") || "instructions-only"}\n`);
|
|
99
151
|
if (value.key) process.stdout.write(`${value.key}: ${JSON.stringify(value.value)}\n`);
|
|
100
152
|
else if (value.config) process.stdout.write(`${JSON.stringify(value.config, null, 2)}\n`);
|
|
153
|
+
if (value.cliVersion) process.stdout.write(`cli version: ${value.cliVersion}\n`);
|
|
154
|
+
if (value.projectVersion) process.stdout.write(`project assets: ${value.projectVersion}\n`);
|
|
155
|
+
if (value.latestVersion) process.stdout.write(`latest version: ${value.latestVersion}\n`);
|
|
156
|
+
if (value.updateAvailable) process.stdout.write("update available: yes\n");
|
|
157
|
+
if (value.projectUpdateAvailable) process.stdout.write("project upgrade available: yes\n");
|
|
101
158
|
if (value.workItems) {
|
|
102
159
|
for (const item of value.workItems) {
|
|
103
160
|
process.stdout.write(`${item.changed ? "shared" : "unchanged"} ${item.work}\n`);
|
|
@@ -124,6 +181,28 @@ function exitCodeFor(code) {
|
|
|
124
181
|
return 1;
|
|
125
182
|
}
|
|
126
183
|
|
|
184
|
+
function launchUpdateRefresh(options, runner = spawn) {
|
|
185
|
+
try {
|
|
186
|
+
const child = runner(process.execPath, [
|
|
187
|
+
__filename,
|
|
188
|
+
"update",
|
|
189
|
+
"check",
|
|
190
|
+
"--refresh-cache",
|
|
191
|
+
"--json",
|
|
192
|
+
"--target",
|
|
193
|
+
options.target,
|
|
194
|
+
], {
|
|
195
|
+
detached: true,
|
|
196
|
+
stdio: "ignore",
|
|
197
|
+
env: { ...process.env, DJOURNAL_UPDATE_WORKER: "1" },
|
|
198
|
+
});
|
|
199
|
+
child.unref();
|
|
200
|
+
return true;
|
|
201
|
+
} catch {
|
|
202
|
+
return false;
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
|
|
127
206
|
async function main() {
|
|
128
207
|
try {
|
|
129
208
|
const options = parseArgs(process.argv.slice(2));
|
|
@@ -136,6 +215,12 @@ async function main() {
|
|
|
136
215
|
else if (options.command === "share") result = share(options);
|
|
137
216
|
else if (options.command === "pull") result = pull(options);
|
|
138
217
|
else if (options.command === "sync") result = sync(options);
|
|
218
|
+
else if (options.command === "work" && options.subcommand === "list") result = listWork(options);
|
|
219
|
+
else if (options.command === "work" && options.subcommand === "bind") result = bindWork(options);
|
|
220
|
+
else if (options.command === "update") {
|
|
221
|
+
result = await checkUpdates(options);
|
|
222
|
+
if (result.refreshNeeded) result.backgroundRefreshStarted = launchUpdateRefresh(options);
|
|
223
|
+
}
|
|
139
224
|
else result = doctor(options);
|
|
140
225
|
print(result, options.json);
|
|
141
226
|
if (result.ok === false || result.installed === false || result.clean === false || result.conflicts?.length) process.exitCode = 2;
|
|
@@ -150,4 +235,4 @@ async function main() {
|
|
|
150
235
|
|
|
151
236
|
if (require.main === module) main();
|
|
152
237
|
|
|
153
|
-
module.exports = { parseArgs, print };
|
|
238
|
+
module.exports = { launchUpdateRefresh, parseArgs, print };
|
package/docs/architecture.md
CHANGED
|
@@ -10,6 +10,7 @@ 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
|
|
13
14
|
.journal/
|
|
14
15
|
state.json
|
|
15
16
|
work/<work-item>/
|
|
@@ -47,7 +48,13 @@ Every work item has:
|
|
|
47
48
|
```
|
|
48
49
|
|
|
49
50
|
The frontmatter stores stable identity, title, status, visibility, authorship,
|
|
50
|
-
and timestamps.
|
|
51
|
+
and timestamps. Several work items may have lifecycle `status: active` at the
|
|
52
|
+
same time.
|
|
53
|
+
|
|
54
|
+
`state.json` stores the global fallback selected work item for backward
|
|
55
|
+
compatibility. Parallel sessions can bind to a different active work item using
|
|
56
|
+
local operational state under `sessions/`; those bindings are not durable
|
|
57
|
+
journal history and are not projected into shared `.journal/` content.
|
|
51
58
|
|
|
52
59
|
## Configuration
|
|
53
60
|
|
|
@@ -160,8 +167,11 @@ audit, reconciliation, and closure.
|
|
|
160
167
|
|
|
161
168
|
Hooks remind agents about the workflow, delegate configured synchronization
|
|
162
169
|
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.
|
|
170
|
+
semantic journal entries. When `.djournal.json` exists, hooks read work context
|
|
171
|
+
and sync config from the global project store. If a session binding exists, the
|
|
172
|
+
hook reports that bound work item. If several work items are lifecycle-active and
|
|
173
|
+
no binding exists, the hook asks the agent to prompt the user before meaningful
|
|
174
|
+
work.
|
|
165
175
|
|
|
166
176
|
For Claude Code, install also injects a narrow permission grant into
|
|
167
177
|
`.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
|
package/docs/installation.md
CHANGED
|
@@ -151,14 +151,57 @@ djournal install --instructions-only
|
|
|
151
151
|
```bash
|
|
152
152
|
djournal status
|
|
153
153
|
djournal doctor
|
|
154
|
+
djournal update check
|
|
154
155
|
```
|
|
155
156
|
|
|
156
|
-
`status` reports installed files
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
157
|
+
`status` reports installed files, cleanliness, the executing CLI version, the
|
|
158
|
+
project asset version, and cached npm release availability. `doctor` checks the
|
|
159
|
+
local environment and harness configuration. For Pi it reports extension
|
|
160
|
+
presence and reminds you that project trust is required; it does not inspect or
|
|
161
|
+
change Pi's private trust state.
|
|
162
|
+
|
|
163
|
+
## Update notifications
|
|
164
|
+
|
|
165
|
+
djournal checks npm release metadata without delaying session startup. A
|
|
166
|
+
session reads `update-check.json` under `DJOURNAL_HOME` (default:
|
|
167
|
+
`~/.djournal/update-check.json`) and, when that cache is older than 24 hours,
|
|
168
|
+
starts a bounded background refresh for a later session. Registry failures are
|
|
169
|
+
silent in this passive path.
|
|
170
|
+
|
|
171
|
+
When a cached release is newer than the executing CLI, every new session shows
|
|
172
|
+
an update notice until the newer package is installed. When the CLI is newer
|
|
173
|
+
than a project's installed hooks and rules, every new session instead—or
|
|
174
|
+
additionally—reminds you to upgrade those project assets.
|
|
175
|
+
|
|
176
|
+
Check immediately:
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
djournal update check
|
|
180
|
+
djournal update check --json
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
For a global installation, update both layers:
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
npm install -g djournal@latest
|
|
187
|
+
djournal upgrade
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Passive checks are enabled by default. Configure the interval or disable them
|
|
191
|
+
for a project:
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
djournal config updates.intervalHours 24
|
|
195
|
+
djournal config updates.enabled false
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Set `NO_UPDATE_NOTIFIER=1` to disable passive checks and notices for the current
|
|
199
|
+
environment. CI and test environments skip them automatically. Explicit
|
|
200
|
+
`djournal update check` commands still perform a foreground check and report
|
|
201
|
+
errors.
|
|
160
202
|
|
|
161
203
|
## Related docs
|
|
162
204
|
|
|
163
205
|
- [Remote Git sync setup](remote-sync.md)
|
|
206
|
+
- [Read-only team journal access](read-only-team-journal.md)
|
|
164
207
|
- [Uninstalling and reinstalling](uninstalling.md)
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# Read-Only Team Journal Access
|
|
2
|
+
|
|
3
|
+
This guide is for people who need to read, recall, and research team journal
|
|
4
|
+
history without publishing their own journal entries back to the shared remote.
|
|
5
|
+
Typical users include PMs, designers, support leads, and executives who want to
|
|
6
|
+
ask an agent about prior decisions without learning the full synchronization
|
|
7
|
+
workflow.
|
|
8
|
+
|
|
9
|
+
## Current Model
|
|
10
|
+
|
|
11
|
+
djournal does not yet have a single `connect --read-only` command. Today, a
|
|
12
|
+
read-only setup is achieved by combining three controls:
|
|
13
|
+
|
|
14
|
+
- Git credentials that can clone and pull the team journal repository but cannot
|
|
15
|
+
push to it.
|
|
16
|
+
- djournal sync config that enables `pull` but does not enable automatic
|
|
17
|
+
publication.
|
|
18
|
+
- Agent prompts that ask for read-only skills such as `recall`, `research`, and
|
|
19
|
+
`document`, not implementation or journal closure.
|
|
20
|
+
|
|
21
|
+
This still writes local files under the user's djournal home. "Read-only" means
|
|
22
|
+
read-only with respect to the organization remote, not a filesystem mode that
|
|
23
|
+
prevents local cache or canonical-store hydration.
|
|
24
|
+
|
|
25
|
+
## Setup for a Non-Technical Reader
|
|
26
|
+
|
|
27
|
+
Ask the organization admin for the team journal repository URL and read-only Git
|
|
28
|
+
access. Then use this script-like sequence in a terminal from a working folder:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
npm install -g djournal
|
|
32
|
+
git clone <team-journal-repository-url> team-journal
|
|
33
|
+
cd team-journal
|
|
34
|
+
djournal install --instructions-only
|
|
35
|
+
djournal config sync.enabled true
|
|
36
|
+
djournal config sync.mode standalone
|
|
37
|
+
djournal config sync.path .
|
|
38
|
+
djournal config sync.auto false
|
|
39
|
+
djournal pull
|
|
40
|
+
djournal status
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Use `--instructions-only` when the person only needs portable journal skills and
|
|
44
|
+
does not need editor-specific hooks. Use a harness install instead when they
|
|
45
|
+
will use the journal from Codex, Claude Code, or Pi:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
djournal install --harness codex
|
|
49
|
+
djournal install --harness claude-code
|
|
50
|
+
djournal install --harness pi
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Do not run these commands in a read-only consumer setup:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
djournal share
|
|
57
|
+
djournal sync
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
If read-only Git permissions are configured correctly, accidental pushes should
|
|
61
|
+
fail at the remote even if someone runs a publication command.
|
|
62
|
+
|
|
63
|
+
## Copy/Paste Agent Prompt
|
|
64
|
+
|
|
65
|
+
Use this prompt after installation when asking an LLM agent to connect the local
|
|
66
|
+
checkout to the remote journal in read-only mode:
|
|
67
|
+
|
|
68
|
+
```text
|
|
69
|
+
Set up djournal for read-only team journal access.
|
|
70
|
+
|
|
71
|
+
The team journal repository is: <paste repository URL>
|
|
72
|
+
I only need to recall and research existing decisions. Do not publish, share,
|
|
73
|
+
sync, push, or create journal entries unless I explicitly ask later.
|
|
74
|
+
|
|
75
|
+
Please:
|
|
76
|
+
1. Verify Node.js and npm are available.
|
|
77
|
+
2. Install or update djournal with `npm install -g djournal`.
|
|
78
|
+
3. Clone the team journal repository if it is not already cloned.
|
|
79
|
+
4. Run `djournal install --instructions-only` in the cloned journal repository.
|
|
80
|
+
5. Configure standalone pull access with:
|
|
81
|
+
- `djournal config sync.enabled true`
|
|
82
|
+
- `djournal config sync.mode standalone`
|
|
83
|
+
- `djournal config sync.path .`
|
|
84
|
+
- `djournal config sync.auto false`
|
|
85
|
+
6. Run `djournal pull` and `djournal status`.
|
|
86
|
+
7. Report whether recall is ready and show the active work item if one exists.
|
|
87
|
+
|
|
88
|
+
Keep this setup read-only for the organization remote. If a command would write
|
|
89
|
+
to the remote, stop and explain why.
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Reader Prompts
|
|
93
|
+
|
|
94
|
+
Good prompts for read-only users:
|
|
95
|
+
|
|
96
|
+
```text
|
|
97
|
+
Recall why we chose the current billing webhook retry strategy.
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
```text
|
|
101
|
+
Find product decisions about onboarding and summarize the evidence.
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
```text
|
|
105
|
+
Research the journal history for risks in changing the checkout flow. Do not
|
|
106
|
+
edit files or write a journal entry.
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
```text
|
|
110
|
+
Show the timeline for the mobile launch work item and list unresolved decisions.
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Avoid prompts that imply write behavior unless the user really intends to
|
|
114
|
+
contribute:
|
|
115
|
+
|
|
116
|
+
- "Implement this"
|
|
117
|
+
- "Record a decision"
|
|
118
|
+
- "Share this work"
|
|
119
|
+
- "Sync my journal"
|
|
120
|
+
|
|
121
|
+
## Organization Admin Checklist
|
|
122
|
+
|
|
123
|
+
For a reader-friendly remote:
|
|
124
|
+
|
|
125
|
+
- Put shared journal projection content in a standalone Git repository.
|
|
126
|
+
- Grant readers clone/pull access only.
|
|
127
|
+
- Keep sensitive or local-only work out of the shared projection.
|
|
128
|
+
- Publish only reviewed work items with `djournal share` and `djournal sync`
|
|
129
|
+
from a maintainer machine or CI account.
|
|
130
|
+
- Provide the repository URL and the copy/paste setup prompt above.
|
|
131
|
+
|
|
132
|
+
## Product Gaps
|
|
133
|
+
|
|
134
|
+
The current workflow is usable but too manual for non-technical people. A better
|
|
135
|
+
first-class experience would add:
|
|
136
|
+
|
|
137
|
+
- `djournal connect <repo-url> --read-only`, which clones or opens the remote,
|
|
138
|
+
installs instructions, configures standalone pull, disables auto-sync, and
|
|
139
|
+
runs status.
|
|
140
|
+
- `djournal recall-ready`, or an expanded `status`, that explains in plain
|
|
141
|
+
language whether the local reader can use recall.
|
|
142
|
+
- A config flag such as `sync.readOnly: true` that causes `share` and `sync` to
|
|
143
|
+
fail before attempting Git publication.
|
|
144
|
+
- Documentation or generated prompts tailored per harness.
|
|
145
|
+
|
|
146
|
+
## Related docs
|
|
147
|
+
|
|
148
|
+
- [Installation and repository layouts](installation.md)
|
|
149
|
+
- [Remote Git sync setup](remote-sync.md)
|
|
150
|
+
- [Visibility and sharing](visibility-and-sharing.md)
|
package/docs/remote-sync.md
CHANGED
|
@@ -181,5 +181,6 @@ The durable team memory is the work item content: `work.md`, `journal/`,
|
|
|
181
181
|
|
|
182
182
|
## Related docs
|
|
183
183
|
|
|
184
|
+
- [Read-only team journal access](read-only-team-journal.md)
|
|
184
185
|
- [Visibility and sharing](visibility-and-sharing.md)
|
|
185
186
|
- [Architecture and data model](architecture.md)
|
package/lib/installer/index.js
CHANGED
|
@@ -14,6 +14,13 @@ const {
|
|
|
14
14
|
removeManagedBlock,
|
|
15
15
|
upsertManagedBlock,
|
|
16
16
|
} = require("./merge.js");
|
|
17
|
+
const {
|
|
18
|
+
cacheIsStale,
|
|
19
|
+
deriveUpdateState,
|
|
20
|
+
passiveChecksEnabled,
|
|
21
|
+
readCache: readUpdateCache,
|
|
22
|
+
refreshCache: refreshUpdateCache,
|
|
23
|
+
} = require("../update-checker.js");
|
|
17
24
|
|
|
18
25
|
const SCHEMA_VERSION = 1;
|
|
19
26
|
const SUPPORTED_HARNESSES = ["codex", "claude-code", "pi"];
|
|
@@ -167,6 +174,10 @@ function defaultProjectConfig(target, store) {
|
|
|
167
174
|
default: "local_only",
|
|
168
175
|
sharedWorkItems: {},
|
|
169
176
|
},
|
|
177
|
+
updates: {
|
|
178
|
+
enabled: true,
|
|
179
|
+
intervalHours: 24,
|
|
180
|
+
},
|
|
170
181
|
};
|
|
171
182
|
}
|
|
172
183
|
|
|
@@ -255,6 +266,10 @@ function packageVersion(sourceRoot) {
|
|
|
255
266
|
return parseJson(fs.readFileSync(path.join(sourceRoot, "package.json")), "package.json").version;
|
|
256
267
|
}
|
|
257
268
|
|
|
269
|
+
function packageSourceRoot(options = {}) {
|
|
270
|
+
return path.resolve(options.sourceRoot || path.join(__dirname, "../.."));
|
|
271
|
+
}
|
|
272
|
+
|
|
258
273
|
function commandExists(command, env = process.env) {
|
|
259
274
|
const pathValue = env.PATH || "";
|
|
260
275
|
const extensions = process.platform === "win32"
|
|
@@ -414,7 +429,7 @@ function markdownRecord(target, relative, body, oldRecord, harness) {
|
|
|
414
429
|
|
|
415
430
|
function journalAccessFragment(harness, store) {
|
|
416
431
|
if (harness !== "claude-code") return {};
|
|
417
|
-
const commands = ["status", "doctor", "config", "share", "sync"];
|
|
432
|
+
const commands = ["status", "doctor", "config", "share", "sync", "update"];
|
|
418
433
|
return {
|
|
419
434
|
permissions: {
|
|
420
435
|
additionalDirectories: [store.root],
|
|
@@ -572,6 +587,17 @@ function readActiveWork(context, requested) {
|
|
|
572
587
|
return { slug, relative, file, text, metadata, visibility: metadata.visibility || "local_only" };
|
|
573
588
|
}
|
|
574
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
|
+
|
|
575
601
|
function readAllWork(context) {
|
|
576
602
|
const workRoot = path.join(context.journalRoot, "work");
|
|
577
603
|
const entries = fs.existsSync(workRoot) ? fs.readdirSync(workRoot, { withFileTypes: true }) : [];
|
|
@@ -585,6 +611,53 @@ function readAllWork(context) {
|
|
|
585
611
|
return workItems;
|
|
586
612
|
}
|
|
587
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
|
+
|
|
588
661
|
function readJournalConfig(target) {
|
|
589
662
|
const context = projectContext(target);
|
|
590
663
|
return readProjectConfig(context);
|
|
@@ -1288,9 +1361,54 @@ function recordStatus(target, record) {
|
|
|
1288
1361
|
function status(options) {
|
|
1289
1362
|
const target = checkTarget(options.target || process.cwd());
|
|
1290
1363
|
const manifest = loadManifest(target);
|
|
1291
|
-
|
|
1364
|
+
const config = readProjectConfig(projectContext(target, options));
|
|
1365
|
+
const cache = readUpdateCache(options);
|
|
1366
|
+
const updateState = deriveUpdateState({
|
|
1367
|
+
cliVersion: packageVersion(packageSourceRoot(options)),
|
|
1368
|
+
projectVersion: manifest?.toolVersion,
|
|
1369
|
+
cache,
|
|
1370
|
+
});
|
|
1371
|
+
const updateChecksEnabled = passiveChecksEnabled(config, options.env || process.env, { allowTest: options.allowTest });
|
|
1372
|
+
if (!manifest) return { installed: false, target, ...updateState, updateChecksEnabled };
|
|
1292
1373
|
const files = manifest.files.map((record) => ({ path: record.path, mode: record.mode, status: recordStatus(target, record) }));
|
|
1293
|
-
return {
|
|
1374
|
+
return {
|
|
1375
|
+
installed: true,
|
|
1376
|
+
target,
|
|
1377
|
+
toolVersion: manifest.toolVersion,
|
|
1378
|
+
...updateState,
|
|
1379
|
+
updateChecksEnabled,
|
|
1380
|
+
harnesses: manifest.harnesses,
|
|
1381
|
+
files,
|
|
1382
|
+
clean: files.every((file) => file.status === "clean"),
|
|
1383
|
+
};
|
|
1384
|
+
}
|
|
1385
|
+
|
|
1386
|
+
async function checkUpdates(options) {
|
|
1387
|
+
const target = checkTarget(options.target || process.cwd());
|
|
1388
|
+
const manifest = loadManifest(target);
|
|
1389
|
+
const config = readProjectConfig(projectContext(target, options));
|
|
1390
|
+
const cliVersion = packageVersion(packageSourceRoot(options));
|
|
1391
|
+
const enabled = passiveChecksEnabled(config, options.env || process.env, { allowTest: options.allowTest });
|
|
1392
|
+
let cache = readUpdateCache(options);
|
|
1393
|
+
let refreshed = false;
|
|
1394
|
+
if (!options.passive || options.refreshCache) {
|
|
1395
|
+
try {
|
|
1396
|
+
cache = await refreshUpdateCache({ ...options, cliVersion, packageName: "djournal" });
|
|
1397
|
+
refreshed = true;
|
|
1398
|
+
} catch (error) {
|
|
1399
|
+
throw new InstallerError(error.message, error.code || "UPDATE_CHECK_FAILED");
|
|
1400
|
+
}
|
|
1401
|
+
}
|
|
1402
|
+
const stale = cacheIsStale(cache, { config, now: options.now });
|
|
1403
|
+
return {
|
|
1404
|
+
action: "update-check",
|
|
1405
|
+
target,
|
|
1406
|
+
enabled,
|
|
1407
|
+
stale,
|
|
1408
|
+
refreshNeeded: Boolean(options.passive && enabled && stale),
|
|
1409
|
+
refreshed,
|
|
1410
|
+
...deriveUpdateState({ cliVersion, projectVersion: manifest?.toolVersion, cache }),
|
|
1411
|
+
};
|
|
1294
1412
|
}
|
|
1295
1413
|
|
|
1296
1414
|
module.exports = {
|
|
@@ -1299,12 +1417,15 @@ module.exports = {
|
|
|
1299
1417
|
PROJECT_MARKER_PATH,
|
|
1300
1418
|
SUPPORTED_HARNESSES,
|
|
1301
1419
|
applyTransaction,
|
|
1420
|
+
checkUpdates,
|
|
1421
|
+
bindWork,
|
|
1302
1422
|
configure,
|
|
1303
1423
|
detectHarnesses,
|
|
1304
1424
|
doctor,
|
|
1305
1425
|
djournalHome,
|
|
1306
1426
|
install,
|
|
1307
1427
|
loadManifest,
|
|
1428
|
+
listWork,
|
|
1308
1429
|
pull,
|
|
1309
1430
|
projectContext,
|
|
1310
1431
|
recoverTransaction,
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
const crypto = require("node:crypto");
|
|
4
|
+
const fs = require("node:fs");
|
|
5
|
+
const os = require("node:os");
|
|
6
|
+
const path = require("node:path");
|
|
7
|
+
const semver = require("semver");
|
|
8
|
+
|
|
9
|
+
const CACHE_FILENAME = "update-check.json";
|
|
10
|
+
const DEFAULT_INTERVAL_HOURS = 24;
|
|
11
|
+
const DEFAULT_TIMEOUT_MS = 3000;
|
|
12
|
+
const MAX_RESPONSE_BYTES = 1024 * 1024;
|
|
13
|
+
const REGISTRY_ACCEPT = "application/vnd.npm.install-v1+json";
|
|
14
|
+
|
|
15
|
+
class UpdateCheckError extends Error {
|
|
16
|
+
constructor(message, code = "UPDATE_CHECK_FAILED") {
|
|
17
|
+
super(message);
|
|
18
|
+
this.name = "UpdateCheckError";
|
|
19
|
+
this.code = code;
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
function djournalHome(options = {}) {
|
|
24
|
+
return path.resolve(options.djournalHome || process.env.DJOURNAL_HOME || path.join(os.homedir(), ".djournal"));
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function cacheFile(options = {}) {
|
|
28
|
+
return path.resolve(options.cacheFile || path.join(djournalHome(options), CACHE_FILENAME));
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
function validVersion(value) {
|
|
32
|
+
return typeof value === "string" ? semver.valid(value) : null;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
function normalizeCache(value) {
|
|
36
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) return null;
|
|
37
|
+
const latestVersion = validVersion(value.latestVersion);
|
|
38
|
+
const checkedAt = typeof value.checkedAt === "string" && Number.isFinite(Date.parse(value.checkedAt))
|
|
39
|
+
? new Date(value.checkedAt).toISOString()
|
|
40
|
+
: null;
|
|
41
|
+
const distTag = typeof value.distTag === "string" && value.distTag ? value.distTag : null;
|
|
42
|
+
if (!latestVersion || !checkedAt || !distTag) return null;
|
|
43
|
+
return { checkedAt, latestVersion, distTag };
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function readCache(options = {}) {
|
|
47
|
+
try {
|
|
48
|
+
const file = cacheFile(options);
|
|
49
|
+
const stat = fs.statSync(file);
|
|
50
|
+
if (!stat.isFile() || stat.size > MAX_RESPONSE_BYTES) return null;
|
|
51
|
+
return normalizeCache(JSON.parse(fs.readFileSync(file, "utf8")));
|
|
52
|
+
} catch {
|
|
53
|
+
return null;
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
function writeCache(value, options = {}) {
|
|
58
|
+
const normalized = normalizeCache(value);
|
|
59
|
+
if (!normalized) throw new UpdateCheckError("update cache is invalid", "INVALID_UPDATE_CACHE");
|
|
60
|
+
const file = cacheFile(options);
|
|
61
|
+
const directory = path.dirname(file);
|
|
62
|
+
fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
|
|
63
|
+
const temporary = path.join(directory, `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`);
|
|
64
|
+
try {
|
|
65
|
+
fs.writeFileSync(temporary, `${JSON.stringify(normalized, null, 2)}\n`, { mode: 0o600 });
|
|
66
|
+
fs.renameSync(temporary, file);
|
|
67
|
+
} catch (error) {
|
|
68
|
+
try { fs.unlinkSync(temporary); } catch {}
|
|
69
|
+
throw error;
|
|
70
|
+
}
|
|
71
|
+
return normalized;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
function intervalHours(config = {}) {
|
|
75
|
+
const value = config?.updates?.intervalHours;
|
|
76
|
+
return Number.isFinite(value) && value > 0 ? value : DEFAULT_INTERVAL_HOURS;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
function cacheIsStale(cache, options = {}) {
|
|
80
|
+
if (!cache) return true;
|
|
81
|
+
const now = options.now instanceof Date ? options.now.getTime() : Number(options.now ?? Date.now());
|
|
82
|
+
const checkedAt = Date.parse(cache.checkedAt);
|
|
83
|
+
const intervalMs = intervalHours(options.config) * 60 * 60 * 1000;
|
|
84
|
+
return !Number.isFinite(now) || !Number.isFinite(checkedAt) || now - checkedAt >= intervalMs;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
function environmentFlag(value) {
|
|
88
|
+
return typeof value === "string" ? !["", "0", "false"].includes(value.toLowerCase()) : Boolean(value);
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
function passiveChecksEnabled(config = {}, env = process.env, options = {}) {
|
|
92
|
+
if (config?.updates?.enabled === false) return false;
|
|
93
|
+
if (environmentFlag(env.NO_UPDATE_NOTIFIER) || environmentFlag(env.CI)) return false;
|
|
94
|
+
if (!options.allowTest && (env.NODE_ENV === "test" || environmentFlag(env.NODE_TEST_CONTEXT))) return false;
|
|
95
|
+
return true;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
function deriveUpdateState(options = {}) {
|
|
99
|
+
const cliVersion = validVersion(options.cliVersion);
|
|
100
|
+
const projectVersion = validVersion(options.projectVersion);
|
|
101
|
+
const cache = normalizeCache(options.cache);
|
|
102
|
+
const latestVersion = cache?.latestVersion || null;
|
|
103
|
+
return {
|
|
104
|
+
cliVersion,
|
|
105
|
+
projectVersion,
|
|
106
|
+
latestVersion,
|
|
107
|
+
checkedAt: cache?.checkedAt || null,
|
|
108
|
+
distTag: cache?.distTag || options.distTag || "latest",
|
|
109
|
+
updateAvailable: Boolean(cliVersion && latestVersion && semver.gt(latestVersion, cliVersion)),
|
|
110
|
+
projectUpdateAvailable: Boolean(cliVersion && projectVersion && semver.gt(cliVersion, projectVersion)),
|
|
111
|
+
};
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
async function fetchLatest(options = {}) {
|
|
115
|
+
const fetchImpl = options.fetchImpl || globalThis.fetch;
|
|
116
|
+
if (typeof fetchImpl !== "function") throw new UpdateCheckError("fetch is unavailable", "UPDATE_FETCH_UNAVAILABLE");
|
|
117
|
+
const packageName = options.packageName || "djournal";
|
|
118
|
+
const distTag = options.distTag || "latest";
|
|
119
|
+
const timeoutMs = options.timeoutMs || DEFAULT_TIMEOUT_MS;
|
|
120
|
+
const signal = options.signal || AbortSignal.timeout(timeoutMs);
|
|
121
|
+
let response;
|
|
122
|
+
try {
|
|
123
|
+
response = await fetchImpl(`https://registry.npmjs.org/${encodeURIComponent(packageName)}`, {
|
|
124
|
+
headers: {
|
|
125
|
+
accept: REGISTRY_ACCEPT,
|
|
126
|
+
"user-agent": `${packageName}/${options.cliVersion || "unknown"}`,
|
|
127
|
+
},
|
|
128
|
+
signal,
|
|
129
|
+
});
|
|
130
|
+
} catch (error) {
|
|
131
|
+
throw new UpdateCheckError(`npm registry request failed: ${error.message}`, "UPDATE_NETWORK_FAILED");
|
|
132
|
+
}
|
|
133
|
+
if (!response || response.ok !== true) {
|
|
134
|
+
throw new UpdateCheckError(`npm registry returned HTTP ${response?.status || "unknown"}`, "UPDATE_HTTP_FAILED");
|
|
135
|
+
}
|
|
136
|
+
const text = await response.text();
|
|
137
|
+
if (Buffer.byteLength(text) > MAX_RESPONSE_BYTES) {
|
|
138
|
+
throw new UpdateCheckError("npm registry response is too large", "UPDATE_RESPONSE_INVALID");
|
|
139
|
+
}
|
|
140
|
+
let metadata;
|
|
141
|
+
try { metadata = JSON.parse(text); } catch {
|
|
142
|
+
throw new UpdateCheckError("npm registry response is not valid JSON", "UPDATE_RESPONSE_INVALID");
|
|
143
|
+
}
|
|
144
|
+
const latestVersion = validVersion(metadata?.["dist-tags"]?.[distTag]);
|
|
145
|
+
if (!latestVersion) {
|
|
146
|
+
throw new UpdateCheckError(`npm registry response has no valid ${distTag} version`, "UPDATE_RESPONSE_INVALID");
|
|
147
|
+
}
|
|
148
|
+
return { latestVersion, distTag };
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
async function refreshCache(options = {}) {
|
|
152
|
+
const latest = await fetchLatest(options);
|
|
153
|
+
const now = options.now instanceof Date ? options.now : new Date(options.now ?? Date.now());
|
|
154
|
+
if (!Number.isFinite(now.getTime())) throw new UpdateCheckError("current time is invalid", "UPDATE_TIME_INVALID");
|
|
155
|
+
return writeCache({ ...latest, checkedAt: now.toISOString() }, options);
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
module.exports = {
|
|
159
|
+
CACHE_FILENAME,
|
|
160
|
+
DEFAULT_INTERVAL_HOURS,
|
|
161
|
+
DEFAULT_TIMEOUT_MS,
|
|
162
|
+
MAX_RESPONSE_BYTES,
|
|
163
|
+
REGISTRY_ACCEPT,
|
|
164
|
+
UpdateCheckError,
|
|
165
|
+
cacheFile,
|
|
166
|
+
cacheIsStale,
|
|
167
|
+
deriveUpdateState,
|
|
168
|
+
djournalHome,
|
|
169
|
+
fetchLatest,
|
|
170
|
+
intervalHours,
|
|
171
|
+
normalizeCache,
|
|
172
|
+
passiveChecksEnabled,
|
|
173
|
+
readCache,
|
|
174
|
+
refreshCache,
|
|
175
|
+
validVersion,
|
|
176
|
+
writeCache,
|
|
177
|
+
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "djournal",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.0",
|
|
4
4
|
"description": "Durable project memory for coding agents, stored as linked Markdown",
|
|
5
5
|
"type": "commonjs",
|
|
6
6
|
"bin": {
|
|
@@ -26,7 +26,7 @@
|
|
|
26
26
|
"check:pr-title": "node scripts/check-pr-title.js",
|
|
27
27
|
"link:global": "npm link",
|
|
28
28
|
"release": "semantic-release",
|
|
29
|
-
"test": "node tests/journal-hook.test.js && node tests/pi-adapter.test.js && node tests/installer/installer.test.js && node tests/release-policy.test.js && node tests/skill-instructions.test.js && npm run check:package",
|
|
29
|
+
"test": "node tests/update-checker.test.js && node tests/journal-hook.test.js && node tests/pi-adapter.test.js && node tests/installer/installer.test.js && node tests/release-policy.test.js && node tests/skill-instructions.test.js && npm run check:package",
|
|
30
30
|
"prepublishOnly": "npm test"
|
|
31
31
|
},
|
|
32
32
|
"repository": {
|
|
@@ -54,5 +54,8 @@
|
|
|
54
54
|
},
|
|
55
55
|
"devDependencies": {
|
|
56
56
|
"semantic-release": "25.0.3"
|
|
57
|
+
},
|
|
58
|
+
"dependencies": {
|
|
59
|
+
"semver": "7.8.5"
|
|
57
60
|
}
|
|
58
61
|
}
|