@w6w/cli 0.1.0

package/dist/src/exit.js

@@ -0,0 +1,94 @@
+/**
+ * The exit-code mapping — the CLI's machine-readable half of every answer.
+ *
+ * A command's stdout is for a human or for `jq`; its exit code is for the shell
+ * that called it, and it is the only part of the answer a CI job reads. So the
+ * four codes are a contract, generated into `src/help.generated.ts` from the
+ * shared wrapper surface contract rather than restated here:
+ *
+ * | code | meaning |
+ * |---|---|
+ * | 0 | success — including help, and including a queued or running workflow |
+ * | 1 | usage error — a bad invocation, or a client that was never configured |
+ * | 2 | API error — the server was reached and answered with a failure |
+ * | 3 | run failure — `--wait` came back with a run whose status is `failed` |
+ *
+ * Two of those are traps, and {@linkcode exitCodeFor} exists so that every
+ * command falls into them the same way instead of each deciding for itself:
+ *
+ * - **A queued run is success.** Enqueuing a workflow answers before the run
+ *   finishes; the caller asked for it to start, and it started.
+ * - **A failed run is data, not an error.** The server reports a run-level
+ *   failure inside the response envelope, with an ordinary success status — so
+ *   the SDK returns it rather than raising, and only the CLI turns it into a
+ *   distinct code. Keeping it apart from an API error is the whole point: a
+ *   failed workflow and an unreachable server demand opposite responses, and a
+ *   script that cannot tell them apart will retry the wrong one.
+ *
+ * @module
+ */
+import { ApiError } from "@w6w/sdk";
+import { EXIT_API_ERROR, EXIT_RUN_FAILURE, EXIT_SUCCESS, EXIT_USAGE } from "./help.generated.js";
+export { EXIT_API_ERROR, EXIT_RUN_FAILURE, EXIT_SUCCESS, EXIT_USAGE };
+/** The run status that means the workflow itself failed. */
+const FAILED = "failed";
+/**
+ * Whether an outcome is a terminal run that failed.
+ *
+ * Structural on purpose: the run envelope arrives from the SDK as data, and the
+ * only field this mapping is entitled to read is the one the exit-code contract
+ * names.
+ */
+function isFailedRun(outcome) {
+    if (typeof outcome !== "object" || outcome === null)
+        return false;
+    return outcome.status === FAILED;
+}
+/**
+ * Whether a thrown value is an error raised by the server having answered.
+ *
+ * `instanceof` is the primary test. The name check behind it is not ceremony:
+ * an installed CLI resolves `@w6w/sdk` through the package manager, and a host
+ * that ends up with two copies of the SDK on disk produces an `ApiError` that
+ * fails `instanceof` against *this* copy's class. Falling back to the name keeps
+ * a genuine server failure out of the usage bucket in that case.
+ */
+function isApiError(outcome) {
+    return outcome instanceof ApiError ||
+        (outcome instanceof Error && outcome.name === "ApiError");
+}
+/**
+ * Map a command's outcome — its return value, or the error it threw — to an
+ * exit code.
+ *
+ * This is the only place any command decides what to exit with; there are no
+ * other codes anywhere in the CLI.
+ *
+ * ```ts
+ * try {
+ *   return exitCodeFor(await client.workflows.run(id, { wait: true }));
+ * } catch (err) {
+ *   return exitCodeFor(err);
+ * }
+ * ```
+ *
+ * @param outcome - A returned payload, or a caught error.
+ * @returns One of the four codes above.
+ */
+export function exitCodeFor(outcome) {
+    // The server answered, and what it answered was a failure.
+    if (isApiError(outcome))
+        return EXIT_API_ERROR;
+    // Anything else that was thrown never reached the server: a configuration
+    // error (no base URL, no token, a token that cannot be sent) or a local bug.
+    // The split matters — an API error means the request was made and refused,
+    // and a caller that retries on it would be retrying nothing here.
+    if (outcome instanceof Error)
+        return EXIT_USAGE;
+    // Returned data. A run that came back failed is the one payload that is not
+    // success; every other payload is.
+    if (isFailedRun(outcome))
+        return EXIT_RUN_FAILURE;
+    return EXIT_SUCCESS;
+}
+//# sourceMappingURL=exit.js.map

package/dist/src/exit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit.js","sourceRoot":"","sources":["../../src/exit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjG,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC;AAEtE,4DAA4D;AAC5D,MAAM,MAAM,GAAG,QAAQ,CAAC;AAExB;;;;;;GAMG;AACH,SAAS,WAAW,CAAC,OAAgB;IACnC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAClE,OAAQ,OAAgC,CAAC,MAAM,KAAK,MAAM,CAAC;AAC7D,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,UAAU,CAAC,OAAgB;IAClC,OAAO,OAAO,YAAY,QAAQ;QAChC,CAAC,OAAO,YAAY,KAAK,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,2DAA2D;IAC3D,IAAI,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,cAAc,CAAC;IAC/C,0EAA0E;IAC1E,6EAA6E;IAC7E,2EAA2E;IAC3E,kEAAkE;IAClE,IAAI,OAAO,YAAY,KAAK;QAAE,OAAO,UAAU,CAAC;IAChD,4EAA4E;IAC5E,mCAAmC;IACnC,IAAI,WAAW,CAAC,OAAO,CAAC;QAAE,OAAO,gBAAgB,CAAC;IAClD,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/dist/src/help.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The help renderer.
+ *
+ * `--help` is the CLI's documentation — not a pointer to documentation, the thing
+ * itself. So it resolves at all three levels (root, group, command), it never
+ * authenticates, it never reads configuration, it never makes a network call, and
+ * nothing in this file does any I/O at all: every function here takes a tree and
+ * returns a string. The caller decides whether that string goes to stdout with
+ * exit 0 (help was asked for) or to stderr with exit 1 (the invocation was
+ * unknown or incomplete).
+ *
+ * The tree itself is generated from the shared wrapper surface contract — see
+ * `scripts/gen-help.ts`. This file only lays it out.
+ *
+ * @module
+ */
+import type { HelpCommand, HelpGroup, HelpTree } from "./help.generated.ts";
+/** Where a command path landed in the tree. */
+export type Resolution = {
+    kind: "root";
+} | {
+    kind: "group";
+    group: HelpGroup;
+} | {
+    kind: "command";
+    command: HelpCommand;
+    group: HelpGroup | null;
+} | {
+    kind: "unknown";
+    token: string;
+    group: HelpGroup | null;
+};
+/**
+ * Resolves a command path against the tree.
+ *
+ * Handles the `w6w info` style aliases declared by the contract, so an alias
+ * prints the help of the command it stands for rather than a second copy.
+ */
+export declare function resolve(path: string[], tree?: HelpTree): Resolution;
+/** Root help: what w6w is, its command groups, and the global flags. */
+export declare function renderRootHelp(tree?: HelpTree): string;
+/** Group help: the commands in that group, and nothing else. */
+export declare function renderGroupHelp(group: HelpGroup, tree?: HelpTree): string;
+/** Command help: summary, usage, arguments, flags, and a runnable example. */
+export declare function renderCommandHelp(command: HelpCommand, tree?: HelpTree): string;
+/** Renders whichever level a resolution landed on. */
+export declare function renderHelp(resolution: Resolution, tree?: HelpTree): string;
+//# sourceMappingURL=help.d.ts.map

package/dist/src/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/help.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAa,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEvF,+CAA+C;AAC/C,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAA;CAAE,GAClE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAA;CAAE,CAAC;AAiChE;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,QAAoB,GAAG,UAAU,CAuB9E;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,IAAI,GAAE,QAAoB,GAAG,MAAM,CAejE;AAED,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,GAAE,QAAoB,GAAG,MAAM,CAWpF;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,GAAE,QAAoB,GAAG,MAAM,CAsB1F;AAED,sDAAsD;AACtD,wBAAgB,UAAU,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,GAAE,QAAoB,GAAG,MAAM,CAWrF"}

package/dist/src/help.generated.d.ts

@@ -0,0 +1,88 @@
+/** One argument or flag of a command, ready to render. */
+export interface HelpParam {
+    /** The contract's parameter name. */
+    name: string;
+    /** `argument` renders under ARGUMENTS, `flag` under OPTIONS. */
+    kind: "argument" | "flag";
+    /** What the help line shows, e.g. `<id>` or `--format <f>`. */
+    display: string;
+    description: string;
+    required: boolean;
+}
+/** One of the CLI's global flags. */
+export interface HelpGlobalFlag {
+    name: string;
+    alias: string | null;
+    type: string;
+    env: string | null;
+    /** What the help line shows, e.g. `-v, --version`. */
+    display: string;
+    description: string;
+}
+/** One runnable command — a leaf of the tree. */
+export interface HelpCommand {
+    /** The contract operation this command implements, e.g. `documents.create`. */
+    operation: string;
+    /** The command path below the binary, e.g. `["documents", "create"]`. */
+    path: string[];
+    name: string;
+    /** Alternative paths that resolve to this same command. */
+    aliases: string[][];
+    /** The contract's summary, verbatim. */
+    summary: string;
+    /** The summary as it appears in a one-line COMMANDS listing. */
+    short: string;
+    /** The summary as it appears after the em dash in the command's own help. */
+    headline: string;
+    usage: string;
+    /** The contract's `naming.cli` spelling, verbatim. */
+    naming: string;
+    /** The contract's `status` — server readiness, not wrapper completeness. */
+    status: string;
+    params: HelpParam[];
+    examples: string[];
+    notes: string[];
+}
+/** A group of commands, e.g. `w6w documents`. Groups are never runnable. */
+export interface HelpGroup {
+    name: string;
+    summary: string;
+    headline: string;
+    usage: string;
+    commands: HelpCommand[];
+    /** Flags every command in the group accepts. */
+    options: HelpParam[];
+    examples: string[];
+}
+/** The whole command tree. */
+export interface HelpTree {
+    binary: string;
+    contractVersion: string;
+    tagline: string;
+    usage: string;
+    docsUrl: string;
+    /** Commands that sit at the root because they have no siblings. */
+    commands: HelpCommand[];
+    groups: HelpGroup[];
+    globalFlags: HelpGlobalFlag[];
+    examples: string[];
+}
+/** One entry of the exit-code contract. */
+export interface HelpExitCode {
+    code: number;
+    name: string;
+    meaning: string;
+}
+/** The command tree, generated from the shared wrapper surface contract. */
+export declare const HELP_TREE: HelpTree;
+/** Every command path the parser may match, aliases included. */
+export declare const COMMAND_PATHS: string[][];
+/** The exit-code contract, verbatim from the shared contract's `cli.exitCodes`. */
+export declare const EXIT_CODES: HelpExitCode[];
+export declare const EXIT_SUCCESS: number;
+export declare const EXIT_USAGE: number;
+export declare const EXIT_API_ERROR: number;
+export declare const EXIT_RUN_FAILURE: number;
+/** The global flags, lifted out of the tree for the argument parser. */
+export declare const GLOBAL_FLAGS: HelpGlobalFlag[];
+//# sourceMappingURL=help.generated.d.ts.map

package/dist/src/help.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.generated.d.ts","sourceRoot":"","sources":["../../src/help.generated.ts"],"names":[],"mappings":"AAiBA,0DAA0D;AAC1D,MAAM,WAAW,SAAS;IACxB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,qCAAqC;AACrC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC;IACpB,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,gDAAgD;IAChD,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,8BAA8B;AAC9B,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,4EAA4E;AAC5E,eAAO,MAAM,SAAS,EAAE,QAy2BvB,CAAC;AAEF,iEAAiE;AACjE,eAAO,MAAM,aAAa,EAAE,MAAM,EAAE,EAsEnC,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,UAAU,EAAE,YAAY,EAqBpC,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,MAAU,CAAC;AACtC,eAAO,MAAM,UAAU,EAAE,MAAU,CAAC;AACpC,eAAO,MAAM,cAAc,EAAE,MAAU,CAAC;AACxC,eAAO,MAAM,gBAAgB,EAAE,MAAU,CAAC;AAE1C,wEAAwE;AACxE,eAAO,MAAM,YAAY,EAAE,cAAc,EAA0B,CAAC"}