artshelf 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -52,6 +52,22 @@
 - Tightened the portable agent skill description so the completion-gate trigger
   is visible before final responses, status updates, handoffs, and done reports.
 
+## [0.5.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.4.1...artshelf-v0.5.0) (2026-06-05)
+
+
+### Features
+
+* default storage to .artshelf paths ([95ef94e](https://github.com/calvinnwq/artshelf/commit/95ef94edef5862c45e5526a27c4adf0bf40306ca))
+* default storage to .artshelf paths ([0da2cda](https://github.com/calvinnwq/artshelf/commit/0da2cda19ff56f78f203840ed71c2379f533750b))
+
+## [0.4.1](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.4.0...artshelf-v0.4.1) (2026-06-05)
+
+
+### Bug Fixes
+
+* read CLI version from package metadata ([dafffe9](https://github.com/calvinnwq/artshelf/commit/dafffe9c6d1f1d4aba0062ae64b15f8a919b5b62))
+* read CLI version from package metadata ([72dcc9d](https://github.com/calvinnwq/artshelf/commit/72dcc9d03d34f3c688a05a1d767931d82587d88a))
+
 ## [0.4.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.3.0...artshelf-v0.4.0) (2026-06-05)
 
 

package/README.md

@@ -116,8 +116,8 @@ This adds a separate approval boundary between quarantine and destructive deleti
 
 ## Explicit Ledgers
 
-By default, Artshelf writes repo-local `.shelf/ledger.jsonl` inside a git repo and
-`~/.shelf/ledger.jsonl` outside one. Use `--ledger <path>` and an isolated
+By default, Artshelf writes repo-local `.artshelf/ledger.jsonl` inside a git repo and
+`~/.artshelf/ledger.jsonl` outside one. Use `--ledger <path>` and an isolated
 `--registry <path>` for tests, demos, and unusual workflows:
 
 ```bash
@@ -126,16 +126,21 @@ artshelf list --ledger /tmp/artshelf-ledger.jsonl
 ```
 
 Artshelf also keeps a small global registry of known ledgers at
-`~/.shelf/ledgers.json`. Override it with `--registry <path>` or
+`~/.artshelf/ledgers.json`. Override it with `--registry <path>` or
 `ARTSHELF_REGISTRY`; renamed installs still honor legacy `SHELF_REGISTRY` when
 `ARTSHELF_REGISTRY` is unset. `put` registers its ledger automatically, and you
 can register an existing ledger explicitly:
 
 ```bash
 artshelf ledgers list
-artshelf ledgers add --ledger /path/to/repo/.shelf/ledger.jsonl --name my-repo
+artshelf ledgers add --ledger /path/to/repo/.artshelf/ledger.jsonl --name my-repo
 ```
 
+Renamed installs before `0.5.0` used `.shelf` storage paths. Migrate by copying
+each ledger directory to `.artshelf`, rewriting registry paths to the copied
+ledgers, validating with `artshelf ledgers list --json`, and keeping the old
+`.shelf` directories until rollback is no longer needed.
+
 `artshelf ledgers list` validates each registered ledger by default — reporting
 ok/missing/invalid status with entry counts, and exiting non-zero when the
 registry or any ledger is broken — so it doubles as a stale-entry check. Add

package/SPEC.md

@@ -428,8 +428,8 @@ Rules:
 
 V1 supports two scopes:
 
-- repo-local: `.shelf/ledger.jsonl`
-- user-global: `~/.shelf/ledger.jsonl`
+- repo-local: `.artshelf/ledger.jsonl`
+- user-global: `~/.artshelf/ledger.jsonl`
 
 Default behavior:
 
@@ -439,10 +439,14 @@ Default behavior:
 
 V1 also supports a user-level registry of known ledgers:
 
-- registry: `~/.shelf/ledgers.json`
+- registry: `~/.artshelf/ledgers.json`
 - `--registry <path>` overrides the registry path. Without it,
   `ARTSHELF_REGISTRY` is read first, then legacy `SHELF_REGISTRY`, then the
   default registry path.
+- Legacy `.shelf` ledgers are not deleted or moved automatically. Migration is
+  copy-first: copy ledger directories to `.artshelf`, rewrite registry entries,
+  validate the new registry, and retain the old `.shelf` directories for
+  rollback until the new paths are proven quiet.
 - Retention and due calculations use wall-clock time by default. `ARTSHELF_NOW`
   overrides it for tests and controlled runs; legacy `SHELF_NOW` is read only
   when `ARTSHELF_NOW` is unset.
@@ -462,7 +466,7 @@ V1 also supports a user-level registry of known ledgers:
   "ledgers": [
     {
       "name": "my-repo",
-      "path": "/absolute/path/to/repo/.shelf/ledger.jsonl",
+      "path": "/absolute/path/to/repo/.artshelf/ledger.jsonl",
       "scope": "repo",
       "createdAt": "2026-06-01T05:42:00Z",
       "updatedAt": "2026-06-01T05:42:00Z"
@@ -506,9 +510,9 @@ Handled records may include cleanup outcome fields:
 ```json
 {
   "cleanupPlanId": "plan_20260601_154200_cd34",
-  "receiptPath": "/absolute/path/.shelf/receipts/plan_20260601_154200_cd34.json",
+  "receiptPath": "/absolute/path/.artshelf/receipts/plan_20260601_154200_cd34.json",
   "cleanedAt": "2026-06-01T05:45:00Z",
-  "targetPath": "/absolute/path/.shelf/trash/plan_20260601_154200_cd34/shf_20260601_154200_ab12-artifact",
+  "targetPath": "/absolute/path/.artshelf/trash/plan_20260601_154200_cd34/shf_20260601_154200_ab12-artifact",
   "cleanupReason": "delete is disabled in v1"
 }
 ```
@@ -531,7 +535,7 @@ the purge provenance:
   "resolutionReason": "trash purge completed",
   "purgedAt": "2026-06-01T06:10:00Z",
   "purgePlanId": "purge_20260601_061000_ef56",
-  "purgeReceiptPath": "/absolute/path/.shelf/purge-receipts/purge_20260601_061000_ef56.json"
+  "purgeReceiptPath": "/absolute/path/.artshelf/purge-receipts/purge_20260601_061000_ef56.json"
 }
 ```
 

package/dist/src/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { appendPreparedRecord, createCleanupPlan, createTrashPurgePlan, dueEntries, executeCleanupPlan, executeTrashPurgePlan, filterRecordsByStatus, findRecords, getRecord, listTrashedRecords, normalizeLedgerPath, prepareRecord, previewCleanupPlan, readLedger, resolveRecord, validateLedger } from "./ledger.js";
 import { listRegisteredLedgers, normalizeRegistryPath, registerLedger } from "./registry.js";
-const VERSION = "0.3.0";
+const VERSION = readPackageVersion();
 const BOOLEAN_FLAGS = new Set(["all", "json", "manual-review", "dry-run", "execute", "help", "version", "plain"]);
 const VALUE_FLAGS = new Set([
     "cleanup",
@@ -21,6 +21,14 @@ const VALUE_FLAGS = new Set([
     "status",
     "ttl"
 ]);
+function readPackageVersion() {
+    const packageJsonPath = decodeURIComponent(new URL("../../package.json", import.meta.url).pathname);
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    if (typeof packageJson.version !== "string") {
+        throw new Error("package.json version must be a string");
+    }
+    return packageJson.version;
+}
 function main(argv) {
     try {
         const parsed = parseArgs(argv);

package/dist/src/ledger.js

@@ -18,8 +18,8 @@ const RESOLVE_STATUSES = new Set(["resolved"]);
 export function defaultLedgerPath(cwd = process.cwd()) {
     const repoRoot = findGitRoot(cwd);
     if (repoRoot)
-        return join(repoRoot, ".shelf", "ledger.jsonl");
-    return join(homedir(), ".shelf", "ledger.jsonl");
+        return join(repoRoot, ".artshelf", "ledger.jsonl");
+    return join(homedir(), ".artshelf", "ledger.jsonl");
 }
 export function normalizeLedgerPath(path) {
     return resolve(path ?? defaultLedgerPath());

package/dist/src/registry.js

@@ -3,7 +3,7 @@ import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { now, toIso } from "./time.js";
 export function defaultRegistryPath() {
-    return process.env.ARTSHELF_REGISTRY ?? process.env.SHELF_REGISTRY ?? join(homedir(), ".shelf", "ledgers.json");
+    return process.env.ARTSHELF_REGISTRY ?? process.env.SHELF_REGISTRY ?? join(homedir(), ".artshelf", "ledgers.json");
 }
 export function normalizeRegistryPath(path) {
     return resolve(path ?? defaultRegistryPath());
@@ -116,17 +116,17 @@ function normalizeName(name) {
 }
 function inferLedgerName(ledgerPath) {
     const normalized = resolve(ledgerPath);
-    if (normalized === join(homedir(), ".shelf", "ledger.jsonl"))
+    if (normalized === join(homedir(), ".artshelf", "ledger.jsonl"))
         return "global";
-    if (basename(dirname(normalized)) === ".shelf")
+    if (basename(dirname(normalized)) === ".artshelf")
         return basename(dirname(dirname(normalized))) || "repo";
     return basename(dirname(normalized)) || "ledger";
 }
 function inferLedgerScope(ledgerPath) {
     const normalized = resolve(ledgerPath);
-    if (normalized.startsWith(join(homedir(), ".shelf")))
+    if (normalized.startsWith(join(homedir(), ".artshelf")))
         return "user";
-    if (basename(dirname(normalized)) === ".shelf")
+    if (basename(dirname(normalized)) === ".artshelf")
         return "repo";
     return "other";
 }

package/docs/agent-usage.html

@@ -143,16 +143,22 @@ artshelf get &lt;id&gt; --json</code></pre>
             <section>
               <h2>Ledger Registry</h2>
               <p>
-                Artshelf keeps a user-level registry at `~/.shelf/ledgers.json` so one CLI can
+                Artshelf keeps a user-level registry at `~/.artshelf/ledgers.json` so one CLI can
                 review all known ledgers without moving project records into one global file.
                 <code>put</code> registers the ledger it writes to.
               </p>
-              <pre><code>artshelf ledgers add --ledger &lt;repo&gt;/.shelf/ledger.jsonl --name &lt;project&gt; --scope repo
+              <pre><code>artshelf ledgers add --ledger &lt;repo&gt;/.artshelf/ledger.jsonl --name &lt;project&gt; --scope repo
 artshelf ledgers list --json
 artshelf review --all --json
 artshelf status --all --json
 artshelf find --all --owner &lt;agent-or-runtime&gt; --json
 artshelf trash list --all --json</code></pre>
+              <p>
+                Renamed installs before <code>0.5.0</code> used <code>.shelf</code> paths. For migration,
+                copy the old ledger directories into <code>.artshelf</code>, rewrite registry entries,
+                validate the new registry, and keep the <code>.shelf</code> copies until rollback is no
+                longer needed.
+              </p>
               <p>
                 <code>artshelf ledgers list --json</code> validates each registered ledger and reports
                 ok/missing/invalid status with entry and warning/error counts, so agents can detect

package/docs/agent-usage.md

@@ -110,16 +110,20 @@ returns no entries, call `put` and record the new id.
 
 ## Ledger Registry
 
-Artshelf keeps a user-level registry at `~/.shelf/ledgers.json` so one CLI can
+Artshelf keeps a user-level registry at `~/.artshelf/ledgers.json` so one CLI can
 review all known ledgers without moving project records into one global file.
 `put` registers the ledger it writes to. Register existing ledgers explicitly
 when adopting Artshelf for an existing project:
 
 ```bash
-artshelf ledgers add --ledger <repo>/.shelf/ledger.jsonl --name <project> --scope repo
+artshelf ledgers add --ledger <repo>/.artshelf/ledger.jsonl --name <project> --scope repo
 artshelf ledgers list --json
 ```
 
+Renamed installs before `0.5.0` used `.shelf` paths. For migration, copy the old
+ledger directories into `.artshelf`, rewrite registry entries, validate the new
+registry, and keep the `.shelf` copies until rollback is no longer needed.
+
 `artshelf ledgers list --json` validates each registered ledger and reports
 ok/missing/invalid status with entry and warning/error counts, so agents can
 detect stale registry entries without a separate validate pass. Add `--plain`

package/docs/quickstart.html

@@ -94,7 +94,7 @@ artshelf validate --ledger /tmp/artshelf-ledger.jsonl --json
 artshelf due --ledger /tmp/artshelf-ledger.jsonl --json
 artshelf cleanup --dry-run --ledger /tmp/artshelf-ledger.jsonl --json</code></pre>
               <p>
-                Dry-run writes a plan under the ledger's `.shelf` directory only when
+                Dry-run writes a plan under the ledger's `.artshelf` directory only when
                 cleanup entries exist. If there is nothing to clean up, it reports
                 <code>not-created</code> and writes no plan file. Review any generated
                 plan id before an execute step.
@@ -119,7 +119,7 @@ artshelf cleanup --dry-run --ledger /tmp/artshelf-ledger.jsonl --json</code></pr
               <h2>4. Purge old trashed records explicitly</h2>
               <p>
                 After cleanup execution, trashed files are quarantined under the ledger's
-                <code>.shelf/trash</code> folder. Before physical deletion, run an explicit
+                <code>.artshelf/trash</code> folder. Before physical deletion, run an explicit
                 reviewed trash purge plan:
               </p>
               <pre><code>artshelf trash list --ledger /tmp/artshelf-ledger.jsonl

package/docs/reference.html

@@ -138,18 +138,24 @@ artshelf get &lt;id&gt; --all --json</code></pre>
             <section>
               <h2>Storage</h2>
               <p>
-                Inside a git repo, Artshelf defaults to `.shelf/ledger.jsonl`. Outside a repo, it
-                defaults to `~/.shelf/ledger.jsonl`. Pass `--ledger &lt;path&gt;` for tests, demos,
+                Inside a git repo, Artshelf defaults to `.artshelf/ledger.jsonl`. Outside a repo, it
+                defaults to `~/.artshelf/ledger.jsonl`. Pass `--ledger &lt;path&gt;` for tests, demos,
                 and controlled smoke runs.
               </p>
               <p>
-                Artshelf also keeps a user-level registry at `~/.shelf/ledgers.json`. Override it
+                Artshelf also keeps a user-level registry at `~/.artshelf/ledgers.json`. Override it
                 with <code>--registry &lt;path&gt;</code> or <code>ARTSHELF_REGISTRY</code>; legacy
                 <code>SHELF_REGISTRY</code> is used only when <code>ARTSHELF_REGISTRY</code> is unset.
                 The registry is a discovery index for supported `--all` review, status, cleanup
                 dry-run, and trash-list commands; project records stay in their own repo-local ledgers.
               </p>
-              <pre><code>artshelf ledgers add --ledger &lt;repo&gt;/.shelf/ledger.jsonl --name &lt;project&gt; --scope repo
+              <p>
+                Renamed installs before <code>0.5.0</code> used <code>.shelf</code> paths. Copy those
+                ledgers into <code>.artshelf</code>, rewrite registry paths, validate with
+                <code>artshelf ledgers list --json</code>, and keep the old directories until rollback
+                is no longer needed.
+              </p>
+              <pre><code>artshelf ledgers add --ledger &lt;repo&gt;/.artshelf/ledger.jsonl --name &lt;project&gt; --scope repo
 artshelf review --all --json
 artshelf status --all --json
 artshelf cleanup --dry-run --all --json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artshelf",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Tiny CLI for accountable temporary artifact retention.",
   "type": "module",
   "author": "Calvin",

package/skills/artshelf/SKILL.md

@@ -121,7 +121,7 @@ next safe action.
 them explicitly:
 
 ```bash
-artshelf ledgers add --ledger <repo>/.shelf/ledger.jsonl --name <project> --scope repo --json
+artshelf ledgers add --ledger <repo>/.artshelf/ledger.jsonl --name <project> --scope repo --json
 ```
 
 `--all` is for discovery and review. Do not use it as permission to mutate