export declare const CLI_NAME: "framework";

/**
 * `voltro help` grouped by the job each command does, in the order a user meets
 * them (scaffold → develop → data → build/run → deploy → observe → maintain).
 *
 * A FLAT list of 45 commands in registry order is unusable: most summaries run
 * past 100 chars, so every line wraps and the whole thing reads as a paragraph
 * wall. Here each line is one short lead sentence; the full summary is a
 * `voltro <command> --help` away.
 *
 * Kept as one table rather than a `group` field on all 45 specs so the ordering
 * is readable in one place. `commands.test.ts` asserts every visible command
 * appears in exactly one group, so this can't drift when a command is added.
 */
export declare const COMMAND_GROUPS: ReadonlyArray<readonly [string, ReadonlyArray<string>]>;

/**
 * Structured `--help` for a command that does not print its own.
 *
 * The dispatcher used to answer `--help` for 39 of the 53 commands with a
 * single summary line — no flags, no example — and `--help` is the second thing
 * a user types after a command surprises them. One renderer
 * (`renderCommandHelp`) turns this data into that page, so growing the coverage
 * is a data edit rather than 39 hand-written print blocks.
 *
 * **Every flag named here must be one the command actually parses.**
 * `commandHelp.test.ts` derives each command's implementation module from the
 * `import('./x')` in its own dispatch entry and fails if a documented flag is
 * not read there — the per-command form of the repo-wide `check-message-apis`
 * rule, which can only see the union of all sources and would therefore accept
 * `voltro test --create-only` because `migrate` happens to parse it.
 */
export declare interface CommandHelp {
    /** Usage line WITHOUT the leading `voltro <name>` — e.g. `[app] [--watch]`. */
    readonly usage?: string;
    /** `[flag, what it does]`. The flag includes its dashes and any `<value>`. */
    readonly flags?: ReadonlyArray<readonly [string, string]>;
    /** `[full command line, what it does]`. Each must start with `voltro <name>`. */
    readonly examples?: ReadonlyArray<readonly [string, string]>;
    /** Environment variables that change what this command does. */
    readonly env?: ReadonlyArray<readonly [string, string]>;
    /** Anything else worth a sentence — printed under the flags. */
    readonly notes?: ReadonlyArray<string>;
}

export declare const COMMANDS: ReadonlyArray<CommandSpec>;

export declare type CommandSpec = {
    readonly name: string;
    readonly summary: string;
    readonly status: 'wired' | 'stub';
    readonly run: (args: ReadonlyArray<string>) => Promise<number>;
    /** Internal command — dispatchable but omitted from `voltro help`. */
    readonly hidden?: boolean;
    /** This command prints its own richer `--help` — let `--help`/`-h` reach it
     *  instead of the dispatcher's uniform one-line fallback. */
    readonly handlesHelp?: boolean;
    /** Flags + examples the shared renderer turns into a real `--help` page.
     *  Mutually exclusive with `handlesHelp` (that command prints its own). */
    readonly help?: CommandHelp;
};

export declare const dispatch: (argv: ReadonlyArray<string>) => Promise<number>;

/**
 * Enumerate all valid templates under TEMPLATES_ROOT. Sorted by id
 * for stable output in `voltro list-templates`.
 */
export declare const listTemplates: () => Promise<ReadonlyArray<TemplateInfo>>;

export declare const printUsage: () => void;

/**
 * ONE renderer for every command's `--help`.
 *
 * Returned as lines rather than printed so the test can assert on the page
 * without capturing stdout — and so `voltro help <command>` and
 * `voltro <command> --help` cannot render differently.
 *
 * A command with no `help` block still gets a real page: name, summary, docs
 * link. That is the old fallback, kept as the FLOOR rather than as the answer —
 * what changed is that a command CAN now say more without printing it by hand.
 */
export declare const renderCommandHelp: (command: CommandSpec) => ReadonlyArray<string>;

/** Command names close enough to a typo to suggest. Also matches on prefix /
 *  substring, so `voltro work` suggests `workflows`. Exported for the test. */
export declare const suggestCommands: (input: string, limit?: number) => ReadonlyArray<string>;

export declare interface TemplateInfo extends TemplateManifest {
    /** Absolute path to the template source directory. */
    readonly path: string;
}

/** What a template scaffolds:
 *  - `api`  — a long-running backend (app.config `type: 'api'`).
 *  - `web`  — a frontend (app.config `type: 'web'`); gets a dev-server port.
 *  - `serverless` — a standalone `*.serverless.ts` function bundle deployed
 *    SEPARATELY via `voltro serverless` (no long-running server, no port).
 *  - `mobile` — an Expo (React Native) app. NOT run by `voltro dev` (Expo owns
 *    Metro / `expo start`); the scaffolder registers it in the workspace so the
 *    sibling api's typed rpc surface resolves, but allocates NO port and adds it
 *    to NO dev-orchestration set. `app.config.ts` is Expo's config, not
 *    Voltro's `type:` config. See `plans/open/mobile/01-template-and-expo-toolchain.md`. */
declare type TemplateKind = 'api' | 'web' | 'serverless' | 'mobile';

declare interface TemplateManifest {
    /** Stable id matching the directory name. */
    readonly id: string;
    /** What kind of app this scaffolds. Used by the cli for sanity
     *  checks (`add-app --template api-backend` against an existing
     *  apps/<project>/api/ rejects) + port allocation (web only). */
    readonly kind: TemplateKind;
    /** One-line summary printed by `voltro list-templates`. */
    readonly summary: string;
    /** Free-form tags surfaced by `voltro list-templates`; helpful for
     *  filtering ("landing", "docs", "cms", "dashboard", "blank"). */
    readonly tags?: ReadonlyArray<string>;
}

export { }


declare module '@voltro/protocol' {
    interface VoltroTableNames {
        'tasks': true;
        'task_sub_tasks': true;
        '_voltro_workflow_runs': true;
        '_voltro_workflow_run_steps': true;
        '_voltro_workflow_run_events': true;
        '_voltro_workflow_events': true;
        '_voltro_workflow_event_deliveries': true;
        '_voltro_approvals': true;
        '_voltro_connections': true;
        '_voltro_undo_log': true;
    }
}


declare module '@voltro/protocol' {
    interface VoltroTableNames {
        'invoices': true;
        'invoice_lines': true;
    }
}