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.
@@ -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 activeWork(root) {
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
- return workBySlug(root, state.active_work_name);
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 work = activeWork(root);
197
- const suffix = work ? ` Active work: ${work.slug}.` : " No valid active work is selected.";
198
- return context(event, `Follow AGENTS.md and .agents/rules/AUTOMATION.md.${pullMessage}${suffix}`);
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 = { handle, parseFrontmatter, requestsJournalSync, resolveClosedEntry, shouldAutoSync };
374
+ module.exports = {
375
+ handle,
376
+ parseFrontmatter,
377
+ requestsJournalSync,
378
+ resolveClosedEntry,
379
+ runUpdateCheck,
380
+ shouldAutoSync,
381
+ shouldCheckUpdates,
382
+ updateNotice,
383
+ };
@@ -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 `<journal-root>/state.json`, but
75
- other work items may remain in `active` status. Active selection and lifecycle
76
- status are different concepts.
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
 
@@ -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 status,
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. Preserve
56
- the exact state shape from `STATE.md` and make the update safely.
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 `<journal-root>/state.json`,
19
- then the active `work.md`.
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 not Git branches.
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 using the
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 };
@@ -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 active work
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
@@ -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 and cleanliness. `doctor` checks the local
157
- environment and harness configuration. For Pi it reports extension presence
158
- and reminds you that project trust is required; it does not inspect or change
159
- Pi's private trust state.
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)
@@ -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)
@@ -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
- if (!manifest) return { installed: false, target };
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 { installed: true, target, toolVersion: manifest.toolVersion, harnesses: manifest.harnesses, files, clean: files.every((file) => file.status === "clean") };
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.6.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
  }