@devdogsuga/devtools 0.1.26 → 0.1.27

package/dist/commands.d.ts

@@ -1,261 +0,0 @@
-/**
- * One choice in a select prompt.
- *
- * `value` is the value the wizard passes for the option's own flag — e.g.
- * `local`/`remote` for `--target`. The menu always emits `[flag, value]`.
- */
-export interface OptionChoice {
-    value: string;
-    label?: string;
-    hint?: string;
-}
-/**
- * A prompt the wizard raises to fill an option the command line would carry.
- *
- * `confirm` has no polarity switch on purpose: **yes adds the flag**, always.
- * So every message here is phrased so yes is the flag's own meaning ("Skip the
- * duplicate scan?" rather than "Scan for duplicates?"). That leaves the wizard
- * without a second place to get an inversion wrong.
- */
-export type OptionPrompt = {
-    kind: "confirm";
-    message: string;
-    initial: boolean;
-} | {
-    kind: "select";
-    message: string;
-    choices: readonly OptionChoice[];
-} | {
-    kind: "text";
-    message: string;
-    placeholder?: string;
-    optional?: boolean;
-};
-export interface CommandOption {
-    /** `--target`. */
-    flag: string;
-    /** `<t>` for a flag that takes a value; absent for a boolean. */
-    value?: string;
-    /** One line. Printed by `devtools <command> --help`. */
-    summary: string;
-    /**
-     * How the wizard asks for it.
-     *
-     * Absent means the wizard does not ask HERE, a decision rather than an
-     * omission. Three kinds of option are deliberately promptless:
-     *
-     *   * ones the command asks for ITSELF, from something live. `--app` picks
-     *     from the apps in the database, `--user` from the accounts on it,
-     *     `--target` from `pick.ts`'s danger-ordered list, `--apps` from the env
-     *     registry. A wizard text box would be a worse version of a menu that
-     *     already exists, and `--target`'s would put production one keystroke
-     *     closer than `pick.ts` deliberately puts it;
-     *   * ones that exist to SUPPRESS a prompt (`--yes`), meaningless in a
-     *     wizard, which is the prompt;
-     *   * ones that carry a credential (`--access-token`). The interactive path
-     *     resolves it better, and typing it makes it visible to `ps` and shell
-     *     history.
-     *
-     * So every option is reachable from the menu; what varies is which screen
-     * asks. `commands.test.ts` pins the promptless set so a fourth case has to be
-     * argued for rather than accumulate.
-     */
-    prompt?: OptionPrompt;
-}
-/**
- * Something about the machine that a command cares about.
- *
- * A string rather than a predicate, so this file stays what its header says it
- * is: data. `environment.ts` is the only module that knows what these mean,
- * `menu.ts` acts on them, and the docs build can render "shown when the local
- * stack is running" without being able to run anything.
- */
-export type Condition = "docker" | "instance-running" | "instance-stopped";
-/**
- * Which layer of the database group a command acts on.
- *
- * Groups like Supabase and (future) `db` span multiple layers: the local
- * Docker stack, the Postgres database inside it, and hosted endpoints. Scopes
- * let `--help` head each run and the wizard put the layer on every line,
- * so a contributor chooses deliberately rather than by accident.
- *
- *   `machine`  — acts on this machine's containers (`link`, `stop`, `restart`)
- *   `repo`     — reads or writes repository files only (no live connection)
- *   `endpoint` — connects to the SESSION's database (picked once at launch,
- *                `--tier development:local|development:remote|staging|production`)
- *   `infra`    — infrastructure-level; touches roles, credentials, or config
- */
-export type Scope = "machine" | "repo" | "endpoint" | "infra";
-/**
- * How each scope reads, in the two places that draw it.
- *
- * `menu` sits inline in a hint, so it is one word. `help` heads a block of
- * commands, so it can be a phrase. Both live here rather than in the renderers
- * because they are labels, the same kind of data as a group title.
- */
-export declare const SCOPES: Record<Scope, {
-    menu: string;
-    help: string;
-}>;
-export interface CommandNode {
-    name: string;
-    /** One line. See the header. */
-    summary: string;
-    /** Sits beside the name in the wizard; shorter than the summary. */
-    hint?: string;
-    options?: readonly CommandOption[];
-    subcommands?: readonly CommandNode[];
-    /**
-     * Offer this in the wizard only while the condition holds.
-     *
-     * For commands that are *meaningless* otherwise, not merely inconvenient:
-     * stopping a stack that is already stopped is the whole of the category. A
-     * command that would run and fail with a good message gets `needs` instead.
-     * See the two-line rule on `isOffered` in `environment.ts` for why hiding is
-     * the rarer of the two.
-     *
-     * Wizard-only. `--help`, the dispatcher and the generated reference all
-     * ignore this, so nothing here removes a command from the CLI.
-     */
-    when?: Condition;
-    /**
-     * Offer this always, but say on the line why it will not work right now.
-     *
-     * Nothing in the tree carries it at the moment — the four moderation
-     * commands were the only ones that ever did, back when each opened a
-     * client against Supabase on this machine with no remote path at all, so
-     * with it down they were a spinner followed by a connection error. They
-     * moved onto the session system alongside `db migrate`/`db reset`, neither
-     * of which has ever gated on a local probe (a hosted session has no local
-     * stack to probe), so nothing here needs the hint any more. Left declared
-     * rather than deleted: a future local-only command is exactly the shape of
-     * thing that would want it back, and `blockedBecause`
-     * (`environment.test.ts`) still exercises the mechanism directly.
-     */
-    needs?: Condition;
-    /**
-     * Which layer this acts on, for a group that spans several. See `Scope`.
-     *
-     * Groups like Supabase span the stack on this machine and the database
-     * inside it.
-     * `--help` heads a block with it; the wizard puts it on the line.
-     */
-    scope?: Scope;
-    /**
-     * Where this command may be reached.
-     *
-     * Most commands are interactive and therefore appear in both the menu and
-     * `--help`. `cli-only` commands still appear in help and completions, but do
-     * not get a GUI entry: their output is meant to be consumed by a shell.
-     */
-    surface?: "interactive" | "cli-only";
-    /**
-     * This command reads and writes no DevDogsUGA env file, database, or
-     * `DEPLOY_ENV` — `launch.ts` may enter plain `development` for it with no
-     * tier prompt and no multi-tier refusal, exactly like the hardcoded
-     * `setup`/`completions` bypass it already carries (see that file's
-     * `launch()` for why those two cannot go through ordinary tier
-     * resolution).
-     *
-     * Both `github rulesets` and `github settings` are the first commands to
-     * use this flag rather than joining that hardcoded name check: everything
-     * either one touches is a `gh api` call against GitHub itself, resolved
-     * from `--org`/`--repo` flags, not from the session's deploy tier — so
-     * `--tier` was never a real requirement, only an artifact of every command
-     * going through the same tier-resolution gate before dispatch. Marked on
-     * the leaf command (`rulesets`, `settings`), not the `github` group node,
-     * because `launch.ts` looks up the exact dispatched path.
-     */
-    envFree?: boolean;
-}
-/** Top-level sections. Only `--help` and the wizard's first screen use these. */
-export interface CommandGroup {
-    title: string;
-    commands: readonly CommandNode[];
-}
-/** Standard success. */
-export declare const EXIT_OK = 0;
-/** Command failed. */
-export declare const EXIT_FAIL = 1;
-/** `--check` found drift. Distinct from failure so scripts can tell them apart. */
-export declare const EXIT_DRIFT = 2;
-/**
- * `docs index`'s delete acknowledgment — NOT a database selector.
- *
- * The db namespace's old `--target local|remote` flag is retired outright
- * (the SESSION names the database now — see `db/connection.ts`), but `docs
- * index` keeps this spelling for a different job: its prune deletes rows,
- * and running that against a non-local `DB_URL` requires saying so out
- * loud. The database itself still comes from the session's env.
- */
-export declare const DOCS_TARGET: CommandOption;
-/**
- * The deployment-tier selector, for the commands that resolve a tier of
- * their OWN (cron/workflows run against a chosen tier's env). The session's
- * global `--tier` — `development:local|development:remote|staging|production`,
- * stripped by the launcher before dispatch — is a superset of this
- * vocabulary; this per-command flag still reads plain tiers.
- */
-export declare const TIER: CommandOption;
-/** Print what would change; write nothing; exit 0. On every command that writes. */
-export declare const DRY_RUN: CommandOption;
-/** Verify correctness; write nothing; exit 2 on drift. */
-export declare const CHECK: CommandOption;
-/**
- * Machine-readable output to stdout.
- *
- * Promptless by design: the wizard is already interactive; a flag that switches
- * its output format has no meaning there. `commands.test.ts` pins the promptless
- * set with a "scripting-only" category for exactly this kind of flag.
- */
-export declare const JSON_FLAG: CommandOption;
-/** Skip every interactive confirmation prompt. On every destructive command. */
-export declare const YES: CommandOption;
-export declare const GROUPS: readonly CommandGroup[];
-/**
- * The commands the `devtools-ci` bin exposes.
- *
- * Kept separate from `GROUPS` because CI commands are never reached from the
- * wizard and never rendered in `--help`. They live here so the docs build can
- * render a CI reference page from the same declaration, and so the tests that
- * guard the style guide can cover both trees without duplicating the pins.
- */
-export declare const CI_GROUPS: readonly CommandGroup[];
-/** Every top-level command, in group order. */
-export declare const TOP_LEVEL: readonly CommandNode[];
-/** Every top-level CI command, in group order. */
-export declare const CI_TOP_LEVEL: readonly CommandNode[];
-/**
- * Walks a path in the CI tree, returning `null` at the first miss.
- *
- * Identical to `findCommand` but over `CI_TOP_LEVEL` rather than `TOP_LEVEL`.
- */
-export declare function findCiCommand(path: readonly string[]): CommandNode | null;
-/** The subcommand names under a CI path. */
-export declare function subcommandCiNames(path: readonly string[]): string[];
-/**
- * Walks a path like `["env", "pull"]`, returning `null` at the first miss.
- *
- * Callers use `null` to mean "not a command", which is the same answer the
- * dispatcher gives, so an unknown name reads the same whichever notices first.
- */
-export declare function findCommand(path: readonly string[]): CommandNode | null;
-/** The group a top-level command sits in, for the wizard's first screen. */
-export declare function groupOf(name: string): CommandGroup | undefined;
-/**
- * The subcommand names under a path, in the order they are declared.
- *
- * This is what the dispatchers in `cli.ts` validate against. A subcommand the
- * tree does not declare is refused by the CLI, and an interactive one it does
- * declare is in the menu. There is one list, and this reads it.
- */
-export declare function subcommandNames(path: readonly string[]): string[];
-/** `pull, push, audit, init, example or reset`, for a refusal message. */
-export declare function subcommandList(path: readonly string[]): string;
-/**
- * Every command path in the tree, deepest names included.
- *
- * Used by the coverage test, and by anything that wants to enumerate the CLI
- * (the docs build's reference page is the intended second caller).
- */
-export declare function allPaths(): string[][];