artshelf 0.3.0

package/dist/src/registry.js

@@ -0,0 +1,137 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { now, toIso } from "./time.js";
+export function defaultRegistryPath() {
+    return process.env.ARTSHELF_REGISTRY ?? process.env.SHELF_REGISTRY ?? join(homedir(), ".shelf", "ledgers.json");
+}
+export function normalizeRegistryPath(path) {
+    return resolve(path ?? defaultRegistryPath());
+}
+export function readRegistry(registryPath = normalizeRegistryPath()) {
+    if (!existsSync(registryPath))
+        return { version: 1, ledgers: [] };
+    const parsed = JSON.parse(readFileSync(registryPath, "utf8"));
+    if (parsed.version !== 1 || !Array.isArray(parsed.ledgers)) {
+        throw new Error(`Invalid Artshelf ledger registry: ${registryPath}`);
+    }
+    return {
+        version: 1,
+        ledgers: parsed.ledgers.map((entry) => normalizeEntry(entry))
+    };
+}
+export function listRegisteredLedgers(registryPath = normalizeRegistryPath()) {
+    return readRegistry(registryPath).ledgers;
+}
+export function registerLedger(input) {
+    const registryPath = normalizeRegistryPath(input.registryPath);
+    const ledgerPath = resolve(input.ledgerPath);
+    return withRegistryLock(registryPath, () => {
+        const registry = readRegistry(registryPath);
+        const timestamp = toIso(now());
+        const existingIndex = registry.ledgers.findIndex((entry) => entry.path === ledgerPath);
+        const existing = existingIndex >= 0 ? registry.ledgers[existingIndex] : undefined;
+        const name = normalizeName(input.name);
+        const entry = {
+            name: name ?? existing?.name ?? inferLedgerName(ledgerPath),
+            path: ledgerPath,
+            scope: input.scope ? assertScope(input.scope) : existing?.scope ?? inferLedgerScope(ledgerPath),
+            createdAt: existing?.createdAt ?? timestamp,
+            updatedAt: timestamp
+        };
+        if (existingIndex >= 0) {
+            registry.ledgers[existingIndex] = entry;
+        }
+        else {
+            registry.ledgers.push(entry);
+        }
+        registry.ledgers.sort((left, right) => left.name.localeCompare(right.name) || left.path.localeCompare(right.path));
+        writeRegistry(registryPath, registry);
+        return entry;
+    });
+}
+function writeRegistry(registryPath, registry) {
+    mkdirSync(dirname(registryPath), { recursive: true });
+    const tmpPath = `${registryPath}.${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}.tmp`;
+    writeFileSync(tmpPath, `${JSON.stringify(registry, null, 2)}\n`);
+    renameSync(tmpPath, registryPath);
+}
+function withRegistryLock(registryPath, fn) {
+    mkdirSync(dirname(registryPath), { recursive: true });
+    const lockPath = `${registryPath}.lock`;
+    const deadline = Date.now() + 5000;
+    const staleAfterMs = 30_000;
+    while (true) {
+        try {
+            mkdirSync(lockPath);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            if (isStaleLock(lockPath, staleAfterMs)) {
+                rmSync(lockPath, { recursive: true, force: true });
+                continue;
+            }
+            if (Date.now() > deadline)
+                throw new Error(`Timed out waiting for Artshelf ledger registry lock: ${registryPath}`);
+            sleep(25);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        rmSync(lockPath, { recursive: true, force: true });
+    }
+}
+function sleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function isStaleLock(lockPath, staleAfterMs) {
+    try {
+        return Date.now() - statSync(lockPath).mtimeMs > staleAfterMs;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function normalizeEntry(entry) {
+    if (!entry.name || !entry.path || !entry.scope || !entry.createdAt || !entry.updatedAt) {
+        throw new Error("Invalid Artshelf ledger registry entry");
+    }
+    return {
+        name: entry.name,
+        path: resolve(entry.path),
+        scope: assertScope(entry.scope),
+        createdAt: entry.createdAt,
+        updatedAt: entry.updatedAt
+    };
+}
+function normalizeName(name) {
+    const trimmed = name?.trim();
+    return trimmed ? trimmed : undefined;
+}
+function inferLedgerName(ledgerPath) {
+    const normalized = resolve(ledgerPath);
+    if (normalized === join(homedir(), ".shelf", "ledger.jsonl"))
+        return "global";
+    if (basename(dirname(normalized)) === ".shelf")
+        return basename(dirname(dirname(normalized))) || "repo";
+    return basename(dirname(normalized)) || "ledger";
+}
+function inferLedgerScope(ledgerPath) {
+    const normalized = resolve(ledgerPath);
+    if (normalized.startsWith(join(homedir(), ".shelf")))
+        return "user";
+    if (basename(dirname(normalized)) === ".shelf")
+        return "repo";
+    return "other";
+}
+function assertScope(scope) {
+    if (scope === "repo" || scope === "user" || scope === "other")
+        return scope;
+    throw new Error(`Unknown ledger scope: ${scope}`);
+}

package/dist/src/time.js

@@ -0,0 +1,71 @@
+const TTL_PATTERN = /^(\d+)([dhm])$/;
+const TTL_MULTIPLIERS = {
+    m: 60 * 1000,
+    h: 60 * 60 * 1000,
+    d: 24 * 60 * 60 * 1000
+};
+export function now() {
+    const forced = process.env.ARTSHELF_NOW ?? process.env.SHELF_NOW;
+    if (!forced)
+        return new Date();
+    const parsed = new Date(forced);
+    if (Number.isNaN(parsed.getTime())) {
+        throw new Error(`Invalid ARTSHELF_NOW value: ${forced}`);
+    }
+    return parsed;
+}
+export function toIso(date) {
+    return date.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+export function addTtl(start, ttl) {
+    const match = TTL_PATTERN.exec(ttl);
+    if (!match) {
+        throw new Error("TTL must look like 30m, 12h, or 7d");
+    }
+    const amount = Number(match[1]);
+    const unit = match[2];
+    if (!unit || !(unit in TTL_MULTIPLIERS)) {
+        throw new Error("TTL must look like 30m, 12h, or 7d");
+    }
+    return new Date(start.getTime() + amount * TTL_MULTIPLIERS[unit]);
+}
+export function ttlToMs(ttl) {
+    const match = TTL_PATTERN.exec(ttl);
+    if (!match) {
+        throw new Error("TTL must look like 30m, 12h, or 7d");
+    }
+    const amount = Number(match[1]);
+    const unit = match[2];
+    if (!unit || !(unit in TTL_MULTIPLIERS)) {
+        throw new Error("TTL must look like 30m, 12h, or 7d");
+    }
+    return amount * TTL_MULTIPLIERS[unit];
+}
+export function ageOf(nowDate, pastIso) {
+    const past = new Date(pastIso);
+    if (Number.isNaN(past.getTime())) {
+        throw new Error(`Invalid timestamp: ${pastIso}`);
+    }
+    const ageMs = Math.max(0, nowDate.getTime() - past.getTime());
+    const totalMinutes = Math.floor(ageMs / (60 * 1000));
+    if (totalMinutes === 0)
+        return "0m";
+    const days = Math.floor(totalMinutes / (24 * 60));
+    const hours = Math.floor(totalMinutes % (24 * 60) / 60);
+    const minutes = totalMinutes % 60;
+    const parts = [];
+    if (days > 0)
+        parts.push(`${days}d`);
+    if (hours > 0)
+        parts.push(`${hours}h`);
+    if (minutes > 0 || parts.length === 0)
+        parts.push(`${minutes}m`);
+    return parts.join(" ");
+}
+export function assertIsoDate(value, label) {
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) {
+        throw new Error(`${label} must be a valid date`);
+    }
+    return toIso(parsed);
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/docs/.nojekyll

@@ -0,0 +1 @@
+

package/docs/agent-usage.html

@@ -0,0 +1,325 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Artshelf Agent Usage</title>
+    <meta name="description" content="How agents should use Artshelf safely.">
+    <link rel="stylesheet" href="site.css">
+    <script src="theme.js" defer></script>
+  </head>
+  <body>
+    <div class="docs-shell">
+      <nav class="global-nav" aria-label="Documentation">
+        <a class="site-mark" href="index.html"><strong>Artshelf</strong><span>Artifact retention CLI</span></a>
+        <button class="theme-toggle" type="button" data-theme-toggle aria-label="Toggle color theme" aria-pressed="false">Dark</button>
+        <div class="nav-scroll" aria-label="Documentation sections">
+        <div class="nav-section">
+          <p class="nav-section-title">Start</p>
+          <a href="index.html">Overview</a>
+          <a href="install.html">Install</a>
+          <a href="quickstart.html">Quickstart</a>
+        </div>
+        <div class="nav-section">
+          <p class="nav-section-title">Agents</p>
+          <a href="agent-usage.html" aria-current="page">Agent usage</a>
+          <a href="https://github.com/calvinnwq/artshelf/blob/main/skills/artshelf/SKILL.md">Agent skill</a>
+        </div>
+        <div class="nav-section">
+          <p class="nav-section-title">Reference</p>
+          <a href="reference.html">CLI reference</a>
+          <a href="https://github.com/calvinnwq/artshelf">GitHub</a>
+        </div>
+        </div>
+      </nav>
+
+      <div class="docs-content">
+        <header class="page-top">
+          <div class="wrap">
+            <nav class="breadcrumbs" aria-label="Breadcrumbs"><a href="index.html">Docs</a><span>/</span><span>Agent usage</span></nav>
+            <div class="hero">
+              <div>
+                <p class="eyebrow">For local agents and automation</p>
+                <h1>Register artifacts while intent is fresh.</h1>
+                <p class="lede">
+                  Agents should use Artshelf when temporary files need accountability, restart
+                  context, or later human review. Source files and cheap build outputs stay out.
+                </p>
+              </div>
+              <div class="terminal">
+                <div class="terminal-head"><span class="dot"></span><span class="dot"></span><span class="dot"></span><span>agent contract</span></div>
+                <pre><code>$ artshelf put &lt;path&gt; \
+  --reason "&lt;why this exists&gt;" \
+  --ttl 3d \
+  --kind run-artifact \
+  --cleanup review \
+  --owner agent \
+  --label &lt;project&gt; \
+  --json</code></pre>
+              </div>
+            </div>
+          </div>
+        </header>
+
+        <main class="wrap">
+          <article>
+            <section>
+              <h2>Registration Trigger</h2>
+              <p>
+                Treat Artshelf as a finalization check, not an optional cleanup habit. Before an agent reports a task as done,
+                it should check whether the task created, copied,
+                exported, quarantined, backed up, or preserved any non-source file or directory
+                that may outlive the current command.
+              </p>
+              <p>
+                Register eligible artifacts immediately. If an eligible artifact is skipped,
+                state the reason: source-controlled, regeneratable, secret-bearing, already
+                tracked by another durable ledger, or explicitly not retained by request.
+              </p>
+            </section>
+
+            <section>
+              <h2>Install Behavior</h2>
+              <p>
+                If <code>artshelf</code> is not installed, prefer the package-manager install
+                when available and verify the CLI before registering artifacts.
+              </p>
+              <pre><code>npm install -g artshelf
+artshelf --version
+artshelf doctor</code></pre>
+              <pre><code>pnpm add -g artshelf
+artshelf --version
+artshelf doctor</code></pre>
+              <p>
+                For source installs, ask where the user wants the repo cloned before setup.
+                Use the local clone, build, and <code>npm link</code> path. Do not create a
+                custom shim.
+              </p>
+              <pre><code>git clone https://github.com/calvinnwq/artshelf.git "$ARTSHELF_REPO"
+cd "$ARTSHELF_REPO"
+corepack enable
+pnpm install --frozen-lockfile
+pnpm run build
+npm link
+artshelf --version
+artshelf doctor</code></pre>
+            </section>
+
+            <section>
+              <h2>Use Artshelf For</h2>
+              <div class="grid">
+                <div class="card"><h3>Backups</h3><p>Rollback copies, pre-edit snapshots, migration backups, and quarantine folders.</p></div>
+                <div class="card"><h3>Evidence</h3><p>Debug output directories, generated reports, logs, and live-smoke artifacts.</p></div>
+                <div class="card"><h3>Long runs</h3><p>Workflow artifacts a future agent might need to resume, review, or clean up.</p></div>
+              </div>
+            </section>
+
+            <section>
+              <h2>Skip Artshelf For</h2>
+              <ul>
+                <li>Source files that belong in git.</li>
+                <li>Build outputs and dependency caches that can be regenerated cheaply.</li>
+                <li>Secrets, credential dumps, or private tokens.</li>
+                <li>Artifacts already owned by a more specific durable workflow ledger.</li>
+              </ul>
+            </section>
+
+            <section>
+              <h2>Idempotent Lookup</h2>
+              <p>
+                Integrations should query the ledger before creating another record for the same
+                artifact. <code>find</code> and <code>get</code> are read-only; they never move,
+                resolve, or delete files.
+              </p>
+              <pre><code>artshelf find --path &lt;path&gt; --owner &lt;agent-or-runtime&gt; --label &lt;task-or-run-id&gt; --json
+artshelf get &lt;id&gt; --json</code></pre>
+              <p>
+                <code>find</code> requires at least one selector. Multiple labels are an all-label
+                match. If it returns a record, reuse that Artshelf id; otherwise call
+                <code>artshelf put</code> and record the new id.
+              </p>
+            </section>
+
+            <section>
+              <h2>Ledger Registry</h2>
+              <p>
+                Artshelf keeps a user-level registry at `~/.shelf/ledgers.json` so one CLI can
+                review all known ledgers without moving project records into one global file.
+                <code>put</code> registers the ledger it writes to.
+              </p>
+              <pre><code>artshelf ledgers add --ledger &lt;repo&gt;/.shelf/ledger.jsonl --name &lt;project&gt; --scope repo
+artshelf ledgers list --json
+artshelf review --all --json
+artshelf status --all --json
+artshelf find --all --owner &lt;agent-or-runtime&gt; --json
+artshelf trash list --all --json</code></pre>
+              <p>
+                <code>artshelf ledgers list --json</code> validates each registered ledger and reports
+                ok/missing/invalid status with entry and warning/error counts, so agents can detect
+                stale registry entries without a separate validate pass; add <code>--plain</code> for a
+                fast listing that skips validation. <code>artshelf review --all --json</code> returns an
+                aggregate triage summary and the next safe action next to the per-ledger detail.
+              </p>
+              <p>Use global cleanup dry-run when you want Artshelf to write cleanup plans for registered ledgers with cleanup entries, without moving files.</p>
+              <pre><code>artshelf cleanup --dry-run --all --json</code></pre>
+              <div class="note">
+                <code>--all</code> is for discovery and review. Cleanup execution remains
+                ledger-specific and requires a reviewed plan id for that ledger.
+              </div>
+              <p>If the executable cleanup entries have not changed, dry-run reuses the existing plan id and refreshes the same plan file instead of creating duplicate plans.</p>
+            </section>
+
+            <section>
+              <h2>Daily Review Workflow</h2>
+              <p>
+                Use this flow when a scheduled review, recurring task, or user request reports
+                Artshelf cleanup attention.
+              </p>
+              <ol>
+                <li>Register artifacts early during work, or state why an eligible artifact was skipped.</li>
+                <li>Review state with read-only commands first: <code>artshelf ledgers list --json</code>, <code>artshelf review --all --json</code>, and <code>artshelf trash list --all --json</code>; for old trash on a selected ledger, run <code>artshelf trash purge --older-than 7d --dry-run --ledger &lt;ledger-path&gt; --json</code>.</li>
+                <li>Present a decision packet instead of raw counts. Include registry health, affected ledgers, due/manual-review/missing-path counts, executable entries, skipped entries, refused entries, trashed record counts and ages, purge dry-run plan ids/skipped entries, and the next safe action.</li>
+                <li>Classify each candidate as <code>trash-safe</code>, <code>needs-human-review</code>, <code>resolve-candidate</code>, or <code>registry-problem</code>.</li>
+                <li>If cleanup execution is appropriate, generate or reuse a dry-run plan, then ask for explicit approval naming the ledger path and reviewed plan id.</li>
+                <li>For trashed records, require a separate reviewed purge plan before physical deletion.</li>
+                <li>After approved cleanup execute, trash purge, or resolve, verify quiet with <code>artshelf review --all --json</code>, plus <code>artshelf trash list --ledger &lt;ledger-path&gt; --json</code> and purge receipt evidence after purge, or explain what remains.</li>
+              </ol>
+              <pre><code>artshelf trash list --ledger &lt;ledger-path&gt;
+artshelf trash purge --older-than 7d --dry-run --ledger &lt;ledger-path&gt; --json
+artshelf trash purge --execute --plan-id &lt;purge-plan-id&gt; --ledger &lt;ledger-path&gt; --json</code></pre>
+              <pre><code>approve artshelf cleanup ledger &lt;ledger-path&gt; plan &lt;plan-id&gt;
+approve artshelf trash purge ledger &lt;ledger-path&gt; plan &lt;purge-plan-id&gt;</code></pre>
+              <div class="note">
+                Never execute from a read-only preview id. Never generate a fresh plan and execute
+                it in the same step. <code>trash</code> moves artifacts into Artshelf trash; physical
+                delete requires a separate reviewed trash purge plan.
+              </div>
+            </section>
+
+            <section>
+              <h2>Report The ID</h2>
+              <pre><code>Artshelf artifacts:
+- shf_20260601_182800_ab12: /tmp/parser-output, debug evidence for issue-123,
+  retain until 2026-06-04, cleanup=review</code></pre>
+              <p>
+                Put the id in handoffs, PR comments, issue comments, memory, or task run
+                summaries when the artifact matters for restart.
+              </p>
+              <p>
+                If there are no eligible artifacts, say nothing. If eligible artifacts were
+                skipped instead of registered, include the brief skip reason from the
+                completion checklist.
+              </p>
+            </section>
+
+            <section>
+              <h2>Cleanup Boundary</h2>
+              <pre><code>artshelf validate --json
+artshelf validate --all --json
+artshelf due --json
+artshelf due --all --json
+artshelf review --all --json</code></pre>
+              <p>Cleanup dry-run is safe to run. It writes plan files for later review only when there are executable cleanup entries; no-op dry-runs report <code>not-created</code> and write no plan file. Matching dry-runs reuse the existing plan id and refresh the plan timestamp.</p>
+              <pre><code>artshelf cleanup --dry-run --json
+artshelf cleanup --dry-run --all --json</code></pre>
+              <pre><code>artshelf cleanup --execute --plan-id &lt;id&gt;</code></pre>
+              <pre><code>artshelf trash list --ledger &lt;ledger-path&gt; --json
+artshelf trash purge --older-than 7d --dry-run --ledger &lt;ledger-path&gt; --json
+artshelf trash purge --execute --plan-id &lt;purge-plan-id&gt; --ledger &lt;ledger-path&gt; --json</code></pre>
+              <div class="note">
+                Execution is approval-only: no daemon, no auto-execute, no global execute, and no
+                fresh-plan-then-execute shortcut. Cleanup execution needs explicit human approval
+                for the reviewed plan id. Trash list and purge dry-run are review steps; trash
+                purge execution needs separate approval naming the ledger and reviewed purge plan
+                id. Execution writes a receipt and updates touched ledger records to `trashed`,
+                `review-required`, or `cleanup-refused`. <code>cleanup=delete</code> stays refused
+                instead of silently deleting files; physical deletion requires a separate reviewed
+                trash purge plan. Artshelf records generated plans and receipts as `owner=artshelf`
+                artifacts.
+              </div>
+              <p>
+                Agents may mark a ledger record manually resolved when the user confirms the
+                artifact was inspected, is already missing, or is no longer needed.
+              </p>
+              <pre><code>artshelf resolve &lt;id&gt; --status resolved --reason &lt;text&gt;</code></pre>
+              <p>
+                Use a specific reason. <code>resolve</code> only updates the ledger; it does not
+                move or delete files. Resolved records stop reappearing in future due and
+                dry-run cleanup output while remaining visible through
+                <code>artshelf list --status resolved</code>.
+              </p>
+            </section>
+
+            <section>
+              <h2>Scheduled Review</h2>
+              <p>
+                Agents may schedule routine Artshelf checks for stale artifacts through their host
+                runtime, such as an agent cron, CI job, or recurring task. Keep scheduled jobs
+                non-destructive.
+              </p>
+              <pre><code>artshelf validate --json
+artshelf validate --all --json
+artshelf due --json
+artshelf due --all --json
+artshelf review --all --json</code></pre>
+              <p>
+                Read-only health and dashboard checks are also safe to schedule. Run
+                <code>artshelf review --all --json</code> for aggregate triage (<code>summary</code>
+                and <code>nextAction</code>), <code>artshelf doctor --json</code> to catch a broken
+                or stale registry before relying on cleanup planning, and
+                <code>artshelf status --all --json</code> for a compact cron summary.
+              </p>
+              <pre><code>artshelf doctor --json
+artshelf status --all --json</code></pre>
+              <p>
+                Scheduled cleanup and trash purge dry-runs may write plan files for later review
+                when entries exist, but must not move or delete files. Matching cleanup dry-runs
+                reuse the existing plan id and refresh the plan timestamp.
+              </p>
+              <pre><code>artshelf cleanup --dry-run --json
+artshelf cleanup --dry-run --all --json
+artshelf trash list --ledger &lt;ledger-path&gt; --json
+artshelf trash list --all --json
+artshelf trash purge --older-than 7d --dry-run --ledger &lt;ledger-path&gt; --json</code></pre>
+              <p>
+                Reports should include the ledger path, due/manual-review/missing-path counts,
+                cleanup dry-run plan id, executable entries, skipped entries, and refused entries.
+                Trash reports may use <code>artshelf trash list --all --json</code> to discover
+                trashed records across registered ledgers, then include trashed record counts
+                and target ages. Run purge dry-runs only for an explicit ledger and report
+                any plan id, matching entries, and skipped entries.
+                Stay quiet when nothing needs attention unless a regular summary was requested.
+              </p>
+              <div class="note">
+                Use explicit ledger paths for scheduled checks. Do not scan arbitrary filesystem
+                locations for ledgers unless the user opted into that discovery scope. Never
+                schedule cleanup execution or trash purge execution; scheduled jobs may only
+                dry-run and report plans for later human review.
+              </div>
+            </section>
+
+            <section>
+              <h2>Completion Checklist</h2>
+              <ol>
+                <li>Did you create, copy, export, quarantine, back up, or preserve any non-source file or directory?</li>
+                <li>Will any of those paths outlive this command?</li>
+                <li>If yes, did you register them with Artshelf or state why Artshelf is not appropriate?</li>
+              </ol>
+              <div class="note">Do not call work done while known eligible artifacts are neither registered nor explicitly skipped.</div>
+            </section>
+
+            <section>
+              <h2>Portable Skill</h2>
+              <p>
+                The repo ships a portable skill at
+                <a href="https://github.com/calvinnwq/artshelf/blob/main/skills/artshelf/SKILL.md">skills/artshelf/SKILL.md</a>.
+                Agents that support local skills can copy or reference it directly.
+              </p>
+            </section>
+          </article>
+        </main>
+        <footer class="site-footer"><div class="wrap">Artshelf docs · <a href="reference.html">Next: CLI reference</a></div></footer>
+      </div>
+    </div>
+  </body>
+</html>