@theowlops/boombot 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @boombot/cli
+
+Command-line interface for BoomBot: first-run setup wizard, health checks, OpenClaw migration, and the gateway launcher.
+
+## Usage
+
+```bash
+npx @boombot/cli@latest
+# Or install once:
+npm install -g @boombot/cli
+boombot
+```
+
+Requires Node.js **22.13+** and Python **3.11+** with `grpcio` and `protobuf`.
+
+First launch creates `~/.boombot/config.json`, API keys and encryption keys without prompts, then opens the web UI. Add a provider in **Settings → Connection**. Keep the terminal open; `Ctrl+C` stops the gateway.
+
+```bash
+boombot --help                  # list commands
+boombot doctor                  # run health checks
+boombot doctor --json           # machine-readable output
+boombot setup                   # terminal configuration wizard
+boombot migrate --from openclaw # migrate an OpenClaw config
+boombot gateway                 # start the gateway (default)
+boombot gateway --no-browser    # headless mode
+```
+
+Config lives in `~/.boombot/config.json` (override with `BOOMBOT_CONFIG`). The operator key is in `api.key`; provider encryption uses `master.key`. Automatic setup never prints either key.
+
+## Standalone binary (no Node.js required)
+
+Build a self-contained executable with Bun:
+
+```bash
+node build-binary.mjs                    # current platform
+node build-binary.mjs --target bun-linux-x64
+node build-binary.mjs --target bun-darwin-arm64
+node build-binary.mjs --target bun-windows-x64
+```
+
+Output: `dist/bin/boombot-<platform>` (~80–120 MB, Bun runtime embedded).
+
+The binary bundles the gateway statically — `boombot gateway` works without Node.js. See [BUILD.md](./BUILD.md) for details and gotchas.
+
+Or via pnpm from the repo root:
+
+```bash
+pnpm --filter @boombot/cli build:binary
+```
+
+## Commands
+
+| Command | Aliases | Description |
+|---|---|---|
+| `boombot setup` | `init` | Terminal wizard: host/port, data dir, providers; preserves existing settings |
+| `boombot doctor` | `dr` | Checks config, permissions, data dir, gateway, providers, channels |
+| `boombot migrate --from openclaw` | `import` | Migrates an OpenClaw config |
+| `boombot` / `boombot gateway` | `serve` | First-run setup, then starts the gateway |
+
+## Framework
+
+Every command is a declarative `CommandSpec` in `src/cli/registry.ts`. Help text is generated from specs; `bin.ts` only parses argv and dispatches. Exit codes: `0` ok, `1` runtime error, `2` usage error. Typos get "did you mean?" suggestions.
+
+## Test / typecheck
+
+```bash
+pnpm test        # vitest run
+pnpm typecheck   # tsc --noEmit
+```

package/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) BoomBot contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/bin/boombot.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// @boombot/cli — global `boombot` bin entry.
+//
+// The compiled CLI lives in ../cli/ (tsc output of apps/cli/src). This tiny
+// wrapper exists so the published bin path is exactly `dist/bin/boombot.js`
+// while keeping one-file-per-source emit (readable stack traces, no bundler).
+import console from 'node:console';
+import process from 'node:process';
+
+const [major, minor] = process.versions.node.split('.').map(Number);
+if (!((major === 22 && minor >= 13) || major >= 24)) {
+  console.error('BoomBot requires Node.js 22.13+ (22.x) or 24+. Install a supported Node.js version, then run boombot again.');
+  process.exitCode = 1;
+} else {
+  await import('../cli/bin.js');
+}

package/dist/cli/api-key.js

@@ -0,0 +1,123 @@
+/**
+ * Gateway API key — the bearer token every client sends to `/v1/commands`.
+ *
+ * `boombot setup` used to generate the key, print it once, and keep only its
+ * sha256. That made it unrecoverable: a hash cannot be turned back into the key,
+ * so anyone who missed the one-time printout had no way to fill in the web UI's
+ * "API key" field — the app asked for a secret that no longer existed anywhere.
+ *
+ * The key is now stored at `~/.boombot/api.key` (mode 0600 on POSIX), the same
+ * place and the same reasoning as `master.key`: a local secret this machine's CLI
+ * and browser need, on a filesystem the operator already controls. It is strictly
+ * less sensitive than `master.key`, which is the KEK that decrypts provider
+ * credentials. On Windows `chmod` is a no-op — see SECURITY.md §5.
+ *
+ * `BOOMBOT_API_KEY` wins when set, matching the gateway's own precedence (see
+ * `resolveApiKeyHash` in `agent-worker/src/config.ts`).
+ *
+ * Never log or print the raw key outside the one-time `boombot setup` notice and
+ * the browser bootstrap URL.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import path from 'node:path';
+import { generateApiKey, hashApiKey, resolveConfigPath } from "./config-file.js";
+/**
+ * Default API-key path: `api.key` next to the config file
+ * (`~/.boombot/api.key` unless `$BOOMBOT_CONFIG` points elsewhere).
+ */
+export function resolveApiKeyPath(configPath = resolveConfigPath()) {
+    return path.join(path.dirname(configPath), 'api.key');
+}
+/** Read the stored API key, or `null` when absent/empty/unreadable. */
+export function loadApiKey(keyPath = resolveApiKeyPath()) {
+    let raw;
+    try {
+        raw = readFileSync(keyPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const key = raw.trim();
+    return key === '' ? null : key;
+}
+/** True when an API key is available (file or environment). */
+export function hasApiKey(keyPath = resolveApiKeyPath()) {
+    const fromEnv = process.env['BOOMBOT_API_KEY'];
+    if (fromEnv !== undefined && fromEnv !== '')
+        return true;
+    return existsSync(keyPath) && loadApiKey(keyPath) !== null;
+}
+/** Persist `key` to `keyPath`, 0600 on POSIX (best-effort on Windows). */
+export function saveApiKey(key, keyPath = resolveApiKeyPath()) {
+    mkdirSync(path.dirname(keyPath), { recursive: true });
+    writeFileSync(keyPath, `${key}\n`, { encoding: 'utf8', mode: 0o600 });
+    if (process.platform !== 'win32') {
+        chmodSync(keyPath, 0o600);
+    }
+}
+/**
+ * Return the existing API key, generating and persisting a fresh one when none
+ * is found. Precedence mirrors the gateway: environment first, then file.
+ *
+ * An existing key is NEVER regenerated — that would silently lock out every
+ * client already holding the current one.
+ */
+export function ensureApiKey(keyPath = resolveApiKeyPath()) {
+    const fromEnv = process.env['BOOMBOT_API_KEY'];
+    if (fromEnv !== undefined && fromEnv !== '') {
+        return {
+            apiKey: fromEnv,
+            apiKeyHash: hashApiKey(fromEnv),
+            keyPath: '',
+            created: false,
+            fromEnv: true,
+        };
+    }
+    const existing = loadApiKey(keyPath);
+    if (existing !== null) {
+        return {
+            apiKey: existing,
+            apiKeyHash: hashApiKey(existing),
+            keyPath,
+            created: false,
+            fromEnv: false,
+        };
+    }
+    const { apiKey, apiKeyHash } = generateApiKey();
+    saveApiKey(apiKey, keyPath);
+    return { apiKey, apiKeyHash, keyPath, created: true, fromEnv: false };
+}
+/**
+ * The key that is actually in force: `BOOMBOT_API_KEY` when set, else the file.
+ *
+ * Every caller must go through this rather than `loadApiKey` directly. The
+ * gateway resolves the operator's key from the environment first, so anything
+ * that reads only the file disagrees with it — and the disagreement shows up as
+ * a browser signed in with a key the gateway rejects.
+ */
+export function effectiveApiKey(keyPath = resolveApiKeyPath()) {
+    const fromEnv = process.env['BOOMBOT_API_KEY'];
+    if (fromEnv !== undefined && fromEnv !== '')
+        return fromEnv;
+    return loadApiKey(keyPath);
+}
+/**
+ * Does the key in force still hash to `expectedHash`?
+ *
+ * `boombot gateway` hands this key to the browser while the gateway authenticates
+ * against `config.json`'s hash. If the two drift apart — an old `api.key` beside
+ * a config rewritten by a later `boombot setup` — the UI receives a key that fails
+ * with UNAUTHORIZED and looks like a broken gateway. Callers use this to say what
+ * actually happened.
+ *
+ * `null` means "cannot tell": no key in force at all, or no hash configured (in
+ * which case the gateway fails closed on every request regardless).
+ */
+export function apiKeyMatchesHash(expectedHash, keyPath = resolveApiKeyPath()) {
+    if (expectedHash === undefined || expectedHash === '')
+        return null;
+    const key = effectiveApiKey(keyPath);
+    if (key === null)
+        return null;
+    return hashApiKey(key) === expectedHash;
+}

package/dist/cli/bin-bun.js

@@ -0,0 +1,17 @@
+// @ts-nocheck
+/**
+ * Bun `--compile` entry point for the standalone BoomBot CLI binary.
+ *
+ * Statically imports the gateway (`@boombot/agent-worker`) so Bun bundles it.
+ * The bundled gateway is exposed via `globalThis.__BOOMBOT_BUNDLED_GATEWAY__`,
+ * which `src/commands/gateway.ts` checks before its dynamic-import path.
+ *
+ * This file is ONLY used by `build-binary.mjs` — the `tsc` build uses `src/bin.ts`.
+ */
+import { startGateway, startGatewayManaged } from '@boombot/gateway';
+globalThis.__BOOMBOT_BUNDLED_GATEWAY__ = {
+    startGateway,
+    startGatewayManaged,
+};
+// Re-export the CLI entry — this becomes the binary's main.
+export * from "./bin.js";

package/dist/cli/bin.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * `boombot` — command-line interface.
+ *
+ * Thin entrypoint: parse argv → dispatch against the declarative registry
+ * (`src/cli/registry.ts`) → structured errors with conventional exit codes.
+ * All command knowledge lives in specs; this file knows nothing about
+ * individual commands.
+ */
+import { CliError, formatCliError } from "./cli/cli-error.js";
+import { dispatch } from "./cli/dispatch.js";
+import { REGISTRY } from "./cli/registry.js";
+import { resolveCliVersion } from "./cli/version.js";
+async function main() {
+    const argv = process.argv.slice(2);
+    // Pre-scan so even an unparseable invocation can render `--json` errors.
+    const json = argv.includes('--json');
+    try {
+        process.exitCode = await dispatch(REGISTRY, argv, {
+            version: resolveCliVersion(), defaultCommand: ['gateway'],
+        });
+    }
+    catch (err) {
+        const text = formatCliError(err, json);
+        if (json) {
+            console.log(text);
+        }
+        else {
+            console.error(text);
+        }
+        process.exitCode = err instanceof CliError ? err.exitCode : 1;
+    }
+}
+void main();

package/dist/cli/cli/cli-error.js

@@ -0,0 +1,61 @@
+/**
+ * Structured CLI errors — orca-inspired.
+ *
+ * Every failure carries a machine-readable `code`, a conventional exit code
+ * and recovery hints (`suggestions` + `nextSteps`). `--json` prints the same
+ * shape agents can parse; humans get a short message with "did you mean?".
+ *
+ * Exit codes: 0 ok · 1 runtime error · 2 usage error (bad command/flag).
+ */
+export const EXIT_OK = 0;
+export const EXIT_RUNTIME_ERROR = 1;
+export const EXIT_USAGE_ERROR = 2;
+export class CliError extends Error {
+    code;
+    exitCode;
+    suggestions;
+    nextSteps;
+    constructor(options) {
+        super(options.message);
+        this.name = 'CliError';
+        this.code = options.code;
+        this.exitCode = options.code === 'RUNTIME_ERROR' ? EXIT_RUNTIME_ERROR : EXIT_USAGE_ERROR;
+        this.suggestions = options.suggestions ?? [];
+        this.nextSteps = options.nextSteps ?? [];
+    }
+}
+/** Wrap an unexpected failure so `--json` stays machine-readable. */
+export function toCliError(error) {
+    if (error instanceof CliError)
+        return error;
+    return new CliError({
+        code: 'RUNTIME_ERROR',
+        message: error instanceof Error ? error.message : String(error),
+    });
+}
+/**
+ * Render any error for output. Human mode prints the message plus recovery
+ * hints to stderr; `--json` prints a stable envelope to stdout.
+ */
+export function formatCliError(error, json) {
+    const cli = toCliError(error);
+    if (json) {
+        const envelope = {
+            ok: false,
+            error: {
+                code: cli.code,
+                message: cli.message,
+                suggestions: cli.suggestions,
+                nextSteps: cli.nextSteps,
+            },
+        };
+        return JSON.stringify(envelope, null, 2);
+    }
+    const lines = [`boombot: ${cli.message}`];
+    if (cli.suggestions.length > 0) {
+        lines.push(`Did you mean: ${cli.suggestions.map((s) => `boombot ${s}`).join(', ')}?`);
+    }
+    for (const step of cli.nextSteps)
+        lines.push(`Next step: ${step}`);
+    return lines.join('\n');
+}

package/dist/cli/cli/dispatch.js

@@ -0,0 +1,138 @@
+/**
+ * Command dispatch — orca-inspired.
+ *
+ * parse argv → match the LONGEST registered path/alias prefix (nested
+ * subcommands work from day one) → validate flags against the spec →
+ * run the handler. Unknown commands/flags produce CliErrors with
+ * "did you mean?" suggestions instead of a bare crash.
+ */
+import { isValidProfileName } from "../config-file.js";
+import { CliError, EXIT_OK } from "./cli-error.js";
+import { renderCommandHelp, renderRootHelp } from "./help.js";
+import { parseArgv } from "./parser.js";
+import { GLOBAL_FLAGS, specPaths } from "./spec.js";
+import { suggestCommands, suggestFlags } from "./suggest.js";
+function findMatch(registry, positionals) {
+    // Longest prefix first so nested paths shadow their parents.
+    for (let len = positionals.length; len >= 1; len--) {
+        const candidate = positionals.slice(0, len);
+        for (const command of registry) {
+            for (const p of specPaths(command.spec)) {
+                if (p.length === candidate.length && p.every((part, i) => part === candidate[i])) {
+                    return { command, consumed: len };
+                }
+            }
+        }
+    }
+    return null;
+}
+function validFlagNames(spec) {
+    const names = new Set();
+    for (const f of spec.flags)
+        names.add(f.name);
+    for (const f of GLOBAL_FLAGS)
+        names.add(f.name);
+    return [...names];
+}
+function flagSpecFor(spec, name) {
+    for (const f of spec.flags)
+        if (f.name === name)
+            return f;
+    for (const f of GLOBAL_FLAGS)
+        if (f.name === name)
+            return f;
+    return undefined;
+}
+export async function dispatch(registry, argv, opts) {
+    const program = opts.programName ?? 'boombot';
+    const parsed = parseArgv(argv);
+    if (parsed.version) {
+        console.log(opts.version);
+        return EXIT_OK;
+    }
+    if (parsed.positionals.length === 0) {
+        if (!parsed.help && opts.defaultCommand?.length) {
+            return dispatch(registry, [...opts.defaultCommand, ...argv], opts);
+        }
+        // `boombot` or `boombot --help` (or only flags): root help. An explicit
+        // --help is success; a bare invocation is a usage error (exit 2),
+        // preserving the old exit-nonzero-on-no-command contract.
+        console.log(renderRootHelp(registry, { version: opts.version, programName: program }));
+        return parsed.help ? EXIT_OK : 2;
+    }
+    const match = findMatch(registry, parsed.positionals);
+    if (match === null) {
+        const suggestions = suggestCommands(registry.map((c) => c.spec), [...parsed.positionals]);
+        throw new CliError({
+            code: 'UNKNOWN_COMMAND',
+            message: `unknown command: ${parsed.positionals.join(' ')}`,
+            suggestions,
+            nextSteps: suggestions.length > 0
+                ? []
+                : [`Run \`${program} --help\` for the command list.`],
+        });
+    }
+    const { command, consumed } = match;
+    const extra = parsed.positionals.slice(consumed);
+    if (parsed.help) {
+        console.log(renderCommandHelp(command.spec, { programName: program }));
+        return EXIT_OK;
+    }
+    if (extra.length > 0 && command.spec.acceptsPositionals !== true) {
+        throw new CliError({
+            code: 'UNEXPECTED_ARGUMENT',
+            message: `unexpected argument: ${extra.join(' ')}`,
+            nextSteps: [`Run \`${program} ${command.spec.path.join(' ')} --help\` for usage.`],
+        });
+    }
+    // Flag validation against the spec (+ globals).
+    const valid = validFlagNames(command.spec);
+    for (const name of Object.keys(parsed.flags)) {
+        const decl = flagSpecFor(command.spec, name);
+        if (decl === undefined) {
+            const suggestions = suggestFlags(name, valid);
+            throw new CliError({
+                code: 'UNKNOWN_FLAG',
+                message: `unknown flag: --${name}`,
+                suggestions: suggestions.map((s) => `${command.spec.path.join(' ')} --${s}`),
+                nextSteps: [
+                    `Valid flags: ${valid
+                        .sort()
+                        .map((n) => `--${n}`)
+                        .join(', ')}`,
+                ],
+            });
+        }
+        if (decl.takesValue && parsed.flags[name] === true) {
+            throw new CliError({
+                code: 'MISSING_FLAG_VALUE',
+                message: `--${name} requires a value`,
+                nextSteps: [`Run \`${program} ${command.spec.path.join(' ')} --help\` for usage.`],
+            });
+        }
+    }
+    // `--config` keeps its historical meaning: env override before handlers run.
+    const configFlag = parsed.flags['config'];
+    const profileFlag = parsed.flags['profile'];
+    const profile = typeof profileFlag === 'string' ? profileFlag : process.env['BOOMBOT_PROFILE'];
+    if ((typeof profileFlag === 'string' && !isValidProfileName(profileFlag)) ||
+        (profileFlag === undefined && profile !== undefined && profile !== '' && !isValidProfileName(profile))) {
+        throw new CliError({
+            code: 'INVALID_FLAG_VALUE',
+            message: 'profile must match [a-z0-9][a-z0-9_-]{0,63}',
+        });
+    }
+    if (typeof configFlag === 'string' && configFlag !== '') {
+        process.env['BOOMBOT_CONFIG'] = configFlag;
+    }
+    if (typeof profileFlag === 'string')
+        process.env['BOOMBOT_PROFILE'] = profileFlag;
+    const ctx = {
+        flags: parsed.flags,
+        positionals: extra,
+        json: parsed.json,
+        rawArgs: argv,
+    };
+    const code = await command.handler(ctx);
+    return code ?? EXIT_OK;
+}

package/dist/cli/cli/help.js

@@ -0,0 +1,83 @@
+/**
+ * Help text — GENERATED from the command registry, never hand-written.
+ *
+ * If a command exists in the registry, it shows up in `--help` with the
+ * right summary, flags and examples. Adding a command = adding a spec.
+ */
+import { GLOBAL_FLAGS, specPaths } from "./spec.js";
+function flagUsage(flag) {
+    const long = flag.takesValue ? `--${flag.name} ${flag.valueName ?? '<value>'}` : `--${flag.name}`;
+    return flag.short !== undefined ? `-${flag.short}, ${long}` : long;
+}
+function flagLine(flag) {
+    const env = flag.env !== undefined ? ` (also: ${flag.env}=…)` : '';
+    return `  ${flagUsage(flag).padEnd(24)} ${flag.description}${env}`;
+}
+/** `boombot --help` — every visible command, generated from specs. */
+export function renderRootHelp(commands, opts) {
+    const program = opts.programName ?? 'boombot';
+    const visible = commands.filter((c) => c.spec.hidden !== true);
+    const lines = [
+        `${program} ${opts.version} — BoomBot command-line interface`,
+        '',
+        'Usage:',
+        `  ${program}                        start locally; configure a provider in the web UI`,
+        `  ${program} <command> [options]`,
+        `  ${program} <command> --help    show help for a command`,
+        '',
+        'Commands:',
+    ];
+    for (const { spec } of visible) {
+        const name = spec.path.join(' ');
+        const alias = spec.aliases !== undefined && spec.aliases.length > 0
+            ? ` (${spec.aliases.map((a) => a.join(' ')).join(', ')})`
+            : '';
+        lines.push(`  ${name.padEnd(16)}${spec.summary}${alias}`);
+    }
+    lines.push('', 'Global options:');
+    for (const flag of GLOBAL_FLAGS)
+        lines.push(flagLine(flag));
+    lines.push('', `Run \`${program} <command> --help\` for command details.`);
+    return lines.join('\n');
+}
+/** `boombot <command> --help` — usage, flags, examples, notes. */
+export function renderCommandHelp(spec, opts) {
+    const program = opts.programName ?? 'boombot';
+    const lines = [
+        `${program} ${spec.path.join(' ')} — ${spec.summary}`,
+        '',
+        'Usage:',
+        `  ${spec.usage}`,
+        '',
+    ];
+    if (spec.aliases !== undefined && spec.aliases.length > 0) {
+        lines.push(`Aliases: ${spec.aliases.map((a) => `${program} ${a.join(' ')}`).join(', ')}`, '');
+    }
+    if (spec.flags.length > 0) {
+        lines.push('Options:');
+        for (const flag of spec.flags)
+            lines.push(flagLine(flag));
+        lines.push('');
+    }
+    lines.push('Global options:');
+    for (const flag of GLOBAL_FLAGS)
+        lines.push(flagLine(flag));
+    lines.push('');
+    if (spec.examples !== undefined && spec.examples.length > 0) {
+        lines.push('Examples:');
+        for (const ex of spec.examples)
+            lines.push(`  ${ex}`);
+        lines.push('');
+    }
+    if (spec.notes !== undefined && spec.notes.length > 0) {
+        lines.push('Notes:');
+        for (const note of spec.notes)
+            lines.push(`  - ${note}`);
+        lines.push('');
+    }
+    return lines.join('\n').trimEnd();
+}
+/** All spellings users may type (canonical + aliases), for tests/docs. */
+export function allCommandSpellings(specs) {
+    return specs.flatMap((s) => [...specPaths(s)]);
+}

package/dist/cli/cli/parser.js

@@ -0,0 +1,89 @@
+/**
+ * argv parser — intentionally small and heuristic.
+ *
+ * Splits raw argv into positionals (command path candidates) and flags.
+ * Whether a flag takes a value is validated LATER against the spec in
+ * dispatch.ts; here the rule is only: `--flag <next>` consumes the next
+ * token when it does not look like a flag. `--` ends flag parsing.
+ */
+import { CliError } from "./cli-error.js";
+import { SHORT_FLAGS } from "./spec.js";
+function isFlagToken(token) {
+    return token.startsWith('-') && token.length > 1;
+}
+export function parseArgv(argv) {
+    const positionals = [];
+    const flags = {};
+    let json = false;
+    let help = false;
+    let version = false;
+    let onlyPositionals = false;
+    const setKnownBoolean = (name) => {
+        if (name === 'json') {
+            json = true;
+            return true;
+        }
+        if (name === 'help') {
+            help = true;
+            return true;
+        }
+        if (name === 'version') {
+            version = true;
+            return true;
+        }
+        return false;
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === undefined)
+            continue;
+        if (onlyPositionals) {
+            positionals.push(arg);
+            continue;
+        }
+        if (arg === '--') {
+            onlyPositionals = true;
+            continue;
+        }
+        if (arg.startsWith('--')) {
+            const eq = arg.indexOf('=');
+            if (eq !== -1) {
+                const name = arg.slice(2, eq);
+                const value = arg.slice(eq + 1);
+                if (name === '')
+                    throw new CliError({ code: 'UNKNOWN_FLAG', message: `bad flag: ${arg}` });
+                if (!setKnownBoolean(name))
+                    flags[name] = value;
+                continue;
+            }
+            const name = arg.slice(2);
+            if (name === '')
+                throw new CliError({ code: 'UNKNOWN_FLAG', message: `bad flag: ${arg}` });
+            if (!setKnownBoolean(name)) {
+                const next = argv[i + 1];
+                if (next !== undefined && !isFlagToken(next)) {
+                    flags[name] = next;
+                    i++;
+                }
+                else {
+                    flags[name] = true;
+                }
+            }
+            continue;
+        }
+        if (arg.startsWith('-') && !arg.startsWith('--')) {
+            // Single-dash: only -h / -v are known; anything else is recorded raw
+            // and rejected later by dispatch flag validation (with suggestions).
+            const mapped = SHORT_FLAGS[arg.slice(1)];
+            if (mapped !== undefined && arg.length === 2) {
+                setKnownBoolean(mapped);
+            }
+            else {
+                flags[arg.slice(1)] = true;
+            }
+            continue;
+        }
+        positionals.push(arg);
+    }
+    return { positionals, flags, json, help, version };
+}