djournal 0.5.1 → 0.7.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/contract.md +4 -3
- package/.agents/adapters/shared/journal-hook.js +81 -6
- package/.agents/skills/init-work/SKILL.md +12 -9
- package/.agents/skills/switch/SKILL.md +11 -8
- package/.claude/settings.json +3 -3
- package/.codex/hooks.json +3 -3
- package/README.md +14 -4
- package/bin/journal.js +55 -2
- package/docs/architecture.md +10 -3
- package/docs/djournal-in-practice.md +14 -0
- package/docs/installation.md +51 -6
- package/docs/read-only-team-journal.md +150 -0
- package/docs/remote-sync.md +49 -10
- package/docs/visibility-and-sharing.md +12 -4
- package/lib/installer/index.js +353 -10
- package/lib/update-checker.js +177 -0
- package/package.json +5 -2
|
@@ -7,8 +7,8 @@ second workflow engine and do not own durable state.
|
|
|
7
7
|
|
|
8
8
|
| Event | Adapter behavior |
|
|
9
9
|
| --- | --- |
|
|
10
|
-
| `session_start` |
|
|
11
|
-
| `prompt_submit` |
|
|
10
|
+
| `session_start` | Pull configured standalone journal transport, then inject active work and `AGENTS.md` context |
|
|
11
|
+
| `prompt_submit` | Pull for explicit journal-sync intent, remind the agent to classify the request, and preserve opt-out |
|
|
12
12
|
| `mutation_observed` | Optional ephemeral reminder only; never write state |
|
|
13
13
|
| `before_compact` | Optional reminder to preserve material state before context loss |
|
|
14
14
|
| `stop` | Validate the final journal status marker and request one closure pass |
|
|
@@ -40,7 +40,8 @@ native payloads to these names.
|
|
|
40
40
|
|
|
41
41
|
## Invariants
|
|
42
42
|
|
|
43
|
-
- Hooks
|
|
43
|
+
- Hooks do not create or edit semantic journal entries. They may delegate
|
|
44
|
+
configured pull/sync transport to the CLI.
|
|
44
45
|
- `stop_hook_active: true` always permits stopping.
|
|
45
46
|
- `closed` markers must resolve to an existing Markdown spine entry under the
|
|
46
47
|
resolved journal root. Agents emit canonical repository-relative
|
|
@@ -97,6 +97,18 @@ function shouldAutoSync(root) {
|
|
|
97
97
|
return config.enabled === true && config.auto === true && config.mode === "standalone";
|
|
98
98
|
}
|
|
99
99
|
|
|
100
|
+
function environmentFlag(value) {
|
|
101
|
+
return typeof value === "string" ? !["", "0", "false"].includes(value.toLowerCase()) : Boolean(value);
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
function shouldCheckUpdates(root, env = process.env, options = {}) {
|
|
105
|
+
const config = readConfig(projectContext(root));
|
|
106
|
+
if (config.updates?.enabled === false) return false;
|
|
107
|
+
if (environmentFlag(env.NO_UPDATE_NOTIFIER) || environmentFlag(env.CI)) return false;
|
|
108
|
+
if (!options.allowTest && (env.NODE_ENV === "test" || environmentFlag(env.NODE_TEST_CONTEXT))) return false;
|
|
109
|
+
return true;
|
|
110
|
+
}
|
|
111
|
+
|
|
100
112
|
function context(event, message) {
|
|
101
113
|
return {
|
|
102
114
|
hookSpecificOutput: {
|
|
@@ -158,9 +170,9 @@ function validateClosedPath(root, value) {
|
|
|
158
170
|
return !!resolveClosedEntry(root, value);
|
|
159
171
|
}
|
|
160
172
|
|
|
161
|
-
function
|
|
173
|
+
function runJournal(root, args, runner) {
|
|
162
174
|
const run = runner || ((command, args, options) => spawnSync(command, args, options));
|
|
163
|
-
const result = run("journal",
|
|
175
|
+
const result = run("journal", args, {
|
|
164
176
|
cwd: root,
|
|
165
177
|
encoding: "utf8",
|
|
166
178
|
timeout: 30000,
|
|
@@ -173,15 +185,62 @@ function syncSharedWork(root, work, runner) {
|
|
|
173
185
|
return { ok: true, message: (result.stdout || "").trim() };
|
|
174
186
|
}
|
|
175
187
|
|
|
188
|
+
function runUpdateCheck(root, runner) {
|
|
189
|
+
const run = runner || ((command, args, options) => spawnSync(command, args, options));
|
|
190
|
+
const result = run("journal", ["update", "check", "--passive", "--json"], {
|
|
191
|
+
cwd: root,
|
|
192
|
+
encoding: "utf8",
|
|
193
|
+
timeout: 5000,
|
|
194
|
+
});
|
|
195
|
+
if (result.error || result.status !== 0) return null;
|
|
196
|
+
try {
|
|
197
|
+
const value = JSON.parse(result.stdout || "");
|
|
198
|
+
return value && typeof value === "object" && value.enabled !== false ? value : null;
|
|
199
|
+
} catch {
|
|
200
|
+
return null;
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
function updateNotice(value) {
|
|
205
|
+
if (!value) return "";
|
|
206
|
+
const messages = [];
|
|
207
|
+
if (value.updateAvailable && value.cliVersion && value.latestVersion) {
|
|
208
|
+
messages.push(`djournal ${value.latestVersion} is available (CLI ${value.cliVersion}). Update the npm package, then run \`djournal upgrade\` in this project.`);
|
|
209
|
+
}
|
|
210
|
+
if (value.projectUpdateAvailable && value.projectVersion && value.cliVersion) {
|
|
211
|
+
messages.push(`This project uses djournal assets ${value.projectVersion}; CLI ${value.cliVersion} is installed. Run \`djournal upgrade\`.`);
|
|
212
|
+
}
|
|
213
|
+
return messages.length ? ` ${messages.join(" ")}` : "";
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
function requestsJournalSync(prompt) {
|
|
217
|
+
const match = prompt.match(/\b(?:sync|synchronize|pull)\s+(?:the\s+)?journal\b|\bjournal\s+(?:sync|synchronize|pull)\b/i);
|
|
218
|
+
if (!match) return false;
|
|
219
|
+
const prefix = prompt.slice(Math.max(0, match.index - 32), match.index);
|
|
220
|
+
return !/\b(?:do\s+not|don't|dont|not|without|avoid|skip)\b[^.!?]*$/i.test(prefix);
|
|
221
|
+
}
|
|
222
|
+
|
|
176
223
|
function handle(payload, options = {}) {
|
|
177
224
|
const event = payload.hook_event_name;
|
|
178
225
|
const root = findRoot(payload.cwd);
|
|
179
226
|
if (!root) return {};
|
|
180
227
|
|
|
181
228
|
if (event === "SessionStart") {
|
|
229
|
+
let pullMessage = "";
|
|
230
|
+
if (shouldAutoSync(root)) {
|
|
231
|
+
const result = runJournal(root, ["pull", "--auto"], options.journalRunner || options.syncRunner);
|
|
232
|
+
pullMessage = result.ok
|
|
233
|
+
? " Journal pull completed before loading active work."
|
|
234
|
+
: ` Automatic journal pull failed: ${result.message}`;
|
|
235
|
+
}
|
|
236
|
+
const env = options.env || process.env;
|
|
237
|
+
const allowTest = typeof options.updateRunner === "function";
|
|
238
|
+
const updateMessage = shouldCheckUpdates(root, env, { allowTest })
|
|
239
|
+
? updateNotice(runUpdateCheck(root, options.updateRunner))
|
|
240
|
+
: "";
|
|
182
241
|
const work = activeWork(root);
|
|
183
242
|
const suffix = work ? ` Active work: ${work.slug}.` : " No valid active work is selected.";
|
|
184
|
-
return context(event, `Follow AGENTS.md and .agents/rules/AUTOMATION.md.${suffix}`);
|
|
243
|
+
return context(event, `Follow AGENTS.md and .agents/rules/AUTOMATION.md.${pullMessage}${updateMessage}${suffix}`);
|
|
185
244
|
}
|
|
186
245
|
|
|
187
246
|
if (event === "UserPromptSubmit") {
|
|
@@ -189,6 +248,13 @@ function handle(payload, options = {}) {
|
|
|
189
248
|
if (/\bjournal\s*:\s*off\b/i.test(prompt)) {
|
|
190
249
|
return context(event, "Journal opt-out applies to this request. End with the journal-status: off marker.");
|
|
191
250
|
}
|
|
251
|
+
if (requestsJournalSync(prompt)) {
|
|
252
|
+
const result = runJournal(root, ["pull"], options.journalRunner || options.syncRunner);
|
|
253
|
+
const pullMessage = result.ok
|
|
254
|
+
? "The journal was pulled before handling this explicit synchronization request."
|
|
255
|
+
: `The requested journal pull failed and must be resolved before publication: ${result.message}`;
|
|
256
|
+
return context(event, `${pullMessage} Classify this request using the ambient journal workflow and run journal sync if publication was requested.`);
|
|
257
|
+
}
|
|
192
258
|
return context(event, "Classify this request using the ambient journal workflow. Close meaningful changed state before the final response, without adding ceremony to read-only or trivial work.");
|
|
193
259
|
}
|
|
194
260
|
|
|
@@ -217,11 +283,11 @@ function handle(payload, options = {}) {
|
|
|
217
283
|
if (status === "closed") {
|
|
218
284
|
const work = workBySlug(root, closedEntry.workSlug);
|
|
219
285
|
if ((work?.shared || work?.visibility === "team_shared") && shouldAutoSync(root)) {
|
|
220
|
-
const result =
|
|
286
|
+
const result = runJournal(root, ["sync", "--auto", "--work", work.slug], options.journalRunner || options.syncRunner);
|
|
221
287
|
if (!result.ok) {
|
|
222
288
|
return context(event, `Journal entry is closed and shared work automatic journal sync failed: ${result.message}`);
|
|
223
289
|
}
|
|
224
|
-
return context(event, "Journal entry is closed
|
|
290
|
+
return context(event, "Journal entry is closed; remote work was pulled before shared work was synchronized.");
|
|
225
291
|
}
|
|
226
292
|
}
|
|
227
293
|
return {};
|
|
@@ -242,4 +308,13 @@ if (require.main === module) {
|
|
|
242
308
|
main();
|
|
243
309
|
}
|
|
244
310
|
|
|
245
|
-
module.exports = {
|
|
311
|
+
module.exports = {
|
|
312
|
+
handle,
|
|
313
|
+
parseFrontmatter,
|
|
314
|
+
requestsJournalSync,
|
|
315
|
+
resolveClosedEntry,
|
|
316
|
+
runUpdateCheck,
|
|
317
|
+
shouldAutoSync,
|
|
318
|
+
shouldCheckUpdates,
|
|
319
|
+
updateNotice,
|
|
320
|
+
};
|
|
@@ -14,16 +14,19 @@ Create one project-level work item. Work items may span repositories.
|
|
|
14
14
|
- `.agents/rules/METADATA.md`
|
|
15
15
|
- `.agents/rules/SAFETY.md`
|
|
16
16
|
- `.agents/rules/STATE.md`
|
|
17
|
-
2.
|
|
17
|
+
2. Run `djournal pull` from the project root before inspecting existing work.
|
|
18
|
+
Continue when synchronization is disabled or no projection exists. Stop and
|
|
19
|
+
report any unresolved pull conflict before creating a work item.
|
|
20
|
+
3. Require a non-empty work name or infer one only when the user's requested
|
|
18
21
|
project is unambiguous.
|
|
19
|
-
|
|
22
|
+
4. Resolve the journal root according to `STATE.md`. List `<journal-root>/work/`
|
|
20
23
|
when it exists. Reject an equivalent existing work item instead of creating a
|
|
21
24
|
duplicate.
|
|
22
|
-
|
|
25
|
+
5. Build the folder slug as `YYYY-MM-DD-NN-kebab-case-name` using the current UTC
|
|
23
26
|
date and next unused daily sequence.
|
|
24
|
-
|
|
27
|
+
6. Resolve `createdBy`, generate a `wi_` UUIDv7, and capture one canonical UTC
|
|
25
28
|
timestamp according to `METADATA.md`.
|
|
26
|
-
|
|
29
|
+
7. Create:
|
|
27
30
|
|
|
28
31
|
```text
|
|
29
32
|
<journal-root>/work/<slug>/
|
|
@@ -34,12 +37,12 @@ Create one project-level work item. Work items may span repositories.
|
|
|
34
37
|
└── decisions/
|
|
35
38
|
```
|
|
36
39
|
|
|
37
|
-
|
|
40
|
+
8. Write `work.md` with the exact work-item frontmatter contract. Use:
|
|
38
41
|
- `status: active`
|
|
39
42
|
- `visibility: local_only`
|
|
40
43
|
- identical `createdAt` and `updatedAt`
|
|
41
44
|
- a concise title and description
|
|
42
|
-
|
|
45
|
+
9. Add a short body:
|
|
43
46
|
|
|
44
47
|
```markdown
|
|
45
48
|
# <Title>
|
|
@@ -49,9 +52,9 @@ Create one project-level work item. Work items may span repositories.
|
|
|
49
52
|
<What outcome this work item exists to achieve.>
|
|
50
53
|
```
|
|
51
54
|
|
|
52
|
-
|
|
55
|
+
10. Create or update `<journal-root>/state.json` to select the new slug. Preserve
|
|
53
56
|
the exact state shape from `STATE.md` and make the update safely.
|
|
54
|
-
|
|
57
|
+
11. Re-read `work.md` and state. Verify slug, IDs, directories, timestamps,
|
|
55
58
|
status, visibility, and JSON validity.
|
|
56
59
|
|
|
57
60
|
## Constraints
|
|
@@ -10,19 +10,22 @@ Switch journal context only. Work items are projects and are not Git branches.
|
|
|
10
10
|
## Procedure
|
|
11
11
|
|
|
12
12
|
1. Read `.agents/rules/STATE.md`, `FEAT.md`, `METADATA.md`, and `SAFETY.md`.
|
|
13
|
-
2.
|
|
13
|
+
2. Run `djournal pull` from the project root so remote-only and recently updated
|
|
14
|
+
work is present before selection. Continue when synchronization is disabled
|
|
15
|
+
or no projection exists. Stop and report unresolved pull conflicts.
|
|
16
|
+
3. Resolve the journal root according to `STATE.md`; read current state when
|
|
14
17
|
valid.
|
|
15
|
-
|
|
18
|
+
4. Enumerate `<journal-root>/work/*/work.md` and show slug, title, status, and
|
|
16
19
|
visibility. Include legacy folders with incomplete metadata.
|
|
17
|
-
|
|
20
|
+
5. Match the argument by exact slug first, then unique title/slug substring.
|
|
18
21
|
If omitted, missing, or ambiguous, request one explicit selection.
|
|
19
|
-
|
|
20
|
-
|
|
22
|
+
6. If already selected, report that and stop.
|
|
23
|
+
7. Optionally inspect Git status read-only and mention uncommitted changes, but do
|
|
21
24
|
not commit, stash, switch branches, or block the journal switch.
|
|
22
|
-
|
|
25
|
+
8. Update `<journal-root>/state.json` atomically to the selected slug using the
|
|
23
26
|
exact shape in `STATE.md`.
|
|
24
|
-
|
|
25
|
-
|
|
27
|
+
9. Re-read state and verify the target folder and `work.md` slug.
|
|
28
|
+
10. Present the selected work's latest spine summary and next steps using the
|
|
26
29
|
`resume` retrieval procedure.
|
|
27
30
|
|
|
28
31
|
## Constraints
|
package/.claude/settings.json
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
"type": "command",
|
|
9
9
|
"command": "node",
|
|
10
10
|
"args": ["${CLAUDE_PROJECT_DIR}/.agents/adapters/shared/journal-hook.js", "--harness", "claude-code"],
|
|
11
|
-
"timeout":
|
|
11
|
+
"timeout": 45,
|
|
12
12
|
"statusMessage": "Loading journal workflow"
|
|
13
13
|
}
|
|
14
14
|
]
|
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
"type": "command",
|
|
22
22
|
"command": "node",
|
|
23
23
|
"args": ["${CLAUDE_PROJECT_DIR}/.agents/adapters/shared/journal-hook.js", "--harness", "claude-code"],
|
|
24
|
-
"timeout":
|
|
24
|
+
"timeout": 45
|
|
25
25
|
}
|
|
26
26
|
]
|
|
27
27
|
}
|
|
@@ -33,7 +33,7 @@
|
|
|
33
33
|
"type": "command",
|
|
34
34
|
"command": "node",
|
|
35
35
|
"args": ["${CLAUDE_PROJECT_DIR}/.agents/adapters/shared/journal-hook.js", "--harness", "claude-code"],
|
|
36
|
-
"timeout":
|
|
36
|
+
"timeout": 45,
|
|
37
37
|
"statusMessage": "Checking journal closure"
|
|
38
38
|
}
|
|
39
39
|
]
|
package/.codex/hooks.json
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
{
|
|
8
8
|
"type": "command",
|
|
9
9
|
"command": "sh -c 'd=\"$PWD\"; while [ \"$d\" != / ] && [ ! -f \"$d/.agents/adapters/shared/journal-hook.js\" ]; do d=\"$(dirname \"$d\")\"; done; [ -f \"$d/.agents/adapters/shared/journal-hook.js\" ] || exit 0; exec node \"$d/.agents/adapters/shared/journal-hook.js\" --harness codex'",
|
|
10
|
-
"timeout":
|
|
10
|
+
"timeout": 45,
|
|
11
11
|
"statusMessage": "Loading journal workflow"
|
|
12
12
|
}
|
|
13
13
|
]
|
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
{
|
|
20
20
|
"type": "command",
|
|
21
21
|
"command": "sh -c 'd=\"$PWD\"; while [ \"$d\" != / ] && [ ! -f \"$d/.agents/adapters/shared/journal-hook.js\" ]; do d=\"$(dirname \"$d\")\"; done; [ -f \"$d/.agents/adapters/shared/journal-hook.js\" ] || exit 0; exec node \"$d/.agents/adapters/shared/journal-hook.js\" --harness codex'",
|
|
22
|
-
"timeout":
|
|
22
|
+
"timeout": 45
|
|
23
23
|
}
|
|
24
24
|
]
|
|
25
25
|
}
|
|
@@ -30,7 +30,7 @@
|
|
|
30
30
|
{
|
|
31
31
|
"type": "command",
|
|
32
32
|
"command": "sh -c 'd=\"$PWD\"; while [ \"$d\" != / ] && [ ! -f \"$d/.agents/adapters/shared/journal-hook.js\" ]; do d=\"$(dirname \"$d\")\"; done; [ -f \"$d/.agents/adapters/shared/journal-hook.js\" ] || exit 0; exec node \"$d/.agents/adapters/shared/journal-hook.js\" --harness codex'",
|
|
33
|
-
"timeout":
|
|
33
|
+
"timeout": 45,
|
|
34
34
|
"statusMessage": "Checking journal closure"
|
|
35
35
|
}
|
|
36
36
|
]
|
package/README.md
CHANGED
|
@@ -214,9 +214,11 @@ 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
|
|
221
|
+
djournal pull
|
|
220
222
|
djournal sync
|
|
221
223
|
djournal upgrade
|
|
222
224
|
djournal uninstall
|
|
@@ -230,10 +232,17 @@ Existing `AGENTS.md` and `CLAUDE.md` files are never replaced. djournal adds an
|
|
|
230
232
|
owned block, updates only that block, and removes only that block during
|
|
231
233
|
uninstall; surrounding project instructions remain untouched.
|
|
232
234
|
|
|
233
|
-
`share` marks the active work item in the global sharing index. `
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
235
|
+
`share` marks the active work item in the global sharing index. `pull` hydrates
|
|
236
|
+
the canonical global store from the Git-backed projection with conservative
|
|
237
|
+
three-way reconciliation. `sync` pulls first, then projects and publishes
|
|
238
|
+
shared work. Colocated mode leaves product-repository Git operations to the
|
|
239
|
+
user; standalone mode performs the configured Git pull and push.
|
|
240
|
+
|
|
241
|
+
At session start, djournal reads a user-local npm release cache and reports a
|
|
242
|
+
known CLI or project-asset update every session until it is installed. Stale
|
|
243
|
+
release data is refreshed in the background at most once every 24 hours. Run
|
|
244
|
+
`djournal update check` for an immediate check, or disable passive checks with
|
|
245
|
+
`djournal config updates.enabled false` or `NO_UPDATE_NOTIFIER=1`.
|
|
237
246
|
|
|
238
247
|
## Status
|
|
239
248
|
|
|
@@ -256,6 +265,7 @@ djournal is licensed under the [Apache License 2.0](LICENSE).
|
|
|
256
265
|
|
|
257
266
|
- [Installation and repository layouts](docs/installation.md)
|
|
258
267
|
- [Remote Git sync setup](docs/remote-sync.md)
|
|
268
|
+
- [Read-only team journal access](docs/read-only-team-journal.md)
|
|
259
269
|
- [Architecture and data model](docs/architecture.md)
|
|
260
270
|
- [Visibility and sharing](docs/visibility-and-sharing.md)
|
|
261
271
|
- [Djournal in practice](docs/djournal-in-practice.md)
|
package/bin/journal.js
CHANGED
|
@@ -3,11 +3,14 @@
|
|
|
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,
|
|
8
10
|
configure,
|
|
9
11
|
doctor,
|
|
10
12
|
install,
|
|
13
|
+
pull,
|
|
11
14
|
share,
|
|
12
15
|
sync,
|
|
13
16
|
status,
|
|
@@ -26,7 +29,9 @@ function usage() {
|
|
|
26
29
|
journal doctor [--target DIR] [--json]
|
|
27
30
|
journal config [--target DIR] [KEY [VALUE]] [--dry-run] [--json]
|
|
28
31
|
journal share [--target DIR] [--work SLUG | --all] [--dry-run] [--json]
|
|
32
|
+
journal pull [--target DIR] [--work SLUG] [--dry-run] [--json]
|
|
29
33
|
journal sync [--target DIR] [--work SLUG] [--dry-run] [--json]
|
|
34
|
+
journal update check [--target DIR] [--json]
|
|
30
35
|
|
|
31
36
|
Options:
|
|
32
37
|
--dry-run Show the planned operation without writing
|
|
@@ -42,10 +47,14 @@ Options:
|
|
|
42
47
|
function parseArgs(argv) {
|
|
43
48
|
const args = [...argv];
|
|
44
49
|
const command = args.shift();
|
|
45
|
-
if (!command || !["install", "upgrade", "uninstall", "status", "doctor", "config", "share", "sync"].includes(command)) {
|
|
50
|
+
if (!command || !["install", "upgrade", "uninstall", "status", "doctor", "config", "share", "pull", "sync", "update"].includes(command)) {
|
|
46
51
|
throw new InstallerError(usage(), "USAGE");
|
|
47
52
|
}
|
|
48
53
|
const options = { command, harnesses: [] };
|
|
54
|
+
if (command === "update") {
|
|
55
|
+
options.subcommand = args.shift();
|
|
56
|
+
if (options.subcommand !== "check") throw new InstallerError("update requires the check subcommand", "USAGE");
|
|
57
|
+
}
|
|
49
58
|
while (args.length) {
|
|
50
59
|
const arg = args.shift();
|
|
51
60
|
if (arg === "--target") {
|
|
@@ -66,6 +75,8 @@ function parseArgs(argv) {
|
|
|
66
75
|
else if (arg === "--auto") options.auto = true;
|
|
67
76
|
else if (arg === "--yes") options.yes = true;
|
|
68
77
|
else if (arg === "--json") options.json = true;
|
|
78
|
+
else if (arg === "--passive" && command === "update") options.passive = true;
|
|
79
|
+
else if (arg === "--refresh-cache" && command === "update") options.refreshCache = true;
|
|
69
80
|
else if (arg === "--help" || arg === "-h") throw new InstallerError(usage(), "HELP");
|
|
70
81
|
else if (command === "config" && !options.key) options.key = arg;
|
|
71
82
|
else if (command === "config" && typeof options.value === "undefined") options.value = arg;
|
|
@@ -90,12 +101,27 @@ function print(value, json) {
|
|
|
90
101
|
process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
|
|
91
102
|
return;
|
|
92
103
|
}
|
|
104
|
+
if (value.action === "update-check") {
|
|
105
|
+
process.stdout.write(`cli version: ${value.cliVersion || "unknown"}\n`);
|
|
106
|
+
if (value.projectVersion) process.stdout.write(`project assets: ${value.projectVersion}\n`);
|
|
107
|
+
process.stdout.write(`latest version: ${value.latestVersion || "unknown"}\n`);
|
|
108
|
+
if (value.updateAvailable) process.stdout.write(`update available: ${value.cliVersion} -> ${value.latestVersion}\n`);
|
|
109
|
+
else if (value.latestVersion) process.stdout.write("djournal CLI is up to date\n");
|
|
110
|
+
if (value.projectUpdateAvailable) process.stdout.write(`project upgrade available: ${value.projectVersion} -> ${value.cliVersion}\n`);
|
|
111
|
+
if (value.checkedAt) process.stdout.write(`checked: ${value.checkedAt}\n`);
|
|
112
|
+
return;
|
|
113
|
+
}
|
|
93
114
|
if (value.action) process.stdout.write(`${value.action}: ${value.target}\n`);
|
|
94
115
|
else if (typeof value.installed === "boolean") process.stdout.write(value.installed ? `installed: ${value.target}\n` : `not installed: ${value.target}\n`);
|
|
95
116
|
else process.stdout.write(`${value.ok ? "ok" : "failed"}: ${value.target}\n`);
|
|
96
117
|
if (value.harnesses) process.stdout.write(`harnesses: ${value.harnesses.join(", ") || "instructions-only"}\n`);
|
|
97
118
|
if (value.key) process.stdout.write(`${value.key}: ${JSON.stringify(value.value)}\n`);
|
|
98
119
|
else if (value.config) process.stdout.write(`${JSON.stringify(value.config, null, 2)}\n`);
|
|
120
|
+
if (value.cliVersion) process.stdout.write(`cli version: ${value.cliVersion}\n`);
|
|
121
|
+
if (value.projectVersion) process.stdout.write(`project assets: ${value.projectVersion}\n`);
|
|
122
|
+
if (value.latestVersion) process.stdout.write(`latest version: ${value.latestVersion}\n`);
|
|
123
|
+
if (value.updateAvailable) process.stdout.write("update available: yes\n");
|
|
124
|
+
if (value.projectUpdateAvailable) process.stdout.write("project upgrade available: yes\n");
|
|
99
125
|
if (value.workItems) {
|
|
100
126
|
for (const item of value.workItems) {
|
|
101
127
|
process.stdout.write(`${item.changed ? "shared" : "unchanged"} ${item.work}\n`);
|
|
@@ -122,6 +148,28 @@ function exitCodeFor(code) {
|
|
|
122
148
|
return 1;
|
|
123
149
|
}
|
|
124
150
|
|
|
151
|
+
function launchUpdateRefresh(options, runner = spawn) {
|
|
152
|
+
try {
|
|
153
|
+
const child = runner(process.execPath, [
|
|
154
|
+
__filename,
|
|
155
|
+
"update",
|
|
156
|
+
"check",
|
|
157
|
+
"--refresh-cache",
|
|
158
|
+
"--json",
|
|
159
|
+
"--target",
|
|
160
|
+
options.target,
|
|
161
|
+
], {
|
|
162
|
+
detached: true,
|
|
163
|
+
stdio: "ignore",
|
|
164
|
+
env: { ...process.env, DJOURNAL_UPDATE_WORKER: "1" },
|
|
165
|
+
});
|
|
166
|
+
child.unref();
|
|
167
|
+
return true;
|
|
168
|
+
} catch {
|
|
169
|
+
return false;
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
|
|
125
173
|
async function main() {
|
|
126
174
|
try {
|
|
127
175
|
const options = parseArgs(process.argv.slice(2));
|
|
@@ -132,7 +180,12 @@ async function main() {
|
|
|
132
180
|
else if (options.command === "status") result = status(options);
|
|
133
181
|
else if (options.command === "config") result = configure(options);
|
|
134
182
|
else if (options.command === "share") result = share(options);
|
|
183
|
+
else if (options.command === "pull") result = pull(options);
|
|
135
184
|
else if (options.command === "sync") result = sync(options);
|
|
185
|
+
else if (options.command === "update") {
|
|
186
|
+
result = await checkUpdates(options);
|
|
187
|
+
if (result.refreshNeeded) result.backgroundRefreshStarted = launchUpdateRefresh(options);
|
|
188
|
+
}
|
|
136
189
|
else result = doctor(options);
|
|
137
190
|
print(result, options.json);
|
|
138
191
|
if (result.ok === false || result.installed === false || result.clean === false || result.conflicts?.length) process.exitCode = 2;
|
|
@@ -147,4 +200,4 @@ async function main() {
|
|
|
147
200
|
|
|
148
201
|
if (require.main === module) main();
|
|
149
202
|
|
|
150
|
-
module.exports = { parseArgs, print };
|
|
203
|
+
module.exports = { launchUpdateRefresh, parseArgs, print };
|
package/docs/architecture.md
CHANGED
|
@@ -158,9 +158,10 @@ questions.
|
|
|
158
158
|
work such as resume, planning, research, decision capture, documentation,
|
|
159
159
|
audit, reconciliation, and closure.
|
|
160
160
|
|
|
161
|
-
Hooks remind agents about the workflow
|
|
162
|
-
|
|
163
|
-
|
|
161
|
+
Hooks remind agents about the workflow, delegate configured synchronization
|
|
162
|
+
transport to the CLI, and validate final status markers. Hooks do not create
|
|
163
|
+
semantic journal entries. When `.djournal.json` exists, hooks read active work
|
|
164
|
+
and sync config from the global project store.
|
|
164
165
|
|
|
165
166
|
For Claude Code, install also injects a narrow permission grant into
|
|
166
167
|
`.claude/settings.json` for the exact global project store path and safe
|
|
@@ -174,6 +175,12 @@ into the shared checker. Because Pi has no blocking stop hook,
|
|
|
174
175
|
an invalid final marker causes at most one follow-up turn. Pi project trust is
|
|
175
176
|
managed by Pi, and external sandboxes must expose the global store.
|
|
176
177
|
|
|
178
|
+
Configured standalone session-start hooks invoke `djournal pull --auto` before
|
|
179
|
+
loading active work. Explicit journal-sync prompt intent invokes a manual pull.
|
|
180
|
+
Close hooks invoke `djournal sync --auto --work <slug>`, whose transport ordering
|
|
181
|
+
is pull and reconcile, project canonical work, then commit and push. Hooks never
|
|
182
|
+
implement reconciliation or write semantic entries themselves.
|
|
183
|
+
|
|
177
184
|
## Related docs
|
|
178
185
|
|
|
179
186
|
- [Djournal in practice](djournal-in-practice.md)
|
|
@@ -18,6 +18,11 @@ 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 standalone automatic sync is enabled, session startup first pulls the
|
|
22
|
+
Git-backed journal and reconciles it into canonical storage. Work initialization
|
|
23
|
+
and switching also pull before enumerating available work, so a colleague can
|
|
24
|
+
select work that was created remotely.
|
|
25
|
+
|
|
21
26
|
## Plan before risky work
|
|
22
27
|
|
|
23
28
|
Use a plan entry when the work has multiple phases, cross-component effects, or
|
|
@@ -135,6 +140,15 @@ Explicit request:
|
|
|
135
140
|
Document how journal sync works for future contributors.
|
|
136
141
|
```
|
|
137
142
|
|
|
143
|
+
To request an immediate team refresh and publication:
|
|
144
|
+
|
|
145
|
+
```text
|
|
146
|
+
Sync the journal.
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
The prompt hook pulls first, and the agent then runs the normal journal sync
|
|
150
|
+
workflow when publication is requested.
|
|
151
|
+
|
|
138
152
|
Inferred request:
|
|
139
153
|
|
|
140
154
|
```text
|
package/docs/installation.md
CHANGED
|
@@ -79,11 +79,13 @@ djournal config sync.enabled true
|
|
|
79
79
|
djournal config sync.mode colocated
|
|
80
80
|
djournal config sync.path .
|
|
81
81
|
djournal share --work 2026-07-03-01-example
|
|
82
|
+
djournal pull --work 2026-07-03-01-example
|
|
82
83
|
djournal sync --work 2026-07-03-01-example
|
|
83
84
|
```
|
|
84
85
|
|
|
85
|
-
|
|
86
|
-
|
|
86
|
+
Pull hydrates canonical storage from the current product checkout. Sync pulls
|
|
87
|
+
again, then copies the shared work item into `./.journal/work/...` so normal
|
|
88
|
+
product repository commits can carry it.
|
|
87
89
|
|
|
88
90
|
## Multi-repository setup
|
|
89
91
|
|
|
@@ -149,14 +151,57 @@ djournal install --instructions-only
|
|
|
149
151
|
```bash
|
|
150
152
|
djournal status
|
|
151
153
|
djournal doctor
|
|
154
|
+
djournal update check
|
|
152
155
|
```
|
|
153
156
|
|
|
154
|
-
`status` reports installed files
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
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.
|
|
158
202
|
|
|
159
203
|
## Related docs
|
|
160
204
|
|
|
161
205
|
- [Remote Git sync setup](remote-sync.md)
|
|
206
|
+
- [Read-only team journal access](read-only-team-journal.md)
|
|
162
207
|
- [Uninstalling and reinstalling](uninstalling.md)
|