artshelf 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Renamed the published package and CLI binary from `shelf` to `artshelf`,
+  moved project URLs to `calvinnwq/artshelf`, and prepared public npm publishing.
 - Added a user-level ledger registry plus `--all` review commands so Artshelf can
   discover known project/user ledgers from one CLI entry point.
 - Added read-only `find` and `get` commands for ledger lookup and idempotent
@@ -50,6 +52,51 @@
 - Tightened the portable agent skill description so the completion-gate trigger
   is visible before final responses, status updates, handoffs, and done reports.
 
+## [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)
+
+
+### Features
+
+* **cli:** add approval-first trash list and purge workflow ([20405db](https://github.com/calvinnwq/artshelf/commit/20405db8a7856440afe6aaf487cc156e6c66245d))
+* **cli:** add approval-first trash list and purge workflow ([5a389f3](https://github.com/calvinnwq/artshelf/commit/5a389f3e4f18c75973f29dc727969063e3b3f54b))
+* **cli:** add ledger registry review ([0cbdcc6](https://github.com/calvinnwq/artshelf/commit/0cbdcc6c1c1706b78e84a738fd8dfef900459045))
+* **cli:** add ledger registry review ([d070131](https://github.com/calvinnwq/artshelf/commit/d0701317514f36ee266ca06c30b4ee67a6e45e42))
+* **cli:** add read-only `shelf doctor` health command ([0ce18ea](https://github.com/calvinnwq/artshelf/commit/0ce18ea560ae7f870ea68b7248d097f4c7033b91))
+* **cli:** add read-only `shelf status` dashboard command ([699035c](https://github.com/calvinnwq/artshelf/commit/699035c97009cb29caa0c995025a2d74533e21f1))
+* **cli:** add shelf doctor and status commands ([c0f9a10](https://github.com/calvinnwq/artshelf/commit/c0f9a109cee58de7d7e8cf27e3860fee62941686))
+* **cli:** add shelf lookup commands ([9092ea7](https://github.com/calvinnwq/artshelf/commit/9092ea72695b6b383a8ff3b74ccaabc2974e67fb))
+* **cli:** improve shelf review triage and ledger listing ([6dc3c65](https://github.com/calvinnwq/artshelf/commit/6dc3c65e6837e542510d53890f1f49d3a28e0878))
+* **cli:** optimize cleanup plan lifecycle ([f78773c](https://github.com/calvinnwq/artshelf/commit/f78773ca737b9d7a8318725d63590c9ed8184ba5))
+* **cli:** resolve shelf records ([f21318d](https://github.com/calvinnwq/artshelf/commit/f21318d6edd16a170fcb6539c40899ec8b83c1ba))
+* **cli:** summarize all-ledger review triage ([3284bd8](https://github.com/calvinnwq/artshelf/commit/3284bd886998777bd06a681ab3bfe0b819938c84))
+* **cli:** validate registered ledgers in ledgers list ([327e4f8](https://github.com/calvinnwq/artshelf/commit/327e4f815c814c6b540fcbae8b42dbd8873fb4ab))
+* optimize cleanup plan lifecycle ([4d77b2b](https://github.com/calvinnwq/artshelf/commit/4d77b2bed4a7bc963d2e9900a4dbbf3fed672514))
+* rename Shelf package and CLI to Artshelf ([127649d](https://github.com/calvinnwq/artshelf/commit/127649d3689493700a4ef68922b6a837a2d53fc2))
+* rename shelf to artshelf ([e7d250c](https://github.com/calvinnwq/artshelf/commit/e7d250cee56c27494bae224fe294387497fa8713))
+* resolve shelf records ([dcd5109](https://github.com/calvinnwq/artshelf/commit/dcd5109c5a73f5080d89db51f375b9a5e307c65b))
+* update ledger state after cleanup ([#7](https://github.com/calvinnwq/artshelf/issues/7)) ([31add84](https://github.com/calvinnwq/artshelf/commit/31add8466f0e37e397cfaf3dc146bd8060f57717))
+
+
+### Bug Fixes
+
+* build artshelf before packing ([470ea86](https://github.com/calvinnwq/artshelf/commit/470ea8637be29978e686f66b2bf1bb838a8a4fa8))
+* clarify approval-only cleanup safety model ([20b8258](https://github.com/calvinnwq/artshelf/commit/20b82584e86a0a8f9b4067d2fbdc94d2c8064253))
+* **cli:** align cleanup preview reuse ([b918a5d](https://github.com/calvinnwq/artshelf/commit/b918a5dc09536a9b87964fbf552b66ea16c0c62a))
+* **cli:** harden registry diagnostics ([098f88e](https://github.com/calvinnwq/artshelf/commit/098f88e9ec8167333cb4d8f67876054b1076f922))
+* **cli:** keep shelf review read-only ([8c417c2](https://github.com/calvinnwq/artshelf/commit/8c417c2e5737ee778c6f7a86b0c7e559d3cae7dc))
+* **cli:** normalize review no-plan output ([57a6275](https://github.com/calvinnwq/artshelf/commit/57a6275b5960385102e8e4c54cfa498404df562d))
+* **cli:** report stale ledgers in all-mode reads ([bc035ef](https://github.com/calvinnwq/artshelf/commit/bc035efbc15ba7877634cb7ec6c0702416d8510b))
+* harden artshelf rename migration ([a84957c](https://github.com/calvinnwq/artshelf/commit/a84957c186f442d9067d07ec132fda4201cbc59e))
+* **trash:** harden purge execution guardrails ([e569b1b](https://github.com/calvinnwq/artshelf/commit/e569b1be4a4f931f856fa9683afcb14023724ad9))
+
 ## [0.3.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.2.0...artshelf-v0.3.0) (2026-06-05)
 
 

package/README.md

@@ -16,13 +16,13 @@ stay out of the way until you need them.
 
 ## Status
 
-Artshelf is an early v1 MVP. The CLI is being prepared for npm distribution
-under the unscoped `artshelf` package name. The existing local/source install
-path remains supported as a fallback while npm publishing is wired up.
+Artshelf is an early v1 MVP. The CLI is distributed under the unscoped
+`artshelf` package name. The existing local/source install path remains supported
+as a fallback.
 
 ## Install
 
-Use the npm package once it is published:
+Install the npm package:
 
 ```bash
 npm install -g artshelf
@@ -127,8 +127,9 @@ 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_REGISTRY`. `put` registers its ledger automatically, and you can register
-an existing ledger explicitly:
+`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
@@ -245,9 +246,9 @@ purge, and when `artshelf resolve <id> --status resolved --reason <text>` may ma
 confirmed handled, missing, or no-longer-needed records without moving or
 deleting files.
 
-From a source checkout, use `skills/artshelf/SKILL.md` directly. Agents should ask
-where the user wants Artshelf cloned before installing or linking it. Package-manager
-distribution for agent skills can come later.
+The same skill ships in the npm package. From a source checkout, use
+`skills/artshelf/SKILL.md` directly. Agents should ask where the user wants
+Artshelf cloned before installing or linking it.
 
 ## Development
 
@@ -264,6 +265,13 @@ pnpm docs:serve
 
 Then open <http://127.0.0.1:8080/>.
 
+Release Please owns version bumps, changelog updates, tags, and GitHub releases.
+When a Release Please PR is merged and a release is created, the release workflow
+validates the package with `pnpm check` and publishes `artshelf` to npm through
+npm Trusted Publishing. The npm package must have this repository's release
+workflow configured as a trusted publisher; no long-lived npm token is expected
+in GitHub secrets.
+
 During tests or one-off runs, pass both `--ledger <path>` and `--registry <path>`
 to keep entries and registry updates out of default Artshelf storage.
 
@@ -274,7 +282,8 @@ covered by tests. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Support And Security
 
-Use GitHub issues for bugs and feature ideas once the public remote exists. See
+Use [GitHub issues](https://github.com/calvinnwq/artshelf/issues) for bugs and
+feature ideas. See
 [SUPPORT.md](SUPPORT.md) and [SECURITY.md](SECURITY.md).
 
 ## License

package/SPEC.md

@@ -440,7 +440,12 @@ Default behavior:
 V1 also supports a user-level registry of known ledgers:
 
 - registry: `~/.shelf/ledgers.json`
-- `ARTSHELF_REGISTRY` or `--registry <path>` can override the registry path.
+- `--registry <path>` overrides the registry path. Without it,
+  `ARTSHELF_REGISTRY` is read first, then legacy `SHELF_REGISTRY`, then the
+  default registry path.
+- 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.
 - `put` registers the ledger it writes to.
 - `ledgers add` registers an existing ledger explicitly.
 - `--all` reads registered ledgers as one review surface.
@@ -537,7 +542,7 @@ hold, and every future feature (`status`, `doctor`, `review`, scheduled jobs,
 ...) must preserve them rather than add a shortcut around them:
 
 - **No daemon.** Artshelf never runs in the background or watches the clock. It
-  only does work while you are running a `artshelf` command.
+  only does work while you are running an `artshelf` command.
 - **No auto-execute.** No command cleans up as a side effect. The only commands
   that move, trash, or delete files are `artshelf cleanup --execute` and
   `artshelf trash purge --execute`, each run by a human against a separately
@@ -672,4 +677,3 @@ human review.
 - Retention classes like keep-daily/weekly/monthly.
 - Dependency roots and pinning.
 - Credential scanning.
-- Public package publishing.

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

@@ -592,10 +592,9 @@ function registerArtshelfArtifact(ledgerPath, path, input) {
         labels: input.labels
     });
     const records = readLedger(ledgerPath);
-    const index = records.findIndex((record) => (record.owner === "artshelf" &&
+    const index = records.findIndex((record) => (isMatchingArtshelfArtifact(record, path, input.labels) &&
         record.status === "active" &&
-        record.path === path &&
-        sameLabels(record.labels, input.labels)));
+        record.path === path));
     if (index === -1) {
         appendPreparedRecord(ledgerPath, prepared);
         return;
@@ -611,10 +610,21 @@ function registerArtshelfArtifact(ledgerPath, path, input) {
         retention: prepared.retention,
         kind: prepared.kind,
         cleanup: prepared.cleanup,
+        owner: prepared.owner,
         labels: prepared.labels
     };
     writeLedger(ledgerPath, records);
 }
+function isMatchingArtshelfArtifact(record, path, labels) {
+    if (record.path !== path)
+        return false;
+    if (record.owner === "artshelf")
+        return sameLabels(record.labels, labels);
+    if (record.owner !== "shelf")
+        return false;
+    const legacyLabels = labels.map((label, index) => index === 0 && label === "artshelf" ? "shelf" : label);
+    return sameLabels(record.labels, legacyLabels);
+}
 function sameLabels(left, right) {
     if (left.length !== right.length)
         return false;

package/docs/index.html

@@ -51,7 +51,7 @@
                   then gives humans and agents a reviewable cleanup plan before anything moves.
                 </p>
                 <div class="actions">
-                  <a class="button primary" href="install.html">Install from source</a>
+                  <a class="button primary" href="install.html">Install from npm</a>
                   <a class="button" href="quickstart.html">Quickstart</a>
                   <a class="button" href="agent-usage.html">Agent usage</a>
                   <a class="button" href="https://github.com/calvinnwq/artshelf">GitHub</a>
@@ -119,8 +119,8 @@ $ artshelf cleanup --dry-run --json
               <h2>Pick Your Path</h2>
               <div class="grid">
                 <a class="doc-card" href="install.html">
-                  <strong>Install from source</strong>
-                  <span>Clone locally, build, link with npm, and smoke-test the CLI.</span>
+                  <strong>Install from npm</strong>
+                  <span>Install the package globally, or use source install as the fallback path.</span>
                 </a>
                 <a class="doc-card" href="quickstart.html">
                   <strong>Try the workflow</strong>
@@ -157,7 +157,7 @@ $ artshelf cleanup --dry-run --json
                 <li>Cleanup refuses delete actions; physical trash purge needs its own reviewed plan.</li>
               </ul>
               <div class="note">
-                Artshelf is an early v1 MVP. Source install and live dogfooding come before npm publishing.
+                Artshelf is an early v1 MVP. The npm package is the primary install path; source install remains available as a fallback.
               </div>
             </section>
           </article>

package/docs/install.html

@@ -42,8 +42,8 @@
                 <p class="eyebrow">Install</p>
                 <h1>Install Artshelf.</h1>
                 <p class="lede">
-                  Artshelf is being prepared for npm distribution under the unscoped
-                  `artshelf` package name. Source install remains the fallback path.
+                  Artshelf is distributed under the unscoped `artshelf` package name.
+                  Source install remains the fallback path.
                 </p>
               </div>
               <div class="terminal">
@@ -62,8 +62,8 @@ $ artshelf doctor</code></pre>
               <h2>Requirements</h2>
               <div class="grid">
                 <div class="card"><h3>Node.js 22+</h3><p>The package declares `node &gt;=22` and CI runs on Node 24.</p></div>
-                <div class="card"><h3>Corepack</h3><p>Use Corepack to activate the pinned pnpm version from `packageManager`.</p></div>
-                <div class="card"><h3>Git</h3><p>Clone the public repo and keep source installs easy to update with `git pull`.</p></div>
+                <div class="card"><h3>npm or pnpm</h3><p>Install the global package with your preferred Node package manager.</p></div>
+                <div class="card"><h3>Source tooling</h3><p>Corepack and Git are only needed when cloning, building, and linking from source.</p></div>
               </div>
             </section>
 
@@ -75,10 +75,6 @@ artshelf doctor</code></pre>
               <pre><code>pnpm add -g artshelf
 artshelf --version
 artshelf doctor</code></pre>
-              <p>
-                The npm package exposes `artshelf` as the primary command and keeps
-                `shelf` as a temporary compatibility alias.
-              </p>
               <pre><code>npm uninstall -g artshelf</code></pre>
             </section>
 

package/docs/reference.html

@@ -88,6 +88,9 @@ $ artshelf --version</code></pre>
 --registry &lt;path&gt; Use an explicit ledger registry
 --all             Read all registered ledgers for supported commands
 ARTSHELF_REGISTRY    Override the default ledger registry path
+SHELF_REGISTRY       Legacy fallback when ARTSHELF_REGISTRY is unset
+ARTSHELF_NOW         Override current time for retention and due calculations
+SHELF_NOW            Legacy fallback when ARTSHELF_NOW is unset
 --json            Emit machine-readable JSON
 --help            Show help
 --version         Show version</code></pre>
@@ -141,9 +144,10 @@ artshelf get &lt;id&gt; --all --json</code></pre>
               </p>
               <p>
                 Artshelf also keeps a user-level registry at `~/.shelf/ledgers.json`. Override it
-                with <code>--registry &lt;path&gt;</code> or <code>ARTSHELF_REGISTRY</code>. 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.
+                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
 artshelf review --all --json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artshelf",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Tiny CLI for accountable temporary artifact retention.",
   "type": "module",
   "author": "Calvin",
@@ -20,8 +20,7 @@
     "tmp"
   ],
   "bin": {
-    "artshelf": "dist/src/cli.js",
-    "shelf": "dist/src/cli.js"
+    "artshelf": "dist/src/cli.js"
   },
   "publishConfig": {
     "access": "public"
@@ -43,6 +42,8 @@
     "test": "node --test dist/tests/*.test.js",
     "check": "pnpm run build && pnpm run test",
     "docs:serve": "python3 -m http.server 8080 --bind 127.0.0.1 --directory docs",
+    "prepack": "pnpm run build",
+    "prepublishOnly": "pnpm run build",
     "start": "node dist/src/cli.js"
   },
   "devDependencies": {