@devdogsuga/devtools 0.1.0

package/dist/commands.d.ts

@@ -0,0 +1,255 @@
+/**
+ * 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.
+     *
+     * The four moderation commands carry it: each one opens a client against
+     * Supabase on this machine and has no remote path at all, so with it down
+     * they are a spinner followed by a connection error. The hint turns that
+     * into a sentence the reader sees before choosing.
+     */
+    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[][];