@pellux/goodvibes-daemon 1.28.0

package/src/cli/completion.ts

@@ -0,0 +1,299 @@
+/**
+ * completion.ts — shell completion generated from the command catalog.
+ *
+ * The scripts are DERIVED, never hand-maintained: a command added to
+ * `./command-catalog.ts` is completable the moment it exists, and one removed
+ * stops being offered. A hand-written completion script is a second vocabulary,
+ * and a second vocabulary drifts.
+ *
+ * What each script completes:
+ *   - the command word (names and aliases, in catalog order)
+ *   - a command's own sub-words (`sessions list`, `config get`, `webui enable`)
+ *   - a command's flags plus the global ones, once a command word is present
+ *
+ * Values are deliberately NOT completed. A settings key, a session id or a host
+ * name would each have to be fetched from a running daemon, and a completion
+ * that hangs while a socket times out is worse than one that offers nothing.
+ */
+import {
+  DAEMON_COMMANDS,
+  GLOBAL_FLAGS,
+  daemonCommandSpec,
+  flagsForCommand,
+  type DaemonCommand,
+} from './command-catalog.ts';
+
+export const COMPLETION_SHELLS = ['bash', 'zsh', 'fish'] as const;
+export type CompletionShell = (typeof COMPLETION_SHELLS)[number];
+
+export function isCompletionShell(value: string | undefined): value is CompletionShell {
+  return typeof value === 'string' && (COMPLETION_SHELLS as readonly string[]).includes(value);
+}
+
+/** Every word that selects a command, catalog order, names before aliases. */
+export function completionCommandWords(): readonly string[] {
+  return DAEMON_COMMANDS.flatMap((spec) => [spec.name, ...spec.aliases]);
+}
+
+/** Long and short flag tokens a command accepts, its own plus the global ones. */
+export function completionFlagsFor(command: DaemonCommand): readonly string[] {
+  return flagsForCommand(command).flatMap((flag) => flag.tokens);
+}
+
+/** A shell-safe identifier fragment (`goodvibes-daemon` -> `goodvibes_daemon`). */
+function shellIdent(value: string): string {
+  return value.replace(/[^A-Za-z0-9_]/g, '_');
+}
+
+function bashScript(binary: string): string {
+  const fn = `_${shellIdent(binary)}_complete`;
+  const commandWords = completionCommandWords().join(' ');
+  const globalFlags = GLOBAL_FLAGS.flatMap((flag) => flag.tokens).join(' ');
+
+  const caseArms = DAEMON_COMMANDS.map((spec) => {
+    const words = [spec.name, ...spec.aliases].join('|');
+    const flags = completionFlagsFor(spec.name).join(' ');
+    const subs = spec.subcommands.join(' ');
+    return [
+      `    ${words})`,
+      `      __gvd_flags="${flags}"`,
+      `      __gvd_subs="${subs}"`,
+      '      ;;',
+    ].join('\n');
+  }).join('\n');
+
+  return [
+    `# bash completion for ${binary} — generated from its command catalog.`,
+    `# Install: ${binary} completion bash > ~/.local/share/bash-completion/completions/${binary}`,
+    '',
+    `${fn}() {`,
+    '  local cur prev words cword',
+    '  cur="${COMP_WORDS[COMP_CWORD]}"',
+    '  prev="${COMP_WORDS[COMP_CWORD-1]}"',
+    '',
+    `  local __gvd_commands="${commandWords}"`,
+    `  local __gvd_global="${globalFlags}"`,
+    '  local __gvd_flags=""',
+    '  local __gvd_subs=""',
+    '  local __gvd_command=""',
+    '',
+    '  # The first word that is not an option and not an option value is the command.',
+    '  local i',
+    '  for (( i=1; i < COMP_CWORD; i++ )); do',
+    '    local w="${COMP_WORDS[i]}"',
+    '    case "$w" in',
+    '      -*) continue ;;',
+    '      *)',
+    '        case " $__gvd_commands " in',
+    '          *" $w "*) __gvd_command="$w"; break ;;',
+    '        esac',
+    '        ;;',
+    '    esac',
+    '  done',
+    '',
+    '  if [[ -z "$__gvd_command" ]]; then',
+    '    if [[ "$cur" == -* ]]; then',
+    '      COMPREPLY=( $(compgen -W "$__gvd_global" -- "$cur") )',
+    '    else',
+    '      COMPREPLY=( $(compgen -W "$__gvd_commands" -- "$cur") )',
+    '    fi',
+    '    return 0',
+    '  fi',
+    '',
+    '  case "$__gvd_command" in',
+    caseArms,
+    '  esac',
+    '',
+    '  if [[ "$cur" == -* ]]; then',
+    '    COMPREPLY=( $(compgen -W "$__gvd_flags" -- "$cur") )',
+    '  else',
+    '    COMPREPLY=( $(compgen -W "$__gvd_subs" -- "$cur") )',
+    '  fi',
+    '  return 0',
+    '}',
+    '',
+    `complete -F ${fn} ${binary}`,
+    '',
+  ].join('\n');
+}
+
+function zshDescribe(value: string): string {
+  // Colons separate a zsh completion candidate from its description.
+  return value.replace(/:/g, '\\:').replace(/'/g, "'\\''");
+}
+
+function zshScript(binary: string): string {
+  const commandLines = DAEMON_COMMANDS
+    .map((spec) => `    '${zshDescribe(spec.name)}:${zshDescribe(spec.summary)}'`)
+    .join('\n');
+
+  const caseArms = DAEMON_COMMANDS.map((spec) => {
+    const words = [spec.name, ...spec.aliases].join('|');
+    const flags = completionFlagsFor(spec.name)
+      .map((token) => `'${zshDescribe(token)}'`)
+      .join(' ');
+    const subs = spec.subcommands.map((sub) => `'${zshDescribe(sub)}'`).join(' ');
+    return [
+      `      ${words})`,
+      `        __gvd_flags=(${flags})`,
+      `        __gvd_subs=(${subs})`,
+      '        ;;',
+    ].join('\n');
+  }).join('\n');
+
+  const fn = `_${shellIdent(binary)}`;
+  return [
+    `#compdef ${binary}`,
+    `# zsh completion for ${binary} — generated from its command catalog.`,
+    `# Install: ${binary} completion zsh > ~/.zfunc/_${binary}   (with ~/.zfunc on $fpath)`,
+    '',
+    `${fn}() {`,
+    '  local -a __gvd_commands __gvd_flags __gvd_subs',
+    '  __gvd_commands=(',
+    commandLines,
+    '  )',
+    '',
+    '  local __gvd_command="" w',
+    '  for w in ${words[2,CURRENT-1]}; do',
+    '    case $w in',
+    '      -*) continue ;;',
+    '      *) __gvd_command=$w; break ;;',
+    '    esac',
+    '  done',
+    '',
+    '  if [[ -z $__gvd_command ]]; then',
+    '    _describe -t commands "command" __gvd_commands',
+    '    return',
+    '  fi',
+    '',
+    '  case $__gvd_command in',
+    caseArms,
+    '  esac',
+    '',
+    '  if [[ ${words[CURRENT]} == -* ]]; then',
+    '    compadd -a __gvd_flags',
+    '  else',
+    '    compadd -a __gvd_subs',
+    '  fi',
+    '}',
+    '',
+    `${fn} "$@"`,
+    '',
+  ].join('\n');
+}
+
+function fishEscape(value: string): string {
+  return value.replace(/'/g, "\\'");
+}
+
+function fishScript(binary: string): string {
+  const guard = `__${shellIdent(binary)}_no_command`;
+  const lines: string[] = [
+    `# fish completion for ${binary} — generated from its command catalog.`,
+    `# Install: ${binary} completion fish > ~/.config/fish/completions/${binary}.fish`,
+    '',
+    `function ${guard}`,
+    '  set -l tokens (commandline -opc)',
+    '  set -e tokens[1]',
+    '  for token in $tokens',
+    '    switch $token',
+    "      case '-*'",
+    '        continue',
+    "      case '*'",
+    '        return 1',
+    '    end',
+    '  end',
+    '  return 0',
+    'end',
+    '',
+  ];
+
+  for (const spec of DAEMON_COMMANDS) {
+    lines.push(
+      `complete -c ${binary} -n '${guard}' `
+        + `-a '${fishEscape(spec.name)}' -d '${fishEscape(spec.summary)}'`,
+    );
+  }
+  lines.push('');
+
+  for (const spec of DAEMON_COMMANDS) {
+    for (const sub of spec.subcommands) {
+      lines.push(`complete -c ${binary} -n '__fish_seen_subcommand_from ${spec.name}' -a '${fishEscape(sub)}'`);
+    }
+    for (const flag of daemonCommandSpec(spec.name).flags) {
+      for (const token of flag.tokens) {
+        const option = token.startsWith('--') ? `-l ${token.slice(2)}` : `-s ${token.slice(1)}`;
+        const takesValue = flag.kind === 'boolean' ? '' : ' -r';
+        lines.push(
+          `complete -c ${binary} -n '__fish_seen_subcommand_from ${spec.name}' `
+            + `${option}${takesValue} -d '${fishEscape(flag.summary)}'`,
+        );
+      }
+    }
+  }
+
+  lines.push('');
+  for (const flag of GLOBAL_FLAGS) {
+    for (const token of flag.tokens) {
+      const option = token.startsWith('--') ? `-l ${token.slice(2)}` : `-s ${token.slice(1)}`;
+      const takesValue = flag.kind === 'boolean' ? '' : ' -r';
+      lines.push(`complete -c ${binary} ${option}${takesValue} -d '${fishEscape(flag.summary)}'`);
+    }
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+export function renderCompletionScript(shell: CompletionShell, binary = 'goodvibes-daemon'): string {
+  if (shell === 'bash') return bashScript(binary);
+  if (shell === 'zsh') return zshScript(binary);
+  return fishScript(binary);
+}
+
+export interface CompletionCommandResult {
+  readonly exitCode: number;
+  readonly lines: readonly string[];
+}
+
+/**
+ * `goodvibes-daemon completion <shell>`.
+ *
+ * A missing or unrecognized shell is a usage refusal (exit 2) naming the ones
+ * that exist, rather than a default guess: writing a bash script into a zsh
+ * fpath produces a completion that silently never fires.
+ */
+export function runCompletionCommand(
+  argv: readonly string[],
+  binary = 'goodvibes-daemon',
+): CompletionCommandResult {
+  const positional = argv.filter((token) => !token.startsWith('-'));
+  const shell = positional[0];
+  if (shell === undefined) {
+    return {
+      exitCode: 2,
+      lines: [
+        'completion: name the shell.',
+        `  ${binary} completion ${COMPLETION_SHELLS.join('|')}`,
+      ],
+    };
+  }
+  if (!isCompletionShell(shell)) {
+    return {
+      exitCode: 2,
+      lines: [
+        `completion: '${shell}' is not a shell this generates for.`,
+        `  ${binary} completion ${COMPLETION_SHELLS.join('|')}`,
+      ],
+    };
+  }
+  if (positional.length > 1) {
+    return {
+      exitCode: 2,
+      lines: [
+        `completion: '${positional[1]}' is one argument too many.`,
+        `  ${binary} completion ${COMPLETION_SHELLS.join('|')}`,
+      ],
+    };
+  }
+  return { exitCode: 0, lines: [renderCompletionScript(shell, binary)] };
+}

package/src/cli/help.ts

@@ -0,0 +1,167 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { VERSION } from '../version.ts';
+import {
+  DAEMON_COMMANDS,
+  GLOBAL_FLAGS,
+  daemonCommandSpec,
+  resolveDaemonCommand,
+  type DaemonCommandFlagSpec,
+} from './command-catalog.ts';
+
+function readJsonVersion(path: string): string | null {
+  try {
+    if (!existsSync(path)) return null;
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as { name?: unknown; version?: unknown };
+    // Only trust OUR package.json — a compiled single-file binary can resolve
+    // this path to a different package.json (a bundled dependency's) that
+    // reports a placeholder like "0.0.0". Fall through to the baked VERSION in
+    // that case rather than rendering a stray version in `--version`/banners.
+    if (parsed.name !== 'goodvibes-daemon') return null;
+    return typeof parsed.version === 'string' && parsed.version.length > 0 ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+
+export function getPackageVersion(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return readJsonVersion(join(here, '..', '..', 'package.json'))
+    ?? VERSION;
+}
+
+export function renderGoodVibesVersion(binary = 'goodvibes-daemon'): string {
+  return `${binary} ${getPackageVersion()}`;
+}
+
+/**
+ * Honest one-line startup identity for the daemon binary, emitted right as it
+ * begins serving — including on a bare (no-arg) systemd launch. It states the
+ * RESOLVED version (never a placeholder), the home/host/port it actually bound,
+ * and points at the real service-setup command. This replaces the field
+ * behavior where a bare launch showed a wrong "v0.0.0" banner and gave an
+ * operator nothing to act on. `version` is passed in (never read from the live
+ * build here) so callers/tests can pin a sentinel and never compare the live
+ * VERSION.
+ */
+export function renderDaemonStartupBanner(
+  version: string,
+  binding: { readonly homeDir: string; readonly host: string; readonly port: number },
+  binary = 'goodvibes-daemon',
+): string {
+  return (
+    `${binary} ${version} starting — ` +
+    `home=${binding.homeDir} host=${binding.host} port=${binding.port} ` +
+    `(manage as a service: ${binary} install-service)`
+  );
+}
+
+/**
+ * What the host actually uses to keep the daemon running, named per platform.
+ *
+ * The help said "systemd user service" on every platform, including macOS,
+ * where `install-service` writes a launchd agent and nothing named systemd
+ * exists. Taking the platform as an argument keeps that testable without
+ * stubbing `process`.
+ */
+export function serviceKindForPlatform(platform: NodeJS.Platform = process.platform): string {
+  if (platform === 'darwin') return 'launchd user agent';
+  if (platform === 'win32') return 'Scheduled Task';
+  return 'systemd user service';
+}
+
+const COLUMN = 32;
+
+function pad(left: string): string {
+  return left.length >= COLUMN ? `${left}\n${' '.repeat(COLUMN)}` : left.padEnd(COLUMN);
+}
+
+/** `-y, --yes` / `    --json` / `-m, --model <registryKey>` */
+function renderFlagLine(flag: DaemonCommandFlagSpec): string {
+  const shorts = flag.tokens.filter((token) => !token.startsWith('--'));
+  const longs = flag.tokens.filter((token) => token.startsWith('--'));
+  const value = flag.valueName ? ` <${flag.valueName}>` : '';
+  const left = shorts.length > 0
+    ? `  ${shorts.join(', ')}, ${longs.join(', ')}${value}`
+    : `      ${longs.join(', ')}${value}`;
+  return `${pad(left)}${flag.summary}`;
+}
+
+/**
+ * The top-level help: what the binary is, what it does, what it accepts, and
+ * what its exit codes mean. Generated from the catalog, so a command that
+ * exists is listed and a command that is listed exists.
+ */
+export function renderGoodVibesDaemonHelp(
+  binary = 'goodvibes-daemon',
+  platform: NodeJS.Platform = process.platform,
+): string {
+  const commands = DAEMON_COMMANDS
+    .filter((spec) => spec.name !== 'serve')
+    .map((spec) => `${pad(`  ${spec.name}`)}${spec.summary}`);
+
+  return [
+    `Usage: ${binary} [COMMAND] [OPTIONS]`,
+    '',
+    'The GoodVibes daemon: the one long-running host for the control plane, the',
+    'channels, cluster membership, scheduled work, the knowledge and memory stores,',
+    'and the verb families every GoodVibes client calls.',
+    '',
+    `Run with no command it starts serving in the foreground. Run \`${binary}`,
+    `install-service\` to have it come back after a reboot as a ${serviceKindForPlatform(platform)}.`,
+    '',
+    'Commands:',
+    ...commands,
+    '',
+    `Run \`${binary} help <command>\` for a command's own arguments and flags.`,
+    '',
+    'Global options (accepted by every command):',
+    ...GLOBAL_FLAGS.map(renderFlagLine),
+    '',
+    'Serving options (a bare invocation, or `serve`):',
+    ...daemonCommandSpec('serve').flags.map(renderFlagLine),
+    '',
+    'Exit codes:',
+    `${pad('  0')}the command did what it says`,
+    `${pad('  1')}it ran and failed — the reason is printed`,
+    `${pad('  2')}the command line was wrong: an unknown command, an unknown flag,`,
+    `${pad('   ')}a flag this command does not take, or a missing value`,
+    `${pad('  3')}service-status only: installed, but not running`,
+    `${pad('  4')}service-status only: not installed`,
+  ].join('\n');
+}
+
+/**
+ * `help <command>` — one command's usage, its own flags, and what it does.
+ *
+ * Returns null when the word names no command, so the caller can refuse with
+ * the same "Unknown command" message the parser produces rather than printing
+ * a help page for something that does not exist.
+ */
+export function renderDaemonCommandHelp(
+  commandWord: string,
+  binary = 'goodvibes-daemon',
+  platform: NodeJS.Platform = process.platform,
+): string | null {
+  const command = resolveDaemonCommand(commandWord);
+  if (command === undefined) return null;
+  const spec = daemonCommandSpec(command);
+  const usage = spec.usage.replace(/^goodvibes-daemon/, binary);
+
+  const lines = [`Usage: ${usage}`, '', ...spec.detail];
+  if (spec.flags.length > 0) {
+    lines.push('', 'Options:', ...spec.flags.map(renderFlagLine));
+  }
+  if (spec.passthrough) {
+    lines.push(
+      '',
+      `This command has its own flags; run \`${binary} ${spec.name}\` with none to see them.`,
+    );
+  }
+  lines.push('', 'Global options:', ...GLOBAL_FLAGS.map(renderFlagLine));
+  if (spec.name.endsWith('-service')) {
+    lines.push('', `On this host that means a ${serviceKindForPlatform(platform)}.`);
+  }
+  return lines.join('\n');
+}

package/src/cli/index.ts

@@ -0,0 +1,21 @@
+/**
+ * CLI barrel for the daemon product.
+ *
+ * Two halves, deliberately separable:
+ *   - `command-catalog.ts` is WHAT this binary understands — every command,
+ *     alias, flag and help string, as data.
+ *   - `parser.ts`, `help.ts` and `completion.ts` are the ENGINE that reads a
+ *     catalog and produces a parse, a help page or a completion script. None of
+ *     them names a daemon command.
+ *
+ * The argument surface a `goodvibes` front-end shares — the parse engine's
+ * catalog contract, redaction, config overrides, settings-value reading and
+ * endpoint resolution — is @pellux/goodvibes-terminal-shell's, imported at the
+ * point of use. What stays here is what only this binary has: its own command
+ * vocabulary, and the help and completion built on it.
+ */
+export * from './types.ts';
+export * from './command-catalog.ts';
+export * from './parser.ts';
+export * from './help.ts';
+export * from './completion.ts';

package/src/cli/parser.ts

@@ -0,0 +1,55 @@
+/**
+ * parser.ts — this binary's command line, read by the shared argument engine.
+ *
+ * The engine is `parseWithCatalog` in @pellux/goodvibes-terminal-shell: tokens,
+ * values, arity, `--`, refusals, and no knowledge of any product's commands.
+ * Everything daemon-shaped is in ./command-catalog.ts, and this file is the two
+ * lines that put them together.
+ *
+ * THE TWO RULES THE CATALOG ASKS THE ENGINE TO ENFORCE
+ *
+ * 1. Serving happens on a bare invocation or on `serve`, and on nothing else.
+ *    Previously an unmatched word became a positional and the process fell
+ *    through to "start a daemon in the foreground", so `goodvibes-daemon
+ *    doctor`, `goodvibes-daemon sessions` and `goodvibes-daemon install-servce`
+ *    all silently served. `unmatchedFirstToken: 'reject'` is what ends that.
+ *
+ * 2. Every refusal is a refusal. An unrecognized command, a flag that belongs
+ *    to another surface, a flag this command does not take, a missing value —
+ *    each produces an error line, and the caller exits 2 with the help. Nothing
+ *    is accepted-and-ignored.
+ */
+import {
+  findCatalogFlagArityConflicts as findConflictsIn,
+  parseWithCatalog,
+} from '@pellux/goodvibes-terminal-shell';
+import { DAEMON_CLI_CATALOG } from './command-catalog.ts';
+import type { DaemonCliParseResult } from './types.ts';
+
+/**
+ * Parse a daemon command line.
+ *
+ * Never throws: every problem comes back as a line in `errors`, so the caller
+ * decides how to report it (this binary writes them to the descriptor a service
+ * journal is attached to, then exits 2).
+ */
+export function parseDaemonCli(
+  argv: readonly string[],
+  binary = 'goodvibes-daemon',
+): DaemonCliParseResult {
+  return parseWithCatalog(argv, DAEMON_CLI_CATALOG, binary);
+}
+
+/**
+ * This catalog's own consistency, checked rather than assumed.
+ *
+ * The engine's search for the command word runs before the command is known
+ * and therefore reads arity from one table shared across commands. That is only
+ * honest while no token means "boolean" under one command and "takes a value"
+ * under another. Exported bound to this catalog so a unit test asserts it on
+ * the real vocabulary; a violation comes back as a list of problems, never
+ * thrown, so the test can name them.
+ */
+export function findCatalogFlagArityConflicts(): readonly string[] {
+  return findConflictsIn(DAEMON_CLI_CATALOG);
+}

package/src/cli/surface-catalog.ts

@@ -0,0 +1,26 @@
+import type { ConfigKey } from '@pellux/goodvibes-sdk/platform/config';
+
+/**
+ * The channel surfaces the platform can speak on, with the settings keys each
+ * one needs configured.
+ *
+ * The daemon reads this to answer "which channels are actually usable" — the
+ * `send` subcommand lists them and refuses a channel whose keys are unset,
+ * rather than accepting the message and dropping it. A surface added here
+ * becomes visible to `send` with no further wiring.
+ */
+export const SURFACE_CONFIGS = [
+  ['slack', 'Slack', ['surfaces.slack.signingSecret', 'surfaces.slack.botToken']],
+  ['discord', 'Discord', ['surfaces.discord.publicKey', 'surfaces.discord.botToken', 'surfaces.discord.applicationId']],
+  ['telegram', 'Telegram', ['surfaces.telegram.botToken']],
+  ['webhook', 'Webhook', ['surfaces.webhook.secret']],
+  ['ntfy', 'ntfy', ['surfaces.ntfy.baseUrl']],
+  ['googleChat', 'Google Chat', ['surfaces.googleChat.webhookUrl']],
+  ['signal', 'Signal', ['surfaces.signal.bridgeUrl', 'surfaces.signal.account']],
+  ['whatsapp', 'WhatsApp', ['surfaces.whatsapp.accessToken', 'surfaces.whatsapp.phoneNumberId']],
+  ['imessage', 'iMessage', ['surfaces.imessage.bridgeUrl', 'surfaces.imessage.account']],
+  ['msteams', 'Microsoft Teams', ['surfaces.msteams.appId', 'surfaces.msteams.appPassword']],
+  ['bluebubbles', 'BlueBubbles', ['surfaces.bluebubbles.serverUrl', 'surfaces.bluebubbles.password']],
+  ['mattermost', 'Mattermost', ['surfaces.mattermost.baseUrl', 'surfaces.mattermost.botToken']],
+  ['matrix', 'Matrix', ['surfaces.matrix.homeserverUrl', 'surfaces.matrix.accessToken', 'surfaces.matrix.userId']],
+] as const;

package/src/cli/types.ts

@@ -0,0 +1,63 @@
+import type { DaemonCommand } from './command-catalog.ts';
+
+/**
+ * Everything a parse can produce.
+ *
+ * One record for every command, rather than a discriminated union per command:
+ * the fields a command does not use are simply left at their empty value, and
+ * the catalog is what decides which flags could have set them. A command's
+ * dispatcher reads only the fields its own catalog entry declares.
+ *
+ * Fields describing starting or resuming a conversation — prompt, print,
+ * outputFormat, noAltScreen, open, continueLast, resume, session, fork,
+ * strict — are not here. This binary does not start or resume conversations,
+ * so those flags are parsed, stored, and read by nothing. See
+ * REJECTED_TERMINAL_FLAGS in ./command-catalog.ts for the refusal that
+ * replaced them.
+ */
+export interface DaemonCliFlags {
+  readonly daemonHome: string | undefined;
+  readonly workingDir: string | undefined;
+  readonly help: boolean;
+  readonly version: boolean;
+  /** `--json`: print one JSON document instead of prose. */
+  readonly json: boolean;
+  /** `-y` / `--yes` / `--non-interactive`: consent to a destructive confirmation. */
+  readonly yes: boolean;
+  /** `update --check`: ask for an update check now. */
+  readonly check: boolean;
+  /** `sessions list --all`: include sessions that have already ended. */
+  readonly all: boolean;
+  readonly provider: string | undefined;
+  readonly model: string | undefined;
+  /** `serve` only: the address to BIND. */
+  readonly hostname: string | undefined;
+  /** `serve`: the port to bind. Remote commands: the port to CALL. */
+  readonly port: number | undefined;
+  /** Remote commands only: the machine to call. */
+  readonly host: string | undefined;
+  /** Remote commands only: the operator token to authenticate with. */
+  readonly token: string | undefined;
+  readonly configOverrides: readonly string[];
+  readonly enableFeatures: readonly string[];
+  readonly disableFeatures: readonly string[];
+}
+
+export interface DaemonCliParseResult {
+  readonly binary: string;
+  /** Always resolved. A bare invocation is `serve`; an unrecognized word is an error. */
+  readonly command: DaemonCommand;
+  /** The word the operator actually typed, when they typed one. */
+  readonly rawCommand: string | undefined;
+  /**
+   * Everything after the command word that is not a flag this parser owns. For
+   * a passthrough command (`send`, `cluster`, `webui`, `provision-wake-model`)
+   * it is every remaining token verbatim, flags included.
+   */
+  readonly commandArgs: readonly string[];
+  readonly flags: DaemonCliFlags;
+  /** Usage refusals. A non-empty list means exit 2 with these lines and the help. */
+  readonly errors: readonly string[];
+  /** Non-fatal notices. Printed, then the command runs. */
+  readonly warnings: readonly string[];
+}