@greatwait/cli 0.1.0-alpha.3 → 0.1.0-alpha.4

package/dist/args.d.ts

@@ -22,7 +22,7 @@ export interface ParsedArguments {
  * both spellings — attached and separated — deserve the same answer. Neither
  * repeats the value back.
  */
-export declare const SECRET_ARGUMENT_ADVICE = "A credential given as an argument is visible to every process on this machine and is written to your shell history \u2014 treat the one you just typed as exposed and replace it. Run the command with a bare --api-key and paste the secret when asked, or pipe it in: printf %s \"$KEY\" | greatwait login --api-key";
+export declare function secretArgumentAdvice(programName: string): string;
 export declare function parseArguments(argv: readonly string[], 
 /**
  * The words that begin a command, so the rule below can tell a subcommand
@@ -35,7 +35,7 @@ export declare function parseArguments(argv: readonly string[],
  * than imported, because `commands.ts` reads this module and the cycle would
  * be the wrong way round.
  */
-commandWords?: ReadonlySet<string>): ParsedArguments;
+commandWords?: ReadonlySet<string>, programName?: string): ParsedArguments;
 /**
  * A duration written the way a person writes one: `30s`, `5m`, `2h`.
  *

package/dist/args.js

@@ -1,16 +1,18 @@
+import { CANONICAL_PROGRAM_NAME, COMMAND_CATALOG } from "./catalog.js";
 import { CliError } from "./runtime.js";
-/** Options that take a value. Anything else is a boolean flag. */
-const VALUED_OPTIONS = new Set([
-    "--api-url",
-    "--at",
-    "--data",
-    "--endpoint",
-    "--idempotency-key",
-    "--in",
-    "--scope",
-    "--timeout",
-    "--url",
-]);
+/**
+ * Options that take a value. Anything else is a boolean flag.
+ *
+ * **Derived from the catalog rather than listed here.** A second list was the
+ * first design and it is a drift a test does not notice: an option documented
+ * as `--limit <count>` that this set does not know is parsed as a flag, so the
+ * count becomes a positional argument and the command refuses it as unexpected
+ * — while the reference page says it is supported. One declaration, read by
+ * the parser and by the page, cannot disagree with itself.
+ */
+const VALUED_OPTIONS = new Set(COMMAND_CATALOG.flatMap((command) => command.options
+    .filter((option) => option.value !== undefined)
+    .map((option) => option.flag)));
 /**
  * Options that must never take a value, whatever they look like.
  *
@@ -26,7 +28,9 @@ const SECRET_BEARING_FLAGS = new Set(["--api-key"]);
  * both spellings — attached and separated — deserve the same answer. Neither
  * repeats the value back.
  */
-export const SECRET_ARGUMENT_ADVICE = 'A credential given as an argument is visible to every process on this machine and is written to your shell history — treat the one you just typed as exposed and replace it. Run the command with a bare --api-key and paste the secret when asked, or pipe it in: printf %s "$KEY" | greatwait login --api-key';
+export function secretArgumentAdvice(programName) {
+    return `A credential given as an argument is visible to every process on this machine and is written to your shell history — treat the one you just typed as exposed and replace it. Run the command with a bare --api-key and paste the secret when asked, or pipe it in: printf %s "$KEY" | ${programName} login --api-key`;
+}
 export function parseArguments(argv, 
 /**
  * The words that begin a command, so the rule below can tell a subcommand
@@ -39,7 +43,8 @@ export function parseArguments(argv,
  * than imported, because `commands.ts` reads this module and the cycle would
  * be the wrong way round.
  */
-commandWords = new Set()) {
+commandWords = new Set(), programName = CANONICAL_PROGRAM_NAME) {
+    const secretAdvice = secretArgumentAdvice(programName);
     const command = [];
     const options = {};
     const booleans = new Set();
@@ -55,7 +60,7 @@ commandWords = new Set()) {
         const name = equals === -1 ? token : token.slice(0, equals);
         if (SECRET_BEARING_FLAGS.has(name)) {
             if (equals !== -1) {
-                throw new CliError(`${name} does not take a value on the command line`, "usage", SECRET_ARGUMENT_ADVICE);
+                throw new CliError(`${name} does not take a value on the command line`, "usage", secretAdvice);
             }
             // **The next token is refused here, rather than left to a command.**
             // Leaving it to become a positional argument was the first design, and a
@@ -72,13 +77,25 @@ commandWords = new Set()) {
             if (following !== undefined &&
                 !following.startsWith("--") &&
                 !commandWords.has(following)) {
-                throw new CliError(`${name} does not take a value on the command line`, "usage", SECRET_ARGUMENT_ADVICE);
+                throw new CliError(`${name} does not take a value on the command line`, "usage", secretAdvice);
             }
             booleans.add(name);
             index += 1;
             continue;
         }
         if (VALUED_OPTIONS.has(name)) {
+            // **A second occurrence is refused rather than overwriting the first.**
+            // Two reviewers found the same defect through it: `--scope` documented
+            // itself as repeatable, the record this parses into is one value per
+            // name, and `--scope schedules:read --scope schedules:write` therefore
+            // asked for the second and silently dropped the first — surfacing much
+            // later as a `scope_missing` with nothing to connect it back. The same
+            // shape is worse for `--data` and `--limit`, where the dropped value is
+            // the one somebody meant. Refusing costs a retype; overwriting costs a
+            // debugging session, and always the wrong one.
+            if (Object.hasOwn(options, name)) {
+                throw new CliError(`${name} was given twice`, "usage", "Give it once. An option that takes a list takes the values in one argument, separated by spaces.");
+            }
             if (equals !== -1) {
                 options[name] = token.slice(equals + 1);
                 index += 1;

package/dist/catalog.d.ts

@@ -0,0 +1,196 @@
+import { type OperationDefinition } from "@greatwait/contracts";
+import { EXIT_CLASSES, EXIT_CLASS_MEANINGS, type ExitClass } from "./exit.js";
+/**
+ * What the command line covers, declared once and checked against the registry.
+ *
+ * **This module is metadata and rules, and it imports no client.** The
+ * reference page is generated from it by a script that must not drag the
+ * generated API client into the contract generator's own dependency graph —
+ * the generator writes that client — so the declarations live apart from the
+ * implementations that use them. `commands.ts` binds each declaration to a
+ * function; `coverageProblems` is what refuses a declaration that no longer
+ * matches the registry.
+ *
+ * The story's criterion 2 asks that an added, removed, renamed, scope-changed,
+ * approval-changed, or unavailable operation cannot leave the CLI and its
+ * reference silently stale. That is this file: every operation is either
+ * covered by a command or omitted on a stated ground, the grounds that can be
+ * derived from the registry are checked against it rather than believed, and
+ * the scopes `login` asks for are the union of what the covered operations
+ * need rather than a list somebody maintains beside them.
+ */
+/** A positional argument, in the order the command reads them. */
+export interface CommandPositional {
+    /** As it appears in the reference: `<schedule>`. */
+    readonly name: string;
+    readonly summary: string;
+    readonly optional?: boolean;
+}
+/** An option. `value` absent means it is a flag and takes none. */
+export interface CommandOption {
+    readonly flag: string;
+    readonly summary: string;
+    readonly value?: string;
+}
+export interface CommandDeclaration {
+    /** The words that select it, one or two. The dispatcher tries two first. */
+    readonly words: string;
+    /** The heading it appears under in help and in the reference. */
+    readonly group: string;
+    readonly summary: string;
+    readonly positionals: readonly CommandPositional[];
+    readonly options: readonly CommandOption[];
+    /** Registry operations this command reaches. Empty for a purely local one. */
+    readonly operations: readonly string[];
+    /**
+     * Previews its exact scope and asks before acting.
+     *
+     * Required wherever `confirmationGround` says so and permitted anywhere else:
+     * a command may be more careful than the registry demands, and one of them
+     * is — rotating an endpoint signing key mints a secret shown once, which the
+     * registry describes but has no hint for.
+     */
+    readonly confirms?: boolean;
+}
+/**
+ * Why an operation has no command.
+ *
+ * Two of the three are properties of the registry entry, so the rule below
+ * checks them rather than taking the claim at face value — a ground that
+ * cannot be wrong is a ground nobody has to re-read when the entry changes.
+ * The third carries prose because no property of the entry states it.
+ */
+export type OmissionGround = 
+/** No principal this command line can hold may call it. */
+"principal-unreachable"
+/** Not served by the API at all. */
+ | "not-on-the-api"
+/** A product decision, stated in `because`. */
+ | "declared";
+export interface OperationOmission {
+    readonly operation: string;
+    readonly ground: OmissionGround;
+    readonly because: string;
+}
+/**
+ * The name every written instruction uses.
+ *
+ * The package installs two executables — `greatwait` and `gw` — and each states
+ * its own name, so what a person is told to type next is what they just typed.
+ * The *published* reference, the quickstarts and the first-value journey use
+ * this one, because a written instruction has to be followable by somebody who
+ * installed either.
+ */
+export declare const CANONICAL_PROGRAM_NAME = "greatwait";
+/** The principals a command line can present. Never a browser session. */
+export declare const CLI_PRINCIPALS: readonly ["api-credential", "oauth"];
+/** Whether any principal this command line can hold may call it. */
+export declare function reachableByCli(operation: OperationDefinition): boolean;
+/** Whether the API serves it at all, as opposed to the contract mock alone. */
+export declare function servedByApi(operation: OperationDefinition): boolean;
+/**
+ * Why a command covering this operation must confirm before acting, if it must.
+ *
+ * **Derived from the registry's own hints rather than from a list here**, so an
+ * operation that becomes destructive tomorrow makes a command that does not ask
+ * fail this gate rather than quietly keep shipping.
+ *
+ * Two grounds, and the second is the one that took a correction. Every
+ * externally visible call is *not* a confirmation: `schedules create` reaches a
+ * receiver by design and is the first thing anybody runs, so demanding a
+ * keystroke there would put a prompt in the middle of the published first-value
+ * journey. What separates it from `occurrences redeliver` — which does deserve
+ * one — is that redelivery acts on something that already exists and sends it
+ * again. So the ground is an outward-facing change to an *addressed* object,
+ * which is exactly an operation with a path parameter.
+ */
+export declare function confirmationGround(operation: OperationDefinition): "destructive" | "outward-facing-change" | undefined;
+/**
+ * The request headers the registry declares for an operation.
+ *
+ * Read off the schema's own shape rather than listed here, because the point of
+ * the rules below is that a header appearing or disappearing changes what the
+ * command line must offer. `endpoints.disable` is the case that makes it worth
+ * checking: every other endpoint write accepts `If-Match` and that one does
+ * not, so a command offering the flag there would document a guard the service
+ * ignores — which reads to somebody operating carefully as protection they do
+ * not have.
+ */
+export declare function declaredRequestHeaders(operation: OperationDefinition): readonly string[];
+/**
+ * Every command, in the order the reference and `--help` present them.
+ *
+ * Ordered by what somebody does rather than alphabetically: sign in, look
+ * around, set up a destination, schedule something, watch it, then recover from
+ * it. The groups are the headings.
+ */
+export declare const COMMAND_CATALOG: readonly CommandDeclaration[];
+/**
+ * Every operation with no command, and why.
+ *
+ * The first six are the same fact stated six times: they need a browser
+ * session, and a command line holds an API credential or an OAuth grant. That
+ * is a property of the registry entry, so the rule checks it rather than
+ * believing this list — and it is also why the story says credential and grant
+ * operations appear "only where the current principal rules can support them
+ * honestly". Creating a credential from a credential is the escalation the
+ * control plane refuses on purpose.
+ */
+export declare const OPERATION_OMISSIONS: readonly OperationOmission[];
+/**
+ * The one-line spelling of a command, used by `--help` and by the reference.
+ *
+ * **Rendered from the declaration in both places rather than written twice.**
+ * The story asks that the reference be generated or exhaustively checked
+ * against the executable; sharing the renderer is the version of that with
+ * nothing to check, because a page and a help screen produced by the same
+ * function cannot disagree about what a command takes.
+ */
+export declare function usageLine(command: CommandDeclaration, programName?: string): string;
+/** The help for one command: what it does, what it takes, what each means. */
+export declare function commandHelp(command: CommandDeclaration, programName?: string): string;
+/** Every command, grouped, for the overview `--help` prints. */
+export declare function overview(commands?: readonly CommandDeclaration[]): string;
+export interface CoverageInputs {
+    readonly commands: readonly CommandDeclaration[];
+    readonly omissions: readonly OperationOmission[];
+    readonly operations: readonly OperationDefinition[];
+}
+/**
+ * The scopes `login` asks a person to grant.
+ *
+ * **Derived from what the commands actually call.** A list maintained beside
+ * the catalog is a list that goes stale in the direction nobody notices: a
+ * command added for an operation needing a scope nobody requested fails at
+ * runtime with `scope_missing`, against a grant the person cannot widen without
+ * signing in again. Deriving it also means a widening shows up in the generated
+ * reference's diff, which is where a reviewer will see it.
+ */
+export declare function requestedScopes(inputs: CoverageInputs): readonly string[];
+/**
+ * Everything wrong with the declarations, as sentences.
+ *
+ * A pure function of its inputs so the cases below can hand it a catalog that
+ * violates one rule at a time. Empty means the CLI, its reference and the
+ * registry agree.
+ */
+export declare function coverageProblems(inputs: CoverageInputs): string[];
+/** The declarations as they stand, against the real registry. */
+export declare function catalogInputs(): CoverageInputs;
+/**
+ * The scopes `login` asks for, from what the commands call.
+ *
+ * Asking for everything the server offers would be asking a person to grant a
+ * command line permissions it has no code to use; asking for less than the
+ * commands need is a `scope_missing` on a grant they cannot widen without
+ * signing in again. Neither is a list anybody maintains: this is that union.
+ */
+export declare const REQUESTED_SCOPES: readonly string[];
+/**
+ * Re-exported so the reference generator has one import.
+ *
+ * The page publishes the exit numbers and what they mean, and both come from
+ * the module the runtime reads. A generator reaching into `./exit` separately
+ * would work; this keeps the catalog the single thing a projection depends on.
+ */
+export { EXIT_CLASSES, EXIT_CLASS_MEANINGS, type ExitClass };