funoteka 0.1.0

package/dist/classify/roles.js

@@ -0,0 +1,277 @@
+import { classifyFile } from "../scan/kinds.js";
+import { compareNatural, stemOf } from "../util/names.js";
+/**
+ * What a cue and the image it describes have in common, so that they pair.
+ *
+ * One convention, written two ways, both of them in the collection: ASOT ships
+ * `… - Pulse.cue` beside `… - Pulse.mp3`, and the Maschina Kino rips ship
+ * `… CD1.flac.cue` beside `… CD1.flac`. The first names its disc by stem. The
+ * second leaves the audio's own extension on, and `stemOf` — which strips
+ * exactly one extension, deliberately — reads that as a disc called
+ * `… CD1.flac`, which shares a name with nothing. On MASHCD290 that cost every
+ * disc past the first: the folder read as one album of two images, and 30
+ * declared tracks became 2 (task:2708).
+ *
+ * So the extension comes off twice, and the second time only when what is left
+ * is audio. `X.log.cue` is a cue about a log, not a disc called `X.log`, and
+ * `Opiate FLAC.cue` — the rip that kept two cues and one image — is a name of
+ * its own rather than a partner for `Opiate.flac`.
+ *
+ * Exported because there are two places that pair a cue with its image, and
+ * they were reading the evidence differently: this module's flat-disc detector
+ * read names from the walk, and `cue/engine.ts` read them from the database.
+ * One of them understanding `X.flac.cue` and the other not is how MASHCD290
+ * became a release of two discs of which only the first had tracks (task:2708).
+ */
+export function pairKey(file) {
+    const named = stemOf(file.name);
+    const audioRemoved = classifyFile(named) === 'audio' ? stemOf(named) : named;
+    return audioRemoved.toLowerCase();
+}
+/**
+ * A multi-disc release laid out flat: one image and one cue per disc, side by
+ * side in a single folder, no subfolders at all.
+ *
+ * They pair by name — an image and a cue that name the same disc are one disc
+ * (`pairKey` above has the two writings this has to read). Requiring exactly
+ * one cue and one audio per name keeps a normal album out of this: `FLAC.cue` +
+ * `WAV.cue` + `Opiate.flac` keys as `flac`, `wav`, `opiate`, none of them with
+ * both, so it stays an ordinary album.
+ *
+ * Ordered the way a person would read the disc numbers, not lexicographically.
+ */
+export function flatDiscPairs(files) {
+    const byStem = new Map();
+    for (const file of files) {
+        if (file.kind !== 'cue' && file.kind !== 'audio')
+            continue;
+        const stem = pairKey(file);
+        const bucket = byStem.get(stem) ?? { cues: [], audio: [] };
+        (file.kind === 'cue' ? bucket.cues : bucket.audio).push(file);
+        byStem.set(stem, bucket);
+    }
+    const pairs = [];
+    for (const bucket of byStem.values()) {
+        const cue = bucket.cues[0];
+        const audio = bucket.audio[0];
+        if (bucket.cues.length === 1 && bucket.audio.length === 1 && cue !== undefined && audio !== undefined) {
+            pairs.push({ cue, audio });
+        }
+    }
+    return pairs.sort((a, b) => compareNatural(a.audio.name, b.audio.name));
+}
+/** `CD1`, `CD 1`, `Disc 03`, `d2` — a folder whose whole name is a disc number. */
+const DISC_NAME = /^(?:cd|disc|disk|d)\s*[._-]?\s*(\d{1,2})$/i;
+/**
+ * Does this folder name say it is a disc?
+ *
+ * Two shapes say yes, and both are real. A folder may be nothing *but* the
+ * number — `CD1`, `d2` — which is `DISC_NAME`, anchored, because loose it would
+ * read the `d1` of `1971 - d1` as a disc. Or it may lead with the number and
+ * then name the record: `CD1 ● Группа крови`, how Maschina Records lays out a
+ * Kino box. Not a whole name any more, but a disc just as plainly — and the
+ * anchored read called nine of the ten Kino boxes plain category folders.
+ *
+ * `discMarker` below already read that shape in file names and cue titles; only
+ * the folder question was still anchored. A box folder must keep answering no:
+ * `…, MKK821CD, 3CD)` is a release, and both `\b` guards hold there — in
+ * `MKK821CD` the `cd` follows a letter, and `3CD)` has no digits after it.
+ */
+export function isDiscName(name) {
+    const text = name.trim();
+    return DISC_NAME.test(text) || discMarker(text) !== null;
+}
+/**
+ * A folder named like a box set.
+ *
+ * Structural detection is preferred and runs first — `CD1`, `CD2`, or several
+ * image+cue pairs, are far stronger evidence than a word. This only catches
+ * what structure misses: a box whose discs are named after their albums
+ * (`The Wall`, `Animals`) rather than numbered. Their disc numbers then come
+ * from order, since the names carry none.
+ *
+ * There is deliberately no `Albums -> category` predicate. A folder holding
+ * only albums is already a category structurally, so the name would add a
+ * second rule that can never disagree with the first.
+ */
+const BOX_NAME = /^(?:box|box[ _-]?set|set)$/i;
+export function isBoxName(name) {
+    return BOX_NAME.test(name.trim());
+}
+/**
+ * How many discs a folder name says it holds, or null when it says nothing.
+ *
+ * `The Cure - Assemblage - 1991 (12CD FLAC)` states twelve and `(2CD)` two, and
+ * that is the only evidence some boxes give: their discs are named after the
+ * albums on them (`01 - Three Imaginary Boys (1979)`), not after their numbers,
+ * so nothing structural marks them as discs at all.
+ *
+ * The digits have to stand on their own, the way a disc number does and for the
+ * same reason. `MKK821CD` is a catalogue number, and reading `21CD` out of its
+ * middle would make a box of a folder that never claimed one — so neither a
+ * letter nor a digit may sit in front of the run.
+ */
+const STATED_DISCS = /(?<![\p{L}\p{N}])(\d+)\s*cd\b/iu;
+export function statedDiscCount(name) {
+    const digits = STATED_DISCS.exec(name.trim())?.[1];
+    return digits === undefined ? null : Number.parseInt(digits, 10);
+}
+/**
+ * The number a disc folder states, or null when it states none.
+ *
+ * Anchored form first, then the marker — so `CD1 ● Альбом` numbers itself
+ * instead of waiting on where it sits. A stated number outranks an ordinal, the
+ * same way it does for a flat pair in `classify.ts`; a disc named after its
+ * album states nothing and still falls to its position.
+ */
+export function discNumber(name) {
+    const text = name.trim();
+    const anchored = DISC_NAME.exec(text)?.[1];
+    if (anchored !== undefined)
+        return Number.parseInt(anchored, 10);
+    return discMarker(text);
+}
+/**
+ * `Disc 1`, `[Disc 2]`, `(Disc 03)` — a marker written *anywhere* in a name.
+ *
+ * `DISC_NAME` above reads a folder called `CD1` and nothing else, which is the
+ * right question for a folder. Everything else names a disc differently: the
+ * marker sits in the middle, inside brackets, after the record's own name —
+ * `Pink Floyd - The Wall [Disc 1].ape`, or a cue's `TITLE "The Wall [Disc 1]"`.
+ * Requiring it at the start found nothing, and both discs of the Wall took their
+ * number from sort order instead, which happened to put the second disc first.
+ *
+ * No bare `d`, unlike `DISC_NAME`: anchored to a whole folder name `d2` is
+ * unambiguous, but loose in a name it would match any word ending in `d` that
+ * runs into a digit.
+ *
+ * The number has to stand on its own, and the lookahead is what makes it. A
+ * disc number is one number; a catalogue number is a run of them, and the head
+ * of a run is not a marker. `MEL CD 60 00842` is Melodiya's — the 842nd release
+ * of the 60 series — and reading `CD 60` out of it turned the twenty
+ * independent CDs of one series folder into twenty discs of a single box
+ * ([[task:2713]]) while giving every one of them `disc_number = 60`
+ * ([[task:2715]]). A name that follows the number costs nothing: `CD 2 - Disk
+ * Union Bonus` and `The Wall [1994 Remaster](Disc 2)` are still discs.
+ */
+const DISC_MARKER = /\b(?:disc|disk|cd)\s*[._-]?\s*(\d{1,2})\b(?!\s*\d)/i;
+export function discMarker(name) {
+    const digits = DISC_MARKER.exec(name.trim())?.[1];
+    return digits === undefined ? null : Number.parseInt(digits, 10);
+}
+/**
+ * Where the marker sits in a name, or `-1` when the name states none.
+ *
+ * The index rather than the number, because what a caller wants it for is
+ * everything *in front* of the marker: two folders that agree up to there name
+ * one set, whatever their catalogue numbers say after it.
+ */
+export function discMarkerIndex(name) {
+    return DISC_MARKER.exec(name.trim())?.index ?? -1;
+}
+function hasAudio(node) {
+    return node.files.some((file) => file.kind === 'audio');
+}
+function hasAudioDeep(node) {
+    return hasAudio(node) || node.children.some(hasAudioDeep);
+}
+/**
+ * Assign a role to every node, children first.
+ *
+ * Two rules are worth stating outright, because both were chosen to avoid
+ * inventing structure that is not there:
+ *
+ *   - A folder needs *at least two* audio-bearing CD folders beneath it to be a
+ *     box. One `CD1` is a folder name, not a release, and treating it as one
+ *     would split albums that are perfectly whole.
+ *   - Only disc folders that actually contain audio count. An empty `CD2`
+ *     left over from a bad rip must not turn its parent into a box.
+ *   - **Every** audio-bearing child has to be a disc — two is necessary and not
+ *     sufficient. A shelf of albums that happens to hold one two-disc set is not
+ *     a box: treating it as one made the artist's folder a release and every
+ *     album in it a disc, and sixteen records collapsed into two. The check
+ *     below is where that is decided, and the cost of getting it wrong is
+ *     invisible until a client is shown records rather than album rows.
+ *
+ * Audio in a folder wins over anything below it: the files are the truth.
+ */
+export function assignRoles(node) {
+    for (const child of node.children)
+        assignRoles(child);
+    // A multi-disc release with no subfolders: several image+cue pairs sitting
+    // together. Without this the folder reads as one album holding a few
+    // unrelated files, and every disc past the first loses its tracks entirely.
+    if (flatDiscPairs(node.files).length >= 2) {
+        node.role = 'box';
+        return node.role;
+    }
+    // Direct audio only. A `CD1` that merely *contains* an album folder is a
+    // wrapper, not a disc: promoting it would give a disc album with no tracks of
+    // its own, and leave the real album as one more row underneath it.
+    //
+    // **Every audio-bearing child has to be a disc**, not merely two of them. A
+    // shelf of albums that happens to hold one two-disc set is the case that
+    // decides it: `Slipknot AAC 320` holds eight records, two of which are named
+    // `2014 - .5 The Gray Chapter - CD 1 [JP - WPCR-16130]` and `… CD 2 …`. With
+    // the count alone the artist's folder became a box, all eight became *discs*
+    // of it, and — once the API started answering with records rather than album
+    // rows — sixteen records collapsed into two albums called `Slipknot AAC 320`
+    // and `Slipknot ALAC`. Measured on the live collection; the operator saw the
+    // lost releases before the cause.
+    //
+    // A real box is unharmed: its audio-bearing children are exactly its discs,
+    // and an `Artwork` or `Scans` folder beside them bears none.
+    const discChildren = node.children.filter((child) => isDiscName(child.name) && hasAudio(child));
+    const albumsAlongside = node.children.filter((child) => hasAudio(child) && !isDiscName(child.name));
+    if (discChildren.length >= 2 && albumsAlongside.length === 0) {
+        for (const child of discChildren)
+            child.role = 'disc';
+        node.role = 'box';
+        return node.role;
+    }
+    // Structural detection saw only "a folder of albums". If the folder is named
+    // like a box and holds several, it is one — the discs just are not numbered.
+    // Direct audio again: promoting a wrapper folder to a disc would leave the
+    // disc empty and the real album stranded a level below it.
+    const playableChildren = node.children.filter(hasAudio);
+    if (isBoxName(node.name) && playableChildren.length >= 2) {
+        for (const child of playableChildren)
+            child.role = 'disc';
+        node.role = 'box';
+        return node.role;
+    }
+    // A box that states how many discs it holds but does not number them.
+    //
+    // `The Cure - Assemblage - 1991 (12CD FLAC)` lays its twelve out as
+    // `01 - Three Imaginary Boys (1979)`, `02 - Boys Don't Cry (1980)`, … — no
+    // marker on any of them, so the structural rule above reads twelve albums in
+    // a folder and answers `category`. The box then does not exist as a record,
+    // and every disc is shown as one of its own with the box's name appended to
+    // it: nine records named `X (Assemblage - 1991 (12CD FLAC))`.
+    //
+    // The count is the collector's own statement, and it is *checked* rather than
+    // trusted — a folder holding a different number of records than it claims is
+    // not a box. That check is the whole safety of the rule: without it, this
+    // says "the name mentions CDs", and a shelf of rips under a folder that
+    // happens to say `2CD` becomes a release whose every record is a disc of it.
+    const stated = statedDiscCount(node.name);
+    if (stated !== null && stated >= 2) {
+        const records = node.children.filter(hasAudio);
+        if (records.length === stated && records.every((child) => !isDiscName(child.name))) {
+            for (const child of records)
+                child.role = 'disc';
+            node.role = 'box';
+            return node.role;
+        }
+    }
+    if (hasAudio(node)) {
+        node.role = 'album';
+        return node.role;
+    }
+    if (node.children.some(hasAudioDeep)) {
+        node.role = 'category';
+        return node.role;
+    }
+    node.role = 'empty';
+    return node.role;
+}

package/dist/classify/shelf-name.js

@@ -0,0 +1,178 @@
+import { withTransaction } from "../db/index.js";
+import { basenameOf, folderOf } from "../util/names.js";
+/**
+ * Say which shelf a record came from — in the record's name, and last.
+ *
+ * A collector who keeps two rips of one album (`Slipknot AAC 320`,
+ * `Slipknot ALAC`) has two records that agree about everything a client is
+ * shown: the same title, the same artist, the same year. The only thing
+ * separating them is the folder they sit in, and a folder is not a name. So
+ * `We Are Not Your Kind` appeared three times in the operator's library with
+ * nothing to choose between them.
+ *
+ * **Why this runs last, and not in `classify`.** Two reasons, and the second is
+ * the one that decided it:
+ *
+ *   - The qualifier is the shelf's name *minus the artist's*, and the artist is
+ *     something only the artist stage knows. `classify` writes no artists at
+ *     all, deliberately, so a rule there had to guess the name from a sibling
+ *     folder — a heuristic that named another artist's folder as this one's
+ *     (`Nirvana (UK)` beside `Nirvana` gave `(UK)`) and could not see the
+ *     ordinary `Artist/Shelf/CD1` layout at all. Here the artist is a fact.
+ *   - It must not replace the name, only extend it. The name a record is shown
+ *     by is the best one three stages could agree on — the folder's, improved
+ *     by a tag, overruled by a cue — and a qualifier written earlier would
+ *     either be thrown away by a later stage or force the *folder's* spelling
+ *     on every shelf album. Measured: the shelves' albums carry tag names the
+ *     folders do not (`Vol. 3: (The Subliminal Verses)` against `Vol. 3 (The
+ *     Subliminal Verses)`), and forcing the folder's would have cost the
+ *     collection every colon it has.
+ *
+ * Running after every stage that names anything means nothing can overrule it,
+ * and it is re-derived every run like every other name here: the stages above
+ * rewrite titles from the folder each time, so what arrives here is a fresh
+ * name and not one this stage wrote a minute ago.
+ *
+ * **It appends to the record, not to the disc.** An album that belongs to a
+ * release is a disc of it, and the record is what a client is shown — the
+ * release's title carries the qualifier, and the disc keeps the name its own
+ * folder states.
+ */
+export function nameShelfRecords(db) {
+    const counters = { shelves: 0, named: 0 };
+    // Which folders are shelves. Read once: the albums below are looked up by
+    // their parent's path, and a path is only a shelf in the root it belongs to.
+    const roles = new Map();
+    const folderRows = db
+        .prepare('SELECT root_id, rel_path, role FROM folder')
+        .all();
+    for (const row of folderRows)
+        roles.set(shelfKey(row.root_id, row.rel_path), row.role);
+    const seen = new Set();
+    const renameAlbum = db.prepare('UPDATE album SET title = ?, title_source = ? WHERE id = ?');
+    const renameRelease = db.prepare('UPDATE release SET title = ?, title_source = ? WHERE id = ?');
+    const name = (rootId, shelfPath, artist) => {
+        if (roles.get(shelfKey(rootId, shelfPath)) !== 'category')
+            return null;
+        const qualifier = qualifierOf(basenameOf(shelfPath), artist);
+        if (qualifier === null)
+            return null;
+        seen.add(shelfKey(rootId, shelfPath));
+        return qualifier;
+    };
+    // The records that are albums: a shelf's own albums, and not its discs.
+    const albums = db
+        .prepare(`SELECT a.id, a.root_id, a.rel_path, a.title, ar.name AS artist
+         FROM album a
+         LEFT JOIN artist ar ON ar.id = a.artist_id
+        WHERE a.release_id IS NULL`)
+        .all();
+    // One transaction for both passes. Without it every rename below is its own
+    // commit, and a commit is a disk flush: measured on the live collection, this
+    // stage cost **902 ms** committing each and **13 ms** with the transaction
+    // (task:2883). `db/index.ts` has the rule.
+    withTransaction(db, () => {
+        for (const row of albums) {
+            const qualifier = name(row.root_id, folderOf(row.rel_path), row.artist);
+            if (qualifier === null)
+                continue;
+            const title = qualified(row.title ?? '', qualifier);
+            if (title === row.title)
+                continue;
+            renameAlbum.run(title, 'shelf', row.id);
+            counters.named += 1;
+        }
+        // And the records that are releases: a shelf's disc set is one of these, and
+        // its title is what a client is shown for the whole group.
+        const releases = db
+            .prepare(`SELECT r.id, r.root_id, r.rel_path, r.title, ar.name AS artist
+           FROM release r
+           LEFT JOIN artist ar ON ar.id = r.artist_id`)
+            .all();
+        for (const row of releases) {
+            // A release's own artist is set by the artist stage from the credit its
+            // discs agree on; when it has none — a compilation whose files name nobody
+            // — any artist among its discs answers, because the shelf's name is what
+            // is being subtracted and that is the same for all of them.
+            const artist = row.artist ??
+                (db
+                    .prepare(`SELECT ar.name AS name FROM album a
+                 JOIN artist ar ON ar.id = a.artist_id
+                WHERE a.release_id = ? LIMIT 1`)
+                    .get(row.id)?.name ??
+                    null);
+            // The shelf *is* the release's folder — that is what the classifier keys
+            // it by — where an album's shelf is the folder above it.
+            const qualifier = name(row.root_id, row.rel_path, artist);
+            if (qualifier === null)
+                continue;
+            const title = qualified(row.title ?? '', qualifier);
+            if (title === row.title)
+                continue;
+            renameRelease.run(title, 'shelf', row.id);
+            counters.named += 1;
+        }
+    });
+    counters.shelves = seen.size;
+    return counters;
+}
+/** A folder is only the one meant when its root is, so the root is in the key. */
+function shelfKey(rootId, relPath) {
+    return `${rootId}\u0000${relPath}`;
+}
+/**
+ * What stands between an artist's name and the shelf's own word.
+ *
+ * The bullet is here for the same reason the dash is: this collection writes
+ * `Кино ● Каталог Maschina Records`, and the bullet is a separator in exactly
+ * the place a space would be. Left out of the class it became part of the note,
+ * and every record under that shelf was named `… (● Каталог Maschina Records)` —
+ * the separator carried into the name it was separating.
+ */
+const SEPARATOR = /^[\s\-_.●•]/;
+const SEPARATOR_ALL = /^[\s\-_.●•]+/;
+/**
+ * What a shelf's name says beyond the artist it holds, or null.
+ *
+ * `Slipknot AAC 320` and `Slipknot ALAC` hold different rips of the same
+ * records, and what tells them apart is `AAC 320` and `ALAC` — the artist's own
+ * name is not part of the difference, and repeating it in every name is noise.
+ *
+ * A separator has to follow the artist's name, or `S` claims `Slipknot` and
+ * `node-extract` claims `node-extract2` — both measured on the live root, as
+ * `lipknot AAC 320` and `2`. Null when nothing is left over, which is the
+ * answer for an artist's own folder: it has nothing to add to itself.
+ */
+function qualifierOf(shelfName, artistName) {
+    const shelf = shelfName.trim();
+    const artist = (artistName ?? '').trim();
+    if (artist === '' || !shelf.startsWith(artist))
+        return null;
+    const rest = shelf.slice(artist.length);
+    if (!SEPARATOR.test(rest))
+        return null;
+    const spare = rest.replace(SEPARATOR_ALL, '').trim();
+    return spare === '' ? null : spare;
+}
+/**
+ * The name with the qualifier on the end, and never on twice.
+ *
+ * The stages above rewrite every title from the folder each run, so what
+ * arrives here normally carries no qualifier — but a root the walk did not see
+ * keeps the rows it had, this stage's among them, and a name that collected a
+ * second `(AAC 320)` on every run would be a name nobody could read.
+ *
+ * The empty case is the last line's, and it is a guard rather than a path:
+ * `base` is empty exactly when the title *is* the suffix — a leading space, the
+ * qualifier, and its brackets, and nothing else. No stage writes a name like
+ * that, and none of the 426 records of the live collection carries one: the only
+ * title that is nothing but a bracket is `( )`, which has no leading space and
+ * is no qualifier (measured 2026-09-13, task:2843). It is kept because the title
+ * here can be a *tag's* — the one name this stage does not derive itself — and
+ * a guard costs a line where a missing one costs a name.
+ */
+function qualified(title, qualifier) {
+    const suffix = ` (${qualifier})`;
+    const base = title.endsWith(suffix) ? title.slice(0, -suffix.length) : title;
+    return base === '' ? `(${qualifier})` : `${base}${suffix}`;
+}

package/dist/classify/tree.js

@@ -0,0 +1,43 @@
+function byRelPath(a, b) {
+    return a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0;
+}
+/**
+ * Rebuild the folder hierarchy from the flat inventory a scan produced.
+ *
+ * The root is a virtual node: it exists even when no folder row describes it,
+ * because scanning a folder that *is* an album is normal, and its files have to
+ * land somewhere. A file naming a folder that the walk never reported gets that
+ * folder synthesised rather than dropped.
+ */
+export function buildTree(folders, files) {
+    const root = { relPath: '', name: '', files: [], children: [], role: null };
+    const index = new Map([['', root]]);
+    const ensure = (relPath) => {
+        const known = index.get(relPath);
+        if (known)
+            return known;
+        const cut = relPath.lastIndexOf('/');
+        const parentRelPath = cut === -1 ? '' : relPath.slice(0, cut);
+        const created = {
+            relPath,
+            name: relPath.slice(cut + 1),
+            files: [],
+            children: [],
+            role: null,
+        };
+        ensure(parentRelPath).children.push(created);
+        index.set(relPath, created);
+        return created;
+    };
+    for (const folder of folders)
+        ensure(folder);
+    for (const file of files)
+        ensure(file.folderRelPath).files.push(file);
+    const sortDeep = (node) => {
+        node.children.sort(byRelPath);
+        for (const child of node.children)
+            sortDeep(child);
+    };
+    sortDeep(root);
+    return root;
+}

package/dist/cli/args.js

@@ -0,0 +1,169 @@
+import { parseArgs } from 'node:util';
+/** Usage errors share a code so scripts can tell them from a failed scan. */
+const USAGE_ERROR = 2;
+const COMMANDS = new Set([
+    'scan',
+    'inventory',
+    'serve',
+    'stop',
+    'status',
+    'junk',
+    'keys',
+    'mcp',
+]);
+/** What `junk` can be asked to do, and the verdict each verb writes. */
+const JUNK_ACTIONS = new Set(['list', 'block', 'allow']);
+/** What `keys` can be asked to do. `list` takes nothing; the other two take one name. */
+const KEYS_ACTIONS = new Set(['list', 'add', 'revoke']);
+export function resolveCommand(argv) {
+    let values;
+    let positionals;
+    try {
+        ({ values, positionals } = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                db: { type: 'string' },
+                help: { type: 'boolean', short: 'h' },
+                host: { type: 'string' },
+                port: { type: 'string' },
+                daemon: { type: 'boolean' },
+                note: { type: 'string' },
+                full: { type: 'boolean' },
+                url: { type: 'string' },
+            },
+        }));
+    }
+    catch (err) {
+        return { kind: 'error', message: err.message, code: USAGE_ERROR };
+    }
+    if (values.help)
+        return { kind: 'help' };
+    const dbPath = values.db;
+    const [command, ...roots] = positionals;
+    if (command === undefined)
+        return { kind: 'error', message: 'no command given', code: USAGE_ERROR };
+    if (!COMMANDS.has(command)) {
+        return { kind: 'error', message: `unknown command "${command}"`, code: USAGE_ERROR };
+    }
+    if (command === 'serve') {
+        if (roots.length > 0) {
+            return { kind: 'error', message: 'serve takes no roots', code: USAGE_ERROR };
+        }
+        return {
+            kind: 'serve',
+            daemon: values.daemon === true,
+            dbPath: values.db,
+            host: values.host,
+            port: values.port,
+        };
+    }
+    if (command === 'mcp') {
+        if (roots.length > 0) {
+            return { kind: 'error', message: 'mcp takes no arguments', code: USAGE_ERROR };
+        }
+        return { kind: 'mcp', url: values.url };
+    }
+    if (command === 'stop' || command === 'status') {
+        if (roots.length > 0) {
+            return { kind: 'error', message: `${command} takes no roots`, code: USAGE_ERROR };
+        }
+        if (values.daemon === true) {
+            return { kind: 'error', message: `${command} takes no --daemon`, code: USAGE_ERROR };
+        }
+        return { kind: command, dbPath: values.db };
+    }
+    // Where to listen is the server's question alone. A flag accepted and ignored
+    // is worse than one refused: the operator would believe they had moved it.
+    const misplaced = [
+        ...(values.host === undefined ? [] : ['--host']),
+        ...(values.port === undefined ? [] : ['--port']),
+        ...(values.daemon === true ? ['--daemon'] : []),
+        // `--note` belongs to `junk` alone, and it is refused here rather than
+        // there because this is where every command that does not take it is
+        // checked. A flag accepted and ignored is worse than one refused: the
+        // operator would believe the note had been kept.
+        ...(values.note === undefined || command === 'junk' ? [] : ['--note']),
+        // `--full` belongs to `scan` alone, and it is refused elsewhere rather than
+        // there: the operator who put it on `inventory` would otherwise believe they
+        // had asked for a re-read.
+        ...(values.full === true && command !== 'scan' ? ['--full'] : []),
+        ...(values.url === undefined || command === 'mcp' ? [] : ['--url']),
+    ];
+    if (misplaced.length > 0) {
+        return {
+            kind: 'error',
+            message: `${command} takes no ${misplaced.join(' or ')}`,
+            code: USAGE_ERROR,
+        };
+    }
+    if (command === 'inventory') {
+        if (roots.length > 0) {
+            return { kind: 'error', message: 'inventory takes no roots', code: USAGE_ERROR };
+        }
+        return { kind: 'inventory', dbPath };
+    }
+    if (command === 'keys') {
+        const [action = 'list', ...rest] = roots;
+        if (!KEYS_ACTIONS.has(action)) {
+            return {
+                kind: 'error',
+                message: `keys does not take "${action}" (one of: list, add, revoke)`,
+                code: USAGE_ERROR,
+            };
+        }
+        if (action === 'list') {
+            if (rest.length > 0) {
+                return { kind: 'error', message: 'keys list takes nothing', code: USAGE_ERROR };
+            }
+            return { kind: 'keys', action: 'list', dbPath };
+        }
+        if (rest.length !== 1 || rest[0] === '') {
+            return {
+                kind: 'error',
+                message: action === 'add'
+                    ? 'keys add needs one label — what the key is for, or whose it is'
+                    : 'keys revoke needs one id or label',
+                code: USAGE_ERROR,
+            };
+        }
+        return { kind: 'keys', action: action, what: rest[0], dbPath };
+    }
+    if (command === 'junk') {
+        const [action = 'list', ...rest] = roots;
+        if (!JUNK_ACTIONS.has(action)) {
+            return {
+                kind: 'error',
+                message: `junk does not take "${action}" (one of: list, block, allow)`,
+                code: USAGE_ERROR,
+            };
+        }
+        if (action === 'list') {
+            if (rest.length > 0) {
+                return { kind: 'error', message: 'junk list takes no paths', code: USAGE_ERROR };
+            }
+            return { kind: 'junk', action: 'list', dbPath };
+        }
+        if (rest.length !== 1) {
+            return {
+                kind: 'error',
+                message: `junk ${action} needs one path`,
+                code: USAGE_ERROR,
+            };
+        }
+        if (values.note !== undefined && values.note === '') {
+            return { kind: 'error', message: '--note needs a value', code: USAGE_ERROR };
+        }
+        return {
+            kind: 'junk',
+            action: action,
+            path: rest[0],
+            note: values.note,
+            dbPath,
+        };
+    }
+    if (roots.length === 0) {
+        return { kind: 'error', message: 'scan needs at least one root', code: USAGE_ERROR };
+    }
+    return { kind: 'scan', roots, dbPath, full: values.full === true };
+}