@skrr-ai/cli 0.1.9 → 0.1.11

package/dist/commands/wiki/mv.js

@@ -1,10 +1,69 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.destinationConflict = destinationConflict;
+exports.serverRenamedOnMove = serverRenamedOnMove;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
 const http_error_1 = require("../../lib/http-error");
 const wiki_1 = require("../../lib/wiki");
+const write_1 = require("./write");
+/**
+ * Why this move must not proceed — or `null` when it may.
+ *
+ * Pure, so the decision is testable without a server: everything it needs is
+ * the occupant, the kinds involved, and whether the caller authorised a
+ * replacement. The messages say the word the old output never did — "already
+ * exists" — because a human watching the terminal could see the `-2` in the
+ * success line and still not read it as a collision.
+ */
+function destinationConflict(opts) {
+    const { occupant, sourceKind, source, destination, force, binName, spaceId } = opts;
+    if (occupant.kind === 'free' || occupant.kind === 'self')
+        return null;
+    if (occupant.kind === 'folder') {
+        // No `--force` escape here even for a folder source: replacing a folder
+        // means deleting a subtree, and `rmdir` is the verb that asks about that.
+        return {
+            message: `'${destination}' already exists — it is a folder, and \`mv\` will not replace one.\n` +
+                `Move '${source}' somewhere else, or remove the folder first with ` +
+                `\`${binName} wiki rmdir ${spaceId} ${destination}\`.`,
+            code: 'WIKI_DESTINATION_EXISTS',
+        };
+    }
+    if (sourceKind === 'folder') {
+        return {
+            message: `'${destination}' already exists — it is a page, so a folder cannot take that path.\n` +
+                `Pick another destination, or remove the page first with ` +
+                `\`${binName} wiki rm ${spaceId} ${destination}\`.`,
+            code: 'WIKI_DESTINATION_EXISTS',
+        };
+    }
+    if (!force) {
+        return {
+            message: `'${destination}' already exists (page ${occupant.pageId}, "${occupant.title}"). ` +
+                `Nothing was moved.\n` +
+                `Pass --force to replace it with '${source}', or choose a different destination. ` +
+                `Without it \`mv\` would land '${source}' beside the page rather than on it, and ` +
+                `\`${binName} wiki cat ${spaceId} ${destination}\` would still read the OLD content.`,
+            code: 'WIKI_DESTINATION_EXISTS',
+        };
+    }
+    return null;
+}
+/**
+ * Did the server disambiguate the slug anyway?
+ *
+ * The pre-flight check above closes the ordinary case, but it cannot close the
+ * race — a page can appear on the destination between the check and the move —
+ * and an older server has no notion of refusing. `allocateSlug` suffixes (`y` ->
+ * `y-2`), which is precisely the outcome that must never read as success, so the
+ * post-check reuses `write.ts`'s detector rather than a second copy of the
+ * server's slug rules.
+ */
+function serverRenamedOnMove(requestedSlug, movedSlug) {
+    return (0, write_1.createdSlugCollided)(requestedSlug, movedSlug);
+}
 /**
  * `skrr wiki mv <space> <source> <destination>` — move or rename a page OR a
  * folder.
@@ -19,6 +78,16 @@ const wiki_1 = require("../../lib/wiki");
  * through `PATCH /pages/:pageId/move` (which creates missing destination
  * folders); folders go through `PATCH /folders/:folder_id`, whose server-side
  * guard refuses to move a folder into its own descendant.
+ *
+ * OCCUPIED DESTINATIONS ARE REFUSED, not renamed around. The move endpoint runs
+ * the same `allocateSlug` de-duplication a CREATE does, so `mv X Y` onto an
+ * existing `Y` landed the source at `Y-2`, reported success, and left `Y`
+ * holding its OLD content — and `mv X Y; cat Y` then reads the stale page while
+ * believing it read the new one. Moving something onto a canonical path is the
+ * entire reason to run `mv`, so "I could not do that, so I did something
+ * adjacent" is the one outcome this command must not present as success.
+ * `--force` gives the filesystem's answer (replace the destination); the
+ * default gives the safe one (refuse and change nothing).
  */
 class WikiMv extends base_command_1.BaseCommand {
     static description = 'Move or rename a wiki page or folder';
@@ -26,6 +95,7 @@ class WikiMv extends base_command_1.BaseCommand {
         '<%= config.bin %> wiki mv <space-id> draft Engineering/Runbooks/deploy',
         '<%= config.bin %> wiki mv <space-id> Engineering/old-name Engineering/new-name',
         '<%= config.bin %> wiki mv <space-id> Notes Engineering/Notes',
+        '<%= config.bin %> wiki mv <space-id> new-runbook Engineering/deploy --force',
         '<%= config.bin %> wiki mv <space-id> Engineering/Runbooks Archive/Runbooks --json',
     ];
     static args = {
@@ -36,13 +106,23 @@ class WikiMv extends base_command_1.BaseCommand {
             ignoreStdin: true,
         }),
         destination: core_1.Args.string({
-            description: 'Destination path (missing parent folders are created for pages)',
+            description: 'Destination path (missing parent folders are created for pages). ' +
+                'An occupied destination is refused unless --force.',
             required: true,
             ignoreStdin: true,
         }),
     };
     static flags = {
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+        force: core_1.Flags.boolean({
+            char: 'f',
+            // Named for what it destroys, not for what it skips: unlike `wiki rm`'s
+            // --force this suppresses no prompt, it authorises deleting whatever is
+            // already on the destination path.
+            description: 'Replace an existing page at the destination (deletes it first)',
+            aliases: ['yes'],
+            charAliases: ['y'],
+        }),
     };
     async run() {
         this.requireAuth();
@@ -79,6 +159,45 @@ class WikiMv extends base_command_1.BaseCommand {
                 this.handleApiError(err);
         }
         if (page) {
+            const occupant = await this.resolveDestination(args.space, args.destination, {
+                pageId: page.pageId,
+            });
+            const conflict = destinationConflict({
+                occupant,
+                sourceKind: 'page',
+                source,
+                destination: args.destination,
+                force: flags.force,
+                binName: this.config.bin,
+                spaceId: args.space,
+            });
+            if (conflict) {
+                this.failWithCliError({ ...conflict, exit: 1, retryable: false });
+            }
+            // `--force` on an occupied destination: clear the path before moving, so
+            // the move lands ON it rather than beside it. Archive, not purge —
+            // `wiki rm --purge` is where destroying edit history is asked for
+            // explicitly, and it should not be a side effect of a move.
+            //
+            // The order is forced (moving first would just hit the collision again),
+            // so a move that fails after the delete leaves the destination archived
+            // and the source where it was. That is recoverable — the row survives —
+            // and it is the lesser failure: the alternative is the behaviour this
+            // whole guard exists to remove, where both pages end up present and the
+            // canonical path quietly holds the wrong one. A server-side atomic
+            // replace (`conflict: 'replace'` on the move endpoint, mirroring the one
+            // create already takes) is the real fix and is not the CLI's to make.
+            if (occupant.kind === 'page') {
+                try {
+                    await data_provider_1.dataService.deleteSpaceWikiPage({
+                        spaceId: args.space,
+                        pageId: occupant.pageId,
+                    });
+                }
+                catch (err) {
+                    this.handleApiError(err);
+                }
+            }
             let moved;
             try {
                 moved = await data_provider_1.dataService.moveSpaceWikiPage({
@@ -90,11 +209,35 @@ class WikiMv extends base_command_1.BaseCommand {
             catch (err) {
                 this.handleApiError(err);
             }
+            // The check above cannot close the window between it and the move, and an
+            // older server refuses nothing. Landing at `y-2` is a FAILED move, so say
+            // so rather than printing a success line naming a path nobody asked for.
+            if (serverRenamedOnMove(name, moved.slug)) {
+                this.failWithCliError({
+                    message: `'${args.destination}' was already taken, so the server moved '${source}' to ` +
+                        `'${moved.path ?? moved.slug}' instead. '${args.destination}' still holds its ` +
+                        `ORIGINAL content — the move you asked for did NOT happen.\n` +
+                        `Re-run with --force to replace the destination, or move ` +
+                        `'${moved.path ?? moved.slug}' where you want it.`,
+                    code: 'WIKI_DESTINATION_EXISTS',
+                    exit: 1,
+                    retryable: true,
+                    details: {
+                        requestedPath: args.destination,
+                        requestedSlug: name,
+                        actualSlug: moved.slug,
+                        movedPageId: moved.pageId,
+                    },
+                });
+            }
             if (flags.json) {
                 this.log(JSON.stringify({ kind: 'page', ...moved }, null, 2));
                 return;
             }
             this.log(`Moved page ${source} → ${moved.path ?? args.destination}.`);
+            if (occupant.kind === 'page') {
+                this.log(`Replaced the page that was there ("${occupant.title}", now deleted).`);
+            }
             // A rename moved the path but not the title. When the title was never
             // authored (it still equals the old slug), point the user at the one
             // command that finishes the rename rather than leaving them to notice the
@@ -111,7 +254,43 @@ class WikiMv extends base_command_1.BaseCommand {
                 this.log(hint);
             return;
         }
-        await this.moveFolder(args.space, source, dir, name, flags.json);
+        await this.moveFolder(args.space, source, args.destination, dir, name, flags);
+    }
+    /**
+     * What already occupies `destination` — a page, a folder, us, or nothing.
+     *
+     * A page and a folder cannot share a path, so this asks in the same order the
+     * source resolution does. Both lookups treat a 404 as an answer rather than a
+     * failure; anything else still surfaces, so an unreadable destination never
+     * degrades into "looks free, go ahead and clobber".
+     */
+    async resolveDestination(spaceId, destination, 
+    // The thing being moved. `mv x x` and a rename that changes nothing both
+    // resolve the destination to the SOURCE, and refusing those would turn a
+    // harmless no-op into an error.
+    self = {}) {
+        try {
+            const existing = await data_provider_1.dataService.getSpaceWikiPageByPath(spaceId, destination);
+            if (existing) {
+                if (self.pageId && existing.pageId === self.pageId)
+                    return { kind: 'self' };
+                return { kind: 'page', pageId: existing.pageId, title: existing.title };
+            }
+        }
+        catch (err) {
+            if (!(0, http_error_1.isHttpNotFound)(err))
+                this.handleApiError(err);
+        }
+        let folderId = null;
+        try {
+            folderId = await (0, wiki_1.resolveWikiFolderId)(spaceId, destination, data_provider_1.dataService.listSpaceWikiDirectory, http_error_1.isHttpNotFound);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        if (!folderId)
+            return { kind: 'free' };
+        return folderId === self.folderId ? { kind: 'self' } : { kind: 'folder' };
     }
     /**
      * Reparent and/or rename a folder.
@@ -121,7 +300,7 @@ class WikiMv extends base_command_1.BaseCommand {
      * would mean a typo in the destination silently builds a new tree instead of
      * failing — `mkdir -p` is a separate decision the caller should make.
      */
-    async moveFolder(spaceId, source, destinationDir, name, json) {
+    async moveFolder(spaceId, source, destination, destinationDir, name, flags) {
         let folderId;
         try {
             folderId = await (0, wiki_1.resolveWikiFolderId)(spaceId, source, data_provider_1.dataService.listSpaceWikiDirectory, http_error_1.isHttpNotFound);
@@ -157,6 +336,21 @@ class WikiMv extends base_command_1.BaseCommand {
                 });
             }
         }
+        // Same refusal the page branch makes, for the same reason: a folder that
+        // silently lands beside its destination instead of on it is a move that
+        // reports success without happening.
+        const conflict = destinationConflict({
+            occupant: await this.resolveDestination(spaceId, destination, { folderId }),
+            sourceKind: 'folder',
+            source,
+            destination,
+            force: flags.force,
+            binName: this.config.bin,
+            spaceId,
+        });
+        if (conflict) {
+            this.failWithCliError({ ...conflict, exit: 1, retryable: false });
+        }
         let updated;
         try {
             updated = await data_provider_1.dataService.updateSpaceWikiFolder({
@@ -168,7 +362,7 @@ class WikiMv extends base_command_1.BaseCommand {
         catch (err) {
             this.handleApiError(err);
         }
-        if (json) {
+        if (flags.json) {
             this.log(JSON.stringify({ kind: 'folder', ...updated }, null, 2));
             return;
         }

package/dist/commands/wiki/rm.js

@@ -90,7 +90,18 @@ class WikiRm extends base_command_1.BaseCommand {
             this.log(JSON.stringify(result, null, 2));
             return;
         }
-        this.log(flags.purge ? `Purged ${args.path}.` : `Deleted ${args.path}.`);
+        if (flags.purge) {
+            this.log(`Purged ${args.path}.`);
+            return;
+        }
+        // The page id is the ONLY handle left that reaches this content, and it was
+        // the one thing not printed. `rm` archives rather than destroys — the help
+        // says so — and `wiki cat --page-id <id>` still returns the body. But `ls`
+        // drops the page and `rm` said only "Deleted <path>.", so the handle was
+        // discarded at exactly the moment it became the sole way back. An honest
+        // "archived, not destroyed" then behaves like "destroyed".
+        this.log(`Deleted ${args.path} (${page.pageId}).`);
+        this.log(`  Archived, not destroyed — read it with \`${this.config.bin} wiki cat ${args.space} --page-id ${page.pageId}\`.`);
     }
 }
 exports.default = WikiRm;

package/dist/commands/wiki/write.js

@@ -94,9 +94,25 @@ class WikiWrite extends base_command_1.BaseCommand {
     // one place a CLI user (or an agent with no docs) looks before writing, and
     // `__x__` silently staying literal is exactly the kind of surprise that has to
     // reach them there. (OSK-4844)
+    //
+    // It has to be SELF-CONTAINED, which the first cut was not: it named the cost
+    // of the escape rule ("a backslash before punctuation escapes it") and then
+    // pointed at `docs/cli/SKRR_WIKI.md` for what that actually costs you — a path
+    // inside the git checkout, which someone who installed `skrr` from npm does
+    // not have, with no URL and no `skrr docs` to reach it by. So the CLI's own
+    // answer to "what does that mean for my regex?" was a file the reader cannot
+    // open. It is two sentences; they belong here.
+    //
+    // Stated as CONSUMED rather than as "escaped", because the wiki stores
+    // rendered HTML: those bytes are gone on the FIRST write, not merely hidden
+    // on read, and no `wiki cat --html` gets them back.
     static description = 'Write a wiki page, creating it (and any missing folders) if needed. ' +
-        'Markdown by default; `__x__` stays literal (use `**x**` for bold) and a ' +
-        'backslash before punctuation escapes it — see docs/cli/SKRR_WIKI.md.';
+        'Markdown by default: `__x__` stays literal (use `**x**` for bold), and a ' +
+        'backslash before ASCII punctuation is an escape, so the backslash itself ' +
+        'is CONSUMED and not stored — `\\d+\\.\\d+` becomes `\\d+.\\d+`. Double it ' +
+        '(`\\\\.`) to keep a literal backslash, or put the text in a code span or ' +
+        'fence, where nothing is interpreted. A backslash before anything else ' +
+        '(a letter, a space) is kept as written.';
     static examples = [
         '<%= config.bin %> wiki write <space-id> Engineering/deploy --file runbook.md',
         'cat notes.md | <%= config.bin %> wiki write <space-id> notes --stdin',
@@ -113,7 +129,9 @@ class WikiWrite extends base_command_1.BaseCommand {
         stdin: core_1.Flags.boolean({ description: 'Read content from stdin' }),
         html: core_1.Flags.boolean({ description: 'Treat the input as HTML instead of Markdown' }),
         append: core_1.Flags.boolean({ description: 'Append instead of replacing (>> rather than >)' }),
-        title: core_1.Flags.string({ description: 'Title for a newly-created page (defaults to the slug)' }),
+        title: core_1.Flags.string({
+            description: 'Title for a NEWLY-CREATED page (defaults to the slug). Retitle an existing page with `wiki update --title`',
+        }),
     };
     async run() {
         this.requireAuth();
@@ -216,6 +234,20 @@ class WikiWrite extends base_command_1.BaseCommand {
                 },
             });
         }
+        // `--title` is create-only, which the help now says — but the command still
+        // ACCEPTED it, reported success, and changed nothing about the one thing
+        // the flag names. `wiki update`'s own help already argues this case: it
+        // refuses an all-empty patch precisely so "a mistyped flag name [does not]
+        // look like success". Same reasoning, and the write itself succeeded, so
+        // this is a warning naming the command that does the job rather than a
+        // failure. To stderr, so `--json` stays a clean contract — and BEFORE the
+        // `--json` early return, or the caller most likely to be scripting this is
+        // the one caller who never hears it.
+        if (wroteIntoExisting && flags.title !== undefined && flags.title !== page.title) {
+            this.warn(`--title was ignored: '${page.path ?? args.path}' already exists, and \`wiki write\` only titles pages ` +
+                `it creates. Retitle it with \`${this.config.bin} wiki update ${args.space} ${page.path ?? args.path} ` +
+                `--title ${JSON.stringify(flags.title)}\` (the slug is kept, so stored paths stay valid).`);
+        }
         if (flags.json) {
             this.log(JSON.stringify(page, null, 2));
             return;

package/dist/help.d.ts

@@ -0,0 +1,27 @@
+import { Help } from '@oclif/core';
+/**
+ * Make `--help` on a command that does not exist say the same thing running it
+ * says.
+ *
+ * oclif's help command resolves the id itself and never reaches the
+ * `command_not_found` hook, so the two paths answered differently:
+ *
+ *     $ skrr daemon reload
+ *         Error: `skrr daemon` exists, but does not take the positional
+ *         argument `reload`.
+ *         See `skrr daemon --help`.
+ *
+ *     $ skrr daemon reload --help
+ *      ›   Error: Command daemon:reload not found.
+ *
+ * The second names an internal colon-form id the user never typed and cannot
+ * type, and offers no next step — and it is the one a reader exploring the CLI
+ * hits FIRST, because asking for help on a guessed subcommand is what people do
+ * before running it. The audience most likely to need the good message was the
+ * audience reliably denied it.
+ *
+ * Only the not-found path is overridden. Real help output is untouched.
+ */
+export default class SkrrHelp extends Help {
+    showHelp(argv: string[]): Promise<void>;
+}

package/dist/help.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const command_miss_1 = require("./lib/command-miss");
+/**
+ * Make `--help` on a command that does not exist say the same thing running it
+ * says.
+ *
+ * oclif's help command resolves the id itself and never reaches the
+ * `command_not_found` hook, so the two paths answered differently:
+ *
+ *     $ skrr daemon reload
+ *         Error: `skrr daemon` exists, but does not take the positional
+ *         argument `reload`.
+ *         See `skrr daemon --help`.
+ *
+ *     $ skrr daemon reload --help
+ *      ›   Error: Command daemon:reload not found.
+ *
+ * The second names an internal colon-form id the user never typed and cannot
+ * type, and offers no next step — and it is the one a reader exploring the CLI
+ * hits FIRST, because asking for help on a guessed subcommand is what people do
+ * before running it. The audience most likely to need the good message was the
+ * audience reliably denied it.
+ *
+ * Only the not-found path is overridden. Real help output is untouched.
+ */
+class SkrrHelp extends core_1.Help {
+    async showHelp(argv) {
+        // Mirror oclif's own id resolution: the topic separator is a space here, so
+        // the id is the leading non-flag tokens joined with `:`.
+        const tokens = [];
+        for (const token of argv) {
+            if (token.startsWith('-'))
+                break;
+            tokens.push(token);
+        }
+        const id = tokens.join(':');
+        // A bare topic (`skrr daemon`) has no command but DOES have help to show,
+        // so it must fall through — only an id that is neither a command nor a
+        // topic is a miss.
+        if (id && !this.config.findCommand(id) && !this.config.findTopic(id)) {
+            throw new Error((0, command_miss_1.describeCommandMiss)((0, command_miss_1.lookupFromConfig)(this.config), id));
+        }
+        return super.showHelp(argv);
+    }
+}
+exports.default = SkrrHelp;

package/dist/hooks/command-not-found.d.ts

@@ -1,3 +1,34 @@
 import { Hook } from '@oclif/core';
+/**
+ * Turn "command not found" back into the truth when the command DOES exist.
+ *
+ * ── The failure ───────────────────────────────────────────────────────────
+ *
+ * oclif resolves a command by joining argv with `:`, so an unexpected
+ * positional becomes part of the command id:
+ *
+ *     $ skrr shortcuts list 4a167054-e70e-4b1c-ab43-88de52d3d4a2
+ *      ›   Error: command shortcuts:list:4a167054-… not found
+ *
+ * `skrr shortcuts list` exists and is correct — only the argument form was
+ * wrong; it wants `--space`. But the message says the COMMAND is missing, which
+ * is the one conclusion that sends a reader looking in the wrong place. I hit
+ * the identical shape on `skrr commitments archive <id>` and briefly believed
+ * the subcommand had been removed.
+ *
+ * It is easy to hit because the CLI has no rule about how a space is passed:
+ * 65 commands take it as a positional and 61 as `--space`, and `projects
+ * create <SPACE>` sits beside `projects archive --space`. Picking one is a
+ * separate, larger change (OSK-4527). This makes guessing wrong cheap either
+ * way, which is worth having even after that lands.
+ *
+ * ── What it does ──────────────────────────────────────────────────────────
+ *
+ * Walks the id's prefixes longest-first. If one resolves to a real command, the
+ * remaining tokens are arguments that command did not want, and the message
+ * says so — naming the command, the leftover tokens, and the flag to try when
+ * the command has an obvious one. Otherwise it falls through to oclif's own
+ * not-found behaviour, because then the command really is missing.
+ */
 declare const hook: Hook<'command_not_found'>;
 export default hook;

package/dist/hooks/command-not-found.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const command_manifest_1 = require("../lib/command-manifest");
 const usage_discovery_1 = require("../lib/usage-discovery");
+const command_miss_1 = require("../lib/command-miss");
 /**
  * Turn "command not found" back into the truth when the command DOES exist.
  *
@@ -33,8 +34,6 @@ const usage_discovery_1 = require("../lib/usage-discovery");
  * the command has an obvious one. Otherwise it falls through to oclif's own
  * not-found behaviour, because then the command really is missing.
  */
-/** A uuid-ish token, which is what a stray space id looks like. */
-const LOOKS_LIKE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const hook = async function (opts) {
     const id = String(opts.id ?? '');
     const parts = id.split(':').filter(Boolean);
@@ -66,86 +65,19 @@ const hook = async function (opts) {
                 throw err;
         }
     }
-    // Longest prefix first: `a:b:c` should report `a b`, not `a`.
-    for (let take = parts.length - 1; take >= 1; take -= 1) {
-        const candidateId = parts.slice(0, take).join(':');
-        const found = this.config.findCommand(candidateId);
-        if (!found)
-            continue;
-        const extras = parts.slice(take);
-        const spoken = `${this.config.bin} ${parts.slice(0, take).join(' ')}`;
-        // Suggest the flag only when the command actually has it, so the hint can
-        // never point at something that does not exist.
-        const flags = Object.keys(found.flags ?? {});
-        const hint = extras.some((e) => LOOKS_LIKE_ID.test(e)) && flags.includes('space')
-            ? ` Pass it as \`--space ${extras[0]}\`.`
-            : flags.includes('space')
-                ? ' It takes `--space <id>`.'
-                : '';
-        const plural = extras.length === 1 ? 'argument' : 'arguments';
-        throw new Error(`\`${spoken}\` exists, but does not take the positional ${plural} ` +
-            `${extras.map((e) => `\`${e}\``).join(' ')}.${hint}\n` +
-            `See \`${spoken} --help\`.`);
-    }
-    // No prefix resolved — the command genuinely is not there.
+    // The message itself lives in `lib/command-miss`, shared with the help
+    // class — `skrr daemon reload` reaches this hook and `skrr daemon reload
+    // --help` does not, so the two surfaces have to read from one description or
+    // they drift, which is exactly how the `--help` path ended up with oclif's
+    // raw boilerplate while this path had a good message.
     //
-    // This branch MUST throw. A `command_not_found` hook that returns without
-    // throwing is treated as having handled the miss, so oclif prints nothing and
-    // exits 0 — a typo would silently look like success, which is far worse than
-    // the message this hook was written to improve. (I shipped exactly that for
-    // one build; `skrr shortcuts lst` said nothing and exited 0.)
-    const allIds = this.config.commandIDs.map((c) => String(c));
-    // Topic names are candidates too, so a near-miss on a bare topic gets routed
-    // to the topic rather than nothing (OSK-4869): `skrr harness` (singular) is
-    // one edit from the `harnesses` topic, but that topic owns no command whose
-    // id is close to `harness`, so a command-id-only search suggests nothing.
-    const topics = this.config.topics;
-    const topicNames = Array.isArray(topics)
-        ? topics.map((t) => String(t?.name ?? '')).filter(Boolean)
-        : [];
-    // Prefer siblings under the same topic. `commitments:archive:<id>` is a long
-    // way from every real command id, so a whole-string comparison finds nothing
-    // and the reader is told only that they are wrong — when the useful answer is
-    // "that topic exists and here is what it does have".
-    const topic = parts[0];
-    const siblings = allIds.filter((c) => c.startsWith(`${topic}:`));
-    const suggestions = siblings.length
-        ? nearestCommands(parts.slice(0, 2).join(':'), siblings)
-        : nearestCommands(id, [...allIds, ...topicNames]);
-    throw new Error(`\`${this.config.bin} ${parts.join(' ')}\` is not a command.` +
-        (suggestions.length
-            ? `\nDid you mean: ${suggestions.map((s) => `\`${this.config.bin} ${s.split(':').join(' ')}\``).join(', ')}?`
-            : `\nRun \`${this.config.bin} --help\` to see the topics.`));
+    // This MUST throw. A `command_not_found` hook that returns without throwing
+    // is treated as having handled the miss, so oclif prints nothing and exits 0
+    // — a typo would silently look like success, which is far worse than the
+    // message this hook was written to improve. (I shipped exactly that for one
+    // build; `skrr shortcuts lst` said nothing and exited 0.)
+    throw new Error((0, command_miss_1.describeCommandMiss)((0, command_miss_1.lookupFromConfig)(this.config), id));
 };
-/** Cheap edit distance, bounded — this runs only on a miss. */
-function editDistance(a, b) {
-    const rows = a.length + 1;
-    const cols = b.length + 1;
-    let prev = Array.from({ length: cols }, (_, j) => j);
-    for (let i = 1; i < rows; i += 1) {
-        const cur = [i, ...Array(cols - 1).fill(0)];
-        for (let j = 1; j < cols; j += 1) {
-            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
-        }
-        prev = cur;
-    }
-    return prev[cols - 1];
-}
-/**
- * The closest real command ids, so a typo gets a route forward rather than
- * only a verdict.
- */
-function nearestCommands(id, all, limit = 3) {
-    return (all
-        .map((candidate) => ({ candidate, d: editDistance(id, candidate) }))
-        // A third of the length keeps this to genuine near-misses; without a bound
-        // every miss suggests three unrelated commands, which is noise wearing the
-        // shape of help.
-        .filter(({ d }) => d <= Math.max(2, Math.floor(id.length / 3)))
-        .sort((x, y) => x.d - y.d)
-        .slice(0, limit)
-        .map(({ candidate }) => candidate));
-}
 exports.default = hook;
 class VirtualUsageFlagError extends Error {
 }

package/dist/lib/command-miss.d.ts

@@ -0,0 +1,60 @@
+/**
+ * What to say when a command id does not resolve — ONE description, shared by
+ * every surface that can produce a miss.
+ *
+ * There are two such surfaces, and they used to disagree. `skrr daemon reload`
+ * goes through the `command_not_found` hook and gets a message naming the real
+ * command, the mistake, and the next step. `skrr daemon reload --help` goes
+ * through oclif's HELP command, which does its own lookup and never reaches
+ * that hook — so it answered `Command daemon:reload not found.`: raw
+ * boilerplate naming an internal colon-form id the user never typed and cannot
+ * type, with no route forward.
+ *
+ * The audience is what makes that the wrong way round. Someone exploring a
+ * service-manager CLI types `--help` on a guessed subcommand FIRST. So the
+ * readers most likely to hit a miss were exactly the readers the good message
+ * was written for, and they systematically got the bad one.
+ *
+ * Keeping the text here rather than in either caller is the point: a fix to one
+ * phrasing reaches both, and neither surface can quietly drift from the other.
+ */
+/** Minimal view of the oclif config this needs — keeps the module testable. */
+export type CommandLookup = {
+    bin: string;
+    findCommand: (id: string) => {
+        flags?: Record<string, unknown>;
+    } | undefined;
+    commandIDs: string[];
+    topicNames: string[];
+};
+/** Cheap edit distance, bounded — this runs only on a miss. */
+export declare function editDistance(a: string, b: string): number;
+/**
+ * The closest real command ids, so a typo gets a route forward rather than
+ * only a verdict.
+ */
+export declare function nearestCommands(id: string, all: string[], limit?: number): string[];
+/**
+ * The message for a colon-joined id that did not resolve.
+ *
+ * Two shapes, in order:
+ *
+ *  1. A PREFIX of the id is a real command, so the extra tokens are arguments
+ *     it did not want. Longest prefix first, because `a:b:c` should report
+ *     `a b`, not `a`.
+ *  2. Nothing resolved, so the command genuinely is not there — say so, and
+ *     suggest the nearest siblings under the same topic before falling back to
+ *     the whole command list.
+ */
+export declare function describeCommandMiss(config: CommandLookup, id: string): string;
+/** Adapt an oclif `Config` to the lookup shape above. */
+export declare function lookupFromConfig(config: {
+    bin: string;
+    findCommand: (id: string) => unknown;
+    commandIDs: Array<string | {
+        toString(): string;
+    }>;
+    topics?: Array<{
+        name?: string;
+    }>;
+}): CommandLookup;