@w6w/cli 0.1.0

package/dist/src/commands/shared.js

@@ -0,0 +1,152 @@
+/**
+ * The vocabulary every command handler shares: reading its own arguments,
+ * failing as a usage error, and rendering.
+ *
+ * It exists because the alternative is worse in both directions. Copying these
+ * accessors into each command group gives four spellings of "was this flag
+ * given?" — and that question is exactly the one D2 turns on, where a wrong
+ * answer silently rewrites a field the user never mentioned. Putting them in
+ * `./index.ts` instead would make the registry — the file every command group
+ * appends itself to — also the file every group edits, which is how a merge
+ * point becomes a merge conflict.
+ *
+ * Two rules hold everywhere below:
+ *
+ * 1. **A usage error is thrown, never printed.** `main()` reports it on stderr
+ *    once and maps it through `src/exit.ts` to exit `1`; a handler that wrote
+ *    its own message would be a second error path to keep in sync.
+ * 2. **Presence is `!== undefined`, never truthiness.** `--description ""` is a
+ *    flag the user supplied, and it means "clear the description" — a `if
+ *    (value)` test would drop it on the floor.
+ *
+ * @module
+ */
+import { HELP_TREE } from "../help.generated.js";
+/** `w6w documents get` — the command as the user typed it, for a message. */
+function spelling(context) {
+    return `${HELP_TREE.binary} ${context.command.path.join(" ")}`;
+}
+/**
+ * A bad invocation, phrased for the person who typed it.
+ *
+ * The usage line is the contract's own `naming.cli` spelling rather than a
+ * restatement of it, so the thing a user is told to type cannot drift from the
+ * thing the surface contract declares.
+ *
+ * It is a plain `Error` on purpose: `src/exit.ts` maps every non-`ApiError`
+ * throw to the usage code, because anything that is not an `ApiError` never
+ * reached the server. A bespoke class would add a name to the stack trace and
+ * change nothing about the exit code.
+ *
+ * @param context - The command being run.
+ * @param problem - What was wrong, as a sentence.
+ * @returns The error to throw.
+ */
+export function usageError(context, problem) {
+    return new Error(`${problem}\n\nUsage: ${context.command.naming}`);
+}
+/**
+ * One positional argument, required.
+ *
+ * An **empty** argument counts as missing. That is an argument-presence rule and
+ * not a value policy: the server accepts no empty key, name or id, so refusing
+ * `""` here makes nothing unreachable — unlike a key such as `".."`, which is
+ * legitimately creatable and is therefore never rejected client-side (see
+ * `documents get-by-key`).
+ *
+ * @param context - The command being run.
+ * @param index - Position of the argument, after the command path.
+ * @param what - What is expected, e.g. ``"a document id (see: `w6w documents list`)"``.
+ * @returns The argument.
+ * @throws {Error} A usage error when it is absent or empty.
+ */
+export function argument(context, index, what) {
+    const value = context.invocation.positionals[index];
+    if (value === undefined || value.length === 0) {
+        throw usageError(context, `\`${spelling(context)}\` needs ${what}.`);
+    }
+    return value;
+}
+/**
+ * Reject arguments the command does not take.
+ *
+ * Silence here is how a typo becomes a surprise: `w6w documents get doc_1 doc_2`
+ * would fetch the first id and ignore the second, and `w6w vars list --project`
+ * escaped past `--` would list everything as though the scope had been applied.
+ *
+ * @param context - The command being run.
+ * @param expected - How many positional arguments the command takes.
+ * @throws {Error} A usage error naming the first extra argument.
+ */
+export function noExtraArguments(context, expected) {
+    const extra = context.invocation.positionals.slice(expected);
+    if (extra.length === 0)
+        return;
+    throw usageError(context, `\`${spelling(context)}\` takes ${expected === 0 ? "no arguments" : `${expected} argument(s)`}` +
+        `, and got an extra one: \`${extra[0]}\`.`);
+}
+/**
+ * One flag's value, or `undefined` where the flag was not given.
+ *
+ * The distinction is the whole of D2: an absent flag must leave the server's
+ * field alone, and only a flag the user actually typed may change it. Callers
+ * therefore test `!== undefined` and never truthiness.
+ *
+ * @param context - The command being run.
+ * @param name - The flag's camelCased key, e.g. `"project"`, `"description"`.
+ * @returns The value as typed, or `undefined`.
+ */
+export function textFlag(context, name) {
+    const value = context.invocation.options[name];
+    return typeof value === "string" ? value : undefined;
+}
+/**
+ * One flag's value, required.
+ *
+ * @param context - The command being run.
+ * @param name - The flag's camelCased key.
+ * @param display - How the flag is spelled in help, e.g. `"--content <text>"`.
+ * @returns The value as typed.
+ * @throws {Error} A usage error when the flag is absent.
+ */
+export function requiredFlag(context, name, display) {
+    const value = textFlag(context, name);
+    if (value === undefined) {
+        throw usageError(context, `\`${spelling(context)}\` needs \`${display}\`.`);
+    }
+    return value;
+}
+/**
+ * Render rows as aligned columns under a dimmed header.
+ *
+ * The last column is never padded, so a value that runs long widens nothing and
+ * a copied line carries no trailing whitespace.
+ *
+ * @param header - Column titles.
+ * @param rows - The rows, each the same length as `header`.
+ * @param styles - The invocation's decorations; plain text when colour is off.
+ * @returns The table, newline-separated.
+ */
+export function table(header, rows, styles) {
+    const widths = header.map((title, column) => Math.max(title.length, ...rows.map((row) => row[column].length)));
+    const line = (cells) => cells
+        .map((cell, column) => (column === cells.length - 1 ? cell : cell.padEnd(widths[column])))
+        .join("  ");
+    return [styles.dim(line(header)), ...rows.map(line)].join("\n");
+}
+/**
+ * A one-line preview of an opaque value, for a table cell.
+ *
+ * JSON rather than the value's own text: a variable's value may be a string, a
+ * number, a boolean or a whole document, and `hello` versus `"hello"` is the
+ * difference between a `string` variable and a `json` one holding a string.
+ *
+ * @param value - The value, straight off the wire.
+ * @param width - Maximum characters before an ellipsis.
+ * @returns The preview.
+ */
+export function preview(value, width = 40) {
+    const text = JSON.stringify(value) ?? String(value);
+    return text.length <= width ? text : `${text.slice(0, width - 1)}…`;
+}
+//# sourceMappingURL=shared.js.map

package/dist/src/commands/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/commands/shared.ts"],"names":[],"mappings":"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"}

package/dist/src/commands/vars.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `w6w vars …` — typed variables at the command line.
+ *
+ * Six commands, **one SDK call each**, addressed the way the server addresses
+ * them: **create by `name`, read by id or by name, update and delete by id**
+ * (`docs/implementation.md` §7). Nothing here composes two requests or resolves
+ * a name by listing and scanning — `get-by-name` targets the real
+ * `GET /vars/by-name/{name}` route, which is `status: "planned"` and answers
+ * `404` until it lands (T4.4.1, fenced by BLK-1). That is the correct failure
+ * and it is not worked around.
+ *
+ * **There is no `--project` on any command in this group, and this module
+ * refuses one rather than ignoring it.** Variables are scoped by tenant and
+ * subject only: the `vars` table has no project column and no `vars` route reads
+ * the query parameter, while every `documents` route does. The asymmetry is
+ * real, so the CLI states it — accepting a flag the server ignores would teach a
+ * user a scoping model that does not exist, and they would find out when two
+ * projects turned out to share one variable.
+ *
+ * @module
+ */
+import type { CommandRegistry } from "../../mod.ts";
+/**
+ * Encode a `--value` string into the JSON value the server will type-check.
+ *
+ * A command line carries text and the API carries JSON, so something has to
+ * bridge the two. The rule is one sentence, and it is **encoding, never
+ * validation** — nothing here rejects a value, and the type policy stays where
+ * it belongs, in the server (`400 invalid_type` / `400 invalid_value`):
+ *
+ * > With `--type string` the text is the value, verbatim. Otherwise the text is
+ * > read as JSON if it parses as JSON, and is the string itself if it does not.
+ *
+ * So `--type string --value hello` stores `"hello"`, `--type number --value 42`
+ * stores `42`, `--type json --value '{"a":1}'` stores the object — and
+ * `--type number --value forty-two` sends `"forty-two"`, which comes back as the
+ * server's `400 invalid_value` rather than as a client-side complaint that would
+ * go stale the day the server's rule changes.
+ *
+ * On `w6w vars update` the type is usually not restated, and then the fallback
+ * arm is the whole rule — which is also what makes an **explicit null**
+ * expressible: `--value null` sends `{"value":null}`, distinct from omitting the
+ * flag and sending `{}` (D2).
+ *
+ * @param text - The `--value` flag, as typed.
+ * @param type - The `--type` flag, when the invocation carried one.
+ * @returns The value to put in the request body.
+ */
+export declare function encodeValue(text: string, type: string | undefined): unknown;
+/**
+ * The six `w6w vars` commands, keyed by the canonical command path.
+ *
+ * The keys are the generated help tree's `path` values joined by a space, which
+ * are `endpoints.json`'s `naming.cli` spellings — `tests/cmd_vars_test.ts`
+ * asserts the two sets are the same, so a command cannot be registered under a
+ * name the help does not document, or documented under a name nothing runs.
+ */
+export declare const VAR_COMMANDS: CommandRegistry;
+//# sourceMappingURL=vars.d.ts.map

package/dist/src/commands/vars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vars.d.ts","sourceRoot":"","sources":["../../../src/commands/vars.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAkC,eAAe,EAAE,MAAM,cAAc,CAAC;AAoDpF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAO3E;AAsHD;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,EAAE,eAO1B,CAAC"}

package/dist/src/commands/vars.js

@@ -0,0 +1,216 @@
+/**
+ * `w6w vars …` — typed variables at the command line.
+ *
+ * Six commands, **one SDK call each**, addressed the way the server addresses
+ * them: **create by `name`, read by id or by name, update and delete by id**
+ * (`docs/implementation.md` §7). Nothing here composes two requests or resolves
+ * a name by listing and scanning — `get-by-name` targets the real
+ * `GET /vars/by-name/{name}` route, which is `status: "planned"` and answers
+ * `404` until it lands (T4.4.1, fenced by BLK-1). That is the correct failure
+ * and it is not worked around.
+ *
+ * **There is no `--project` on any command in this group, and this module
+ * refuses one rather than ignoring it.** Variables are scoped by tenant and
+ * subject only: the `vars` table has no project column and no `vars` route reads
+ * the query parameter, while every `documents` route does. The asymmetry is
+ * real, so the CLI states it — accepting a flag the server ignores would teach a
+ * user a scoping model that does not exist, and they would find out when two
+ * projects turned out to share one variable.
+ *
+ * @module
+ */
+import { argument, noExtraArguments, preview, requiredFlag, table, textFlag, usageError, } from "./shared.js";
+/** The flag this group does not have, in both spellings a user can type it. */
+const PROJECT_FLAG = "--project";
+/**
+ * Refuse `--project`, with the reason.
+ *
+ * Which paths reach this, precisely, because a guard nobody can trigger is
+ * decoration:
+ *
+ * - `w6w vars list --project prj_1` does **not** reach it. `--project` is not
+ *   among a `vars` command's declared flags, so the parser rejects it as an
+ *   unknown flag before any handler runs — a usage error, exit `1`, with the
+ *   command's own help beneath it. Correct code, generic message; making that
+ *   message say *why* needs a note on the operation in `endpoints.json` (which
+ *   is where all help text comes from) or a "refused flag" concept in the
+ *   dispatcher, and both live outside this node's files — see BLK-2.
+ * - `w6w vars list -- --project prj_1` **does** reach it, as a positional. So
+ *   does any invocation in which the flag survives parsing, which is what makes
+ *   this a guard rather than a comment: if `--project` is ever added to the
+ *   `vars` operations by mistake, this is what fails instead of the server
+ *   quietly ignoring it.
+ *
+ * Called first in every handler, ahead of the argument-count check, so the
+ * specific explanation wins over "takes no arguments".
+ */
+function refuseProject(context) {
+    const flagged = Object.hasOwn(context.invocation.options, "project") ||
+        context.invocation.positionals.some((token) => token === PROJECT_FLAG || token.startsWith(`${PROJECT_FLAG}=`));
+    if (!flagged)
+        return;
+    throw usageError(context, `\`w6w vars\` commands take no ${PROJECT_FLAG}: variables are not project-scoped. ` +
+        "They are scoped to your tenant and subject, and every project you can reach sees " +
+        "the same ones. Documents are the project-scoped asset — see `w6w documents --help`.");
+}
+/**
+ * Encode a `--value` string into the JSON value the server will type-check.
+ *
+ * A command line carries text and the API carries JSON, so something has to
+ * bridge the two. The rule is one sentence, and it is **encoding, never
+ * validation** — nothing here rejects a value, and the type policy stays where
+ * it belongs, in the server (`400 invalid_type` / `400 invalid_value`):
+ *
+ * > With `--type string` the text is the value, verbatim. Otherwise the text is
+ * > read as JSON if it parses as JSON, and is the string itself if it does not.
+ *
+ * So `--type string --value hello` stores `"hello"`, `--type number --value 42`
+ * stores `42`, `--type json --value '{"a":1}'` stores the object — and
+ * `--type number --value forty-two` sends `"forty-two"`, which comes back as the
+ * server's `400 invalid_value` rather than as a client-side complaint that would
+ * go stale the day the server's rule changes.
+ *
+ * On `w6w vars update` the type is usually not restated, and then the fallback
+ * arm is the whole rule — which is also what makes an **explicit null**
+ * expressible: `--value null` sends `{"value":null}`, distinct from omitting the
+ * flag and sending `{}` (D2).
+ *
+ * @param text - The `--value` flag, as typed.
+ * @param type - The `--type` flag, when the invocation carried one.
+ * @returns The value to put in the request body.
+ */
+export function encodeValue(text, type) {
+    if (type === "string")
+        return text;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/** One variable, as a table row. */
+function row(variable) {
+    return [variable.id, variable.name, variable.type, preview(variable.value)];
+}
+/** The listing: one line per variable, or a line saying there are none. */
+function renderList(vars, styles) {
+    if (vars.length === 0)
+        return styles.dim("No variables.");
+    return table(["ID", "NAME", "TYPE", "VALUE"], vars.map(row), styles);
+}
+/** One variable in full. The value is pretty-printed JSON: it may be a document. */
+function renderVar(variable, styles) {
+    const heading = `${styles.bold(variable.name)} ${styles.dim(`(${variable.id})`)}`;
+    const meta = styles.dim(`${variable.type} · updated ${variable.updatedAt}`);
+    const description = variable.description.length > 0 ? [variable.description] : [];
+    return [heading, meta, ...description, "", JSON.stringify(variable.value, null, 2)].join("\n");
+}
+/** The confirmation for a write: what changed, and how to address it next time. */
+function renderWrite(verb, variable, styles) {
+    return `${verb} ${styles.bold(variable.name)} ${styles.dim(`(${variable.id})`)}`;
+}
+const list = async (context) => {
+    refuseProject(context);
+    noExtraArguments(context, 0);
+    const vars = await context.client().vars.list();
+    context.out.emit(vars, (styles) => renderList(vars, styles));
+};
+const get = async (context) => {
+    refuseProject(context);
+    const id = argument(context, 0, "a variable id (see: `w6w vars list`)");
+    noExtraArguments(context, 1);
+    const variable = await context.client().vars.get(id);
+    context.out.emit(variable, (styles) => renderVar(variable, styles));
+};
+/**
+ * `w6w vars get-by-name <name>` — the name-addressed read.
+ *
+ * The name is handed to the SDK untouched and percent-encoded at interpolation.
+ * **No name is rejected here**: `^[a-z_][a-z0-9_]*$` is the server's rule to
+ * enforce, and a copy of it in the CLI would refuse locally whatever the server
+ * started accepting next. The same dot-segment caveat as
+ * `w6w documents get-by-key` applies to this lane (D1) — see
+ * `src/commands/documents.ts` — though the server's own name rule admits no dot
+ * at all, so no name it accepts can reach it.
+ */
+const getByName = async (context) => {
+    refuseProject(context);
+    const name = argument(context, 0, "a variable name (the name it was created under)");
+    noExtraArguments(context, 1);
+    const variable = await context.client().vars.getByName(name);
+    context.out.emit(variable, (styles) => renderVar(variable, styles));
+};
+const create = async (context) => {
+    refuseProject(context);
+    const name = argument(context, 0, "a variable name to create (matching `^[a-z_][a-z0-9_]*$`)");
+    noExtraArguments(context, 1);
+    const type = requiredFlag(context, "type", "--type <t>");
+    const variable = await context.client().vars.create({
+        name,
+        // Cast, not checked: the four types are the server's enum, which answers
+        // `400 invalid_type` for anything else. A copy of it here would go stale.
+        type: type,
+        value: encodeValue(requiredFlag(context, "value", "--value <v>"), type),
+        description: textFlag(context, "description"),
+    });
+    context.out.emit(variable, (styles) => renderWrite("Created", variable, styles));
+};
+/**
+ * `w6w vars update <id>` — a patch, addressed by the server-issued id.
+ *
+ * **Only flags the user typed reach the wire (D2).** `w6w vars update var_1
+ * --description "…"` sends `{"description":"…"}` and leaves the value alone;
+ * `w6w vars update var_1` alone sends `{}`; and `--value null` sends
+ * `{"value":null}`, which is a different request meaning a different thing. The
+ * three are distinguishable because the patch is assembled field by field from
+ * flags that were **present**, never from values that happened to be truthy.
+ */
+const update = async (context) => {
+    refuseProject(context);
+    const id = argument(context, 0, "the variable id to update (see: `w6w vars list`)");
+    noExtraArguments(context, 1);
+    const patch = {};
+    const type = textFlag(context, "type");
+    if (type !== undefined)
+        patch.type = type;
+    const value = textFlag(context, "value");
+    if (value !== undefined)
+        patch.value = encodeValue(value, type);
+    const description = textFlag(context, "description");
+    if (description !== undefined)
+        patch.description = description;
+    const variable = await context.client().vars.update(id, patch);
+    context.out.emit(variable, (styles) => renderWrite("Updated", variable, styles));
+};
+/**
+ * `w6w vars delete <id>` — and **nothing on stdout**.
+ *
+ * As with documents: the server's `{ok:true}` unwraps to nothing at all, so the
+ * machine-readable answer is the exit code and the human's confirmation goes
+ * through `note()`, which `--json` suppresses.
+ */
+const remove = async (context) => {
+    refuseProject(context);
+    const id = argument(context, 0, "the variable id to delete (see: `w6w vars list`)");
+    noExtraArguments(context, 1);
+    await context.client().vars.delete(id);
+    context.out.note(`Deleted ${id}.`);
+};
+/**
+ * The six `w6w vars` commands, keyed by the canonical command path.
+ *
+ * The keys are the generated help tree's `path` values joined by a space, which
+ * are `endpoints.json`'s `naming.cli` spellings — `tests/cmd_vars_test.ts`
+ * asserts the two sets are the same, so a command cannot be registered under a
+ * name the help does not document, or documented under a name nothing runs.
+ */
+export const VAR_COMMANDS = {
+    "vars list": list,
+    "vars get": get,
+    "vars get-by-name": getByName,
+    "vars create": create,
+    "vars update": update,
+    "vars delete": remove,
+};
+//# sourceMappingURL=vars.js.map

package/dist/src/commands/vars.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vars.js","sourceRoot":"","sources":["../../../src/commands/vars.ts"],"names":[],"mappings":"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"}

package/dist/src/commands/workflows.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `w6w workflows …` — list definitions and start runs (D4).
+ *
+ * Two commands. `list` exists so a caller can find a `wf_…` id to pass to
+ * `w6w run` or to this group's own `run`; `run` is the typed path with
+ * `--wait`, kept alongside the unified `w6w run` because `?wait=`, variables
+ * and trigger have no slot in that operation's three-field shape.
+ *
+ * @module
+ */
+import type { CommandRegistry } from "../../mod.ts";
+export declare const WORKFLOW_COMMANDS: CommandRegistry;
+//# sourceMappingURL=workflows.d.ts.map

package/dist/src/commands/workflows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.d.ts","sourceRoot":"","sources":["../../../src/commands/workflows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAkC,eAAe,EAAE,MAAM,cAAc,CAAC;AAoEpF,eAAO,MAAM,iBAAiB,EAAE,eAG/B,CAAC"}

package/dist/src/commands/workflows.js

@@ -0,0 +1,75 @@
+/**
+ * `w6w workflows …` — list definitions and start runs (D4).
+ *
+ * Two commands. `list` exists so a caller can find a `wf_…` id to pass to
+ * `w6w run` or to this group's own `run`; `run` is the typed path with
+ * `--wait`, kept alongside the unified `w6w run` because `?wait=`, variables
+ * and trigger have no slot in that operation's three-field shape.
+ *
+ * @module
+ */
+import { argument, noExtraArguments, table, textFlag } from "./shared.js";
+import { exitCodeFor } from "../exit.js";
+/**
+ * The `--project` scope for `list`, or nothing at all.
+ *
+ * Nothing is the important case — an omitted flag is how the caller asks the
+ * server for every project the credential can see, matching
+ * `src/commands/documents.ts`'s `scope()`.
+ */
+function scope(context) {
+    const project = textFlag(context, "project");
+    return project === undefined ? {} : { project };
+}
+/** One workflow, as a table row. */
+function row(workflow) {
+    return [workflow.id, workflow.name, workflow.status, String(workflow.runCount)];
+}
+/** The listing: one line per workflow, or a line saying there are none. */
+function renderList(workflows, styles) {
+    if (workflows.length === 0)
+        return styles.dim("No workflows.");
+    return table(["ID", "NAME", "STATUS", "RUNS"], workflows.map(row), styles);
+}
+/**
+ * A run result. `terminal` and `httpStatus` are this SDK's own derived
+ * fields, not part of the wire body — they are not restated here, and stay
+ * in the `--json` payload, which is the raw object handed to
+ * `context.out.emit`.
+ */
+function renderRun(run, styles) {
+    const heading = `${styles.bold(run.runId)} — ${run.status}`;
+    if (run.status !== "failed" || run.error === undefined)
+        return heading;
+    return `${heading}\n${JSON.stringify(run.error, null, 2)}`;
+}
+const list = async (context) => {
+    noExtraArguments(context, 0);
+    const workflows = await context.client().workflows.list(scope(context));
+    context.out.emit(workflows, (styles) => renderList(workflows, styles));
+};
+/**
+ * `w6w workflows run <id> [--wait]` — enqueue a run, optionally waiting for a
+ * terminal state.
+ *
+ * **A failed run is data, not a thrown error (D3/D4)**: the SDK returns it
+ * rather than raising, so this handler is the one place that turns a
+ * `status: "failed"` result into the CLI's own exit code 3, via the shared
+ * `exitCodeFor` every command falls into the same way (`src/exit.ts`). A
+ * queued or successful run returns `undefined` from `exitCodeFor`'s callers
+ * elsewhere as success — here it is explicit because this is the one command
+ * whose success path can carry a run-level failure.
+ */
+const run = async (context) => {
+    const id = argument(context, 0, "a workflow id (see: `w6w workflows list`)");
+    noExtraArguments(context, 1);
+    const wait = context.invocation.options.wait === true;
+    const result = await context.client().workflows.run(id, wait ? { wait } : {});
+    context.out.emit(result, (styles) => renderRun(result, styles));
+    return exitCodeFor(result);
+};
+export const WORKFLOW_COMMANDS = {
+    "workflows list": list,
+    "workflows run": run,
+};
+//# sourceMappingURL=workflows.js.map

package/dist/src/commands/workflows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.js","sourceRoot":"","sources":["../../../src/commands/workflows.ts"],"names":[],"mappings":"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"}

package/dist/src/exit.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 { EXIT_API_ERROR, EXIT_RUN_FAILURE, EXIT_SUCCESS, EXIT_USAGE } from "./help.generated.ts";
+export { EXIT_API_ERROR, EXIT_RUN_FAILURE, EXIT_SUCCESS, EXIT_USAGE };
+/**
+ * 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 declare function exitCodeFor(outcome: unknown): number;
+//# sourceMappingURL=exit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exit.d.ts","sourceRoot":"","sources":["../../src/exit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,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;AA+BtE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAYpD"}