@devwithdavid/ledger 0.1.4 → 0.1.5

package/LEDGER.md

@@ -170,6 +170,15 @@ repeating the same failure under every idle agent. `--json` includes the
 same data as an `idle` array (`agent`, `pane_tail`, `pane_read_error`) plus
 top-level `idle_pane_read_note` for the whole-socket case.
 
+`catchup` also checks (item 42) whether a newer `@devwithdavid/ledger` npm
+version exists — a plain-text notice after the normal output in
+human-readable mode, or the top-level `update_available` JSON key
+(`{current, latest}` or `null`) in `--json` mode, so `--json` output stays
+valid JSON either way. The check is cached for 6h in
+`$LEDGER_HOME/update-check.json` and degrades silently on any failure
+(offline, timeout, malformed response) — it never delays or breaks
+`catchup`. Run `ledger update` to actually upgrade.
+
 ### First-clerk claiming
 
 ```sh
@@ -181,6 +190,25 @@ ledger clerk status
 `--force` is passed. Do this once per new/resumed clerk session before
 dispatching anything.
 
+`claim` runs the same cached update-availability check as `catchup` (item
+42); since `claim` has no `--json` mode, a matching newer version prints
+as a plain-text line after the claim's JSON output.
+
+### Updating ledger
+
+```sh
+ledger update
+```
+
+Checks npm for the latest `@devwithdavid/ledger` version (always fresh —
+never the 6h cache `claim`/`catchup` use, since this is an explicit user
+action). Already up to date: says so and exits. Newer version available:
+runs `npm install -g @devwithdavid/ledger@latest` immediately (no
+confirmation prompt) and reports old → new version. Unlike the passive
+notice above, failures here (registry unreachable, npm install error) are
+never swallowed — this is a foreground action, so they're reported
+plainly and the command exits non-zero.
+
 ### Registering a project
 
 ```sh

package/README.md

@@ -68,6 +68,13 @@ herdr always runs whatever's currently in the installed package's `dist/`,
 so `npm update -g @devwithdavid/ledger` picks up new releases (including
 watcher changes) on the next event.
 
+**Or just run `ledger update`** — checks npm for a newer version and, if
+one exists, runs the install for you (equivalent to `npm install -g
+@devwithdavid/ledger@latest`). `ledger claim` and `ledger catchup` also
+print a one-line notice when a newer version is available (checked at
+most every 6 hours, silently skipped if npm is unreachable), so you don't
+have to think to check.
+
 ## Starting a clerk session
 
 You don't run `ledger` commands yourself day to day — you talk to **the

package/dist/cli/commands/agents.js

@@ -426,15 +426,41 @@ function deriveLabel(task) {
     const truncated = raw.slice(0, 32).replace(/-+$/g, "");
     return truncated || "task";
 }
+/**
+ * True only if `workspaceId` still exists AND is still the workspace
+ * belonging to `project` — not just that the id resolves to *some*
+ * workspace. Workspace ids are recycled by herdr (e.g. after a herdr
+ * restart resets its allocation), so a stale stored id can collide with an
+ * unrelated, freshly-created workspace that happens to reuse the same id.
+ * Workspaces are created with `label: project.name` (see openDispatchPane
+ * below), so comparing the label is how identity — not just existence — is
+ * verified.
+ */
+function workspaceBelongsToProject(workspaceId, project) {
+    try {
+        // quiet: this is a routine "is it still ours?" check, run on every
+        // dispatch — a missing/stale workspace is an expected, handled outcome,
+        // not noise worth printing to the terminal every time.
+        const workspace = herdr.getWorkspace(workspaceId, { quiet: true });
+        return workspace.label === project.name;
+    }
+    catch (err) {
+        if (err instanceof herdr.HerdrError && err.code === "workspace_not_found") {
+            return false;
+        }
+        throw err;
+    }
+}
 /**
  * One herdr workspace per project, not per dispatch (per the user — see
  * DECISIONS.md): reuses the project's existing workspace as a new tab when
  * one is already live, or creates it (and records it via the caller) when
  * this is the project's first dispatch, or its previous workspace was
- * closed (e.g. by the user) since the last dispatch.
+ * closed (e.g. by the user) or recycled to a different project since the
+ * last dispatch.
  */
 function openDispatchPane(project, cwd, label) {
-    if (project.herdr_workspace && herdr.workspaceExists(project.herdr_workspace)) {
+    if (project.herdr_workspace && workspaceBelongsToProject(project.herdr_workspace, project)) {
         const tab = herdr.createTab({
             workspace: project.herdr_workspace,
             cwd,

package/dist/cli/commands/catchup.js

@@ -1,5 +1,7 @@
 import { getDb } from "../../db/client.js";
 import { HerdrError, readPane } from "../../lib/herdr.js";
+import { packageVersion } from "../../lib/package-info.js";
+import { checkForUpdate, formatUpdateNotice } from "../../lib/update-check.js";
 import { printJson } from "../format.js";
 import { getProjectByName } from "./projects.js";
 /** Default tail length for each idle agent's pane read (A8 liveness triage). */
@@ -73,7 +75,7 @@ export function registerCatchupCommand(program) {
         .option("--project <name>", "scope roadmap (and optionally agents) to one project")
         .option("--idle-pane-lines <n>", "lines of pane tail to show per idle agent (A8 liveness triage); 0 disables pane reads", parseIdlePaneLinesOpt, IDLE_PANE_TAIL_DEFAULT_LINES)
         .option("--json", "output as JSON (default: human-readable)")
-        .action((opts) => {
+        .action(async (opts) => {
         const db = getDb();
         const project = opts.project ? getProjectByName(opts.project) : undefined;
         const firstClerk = db
@@ -135,7 +137,20 @@ export function registerCatchupCommand(program) {
         if (firstClerk) {
             db.prepare("UPDATE first_clerk SET last_seen = datetime('now') WHERE id = 1").run();
         }
-        const summary = { since, blocked, idle, idle_pane_read_note: idlePaneGlobalNote, events, roadmap };
+        // Item 42: cached (6h), silent-on-failure update-availability check.
+        // Added as an explicit top-level key (`update_available`, null when
+        // there's nothing to report) rather than mixed into plain text, so
+        // --json stays valid JSON in both cases.
+        const updateAvailable = await checkForUpdate(packageVersion());
+        const summary = {
+            since,
+            blocked,
+            idle,
+            idle_pane_read_note: idlePaneGlobalNote,
+            events,
+            roadmap,
+            update_available: updateAvailable,
+        };
         if (opts.json) {
             printJson(summary);
             return;
@@ -170,5 +185,7 @@ export function registerCatchupCommand(program) {
             const indent = r.parent_id ? "    " : "  ";
             console.log(`${indent}#${r.id} [${r.status}] ${r.title}`);
         }
+        if (updateAvailable)
+            console.log(`\n${formatUpdateNotice(updateAvailable)}`);
     });
 }

package/dist/cli/commands/clerk.js

@@ -1,5 +1,7 @@
 import { getDb, suppressNextClerkHeartbeat } from "../../db/client.js";
 import * as herdr from "../../lib/herdr.js";
+import { packageVersion } from "../../lib/package-info.js";
+import { checkForUpdate, formatUpdateNotice } from "../../lib/update-check.js";
 import { printJson } from "../format.js";
 const STALE_AFTER_HOURS = 12;
 export function registerClerkCommands(program) {
@@ -11,7 +13,7 @@ export function registerClerkCommands(program) {
         .requiredOption("--session-id <id>", "this clerk session's id")
         .requiredOption("--herdr-pane <id>", "this clerk's own herdr pane id")
         .option("--force", "claim even if the existing claim is not stale")
-        .action((opts) => {
+        .action(async (opts) => {
         const db = getDb();
         const existing = db
             .prepare("SELECT * FROM first_clerk WHERE id = 1")
@@ -38,6 +40,12 @@ export function registerClerkCommands(program) {
         // The claim is durable now; the rename below is cosmetic only.
         renameClaimantWorkspace(opts.herdrPane);
         printJson(row);
+        // Item 42: cached (6h), silent-on-failure update-availability notice.
+        // `claim` has no --json mode, so a plain-text line after the JSON
+        // output is fine per the spec.
+        const update = await checkForUpdate(packageVersion());
+        if (update)
+            console.log(formatUpdateNotice(update));
     });
     clerk
         .command("status")

package/dist/cli/commands/update.js

@@ -0,0 +1,43 @@
+import { spawnSync } from "node:child_process";
+import { packageVersion, PACKAGE_NAME } from "../../lib/package-info.js";
+import { fetchLatestVersionOrThrow, isNewerVersion } from "../../lib/update-check.js";
+/**
+ * `ledger update` (item 42): an explicit, foreground user action, so unlike
+ * the passive claim/catchup notice this always checks fresh (never the 6h
+ * cache) and never degrades silently — every failure (the version check
+ * itself, or the npm install) is reported plainly and exits non-zero.
+ * No confirmation prompt: per the spec, running it at all is the user's
+ * confirmation.
+ */
+export function registerUpdateCommand(program) {
+    program
+        .command("update")
+        .description(`check for and install the latest ${PACKAGE_NAME} from npm`)
+        .action(async () => {
+        const current = packageVersion();
+        let latest;
+        try {
+            latest = await fetchLatestVersionOrThrow();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`couldn't check npm for the latest version: ${msg}`);
+        }
+        if (!isNewerVersion(latest, current)) {
+            console.log(`Already up to date (${current}).`);
+            return;
+        }
+        console.log(`Updating ${PACKAGE_NAME}: ${current} -> ${latest} ...`);
+        const res = spawnSync("npm", ["install", "-g", `${PACKAGE_NAME}@latest`], {
+            encoding: "utf8",
+            stdio: "inherit",
+        });
+        if (res.error) {
+            throw new Error(`npm install failed: ${res.error.message}`);
+        }
+        if (res.status !== 0) {
+            throw new Error(`npm install exited with code ${res.status}`);
+        }
+        console.log(`Updated ${PACKAGE_NAME}: ${current} -> ${latest}.`);
+    });
+}

package/dist/cli/index.js

@@ -1,9 +1,6 @@
 #!/usr/bin/env node
 // Must come first — see the comment in suppress-experimental-warnings.ts.
 import "./suppress-experimental-warnings.js";
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { registerAgentCommands } from "./commands/agents.js";
 import { registerCatchupCommand } from "./commands/catchup.js";
@@ -13,29 +10,9 @@ import { registerEventCommands } from "./commands/events.js";
 import { registerInitCommand } from "./commands/init.js";
 import { registerProjectCommands } from "./commands/projects.js";
 import { registerRoadmapCommands } from "./commands/roadmap.js";
+import { registerUpdateCommand } from "./commands/update.js";
 import { touchClerkHeartbeat } from "../db/client.js";
-// The version is derived from the package's own package.json at runtime —
-// package.json is the ONLY source of it. This entry compiles to
-// dist/cli/index.js, two levels below the package root, so resolve the
-// file relative to *this running code's own location* rather than the cwd
-// (same approach as docs.ts): that works from any invocation directory, in
-// a dev checkout, and in an npm install (the npm tarball carries
-// package.json at its root — verified in the 0.1.2 tarball). Publishing
-// bumps package.json, and since this reads package.json, the two can never
-// desync — a literal here is a second copy and is forbidden.
-// Graceful degradation: if the file can't be read or parsed (a corrupt
-// install), report "unknown" instead of throwing — a version query must
-// never crash the CLI (item 30, DECISIONS.md).
-function packageVersion() {
-    const pkgJsonPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
-    try {
-        const parsed = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
-        return parsed.version ?? "unknown";
-    }
-    catch {
-        return "unknown";
-    }
-}
+import { packageVersion } from "../lib/package-info.js";
 const program = new Command();
 program
     .name("ledger")
@@ -50,6 +27,7 @@ registerClerkCommands(program);
 registerCatchupCommand(program);
 registerDocsCommand(program);
 registerInitCommand(program);
+registerUpdateCommand(program);
 program.exitOverride();
 try {
     await program.parseAsync(process.argv);

package/dist/db/migrations/0002_project_herdr_workspace.js

@@ -7,7 +7,8 @@ export const migration0002ProjectHerdrWorkspace = {
     -- the id here; every later dispatch to the same project reuses it,
     -- adding a new tab rather than a new workspace. NULL until a first
     -- dispatch happens, and re-nulled/replaced if that workspace is found
-    -- closed (see src/lib/herdr.ts workspaceExists).
+    -- closed or recycled to a different project (see src/lib/herdr.ts
+    -- getWorkspace and openDispatchPane's use of it).
     ALTER TABLE projects ADD COLUMN herdr_workspace TEXT;
   `,
 };

package/dist/lib/herdr.js

@@ -105,10 +105,9 @@ export function closeWorkspace(workspaceId) {
 /**
  * Fetches a workspace's info (including its label). Throws HerdrError
  * (e.g. `workspace_not_found`) when the id doesn't exist. Pass `quiet`
- * when a missing workspace is an expected, handled outcome (same rationale
- * as `workspaceExists`): it suppresses herdr's raw error envelope being
- * echoed to the terminal, while `throwHerdrFailure` still parses it from
- * the piped stderr.
+ * when a missing workspace is an expected, handled outcome: it suppresses
+ * herdr's raw error envelope being echoed to the terminal, while
+ * `throwHerdrFailure` still parses it from the piped stderr.
  */
 export function getWorkspace(workspaceId, opts) {
     const result = runHerdr(["workspace", "get", workspaceId], opts);
@@ -117,22 +116,6 @@ export function getWorkspace(workspaceId, opts) {
 export function renameWorkspace(workspaceId, label) {
     runHerdr(["workspace", "rename", workspaceId, label]);
 }
-/** True if `workspaceId` still exists (wasn't closed, e.g. by the user). */
-export function workspaceExists(workspaceId) {
-    try {
-        // quiet: this is a routine "is it still there?" check, run on every
-        // dispatch — a missing workspace is an expected, handled outcome, not
-        // noise worth printing to the terminal every time.
-        runHerdr(["workspace", "get", workspaceId], { quiet: true });
-        return true;
-    }
-    catch (err) {
-        if (err instanceof HerdrError && err.code === "workspace_not_found") {
-            return false;
-        }
-        throw err;
-    }
-}
 /** Adds a new tab (with its own root pane) to an existing workspace at `cwd`. */
 export function createTab(opts) {
     const args = [

package/dist/lib/package-info.js

@@ -0,0 +1,27 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// The npm package name this CLI is published as — also the identity used
+// to query the registry for the latest published version (item 42).
+export const PACKAGE_NAME = "@devwithdavid/ledger";
+// This file compiles to dist/lib/package-info.js, two levels below the
+// package root — resolve package.json relative to *this running code's own
+// location* rather than the cwd (same approach as docs.ts/init.ts), so it
+// works from any invocation directory, in a dev checkout, and in an npm
+// install (the npm tarball carries package.json at its root).
+const PACKAGE_JSON_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+/**
+ * The running CLI's own version, read from package.json at runtime —
+ * package.json is the ONLY source of it (item 30, DECISIONS.md). Graceful
+ * degradation: an unreadable/unparseable package.json reports "unknown"
+ * instead of throwing — a version query must never crash the CLI.
+ */
+export function packageVersion() {
+    try {
+        const parsed = JSON.parse(readFileSync(PACKAGE_JSON_PATH, "utf8"));
+        return parsed.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}

package/dist/lib/update-check.js

@@ -0,0 +1,128 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ledgerHome } from "../db/client.js";
+import { PACKAGE_NAME } from "./package-info.js";
+const CACHE_TTL_MS = 6 * 60 * 60 * 1000; // item 42, user-specified
+const REGISTRY_TIMEOUT_MS = 1500; // "short timeout (~1-2s)", item 42
+function cachePath() {
+    return join(ledgerHome(), "update-check.json");
+}
+function isUpdateCache(value) {
+    const v = value;
+    return (typeof v === "object" &&
+        v !== null &&
+        typeof v.checkedAt === "string" &&
+        typeof v.latestVersion === "string");
+}
+/** Per-machine cache under $LEDGER_HOME — deliberately not ledger.db (item 42: this is local cache state, not shared ledger state). */
+function readCache() {
+    try {
+        const parsed = JSON.parse(readFileSync(cachePath(), "utf8"));
+        return isUpdateCache(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(cache) {
+    try {
+        writeFileSync(cachePath(), JSON.stringify(cache), "utf8");
+    }
+    catch {
+        // Best-effort: a failed cache write must never surface — the notice
+        // check degrades silently on any failure (item 42).
+    }
+}
+function isFresh(cache) {
+    const age = Date.now() - new Date(cache.checkedAt).getTime();
+    return age >= 0 && age < CACHE_TTL_MS;
+}
+/**
+ * Queries the npm registry directly (not the `npm` CLI — no dependency on
+ * it being installed beyond what's needed to actually run the update) for
+ * the latest published version. Throws with a descriptive message on any
+ * failure — offline, timeout, non-2xx, malformed body; callers choose
+ * whether that should be silent (the passive notice, via
+ * `fetchLatestVersion` below) or surfaced (`ledger update`, via
+ * `fetchLatestVersionOrThrow`).
+ */
+async function fetchLatestVersionInternal() {
+    const res = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, {
+        signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+        throw new Error(`npm registry returned HTTP ${res.status} for ${PACKAGE_NAME}`);
+    }
+    const body = await res.json();
+    const version = body?.version;
+    if (typeof version !== "string") {
+        throw new Error("npm registry response had no version field");
+    }
+    return version;
+}
+/**
+ * Silent variant for the passive claim/catchup notice: any failure —
+ * offline, timeout, non-2xx, malformed body — must degrade to "no notice
+ * this time", never throw (item 42).
+ */
+async function fetchLatestVersion() {
+    try {
+        return await fetchLatestVersionInternal();
+    }
+    catch {
+        return null;
+    }
+}
+/** Parses "x.y.z" into a 3-tuple; a missing/non-numeric part reads as 0. */
+function parseVersion(v) {
+    const parts = v.split(".").map((p) => Number.parseInt(p, 10));
+    return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0].map((n) => (Number.isNaN(n) ? 0 : n));
+}
+/** True when `a` is a properly-newer semver than `b` (not string comparison — "0.2.0" > "0.10.0" would be wrong as strings). */
+export function isNewerVersion(a, b) {
+    const [aMaj, aMin, aPatch] = parseVersion(a);
+    const [bMaj, bMin, bPatch] = parseVersion(b);
+    if (aMaj !== bMaj)
+        return aMaj > bMaj;
+    if (aMin !== bMin)
+        return aMin > bMin;
+    return aPatch > bPatch;
+}
+/**
+ * Cached (6h TTL) check for a newer npm version than the one running.
+ * Returns null whenever no *newer* version is known to exist — the
+ * running version is already current, the registry lookup failed, or
+ * "unknown" (package.json unreadable) is running. Never throws (item 42:
+ * this backs the passive claim/catchup notice, which must degrade
+ * silently on any failure).
+ */
+export async function checkForUpdate(currentVersion) {
+    if (currentVersion === "unknown")
+        return null;
+    const cached = readCache();
+    let latest;
+    if (cached && isFresh(cached)) {
+        latest = cached.latestVersion;
+    }
+    else {
+        latest = await fetchLatestVersion();
+        if (latest)
+            writeCache({ checkedAt: new Date().toISOString(), latestVersion: latest });
+    }
+    if (!latest || !isNewerVersion(latest, currentVersion))
+        return null;
+    return { current: currentVersion, latest };
+}
+/**
+ * Always queries the registry fresh, bypassing the cache — for `ledger
+ * update`, an explicit user action where a stale cached answer would be
+ * wrong (item 42: "fresh check is fine here"). Throws (rather than
+ * degrading to null) since this is a foreground, user-invoked action:
+ * failures here must be visible, unlike the passive notice (item 42).
+ */
+export async function fetchLatestVersionOrThrow() {
+    return fetchLatestVersionInternal();
+}
+export function formatUpdateNotice(info) {
+    return `A new version of ledger is available: ${info.current} -> ${info.latest}. Run \`ledger update\` to upgrade.`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devwithdavid/ledger",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Personal agent-orchestration ledger: SQLite state store, CLI, and herdr watcher plugin.",
   "license": "MIT",
   "repository": "https://yggdrasil.thekartiks.com/chewbakartik/ledger.git",