@nuxtseo/cli 0.1.0

package/README.md

@@ -0,0 +1,218 @@
+# NuxtSEO CLI
+
+Use NuxtSEO public Site operations from a terminal, script, or coding agent.
+The CLI sends feature requests through `@nuxtseo/sdk`. It does not call MCP,
+private routes, or providers.
+
+## Install
+
+Install [Node.js](https://nodejs.org) 22 or newer.
+
+```sh
+npm install --global @nuxtseo/cli
+nuxtseo --version
+```
+
+You can also run one command without a global install:
+
+```sh
+npx @nuxtseo/cli sites list
+```
+
+## First Site read
+
+Set a Team API token through your shell or CI secret store, then list the Sites
+the token can access:
+
+```sh
+export NUXTSEO_TOKEN='your-team-api-token'
+nuxtseo sites list
+```
+
+Select a default Site and inspect a Page:
+
+```sh
+nuxtseo sites use site_123
+nuxtseo page inspect https://example.com/about
+```
+
+For an automated read, keep the Site explicit and request JSON:
+
+```sh
+nuxtseo page inspect https://example.com/about \
+  --site site_123 \
+  --json
+```
+
+## Authentication
+
+Run `nuxtseo login`. It prints a pairing code, opens your browser on the
+approval page, and waits. Check that the code in the browser matches the code in
+your terminal, choose a role, and approve. The CLI then receives a Team API
+token and stores it.
+
+The token is an ordinary Team API token labelled `CLI on <hostname>`. It appears
+under Settings > API tokens and is revoked there like any other.
+
+```sh
+nuxtseo login               # pair through the browser
+nuxtseo login --no-browser  # print the URL instead of opening it
+nuxtseo login --with-token  # paste an existing token instead
+```
+
+A pairing request stays open for ten minutes. Denying it creates nothing.
+
+Token resolution order is:
+
+1. `NUXTSEO_TOKEN`
+2. The stored credential
+
+Outside an interactive terminal, `login` reads a token from stdin instead of
+pairing, so CI keeps working. Tokens are never accepted as positional arguments
+or options.
+
+The CLI validates the token with a public Site read, then stores it in the OS
+keychain through optional `@napi-rs/keyring`. When keychain support is
+unavailable, it warns on stderr and uses `~/.nuxtseo/auth.json` with mode `0600`.
+
+`nuxtseo logout` removes the local credential. Revoke the token from the
+NuxtSEO dashboard when it must stop working everywhere. An environment token
+always wins and is unchanged by login or logout.
+
+API host resolution order is:
+
+1. `--api-url`
+2. `NUXTSEO_API_URL`
+3. The host stored by `nuxtseo config`
+4. `https://nuxtseo.com`
+
+## Site selection
+
+Site scoped commands currently resolve a Site in this order:
+
+1. `--site <site-id>`
+2. `NUXTSEO_SITE_ID`
+3. The Site saved by `nuxtseo sites use <site-id>`
+4. The only accessible Site
+5. A selection prompt when several Sites are available in a TTY
+
+Scripts and agents should pass `--site`. Multiple Sites outside a TTY produce
+exit `5`; the CLI never guesses.
+
+An explicit argument, environment value, or stored Site ID goes directly to the
+requested operation. It does not add a `sites.list` request or require
+`sites:read` scope.
+
+## JSON output
+
+For a public API success, `--json` writes the complete protocol response
+envelope to stdout, followed by one newline. The CLI does not unwrap `data`,
+rename fields, rank results, or add local fields. Warnings and diagnostics use
+stderr.
+
+The [OpenAPI 3.1 document](https://nuxtseo.com/docs/api/openapi.json) holds the
+exact paths, request schemas, responses, scopes, and errors. Read it to predict
+an envelope before you call for it.
+
+The SDK validates and parses the HTTP body before the CLI serializes it. The
+JSON value and protocol structure are preserved. Whitespace and object key
+order from the wire are not a byte level guarantee.
+
+When the server returns a valid protocol error body, `--json` writes that body
+to stdout and writes the readable recovery message to stderr.
+
+Local outcomes have no server protocol body. With `--json`, commands such as
+bare `nuxtseo`, `config`, `logout`, and `sites use` emit a tagged CLI-owned JSON
+value with `schemaVersion: 1`. Local failures emit `CliError` with a stable code
+and exit code. These tags are separate from protocol envelopes.
+
+`--help --json` returns the selected command, global options, arguments, and
+subcommands as `CliHelp`. Option names are strict; an unknown option exits `2`
+before authentication or network work.
+
+## Automation controls
+
+The CLI never prompts outside a TTY. `CI=1` or `--no-input` suppresses
+interactive mode in a terminal session. `--json` also implies `--no-input`.
+
+Mutations require confirmation. Pass `--yes` or `-y` in automation:
+
+```sh
+nuxtseo page scan https://example.com/about --site site_123 --yes --json
+```
+
+Agent controls:
+
+| Option | Behavior |
+| --- | --- |
+| `--no-input` | Disable every prompt even when stdin and stdout are TTYs |
+| `--timeout-ms <milliseconds>` | Apply one deadline to Site resolution, SDK retries, and the operation; default `30000`, maximum `300000` |
+
+Request timeouts return `CliError` code `request_timeout` and exit `6`.
+`SIGINT` and `SIGTERM` abort the active request and return exit `130`.
+
+## Commands and paging
+
+```text
+nuxtseo login
+nuxtseo logout
+nuxtseo whoami
+nuxtseo config
+nuxtseo sites list
+nuxtseo sites use <site-id>
+nuxtseo usage
+nuxtseo actions list
+nuxtseo actions show <action-id>
+nuxtseo actions resolve <action-id>
+nuxtseo backlinks recoverable
+nuxtseo mentions list
+nuxtseo page inspect <url>
+nuxtseo page scan <url>
+nuxtseo performance
+nuxtseo search status
+```
+
+The CLI fetches one page per invocation. It does not auto-page or merge
+responses.
+
+| Command | Paging inputs | Default |
+| --- | --- | --- |
+| `actions list` | `--limit 1..25`, `--offset >=0` | `--limit 10 --offset 0` |
+| `actions show` | `--group-id`, `--cursor`, `--limit 1..100` | `--limit 50` |
+| `page inspect` | `--limit 1..200`, `--offset >=0` | `--limit 100 --offset 0` |
+| `backlinks recoverable` | `--limit 1..200`, `--offset >=0` | `--limit 100 --offset 0` |
+| `mentions list` | `--limit 1..200` | `--limit 100` |
+
+Keep the server order for actions. For another page, pass the next offset or
+cursor reported by the response. A cursor is opaque; do not edit or infer it.
+
+## Coding agents
+
+The package ships an agent skill that teaches Claude Code how to drive the CLI.
+Copy it into a project after install:
+
+```sh
+mkdir -p .claude/skills
+cp -R node_modules/@nuxtseo/cli/skills/nuxtseo-cli .claude/skills/
+```
+
+The skill covers the JSON contract, Site selection, paging, mutation consent,
+and what to do for each exit code.
+
+## Exit codes and recovery
+
+| Code | Meaning | Typical recovery |
+| ---: | --- | --- |
+| `0` | Success, including a closed stdout pipe | Continue |
+| `2` | Invalid input or missing mutation confirmation | Fix arguments; use `--yes` for a deliberate mutation |
+| `3` | Missing, invalid, or expired authentication | Replace `NUXTSEO_TOKEN` or run `nuxtseo login` |
+| `4` | Forbidden, scope, or entitlement failure | Use a token with the required access or change plan |
+| `5` | Conflict, stale evidence, or ambiguous Site | Refresh the read; pass `--site` when selection is ambiguous |
+| `6` | Rate, quota, provider, or request timeout | Read retry metadata on stderr and retry later |
+| `7` | Local state, network, contract, or infrastructure failure | Fix the named path or network issue; keep the request ID |
+| `8` | Resource or accessible Site not found | Run `sites list`, then `sites use` or pass `--site` |
+| `130` | Interrupted or cancelled | Confirm no mutation result before retrying |
+
+The CLI prints the exact server error code. When available, stderr also includes
+the request ID, retry delay, rate limit, reset time, and structured details.
+The CLI never falls back to MCP, a private route, or cached feature data.

package/dist/api.d.ts

@@ -0,0 +1,14 @@
+import type { PublicV1Client } from '@nuxtseo/sdk';
+import type { CliResult } from './failures.js';
+import type { GlobalOptions } from './parse.js';
+import type { CliRuntime } from './runtime.js';
+import type { CredentialSource, NuxtSeoConfig, StateError } from './state/index.js';
+export interface ApiContext {
+    apiUrl: string;
+    client: PublicV1Client;
+    config: NuxtSeoConfig;
+    credentialSource: CredentialSource;
+}
+export declare function fromStateError(error: StateError): CliResult<never>;
+export declare function createApiClient(apiUrl: string, token: string): PublicV1Client;
+export declare function loadApiContext(runtime: CliRuntime, globals: GlobalOptions): Promise<CliResult<ApiContext>>;

package/dist/api.js

@@ -0,0 +1,43 @@
+import { createBearerTransport, createPublicV1Client } from '@nuxtseo/sdk';
+import { EXIT_CODE, fail, ok } from './failures.js';
+import { readConfig, resolveApiUrl, resolveCredential } from './state/index.js';
+export function fromStateError(error) {
+    const exitCode = error._tag === 'InvalidCredential'
+        ? EXIT_CODE.authentication
+        : error._tag === 'InvalidApiUrl' || error._tag === 'InvalidConfig'
+            ? EXIT_CODE.invalidInput
+            : EXIT_CODE.infrastructure;
+    const code = error._tag === 'InvalidCredential'
+        ? 'authentication_required'
+        : error._tag === 'InvalidApiUrl' || error._tag === 'InvalidConfig'
+            ? 'invalid_cli_input'
+            : 'state_error';
+    return fail(exitCode, `${error._tag}: ${error.message}`, 'cause' in error ? error.cause : undefined, code);
+}
+export function createApiClient(apiUrl, token) {
+    return createPublicV1Client({
+        transport: createBearerTransport({ baseUrl: apiUrl, token }),
+    });
+}
+export async function loadApiContext(runtime, globals) {
+    const [apiUrl, credential, config] = await Promise.all([
+        resolveApiUrl({ apiUrl: globals.apiUrl, env: runtime.env, paths: runtime.paths }),
+        resolveCredential({ env: runtime.env, paths: runtime.paths }),
+        readConfig({ paths: runtime.paths }),
+    ]);
+    if (apiUrl._tag === 'Err')
+        return fromStateError(apiUrl.error);
+    if (credential._tag === 'Err')
+        return fromStateError(credential.error);
+    if (config._tag === 'Err')
+        return fromStateError(config.error);
+    if (!credential.value) {
+        return fail(EXIT_CODE.authentication, 'authentication_required: Set NUXTSEO_TOKEN or run `nuxtseo login`.\nCreate a Team API token at https://nuxtseo.com/pro/dashboard/settings/api-tokens.');
+    }
+    return ok({
+        apiUrl: apiUrl.value.apiUrl,
+        client: createApiClient(apiUrl.value.apiUrl, credential.value.token),
+        config: config.value,
+        credentialSource: credential.value.source,
+    });
+}

package/dist/browser.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Best-effort browser open. Every failure mode here (headless box, no
+ * `xdg-open`, sandboxed spawn) is expected, so this reports whether it worked
+ * and the caller prints the URL instead. It must never throw, because the poll
+ * loop that follows is what actually completes the login.
+ */
+export declare function openBrowser(url: string): boolean;

package/dist/browser.js

@@ -0,0 +1,24 @@
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+/**
+ * Best-effort browser open. Every failure mode here (headless box, no
+ * `xdg-open`, sandboxed spawn) is expected, so this reports whether it worked
+ * and the caller prints the URL instead. It must never throw, because the poll
+ * loop that follows is what actually completes the login.
+ */
+export function openBrowser(url) {
+    const [command, args] = process.platform === 'darwin'
+        ? ['open', [url]]
+        : process.platform === 'win32'
+            ? ['cmd', ['/c', 'start', '', url]]
+            : ['xdg-open', [url]];
+    try {
+        const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+        child.on('error', () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cli-entry.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli-entry.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { homedir } from 'node:os';
+import process from 'node:process';
+import { runCli } from './cli.js';
+import { createStatePaths } from './state/index.js';
+const abortController = new AbortController();
+const abort = () => abortController.abort(new DOMException('Command interrupted.', 'AbortError'));
+function outputError(cause) {
+    if (cause.code === 'EPIPE')
+        process.exit(0);
+    throw cause;
+}
+process.once('SIGINT', abort);
+process.once('SIGTERM', abort);
+process.stdout.once('error', outputError);
+async function readStdin() {
+    process.stdin.setEncoding('utf8');
+    let input = '';
+    for await (const chunk of process.stdin)
+        input += chunk;
+    return input;
+}
+const interactive = process.stdin.isTTY === true
+    && process.stdout.isTTY === true
+    && process.stderr.isTTY === true
+    && !process.env.CI;
+process.exitCode = await runCli(process.argv.slice(2), {
+    env: process.env,
+    paths: createStatePaths(homedir()),
+    input: process.stdin,
+    output: process.stdout,
+    error: process.stderr,
+    inputIsTTY: process.stdin.isTTY === true,
+    interactive,
+    signal: abortController.signal,
+    requestSignal: abortController.signal,
+    readStdin,
+});
+process.removeListener('SIGINT', abort);
+process.removeListener('SIGTERM', abort);
+process.stdout.removeListener('error', outputError);

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+import type { ExitCode } from './failures.js';
+import type { CliRuntime } from './runtime.js';
+export declare function runCli(rawArgs: readonly string[], runtime: CliRuntime): Promise<ExitCode>;

package/dist/cli.js

@@ -0,0 +1,232 @@
+import * as prompts from '@clack/prompts';
+import { renderUsage, runCommand } from 'citty';
+import { fromStateError, loadApiContext } from './api.js';
+import { commandWithGlobalOptions, describeCommand, resolveCommand, validateCommandOptions, } from './command-contract.js';
+import { createRootCommand } from './commands.js';
+import { EXIT_CODE, fail, fromSdkFailure, ok, unexpectedFailure } from './failures.js';
+import { extractGlobalOptions } from './parse.js';
+import { writeCliResponse, writeDiagnostic, writeOutput, writeProtocolResponse } from './runtime.js';
+import { getCredentialStatus, readConfig, resolveApiUrl, resolveSiteId, updateConfig } from './state/index.js';
+import { VERSION } from './version.js';
+function report(runtime, failure, json = false) {
+    if (json) {
+        if (failure.protocolResponse !== undefined) {
+            writeProtocolResponse(runtime, failure.protocolResponse);
+        }
+        else {
+            writeCliResponse(runtime, {
+                _tag: 'CliError',
+                schemaVersion: 1,
+                error: {
+                    code: failure.code,
+                    exitCode: failure.exitCode,
+                    message: failure.message,
+                },
+            });
+        }
+    }
+    writeDiagnostic(runtime, failure.message);
+    return failure.exitCode;
+}
+function isCittyInputError(cause) {
+    return typeof cause === 'object'
+        && cause !== null
+        && 'code' in cause
+        && typeof cause.code === 'string'
+        && ['EARG', 'E_NO_COMMAND', 'E_UNKNOWN_COMMAND'].includes(cause.code);
+}
+async function rootUsage(runtime, globals) {
+    return renderUsage(createRootCommand(runtime, globals, { result: null }));
+}
+async function requestedUsage(runtime, globals, args) {
+    const root = createRootCommand(runtime, globals, { result: null });
+    const resolved = resolveCommand(root, args.filter(argument => argument !== '--help' && argument !== '-h'));
+    const parentName = resolved.path.length > 1 ? resolved.path.slice(0, -1).join(' ') : undefined;
+    return renderUsage(commandWithGlobalOptions(root, resolved.command), parentName ? { meta: { name: parentName, version: VERSION } } : undefined);
+}
+async function runExplicit(args, runtime, globals) {
+    const execution = { result: null };
+    const command = createRootCommand(runtime, globals, execution);
+    const validOptions = validateCommandOptions(command, args);
+    if (validOptions._tag === 'Err')
+        return validOptions;
+    return runCommand(command, { rawArgs: args })
+        .then(() => execution.result ?? fail(EXIT_CODE.infrastructure, 'unexpected: Command completed without a result.'))
+        .catch((cause) => {
+        if (isCittyInputError(cause))
+            return fail(EXIT_CODE.invalidInput, `invalid_cli_input: ${cause instanceof Error ? cause.message : String(cause)}`);
+        return { _tag: 'Err', error: unexpectedFailure(cause) };
+    });
+}
+async function nonInteractiveBare(runtime, globals) {
+    const [auth, apiUrl, config] = await Promise.all([
+        getCredentialStatus({ env: runtime.env, paths: runtime.paths }),
+        resolveApiUrl({ apiUrl: globals.apiUrl, env: runtime.env, paths: runtime.paths }),
+        readConfig({ paths: runtime.paths }),
+    ]);
+    if (auth._tag === 'Err')
+        return fromStateError(auth.error);
+    if (apiUrl._tag === 'Err')
+        return fromStateError(apiUrl.error);
+    if (config._tag === 'Err')
+        return fromStateError(config.error);
+    const site = resolveSiteId({ siteId: globals.siteId, env: runtime.env, config: config.value });
+    if (site._tag === 'Err')
+        return fail(EXIT_CODE.invalidInput, `${site.error._tag}: ${site.error.message}`);
+    if (globals.json) {
+        writeCliResponse(runtime, {
+            _tag: 'CliStatus',
+            schemaVersion: 1,
+            cliVersion: VERSION,
+            authentication: auth.value,
+            api: { url: apiUrl.value.apiUrl, source: apiUrl.value.source },
+            site: site.value,
+        });
+    }
+    else {
+        writeOutput(runtime, await rootUsage(runtime, globals));
+        writeOutput(runtime, [
+            `Authentication: ${auth.value.authenticated ? auth.value.source : 'not configured'}`,
+            `API: ${apiUrl.value.apiUrl}`,
+            `Selected Site: ${site.value?.siteId ?? 'none'}`,
+        ].join('\n'));
+    }
+    return ok(undefined);
+}
+async function switchSite(runtime, globals) {
+    const api = await loadApiContext(runtime, globals);
+    if (api._tag === 'Err')
+        return api;
+    const listed = await api.value.client.sites.list({}, { signal: runtime.requestSignal });
+    if (listed._tag === 'Err')
+        return fromSdkFailure(listed.error);
+    if (listed.value.data.sites.length === 0)
+        return fail(EXIT_CODE.notFound, 'site_empty: This token has no accessible Sites.', undefined, 'site_empty');
+    const selected = await prompts.select({
+        message: 'Current Site',
+        options: listed.value.data.sites.map(site => ({
+            value: site.id,
+            label: site.name ?? site.url ?? site.id,
+            hint: site.id,
+        })),
+        initialValue: api.value.config.siteId,
+        input: runtime.input,
+        output: runtime.error,
+        signal: runtime.signal,
+    });
+    if (prompts.isCancel(selected))
+        return fail(EXIT_CODE.interrupted, 'interrupted: Site selection cancelled.');
+    const saved = await updateConfig({ siteId: selected }, { paths: runtime.paths });
+    if (saved._tag === 'Err')
+        return fromStateError(saved.error);
+    writeOutput(runtime, `Selected Site: ${selected}`);
+    return ok(undefined);
+}
+async function promptPageUrl(runtime, action) {
+    const url = await prompts.text({
+        message: `${action} which Page?`,
+        placeholder: 'https://example.com/page',
+        input: runtime.input,
+        output: runtime.error,
+        signal: runtime.signal,
+        validate: value => typeof value === 'string' && URL.canParse(value) ? undefined : 'Enter an absolute URL.',
+    });
+    return prompts.isCancel(url)
+        ? fail(EXIT_CODE.interrupted, `interrupted: ${action} cancelled.`)
+        : ok(url);
+}
+async function interactiveBare(runtime, globals) {
+    const [auth, apiUrl, config] = await Promise.all([
+        getCredentialStatus({ env: runtime.env, paths: runtime.paths }),
+        resolveApiUrl({ apiUrl: globals.apiUrl, env: runtime.env, paths: runtime.paths }),
+        readConfig({ paths: runtime.paths }),
+    ]);
+    if (auth._tag === 'Err')
+        return fromStateError(auth.error);
+    if (apiUrl._tag === 'Err')
+        return fromStateError(apiUrl.error);
+    if (config._tag === 'Err')
+        return fromStateError(config.error);
+    prompts.intro(`NuxtSEO ${VERSION}`, { input: runtime.input, output: runtime.error });
+    prompts.note([
+        `Authentication: ${auth.value.authenticated ? auth.value.source : 'not configured'}`,
+        `API: ${apiUrl.value.apiUrl}`,
+        `Current Site: ${config.value.siteId ?? 'none'}`,
+    ].join('\n'), 'Status', { input: runtime.input, output: runtime.error });
+    const selected = await prompts.select({
+        message: 'What would you like to do?',
+        options: [
+            ...(!auth.value.authenticated ? [{ value: 'login', label: 'Log in', hint: 'Team API token' }] : []),
+            { value: 'site', label: 'Switch Site', hint: config.value.siteId ?? 'none selected' },
+            { value: 'actions', label: 'Next actions' },
+            { value: 'inspect', label: 'Inspect a Page' },
+            { value: 'scan', label: 'Scan a Page' },
+            { value: 'performance', label: 'Performance overview' },
+            { value: 'search', label: 'Search Console status' },
+            { value: 'usage', label: 'Account usage' },
+            { value: 'config', label: 'Configuration' },
+            { value: 'exit', label: 'Exit' },
+        ],
+        input: runtime.input,
+        output: runtime.error,
+        signal: runtime.signal,
+    });
+    if (prompts.isCancel(selected) || selected === 'exit')
+        return ok(undefined);
+    if (selected === 'site')
+        return switchSite(runtime, globals);
+    if (selected === 'inspect' || selected === 'scan') {
+        const url = await promptPageUrl(runtime, selected === 'inspect' ? 'Inspect' : 'Scan');
+        return url._tag === 'Err'
+            ? url
+            : runExplicit(['page', selected, url.value], runtime, globals);
+    }
+    const commands = {
+        login: ['login'],
+        actions: ['actions', 'list'],
+        performance: ['performance'],
+        search: ['search', 'status'],
+        usage: ['usage'],
+        config: ['config'],
+    };
+    return runExplicit(commands[selected], runtime, globals);
+}
+export async function runCli(rawArgs, runtime) {
+    const jsonRequested = rawArgs.includes('--json');
+    const parsed = extractGlobalOptions(rawArgs);
+    if (parsed._tag === 'Err')
+        return report(runtime, parsed.error, jsonRequested);
+    const { args, options: globals } = parsed.value;
+    const effectiveRuntime = {
+        ...runtime,
+        interactive: runtime.interactive && !globals.json && !globals.noInput,
+        requestSignal: AbortSignal.any([
+            runtime.requestSignal,
+            AbortSignal.timeout(globals.timeoutMs),
+        ]),
+    };
+    if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
+        if (globals.json)
+            writeCliResponse(effectiveRuntime, { _tag: 'CliVersion', schemaVersion: 1, version: VERSION });
+        else
+            writeOutput(effectiveRuntime, VERSION);
+        return EXIT_CODE.success;
+    }
+    if (args.includes('--help') || args.includes('-h')) {
+        const command = createRootCommand(effectiveRuntime, globals, { result: null });
+        const validOptions = validateCommandOptions(command, args);
+        if (validOptions._tag === 'Err')
+            return report(effectiveRuntime, validOptions.error, globals.json);
+        if (globals.json)
+            writeCliResponse(effectiveRuntime, describeCommand(command, args, VERSION));
+        else
+            writeOutput(effectiveRuntime, await requestedUsage(effectiveRuntime, globals, args));
+        return EXIT_CODE.success;
+    }
+    const result = args.length === 0
+        ? effectiveRuntime.interactive
+            ? await interactiveBare(effectiveRuntime, globals)
+            : await nonInteractiveBare(effectiveRuntime, globals)
+        : await runExplicit(args, effectiveRuntime, globals);
+    return result._tag === 'Ok' ? EXIT_CODE.success : report(effectiveRuntime, result.error, globals.json);
+}

package/dist/command-contract.d.ts

@@ -0,0 +1,33 @@
+import type { CommandDef } from 'citty';
+import type { CliResult } from './failures.js';
+export interface ResolvedCommand {
+    command: CommandDef<any>;
+    path: string[];
+    remaining: readonly string[];
+}
+export interface CliHelpArgument {
+    name: string;
+    type: 'boolean' | 'enum' | 'positional' | 'string';
+    required: boolean;
+    description?: string;
+    valueHint?: string;
+    aliases?: string[];
+    options?: string[];
+}
+export interface CliHelpResponse {
+    _tag: 'CliHelp';
+    schemaVersion: 1;
+    cliVersion: string;
+    command: string;
+    description?: string;
+    globalOptions: CliHelpArgument[];
+    arguments: CliHelpArgument[];
+    subcommands: Array<{
+        name: string;
+        description?: string;
+    }>;
+}
+export declare function resolveCommand(root: CommandDef<any>, rawArgs: readonly string[]): ResolvedCommand;
+export declare function describeCommand(root: CommandDef<any>, rawArgs: readonly string[], cliVersion: string): CliHelpResponse;
+export declare function validateCommandOptions(root: CommandDef<any>, rawArgs: readonly string[]): CliResult<void>;
+export declare function commandWithGlobalOptions(root: CommandDef<any>, command: CommandDef<any>): CommandDef<any>;