@hraness/sponge 0.1.2 → 0.2.1

package/dist/src/cli/arguments.js

@@ -0,0 +1,106 @@
+import { isAbsolute } from 'node:path';
+import { InputError } from '../app/source.js';
+const specifications = {
+    init: { count: 0, flags: {} },
+    add: { count: 1, flags: { connection: 'value', kind: 'value', wait: 'boolean', language: 'value', 'force-local': 'boolean', 'allow-private-network': 'boolean' } },
+    list: { count: 0, flags: {} },
+    asset: { count: 2, flags: {} },
+    show: { count: 1, flags: { format: 'value' } },
+    delete: { count: 1, flags: {} },
+    refresh: { count: 1, flags: { wait: 'boolean', language: 'value', 'force-local': 'boolean', 'allow-private-network': 'boolean' } },
+    search: { count: 1, flags: { mode: 'value', limit: 'value', profile: 'value' } },
+    run: { count: 0, flags: { drain: 'boolean', language: 'value', 'force-local': 'boolean', 'allow-private-network': 'boolean' } },
+    setup: { count: 0, flags: { capture: 'boolean', asr: 'boolean', embedding: 'boolean' } },
+    doctor: { count: 0, flags: {} },
+    queue: { count: -1, flags: {} },
+    export: { count: 1, flags: { output: 'value' } },
+    backup: { count: 0, flags: { output: 'value' } },
+    restore: { count: 1, flags: { into: 'value' } },
+    gc: { count: 0, flags: { 'dry-run': 'boolean', apply: 'value' } },
+    worker: { count: 1, flags: { language: 'value', 'force-local': 'boolean' } },
+    index: { count: -1, flags: { profile: 'value' } },
+    import: { count: 1, flags: { apply: 'boolean', 'dry-run': 'boolean', limit: 'value', offset: 'value' } },
+};
+/** No shell grammar, implicit option coercion, duplicate flags, or unbounded argv. */
+export function parseArguments(argv) {
+    if (argv.length > 32 || argv.some(arg => Buffer.byteLength(arg) > 8192 || /[\u0000-\u001f\u007f]/u.test(arg)))
+        throw new InputError();
+    if (argv.length === 0 || argv.length === 1 && ['--help', '-h'].includes(argv[0]))
+        return { command: 'help', positional: [], flags: {}, json: false };
+    if (argv.length === 1 && argv[0] === '--version')
+        return { command: 'version', positional: [], flags: {}, json: false };
+    // Global flags are valid before or after the command.
+    let command;
+    const flags = Object.create(null);
+    const positional = [];
+    const allFlags = { library: 'value', json: 'boolean' };
+    for (const spec of Object.values(specifications))
+        Object.assign(allFlags, spec.flags);
+    let literal = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--' && !literal) {
+            literal = true;
+            continue;
+        }
+        if (arg.startsWith('--') && !literal) {
+            const key = arg.slice(2);
+            const kind = (command && specifications[command]?.flags[key]) ?? allFlags[key];
+            if (!kind || Object.hasOwn(flags, key))
+                throw new InputError();
+            if (kind === 'boolean')
+                flags[key] = true;
+            else {
+                const value = argv[++i];
+                if (!value || value.startsWith('--'))
+                    throw new InputError();
+                flags[key] = value;
+            }
+        }
+        else if (!command)
+            command = arg;
+        else
+            positional.push(arg);
+    }
+    const spec = command && specifications[command];
+    if (!command || !spec || (command === 'queue' ? !(['status', 'recover'].includes(positional[0]) && positional.length === 1 || ['cancel', 'retry'].includes(positional[0]) && positional.length === 2) : command === 'index' ? !(['create', 'run'].includes(positional[0]) && positional.length === 1 || ['status', 'rollback'].includes(positional[0]) && positional.length === 2) : positional.length !== spec.count))
+        throw new InputError();
+    if (Object.keys(flags).some(key => !['library', 'json'].includes(key) && !Object.hasOwn(spec.flags, key)))
+        throw new InputError();
+    const library = flags.library;
+    if (library !== undefined && (typeof library !== 'string' || !isAbsolute(library)))
+        throw new InputError();
+    if (flags.kind && !['article', 'pdf', 'media'].includes(String(flags.kind)))
+        throw new InputError();
+    if (flags.format && !['markdown', 'json'].includes(String(flags.format)))
+        throw new InputError();
+    if (flags.mode && !['lexical', 'hybrid'].includes(String(flags.mode)))
+        throw new InputError();
+    if (flags.limit && (!/^[1-9]\d{0,2}$/u.test(String(flags.limit)) || Number(flags.limit) > 100))
+        throw new InputError();
+    if (command === 'run' && !flags.drain || command === 'setup' && [flags.capture, flags.asr, flags.embedding].filter(Boolean).length !== 1)
+        throw new InputError();
+    if (flags['allow-private-network'] && command !== 'run' && !flags.wait)
+        throw new InputError();
+    if (['export', 'backup'].includes(command) && (typeof flags.output !== 'string' || !isAbsolute(flags.output)))
+        throw new InputError();
+    if (command === 'restore' && (typeof flags.into !== 'string' || !isAbsolute(flags.into) || flags.library !== undefined || !isAbsolute(positional[0])))
+        throw new InputError();
+    if (command === 'gc' && (Boolean(flags['dry-run']) === Boolean(flags.apply) || flags.apply !== undefined && !isAbsolute(String(flags.apply))))
+        throw new InputError();
+    if (command === 'worker' && !['install', 'status', 'uninstall', 'serve'].includes(positional[0]))
+        throw new InputError();
+    if (command === 'import' && (!isAbsolute(positional[0]) || flags.apply && flags['dry-run'] || flags.offset !== undefined && !/^(0|[1-9][0-9]{0,5})$/.test(String(flags.offset))))
+        throw new InputError();
+    if (flags.language !== undefined && flags.language !== 'en')
+        throw new InputError();
+    if (flags['force-local'] && command === 'worker' && positional[0] === 'install')
+        throw new InputError();
+    if (flags['force-local'] && !flags.language)
+        throw new InputError();
+    if ((flags.language || flags['force-local']) && (['add', 'refresh'].includes(command) && !flags.wait || command === 'worker' && !['serve', 'install'].includes(positional[0])))
+        throw new InputError();
+    if (flags.profile && (!(command === 'search' || command === 'index' && positional[0] === 'create') || !/^[a-zA-Z0-9_-]{1,128}$/.test(String(flags.profile))))
+        throw new InputError();
+    return { command, positional, flags, library: library, json: flags.json === true || flags.format === 'json' };
+}

package/dist/src/cli/config.d.ts

@@ -0,0 +1,8 @@
+import type { CaptureConnection } from '../acquisition/index.js';
+export interface Connection {
+    id: string;
+    realm: string;
+    capture: CaptureConnection;
+}
+/** Local references only. Tokens, cookies and passwords never belong in this file. */
+export declare function readConnections(root: string): Promise<Connection[]>;

package/dist/src/cli/config.js

@@ -0,0 +1,45 @@
+import { lstat } from 'node:fs/promises';
+import { readConfined } from '../acquisition/files.js';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { InputError } from '../app/source.js';
+/** Local references only. Tokens, cookies and passwords never belong in this file. */
+export async function readConnections(root) {
+    const path = join(root, 'connections.json');
+    let bytes;
+    try {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 65536 || (stat.mode & 0o077) !== 0)
+            throw new InputError();
+        bytes = await readConfined(root, 'connections.json', 65536);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    let config;
+    try {
+        config = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new InputError();
+    }
+    if (config?.schemaVersion !== 1 || !Array.isArray(config.connections) || config.connections.length > 100)
+        throw new InputError();
+    const ids = new Set();
+    return config.connections.map((entry) => {
+        if (!entry || typeof entry.id !== 'string' || !/^[a-zA-Z0-9_-]{1,64}$/.test(entry.id) || ids.has(entry.id))
+            throw new InputError();
+        ids.add(entry.id);
+        let capture;
+        if (entry.kind === 'account' && typeof entry.stateHome === 'string' && entry.stateHome.startsWith('/') && typeof entry.accountId === 'string')
+            capture = { kind: 'account', stateHome: entry.stateHome, accountId: entry.accountId };
+        else if (entry.kind === 'cdp' && typeof entry.endpoint === 'string')
+            capture = { kind: 'cdp', endpoint: entry.endpoint };
+        else
+            throw new InputError();
+        const realm = 'connection:' + createHash('sha256').update(JSON.stringify([entry.id, capture])).digest('hex');
+        return { id: entry.id, realm, capture };
+    });
+}

package/dist/src/cli/import.d.ts

@@ -0,0 +1,4 @@
+import type { LibraryStore } from '../store/index.js';
+import { type ImportOptions, type ImportReport } from '../importers/apply.js';
+/** A source manifest is explicit; default execution produces a private dry-run report. */
+export declare function importAction(store: LibraryStore, path: string, options: ImportOptions): Promise<ImportReport>;

package/dist/src/cli/import.js

@@ -0,0 +1,3 @@
+import { importManifest } from '../importers/apply.js';
+/** A source manifest is explicit; default execution produces a private dry-run report. */
+export function importAction(store, path, options) { return importManifest(store, path, options); }

package/dist/src/cli/indexing.d.ts

@@ -0,0 +1,7 @@
+import type { LibraryStore } from '../store/index.js';
+import { type EmbeddingRuntime } from '../inference/embedding/index.js';
+export declare function indexAction(store: LibraryStore, action: string, id: string | undefined, options?: {
+    runtime?: EmbeddingRuntime;
+    profile?: string;
+    signal?: AbortSignal;
+}): Promise<Record<string, unknown>>;

package/dist/src/cli/indexing.js

@@ -0,0 +1,21 @@
+import { embeddingIdentity, embeddingFingerprint } from '../inference/embedding/index.js';
+import { drainIndexQueue } from '../indexing/runner.js';
+import { StoreError } from '../store/index.js';
+import { NativeCatalogError } from '../models/catalog.js';
+export async function indexAction(store, action, id, options = {}) {
+    if (action === 'status')
+        return { generation: store.indexStatus(id) };
+    if (action === 'rollback') {
+        const generation = store.indexStatus(id);
+        if (!['active', 'retired'].includes(generation.state))
+            throw new StoreError('invalid-input');
+        return { generation: store.activateIndex(id) };
+    }
+    if (!options.runtime)
+        throw new NativeCatalogError('runtime-missing');
+    if (action === 'create') {
+        const runtime = options.runtime, generation = store.createIndexGeneration({ profileId: options.profile ?? 'default', fingerprint: embeddingFingerprint(runtime.helperSha256), identity: { ...embeddingIdentity, helperSha256: runtime.helperSha256 }, dimensions: embeddingIdentity.dimensions });
+        return { generation, job: store.submitIndexJob(generation.id) };
+    }
+    return { results: await drainIndexQueue(store, { runtime: options.runtime, signal: options.signal }) };
+}

package/dist/src/cli/main.d.ts

@@ -0,0 +1 @@
+export declare function main(argv: string[], version: string): Promise<number>;

package/dist/src/cli/main.js

@@ -0,0 +1,333 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { lstat } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { terminalSafe } from './terminal.js';
+import { parseArguments } from './arguments.js';
+import { readConnections } from './config.js';
+import { pdfSource } from '../pdf/index.js';
+import { articleSource, mediaSource, InputError } from '../app/source.js';
+import { openLibrary, StoreError } from '../store/index.js';
+import { defaultCapturePins, inspectCaptureRuntime, provisionCapture, captureSetupPlan } from '../acquisition/index.js';
+import { queueAction } from './queue.js';
+import { portabilityAction, restoreAction } from './portability.js';
+import { workerAction, serveWorker, hasDueAcquisition } from './worker.js';
+import { nativeSetupPlan, provisionNative, inspectNative } from '../models/runtime.js';
+import { nativeDownloadAuthGuidance } from '../models/download.js';
+import { drainIndexQueue } from '../indexing/runner.js';
+import { createQueryEmbedder } from '../search/query.js';
+import { indexAction } from './indexing.js';
+import { importAction } from './import.js';
+import { drainLibrary } from '../worker/basic.js';
+import { failure } from '../acquisition/errors.js';
+const help = `sponge — a local article library
+
+  init                          Create a private library
+  setup --capture|--asr|--embedding  Download one pinned runtime
+  add URL_OR_PDF [--kind article|pdf|media] [--connection ID] [--wait]
+  run --drain                   Process queued articles sequentially
+  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
+  list                          List saved and queued items
+  show ITEM [--format markdown|json]
+  asset ITEM SHA                Write a verified asset to stdout
+  search QUERY [--mode hybrid|lexical] [--profile default] [--limit 20]
+  refresh ITEM [--wait]         Capture a new revision
+  delete ITEM                   Hide an item and remove it from search
+  index create [--profile default]  Queue a new embedding generation
+  index status GENERATION       Inspect generation coverage
+  index run                     Drain queued embedding jobs
+  index rollback GENERATION     Reactivate a compatible complete generation
+  doctor                        Check library and runtime states
+  export ITEM --output DIR      Export Markdown and local assets
+  backup --output FILE          Save a verified offline backup
+  restore FILE --into NEW_DIR   Restore into a new private library
+  gc --dry-run                  Write a report of unreferenced blobs
+  gc --apply REPORT             Recheck and remove reported blobs
+  worker install [--language en] Enable the optional background worker
+  worker status                 Inspect the background worker
+  worker uninstall              Stop it and preserve the library
+  import MANIFEST [--apply]     Preview or import existing Wordcell captures
+
+Global flags: --library /absolute/path --json
+Use -- before an option-like search query. Capture setup is explicit.
+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.
+`;
+const codes = new Set(['grant-permission', 'repair-auth', 'unsupported', 'unavailable', 'rate-limited', 'partial', 'cleanup-required', 'cancelled', 'invalid-input', 'unclassified', 'integrity', 'limit-exceeded', 'runtime-missing', 'schema-newer', 'owner-busy']);
+function errorCode(error, fallback) { const code = error?.code; return code && codes.has(code) ? code : fallback; }
+function exitFor(code) { return code === 'cancelled' ? 130 : code === 'invalid-input' ? 2 : code === 'partial' ? 3 : ['grant-permission', 'repair-auth', 'cleanup-required', 'runtime-missing', 'owner-busy'].includes(code) ? 4 : 1; }
+export async function main(argv, version) {
+    const requestId = randomUUID();
+    let store;
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    process.on('SIGINT', cancel);
+    process.on('SIGTERM', cancel);
+    try {
+        const args = parseArguments(argv), emit = (data, text) => { const output = args.json ? JSON.stringify({ schemaVersion: 1, requestId, ok: true, ...data }) + '\n' : (text ?? JSON.stringify(data)) + '\n'; process.stdout.write(process.stdout.isTTY ? terminalSafe(output) : output); };
+        if (args.command === 'help') {
+            process.stdout.write(help);
+            return 0;
+        }
+        if (args.command === 'version') {
+            process.stdout.write(version + '\n');
+            return 0;
+        }
+        if (args.command === 'restore') {
+            emit(await restoreAction(args.positional[0], String(args.flags.into)));
+            return 0;
+        }
+        const root = args.library ?? join(homedir(), '.local', 'share', 'sponge');
+        if (args.command !== 'init') {
+            try {
+                await lstat(join(root, '.sponge-library'));
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    throw new StoreError('unavailable');
+                throw error;
+            }
+        }
+        store = await openLibrary(root);
+        if (args.command === 'init') {
+            emit({ library: store.root }, `Library: ${store.root}`);
+            return 0;
+        }
+        if (args.command === 'worker' && args.positional[0] !== 'serve') {
+            emit(await workerAction(store, args.positional[0], version, undefined, { language: args.flags.language }));
+            return 0;
+        }
+        if (args.command === 'export' || args.command === 'backup' || args.command === 'gc') {
+            emit(await portabilityAction(store, args.command, { itemId: args.positional[0], output: args.flags.output, dryRun: args.flags['dry-run'] === true, report: args.flags.apply }));
+            return 0;
+        }
+        const runtimeRoot = join(store.root, 'runtime', 'capture', defaultCapturePins.id);
+        const nativeRoot = join(store.root, 'runtime', 'models');
+        if (args.command === 'setup' && !args.flags.capture) {
+            const kind = args.flags.asr ? 'asr' : 'embedding', plan = await nativeSetupPlan(kind, version);
+            process.stderr.write(JSON.stringify({ setup: kind, ...plan }) + '\n');
+            try {
+                await provisionNative(kind, nativeRoot, version, controller.signal);
+            }
+            catch (error) {
+                if (error.code === 'repair-auth' && !args.json)
+                    process.stderr.write(nativeDownloadAuthGuidance + '\n');
+                throw error;
+            }
+            emit({ [kind]: 'ready' });
+            return 0;
+        }
+        if (args.command === 'setup') {
+            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(store.root, 'runtime', 'capture'), pins: defaultCapturePins, signal: controller.signal });
+            emit({ capture: 'ready' }, 'Capture ready');
+            return 0;
+        }
+        if (args.command === 'list') {
+            const items = store.list();
+            emit({ items }, items.map(item => `${item.itemId}\t${item.title}`).join('\n'));
+            return 0;
+        }
+        if (args.command === 'show') {
+            const item = store.read(args.positional[0]);
+            if (!item)
+                throw new StoreError('unavailable');
+            emit({ item }, item.markdown);
+            return item.status === 'partial' ? 3 : 0;
+        }
+        if (args.command === 'asset') {
+            const item = store.read(args.positional[0]), asset = item?.assets.find(a => a.sha256 === args.positional[1]);
+            if (!asset)
+                throw new StoreError('unavailable');
+            const bytes = store.readBlob(asset);
+            if (args.json)
+                emit({ asset });
+            else {
+                if (process.stdout.isTTY)
+                    throw new InputError();
+                process.stdout.write(bytes);
+            }
+            return 0;
+        }
+        if (args.command === 'index') {
+            const action = args.positional[0], runtime = ['create', 'run'].includes(action) ? await inspectNative('embedding', nativeRoot, version) : undefined;
+            const result = await indexAction(store, action, args.positional[1], { runtime, profile: args.flags.profile, signal: controller.signal });
+            emit(result);
+            const failed = result.results?.find(r => !r.ok);
+            return failed ? exitFor(failed.code) : 0;
+        }
+        if (args.command === 'search') {
+            if (args.flags.mode === 'lexical') {
+                const items = store.search(args.positional[0], Number(args.flags.limit ?? 20));
+                emit({ items }, items.map(item => `${item.itemId}\t${item.title}`).join('\n'));
+                return 0;
+            }
+            let embedding;
+            try {
+                embedding = await inspectNative('embedding', nativeRoot, version);
+            }
+            catch { /* Hybrid explicitly reports semantic unavailability and preserves lexical results. */ }
+            const result = await store.searchHybrid(args.positional[0], { profileId: args.flags.profile, limit: Number(args.flags.limit ?? 20), signal: controller.signal, ...(embedding ? { embed: createQueryEmbedder(store, embedding) } : {}) });
+            emit({ items: result.hits, warnings: result.warnings, generation: result.generation }, [...result.hits.map(item => `${item.itemId}\t${item.title}`), ...result.warnings.map(warning => `Warning: ${warning}`)].join('\n'));
+            return controller.signal.aborted ? 130 : 0;
+        }
+        if (args.command === 'delete') {
+            store.delete(args.positional[0]);
+            emit({ itemId: args.positional[0], deleted: true }, 'Deleted');
+            return 0;
+        }
+        if (args.command === 'queue') {
+            const result = await queueAction(store, args.positional[0], args.positional[1]);
+            emit(result);
+            return 0;
+        }
+        if (args.command === 'doctor') {
+            let capture = 'ready';
+            try {
+                await inspectCaptureRuntime(runtimeRoot, defaultCapturePins);
+            }
+            catch (error) {
+                capture = errorCode(error, 'runtime-missing');
+            }
+            const states = {};
+            for (const kind of ['asr', 'embedding']) {
+                try {
+                    await inspectNative(kind, nativeRoot, version);
+                    states[kind] = 'ready';
+                }
+                catch (error) {
+                    states[kind] = errorCode(error, 'runtime-missing');
+                }
+            }
+            const cleanup = store.pendingCleanupCount();
+            emit({ library: 'ready', capture, ...states, pendingCleanup: cleanup }, `Library: ready\nCapture: ${capture}\nASR: ${states.asr}\nEmbedding: ${states.embedding}\nPending cleanup: ${cleanup}`);
+            return cleanup || capture !== 'ready' ? 4 : 0;
+        }
+        if (args.command === 'run' && !hasDueAcquisition(store)) {
+            if (store.ownerSnapshot())
+                throw new StoreError('owner-busy');
+            if (store.pendingCleanupCount())
+                throw Object.assign(Error('cleanup-required'), { code: 'cleanup-required' });
+            if (!store.listJobs().some(job => job.operation === 'index' && job.state === 'queued')) {
+                emit({ results: [], indexResults: [] }, 'Queue empty');
+                return 0;
+            }
+            const runtime = await inspectNative('embedding', nativeRoot, version), indexResults = await drainIndexQueue(store, { runtime, signal: controller.signal });
+            emit({ results: [], indexResults });
+            const failed = indexResults.find(result => !result.ok);
+            return failed && !failed.ok ? exitFor(failed.code) : controller.signal.aborted ? 130 : 0;
+        }
+        const connections = await readConnections(store.root);
+        let jobId, itemId;
+        if (args.command === 'add') {
+            const connection = args.flags.connection ? connections.find(c => c.id === args.flags.connection) : undefined;
+            if (args.flags.connection && !connection)
+                throw new InputError();
+            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.submitSource({ kind, ...source, idempotencyKey: 'save:' + source.sourceKey });
+            jobId = submission.jobId;
+            itemId = submission.itemId;
+            const job = store.listJobs().find(j => j.id === jobId);
+            if (!args.flags.wait) {
+                emit({ ...submission, state: job?.state ?? 'queued' }, `${itemId}\t${job?.state ?? 'queued'}`);
+                return 0;
+            }
+            if (job?.state === 'succeeded') {
+                const item = store.read(itemId);
+                emit({ itemId, jobId, status: item.status }, `${itemId}\t${item.status}`);
+                return item.status === 'partial' ? 3 : 0;
+            }
+        }
+        else if (args.command === 'refresh') {
+            const previous = store.listJobs().find(j => j.item_id === args.positional[0]), source = previous && store.sourceForJob(String(previous.id));
+            if (!source || !['article', 'pdf', 'media'].includes(source.kind))
+                throw new StoreError('unavailable');
+            const submission = store.submitSource({ ...source, kind: source.kind, intent: 'refresh', idempotencyKey: randomUUID() });
+            jobId = submission.jobId;
+            itemId = submission.itemId;
+            if (!args.flags.wait) {
+                emit(submission, `${itemId}\tqueued`);
+                return 0;
+            }
+        }
+        if (jobId) {
+            const job = store.listJobs().find(j => j.id === jobId);
+            if (job && job.state !== 'queued') {
+                const code = job.state === 'cancelled' ? 'cancelled' : job.state === 'cleanup-pending' ? 'cleanup-required' : job.state === 'running' ? 'owner-busy' : errorCode({ code: job.reason }, 'unclassified');
+                throw Object.assign(Error(code), { code });
+            }
+        }
+        if (args.command === 'worker') {
+            emit(await serveWorker(store, { signal: controller.signal, language: args.flags.language, forceLocal: args.flags['force-local'] === true, resolveCaptureRuntime: () => inspectCaptureRuntime(runtimeRoot, defaultCapturePins), resolveConnection: (realm) => { if (realm === 'public')
+                    return undefined; const connection = connections.find(c => c.realm === realm); if (!connection)
+                    throw Object.assign(Error('repair-auth'), { code: 'repair-auth' }); return connection.capture; } }, version));
+            return 0;
+        }
+        let runtime;
+        try {
+            runtime = await inspectCaptureRuntime(runtimeRoot, defaultCapturePins);
+        }
+        catch (error) {
+            const code = errorCode(error, 'runtime-missing');
+            throw Object.assign(Error(code), { code });
+        }
+        if (args.command === 'import') {
+            const report = await importAction(store, args.positional[0], { runtime, dryRun: args.flags.apply !== true, limit: Number(args.flags.limit ?? 20), offset: Number(args.flags.offset ?? 0), signal: controller.signal });
+            emit({ report });
+            return controller.signal.aborted ? 130 : report.entries.some(entry => entry.status === 'failed' || entry.status === 'unsupported') ? 3 : 0;
+        }
+        let asrRuntime;
+        try {
+            asrRuntime = await inspectNative('asr', nativeRoot, version);
+        }
+        catch (error) {
+            if (!['runtime-missing', 'unsupported'].includes(errorCode(error, 'integrity')))
+                throw error;
+        }
+        const workerOptions = { asrRuntime, language: args.flags.language, forceLocal: args.flags['force-local'] === true, runtime, jobId, signal: controller.signal, allowPrivateNetwork: args.flags['allow-private-network'] === true, resolveConnection: (realm) => { if (realm === 'public')
+                return undefined; const connection = connections.find(c => c.realm === realm); if (!connection)
+                throw Object.assign(Error('repair-auth'), { code: 'repair-auth' }); return connection.capture; } };
+        const results = await drainLibrary(store, workerOptions);
+        if (jobId && !results.length && !controller.signal.aborted) {
+            const job = store.listJobs().find(j => j.id === jobId);
+            const code = job?.state === 'cancelled' ? 'cancelled' : job?.state === 'cleanup-pending' ? 'cleanup-required' : job?.state === 'running' ? 'owner-busy' : errorCode({ code: job?.reason }, 'unclassified');
+            throw Object.assign(Error(code), { code });
+        }
+        let indexResults = [];
+        if (args.command === 'run' && !controller.signal.aborted && store.listJobs().some(job => job.operation === 'index' && job.state === 'queued')) {
+            const embedding = await inspectNative('embedding', nativeRoot, version);
+            indexResults = await drainIndexQueue(store, { runtime: embedding, signal: controller.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 (controller.signal.aborted)
+            return 130;
+        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;
+    }
+    catch (error) {
+        const value = error?.code, code = value && codes.has(value) ? value : 'unclassified';
+        process.stderr.write(JSON.stringify(failure(requestId, code)) + '\n');
+        return exitFor(code);
+    }
+    finally {
+        store?.close();
+        process.off('SIGINT', cancel);
+        process.off('SIGTERM', cancel);
+    }
+}

package/dist/src/cli/portability.d.ts

@@ -0,0 +1,9 @@
+import type { LibraryStore } from '../store/index.js';
+import { restoreLibrary } from '../portability/backup.js';
+export declare function portabilityAction(store: LibraryStore, action: 'export' | 'backup' | 'gc', options: {
+    itemId?: string;
+    output?: string;
+    dryRun?: boolean;
+    report?: string;
+}): Promise<Record<string, unknown>>;
+export declare const restoreAction: typeof restoreLibrary;

package/dist/src/cli/portability.js

@@ -0,0 +1,39 @@
+import { fstatSync, closeSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { StoreError } from '../store/types.js';
+import { openRead, readExact, writePrivateExclusive } from '../portability/files.js';
+import { backupLibrary, restoreLibrary } from '../portability/backup.js';
+import { exportItem } from '../portability/export.js';
+import { createGcReport, applyGcReport } from '../portability/gc.js';
+export async function portabilityAction(store, action, options) {
+    if (action === 'export') {
+        if (!options.itemId || !options.output)
+            throw new StoreError('invalid-input');
+        return exportItem(store, options.itemId, options.output);
+    }
+    if (action === 'backup') {
+        if (!options.output)
+            throw new StoreError('invalid-input');
+        return backupLibrary(store, options.output);
+    }
+    if (action !== 'gc' || Boolean(options.dryRun) === Boolean(options.report))
+        throw new StoreError('invalid-input');
+    if (options.dryRun) {
+        const report = createGcReport(store), path = join(store.root, 'runtime', `gc-${randomUUID()}.json`);
+        writePrivateExclusive(path, JSON.stringify(report) + '\n');
+        return { report: path, candidates: report.candidates.length, bytes: report.candidates.reduce((n, c) => n + c.bytes, 0) };
+    }
+    const fd = openRead(options.report);
+    try {
+        const bytes = fstatSync(fd).size;
+        if (bytes > 32 * 1024 ** 2)
+            throw new StoreError('limit-exceeded');
+        return applyGcReport(store, JSON.parse(readExact(fd, bytes).toString('utf8')));
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+// Restore must dispatch before opening the normal library; it never targets the default root.
+export const restoreAction = restoreLibrary;

package/dist/src/cli/queue.d.ts

@@ -0,0 +1,2 @@
+import type { LibraryStore } from '../store/index.js';
+export declare function queueAction(store: LibraryStore, action: 'status' | 'cancel' | 'retry' | 'recover', jobId?: string): Promise<Record<string, unknown>>;

package/dist/src/cli/queue.js

@@ -0,0 +1,23 @@
+import { StoreError } from '../store/index.js';
+import { recoverWorker } from '../worker/custody.js';
+export async function queueAction(store, action, jobId) {
+    if (action === 'status') {
+        if (jobId)
+            return { jobs: store.listJobs().filter(j => j.id === jobId) };
+        return { jobs: store.listJobs(), owner: store.ownerSnapshot(), pendingCleanup: store.pendingCleanupCount() };
+    }
+    if (action === 'recover') {
+        if (jobId)
+            throw new StoreError('invalid-input');
+        return await recoverWorker(store);
+    }
+    if (!jobId)
+        throw new StoreError('invalid-input');
+    if (action === 'cancel')
+        store.requestCancellation(jobId);
+    else if (action === 'retry')
+        store.retryJob(jobId, { automatic: false });
+    else
+        throw new StoreError('invalid-input');
+    return { jobId, action };
+}

package/dist/src/cli/terminal.d.ts

@@ -0,0 +1,2 @@
+/** Neutralize terminal commands without changing redirected Markdown or stored content. */
+export declare function terminalSafe(value: string): string;

package/dist/src/cli/terminal.js

@@ -0,0 +1,4 @@
+/** Neutralize terminal commands without changing redirected Markdown or stored content. */
+export function terminalSafe(value) {
+    return value.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu, c => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'));
+}

package/dist/src/cli/worker.d.ts

@@ -0,0 +1,16 @@
+import type { LibraryStore } from '../store/index.js';
+import { drainLibrary } from '../worker/basic.js';
+import { type ServiceEnvironment } from '../service/launch-agent.js';
+export declare function workerAction(store: LibraryStore, action: 'install' | 'status' | 'uninstall', version: string, environment?: ServiceEnvironment, options?: {
+    language?: 'en';
+}): Promise<Record<string, unknown>>;
+type DrainOptions = Parameters<typeof drainLibrary>[1];
+export type ServiceDrainOptions = Omit<DrainOptions, 'runtime'> & {
+    runtime?: DrainOptions['runtime'];
+    resolveCaptureRuntime?: () => Promise<DrainOptions['runtime']>;
+};
+/** Dispatch only work that claimNext can admit; delayed retries retain their due time. */
+export declare function hasDueAcquisition(store: LibraryStore): boolean;
+export declare function drainServiceQueues(store: LibraryStore, options: ServiceDrainOptions, version: string, signal: AbortSignal): Promise<readonly unknown[]>;
+export declare function serveWorker(store: LibraryStore, options: ServiceDrainOptions, version: string, environment?: ServiceEnvironment): Promise<Record<string, unknown>>;
+export {};