artshelf 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+## Unreleased
+
+- 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
+  agent integrations.
+- Documented `find` / `get` as the lookup surface agents should use before
+  creating duplicate records with `put`.
+- Tightened portable agent trigger guidance and removed setup-specific docs so
+  Artshelf remains workflow-agnostic.
+- Added `pnpm docs:serve` for local static docs preview.
+- Changed cleanup dry-run to avoid writing plan files when there are no
+  executable cleanup entries, and registered Artshelf-created plans/receipts as
+  Artshelf-owned ledger artifacts.
+- Reuse unchanged cleanup dry-run plans by refreshing the existing plan timestamp
+  and Artshelf-owned plan record instead of creating duplicate plan files.
+- Added a read-only `artshelf doctor` command that reports CLI and runtime version,
+  the selected/default ledger path, selected/global registry path,
+  registered-ledger health (stale or invalid entries), and the cleanup safety
+  posture, exiting non-zero when the registry or a registered ledger is broken.
+- Added a read-only `artshelf status` dashboard: single-ledger mode reports
+  selected-ledger counts, while `--all` adds registry health, total ledgers, and
+  aggregated active, kept, due, manual-review, missing-path, and pending-cleanup
+  counts, with `--all --json` suited to cron and human output short enough to
+  paste into a chat.
+- Changed `artshelf ledgers list` to validate each registered ledger by default,
+  reporting ok/missing/invalid status, entry counts, and warning/error counts in
+  both human and JSON output and exiting non-zero when the registry or any
+  registered ledger is broken, so agents can detect stale registry entries
+  without a separate validate pass. Added `--plain` for the backward-compatible
+  fast path that lists registered ledgers without reading them.
+- Changed `artshelf review --all` to emit an aggregate triage summary alongside the
+  existing per-ledger detail: JSON gains a `summary` block (affected ledgers,
+  due, manual-review, missing-path, executable, skipped counts, and plan ids) and
+  human output adds a triage line plus the next safe action. Review stays
+  read-only and never writes cleanup plans.
+- Added approval-first `artshelf trash list` and `artshelf trash purge` commands for
+  reviewing quarantined trash and physically deleting it only from a reviewed,
+  ledger-scoped purge plan.
+- Changed ledger validation to require cleanup metadata on trashed records and
+  warn when a trashed target path is missing.
+- Hardened trash purge execution with ledger-local path checks, durable failure
+  receipts, interrupted-run resume, and refusal of completed purge receipts.
+- Reorganized the README and docs quickstart to lead with the approval-first
+  workflows — register a temp artifact, review everything safely, approve
+  cleanup safely, and purge old trash explicitly — keeping reference material
+  available below the lead.
+- Tightened the portable agent skill description so the completion-gate trigger
+  is visible before final responses, status updates, handoffs, and done reports.
+
+## [0.3.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.2.0...artshelf-v0.3.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))
+
+
+### Bug Fixes
+
+* **trash:** harden purge execution guardrails ([e569b1b](https://github.com/calvinnwq/artshelf/commit/e569b1be4a4f931f856fa9683afcb14023724ad9))
+
+## [0.2.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.1.0...artshelf-v0.2.0) (2026-06-04)
+
+
+### Features
+
+* **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 `artshelf doctor` health command ([0ce18ea](https://github.com/calvinnwq/artshelf/commit/0ce18ea560ae7f870ea68b7248d097f4c7033b91))
+* **cli:** add read-only `artshelf status` dashboard command ([699035c](https://github.com/calvinnwq/artshelf/commit/699035c97009cb29caa0c995025a2d74533e21f1))
+* **cli:** add artshelf doctor and status commands ([c0f9a10](https://github.com/calvinnwq/artshelf/commit/c0f9a109cee58de7d7e8cf27e3860fee62941686))
+* **cli:** add artshelf lookup commands ([9092ea7](https://github.com/calvinnwq/artshelf/commit/9092ea72695b6b383a8ff3b74ccaabc2974e67fb))
+* **cli:** improve artshelf 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 artshelf 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))
+* resolve artshelf 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
+
+* 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 artshelf 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))
+
+## 0.1.0 - 2026-06-01
+
+- Initial Artshelf CLI MVP.
+- Added JSONL ledger writes, `put`, `list`, `due`, `validate`, cleanup dry-run
+  plans, plan-id-based cleanup execution, `list --status`, and manual `resolve`.
+- Added Node test coverage and public-ready repository bootstrap.
+- Added GitHub Pages docs, source-install instructions, packaged agent skill,
+  and scheduled-review guidance for agents.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Calvin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,282 @@
+# Artshelf
+
+Artshelf is a tiny CLI for putting temporary artifacts, backups, and run outputs
+somewhere accountable, with an expiry tag and a cleanup plan.
+
+It is built for agent-heavy workflows where files and directories are often
+created in `tmp/`, repo folders, or backup locations and then forgotten. Artshelf
+records why an artifact exists at creation time, then makes later cleanup
+visible and reviewable.
+
+Artshelf centers on four approval-first workflows: **register a temp artifact** the
+moment it is created, **review everything safely** before anything moves,
+**approve cleanup safely** from a reviewed plan, and **purge old trash
+explicitly** from a separate reviewed plan. The reference sections further down
+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.
+
+## Install
+
+Use the npm package once it is published:
+
+```bash
+npm install -g artshelf
+artshelf --version
+artshelf doctor
+```
+
+With pnpm:
+
+```bash
+pnpm add -g artshelf
+artshelf --version
+artshelf doctor
+```
+
+Source install remains the fallback path: clone the repo, build it, and link the
+CLI with `npm link`.
+
+```bash
+git clone https://github.com/calvinnwq/artshelf.git
+cd artshelf
+corepack enable
+pnpm install --frozen-lockfile
+pnpm run build
+npm link
+artshelf --version
+artshelf doctor
+```
+
+To remove the linked command later:
+
+```bash
+npm uninstall -g artshelf
+npm unlink -g artshelf
+```
+
+## Core Workflows
+
+Artshelf is built around four approval-first workflows. Start here; the reference
+sections below are there when you need them, not before.
+
+### 1. Register a temp artifact
+
+Record an artifact the moment it is created, while the reason is still fresh:
+
+```bash
+artshelf put tmp/run-output --reason "debug parser output" --ttl 3d --kind scratch --cleanup trash
+```
+
+Artshelf returns an id. Capture it anywhere future cleanup context matters.
+
+### 2. Review everything safely
+
+Inspect the ledger and preview cleanup without moving anything:
+
+```bash
+artshelf list
+artshelf status
+artshelf due
+artshelf cleanup --dry-run
+```
+
+Because this example keeps the artifact for three days, an immediate dry-run
+reports `not-created` and writes no plan. A dry-run returns a real plan id only
+after `due` shows cleanup entries.
+
+### 3. Approve cleanup safely
+
+Execute only from a reviewed plan id, and only after a human approves it:
+
+```bash
+artshelf cleanup --execute --plan-id plan_20260601_120000_ab12
+```
+
+There is no auto-execute, no global execute, and no fresh-plan-then-execute
+shortcut. Execution writes a receipt and updates the touched ledger records.
+
+### 4. Purge old trash explicitly
+
+Cleanup execution with `cleanup=trash` moves artifacts into Artshelf's local trash
+folder. Those trashed records remain discoverable (`artshelf trash list`) for review
+and should only be physically removed through a separately reviewed trash purge
+plan:
+
+```bash
+artshelf trash purge --older-than 30d --dry-run --json
+artshelf trash purge --execute --plan-id purge_20260601_120000_ab12
+```
+
+This adds a separate approval boundary between quarantine and destructive deletion.
+
+## 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
+`--registry <path>` for tests, demos, and unusual workflows:
+
+```bash
+artshelf put /tmp/parser-output --reason "parser fixture" --ttl 1d --ledger /tmp/artshelf-ledger.jsonl --registry /tmp/artshelf-registry.json --json
+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:
+
+```bash
+artshelf ledgers list
+artshelf ledgers add --ledger /path/to/repo/.shelf/ledger.jsonl --name my-repo
+```
+
+`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
+`--plain` for the fast listing that skips validation.
+
+Use `--all` for one read-only discovery entry point across registered ledgers:
+
+```bash
+artshelf review --all --json
+artshelf status --all --json
+artshelf due --all --json
+artshelf trash list --all --json
+artshelf find --all --owner <agent-or-runtime> --json
+```
+
+`artshelf review --all` adds an aggregate triage summary (affected ledgers, due,
+manual-review, missing-path, executable, and skipped counts plus preview plan
+ids) and states the next safe action, while staying read-only.
+
+Use global dry-run cleanup when you want Artshelf to write cleanup plans for
+registered ledgers with cleanup entries, without moving files:
+
+```bash
+artshelf cleanup --dry-run --all --json
+```
+
+Global execution is intentionally refused. To mutate files, review a dry-run
+plan, then execute it against the specific ledger that produced it.
+Repeated dry-runs with the same executable cleanup entries reuse the existing
+plan id and refresh its timestamp instead of creating duplicate plan files.
+
+## Safety Model
+
+- Ledger-first, not filesystem-scan-first.
+- Dry-run before mutation.
+- Execute only from a reviewed plan id.
+- No daemon or auto-execute path.
+- No global execute; cleanup execute and trash purge refuse `--all`.
+  `--all` is read-only or dry-run reporting only.
+- No fresh-plan-then-execute shortcut.
+- Trash/review by default, not delete.
+- No silent deletion; `cleanup=delete` stays refused, and trash purge needs its own reviewed plan.
+- Agent-friendly JSON output from every command.
+- Small enough to actually use.
+
+V1 only moves `cleanup=trash` entries into Artshelf's local trash folder. Entries
+marked `cleanup=review` become `review-required`, and `cleanup=delete` is
+refused as `cleanup-refused`; physical deletion only happens through a separate
+reviewed `artshelf trash purge --execute` plan.
+
+Dry-run cleanup writes a plan only when there are executable cleanup entries.
+No-op dry-runs report `not-created` and avoid writing plan files. When Artshelf does
+write a plan, it also records that plan in the ledger as an Artshelf-owned artifact.
+
+After `cleanup --execute`, Artshelf writes a receipt, records the receipt as a
+Artshelf-owned artifact, and updates touched ledger records. Handled records stop
+appearing in `due` and future dry-run cleanup plans, while `artshelf list` still
+keeps the audit trail visible.
+
+## Commands
+
+```bash
+artshelf put <path> --reason "debug parser output" --ttl 3d --kind scratch
+artshelf ledgers list
+artshelf ledgers list --plain
+artshelf ledgers add --ledger <path>
+artshelf list
+artshelf list --all
+artshelf list --status active
+artshelf find --path <path> --owner <agent-or-runtime> --label <task-or-run-id>
+artshelf find --all --owner <agent-or-runtime>
+artshelf get <id>
+artshelf get <id> --all
+artshelf due
+artshelf due --all
+artshelf validate
+artshelf validate --all
+artshelf review
+artshelf review --all
+artshelf doctor
+artshelf status
+artshelf status --all
+artshelf cleanup --dry-run
+artshelf cleanup --dry-run --all
+artshelf cleanup --execute --plan-id <id>
+artshelf trash list [--all] [--ledger <path>] [--json]
+artshelf trash purge --older-than <ttl> --dry-run [--ledger <path>] [--json]
+artshelf trash purge --execute --plan-id <id> [--ledger <path>] [--json]
+artshelf resolve <id> --status resolved --reason "inspected and no longer needed"
+```
+
+Use `artshelf help` or `artshelf help <command>` for command details. All core
+commands support `--json`.
+
+See the [docs site](https://calvinnwq.github.io/artshelf/) for install,
+quickstart, agent usage, and CLI reference. The source repo also keeps the
+[v1 spec](SPEC.md) and [agent usage guide](docs/agent-usage.md).
+
+## Agent Skill
+
+The package includes an agent-facing skill at `skills/artshelf/SKILL.md`. Agents
+that support local skills can copy or reference this file to learn when to call
+`artshelf put`, how to report Artshelf ids in handoffs and issue comments, why
+`artshelf find` / `artshelf get` are the read-only idempotency lookup surface, why
+`cleanup --execute` requires explicit approval for a reviewed plan id, how to
+review trashed records with `artshelf trash list` before a separately approved trash
+purge, and when `artshelf resolve <id> --status resolved --reason <text>` may mark
+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.
+
+## Development
+
+```bash
+pnpm install
+pnpm check
+```
+
+Preview the static docs site locally:
+
+```bash
+pnpm docs:serve
+```
+
+Then open <http://127.0.0.1:8080/>.
+
+During tests or one-off runs, pass both `--ledger <path>` and `--registry <path>`
+to keep entries and registry updates out of default Artshelf storage.
+
+## Contributing
+
+Artshelf is small on purpose. Keep new behavior ledger-first, previewable, and
+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
+[SUPPORT.md](SUPPORT.md) and [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).