@hraness/sponge 0.2.5 → 0.3.0

package/dist/src/app/source.js

@@ -1,36 +1,40 @@
-import { createHash } from 'node:crypto';
+import { sha256 } from '../util/hash.js';
 import { campaignFields, filterQuery } from '../identity/query-policy.js';
-export class InputError extends Error {
-    code = 'invalid-input';
-    constructor() { super('invalid-input'); }
-}
+import { SpongeError } from '../errors.js';
 /** Identity normalization removes only known campaign fields; private realms remain distinct. */
 function webSource(locator, realm, kind) {
-    if (Buffer.byteLength(locator) > 8192 || !realm || Buffer.byteLength(realm) > 256 || /[\u0000-\u001f\u007f]/u.test(locator + realm))
-        throw new InputError();
+    if (Buffer.byteLength(locator) > 8192 ||
+        !realm ||
+        Buffer.byteLength(realm) > 256 ||
+        /[\u0000-\u001f\u007f]/u.test(locator + realm))
+        throw new SpongeError('invalid-input');
     const normalized = normalizeWebLocator(locator);
-    const sourceKey = createHash('sha256').update(JSON.stringify([kind, realm, normalized])).digest('hex');
+    const sourceKey = sha256(JSON.stringify([kind, realm, normalized]));
     return { sourceKey, locator, realm };
 }
 /** The identity form of an http(s) locator; source keys and shareable URIs both use it. Its output pins every existing source key. */
 export function normalizeWebLocator(locator) {
     if (Buffer.byteLength(locator) > 8192 || /[\u0000-\u001f\u007f]/u.test(locator))
-        throw new InputError();
+        throw new SpongeError('invalid-input');
     let url;
     try {
         url = new URL(locator);
     }
     catch {
-        throw new InputError();
+        throw new SpongeError('invalid-input');
     }
     if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || !url.hostname)
-        throw new InputError();
+        throw new SpongeError('invalid-input');
     // Undecodable keys are kept: they cannot be campaign fields.
     if (url.search)
-        url.search = filterQuery(url.search, key => campaignFields.has(key));
+        url.search = filterQuery(url.search, (key) => campaignFields.has(key));
     // URL normalizes host casing/default ports. Preserve query order, unknown fields and fragments.
     return url.href;
 }
-export function articleSource(locator, realm = 'public') { return webSource(locator, realm, 'article'); }
+export function articleSource(locator, realm = 'public') {
+    return webSource(locator, realm, 'article');
+}
 /** A page and its media can be saved independently without changing existing article identities. */
-export function mediaSource(locator, realm = 'public') { return webSource(locator, realm, 'media'); }
+export function mediaSource(locator, realm = 'public') {
+    return webSource(locator, realm, 'media');
+}

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

@@ -1,9 +1,3 @@
-export interface Arguments {
-    command: string;
-    positional: string[];
-    flags: Record<string, string | true>;
-    library?: string;
-    json: boolean;
-}
-/** No shell grammar, implicit option coercion, duplicate flags, or unbounded argv. */
+import { type Arguments } from './commands.js';
+/** No shell grammar, implicit option coercion, duplicate flags, or unbounded argv. Commands and their rules live in the registry. */
 export declare function parseArguments(argv: string[]): Arguments;

package/dist/src/cli/arguments.js

@@ -1,47 +1,30 @@
 import { isAbsolute } from 'node:path';
-import { InputError } from '../app/source.js';
-import { reviewSpec } from './digest.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', runtimes: 'boolean' } },
-    worker: { count: 1, flags: { language: 'value', 'force-local': 'boolean' } },
-    index: { count: -1, flags: { profile: 'value', keep: 'value', 'dry-run': 'boolean', vacuum: 'boolean' } },
-    visibility: { count: 2, flags: {} },
-    highlight: { count: 2, flags: { note: 'value', occurrence: 'value' } },
-    comment: { count: 2, flags: { on: 'value' } },
-    publish: { count: 0, flags: { 'dry-run': 'boolean', output: 'value', 'min-age-days': 'value', title: 'value', 'base-url': 'value' } },
-    digest: { count: 1, flags: { endpoint: 'value', model: 'value', 'check-support': 'boolean' } },
-    review: { count: 1, flags: { accept: 'value', reject: 'value' } },
-    import: { count: -1, flags: { apply: 'boolean', 'dry-run': 'boolean', limit: 'value', offset: 'value' } },
+import { SpongeError } from '../errors.js';
+import { command as lookup, commands } from './commands.js';
+const globals = {
+    library: 'value',
+    json: 'boolean',
+    debug: 'boolean',
+    help: 'boolean',
 };
-/** No shell grammar, implicit option coercion, duplicate flags, or unbounded argv. */
+/** 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 } : {} });
+};
+/** No shell grammar, implicit option coercion, duplicate flags, or unbounded argv. Commands and their rules live in the registry. */
 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 > 32 || argv.some((arg) => Buffer.byteLength(arg) > 8192 || /[\u0000-\u001f\u007f]/u.test(arg)))
+        usage();
+    if (argv.length === 0 || (argv.length === 1 && ['--help', '-h'].includes(argv[0])))
+        return { command: 'help', positional: [], flags: {}, json: false, debug: false };
     if (argv.length === 1 && argv[0] === '--version')
-        return { command: 'version', positional: [], flags: {}, json: false };
+        return { command: 'version', positional: [], flags: {}, json: false, debug: 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))
+    const allFlags = { ...globals };
+    for (const spec of commands)
         Object.assign(allFlags, spec.flags);
     let literal = false;
     for (let i = 0; i < argv.length; i++) {
@@ -52,15 +35,15 @@ export function parseArguments(argv) {
         }
         if (arg.startsWith('--') && !literal) {
             const key = arg.slice(2);
-            const kind = (command && specifications[command]?.flags[key]) ?? allFlags[key];
+            const kind = lookup(command)?.flags[key] ?? allFlags[key];
             if (!kind || Object.hasOwn(flags, key))
-                throw new InputError();
+                usage(command);
             if (kind === 'boolean')
                 flags[key] = true;
             else {
                 const value = argv[++i];
                 if (!value || value.startsWith('--'))
-                    throw new InputError();
+                    usage(command);
                 flags[key] = value;
             }
         }
@@ -69,55 +52,59 @@ export function parseArguments(argv) {
         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 === 'import' ? !(positional.length === 1 || positional[0] === 'jungle' && positional.length === 2) : command === 'index' ? !(['create', 'run', 'prune'].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 spec = lookup(command);
+    if (!command && flags.help)
+        return { command: 'help', positional: [], flags: {}, json: false, debug: flags.debug === true };
+    if (!command || !spec)
+        return usage();
+    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))
+        usage(command);
+    if (Object.keys(flags).some((key) => !Object.hasOwn(globals, key) && !Object.hasOwn(spec.flags, key)))
+        usage(command);
+    if (spec.check && !spec.check(positional, flags))
+        usage(command);
     const library = flags.library;
     if (library !== undefined && (typeof library !== 'string' || !isAbsolute(library)))
-        throw new InputError();
+        usage(command);
     if (flags.kind && !['article', 'pdf', 'media'].includes(String(flags.kind)))
-        throw new InputError();
+        usage(command);
     if (flags.format && !['markdown', 'json'].includes(String(flags.format)))
-        throw new InputError();
+        usage(command);
     if (flags.mode && !['lexical', 'hybrid'].includes(String(flags.mode)))
-        throw new InputError();
-    if (flags.limit && (!/^[1-9]\d{0,3}$/u.test(String(flags.limit)) || Number(flags.limit) > (command === 'import' && positional[0] === 'jungle' ? 1000 : 100)))
-        throw new InputError();
-    if (command === 'run' && !flags.drain || command === 'setup' && [flags.capture, flags.asr, flags.embedding].filter(Boolean).length !== 1)
-        throw new InputError();
+        usage(command);
+    if (flags.limit &&
+        (!/^[1-9]\d{0,3}$/u.test(String(flags.limit)) ||
+            Number(flags.limit) > (command === 'import' && positional[0] === 'jungle' ? 1000 : 100)))
+        usage(command);
     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' && (flags.runtimes ? flags.apply !== undefined : 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.at(-1)) || flags.apply && flags['dry-run'] || flags.offset !== undefined && !/^(0|[1-9][0-9]{0,5})$/.test(String(flags.offset))))
-        throw new InputError();
-    if (command === 'visibility' && !['public', 'private', 'default'].includes(positional[1]) || command === 'publish' && (Boolean(flags['dry-run']) === Boolean(flags.output) || flags.output !== undefined && (typeof flags.output !== 'string' || !isAbsolute(flags.output)) || (flags.title !== undefined || flags['base-url'] !== undefined) && !flags.output || flags['min-age-days'] !== undefined && !/^(0|[1-9][0-9]{0,3})$/.test(String(flags['min-age-days'])) || Number(flags['min-age-days'] ?? 0) > 3650 || flags.title !== undefined && String(flags.title).length > 200 || flags['base-url'] !== undefined && !/^https:\/\//.test(String(flags['base-url']))))
-        throw new InputError();
-    if (command === 'digest' && (Boolean(flags.endpoint) !== Boolean(flags.model) || flags['check-support'] && !flags.endpoint || flags.model !== undefined && !/^[\w.:/@+-]{1,256}$/.test(String(flags.model))))
-        throw new InputError();
-    if (command === 'review' && (flags.accept === undefined && flags.reject === undefined || [flags.accept, flags.reject].some(v => v !== undefined && !reviewSpec.test(String(v)))))
-        throw new InputError();
+        usage(command);
     if (flags.occurrence !== undefined && !/^(0|[1-9][0-9]{0,4})$/.test(String(flags.occurrence)))
-        throw new InputError();
+        usage(command);
     if (flags.language !== undefined && flags.language !== 'en')
-        throw new InputError();
+        usage(command);
     if (flags['force-local'] && command === 'worker' && positional[0] === 'install')
-        throw new InputError();
+        usage(command);
     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 (command === 'index' && positional[0] !== 'prune' && (flags.keep !== undefined || flags['dry-run'] || flags.vacuum) || flags.keep !== undefined && !/^(0|[1-9]|1[0-6])$/.test(String(flags.keep)))
-        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' };
+        usage(command);
+    if ((flags.language || flags['force-local']) &&
+        ((['add', 'refresh'].includes(command) && !flags.wait) ||
+            (command === 'worker' && !['serve', 'install'].includes(positional[0]))))
+        usage(command);
+    if (flags.keep !== undefined && !/^(0|[1-9]|1[0-6])$/.test(String(flags.keep)))
+        usage(command);
+    if (flags.profile &&
+        (!(command === 'search' ||
+            (command === 'index' && (positional[0] === 'create' || (positional[0] === 'status' && positional.length === 1)))) ||
+            !/^[a-zA-Z0-9_-]{1,128}$/.test(String(flags.profile))))
+        usage(command);
+    return {
+        command,
+        positional,
+        flags,
+        library: library,
+        json: flags.json === true || flags.format === 'json',
+        debug: flags.debug === true,
+    };
 }

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

@@ -0,0 +1,42 @@
+import type { LibraryStore } from '../store/index.js';
+/** A parsed command line (see `arguments.ts`). */
+export interface Arguments {
+    command: string;
+    positional: string[];
+    flags: Record<string, string | true>;
+    library?: string;
+    json: boolean;
+    debug: boolean;
+}
+type Flags = Arguments['flags'];
+export interface Context {
+    args: Arguments;
+    store: LibraryStore;
+    version: string;
+    signal: AbortSignal;
+    emit: (data: unknown, text?: string) => void;
+    write: (text: string | Uint8Array) => void;
+    captureRoot: string;
+    nativeRoot: string;
+}
+export interface Command {
+    name: string;
+    summary: string;
+    /** Help lines: [synopsis without `sponge`, description]. */
+    usage: readonly (readonly [string, string])[];
+    /** Positional count, or a predicate over the positionals. */
+    positional: number | ((p: string[]) => boolean);
+    flags: Readonly<Record<string, 'value' | 'boolean'>>;
+    /** Command-specific usage rules beyond arity and flag names; false is a usage error. */
+    check?: (p: string[], f: Flags) => boolean;
+    /** none: no library; create: init may create it; open: an existing library. */
+    library: 'none' | 'create' | 'open';
+    handler: (c: Context) => Promise<number> | number;
+}
+export declare const commands: readonly Command[];
+export declare const command: (name: string | undefined) => Command | undefined;
+export declare function help(): string;
+/** One command's synopsis lines; also the hint printed for its usage errors. */
+export declare const usageOf: (name: string) => string;
+export declare function commandHelp(name: string): string;
+export {};