@rebasepro/cli 0.13.1-canary.g06dbe5b → 0.13.1-canary.g1bf9303

package/dist/commands/cloud/context.d.ts

@@ -193,6 +193,22 @@ export declare function printJson(value: unknown): void;
  * call is what guarantees a command can never print a table AND a JSON blob.
  */
 export declare function emit(human: () => void, json: unknown): void;
+/**
+ * Print a help page — the human one, or a machine-readable description of the
+ * same command in JSON mode.
+ *
+ * `--help` is the one place where "stdout is not a TTY" is a weak signal: a
+ * person runs `rebase cloud db --help | less` and wants the page. But the rule
+ * this family promises is that stdout carries one JSON value whenever it is not
+ * a terminal, and a help page is the easiest possible thing to describe
+ * structurally — so rather than carve out an exception, help answers the same
+ * question in the reader's own language. For an agent, `--help` piped is then a
+ * discovery call rather than 60 lines of ANSI to scrape.
+ *
+ * `env` shipped this shape first, alone; this generalises it so every group
+ * answers the same way.
+ */
+export declare function emitHelp(command: string, actions: string[], human: () => void, extra?: Record<string, unknown>): void;
 /**
  * Print a warning (+ optional hint) — in every output mode, always to stderr.
  *
@@ -213,7 +229,22 @@ export declare function emit(human: () => void, json: unknown): void;
  * is for whoever reads the transcript afterwards.
  */
 export declare function warn(message: string, hint?: string): void;
-/** Print an error (+ optional hint) and exit non-zero. Never returns. */
+/**
+ * Print an error (+ optional hint) and exit non-zero. Never returns.
+ *
+ * `code` is the field a caller branches on, and it defaults to `"error"` rather
+ * than `null`. An envelope whose only machine-readable field is null is not
+ * machine-readable — `{"error":{"message":"No project specified…","code":null}}`
+ * forced the very substring-matching on `message` that the envelope exists to
+ * make unnecessary, and `message` is the field most likely to be reworded.
+ *
+ * `"error"` is deliberately a poor code: it says "this refusal has not been
+ * classified yet" without ever being absent. Anything a caller might plausibly
+ * want to distinguish — `usage`, `not_found`, `unauthenticated` — passes a real
+ * one. Codes are part of the CLI's contract once shipped; see
+ * `cloud-reporting.test.ts`, which pins the ones commands are documented to
+ * return.
+ */
 export declare function fail(message: string, hint?: string, code?: string): never;
 /**
  * Confirm a destructive/irreversible action, respecting non-interactive use.
@@ -227,6 +258,21 @@ export declare function confirmDestructive(opts: {
     yes: boolean;
     prompt: string;
 }): Promise<void>;
+/**
+ * Refuse, rather than prompt, when there is nobody to answer.
+ *
+ * `confirmDestructive` has always done this for yes/no confirmations. The
+ * *value* prompts had no such guard: `cloud login`, `cloud link`, `cloud use`,
+ * `cloud orgs create` and `cloud db create` all called `inquirer.prompt`
+ * unconditionally, so piping any of them — which is how an agent runs every
+ * command in this family — parked the process on a prompt reading from a stdin
+ * that was never going to produce a line. A hang is the worst failure mode
+ * available here: no output, no exit code, nothing to retry on.
+ *
+ * @param what   what the prompt would have asked for, e.g. "an email and password"
+ * @param flags  the flags that supply it non-interactively
+ */
+export declare function requireInteractive(what: string, flags: string): void;
 /**
  * Resolve one cloud command's flags and ARGUMENTS from the full `process.argv`.
  *
@@ -285,7 +331,40 @@ export declare function parseCloudArgs<S extends arg.Spec>(opts: {
     flags: arg.Result<S & typeof GLOBAL_CLOUD_FLAGS>;
     positionals: string[];
 };
+/**
+ * Announce an outcome — "Logged in as …", "Deleted project …".
+ *
+ * On **stderr**, in both modes. It reads like a result and is not one: the
+ * result is the JSON value (or the table) on stdout, and every JSON payload in
+ * this family already carries `success: true`. Leaving this on stdout meant a
+ * successful `rebase cloud link | jq` was handed a green tick followed by an
+ * object — one stream, two syntaxes, and only the second parseable.
+ *
+ * It stays visible in JSON mode, unlike `note`: an agent that got a `success`
+ * line on a command it expected to refuse has learned something.
+ */
 export declare function success(message: string): void;
+/**
+ * Narrate progress, or point at the next step — "Signing in to …", "Redeploy
+ * for the tenant to pick this up".
+ *
+ * stderr, and **suppressed entirely in JSON mode**. This is the one helper that
+ * a mode may silence, and the distinction from `warn` is worth keeping sharp:
+ *
+ *   - A warning is a *condition*. It is as true when piped as when watched, so
+ *     silencing it hides something the caller would want to know. `warn` never
+ *     silences.
+ *   - A note is *hand-holding*. "Next: run `rebase generate-sdk`" tells a person
+ *     what to type; the agent reading the JSON already has the same information
+ *     structurally, or does not need it. Printing it anyway is transcript noise.
+ *
+ * When in doubt it is a warning. The cost of a needless warning is a line; the
+ * cost of a swallowed one is the deploy that ejected a project off the managed
+ * runtime and said so only to a terminal nobody was looking at.
+ */
+export declare function note(message: string, indent?: string): void;
+/** A blank spacer line on the narration stream. No-op in JSON mode. */
+export declare function noteBlank(): void;
 /** Colorize a deployment / resource status token. */
 export declare function colorStatus(status: string | undefined): string;
 /**
@@ -300,7 +379,12 @@ export declare function keyValues(rows: Array<[string, string | null | undefined
  */
 export declare function reportError(e: unknown, context: string): never;
 /**
- * Open a URL in the user's default browser (best effort). Always prints the URL
- * first so it stays usable over SSH or when no browser is available.
+ * Open a URL in the user's default browser (best effort). Always announces the
+ * URL first so it stays usable over SSH or when no browser is available.
+ *
+ * The announcement is narration, not the result — it goes to stderr, and in
+ * JSON mode it is silent. Every caller `emit`s the same URL in its payload, so
+ * a machine reader gets it from the one place it is guaranteed to be parseable
+ * rather than from a line that happens to end in a URL.
  */
 export declare function openUrl(target: string, label?: string): void;