@hraness/sponge 0.2.6 → 0.3.1

package/dist/src/cli/commands.js

@@ -0,0 +1,795 @@
+import { join, isAbsolute } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { readConnections } from './config.js';
+import { pdfSource } from '../pdf/index.js';
+import { articleSource, mediaSource } from '../app/source.js';
+import { defaultCapturePins, inspectCaptureRuntime, provisionCapture, captureSetupPlan } from '../acquisition/index.js';
+import { queueAction } from './queue.js';
+import { portabilityAction } from './portability.js';
+import { restoreLibrary } from '../portability/backup.js';
+import { workerAction, serveWorker, hasDueAcquisition, workerDoctor } from './worker.js';
+import { nativeSetupPlan, provisionNative, inspectNative } from '../models/runtime.js';
+import { nativeDownloadAuthGuidance } from '../models/download.js';
+import { drainIndexQueue } from '../indexing/runner.js';
+import { indexAction, overviewText } from './indexing.js';
+import { pruneText } from '../indexing/prune-run.js';
+import { importAction, jungleAction, jungleText } from './import.js';
+import { digestText, reviewFromSpec, reviewSpec } from './digest.js';
+import { connectEndpoint } from '../digest/endpoint.js';
+import { createDigest } from '../digest/pipeline.js';
+import { createQueryEmbedder, createTextEmbedder } from '../search/query.js';
+import { runtimeGcAction, runtimeGcText, setupRuntimeGc } from './runtimes.js';
+import { drainLibrary } from '../worker/basic.js';
+import { minAge, publishSite } from '../publish/index.js';
+import { SpongeError, codeOf, publicCode, exitFor, isSpongeCode } from '../errors.js';
+const abs = (v) => typeof v === 'string' && isAbsolute(v);
+const media = { language: 'value', 'force-local': 'boolean', 'allow-private-network': 'boolean' };
+const lines = (items) => items.map((item) => `${item.itemId}\t${item.title}`);
+/** A required capture runtime, as the categorical code of its inspection failure. */
+async function captureRuntime(c) {
+    try {
+        return await inspectCaptureRuntime(c.captureRoot, defaultCapturePins);
+    }
+    catch (error) {
+        throw new SpongeError(publicCode(error, 'runtime-missing'), { cause: error });
+    }
+}
+/** The failure of a job that did not run here: its state, or its recorded reason. */
+function jobFailure(store, jobId) {
+    const job = store.queue.list().find((j) => j.id === jobId), reason = job?.reason;
+    return new SpongeError(job?.state === 'cancelled'
+        ? 'cancelled'
+        : job?.state === 'cleanup-pending'
+            ? 'cleanup-required'
+            : job?.state === 'running'
+                ? 'owner-busy'
+                : isSpongeCode(reason)
+                    ? reason
+                    : 'unclassified');
+}
+const resolveConnection = (connections) => (realm) => {
+    if (realm === 'public')
+        return undefined;
+    const connection = connections.find((c) => c.realm === realm);
+    if (!connection)
+        throw new SpongeError('repair-auth');
+    return connection.capture;
+};
+/** add/refresh with --wait and run --drain: drain acquisition (one job when given), then queued indexes for run. */
+async function drain(c, jobId, connections) {
+    const { store, args, signal } = c;
+    connections ??= await readConnections(store.root);
+    if (jobId) {
+        const job = store.queue.list().find((j) => j.id === jobId);
+        if (job && job.state !== 'queued')
+            throw jobFailure(store, jobId);
+    }
+    const runtime = await captureRuntime(c);
+    let asrRuntime;
+    try {
+        asrRuntime = await inspectNative('asr', c.nativeRoot, c.version);
+    }
+    catch (error) {
+        if (!['runtime-missing', 'unsupported'].includes(publicCode(error, 'integrity')))
+            throw error;
+    }
+    const results = await drainLibrary(store, {
+        asrRuntime,
+        language: args.flags.language,
+        forceLocal: args.flags['force-local'] === true,
+        runtime,
+        jobId,
+        signal,
+        allowPrivateNetwork: args.flags['allow-private-network'] === true,
+        resolveConnection: resolveConnection(connections),
+    });
+    if (jobId && !results.length && !signal.aborted)
+        throw jobFailure(store, jobId);
+    let indexResults = [];
+    if (args.command === 'run' &&
+        !signal.aborted &&
+        store.queue.list().some((job) => job.operation === 'index' && job.state === 'queued')) {
+        const embedding = await inspectNative('embedding', c.nativeRoot, c.version);
+        indexResults = await drainIndexQueue(store, { runtime: embedding, signal });
+        const indexFailed = indexResults.find((result) => !result.ok);
+        if (indexFailed && !indexFailed.ok) {
+            process.stderr.write(JSON.stringify(indexFailed) + '\n');
+            return exitFor(indexFailed.code);
+        }
+    }
+    const failed = results.find((result) => !result.ok);
+    if (failed && !failed.ok) {
+        process.stderr.write(JSON.stringify(failed) + '\n');
+        return exitFor(failed.code);
+    }
+    if (signal.aborted)
+        return 130;
+    c.emit({ results, indexResults }, results.map((result) => (result.ok ? `${result.itemId}\t${result.status}` : '')).join('\n') || 'Queue empty');
+    return results.some((result) => result.ok && result.status === 'partial') ? 3 : 0;
+}
+export const commands = [
+    {
+        name: 'init',
+        summary: 'Create a private library',
+        usage: [['init', 'Create a private library']],
+        positional: 0,
+        flags: {},
+        library: 'create',
+        handler: (c) => {
+            c.emit({ library: c.store.root }, `Library: ${c.store.root}`);
+            return 0;
+        },
+    },
+    {
+        name: 'setup',
+        summary: 'Download one pinned runtime',
+        usage: [['setup --capture|--asr|--embedding', 'Download one pinned runtime']],
+        positional: 0,
+        flags: { capture: 'boolean', asr: 'boolean', embedding: 'boolean' },
+        library: 'open',
+        check: (_, f) => [f.capture, f.asr, f.embedding].filter(Boolean).length === 1,
+        handler: async (c) => {
+            if (!c.args.flags.capture) {
+                const kind = c.args.flags.asr ? 'asr' : 'embedding', plan = await nativeSetupPlan(kind, c.version);
+                process.stderr.write(JSON.stringify({ setup: kind, ...plan }) + '\n');
+                try {
+                    await provisionNative(kind, c.nativeRoot, c.version, c.signal);
+                }
+                catch (error) {
+                    if (codeOf(error) === 'repair-auth' && !c.args.json)
+                        process.stderr.write(nativeDownloadAuthGuidance + '\n');
+                    throw error;
+                }
+                const gc = await setupRuntimeGc(c.store, c.version);
+                c.emit({ [kind]: 'ready', gc });
+                return 0;
+            }
+            const plan = captureSetupPlan(defaultCapturePins);
+            process.stderr.write(`Capture setup: ${plan.downloadBytes} pinned artifact bytes, plus frozen dependency downloads. Temporary installation limit: ${plan.stagingBudgetBytes} bytes; retained runtime limit: ${plan.installationBudgetBytes} bytes; dependency installation deadline: ${plan.installationDeadlineMs / 60000} minutes. ${plan.requiredFreeBytes} free bytes required.\n`);
+            await provisionCapture({
+                runtimeRoot: join(c.store.root, 'runtime', 'capture'),
+                pins: defaultCapturePins,
+                signal: c.signal,
+            });
+            const gc = await setupRuntimeGc(c.store, c.version);
+            c.emit({ capture: 'ready', gc }, 'skipped' in gc ? `Capture ready\nRuntime GC skipped: ${gc.skipped}` : `Capture ready\n${runtimeGcText(gc)}`);
+            return 0;
+        },
+    },
+    {
+        name: 'add',
+        summary: 'Save an article, PDF or media source',
+        usage: [['add URL_OR_PDF [--kind article|pdf|media] [--connection ID] [--wait]', '']],
+        positional: 1,
+        flags: { connection: 'value', kind: 'value', wait: 'boolean', ...media },
+        library: 'open',
+        handler: async (c) => {
+            const { store, args } = c, connections = await readConnections(store.root);
+            const connection = args.flags.connection ? connections.find((x) => x.id === args.flags.connection) : undefined;
+            if (args.flags.connection && !connection)
+                throw new SpongeError('invalid-input');
+            const input = args.positional[0], kind = (args.flags.kind ??
+                (/\.pdf(?:[?#]|$)/i.test(input) || input.startsWith('file:') ? 'pdf' : 'article'));
+            const source = (kind === 'pdf' ? pdfSource : kind === 'media' ? mediaSource : articleSource)(input, connection?.realm ?? 'public');
+            const submission = store.queue.submit({ kind, ...source, idempotencyKey: 'save:' + source.sourceKey }), { jobId, itemId } = submission;
+            const job = store.queue.list().find((j) => j.id === jobId);
+            if (!args.flags.wait) {
+                c.emit({ ...submission, state: job?.state ?? 'queued' }, `${itemId}\t${job?.state ?? 'queued'}`);
+                return 0;
+            }
+            if (job?.state === 'succeeded') {
+                const item = store.read(itemId);
+                c.emit({ itemId, jobId, status: item.status }, `${itemId}\t${item.status}`);
+                return item.status === 'partial' ? 3 : 0;
+            }
+            return drain(c, jobId, connections);
+        },
+    },
+    {
+        name: 'run',
+        summary: 'Process queued work sequentially',
+        usage: [['run --drain', 'Process queued articles sequentially']],
+        positional: 0,
+        flags: { drain: 'boolean', ...media },
+        library: 'open',
+        check: (_, f) => f.drain === true,
+        handler: async (c) => {
+            const { store, signal } = c;
+            if (hasDueAcquisition(store))
+                return drain(c);
+            if (store.queue.ownerSnapshot())
+                throw new SpongeError('owner-busy');
+            if (store.queue.pendingCleanup())
+                throw new SpongeError('cleanup-required');
+            if (!store.queue.list().some((job) => job.operation === 'index' && job.state === 'queued')) {
+                c.emit({ results: [], indexResults: [] }, 'Queue empty');
+                return 0;
+            }
+            const runtime = await inspectNative('embedding', c.nativeRoot, c.version), indexResults = await drainIndexQueue(store, { runtime, signal });
+            c.emit({ results: [], indexResults });
+            const failed = indexResults.find((result) => !result.ok);
+            return failed && !failed.ok ? exitFor(failed.code) : signal.aborted ? 130 : 0;
+        },
+    },
+    {
+        name: 'queue',
+        summary: 'Inspect and manage jobs',
+        usage: [
+            ['queue status', 'Show jobs and their states'],
+            ['queue cancel JOB', 'Cancel a queued or active job'],
+            ['queue retry JOB', 'Retry a failed job after resolving its cause'],
+            ['queue recover', 'Reconcile a stopped worker after cleanup'],
+        ],
+        positional: (p) => (['status', 'recover'].includes(p[0]) && p.length === 1) ||
+            (['cancel', 'retry'].includes(p[0]) && p.length === 2),
+        flags: {},
+        library: 'open',
+        handler: async (c) => {
+            c.emit(await queueAction(c.store, c.args.positional[0], c.args.positional[1]));
+            return 0;
+        },
+    },
+    {
+        name: 'list',
+        summary: 'List saved and queued items',
+        usage: [['list', 'List saved and queued items']],
+        positional: 0,
+        flags: {},
+        library: 'open',
+        handler: (c) => {
+            const items = c.store.list();
+            c.emit({ items }, lines(items).join('\n'));
+            return 0;
+        },
+    },
+    {
+        name: 'show',
+        summary: 'Show an item as Markdown or JSON',
+        usage: [['show ITEM [--format markdown|json]', '']],
+        positional: 1,
+        flags: { format: 'value' },
+        library: 'open',
+        handler: (c) => {
+            const { store } = c, item = store.read(c.args.positional[0]);
+            if (!item)
+                throw new SpongeError('unavailable');
+            c.emit({
+                item,
+                identity: store.identity(item.itemId),
+                annotations: store.annotations.list(item.itemId),
+                digest: store.derivations.current('digest', item.itemId) ?? null,
+                editorial: store.derivations.current('editorial', item.itemId) ?? null,
+            }, item.markdown);
+            return item.status === 'partial' ? 3 : 0;
+        },
+    },
+    {
+        name: 'asset',
+        summary: 'Write a verified asset to stdout',
+        usage: [['asset ITEM SHA', 'Write a verified asset to stdout']],
+        positional: 2,
+        flags: {},
+        library: 'open',
+        handler: (c) => {
+            const item = c.store.read(c.args.positional[0]), asset = item?.assets.find((a) => a.sha256 === c.args.positional[1]);
+            if (!asset)
+                throw new SpongeError('unavailable');
+            const bytes = c.store.blobs.read(asset);
+            if (c.args.json)
+                c.emit({ asset });
+            else {
+                if (process.stdout.isTTY)
+                    throw new SpongeError('invalid-input');
+                c.write(bytes);
+            }
+            return 0;
+        },
+    },
+    {
+        name: 'search',
+        summary: 'Search saved items',
+        usage: [['search QUERY [--mode hybrid|lexical] [--profile default] [--limit 20]', '']],
+        positional: 1,
+        flags: { mode: 'value', limit: 'value', profile: 'value' },
+        library: 'open',
+        handler: async (c) => {
+            const { store, args, signal } = c;
+            if (args.flags.mode === 'lexical') {
+                const items = store.search(args.positional[0], Number(args.flags.limit ?? 20));
+                c.emit({ items }, lines(items).join('\n'));
+                return 0;
+            }
+            let embedding;
+            try {
+                embedding = await inspectNative('embedding', c.nativeRoot, c.version);
+            }
+            catch {
+                /* Hybrid explicitly reports semantic unavailability and preserves lexical results. */
+            }
+            const result = await store.index.search(args.positional[0], {
+                profileId: args.flags.profile,
+                limit: Number(args.flags.limit ?? 20),
+                signal,
+                ...(embedding ? { embed: createQueryEmbedder(store, embedding) } : {}),
+            });
+            c.emit({ items: result.hits, warnings: result.warnings, generation: result.generation }, [...lines(result.hits), ...result.warnings.map((warning) => `Warning: ${warning}`)].join('\n'));
+            return signal.aborted ? 130 : 0;
+        },
+    },
+    {
+        name: 'refresh',
+        summary: 'Capture a new revision',
+        usage: [['refresh ITEM [--wait]', 'Capture a new revision']],
+        positional: 1,
+        flags: { wait: 'boolean', ...media },
+        library: 'open',
+        handler: async (c) => {
+            const { store, args } = c, connections = await readConnections(store.root), previous = store.queue.list().find((j) => j.item_id === args.positional[0]), source = previous && store.queue.source(String(previous.id));
+            if (!source || !['article', 'pdf', 'media'].includes(source.kind))
+                throw new SpongeError('unavailable');
+            const submission = store.queue.submit({
+                ...source,
+                kind: source.kind,
+                intent: 'refresh',
+                idempotencyKey: randomUUID(),
+            });
+            if (!args.flags.wait) {
+                c.emit(submission, `${submission.itemId}\tqueued`);
+                return 0;
+            }
+            return drain(c, submission.jobId, connections);
+        },
+    },
+    {
+        name: 'delete',
+        summary: 'Hide an item and remove it from search',
+        usage: [['delete ITEM', 'Hide an item and remove it from search']],
+        positional: 1,
+        flags: {},
+        library: 'open',
+        handler: (c) => {
+            c.store.delete(c.args.positional[0]);
+            c.emit({ itemId: c.args.positional[0], deleted: true }, 'Deleted');
+            return 0;
+        },
+    },
+    {
+        name: 'index',
+        summary: 'Manage embedding generations',
+        usage: [
+            ['index create [--profile default]', 'Queue a new embedding generation'],
+            ['index status [GENERATION] [--profile default]', 'Active (or given) generation coverage and pending inputs'],
+            ['index run', 'Drain queued embedding jobs'],
+            ['index rollback GENERATION', 'Reactivate a compatible complete generation'],
+            ['index prune [--keep 1] [--dry-run] [--vacuum]', 'Delete vectors of retired generations'],
+        ],
+        positional: (p) => (['create', 'run', 'prune'].includes(p[0]) && p.length === 1) ||
+            (p[0] === 'status' && p.length <= 2) ||
+            (p[0] === 'rollback' && p.length === 2),
+        flags: { profile: 'value', keep: 'value', 'dry-run': 'boolean', vacuum: 'boolean' },
+        library: 'open',
+        check: (p, f) => p[0] === 'prune' || (f.keep === undefined && !f['dry-run'] && !f.vacuum),
+        handler: async (c) => {
+            const { args } = c, action = args.positional[0], runtime = ['create', 'run'].includes(action)
+                ? await inspectNative('embedding', c.nativeRoot, c.version)
+                : undefined;
+            const result = await indexAction(c.store, action, args.positional[1], {
+                runtime,
+                profile: args.flags.profile,
+                signal: c.signal,
+                ...(action === 'prune'
+                    ? {
+                        keep: args.flags.keep === undefined ? undefined : Number(args.flags.keep),
+                        dryRun: args.flags['dry-run'] === true,
+                        vacuum: args.flags.vacuum === true,
+                    }
+                    : {}),
+            });
+            c.emit(result, result.prune
+                ? pruneText(result.prune)
+                : action === 'status' && !args.positional[1]
+                    ? overviewText(result)
+                    : undefined);
+            const failed = result.results?.find((r) => !r.ok);
+            return failed ? exitFor(failed.code) : 0;
+        },
+    },
+    {
+        name: 'doctor',
+        summary: 'Check library and runtime states',
+        usage: [['doctor', 'Check library and runtime states']],
+        positional: 0,
+        flags: {},
+        library: 'open',
+        handler: async (c) => {
+            const { store } = c;
+            let capture = 'ready';
+            try {
+                await inspectCaptureRuntime(c.captureRoot, defaultCapturePins);
+            }
+            catch (error) {
+                capture = publicCode(error, 'runtime-missing');
+            }
+            const states = {};
+            for (const kind of ['asr', 'embedding']) {
+                try {
+                    await inspectNative(kind, c.nativeRoot, c.version);
+                    states[kind] = 'ready';
+                }
+                catch (error) {
+                    states[kind] = publicCode(error, 'runtime-missing');
+                }
+            }
+            const cleanup = store.queue.pendingCleanup(), worker = await workerDoctor(store, c.version), workerBroken = !['ready', 'not-installed', 'unsupported'].includes(worker.worker);
+            c.emit({ library: 'ready', capture, ...states, pendingCleanup: cleanup, worker }, `Library: ready\nCapture: ${capture}\nASR: ${states.asr}\nEmbedding: ${states.embedding}\nPending cleanup: ${cleanup}\nWorker: ${worker.worker}${Array.isArray(worker.drift) ? ` (${worker.drift.join(', ')})` : ''}${worker.repair ? `\n  ${worker.repair}` : ''}`);
+            return cleanup || capture !== 'ready' || workerBroken ? 4 : 0;
+        },
+    },
+    {
+        name: 'export',
+        summary: 'Export Markdown and local assets',
+        usage: [['export ITEM --output DIR', 'Export Markdown and local assets']],
+        positional: 1,
+        flags: { output: 'value' },
+        library: 'open',
+        check: (_, f) => abs(f.output),
+        handler: async (c) => {
+            c.emit(await portabilityAction(c.store, 'export', {
+                itemId: c.args.positional[0],
+                output: c.args.flags.output,
+            }));
+            return 0;
+        },
+    },
+    {
+        name: 'backup',
+        summary: 'Save a verified offline backup',
+        usage: [['backup --output FILE', 'Save a verified offline backup']],
+        positional: 0,
+        flags: { output: 'value' },
+        library: 'open',
+        check: (_, f) => abs(f.output),
+        handler: async (c) => {
+            c.emit(await portabilityAction(c.store, 'backup', { output: c.args.flags.output }));
+            return 0;
+        },
+    },
+    {
+        name: 'restore',
+        summary: 'Restore into a new private library',
+        usage: [['restore FILE --into NEW_DIR', 'Restore into a new private library']],
+        positional: 1,
+        flags: { into: 'value' },
+        library: 'none',
+        check: (p, f) => abs(f.into) && f.library === undefined && abs(p[0]),
+        handler: async (c) => {
+            c.emit(await restoreLibrary(c.args.positional[0], String(c.args.flags.into)));
+            return 0;
+        },
+    },
+    {
+        name: 'gc',
+        summary: 'Collect unreferenced blobs and superseded runtimes',
+        usage: [
+            ['gc --dry-run', 'Write a report of unreferenced blobs'],
+            ['gc --apply REPORT', 'Recheck and remove reported blobs'],
+            ['gc --runtimes [--dry-run]', 'Remove superseded runtimes, models and worker journals'],
+        ],
+        positional: 0,
+        flags: { 'dry-run': 'boolean', apply: 'value', runtimes: 'boolean' },
+        library: 'open',
+        check: (_, f) => f.runtimes
+            ? f.apply === undefined
+            : Boolean(f['dry-run']) !== Boolean(f.apply) && (f.apply === undefined || abs(f.apply)),
+        handler: async (c) => {
+            if (c.args.flags.runtimes) {
+                const report = await runtimeGcAction(c.store, c.version, c.args.flags['dry-run'] === true);
+                c.emit(report, runtimeGcText(report));
+                return 0;
+            }
+            c.emit(await portabilityAction(c.store, 'gc', {
+                dryRun: c.args.flags['dry-run'] === true,
+                report: c.args.flags.apply,
+            }));
+            return 0;
+        },
+    },
+    {
+        name: 'worker',
+        summary: 'Manage the optional background worker',
+        usage: [
+            ['worker install [--language en]', 'Enable the optional background worker'],
+            ['worker status', 'Inspect the background worker'],
+            ['worker uninstall', 'Stop it and preserve the library'],
+        ],
+        positional: 1,
+        flags: { language: 'value', 'force-local': 'boolean' },
+        library: 'open',
+        check: (p) => ['install', 'status', 'uninstall', 'serve'].includes(p[0]),
+        handler: async (c) => {
+            const { store, args } = c;
+            if (args.positional[0] !== 'serve') {
+                c.emit(await workerAction(store, args.positional[0], c.version, undefined, {
+                    language: args.flags.language,
+                }));
+                return 0;
+            }
+            const connections = await readConnections(store.root);
+            c.emit(await serveWorker(store, {
+                signal: c.signal,
+                language: args.flags.language,
+                forceLocal: args.flags['force-local'] === true,
+                resolveCaptureRuntime: () => inspectCaptureRuntime(c.captureRoot, defaultCapturePins),
+                resolveConnection: resolveConnection(connections),
+            }, c.version));
+            return 0;
+        },
+    },
+    {
+        name: 'import',
+        summary: 'Import existing captures',
+        usage: [
+            ['import MANIFEST [--apply]', 'Preview or import existing Wordcell captures'],
+            ['import jungle DIR [--apply]', 'Preview or import Jungle Reading notes, their captures and published state'],
+        ],
+        positional: (p) => p.length === 1 || (p[0] === 'jungle' && p.length === 2),
+        flags: { apply: 'boolean', 'dry-run': 'boolean', limit: 'value', offset: 'value' },
+        library: 'open',
+        check: (p, f) => abs(p.at(-1)) &&
+            !(f.apply && f['dry-run']) &&
+            (f.offset === undefined || /^(0|[1-9][0-9]{0,5})$/.test(String(f.offset))),
+        handler: async (c) => {
+            const { store, args, signal } = c, dryRun = args.flags.apply !== true, offset = Number(args.flags.offset ?? 0);
+            if (args.positional[0] === 'jungle' && args.positional.length === 2) {
+                // A dry run reads Jungle and the library only; applying reverifies every capture with the released verifier.
+                const runtime = dryRun ? undefined : await captureRuntime(c);
+                const report = await jungleAction(store, args.positional[1], {
+                    dryRun,
+                    runtime,
+                    limit: Number(args.flags.limit ?? 1000),
+                    offset,
+                    signal,
+                });
+                c.emit({ report }, jungleText(report));
+                return signal.aborted
+                    ? 130
+                    : report.counts.skipped['capture-failed'] || report.counts.skipped['capture-unsupported']
+                        ? 3
+                        : 0;
+            }
+            const runtime = await captureRuntime(c), report = await importAction(store, args.positional[0], {
+                runtime,
+                dryRun,
+                limit: Number(args.flags.limit ?? 20),
+                offset,
+                signal,
+            });
+            c.emit({ report });
+            return signal.aborted
+                ? 130
+                : report.entries.some((entry) => entry.status === 'failed' || entry.status === 'unsupported')
+                    ? 3
+                    : 0;
+        },
+    },
+    {
+        name: 'visibility',
+        summary: 'Override or restore the default visibility',
+        usage: [['visibility ITEM public|private|default', 'Override or restore the default']],
+        positional: 2,
+        flags: {},
+        library: 'open',
+        check: (p) => ['public', 'private', 'default'].includes(p[1]),
+        handler: (c) => {
+            const [itemId, value] = c.args.positional, state = c.store.setVisibility(itemId, value === 'default' ? null : value);
+            c.emit({ itemId, visibility: state }, `${state.effective}${state.override ? ' (set)' : ' (default)'}`);
+            return 0;
+        },
+    },
+    {
+        name: 'title',
+        summary: "Set or reset an item's title",
+        usage: [
+            ['title set ITEM TEXT', 'Use TEXT as the title; refresh and import never change it'],
+            ['title reset ITEM', 'Restore the default: the captured title (a local scan takes its import note title)'],
+        ],
+        positional: (p) => (p[0] === 'set' && p.length === 3) || (p[0] === 'reset' && p.length === 2),
+        flags: {},
+        library: 'open',
+        handler: (c) => {
+            const [action, itemId, value] = c.args.positional, state = c.store.setTitle(itemId, action === 'set' ? value : null);
+            c.emit({ itemId, title: state }, `${state.title}${state.override !== null ? ' (set)' : ' (default)'}`);
+            return 0;
+        },
+    },
+    {
+        name: 'highlight',
+        summary: 'Anchor a verbatim quote',
+        usage: [['highlight ITEM TEXT [--note BODY] [--occurrence N]', 'Anchor a verbatim quote']],
+        positional: 2,
+        flags: { note: 'value', occurrence: 'value' },
+        library: 'open',
+        handler: (c) => {
+            const { flags, positional } = c.args, annotation = c.store.annotations.addHighlight({
+                itemId: positional[0],
+                quote: positional[1],
+                ...(typeof flags.note === 'string' ? { note: flags.note } : {}),
+                ...(flags.occurrence !== undefined ? { occurrence: Number(flags.occurrence) } : {}),
+            });
+            c.emit({ annotation }, annotation.id);
+            return 0;
+        },
+    },
+    {
+        name: 'comment',
+        summary: 'Comment on an item or reply',
+        usage: [['comment ITEM BODY [--on ANNOTATION]', 'Comment on an item or reply']],
+        positional: 2,
+        flags: { on: 'value' },
+        library: 'open',
+        handler: (c) => {
+            const { flags, positional } = c.args, annotation = c.store.annotations.addComment({
+                itemId: positional[0],
+                body: positional[1],
+                ...(typeof flags.on === 'string' ? { parentId: flags.on } : {}),
+            });
+            c.emit({ annotation }, annotation.id);
+            return 0;
+        },
+    },
+    {
+        name: 'publish',
+        summary: 'Show or write the public reading list',
+        usage: [
+            ['publish --dry-run [--min-age-days N]', 'Show the public reading-list entries'],
+            [
+                'publish --output DIR [--title T] [--base-url https://...] [--min-age-days N]',
+                'Write a signed static feed site with <sponge-list>',
+            ],
+        ],
+        positional: 0,
+        flags: { 'dry-run': 'boolean', output: 'value', 'min-age-days': 'value', title: 'value', 'base-url': 'value' },
+        library: 'open',
+        check: (_, f) => Boolean(f['dry-run']) !== Boolean(f.output) &&
+            (f.output === undefined || abs(f.output)) &&
+            ((f.title === undefined && f['base-url'] === undefined) || Boolean(f.output)) &&
+            (f['min-age-days'] === undefined || /^(0|[1-9][0-9]{0,3})$/.test(String(f['min-age-days']))) &&
+            Number(f['min-age-days'] ?? 0) <= 3650 &&
+            (f.title === undefined || String(f.title).length <= 200) &&
+            (f['base-url'] === undefined || /^https:\/\//.test(String(f['base-url']))),
+        handler: (c) => {
+            const { store, args } = c, minAgeDays = Number(args.flags['min-age-days'] ?? 0);
+            if (typeof args.flags.output === 'string') {
+                const result = publishSite(store, {
+                    output: args.flags.output,
+                    minAgeDays,
+                    ...(typeof args.flags.title === 'string' ? { title: args.flags.title } : {}),
+                    ...(typeof args.flags['base-url'] === 'string' ? { baseUrl: args.flags['base-url'] } : {}),
+                });
+                c.emit(result, `Published ${result.entries} entr${result.entries === 1 ? 'y' : 'ies'} to ${result.output}`);
+                return 0;
+            }
+            const all = store.publicProjection(), projection = { ...all, entries: minAge(all.entries, minAgeDays) };
+            c.emit({
+                dryRun: true,
+                ...projection,
+                ...(minAgeDays ? { held: all.entries.length - projection.entries.length } : {}),
+            }, [
+                ...projection.entries.map((entry) => `${entry.uri}\t${entry.title}`),
+                ...(projection.skipped.length
+                    ? [`Skipped ${projection.skipped.length} public item(s) without a public link`]
+                    : []),
+            ].join('\n') || 'Nothing public');
+            return 0;
+        },
+    },
+    {
+        name: 'digest',
+        summary: 'Draft or show an item digest',
+        usage: [
+            [
+                'digest ITEM --endpoint http://127.0.0.1:PORT --model NAME [--check-support]',
+                'Draft a digest with a local model server you started',
+            ],
+            ['digest ITEM', 'Show the current digest and its review state'],
+        ],
+        positional: 1,
+        flags: { endpoint: 'value', model: 'value', 'check-support': 'boolean' },
+        library: 'open',
+        check: (_, f) => Boolean(f.endpoint) === Boolean(f.model) &&
+            !(f['check-support'] && !f.endpoint) &&
+            (f.model === undefined || /^[\w.:/@+-]{1,256}$/.test(String(f.model))),
+        handler: async (c) => {
+            const { store, args, signal } = c;
+            if (!args.flags.endpoint) {
+                const digest = store.derivations.current('digest', args.positional[0]);
+                if (!digest)
+                    throw new SpongeError('unavailable');
+                c.emit({ digest }, digestText(digest));
+                return 0;
+            }
+            const model = await connectEndpoint({
+                endpoint: String(args.flags.endpoint),
+                model: String(args.flags.model),
+                signal,
+            });
+            const embed = args.flags['check-support']
+                ? createTextEmbedder(store, await inspectNative('embedding', c.nativeRoot, c.version))
+                : undefined;
+            const result = await createDigest(store, args.positional[0], model, { signal, ...(embed ? { embed } : {}) });
+            c.emit({ digest: result.derivation, duplicate: result.duplicate, ...(result.trace ? { trace: result.trace } : {}) }, digestText(result.derivation));
+            return 0;
+        },
+    },
+    {
+        name: 'review',
+        summary: 'Accept or reject digest fields',
+        usage: [['review DIGEST --accept SPEC --reject SPEC', 'Review fields: all, gist, idea:N, quote:N.M']],
+        positional: 1,
+        flags: { accept: 'value', reject: 'value' },
+        library: 'open',
+        check: (_, f) => !(f.accept === undefined && f.reject === undefined) &&
+            [f.accept, f.reject].every((v) => v === undefined || reviewSpec.test(String(v))),
+        handler: (c) => {
+            const { store, args } = c, prior = store.derivations.read('digest', args.positional[0]);
+            if (!prior)
+                throw new SpongeError('unavailable');
+            const digest = store.derivations.review('digest', prior.id, reviewFromSpec(prior, args.flags.accept, args.flags.reject));
+            c.emit({ digest }, digestText(digest));
+            return 0;
+        },
+    },
+    {
+        name: 'help',
+        summary: 'Show help for all commands or one',
+        usage: [['help [COMMAND]', 'Show help for all commands or one']],
+        positional: (p) => p.length <= 1,
+        flags: {},
+        library: 'none',
+        check: (p) => !p.length || commands.some((command) => command.name === p[0]),
+        handler: (c) => {
+            c.write(c.args.positional[0] ? commandHelp(c.args.positional[0]) : help());
+            return 0;
+        },
+    },
+    {
+        name: 'version',
+        summary: 'Print the version',
+        usage: [['--version', 'Print the version']],
+        positional: 0,
+        flags: {},
+        library: 'none',
+        handler: (c) => {
+            c.write(c.version + '\n');
+            return 0;
+        },
+    },
+];
+export const command = (name) => commands.find((c) => c.name === name);
+const row = ([synopsis, description]) => !description
+    ? `  ${synopsis}\n`
+    : synopsis.length < 30
+        ? `  ${synopsis.padEnd(30)}${description}\n`
+        : synopsis.length < 60
+            ? `  ${synopsis}  ${description}\n`
+            : `  ${synopsis}\n${' '.repeat(32)}${description}\n`;
+const notes = `Global flags: --library /absolute/path --json --debug (or SPONGE_DEBUG=1: print error causes to stderr)
+Items are public by default only when captured from a public source.
+Use -- before an option-like search query. Capture setup is explicit.
+Digest endpoints must be literal loopback HTTP (127.0.0.1 or [::1]); Sponge never starts a model server.
+Media: --language en enables local English ASR; --force-local bypasses captions.
+These flags apply to --wait, run --drain, or worker serve.
+worker install --language en saves the English ASR choice for background work.
+For trusted local sources, use --allow-private-network with --wait or run.
+`;
+export function help() {
+    return `sponge — a local article library\n\n${commands.flatMap((c) => c.usage.map(row)).join('')}\n${notes}`;
+}
+/** One command's synopsis lines; also the hint printed for its usage errors. */
+export const usageOf = (name) => command(name)
+    .usage.map(([synopsis]) => `sponge ${synopsis}`)
+    .join('\n');
+export function commandHelp(name) {
+    const c = command(name), flags = Object.keys(c.flags);
+    return `sponge ${c.name} — ${c.summary}\n\nUsage:\n${c.usage.map(row).join('').replace(/^  /gm, '  sponge ')}${flags.length ? `\nFlags: ${flags.map((f) => '--' + f).join(' ')}\n` : ''}\nGlobal flags: --library /absolute/path --json --debug\n`;
+}