artshelf 0.5.0 → 0.7.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 +24 -0
- package/README.md +58 -27
- package/SPEC.md +28 -0
- package/docs/agent-clean.html +126 -0
- package/docs/agent-create.html +98 -0
- package/docs/agent-monitor.html +150 -0
- package/docs/agent-review.html +120 -0
- package/docs/agent-usage.html +104 -313
- package/docs/agent-usage.md +36 -379
- package/docs/examples/artshelf-review-report.json +116 -0
- package/docs/index.html +160 -152
- package/docs/install.html +187 -109
- package/docs/quickstart.html +105 -106
- package/docs/reference.html +214 -164
- package/docs/schemas/artshelf-review-report.schema.json +315 -0
- package/docs/site.css +675 -490
- package/docs/site.js +397 -0
- package/examples/artshelf-review-report.json +116 -0
- package/package.json +3 -1
- package/schemas/artshelf-review-report.schema.json +315 -0
- package/skills/artshelf/SKILL.md +140 -256
- package/skills/artshelf/examples/artshelf-review-report.json +116 -0
- package/skills/artshelf/schemas/artshelf-review-report.schema.json +315 -0
- package/skills/artshelf/scripts/render-review-report.mjs +160 -0
- package/docs/theme.js +0 -42
package/docs/install.html
CHANGED
|
@@ -3,131 +3,209 @@
|
|
|
3
3
|
<head>
|
|
4
4
|
<meta charset="utf-8">
|
|
5
5
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
-
<title>Install Artshelf</title>
|
|
7
|
-
<meta name="description" content="Install Artshelf from npm or
|
|
6
|
+
<title>Install · Artshelf</title>
|
|
7
|
+
<meta name="description" content="Install Artshelf from npm or source, then verify with doctor.">
|
|
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="install.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
|
-
<div>
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
$ artshelf --version
|
|
53
|
-
$ artshelf doctor</code></pre>
|
|
54
|
-
</div>
|
|
55
|
-
</div>
|
|
56
|
-
</div>
|
|
57
|
-
</header>
|
|
58
|
-
|
|
59
|
-
<main class="wrap">
|
|
60
|
-
<article>
|
|
61
|
-
<section>
|
|
62
|
-
<h2>Requirements</h2>
|
|
63
|
-
<div class="grid">
|
|
64
|
-
<div class="card"><h3>Node.js 22+</h3><p>The package declares `node >=22` and CI runs on Node 24.</p></div>
|
|
65
|
-
<div class="card"><h3>npm or pnpm</h3><p>Install the global package with your preferred Node package manager.</p></div>
|
|
66
|
-
<div class="card"><h3>Source tooling</h3><p>Corepack and Git are only needed when cloning, building, and linking from source.</p></div>
|
|
67
|
-
</div>
|
|
68
|
-
</section>
|
|
69
|
-
|
|
70
|
-
<section>
|
|
71
|
-
<h2>Install From npm</h2>
|
|
72
|
-
<pre><code>npm install -g artshelf
|
|
73
|
-
artshelf --version
|
|
74
|
-
artshelf doctor</code></pre>
|
|
75
|
-
<pre><code>pnpm add -g artshelf
|
|
76
|
-
artshelf --version
|
|
77
|
-
artshelf doctor</code></pre>
|
|
78
|
-
<pre><code>npm uninstall -g artshelf</code></pre>
|
|
79
|
-
</section>
|
|
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">02</span>Start · Install</p>
|
|
38
|
+
<h1>Install the CLI, then run doctor.</h1>
|
|
39
|
+
<p class="lede">
|
|
40
|
+
Install globally from npm, verify the command works, then hand the setup
|
|
41
|
+
prompt to your coding agent.
|
|
42
|
+
</p>
|
|
43
|
+
|
|
44
|
+
<section>
|
|
45
|
+
<h2>Requirements</h2>
|
|
46
|
+
<dl class="def-rows">
|
|
47
|
+
<div><dt>Node.js 22+</dt><dd>the package declares <code>node >=22</code>; CI runs on Node 24</dd></div>
|
|
48
|
+
<div><dt>npm or pnpm</dt><dd>any Node package manager can install the global package</dd></div>
|
|
49
|
+
<div><dt>Git + Corepack</dt><dd>only needed for the source install below</dd></div>
|
|
50
|
+
</dl>
|
|
51
|
+
</section>
|
|
52
|
+
|
|
53
|
+
<section>
|
|
54
|
+
<h2>Installation</h2>
|
|
55
|
+
<p>Pick one method. All three end with the same global <code>artshelf</code> command.</p>
|
|
56
|
+
<pre><code><span class="c"># npm</span>
|
|
57
|
+
npm install -g artshelf
|
|
80
58
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
59
|
+
<span class="c"># pnpm</span>
|
|
60
|
+
pnpm add -g artshelf
|
|
61
|
+
|
|
62
|
+
<span class="c"># from source (needs git + corepack)</span>
|
|
63
|
+
git clone https://github.com/calvinnwq/artshelf.git
|
|
84
64
|
cd artshelf
|
|
85
65
|
corepack enable
|
|
86
66
|
pnpm install --frozen-lockfile
|
|
87
67
|
pnpm run build
|
|
88
68
|
npm link
|
|
69
|
+
|
|
70
|
+
<span class="c"># verify whichever you picked</span>
|
|
89
71
|
artshelf --version
|
|
90
72
|
artshelf doctor</code></pre>
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
</
|
|
95
|
-
<
|
|
96
|
-
</
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
73
|
+
<p>
|
|
74
|
+
<code>npm link</code> connects the local checkout to your global npm bin, so
|
|
75
|
+
later rebuilds update the <code>artshelf</code> command. To remove an npm
|
|
76
|
+
install, run <code>npm uninstall -g artshelf</code>; for a source install,
|
|
77
|
+
run <code>npm unlink -g artshelf</code>.
|
|
78
|
+
</p>
|
|
79
|
+
</section>
|
|
80
|
+
|
|
81
|
+
<section>
|
|
82
|
+
<h2>Updating a source install</h2>
|
|
83
|
+
<pre><code><span class="c"># pull the latest changes and rebuild</span>
|
|
84
|
+
cd artshelf
|
|
101
85
|
git pull
|
|
102
86
|
pnpm install --frozen-lockfile
|
|
103
87
|
pnpm run build
|
|
88
|
+
npm link</code></pre>
|
|
89
|
+
</section>
|
|
90
|
+
|
|
91
|
+
<section>
|
|
92
|
+
<h2>Recommended agent setup</h2>
|
|
93
|
+
<p>
|
|
94
|
+
Artshelf is agent-operated, so let your agent finish the job. The repo
|
|
95
|
+
ships <a href="https://github.com/calvinnwq/artshelf/blob/main/INSTALL.md">INSTALL.md</a>
|
|
96
|
+
with the full agent setup steps: install the portable skill together
|
|
97
|
+
with its bundled report renderer script, register existing ledgers, and
|
|
98
|
+
ask you first before creating any scheduled review job. Scheduled jobs
|
|
99
|
+
stay read-only; cleanup and purge execution always come back to you.
|
|
100
|
+
</p>
|
|
101
|
+
<p>Copy this one line into your coding agent:</p>
|
|
102
|
+
<pre><code>Follow the instructions in https://github.com/calvinnwq/artshelf/blob/main/INSTALL.md to set up Artshelf in this workspace.</code></pre>
|
|
103
|
+
<p>What the agent will follow, in full:</p>
|
|
104
|
+
<pre><code># Artshelf agent setup
|
|
105
|
+
|
|
106
|
+
These instructions are written for a coding agent. If you are a human, paste
|
|
107
|
+
this one line into your agent and let it do the rest:
|
|
108
|
+
|
|
109
|
+
> Follow the instructions in
|
|
110
|
+
> https://github.com/calvinnwq/artshelf/blob/main/INSTALL.md
|
|
111
|
+
> to set up Artshelf in this workspace.
|
|
112
|
+
|
|
113
|
+
## 1. Install the CLI
|
|
114
|
+
|
|
115
|
+
Check whether it is already installed before changing anything:
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
artshelf --version
|
|
119
|
+
artshelf doctor
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
If the command is missing, install it from npm and verify again:
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
npm install -g artshelf # or: pnpm add -g artshelf
|
|
126
|
+
artshelf --version
|
|
127
|
+
artshelf doctor
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Only use a source install when the user asks for one, and ask the user where
|
|
131
|
+
to clone the repo first instead of assuming a repo path:
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
git clone https://github.com/calvinnwq/artshelf.git "$ARTSHELF_REPO"
|
|
135
|
+
cd "$ARTSHELF_REPO"
|
|
136
|
+
corepack enable
|
|
137
|
+
pnpm install --frozen-lockfile
|
|
138
|
+
pnpm run build
|
|
104
139
|
npm link
|
|
105
140
|
artshelf --version
|
|
106
|
-
artshelf doctor
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
141
|
+
artshelf doctor
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## 2. Install the portable skill, including its script
|
|
145
|
+
|
|
146
|
+
Install, copy, or reference the portable skill so you register temporary
|
|
147
|
+
artifacts when you create them and check the shelf before handoffs. Copy the
|
|
148
|
+
whole `skills/artshelf` directory, not just SKILL.md: the skill ships with
|
|
149
|
+
`scripts/render-review-report.mjs` (the deterministic review report renderer)
|
|
150
|
+
plus its `schemas/` and `examples/`, and those must travel together.
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
# from the installed npm package
|
|
154
|
+
rm -rf <your-skills-dir>/artshelf
|
|
155
|
+
cp -R "$(npm root -g)/artshelf/skills/artshelf" <your-skills-dir>/
|
|
156
|
+
|
|
157
|
+
# or from a source checkout
|
|
158
|
+
rm -rf <your-skills-dir>/artshelf
|
|
159
|
+
cp -R "$ARTSHELF_REPO/skills/artshelf" <your-skills-dir>/
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Re-run the replacement copy after upgrading the package so the skill and
|
|
163
|
+
script stay in sync with the CLI.
|
|
164
|
+
|
|
165
|
+
## 3. Register existing ledgers
|
|
166
|
+
|
|
167
|
+
`artshelf put` registers its ledger automatically. Register any existing
|
|
168
|
+
project ledgers so `--all` commands can see them:
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
artshelf ledgers add --ledger <repo>/.artshelf/ledger.jsonl --name <project> --scope repo --json
|
|
172
|
+
artshelf ledgers list --json
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## 4. Scheduled review (ask the user first)
|
|
176
|
+
|
|
177
|
+
Ask the user whether they want a scheduled review job before creating one.
|
|
178
|
+
If they approve, schedule a read-only review job (daily works well) in your
|
|
179
|
+
host runtime that runs:
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
artshelf review --all --json
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
and reports what needs attention. Scheduled jobs are review and report only:
|
|
186
|
+
never schedule `artshelf cleanup --execute` or `artshelf trash purge
|
|
187
|
+
--execute`.
|
|
188
|
+
|
|
189
|
+
## 5. Verify and report
|
|
190
|
+
|
|
191
|
+
Finish by showing the user the output of:
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
artshelf doctor
|
|
195
|
+
artshelf ledgers list --json
|
|
196
|
+
```</code></pre>
|
|
197
|
+
<div class="callout" data-kind="note">
|
|
198
|
+
<span class="callout-label">Verify</span>
|
|
199
|
+
<p>However setup happens, finish with <code>artshelf --version</code> and <code>artshelf doctor</code>.</p>
|
|
200
|
+
</div>
|
|
201
|
+
</section>
|
|
202
|
+
</article>
|
|
203
|
+
<footer class="pager" id="pager"></footer>
|
|
204
|
+
</main>
|
|
205
|
+
|
|
206
|
+
<aside class="toc-col"><p class="toc-title">On this page</p><nav id="toc" aria-label="On this page"></nav></aside>
|
|
131
207
|
</div>
|
|
208
|
+
|
|
209
|
+
<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>
|
|
132
210
|
</body>
|
|
133
211
|
</html>
|
package/docs/quickstart.html
CHANGED
|
@@ -3,78 +3,55 @@
|
|
|
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="
|
|
6
|
+
<title>Quickstart · Artshelf</title>
|
|
7
|
+
<meta name="description" content="One artifact through the whole Artshelf lifecycle: register, review, dry-run, approve, verify.">
|
|
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="quickstart.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
|
-
<a href="agent-usage.html">Agent usage</a>
|
|
26
|
-
<a href="https://github.com/calvinnwq/artshelf/blob/main/skills/artshelf/SKILL.md">Agent skill</a>
|
|
27
|
-
</div>
|
|
28
|
-
<div class="nav-section">
|
|
29
|
-
<p class="nav-section-title">Reference</p>
|
|
30
|
-
<a href="reference.html">CLI reference</a>
|
|
31
|
-
<a href="https://github.com/calvinnwq/artshelf">GitHub</a>
|
|
32
|
-
</div>
|
|
33
|
-
</div>
|
|
34
|
-
</nav>
|
|
29
|
+
</div>
|
|
30
|
+
</header>
|
|
35
31
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
<div class="wrap">
|
|
39
|
-
<nav class="breadcrumbs" aria-label="Breadcrumbs"><a href="index.html">Docs</a><span>/</span><span>Quickstart</span></nav>
|
|
40
|
-
<div class="hero">
|
|
41
|
-
<div>
|
|
42
|
-
<p class="eyebrow">Approval-first workflows</p>
|
|
43
|
-
<h1>Register, review, approve — safely.</h1>
|
|
44
|
-
<p class="lede">
|
|
45
|
-
Artshelf centers on four workflows: register a temp artifact when it is created,
|
|
46
|
-
review everything safely before anything moves, approve cleanup safely from a
|
|
47
|
-
reviewed plan, and purge old trash only from a separate reviewed plan. Start with
|
|
48
|
-
explicit ledger and registry paths when testing.
|
|
49
|
-
</p>
|
|
50
|
-
</div>
|
|
51
|
-
<div class="terminal">
|
|
52
|
-
<div class="terminal-head"><span class="dot"></span><span class="dot"></span><span class="dot"></span><span>quickstart</span></div>
|
|
53
|
-
<pre><code>$ mkdir -p /tmp/artshelf-demo
|
|
54
|
-
$ echo "debug output" > /tmp/artshelf-demo/output.txt
|
|
55
|
-
$ artshelf put /tmp/artshelf-demo \
|
|
56
|
-
--reason "quickstart artifact" \
|
|
57
|
-
--ttl 1d \
|
|
58
|
-
--kind scratch \
|
|
59
|
-
--cleanup trash \
|
|
60
|
-
--ledger /tmp/artshelf-ledger.jsonl \
|
|
61
|
-
--registry /tmp/artshelf-registry.json</code></pre>
|
|
62
|
-
</div>
|
|
63
|
-
</div>
|
|
64
|
-
</div>
|
|
65
|
-
</header>
|
|
32
|
+
<div class="frame">
|
|
33
|
+
<nav id="sidebar" class="sidebar" aria-label="Documentation"></nav>
|
|
66
34
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
35
|
+
<main id="content" class="article-col">
|
|
36
|
+
<article>
|
|
37
|
+
<p class="kicker"><span class="n">03</span>Start · Quickstart</p>
|
|
38
|
+
<h1>Put one artifact on the shelf.</h1>
|
|
39
|
+
<p class="lede">
|
|
40
|
+
The whole loop in five minutes, using throwaway paths under <code>/tmp</code>.
|
|
41
|
+
You will register one artifact, review it, dry-run the cleanup, execute the
|
|
42
|
+
approved plan, and verify. Trash gets purged separately at the end.
|
|
43
|
+
</p>
|
|
44
|
+
|
|
45
|
+
<section>
|
|
46
|
+
<h2>1. Create something temporary</h2>
|
|
47
|
+
<pre><code><span class="c"># make a scratch artifact to practice on</span>
|
|
48
|
+
mkdir -p /tmp/artshelf-demo
|
|
73
49
|
echo "debug output" > /tmp/artshelf-demo/output.txt
|
|
74
50
|
|
|
51
|
+
<span class="c"># put it on the shelf: make this demo immediately due, then trash on approval</span>
|
|
75
52
|
artshelf put /tmp/artshelf-demo \
|
|
76
53
|
--reason "quickstart artifact" \
|
|
77
|
-
--ttl
|
|
54
|
+
--ttl 0m \
|
|
78
55
|
--kind scratch \
|
|
79
56
|
--cleanup trash \
|
|
80
57
|
--owner manual \
|
|
@@ -82,61 +59,83 @@ artshelf put /tmp/artshelf-demo \
|
|
|
82
59
|
--ledger /tmp/artshelf-ledger.jsonl \
|
|
83
60
|
--registry /tmp/artshelf-registry.json \
|
|
84
61
|
--json</code></pre>
|
|
85
|
-
|
|
86
|
-
|
|
62
|
+
<p>Note the <code>id</code> the command returns. You will quote it in handoffs and cleanup reports.</p>
|
|
63
|
+
</section>
|
|
87
64
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
<
|
|
65
|
+
<section>
|
|
66
|
+
<h2>2. Review without moving files</h2>
|
|
67
|
+
<div class="callout" data-kind="readonly">
|
|
68
|
+
<span class="callout-label">Non-destructive</span>
|
|
69
|
+
<p>These commands are safe for agents and cron jobs. They never move artifacts or trash entries; cleanup <code>--dry-run</code> may register a review plan.</p>
|
|
70
|
+
</div>
|
|
71
|
+
<pre><code><span class="c"># everything on the shelf</span>
|
|
72
|
+
artshelf list --ledger /tmp/artshelf-ledger.jsonl
|
|
73
|
+
|
|
74
|
+
<span class="c"># quick counts: active, due, trashed</span>
|
|
92
75
|
artshelf status --ledger /tmp/artshelf-ledger.jsonl
|
|
76
|
+
|
|
77
|
+
<span class="c"># check the ledger file itself is healthy</span>
|
|
93
78
|
artshelf validate --ledger /tmp/artshelf-ledger.jsonl --json
|
|
79
|
+
|
|
80
|
+
<span class="c"># which records are due, kept, or missing</span>
|
|
94
81
|
artshelf due --ledger /tmp/artshelf-ledger.jsonl --json
|
|
82
|
+
|
|
83
|
+
<span class="c"># preview cleanup and get a plan id (still moves nothing)</span>
|
|
95
84
|
artshelf cleanup --dry-run --ledger /tmp/artshelf-ledger.jsonl --json</code></pre>
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
</section>
|
|
85
|
+
<p>
|
|
86
|
+
This demo uses <code>--ttl 0m</code>, so the dry-run writes a plan and prints
|
|
87
|
+
the <code>planId</code> a human can approve. When nothing is ready, the
|
|
88
|
+
dry-run reports <code>not-created</code>.
|
|
89
|
+
</p>
|
|
90
|
+
</section>
|
|
103
91
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
92
|
+
<section>
|
|
93
|
+
<h2>3. Execute only an approved plan</h2>
|
|
94
|
+
<p>Copy the <code>planId</code> from the dry-run output in step 2.</p>
|
|
95
|
+
<pre><code><span class="c"># run only the plan that was reviewed</span>
|
|
96
|
+
artshelf cleanup --execute \
|
|
107
97
|
--plan-id plan_20260601_120000_ab12 \
|
|
108
98
|
--ledger /tmp/artshelf-ledger.jsonl</code></pre>
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
approves the reviewed plan id and ledger that produced it. After execution, Artshelf writes
|
|
112
|
-
a receipt and updates touched records so handled artifacts stop appearing in future due checks.
|
|
113
|
-
Artshelf also records generated plans and receipts in the ledger as Artshelf-owned
|
|
114
|
-
artifacts.
|
|
115
|
-
</div>
|
|
116
|
-
</section>
|
|
117
|
-
|
|
118
|
-
<section>
|
|
119
|
-
<h2>4. Purge old trashed records explicitly</h2>
|
|
99
|
+
<div class="callout" data-kind="boundary">
|
|
100
|
+
<span class="callout-label">Hard boundary</span>
|
|
120
101
|
<p>
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
reviewed trash purge plan:
|
|
102
|
+
Execute is intentionally separate. Approval names the exact ledger path and
|
|
103
|
+
reviewed plan id. No global execute path exists.
|
|
124
104
|
</p>
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
105
|
+
</div>
|
|
106
|
+
</section>
|
|
107
|
+
|
|
108
|
+
<section>
|
|
109
|
+
<h2>4. Verify quiet</h2>
|
|
110
|
+
<p>After cleanup, run another read-only review.</p>
|
|
111
|
+
<pre><code><span class="c"># confirm nothing still needs attention</span>
|
|
112
|
+
artshelf review --ledger /tmp/artshelf-ledger.jsonl --json
|
|
113
|
+
|
|
114
|
+
<span class="c"># see what cleanup moved into trash</span>
|
|
115
|
+
artshelf trash list --ledger /tmp/artshelf-ledger.jsonl --json</code></pre>
|
|
116
|
+
</section>
|
|
117
|
+
|
|
118
|
+
<section>
|
|
119
|
+
<h2>5. Purge trash separately</h2>
|
|
120
|
+
<p>
|
|
121
|
+
Cleanup with <code>cleanup=trash</code> moves files into Artshelf trash.
|
|
122
|
+
Physical deletion needs a separate reviewed purge plan.
|
|
123
|
+
</p>
|
|
124
|
+
<pre><code><span class="c"># preview which trashed files are old enough to purge</span>
|
|
125
|
+
artshelf trash purge --older-than 0m --dry-run --ledger /tmp/artshelf-ledger.jsonl --json</code></pre>
|
|
126
|
+
<p>Then execute with the purge <code>planId</code> the dry-run reported.</p>
|
|
127
|
+
<pre><code><span class="c"># delete for real, but only with the reviewed purge plan id</span>
|
|
128
|
+
artshelf trash purge --execute \
|
|
133
129
|
--plan-id purge_20260601_120000_ab12 \
|
|
134
130
|
--ledger /tmp/artshelf-ledger.jsonl</code></pre>
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
131
|
+
</section>
|
|
132
|
+
</article>
|
|
133
|
+
<footer class="pager" id="pager"></footer>
|
|
134
|
+
</main>
|
|
135
|
+
|
|
136
|
+
<aside class="toc-col"><p class="toc-title">On this page</p><nav id="toc" aria-label="On this page"></nav></aside>
|
|
140
137
|
</div>
|
|
138
|
+
|
|
139
|
+
<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>
|
|
141
140
|
</body>
|
|
142
141
|
</html>
|