artshelf 0.6.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +21 -3
- package/README.md +146 -219
- package/SPEC.md +56 -6
- package/dist/src/cli.js +258 -19
- package/docs/agent-clean.html +108 -0
- package/docs/agent-create.html +98 -0
- package/docs/agent-monitor.html +151 -0
- package/docs/agent-purge.html +111 -0
- package/docs/agent-review.html +120 -0
- package/docs/agent-usage.html +114 -402
- package/docs/agent-usage.md +52 -474
- package/docs/index.html +165 -152
- package/docs/install.html +214 -110
- package/docs/quickstart.html +105 -106
- package/docs/reference.html +239 -164
- package/docs/site.css +675 -490
- package/docs/site.js +398 -0
- package/package.json +1 -1
- package/skills/artshelf/SKILL.md +133 -333
- package/skills/artshelf/scripts/render-review-report.mjs +160 -0
- package/docs/theme.js +0 -42
package/docs/reference.html
CHANGED
|
@@ -3,178 +3,253 @@
|
|
|
3
3
|
<head>
|
|
4
4
|
<meta charset="utf-8">
|
|
5
5
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
-
<title>
|
|
6
|
+
<title>CLI reference · Artshelf</title>
|
|
7
7
|
<meta name="description" content="Artshelf v1 command reference.">
|
|
8
|
+
<script>(function(){var stored=null;try{stored=localStorage.getItem("artshelf-docs-theme");}catch(e){}var dark=false;try{dark=matchMedia("(prefers-color-scheme: dark)").matches;}catch(e){}document.documentElement.dataset.theme=stored||(dark?"dark":"light");})();</script>
|
|
9
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
10
|
+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
11
|
+
<link href="https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,450..680;1,9..144,450..680&family=Newsreader:ital,opsz,wght@0,6..72,400..650;1,6..72,400..650&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
|
|
8
12
|
<link rel="stylesheet" href="site.css">
|
|
9
|
-
<script src="
|
|
13
|
+
<script src="site.js" defer></script>
|
|
10
14
|
</head>
|
|
11
|
-
<body>
|
|
12
|
-
<
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
<button class="
|
|
16
|
-
<
|
|
17
|
-
<
|
|
18
|
-
|
|
19
|
-
<a href="
|
|
20
|
-
<
|
|
21
|
-
|
|
15
|
+
<body data-page="reference.html">
|
|
16
|
+
<a class="skip" href="#content">Skip to content</a>
|
|
17
|
+
<header class="masthead">
|
|
18
|
+
<div class="masthead-inner">
|
|
19
|
+
<button class="menu-btn" type="button" data-menu aria-label="Toggle navigation" aria-expanded="false"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M1 3.5h14M1 8h14M1 12.5h14" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg></button>
|
|
20
|
+
<a class="brand" href="index.html">Artshelf<span class="brand-tag">docs</span></a>
|
|
21
|
+
<button class="search-btn" type="button" data-search-open><span>Search docs</span><kbd>/</kbd></button>
|
|
22
|
+
<div class="masthead-tools">
|
|
23
|
+
<a class="gh" href="https://github.com/calvinnwq/artshelf">GitHub</a>
|
|
24
|
+
<button class="theme-btn" type="button" data-theme-toggle aria-label="Toggle color theme" aria-pressed="false">
|
|
25
|
+
<svg class="icon-moon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.6 12.1A6.5 6.5 0 0 1 7.4 2.7a6.5 6.5 0 1 0 7.2 9.4z" fill="currentColor"/></svg>
|
|
26
|
+
<svg class="icon-sun" viewBox="0 0 20 20" aria-hidden="true"><circle cx="10" cy="10" r="3.4" fill="currentColor"/><g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="10" y1="2" x2="10" y2="4"/><line x1="10" y1="16" x2="10" y2="18"/><line x1="2" y1="10" x2="4" y2="10"/><line x1="16" y1="10" x2="18" y2="10"/><line x1="4.2" y1="4.2" x2="5.6" y2="5.6"/><line x1="14.4" y1="14.4" x2="15.8" y2="15.8"/><line x1="4.2" y1="15.8" x2="5.6" y2="14.4"/><line x1="14.4" y1="5.6" x2="15.8" y2="4.2"/></g></svg>
|
|
27
|
+
</button>
|
|
22
28
|
</div>
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
<
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
</
|
|
49
|
-
<
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
29
|
+
</div>
|
|
30
|
+
</header>
|
|
31
|
+
|
|
32
|
+
<div class="frame">
|
|
33
|
+
<nav id="sidebar" class="sidebar" aria-label="Documentation"></nav>
|
|
34
|
+
|
|
35
|
+
<main id="content" class="article-col">
|
|
36
|
+
<article>
|
|
37
|
+
<p class="kicker"><span class="n">05</span>Reference · CLI</p>
|
|
38
|
+
<h1>Small commands, explicit cleanup.</h1>
|
|
39
|
+
<p class="lede">
|
|
40
|
+
Artshelf v1 keeps the API narrow: put entries in a ledger, query existing
|
|
41
|
+
records, write a cleanup plan, and use separate reviewed plan ids for
|
|
42
|
+
cleanup execution and trash purge. Every command below is tagged read-only,
|
|
43
|
+
writes ledger, writes registry, npm install, or approval-gated.
|
|
44
|
+
</p>
|
|
45
|
+
|
|
46
|
+
<section class="cmd">
|
|
47
|
+
<div class="cmd-head"><h2>artshelf put</h2><span class="cmd-flag plan">writes ledger</span></div>
|
|
48
|
+
<pre><code>artshelf put <path> --reason <text> (--ttl <ttl> | --retain-until <iso> | --manual-review) [options]</code></pre>
|
|
49
|
+
<p>Append a ledger entry with reason, retention, owner, labels, kind, and cleanup mode.</p>
|
|
50
|
+
<table class="opts">
|
|
51
|
+
<tr><th>option</th><th>meaning</th></tr>
|
|
52
|
+
<tr><td>--reason <text></td><td>short audit note for why the artifact exists</td></tr>
|
|
53
|
+
<tr><td>--ttl / --retain-until / --manual-review</td><td>choose exactly one retention mode</td></tr>
|
|
54
|
+
<tr><td>--cleanup review|trash|delete</td><td>cleanup mode; delete is accepted but refused at execute</td></tr>
|
|
55
|
+
<tr><td>--owner, --label, --kind</td><td>provenance for later lookup and triage</td></tr>
|
|
56
|
+
</table>
|
|
57
|
+
</section>
|
|
58
|
+
|
|
59
|
+
<section class="cmd">
|
|
60
|
+
<div class="cmd-head"><h2>artshelf ledgers list</h2><span class="cmd-flag readonly">read-only</span></div>
|
|
61
|
+
<pre><code><span class="c"># show registered ledgers and their health</span>
|
|
62
|
+
artshelf ledgers list [--plain] [--json]</code></pre>
|
|
63
|
+
<p>
|
|
64
|
+
<code>list</code> shows registered ledgers with validation status (ok/missing/invalid)
|
|
65
|
+
and entry counts; it exits non-zero when the registry or any ledger is broken, and
|
|
66
|
+
<code>--plain</code> skips validation.
|
|
67
|
+
</p>
|
|
68
|
+
</section>
|
|
69
|
+
|
|
70
|
+
<section class="cmd">
|
|
71
|
+
<div class="cmd-head"><h2>artshelf ledgers add</h2><span class="cmd-flag plan">writes registry</span></div>
|
|
72
|
+
<pre><code><span class="c"># register an existing ledger for --all review</span>
|
|
73
|
+
artshelf ledgers add --ledger <path> [--name <project>] [--scope repo|user|other]</code></pre>
|
|
74
|
+
<p>
|
|
75
|
+
<code>add</code> registers an existing ledger so Artshelf can review it through one
|
|
76
|
+
entry point; scope is inferred from the path when omitted.
|
|
77
|
+
</p>
|
|
78
|
+
</section>
|
|
79
|
+
|
|
80
|
+
<section class="cmd">
|
|
81
|
+
<div class="cmd-head"><h2>artshelf list / find / get</h2><span class="cmd-flag readonly">read-only</span></div>
|
|
82
|
+
<pre><code><span class="c"># browse ledger entries by status</span>
|
|
83
|
+
artshelf list [--all] [--status active|review-required|trashed|cleanup-refused|resolved]
|
|
84
|
+
|
|
85
|
+
<span class="c"># look up records by path, owner, or label</span>
|
|
86
|
+
artshelf find --path <path> [--owner <o>] [--label <l>] [--json]
|
|
87
|
+
|
|
88
|
+
<span class="c"># fetch one record by id</span>
|
|
89
|
+
artshelf get <id> [--all] [--json]</code></pre>
|
|
90
|
+
<p>
|
|
91
|
+
<code>list</code> shows ledger entries and current status. <code>find</code> looks up
|
|
92
|
+
existing records by path, owner, labels, and status. Use it before <code>put</code>
|
|
93
|
+
for idempotent registration; it requires at least one selector and never mutates records.
|
|
94
|
+
<code>get</code> is the audit lookup for one record by Artshelf id.
|
|
95
|
+
</p>
|
|
96
|
+
</section>
|
|
97
|
+
|
|
98
|
+
<section class="cmd">
|
|
99
|
+
<div class="cmd-head"><h2>artshelf due / validate</h2><span class="cmd-flag readonly">read-only</span></div>
|
|
100
|
+
<pre><code><span class="c"># classify active entries: kept, due, manual-review, missing-path</span>
|
|
101
|
+
artshelf due [--all] [--json]
|
|
102
|
+
|
|
103
|
+
<span class="c"># check ledger shape and cleanup metadata</span>
|
|
104
|
+
artshelf validate [--all] [--json]</code></pre>
|
|
105
|
+
<p>
|
|
106
|
+
<code>due</code> classifies active entries as kept, due, manual-review, or missing-path.
|
|
107
|
+
<code>validate</code> checks JSONL shape and handled cleanup metadata, and warns about
|
|
108
|
+
missing active, review-required, or trashed target paths. With <code>--all</code>, both
|
|
109
|
+
report stale registered ledgers.
|
|
110
|
+
</p>
|
|
111
|
+
</section>
|
|
112
|
+
|
|
113
|
+
<section class="cmd">
|
|
114
|
+
<div class="cmd-head"><h2>artshelf review / status / doctor</h2><span class="cmd-flag readonly">read-only</span></div>
|
|
115
|
+
<pre><code><span class="c"># validate + due + plan preview in one pass</span>
|
|
116
|
+
artshelf review [--all] [--json]
|
|
117
|
+
|
|
118
|
+
<span class="c"># lightweight dashboard of counts</span>
|
|
119
|
+
artshelf status [--all] [--json]
|
|
120
|
+
|
|
121
|
+
<span class="c"># CLI version, resolved paths, registry health</span>
|
|
122
|
+
artshelf doctor [--json]</code></pre>
|
|
123
|
+
<p>
|
|
124
|
+
<code>review</code> runs validate, due, and a cleanup plan preview in one pass; no-op
|
|
125
|
+
previews report <code>not-created</code>, and <code>--all</code> adds an aggregate triage
|
|
126
|
+
summary plus the next safe action. <code>status</code> is the lightweight dashboard of
|
|
127
|
+
counts; <code>--all --json</code> is cron-friendly. <code>doctor</code> reports CLI version,
|
|
128
|
+
resolved paths, registry health, and the cleanup safety posture.
|
|
129
|
+
</p>
|
|
130
|
+
</section>
|
|
131
|
+
|
|
132
|
+
<section class="cmd">
|
|
133
|
+
<div class="cmd-head"><h2>artshelf update</h2><span class="cmd-flag plan">npm install</span></div>
|
|
134
|
+
<pre><code><span class="c"># install the latest published npm package</span>
|
|
135
|
+
artshelf update [--json]</code></pre>
|
|
136
|
+
<p>
|
|
137
|
+
Normal commands may print a non-blocking notice to stderr when npm has a
|
|
138
|
+
newer published version. <code>artshelf update</code> runs
|
|
139
|
+
<code>npm install -g artshelf@latest</code> and is for npm global installs
|
|
140
|
+
only. pnpm global installs should update with
|
|
141
|
+
<code>pnpm add -g artshelf@latest</code>. Source installs should update by
|
|
142
|
+
pulling, rebuilding, and linking the checkout. Notices are cached in
|
|
143
|
+
<code>~/.artshelf/update-check.json</code>; set
|
|
144
|
+
<code>ARTSHELF_NO_UPDATE_CHECK=1</code> to disable automatic checks for
|
|
145
|
+
no-network scripts and scheduled jobs. Read-only command labels refer
|
|
146
|
+
to ledger and artifact mutation, not this optional update-check cache.
|
|
147
|
+
</p>
|
|
148
|
+
</section>
|
|
149
|
+
|
|
150
|
+
<section class="cmd">
|
|
151
|
+
<div class="cmd-head"><h2>artshelf cleanup</h2><span class="cmd-flag approval">approval-gated</span></div>
|
|
152
|
+
<pre><code><span class="c"># preview cleanup and register a reviewed plan</span>
|
|
153
|
+
artshelf cleanup --dry-run [--all] [--json]
|
|
154
|
+
|
|
155
|
+
<span class="c"># execute exactly one reviewed plan (approval only)</span>
|
|
156
|
+
artshelf cleanup --execute --plan-id <id> [--ledger <path>]</code></pre>
|
|
157
|
+
<p>
|
|
158
|
+
<code>--dry-run</code> creates and registers a cleanup plan without moving files;
|
|
159
|
+
no-op dry-runs report <code>not-created</code>, and matching dry-runs reuse the
|
|
160
|
+
existing plan id. <code>--execute</code> is approval-only for one reviewed plan id:
|
|
161
|
+
it writes a receipt, registers the receipt artifact, and updates touched records in the ledger.
|
|
162
|
+
</p>
|
|
163
|
+
<div class="callout" data-kind="boundary">
|
|
164
|
+
<span class="callout-label">Hard boundary</span>
|
|
165
|
+
<p>No daemon, no auto-execute, no global execute, and no fresh live set during execute.
|
|
166
|
+
<code>cleanup --execute --all</code> does not exist.</p>
|
|
56
167
|
</div>
|
|
57
|
-
</
|
|
58
|
-
</header>
|
|
59
|
-
|
|
60
|
-
<main class="wrap">
|
|
61
|
-
<article>
|
|
62
|
-
<section>
|
|
63
|
-
<h2>Commands</h2>
|
|
64
|
-
<div class="command-list">
|
|
65
|
-
<div class="command-row"><code>artshelf put <path></code><p>Append a ledger entry with reason, retention, owner, labels, kind, and cleanup mode.</p></div>
|
|
66
|
-
<div class="command-row"><code>artshelf ledgers list</code><p>List registered ledgers with per-ledger validation status (ok/missing/invalid), entry counts, and warning/error counts so agents can spot stale registry entries without a separate validate pass. Exits non-zero when the registry or any ledger is broken. Add <code>--plain</code> for the fast listing that skips validation.</p></div>
|
|
67
|
-
<div class="command-row"><code>artshelf ledgers add --ledger <path> [--scope repo|user|other]</code><p>Register an existing ledger so Artshelf can review it through one entry point. Scope is inferred from the path when omitted.</p></div>
|
|
68
|
-
<div class="command-row"><code>artshelf list</code><p>Show ledger entries and current status. Use <code>--all</code> and <code>--status active|review-required|trashed|cleanup-refused|resolved</code> to filter registered ledgers.</p></div>
|
|
69
|
-
<div class="command-row"><code>artshelf find --path <path></code><p>Read-only lookup for existing records by path, owner, labels, and status.</p></div>
|
|
70
|
-
<div class="command-row"><code>artshelf get <id></code><p>Read-only audit lookup for one ledger record by Artshelf id. Use <code>--all</code> to search registered ledgers.</p></div>
|
|
71
|
-
<div class="command-row"><code>artshelf due</code><p>Classify active entries as kept, due, manual-review, or missing-path. Use <code>--all</code> to read every registered ledger after registry validation.</p></div>
|
|
72
|
-
<div class="command-row"><code>artshelf validate</code><p>Validate JSONL shape, handled cleanup metadata, and warn about missing active, review-required, or trashed target paths. Use <code>--all</code> to report stale registered ledgers.</p></div>
|
|
73
|
-
<div class="command-row"><code>artshelf review</code><p>Run validate, due, and cleanup plan preview. Invalid ledgers and valid ledgers with no cleanup entries report a <code>not-created</code> plan. <code>--all</code> 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, staying read-only.</p></div>
|
|
74
|
-
<div class="command-row"><code>artshelf doctor</code><p>Report machine and registry health: CLI version, selected/default ledger path, selected/global registry path, stale or invalid registered ledgers, and the cleanup safety posture. Read-only; run it after install or when <code>--all</code> commands misbehave. Exits non-zero when the registry or a registered ledger is broken.</p></div>
|
|
75
|
-
<div class="command-row"><code>artshelf status</code><p>Lightweight daily dashboard: single-ledger counts by default, or registry health, total ledgers, and aggregated counts with <code>--all</code>. Reports active, kept, due, manual-review, and missing-path entries plus the pending cleanup count. Read-only and never writes plans or receipts; <code>--all --json</code> is cron-friendly and human output is short enough to paste into a chat.</p></div>
|
|
76
|
-
<div class="command-row"><code>artshelf cleanup --dry-run</code><p>Create and register a cleanup plan without moving files when cleanup entries exist; no-op dry-runs report <code>not-created</code>, and matching dry-runs reuse the existing plan id.</p></div>
|
|
77
|
-
<div class="command-row"><code>artshelf cleanup --execute --plan-id <id></code><p>Approval-only execution for one reviewed plan id: no daemon, no auto-execute, no global execute, and no fresh live set during execute. Writes a receipt, registers the receipt artifact, and updates touched ledger records.</p></div>
|
|
78
|
-
<div class="command-row"><code>artshelf trash list [--all] [--ledger <path>] [--json]</code><p>List trashed records with target path, receiving receipt provenance, and age.</p></div>
|
|
79
|
-
<div class="command-row"><code>artshelf trash purge --older-than <ttl> --dry-run [--ledger <path>] [--json]</code><p>Create a reviewed age-based trash purge plan from a specific ledger. The reviewed plan can be executed with <code>--execute --plan-id <id></code>.</p></div>
|
|
80
|
-
<div class="command-row"><code>artshelf trash purge --execute --plan-id <id> [--ledger <path>] [--json]</code><p>Execute a reviewed trash purge plan id for one explicit ledger. <code>--all</code> is not supported for purge; completed receipts are refused, while started receipts may be resumed and reconciled.</p></div>
|
|
81
|
-
<div class="command-row"><code>artshelf resolve <id> --status resolved --reason <text></code><p>Mark a handled, missing, or no-longer-needed record as manually resolved.</p></div>
|
|
82
|
-
</div>
|
|
83
|
-
</section>
|
|
84
|
-
|
|
85
|
-
<section>
|
|
86
|
-
<h2>Global Options</h2>
|
|
87
|
-
<pre><code>--ledger <path> Use an explicit JSONL ledger
|
|
88
|
-
--registry <path> Use an explicit ledger registry
|
|
89
|
-
--all Read all registered ledgers for supported commands
|
|
90
|
-
ARTSHELF_REGISTRY Override the default ledger registry path
|
|
91
|
-
SHELF_REGISTRY Legacy fallback when ARTSHELF_REGISTRY is unset
|
|
92
|
-
ARTSHELF_NOW Override current time for retention and due calculations
|
|
93
|
-
SHELF_NOW Legacy fallback when ARTSHELF_NOW is unset
|
|
94
|
-
--json Emit machine-readable JSON
|
|
95
|
-
--help Show help
|
|
96
|
-
--version Show version</code></pre>
|
|
97
|
-
</section>
|
|
98
|
-
|
|
99
|
-
<section>
|
|
100
|
-
<h2>Retention</h2>
|
|
101
|
-
<p>Choose exactly one retention mode when calling `put`.</p>
|
|
102
|
-
<pre><code>--ttl 3d
|
|
103
|
-
--retain-until 2026-06-04T08:28:00Z
|
|
104
|
-
--manual-review</code></pre>
|
|
105
|
-
</section>
|
|
106
|
-
|
|
107
|
-
<section>
|
|
108
|
-
<h2>Cleanup Modes</h2>
|
|
109
|
-
<div class="grid">
|
|
110
|
-
<div class="card"><h3>review</h3><p>Default. Included for review but not moved by execute.</p></div>
|
|
111
|
-
<div class="card"><h3>trash</h3><p>Moved into Artshelf's local trash folder when the approved plan executes.</p></div>
|
|
112
|
-
<div class="card"><h3>delete</h3><p>Accepted in the ledger but refused by v1 execution.</p></div>
|
|
113
|
-
</div>
|
|
114
|
-
<p>
|
|
115
|
-
Executed records move out of the active cleanup flow. `review` becomes
|
|
116
|
-
`review-required`, `trash` becomes `trashed`, and refused delete becomes
|
|
117
|
-
`cleanup-refused`. Manual resolution becomes `resolved`. `artshelf list` keeps
|
|
118
|
-
those records visible for audit.
|
|
119
|
-
</p>
|
|
120
|
-
<p>
|
|
121
|
-
`trash` moves stay in Artshelf quarantine until you run `artshelf trash purge`
|
|
122
|
-
with a reviewed purge plan for the current ledger.
|
|
123
|
-
</p>
|
|
124
|
-
</section>
|
|
168
|
+
</section>
|
|
125
169
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
artshelf
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
<
|
|
140
|
-
<
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
</
|
|
158
|
-
<
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
170
|
+
<section class="cmd">
|
|
171
|
+
<div class="cmd-head"><h2>artshelf trash</h2><span class="cmd-flag approval">approval-gated</span></div>
|
|
172
|
+
<pre><code><span class="c"># show trashed records with provenance and age</span>
|
|
173
|
+
artshelf trash list [--all] [--ledger <path>] [--json]
|
|
174
|
+
|
|
175
|
+
<span class="c"># preview an age-based purge plan for one ledger</span>
|
|
176
|
+
artshelf trash purge --older-than <ttl> --dry-run [--ledger <path>] [--json]
|
|
177
|
+
|
|
178
|
+
<span class="c"># physically delete, only with the reviewed purge plan id</span>
|
|
179
|
+
artshelf trash purge --execute --plan-id <id> [--ledger <path>] [--json]</code></pre>
|
|
180
|
+
<p>
|
|
181
|
+
<code>list</code> shows trashed records with target path, receipt provenance, and age.
|
|
182
|
+
<code>purge --dry-run</code> creates a reviewed age-based purge plan from a specific ledger;
|
|
183
|
+
<code>purge --execute</code> runs one reviewed purge plan id for one explicit ledger.
|
|
184
|
+
<code>--all</code> is not supported for purge. Completed receipts are refused; started
|
|
185
|
+
receipts may be resumed and reconciled.
|
|
186
|
+
</p>
|
|
187
|
+
</section>
|
|
188
|
+
|
|
189
|
+
<section class="cmd">
|
|
190
|
+
<div class="cmd-head"><h2>artshelf resolve</h2><span class="cmd-flag plan">writes ledger</span></div>
|
|
191
|
+
<pre><code>artshelf resolve <id> --status resolved --reason <text></code></pre>
|
|
192
|
+
<p>Mark a handled, missing, or no-longer-needed record as manually resolved. Updates the ledger only; never moves or deletes files.</p>
|
|
193
|
+
</section>
|
|
194
|
+
|
|
195
|
+
<section>
|
|
196
|
+
<h2>Global options</h2>
|
|
197
|
+
<table class="opts">
|
|
198
|
+
<tr><th>option</th><th>meaning</th></tr>
|
|
199
|
+
<tr><td>--ledger <path></td><td>use an explicit JSONL ledger</td></tr>
|
|
200
|
+
<tr><td>--registry <path></td><td>use an explicit ledger registry</td></tr>
|
|
201
|
+
<tr><td>--all</td><td>read all registered ledgers for supported commands</td></tr>
|
|
202
|
+
<tr><td>--json</td><td>emit machine-readable JSON</td></tr>
|
|
203
|
+
<tr><td>ARTSHELF_REGISTRY</td><td>override the default ledger registry path</td></tr>
|
|
204
|
+
<tr><td>ARTSHELF_NOW</td><td>override current time for retention and due calculations</td></tr>
|
|
205
|
+
<tr><td>ARTSHELF_NO_UPDATE_CHECK=1</td><td>disable automatic npm update checks</td></tr>
|
|
206
|
+
<tr><td>ARTSHELF_UPDATE_CACHE</td><td>override the update-check cache path</td></tr>
|
|
207
|
+
<tr><td>ARTSHELF_UPDATE_CHECK_TTL_MS</td><td>override the update-check cache TTL</td></tr>
|
|
208
|
+
<tr><td>ARTSHELF_NPM_REGISTRY_URL</td><td>override the npm latest-version endpoint</td></tr>
|
|
209
|
+
<tr><td>ARTSHELF_UPDATE_DRY_RUN=1</td><td>print the npm update command without running it</td></tr>
|
|
210
|
+
<tr><td>ARTSHELF_LATEST_VERSION</td><td>override the latest-version value for tests</td></tr>
|
|
211
|
+
</table>
|
|
212
|
+
</section>
|
|
213
|
+
|
|
214
|
+
<section>
|
|
215
|
+
<h2>Cleanup modes</h2>
|
|
216
|
+
<dl class="def-rows">
|
|
217
|
+
<div><dt>review</dt><dd>the default; included for review but not moved by execute; becomes <code>review-required</code></dd></div>
|
|
218
|
+
<div><dt>trash</dt><dd>moved into Artshelf's local trash when the approved plan executes; becomes <code>trashed</code></dd></div>
|
|
219
|
+
<div><dt>delete</dt><dd>accepted in the ledger, but v1 refuses delete execution; becomes <code>cleanup-refused</code></dd></div>
|
|
220
|
+
</dl>
|
|
221
|
+
<p>
|
|
222
|
+
Executed records move out of the active cleanup flow but stay visible in
|
|
223
|
+
<code>artshelf list</code> for audit. Manual resolution becomes <code>resolved</code>.
|
|
224
|
+
Trash moves stay in Artshelf quarantine until a reviewed purge plan runs for that ledger.
|
|
225
|
+
</p>
|
|
226
|
+
</section>
|
|
227
|
+
|
|
228
|
+
<section>
|
|
229
|
+
<h2>Storage</h2>
|
|
230
|
+
<p>
|
|
231
|
+
Inside a git repo, Artshelf defaults to <code>.artshelf/ledger.jsonl</code>. Outside a
|
|
232
|
+
repo it defaults to <code>~/.artshelf/ledger.jsonl</code>. A user-level registry at
|
|
233
|
+
<code>~/.artshelf/ledgers.json</code> is the discovery index for <code>--all</code>
|
|
234
|
+
review, status, cleanup dry-run, and trash-list; project records stay in their own
|
|
235
|
+
repo-local ledgers. Automatic update checks cache their last npm result at
|
|
236
|
+
<code>~/.artshelf/update-check.json</code> by default.
|
|
237
|
+
</p>
|
|
238
|
+
<div class="callout" data-kind="boundary">
|
|
239
|
+
<span class="callout-label">Hard boundary</span>
|
|
163
240
|
<p>
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
it from the path. All-mode reads report stale or invalid registered ledgers
|
|
167
|
-
before returning records. Global cleanup dry-run writes plan files only for ledgers
|
|
168
|
-
with cleanup entries, and <code>artshelf trash list --all --json</code> is read-only
|
|
169
|
-
trash discovery. Global cleanup execution and trash purge with <code>--all</code>
|
|
170
|
-
are refused. Execute only a specific reviewed plan id against the ledger that
|
|
171
|
-
produced it.
|
|
241
|
+
Global cleanup execution and trash purge with <code>--all</code> are refused.
|
|
242
|
+
Execute only a specific reviewed plan id against the ledger that produced it.
|
|
172
243
|
</p>
|
|
173
|
-
</
|
|
174
|
-
</
|
|
175
|
-
</
|
|
176
|
-
<footer class="
|
|
177
|
-
</
|
|
244
|
+
</div>
|
|
245
|
+
</section>
|
|
246
|
+
</article>
|
|
247
|
+
<footer class="pager" id="pager"></footer>
|
|
248
|
+
</main>
|
|
249
|
+
|
|
250
|
+
<aside class="toc-col"><p class="toc-title">On this page</p><nav id="toc" aria-label="On this page"></nav></aside>
|
|
178
251
|
</div>
|
|
252
|
+
|
|
253
|
+
<footer class="colophon"><div class="colophon-inner"><span>Artshelf docs</span><span>MIT</span><a href="https://github.com/calvinnwq/artshelf">GitHub</a></div></footer>
|
|
179
254
|
</body>
|
|
180
255
|
</html>
|