@hraness/sponge 0.6.5 → 0.6.7

package/dist/src/cli/arguments.js

@@ -8,8 +8,10 @@ const globals = {
     help: 'boolean',
 };
 /** A usage error names its command so the CLI can print that command's synopsis. */
-const usage = (command) => {
-    throw new SpongeError('invalid-input', { detail: command ? { command } : {} });
+const usage = (command, unknown) => {
+    throw new SpongeError('invalid-input', {
+        detail: { usage: true, ...(command ? { command } : {}), ...(unknown ? { unknown } : {}) },
+    });
 };
 /** No shell grammar, implicit option coercion, duplicate flags, or unbounded argv. Commands and their rules live in the registry. */
 export function parseArguments(argv) {
@@ -56,7 +58,7 @@ export function parseArguments(argv) {
     if (!command && flags.help)
         return { command: 'help', positional: [], flags: {}, json: false, debug: flags.debug === true };
     if (!command || !spec)
-        return usage();
+        return usage(undefined, command);
     if (flags.help)
         return { command: 'help', positional: [spec.name], flags: {}, json: false, debug: flags.debug === true };
     if (typeof spec.positional === 'number' ? positional.length !== spec.positional : !spec.positional(positional))

package/dist/src/cli/commands.js

@@ -4,7 +4,7 @@ import { connectionFor, readConnections } from './config.js';
 import { pdfSource } from '../pdf/index.js';
 import { articleSource, inferKind, mediaSource } from '../app/source.js';
 import { pdfToolsAvailable } from '../pdf/tools.js';
-import { queueAction } from './queue.js';
+import { queueAction, queueText } from './queue.js';
 import { portabilityAction } from './portability.js';
 import { restoreLibrary } from '../portability/backup.js';
 import { workerAction, serveWorker, hasDueAcquisition, workerDoctor } from './worker.js';
@@ -234,7 +234,8 @@ export const commands = [
         flags: {},
         library: 'open',
         handler: async (c) => {
-            c.emit(await queueAction(c.store, c.args.positional[0], c.args.positional[1]));
+            const action = c.args.positional[0], result = await queueAction(c.store, action, c.args.positional[1]);
+            c.emit(result, queueText(c.store, action, result));
             return 0;
         },
     },
@@ -784,7 +785,12 @@ export const commands = [
     {
         name: 'review',
         summary: 'Accept or reject digest fields',
-        usage: [['review DIGEST --accept SPEC --reject SPEC', 'Review fields: all, gist, idea:N, quote:N.M']],
+        usage: [
+            [
+                'review DIGEST --accept SPEC --reject SPEC',
+                'Review fields: all, gist, idea:N, quote:N.M, as `sponge digest ITEM` labels them',
+            ],
+        ],
         positional: 1,
         flags: { accept: 'value', reject: 'value' },
         library: 'open',

package/dist/src/cli/main.js

@@ -4,20 +4,43 @@ import { lstat } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import { terminalSafe } from './terminal.js';
 import { parseArguments } from './arguments.js';
-import { command, usageOf } from './commands.js';
+import { command, commands, usageOf } from './commands.js';
 import { openLibrary } from '../store/index.js';
 import { failure } from '../acquisition/errors.js';
 import { SpongeError, codeOf, publicCode, exitFor, hints, detailHints, debugChain, } from '../errors.js';
+/** Names the registered command closest to a mistyped one, never the typed text, which may hold a URL or a secret. */
+function unknownCommandHint(typed) {
+    const distance = (a, b) => {
+        let row = Array.from({ length: b.length + 1 }, (_, j) => j);
+        for (let i = 1; i <= a.length; i++) {
+            const next = [i];
+            for (let j = 1; j <= b.length; j++)
+                next[j] = Math.min(row[j] + 1, next[j - 1] + 1, row[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+            row = next;
+        }
+        return row[b.length];
+    };
+    const [best] = commands
+        .map((c) => ({ name: c.name, d: distance(typed.toLowerCase().slice(0, 32), c.name) }))
+        .filter(({ d }) => d <= 2)
+        .sort((a, b) => a.d - b.d);
+    return `Unknown command.${best ? ` Did you mean \`sponge ${best.name}\`?` : ''} Run \`sponge help\` for the list.`;
+}
 /** Failures print one categorical JSON line: the public code, its specific `reason` when narrower, and a fixed hint.
  * Causes, details, paths and upstream messages appear only with --debug or SPONGE_DEBUG=1. */
 function report(error, requestId, debug) {
-    const reason = codeOf(error), code = publicCode(reason), issues = error?.issues, usage = error?.detail?.command;
+    const reason = codeOf(error), code = publicCode(reason), issues = error?.issues, detail = error?.detail, usage = detail?.command, unknown = detail?.unknown;
     if (Array.isArray(issues))
         process.stderr.write(JSON.stringify({ issues }) + '\n');
     const hint = code === 'invalid-input' && typeof usage === 'string' && command(usage)
         ? `Usage: ${usageOf(usage).replace(/\n/g, ' | ')}`
-        : (detailHints[reason] ?? hints[code]);
-    process.stderr.write(JSON.stringify({ ...failure(requestId, code), ...(reason !== code ? { reason } : {}), hint }) + '\n');
+        : code === 'invalid-input' && typeof unknown === 'string'
+            ? unknownCommandHint(unknown)
+            : (detailHints[reason] ?? hints[code]);
+    // A usage error happens before any acquisition starts, so it names no phase.
+    const { phase, ...envelope } = failure(requestId, code);
+    process.stderr.write(JSON.stringify({ ...envelope, ...(detail?.usage ? {} : { phase }), ...(reason !== code ? { reason } : {}), hint }) +
+        '\n');
     if (debug)
         process.stderr.write(debugChain(error));
     return exitFor(code);

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

@@ -1,2 +1,4 @@
 import type { LibraryStore } from '../store/index.js';
 export declare function queueAction(store: LibraryStore, action: 'status' | 'cancel' | 'retry' | 'recover', jobId?: string): Promise<Record<string, unknown>>;
+/** `sponge queue` without --json: open jobs with the IDs that cancel and retry take, then what was done. */
+export declare function queueText(store: LibraryStore, action: 'status' | 'cancel' | 'retry' | 'recover', result: Record<string, unknown>): string;

package/dist/src/cli/queue.js

@@ -1,5 +1,6 @@
 import { recoverWorker } from '../worker/custody.js';
 import { SpongeError } from '../errors.js';
+import { openJobs } from './status.js';
 export async function queueAction(store, action, jobId) {
     if (action === 'status') {
         if (jobId)
@@ -25,3 +26,24 @@ export async function queueAction(store, action, jobId) {
         throw new SpongeError('invalid-input');
     return { jobId, action };
 }
+/** `sponge queue` without --json: open jobs with the IDs that cancel and retry take, then what was done. */
+export function queueText(store, action, result) {
+    if (action === 'cancel')
+        return `Cancelled ${String(result.jobId)}`;
+    if (action === 'retry')
+        return `Queued ${String(result.jobId)} to run again`;
+    if (action === 'recover')
+        return result.recovered
+            ? `Recovered the stopped worker; ${String(result.attempts)} unfinished attempts released`
+            : 'Nothing to recover';
+    const jobs = result.jobs, open = openJobs(store), titles = new Map(store.list().map((item) => [item.itemId, item.title])), lines = open.length ? open.map((job) => jobLine(job, titles.get(job.item_id))) : ['Nothing waiting'];
+    if (jobs.length > open.length)
+        lines.push(`${jobs.length - open.length} settled or replaced jobs hidden; --json lists every job`);
+    if (result.pendingCleanup)
+        lines.push(`Pending cleanup: ${String(result.pendingCleanup)}; run sponge queue recover`);
+    return lines.join('\n');
+}
+function jobLine(job, title) {
+    const reason = job.reason && job.reason !== job.state ? ` (${String(job.reason)})` : '';
+    return `${String(job.id)}  ${String(job.operation)} ${String(job.state)}${reason}  ${String(job.created_at).slice(0, 10)}${title ? `  ${title}` : ''}`;
+}

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

@@ -1,4 +1,10 @@
 import type { LibraryStore } from '../store/index.js';
+import type { Row } from '../store/context.js';
+/**
+ * Jobs still waiting, running or needing the reader, oldest first. Settled jobs are history, and only each target's
+ * newest job counts: a failure that a later capture of the item (or index job) fixed is history too.
+ */
+export declare function openJobs(store: LibraryStore): Row[];
 /** What the library holds, what is waiting or failed, and what to run next: one screen for `sponge status`. */
 export declare function libraryStatus(store: LibraryStore): {
     items: {
@@ -19,7 +25,7 @@ export declare function libraryStatus(store: LibraryStore): {
     jobs: {
         operation: string;
         state: string;
-        reason: string | null;
+        reason: string;
     }[];
     pendingCleanup: number;
 };

package/dist/src/cli/status.js

@@ -1,20 +1,23 @@
+/**
+ * Jobs still waiting, running or needing the reader, oldest first. Settled jobs are history, and only each target's
+ * newest job counts: a failure that a later capture of the item (or index job) fixed is history too.
+ */
+export function openJobs(store) {
+    const newest = new Map();
+    for (const job of store.queue.list())
+        newest.set(job.operation === 'index' ? 'index' : `${job.operation} ${job.item_id}`, job);
+    return [...newest.values()].filter((job) => !['succeeded', 'cancelled'].includes(String(job.state)));
+}
 const plural = (n, one, many = one + 's') => `${n} ${n === 1 ? one : many}`;
 /** What the library holds, what is waiting or failed, and what to run next: one screen for `sponge status`. */
 export function libraryStatus(store) {
     const items = store.list(), kinds = {}, digests = { accepted: 0, rejected: 0, draft: 0, none: 0 };
     for (const item of items) {
         kinds[item.kind] = (kinds[item.kind] ?? 0) + 1;
-        const gist = store.derivations.current('digest', item.itemId)?.review.gist;
-        digests[gist === undefined ? 'none' : gist === 'accepted' || gist === 'rejected' ? gist : 'draft']++;
+        const digest = store.derivations.current('digest', item.itemId), gist = digest?.review.gist;
+        digests[!digest ? 'none' : gist === 'accepted' || gist === 'rejected' ? gist : 'draft']++;
     }
-    // Settled jobs are history; what is left is waiting, running or needs the reader.
-    // Only each target's newest job counts: a failure that a later capture of the item (or index job) fixed is history.
-    const newest = new Map();
-    for (const job of [...store.queue.list()].sort((a, b) => String(a.created_at).localeCompare(String(b.created_at))))
-        newest.set(job.operation === 'index' ? 'index' : `${job.operation} ${job.item_id}`, job);
-    const jobs = [...newest.values()]
-        .filter((job) => !['succeeded', 'cancelled'].includes(String(job.state)))
-        .map((job) => ({
+    const jobs = openJobs(store).map((job) => ({
         operation: String(job.operation),
         state: String(job.state),
         reason: job.reason ?? null,
@@ -38,7 +41,7 @@ export function statusText(s, worker) {
     };
     const counts = {};
     for (const job of s.jobs) {
-        const key = `${job.operation} ${job.state}${job.reason ? ` (${job.reason})` : ''}`;
+        const key = `${job.operation} ${job.state}${job.reason && job.reason !== job.state ? ` (${job.reason})` : ''}`;
         counts[key] = (counts[key] ?? 0) + 1;
     }
     const failed = s.jobs.some((job) => !['queued', 'running'].includes(job.state));

package/native/runtime-manifest.json

@@ -33,16 +33,16 @@
     }
   ],
   "build": {
-    "asrSourceSha256": "2a727a104fc5eba495f7cb10e6b6c8f6d98618d3db37388fd461371a3af36a77",
+    "asrSourceSha256": "628996352def6d14b40a212f23096045a9ac8a9cf14a8a1e11bbd4f57971c37d",
     "clangVersion": "Apple clang version 21.0.0 (clang-2100.1.1.101)",
-    "embeddingSourceSha256": "cbb35b81a245f565cb084ddf6dd9cddf3afb38e2838d1552871a9d7035389936",
-    "mediaSourceSha256": "463089ae614d0f73f8dbf600fb6c8886991b63cdec27e3aa9cfeb564d6f2981e",
+    "embeddingSourceSha256": "ca177874aa881521ee9235a7dedc243608be15d5a96f0fff4430f4d7a6c2c64e",
+    "mediaSourceSha256": "4b5113123a6e6f5b00de76ae42c4969f650a1093bc1f99ddf70177f815a65851",
     "rustcVersion": "rustc 1.97.1 (8bab26f4f 2026-07-14)",
     "swiftVersion": "Apple Swift version 6.3.3 (swiftlang-6.3.3.1.3 clang-2100.1.1.101)"
   },
   "minimumMacOS": "26.0",
-  "packageVersion": "0.6.5",
+  "packageVersion": "0.6.7",
   "platform": "darwin",
   "schemaVersion": 1,
-  "sourceCommit": "16eca3fb320f29dfb99de79ffd051c491258b93c"
+  "sourceCommit": "60a3273cf828ae3c4ef0c6a3db1ea15984f00d34"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/sponge",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "A local library for captured articles and verified offline assets.",
   "repository": {
     "type": "git",