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/index.html
CHANGED
|
@@ -3,170 +3,183 @@
|
|
|
3
3
|
<head>
|
|
4
4
|
<meta charset="utf-8">
|
|
5
5
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
-
<title>Artshelf
|
|
7
|
-
<meta name="description" content="Artshelf
|
|
6
|
+
<title>Artshelf docs · approval-first artifact retention</title>
|
|
7
|
+
<meta name="description" content="Artshelf records why temporary artifacts exist and refuses to clean anything up without exact human approval.">
|
|
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
|
-
|
|
16
|
-
|
|
17
|
-
</
|
|
18
|
-
<
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
<a href="quickstart.html">Quickstart</a>
|
|
15
|
+
<body data-page="index.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>
|
|
25
28
|
</div>
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
<
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
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">01</span>Start · Overview</p>
|
|
38
|
+
<h1>A shelf for temporary work.</h1>
|
|
39
|
+
<p class="lede">
|
|
40
|
+
Artshelf is an approval-first artifact retention CLI for coding agents and
|
|
41
|
+
the humans reviewing them. Agents create files they should not forget:
|
|
42
|
+
backups, reports, quarantines, debug output. Artshelf records why each one
|
|
43
|
+
exists, when to look at it again, and what cleanup is allowed to do with it.
|
|
44
|
+
</p>
|
|
38
45
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
<span>Docs</span>
|
|
44
|
-
</nav>
|
|
45
|
-
<div class="hero">
|
|
46
|
-
<div>
|
|
47
|
-
<p class="eyebrow">Temporary artifacts · Accountable cleanup</p>
|
|
48
|
-
<h1>Put run outputs somewhere accountable.</h1>
|
|
49
|
-
<p class="lede">
|
|
50
|
-
Artshelf records why temporary artifacts, backups, and debug evidence exist,
|
|
51
|
-
then gives humans and agents a reviewable cleanup plan before anything moves.
|
|
52
|
-
</p>
|
|
53
|
-
<div class="actions">
|
|
54
|
-
<a class="button primary" href="install.html">Install from npm</a>
|
|
55
|
-
<a class="button" href="quickstart.html">Quickstart</a>
|
|
56
|
-
<a class="button" href="agent-usage.html">Agent usage</a>
|
|
57
|
-
<a class="button" href="https://github.com/calvinnwq/artshelf">GitHub</a>
|
|
58
|
-
</div>
|
|
59
|
-
</div>
|
|
60
|
-
<div class="terminal" aria-label="Artshelf terminal example">
|
|
61
|
-
<div class="terminal-head"><span class="dot"></span><span class="dot"></span><span class="dot"></span><span>artshelf</span></div>
|
|
62
|
-
<pre><code>$ artshelf put /tmp/parser-output \
|
|
63
|
-
--reason "debug evidence for parser fix" \
|
|
64
|
-
--ttl 3d \
|
|
65
|
-
--kind run-artifact \
|
|
66
|
-
--cleanup review
|
|
46
|
+
<section>
|
|
47
|
+
<h2>First command</h2>
|
|
48
|
+
<pre><code><span class="c"># install the CLI</span>
|
|
49
|
+
npm install -g artshelf
|
|
67
50
|
|
|
68
|
-
|
|
69
|
-
|
|
51
|
+
<span class="c"># put a file on the shelf: where it is, why it exists, when to look again</span>
|
|
52
|
+
artshelf put ./backup-2026-06-10.tar.gz \
|
|
53
|
+
--reason "pre-migration backup" --ttl 7d --cleanup trash
|
|
70
54
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
55
|
+
<span class="c"># ask what needs attention (reads only, moves nothing)</span>
|
|
56
|
+
artshelf review --json</code></pre>
|
|
57
|
+
<p>
|
|
58
|
+
That is the whole habit. Every temporary file gets a ledger entry, and
|
|
59
|
+
<code>review</code> tells you what needs attention without touching anything.
|
|
60
|
+
</p>
|
|
61
|
+
</section>
|
|
62
|
+
|
|
63
|
+
<section>
|
|
64
|
+
<h2>The loop</h2>
|
|
65
|
+
<p>
|
|
66
|
+
Everything in Artshelf follows five stages: Create, Monitor, Review, Clean, Purge.
|
|
67
|
+
The agent docs use the same names, and each stage links to its page.
|
|
68
|
+
</p>
|
|
69
|
+
<div class="ledger">
|
|
70
|
+
<a class="ledger-row" href="agent-create.html">
|
|
71
|
+
<span class="n">4.1</span>
|
|
72
|
+
<span class="stage">Create</span>
|
|
73
|
+
<span class="what"><span class="cmdline">artshelf put <path> --reason <why> --ttl <ttl></span>Register a temporary file while you still remember why it exists. The record keeps the path, the reason, and a review date.</span>
|
|
74
|
+
</a>
|
|
75
|
+
<a class="ledger-row" href="agent-monitor.html">
|
|
76
|
+
<span class="n">4.2</span>
|
|
77
|
+
<span class="stage">Monitor</span>
|
|
78
|
+
<span class="what"><span class="cmdline">artshelf review --all --json</span>Check the shelf on a schedule. Monitor commands do not mutate ledgers or artifacts, so agents and cron jobs can run them safely.</span>
|
|
79
|
+
</a>
|
|
80
|
+
<a class="ledger-row" href="agent-review.html">
|
|
81
|
+
<span class="n">4.3</span>
|
|
82
|
+
<span class="stage">Review</span>
|
|
83
|
+
<span class="what"><span class="cmdline">artshelf cleanup --dry-run --json</span>Preview what cleanup would do and get a plan id. A human reads that plan and approves it, or doesn't.</span>
|
|
84
|
+
</a>
|
|
85
|
+
<a class="ledger-row" href="agent-clean.html">
|
|
86
|
+
<span class="n">4.4</span>
|
|
87
|
+
<span class="stage">Clean</span>
|
|
88
|
+
<span class="what"><span class="cmdline">artshelf cleanup --execute --plan-id <id></span>Run the one plan the human approved. Artshelf trashes the file, writes receipts, and a follow-up review confirms the shelf is quiet.</span>
|
|
89
|
+
</a>
|
|
90
|
+
<a class="ledger-row" href="agent-purge.html">
|
|
91
|
+
<span class="n">4.5</span>
|
|
92
|
+
<span class="stage">Purge</span>
|
|
93
|
+
<span class="what"><span class="cmdline">artshelf trash purge --execute --plan-id <id></span>Permanently remove old trashed artifacts through a separate, separately reviewed purge plan. Physical deletion never piggybacks on the cleanup plan.</span>
|
|
94
|
+
</a>
|
|
74
95
|
</div>
|
|
75
|
-
</
|
|
76
|
-
</header>
|
|
96
|
+
</section>
|
|
77
97
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
<
|
|
81
|
-
|
|
82
|
-
<
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
<
|
|
92
|
-
<
|
|
93
|
-
</
|
|
94
|
-
|
|
98
|
+
<section>
|
|
99
|
+
<h2>Safety model</h2>
|
|
100
|
+
<p>The same rules apply everywhere, to agents and humans alike. There are no escape hatches.</p>
|
|
101
|
+
<ul class="boundary-list">
|
|
102
|
+
<li>
|
|
103
|
+
<span class="stamp refused">Refused</span>
|
|
104
|
+
<span>No automatic cleanup. Nothing runs on a schedule or daemon, ever.</span>
|
|
105
|
+
</li>
|
|
106
|
+
<li>
|
|
107
|
+
<span class="stamp refused">Refused</span>
|
|
108
|
+
<span><code>cleanup --execute --all</code> does not exist. Execution names one ledger and one reviewed plan id.</span>
|
|
109
|
+
</li>
|
|
110
|
+
<li>
|
|
111
|
+
<span class="stamp refused">Refused</span>
|
|
112
|
+
<span>Delete is refused in v1. <code>cleanup=trash</code> quarantines; physical deletion needs a separate reviewed purge plan.</span>
|
|
113
|
+
</li>
|
|
114
|
+
<li>
|
|
115
|
+
<span class="stamp approval">Approval</span>
|
|
116
|
+
<span>Execute runs only from an already-reviewed ledger plus plan id, after exact human approval.</span>
|
|
117
|
+
</li>
|
|
118
|
+
<li>
|
|
119
|
+
<span class="stamp readonly">Read-only</span>
|
|
120
|
+
<span><code>review</code>, <code>status</code>, and <code>doctor</code> never write plans, receipts, or records.</span>
|
|
121
|
+
</li>
|
|
122
|
+
</ul>
|
|
123
|
+
</section>
|
|
95
124
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
</
|
|
116
|
-
|
|
125
|
+
<section>
|
|
126
|
+
<h2>What a record looks like</h2>
|
|
127
|
+
<p>A record is one line of JSON in the ledger file (<code>.artshelf/ledger.jsonl</code>):</p>
|
|
128
|
+
<pre><code>{
|
|
129
|
+
"id": "shf_20260610_091400_4be1",
|
|
130
|
+
"path": "/repo/backup-2026-06-10.tar.gz",
|
|
131
|
+
"kind": "backup",
|
|
132
|
+
"reason": "pre-migration backup",
|
|
133
|
+
"createdAt": "2026-06-10T09:14:00.000Z",
|
|
134
|
+
"retention": { "mode": "ttl", "ttl": "7d" },
|
|
135
|
+
"retainUntil": "2026-06-17T09:14:00.000Z",
|
|
136
|
+
"cleanup": "trash",
|
|
137
|
+
"owner": "manual",
|
|
138
|
+
"labels": ["migration"],
|
|
139
|
+
"status": "active"
|
|
140
|
+
}</code></pre>
|
|
141
|
+
<p>
|
|
142
|
+
Three fields drive the loop. <code>retention</code> decides when the record
|
|
143
|
+
comes due, <code>cleanup</code> decides what an approved plan may do with the
|
|
144
|
+
file, and <code>status</code> tracks where the record sits in that loop.
|
|
145
|
+
The <code>id</code> is what you quote in reports and handoffs.
|
|
146
|
+
</p>
|
|
147
|
+
<p>
|
|
148
|
+
Ledgers stay with the work. Each project keeps its own ledger file, and a
|
|
149
|
+
global registry keeps track of every ledger it has seen, so one read-only
|
|
150
|
+
command can answer for all of them without merging records into one
|
|
151
|
+
global file.
|
|
152
|
+
</p>
|
|
153
|
+
<pre><code><span class="c"># each project writes its own ledger</span>
|
|
154
|
+
~/work/api/.artshelf/ledger.jsonl
|
|
155
|
+
~/work/site/.artshelf/ledger.jsonl
|
|
117
156
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
<div class="grid">
|
|
121
|
-
<a class="doc-card" href="install.html">
|
|
122
|
-
<strong>Install from npm</strong>
|
|
123
|
-
<span>Install the package globally, or use source install as the fallback path.</span>
|
|
124
|
-
</a>
|
|
125
|
-
<a class="doc-card" href="quickstart.html">
|
|
126
|
-
<strong>Try the workflow</strong>
|
|
127
|
-
<span>Register a temp artifact, review safely, approve cleanup, and purge old trash explicitly.</span>
|
|
128
|
-
</a>
|
|
129
|
-
<a class="doc-card" href="agent-usage.html">
|
|
130
|
-
<strong>Wire up agents</strong>
|
|
131
|
-
<span>Teach agents when to call Artshelf and how to report Artshelf ids.</span>
|
|
132
|
-
</a>
|
|
133
|
-
<a class="doc-card" href="reference.html">
|
|
134
|
-
<strong>Look up commands</strong>
|
|
135
|
-
<span>See the v1 command surface and cleanup safety rules.</span>
|
|
136
|
-
</a>
|
|
137
|
-
<a class="doc-card" href="https://github.com/calvinnwq/artshelf/blob/main/SPEC.md">
|
|
138
|
-
<strong>Read the spec</strong>
|
|
139
|
-
<span>Understand the ledger-first contract and v1 non-goals.</span>
|
|
140
|
-
</a>
|
|
141
|
-
<a class="doc-card" href="https://github.com/calvinnwq/artshelf">
|
|
142
|
-
<strong>Open the repo</strong>
|
|
143
|
-
<span>Source, tests, release automation, and the portable agent skill.</span>
|
|
144
|
-
</a>
|
|
145
|
-
</div>
|
|
146
|
-
</section>
|
|
157
|
+
<span class="c"># the global registry keeps track of every known ledger</span>
|
|
158
|
+
~/.artshelf/ledgers.json
|
|
147
159
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
<ul>
|
|
151
|
-
<li>Ledger-first. Artshelf only cleans entries that were registered intentionally.</li>
|
|
152
|
-
<li>Dry-run before mutation. Plans are written before execution.</li>
|
|
153
|
-
<li>No daemon or auto-execute path. Only a human-run command can mutate files.</li>
|
|
154
|
-
<li>No global execute. <code>--all</code> is read-only or dry-run reporting only; trash purge refuses it.</li>
|
|
155
|
-
<li>No fresh-plan-then-execute shortcut. Execute only a reviewed plan id.</li>
|
|
156
|
-
<li>Handled records stop appearing in future due and cleanup dry-run output.</li>
|
|
157
|
-
<li>Cleanup refuses delete actions; physical trash purge needs its own reviewed plan.</li>
|
|
158
|
-
</ul>
|
|
159
|
-
<div class="note">
|
|
160
|
-
Artshelf is an early v1 MVP. The npm package is the primary install path; source install remains available as a fallback.
|
|
161
|
-
</div>
|
|
162
|
-
</section>
|
|
163
|
-
</article>
|
|
164
|
-
</main>
|
|
160
|
+
<span class="c"># put registers its ledger automatically; add existing ones explicitly</span>
|
|
161
|
+
artshelf ledgers add --ledger <repo>/.artshelf/ledger.jsonl --name <project> --scope repo
|
|
165
162
|
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
163
|
+
<span class="c"># --all commands read across every registered ledger</span>
|
|
164
|
+
artshelf review --all --json</code></pre>
|
|
165
|
+
</section>
|
|
166
|
+
|
|
167
|
+
<section>
|
|
168
|
+
<h2>Where next</h2>
|
|
169
|
+
<ul>
|
|
170
|
+
<li><a href="install.html">Install</a>: get the CLI from npm and check it with <code>artshelf doctor</code>.</li>
|
|
171
|
+
<li><a href="quickstart.html">Quickstart</a>: walk one real artifact through the whole loop in five minutes.</li>
|
|
172
|
+
<li><a href="agent-usage.html">Agent usage</a>: the Create, Monitor, Review, Clean, Purge contract for coding agents.</li>
|
|
173
|
+
<li><a href="reference.html">CLI reference</a>: every command on one page.</li>
|
|
174
|
+
</ul>
|
|
175
|
+
</section>
|
|
176
|
+
</article>
|
|
177
|
+
<footer class="pager" id="pager"></footer>
|
|
178
|
+
</main>
|
|
179
|
+
|
|
180
|
+
<aside class="toc-col"><p class="toc-title">On this page</p><nav id="toc" aria-label="On this page"></nav></aside>
|
|
170
181
|
</div>
|
|
182
|
+
|
|
183
|
+
<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>
|
|
171
184
|
</body>
|
|
172
185
|
</html>
|