artshelf 0.10.1 → 0.11.0

package/CHANGELOG.md

@@ -79,6 +79,48 @@
   cache, `ARTSHELF_NO_UPDATE_CHECK_TTL_MS` overrides the no-update/failed TTL
   (falling back to `ARTSHELF_UPDATE_CHECK_TTL_MS` for compatibility), and a
   non-numeric TTL value falls back to the default instead of disabling expiry.
+- Made concurrent ledger and registry writes safe: ledger mutations now take the
+  same cross-process advisory lock as the registry (extracted into a shared
+  `withPathLock` helper in `src/locks.ts`), and ledger appends and rewrites commit
+  through a unique temp file and an atomic rename, so overlapping `put`,
+  `resolve`, and cleanup runs no longer drop records or leave a partially written
+  ledger.
+- Hardened `cleanup --execute` to reject unsafe plan ids and bind the loaded plan
+  to the request before any filesystem mutation: the plan's `planId` must match
+  the requested id, its `ledgerPath` must match the executing ledger, and its
+  entries must be well-formed, so mismatched or malformed plans are refused before
+  moving files or writing a receipt — the plan-id-bound posture trash purge
+  already enforces.
+
+## [0.11.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.10.2...artshelf-v0.11.0) (2026-06-14)
+
+
+### Features
+
+* **ledger:** add cross-process advisory file lock and unique temp paths for atomic writes (NGX-428) ([0f553e4](https://github.com/calvinnwq/artshelf/commit/0f553e485737cf96390d451f4ae92f52e1abbf2a))
+
+
+### Bug Fixes
+
+* **cleanup:** reject unsafe plan-ids and mismatched plans before filesystem mutation (NGX-426) ([79debb7](https://github.com/calvinnwq/artshelf/commit/79debb7c3610984a969adea7f93b27ca08150647))
+* **ledger:** make ledger writes atomic and concurrency-safe and reject unsafe cleanup plans ([ac98c4e](https://github.com/calvinnwq/artshelf/commit/ac98c4eaf917b695e166f2ca7c40b6759d6e5f53))
+
+## [0.10.2](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.10.1...artshelf-v0.10.2) (2026-06-13)
+
+
+### Code Refactoring
+
+* **cli:** extract command dispatch and shared modules from the monolithic
+  entrypoint ([c198c19](https://github.com/calvinnwq/artshelf/commit/c198c194693e756dd02b2525e2f6abbee5741d59))
+* **cli:** separate status, doctor, review, and JSON renderers from command
+  orchestration ([4ec76b0](https://github.com/calvinnwq/artshelf/commit/4ec76b0b0e4f45562d0e98a1237602bc5d41ca67))
+* **cli:** extract update environment, package, path, and process adapter seams
+  ([4ec76b0](https://github.com/calvinnwq/artshelf/commit/4ec76b0b0e4f45562d0e98a1237602bc5d41ca67))
+* **cli:** restore real per-command modules, add the validate command module,
+  and strengthen architecture guardrails
+  ([a617ba3](https://github.com/calvinnwq/artshelf/commit/a617ba36e7de7d8a5725d1ba47eb3419ae3c6329))
+* **cli:** move help rendering out of the entrypoint and into shared help text
+  ([8e2698b](https://github.com/calvinnwq/artshelf/commit/8e2698bce1b47073d434113cbe1e8cfb32ec34e2))
 
 ## [0.10.1](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.10.0...artshelf-v0.10.1) (2026-06-12)
 

package/README.md

@@ -113,6 +113,9 @@ destructive deletion.
 - **No fresh-plan-then-execute shortcut** — review the plan, then run that plan.
 - **Trash before delete** — `cleanup=delete` stays refused; physical deletion
   needs its own reviewed trash purge. No silent deletion, ever.
+- **Durable, concurrency-safe writes** — ledger and registry mutations take a
+  cross-process lock and commit atomically, so overlapping commands never lose
+  records or leave a half-written ledger.
 - **`--json` on every command**, so agents can act on structured output.
 - **`--agent` on `review`/`status`/`doctor`**, a compact, token-efficient
   decision packet for agents, while the default render stays human-scannable.

package/SPEC.md

@@ -261,7 +261,7 @@ the next action always points at an explicit follow-up command.
 
 `review`, `status`, and `doctor` share three render modes. The default human
 render leads each ledger and summary line with a `✓`/`⚠` attention glyph; `--json`
-stays the full, backward-compatible audit report; and `--agent` emits a compact,
+stays the full, backward-compatible public audit report; and `--agent` emits a compact,
 deterministic single-line JSON decision packet for agents, taking precedence over
 `--json` when both are passed. For `review`, the packet sorts records into
 ready-for-approval, needs-review-first, and blocked groups. Because review is
@@ -423,8 +423,15 @@ artshelf cleanup --execute --plan-id <id> [--ledger <path>] --json
 
 Rules:
 
-- Requires `--plan-id`.
+- Requires `--plan-id`, and refuses an unsafe plan id (anything outside
+  `[A-Za-z0-9_-]`, such as a value containing path separators or `..`) before
+  touching the filesystem.
 - Refuses to generate a fresh live cleanup set during execute.
+- Binds the loaded plan to the request before any mutation: the plan file's
+  `planId` must match the requested id, its `ledgerPath` must match the executing
+  ledger, and its entries must be well-formed. A mismatched or malformed plan is
+  refused without moving files or writing a receipt, mirroring the live-record
+  re-checks `trash purge --execute` performs.
 - Writes a cleanup receipt and appends or refreshes an Artshelf-owned ledger record
   for that receipt with `owner=artshelf`, `kind=run-artifact`, `ttl=30d`,
   `cleanup=review`, and labels including `artshelf`, `cleanup-receipt`, and the
@@ -532,6 +539,16 @@ Default behavior:
 - Otherwise write user-global.
 - Allow `--ledger <path>` for explicit tests and unusual workflows.
 
+Write durability:
+
+- Every mutation of a ledger or the registry runs under a cross-process advisory
+  lock keyed on the target file, so overlapping `artshelf` processes serialize
+  their writes instead of racing. The lock is re-entrant within a process and
+  reclaims a stale lock left by a crashed holder.
+- Ledger writes — both single-record appends and full rewrites — land through a
+  unique temp file and an atomic rename, so an interrupted write cannot truncate
+  the ledger or lose already-recorded entries.
+
 V1 also supports a user-level registry of known ledgers:
 
 - registry: `~/.artshelf/ledgers.json`
@@ -784,6 +801,8 @@ human review.
 - CLI can find existing records by path/owner/label/status and get records by id.
 - CLI can mark records manually resolved with a required reason.
 - CLI validates ledger shape.
+- Concurrent ledger and registry writes are serialized with a cross-process lock
+  and committed atomically, so overlapping commands do not lose records.
 - CLI reports machine and registry health through `artshelf doctor`, exiting
   non-zero when the registry or a registered ledger is broken.
 - CLI reports a read-only daily dashboard through `artshelf status`, with
@@ -795,7 +814,8 @@ human review.
   entries; no-op dry-runs do not write plan files.
 - Cleanup dry-run and execute register the plan/receipt artifacts that Artshelf
   creates.
-- Cleanup execute refuses to run without a plan id.
+- Cleanup execute refuses to run without a plan id, and refuses an unsafe,
+  mismatched, or malformed plan before moving files or writing a receipt.
 - Cleanup execute writes a receipt.
 - CLI can list trashed records (single ledger or `--all`) and purge them through
   an approval-first, ledger-scoped dry-run/execute boundary that writes a purge
@@ -807,7 +827,8 @@ human review.
   JSON decision packet for agents that takes precedence over `--json`.
 - Tests cover record/list/find/get/status-filter/due/validate/resolve/registry,
   `artshelf doctor`, the `artshelf status` dashboard, `--all` review, stale-registry,
-  dry-run, global-dry-run, execute-plan, and trash list/purge behavior.
+  dry-run, global-dry-run, execute-plan, cleanup plan-id validation, concurrent
+  ledger writes, and trash list/purge behavior.
 
 ## Deferred
 

package/dist/src/adapters/process.js

@@ -0,0 +1,7 @@
+import { spawnSync } from "node:child_process";
+export function installGlobalNpmPackage(packageSpec, mode) {
+    if (mode === "pipe") {
+        return spawnSync("npm", ["install", "-g", packageSpec], { encoding: "utf8" });
+    }
+    return spawnSync("npm", ["install", "-g", packageSpec], { encoding: "utf8", stdio: "inherit" });
+}

package/dist/src/adapters/update.js

@@ -0,0 +1,143 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { latestVersionOverride, noUpdateCheckTtlMs, updateCheckTtlMs } from "../config/env.js";
+import { NO_UPDATE_CHECK_TTL_MS, UPDATE_CHECK_TTL_MS, VERSION, npmRegistryUrl } from "../config/package.js";
+import { updateCachePath } from "../config/paths.js";
+export async function getUpdateInfo(options) {
+    return createDefaultUpdateAdapter().getUpdateInfo(options);
+}
+export function createUpdateAdapter(options) {
+    async function getUpdateInfo(optionsForCheck) {
+        const latest = await getLatestVersion(optionsForCheck);
+        if (!latest)
+            return null;
+        return {
+            current: options.currentVersion,
+            latest,
+            updateAvailable: compareVersions(latest, options.currentVersion) > 0
+        };
+    }
+    async function getLatestVersion(optionsForCheck) {
+        const override = latestVersionOverride(options.env);
+        if (override)
+            return normalizeVersion(override);
+        if (!optionsForCheck.force) {
+            const cached = readUpdateCache();
+            if (cached)
+                return cached.latest;
+        }
+        const latest = await options.fetchLatestVersion(options.registryUrl);
+        writeUpdateCache(latest);
+        return latest;
+    }
+    function readUpdateCache() {
+        const cachePath = options.cachePath();
+        if (!options.fileExists(cachePath))
+            return null;
+        try {
+            const cache = JSON.parse(options.readTextFile(cachePath));
+            if (!("latest" in cache))
+                cache.latest = null;
+            if (cache.latest !== null && typeof cache.latest !== "string")
+                return null;
+            if (typeof cache.checkedAt !== "number")
+                return null;
+            const latest = cache.latest === null ? null : normalizeVersion(cache.latest);
+            const ttl = updateCacheTtlFor(latest);
+            if (ttl < 0)
+                return null;
+            if (options.now() - cache.checkedAt > ttl)
+                return null;
+            return { latest };
+        }
+        catch {
+            return null;
+        }
+    }
+    function updateCacheTtlFor(latest) {
+        if (latest && compareVersions(latest, options.currentVersion) > 0) {
+            return updateCheckTtlMs(options.env, UPDATE_CHECK_TTL_MS);
+        }
+        return noUpdateCheckTtlMs(options.env, NO_UPDATE_CHECK_TTL_MS);
+    }
+    function writeUpdateCache(latest) {
+        try {
+            const cachePath = options.cachePath();
+            const dir = dirname(cachePath);
+            if (dir) {
+                options.ensureDirectory(dir);
+                options.writeTextFile(cachePath, `${JSON.stringify({ latest, checkedAt: options.now() }, null, 2)}\n`);
+            }
+        }
+        catch {
+            // Update checks should never affect normal CLI behavior.
+        }
+    }
+    return { getUpdateInfo };
+}
+function createDefaultUpdateAdapter() {
+    const registryUrl = npmRegistryUrl();
+    return createUpdateAdapter({
+        currentVersion: VERSION,
+        registryUrl,
+        env: process.env,
+        now: () => Date.now(),
+        cachePath: () => updateCachePath(),
+        fileExists: existsSync,
+        readTextFile: (path) => readFileSync(path, "utf8"),
+        writeTextFile: writeFileSync,
+        ensureDirectory: (path) => mkdirSync(path, { recursive: true }),
+        fetchLatestVersion: (url) => fetchLatestNpmVersion(url)
+    });
+}
+async function fetchLatestNpmVersion(registryUrl) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 750);
+    try {
+        const response = await fetch(registryUrl, {
+            signal: controller.signal,
+            headers: { accept: "application/json", "user-agent": `artshelf/${VERSION}` }
+        });
+        if (!response.ok)
+            return null;
+        const body = await response.json();
+        if (!body || typeof body !== "object" || typeof body.version !== "string")
+            return null;
+        return normalizeVersion(body.version);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function normalizeVersion(version) {
+    return version.trim().replace(/^v/i, "");
+}
+function compareVersions(left, right) {
+    const a = parseVersion(left);
+    const b = parseVersion(right);
+    for (let index = 0; index < Math.max(a.numbers.length, b.numbers.length); index += 1) {
+        const diff = (a.numbers[index] ?? 0) - (b.numbers[index] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    if (a.prerelease === b.prerelease)
+        return 0;
+    if (!a.prerelease)
+        return 1;
+    if (!b.prerelease)
+        return -1;
+    return a.prerelease.localeCompare(b.prerelease);
+}
+function parseVersion(version) {
+    const [main = "", prerelease = ""] = normalizeVersion(version).split("-", 2);
+    return {
+        numbers: main.split(".").map((part) => {
+            const parsed = Number.parseInt(part, 10);
+            return Number.isFinite(parsed) ? parsed : 0;
+        }),
+        prerelease
+    };
+}