@w6w/cli 0.1.0

package/dist/src/args.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The argument parser.
+ *
+ * There is no CLI framework anywhere in this workspace, and this package takes no
+ * runtime dependency to get one. `parse()` is a **pure function**: it is handed an
+ * argument vector and returns a structured result. It never reads the real
+ * command line, never reads the environment, never writes output and never exits
+ * — that is `src/runtime.ts`'s job, and keeping the two apart is what makes every
+ * invocation in this file testable in-process, in any runtime.
+ *
+ * It also never throws on bad input. A wrong invocation is an ordinary outcome
+ * for a CLI, so a usage error comes back as a value (`{ ok: false }`) carrying the
+ * command path the user was aiming at, which is how the caller knows *which* help
+ * to print (root, group or command) before exiting 1.
+ *
+ * Flag names, aliases and the set of valid command paths all come from the
+ * generated module rather than being restated here, so the parser cannot drift
+ * from the surface contract the help text is built from.
+ *
+ * @module
+ */
+/** A flag the parser will accept. */
+export interface FlagSpec {
+    /** The long name, with its leading dashes, e.g. `--base-url`. */
+    name: string;
+    /** The short alias, with its leading dash, e.g. `-h`. */
+    alias: string | null;
+    /** `boolean` flags take no value; `string` flags take one. */
+    type: string;
+}
+/** The six global flags, exactly as the surface contract declares them. */
+export declare const GLOBAL_FLAG_SPECS: FlagSpec[];
+/** The global flags, resolved. */
+export interface GlobalOptions {
+    /** `--base-url`; falls back to `W6W_BASE_URL` later, in the client. */
+    baseUrl?: string;
+    /** `--token`; falls back to `W6W_TOKEN` later, in the client. */
+    token?: string;
+    json: boolean;
+    noColor: boolean;
+    version: boolean;
+    help: boolean;
+}
+/** A successfully parsed command line. */
+export interface Invocation {
+    /** The command path, e.g. `["documents", "create"]`. Empty for a bare `w6w`. */
+    command: string[];
+    /** Everything left over after the command path, in order. */
+    positionals: string[];
+    globals: GlobalOptions;
+    /** Non-global flags, keyed by camelCased name. Empty unless `flags` was passed. */
+    options: Record<string, string | boolean>;
+}
+/** What `parse()` returns: a parsed command line, or a usage error to report. */
+export type ParseResult = {
+    ok: true;
+    invocation: Invocation;
+} | {
+    ok: false;
+    message: string;
+    command: string[];
+};
+/** Optional extras, so a command group can add its own flags without a rewrite. */
+export interface ParseOptions {
+    /** Command-specific flags, on top of the six global ones. */
+    flags?: readonly FlagSpec[];
+    /** The command paths that exist. Defaults to the generated contract's. */
+    commands?: readonly (readonly string[])[];
+}
+/**
+ * Parses an argument vector.
+ *
+ * Accepted forms: `--flag`, `--flag value`, `--flag=value`, a short alias
+ * (`-h`, `-v`), and `--` to end flag parsing. A repeated flag keeps the last
+ * value. An unknown flag, a missing value, or a value handed to a boolean flag
+ * are all reported as usage errors.
+ */
+export declare function parse(argv: string[], options?: ParseOptions): ParseResult;
+//# sourceMappingURL=args.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,qCAAqC;AACrC,MAAM,WAAW,QAAQ;IACvB,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,2EAA2E;AAC3E,eAAO,MAAM,iBAAiB,EAAE,QAAQ,EAIrC,CAAC;AAEJ,kCAAkC;AAClC,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,0CAA0C;AAC1C,MAAM,WAAW,UAAU;IACzB,gFAAgF;IAChF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,aAAa,CAAC;IACvB,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;CAC3C;AAED,iFAAiF;AACjF,MAAM,MAAM,WAAW,GACnB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,GACpC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEtD,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;CAC3C;AAgCD;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,YAAiB,GAAG,WAAW,CA6E7E"}

package/dist/src/args.js

@@ -0,0 +1,130 @@
+/**
+ * The argument parser.
+ *
+ * There is no CLI framework anywhere in this workspace, and this package takes no
+ * runtime dependency to get one. `parse()` is a **pure function**: it is handed an
+ * argument vector and returns a structured result. It never reads the real
+ * command line, never reads the environment, never writes output and never exits
+ * — that is `src/runtime.ts`'s job, and keeping the two apart is what makes every
+ * invocation in this file testable in-process, in any runtime.
+ *
+ * It also never throws on bad input. A wrong invocation is an ordinary outcome
+ * for a CLI, so a usage error comes back as a value (`{ ok: false }`) carrying the
+ * command path the user was aiming at, which is how the caller knows *which* help
+ * to print (root, group or command) before exiting 1.
+ *
+ * Flag names, aliases and the set of valid command paths all come from the
+ * generated module rather than being restated here, so the parser cannot drift
+ * from the surface contract the help text is built from.
+ *
+ * @module
+ */
+import { COMMAND_PATHS, GLOBAL_FLAGS } from "./help.generated.js";
+/** The six global flags, exactly as the surface contract declares them. */
+export const GLOBAL_FLAG_SPECS = GLOBAL_FLAGS.map((flag) => ({
+    name: flag.name,
+    alias: flag.alias,
+    type: flag.type,
+}));
+/** `--base-url` → `baseUrl`. */
+function optionKey(flagName) {
+    return flagName.replace(/^--/, "").replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+/**
+ * Splits the leftover operands into a command path and its positional arguments.
+ *
+ * Longest match wins, against the command paths the contract declares — which is
+ * what tells `w6w run conn_01H…` (a root command plus a positional) apart from
+ * `w6w documents get` (a two-token command path). An operand that matches nothing
+ * is still returned as a one-token command, so the caller can report it as an
+ * unknown command rather than as a stray argument.
+ */
+function splitCommand(operands, commands) {
+    if (operands.length === 0)
+        return { command: [], positionals: [] };
+    if (operands.length >= 2) {
+        const twoTokenMatch = commands.some((path) => path.length === 2 && path[0] === operands[0] && path[1] === operands[1]);
+        if (twoTokenMatch) {
+            return { command: operands.slice(0, 2), positionals: operands.slice(2) };
+        }
+    }
+    return { command: operands.slice(0, 1), positionals: operands.slice(1) };
+}
+/**
+ * Parses an argument vector.
+ *
+ * Accepted forms: `--flag`, `--flag value`, `--flag=value`, a short alias
+ * (`-h`, `-v`), and `--` to end flag parsing. A repeated flag keeps the last
+ * value. An unknown flag, a missing value, or a value handed to a boolean flag
+ * are all reported as usage errors.
+ */
+export function parse(argv, options = {}) {
+    const specs = [...GLOBAL_FLAG_SPECS, ...(options.flags ?? [])];
+    const commands = options.commands ?? COMMAND_PATHS;
+    const byName = new Map(specs.map((spec) => [spec.name, spec]));
+    const byAlias = new Map(specs.filter((spec) => spec.alias).map((spec) => [spec.alias, spec]));
+    const values = {};
+    const operands = [];
+    const fail = (message) => ({
+        ok: false,
+        message,
+        command: splitCommand(operands, commands).command,
+    });
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--") {
+            operands.push(...argv.slice(i + 1));
+            break;
+        }
+        if (!token.startsWith("-") || token === "-") {
+            operands.push(token);
+            continue;
+        }
+        const equals = token.indexOf("=");
+        const rawName = equals === -1 ? token : token.slice(0, equals);
+        const inlineValue = equals === -1 ? null : token.slice(equals + 1);
+        const spec = rawName.startsWith("--") ? byName.get(rawName) : byAlias.get(rawName);
+        if (!spec)
+            return fail(`unknown flag: ${rawName}`);
+        if (spec.type === "boolean") {
+            if (inlineValue !== null)
+                return fail(`flag ${spec.name} takes no value`);
+            values[optionKey(spec.name)] = true;
+            continue;
+        }
+        if (inlineValue !== null) {
+            values[optionKey(spec.name)] = inlineValue;
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next === undefined || (next.startsWith("-") && next !== "-")) {
+            return fail(`flag ${spec.name} requires a value`);
+        }
+        values[optionKey(spec.name)] = next;
+        i++;
+    }
+    const { command, positionals } = splitCommand(operands, commands);
+    const globalKeys = new Set(GLOBAL_FLAG_SPECS.map((spec) => optionKey(spec.name)));
+    const extras = {};
+    for (const [key, value] of Object.entries(values)) {
+        if (!globalKeys.has(key))
+            extras[key] = value;
+    }
+    return {
+        ok: true,
+        invocation: {
+            command,
+            positionals,
+            globals: {
+                baseUrl: typeof values.baseUrl === "string" ? values.baseUrl : undefined,
+                token: typeof values.token === "string" ? values.token : undefined,
+                json: values.json === true,
+                noColor: values.noColor === true,
+                version: values.version === true,
+                help: values.help === true,
+            },
+            options: extras,
+        },
+    };
+}
+//# sourceMappingURL=args.js.map

package/dist/src/args.js.map

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

package/dist/src/client.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Flags and environment in, a configured `@w6w/sdk` client out.
+ *
+ * This module is the CLI's whole configuration story, and it is deliberately
+ * thin: **no transport, no base-path joining, no HTTP error mapping lives here**
+ * — all of that is the SDK's, and duplicating any of it in a second package is
+ * how two clients of one API start disagreeing about what a base URL means.
+ * What belongs here is the one thing the SDK cannot know: that a command line
+ * has a flag which outranks the environment variable.
+ *
+ * ```
+ * CLI flag (--base-url / --token)  >  environment variable  >  nothing (an error)
+ * ```
+ *
+ * The resolved values are passed to the SDK **explicitly**, and the SDK is never
+ * left to read the environment on the CLI's behalf. That is a mechanism choice,
+ * not a stylistic one: the CLI has to be able to say *which* source it was
+ * looking at when it reports a missing or malformed value, and a library that
+ * reads the environment behind you cannot tell you that. It also means every
+ * environment-dependent behaviour in this package has one seam a test can
+ * substitute — {@linkcode EnvReader} — instead of a real process environment
+ * that only one test at a time can own.
+ *
+ * @module
+ */
+import { type FetchLike, W6wClient } from "@w6w/sdk";
+import type { GlobalOptions } from "./args.ts";
+/**
+ * Reads one environment variable, or `undefined` where the host has none.
+ *
+ * The same shape as `src/runtime.ts`'s `env`, which is the only thing in this
+ * package that reads a real process environment; everything downstream — this
+ * module included — receives it as a value.
+ */
+export type EnvReader = (name: string) => string | undefined;
+/** Environment variable holding the server **origin**. Falls behind `--base-url`. */
+export declare const ENV_BASE_URL = "W6W_BASE_URL";
+/** Environment variable holding the bearer token. Falls behind `--token`. */
+export declare const ENV_TOKEN = "W6W_TOKEN";
+/** An environment with nothing in it. The default, so nothing leaks in by accident. */
+export declare const NO_ENV: EnvReader;
+/**
+ * Read an environment variable, treating a blank value as **absent**.
+ *
+ * `W6W_BASE_URL=`, `W6W_BASE_URL="   "` and an unset `W6W_BASE_URL` are the same
+ * thing: all three fall through the precedence chain to the next source, and
+ * ultimately to a usage error naming both sources.
+ *
+ * The check is a trim-and-emptiness test and deliberately **not** a nullish
+ * coalesce. `??` does not convert `""`, so a set-but-empty variable would
+ * survive as a value and be resolved into a base URL of `/api` — a relative URL,
+ * which fails much later with a message about a request instead of here with a
+ * message about configuration. A blank variable is not exotic: `export W6W_TOKEN=`,
+ * a Dockerfile `ENV` with no build argument behind it, and a CI variable whose
+ * template did not interpolate all produce exactly this, and all three look
+ * unset in every log line.
+ *
+ * The surviving value is returned **verbatim**; trimming applies to the test,
+ * not to the value.
+ *
+ * @param env - The environment seam to read through.
+ * @param name - The variable to read.
+ * @returns The value, or `undefined` when it is unset or blank.
+ */
+export declare function envValue(env: EnvReader, name: string): string | undefined;
+/** Anything the caller wants to hand the client beyond the global flags. */
+export interface ClientOptions {
+    /**
+     * Transport override, passed straight to the SDK. The seam the test suite
+     * runs against; nothing in normal operation sets it.
+     */
+    fetch?: FetchLike;
+    /** Default project id for the project-scoped operations. */
+    project?: string;
+}
+/**
+ * Build the API client for one invocation.
+ *
+ * Call this **lazily**, when a command has decided it needs the API — never at
+ * module load, and never on the help or `--version` path, which must resolve
+ * with no token configured and no server reachable.
+ *
+ * @param globals - The parsed global flags.
+ * @param env - The environment seam. Defaults to an empty environment.
+ * @param options - Transport and default project.
+ * @returns A configured client.
+ * @throws {ConfigError} When the base URL or token is missing or unusable — a usage error.
+ */
+export declare function createClient(globals: GlobalOptions, env?: EnvReader, options?: ClientOptions): W6wClient;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAe,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;AAE7D,qFAAqF;AACrF,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C,6EAA6E;AAC7E,eAAO,MAAM,SAAS,cAAc,CAAC;AAErC,uFAAuF;AACvF,eAAO,MAAM,MAAM,EAAE,SAA2B,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIzE;AAkGD,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,aAAa,EACtB,GAAG,GAAE,SAAkB,EACvB,OAAO,GAAE,aAAkB,GAC1B,SAAS,CA8BX"}

package/dist/src/client.js

@@ -0,0 +1,172 @@
+/**
+ * Flags and environment in, a configured `@w6w/sdk` client out.
+ *
+ * This module is the CLI's whole configuration story, and it is deliberately
+ * thin: **no transport, no base-path joining, no HTTP error mapping lives here**
+ * — all of that is the SDK's, and duplicating any of it in a second package is
+ * how two clients of one API start disagreeing about what a base URL means.
+ * What belongs here is the one thing the SDK cannot know: that a command line
+ * has a flag which outranks the environment variable.
+ *
+ * ```
+ * CLI flag (--base-url / --token)  >  environment variable  >  nothing (an error)
+ * ```
+ *
+ * The resolved values are passed to the SDK **explicitly**, and the SDK is never
+ * left to read the environment on the CLI's behalf. That is a mechanism choice,
+ * not a stylistic one: the CLI has to be able to say *which* source it was
+ * looking at when it reports a missing or malformed value, and a library that
+ * reads the environment behind you cannot tell you that. It also means every
+ * environment-dependent behaviour in this package has one seam a test can
+ * substitute — {@linkcode EnvReader} — instead of a real process environment
+ * that only one test at a time can own.
+ *
+ * @module
+ */
+import { ConfigError, W6wClient } from "@w6w/sdk";
+/** Environment variable holding the server **origin**. Falls behind `--base-url`. */
+export const ENV_BASE_URL = "W6W_BASE_URL";
+/** Environment variable holding the bearer token. Falls behind `--token`. */
+export const ENV_TOKEN = "W6W_TOKEN";
+/** An environment with nothing in it. The default, so nothing leaks in by accident. */
+export const NO_ENV = () => undefined;
+/**
+ * Read an environment variable, treating a blank value as **absent**.
+ *
+ * `W6W_BASE_URL=`, `W6W_BASE_URL="   "` and an unset `W6W_BASE_URL` are the same
+ * thing: all three fall through the precedence chain to the next source, and
+ * ultimately to a usage error naming both sources.
+ *
+ * The check is a trim-and-emptiness test and deliberately **not** a nullish
+ * coalesce. `??` does not convert `""`, so a set-but-empty variable would
+ * survive as a value and be resolved into a base URL of `/api` — a relative URL,
+ * which fails much later with a message about a request instead of here with a
+ * message about configuration. A blank variable is not exotic: `export W6W_TOKEN=`,
+ * a Dockerfile `ENV` with no build argument behind it, and a CI variable whose
+ * template did not interpolate all produce exactly this, and all three look
+ * unset in every log line.
+ *
+ * The surviving value is returned **verbatim**; trimming applies to the test,
+ * not to the value.
+ *
+ * @param env - The environment seam to read through.
+ * @param name - The variable to read.
+ * @returns The value, or `undefined` when it is unset or blank.
+ */
+export function envValue(env, name) {
+    const value = env(name);
+    if (value === undefined || value.trim().length === 0)
+        return undefined;
+    return value;
+}
+/**
+ * Apply the precedence rule to one setting.
+ *
+ * A flag that was **given** wins outright, even when what it was given is empty:
+ * that is a value the user typed, and quietly consulting the environment behind
+ * an explicit `--token=` would be the CLI second-guessing them. (It still does
+ * not produce a usable value — an empty flag reaches the same error — but it
+ * gets there without a detour through the environment.) Only an **absent** flag
+ * falls through.
+ */
+function resolve(flag, env, name) {
+    if (flag !== undefined)
+        return flag;
+    return envValue(env, name);
+}
+/**
+ * A value the CLI cannot work with, phrased as a usage error.
+ *
+ * Every message names **both** sources, because "which one was I supposed to
+ * set?" is the only question the user has at this point, and the answer depends
+ * on whether they are typing a command or writing a deploy manifest.
+ *
+ * The type is the SDK's {@linkcode ConfigError}, not a new one: the split that
+ * matters is configuration-versus-API, and it already exists. A `ConfigError`
+ * means the request never left this machine — `src/exit.ts` maps it to the usage
+ * code. An `ApiError` means the server answered.
+ */
+function configError(problem, flag, variable, hint) {
+    return new ConfigError(`${problem} Set it with ${flag} or the ${variable} environment variable. ${hint}`);
+}
+/**
+ * Reject a base URL the CLI cannot actually send a request to.
+ *
+ * A relative base (`/api`, `localhost:8080`) is a **usage** error and is caught
+ * here, at the point the user can still do something about it. Left alone it
+ * becomes a transport failure much later, reported as "the server may be down" —
+ * a misdiagnosis a user will act on, restarting a server that was never the
+ * problem. The scheme is required for the same reason: `localhost:8080` parses
+ * as a URL whose scheme is `localhost:`, not as a host.
+ */
+function requireAbsolute(baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw configError(`The w6w base URL must be an absolute origin, and \`${baseUrl}\` is not one.`, "--base-url", ENV_BASE_URL, "It looks like `https://api.example.com` — scheme and host, no path.");
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw configError(`The w6w base URL must be an http or https origin, and \`${baseUrl}\` is not one.`, "--base-url", ENV_BASE_URL, "It looks like `https://api.example.com` — scheme and host, no path.");
+    }
+    return baseUrl;
+}
+/**
+ * Characters that cannot be carried in an HTTP header value: the C0 controls,
+ * `DEL`, and anything above the single-byte range.
+ *
+ * A token is normally opaque ASCII, so this rejects almost nothing real — except
+ * the one thing that happens constantly, which is a trailing newline on a token
+ * read out of a file (`W6W_TOKEN=$(cat token.txt)`). Left unchecked that reaches
+ * the header builder and comes back as a bare `TypeError` from outside anyone's
+ * error model: a stack trace, for a typo.
+ */
+function isUnsendable(token) {
+    for (const character of token) {
+        const code = character.codePointAt(0) ?? 0;
+        if (code < 0x20 || code === 0x7f || code > 0xff)
+            return true;
+    }
+    return false;
+}
+/** The token, checked well enough that it can actually be put on the wire. */
+function requireSendableToken(token) {
+    if (!isUnsendable(token))
+        return token;
+    throw configError("The w6w API token contains a character that cannot be sent in an HTTP header " +
+        "(a control character, such as a newline).", "--token", ENV_TOKEN, "A token read out of a file usually carries a trailing newline — strip it.");
+}
+/**
+ * Build the API client for one invocation.
+ *
+ * Call this **lazily**, when a command has decided it needs the API — never at
+ * module load, and never on the help or `--version` path, which must resolve
+ * with no token configured and no server reachable.
+ *
+ * @param globals - The parsed global flags.
+ * @param env - The environment seam. Defaults to an empty environment.
+ * @param options - Transport and default project.
+ * @returns A configured client.
+ * @throws {ConfigError} When the base URL or token is missing or unusable — a usage error.
+ */
+export function createClient(globals, env = NO_ENV, options = {}) {
+    const baseUrl = resolve(globals.baseUrl, env, ENV_BASE_URL);
+    if (baseUrl === undefined || baseUrl.trim().length === 0) {
+        throw configError("No w6w base URL is configured.", "--base-url", ENV_BASE_URL, "It holds the server's origin, like `https://api.example.com`; the API base path is appended for you.");
+    }
+    const token = resolve(globals.token, env, ENV_TOKEN);
+    if (token === undefined || token.trim().length === 0) {
+        throw configError("No w6w API token is configured.", "--token", ENV_TOKEN, "Every w6w API command is authenticated.");
+    }
+    // The join rule (origin in, base path appended, never doubled) belongs to the
+    // SDK and is applied by the constructor. Nothing here re-derives it — read it
+    // back off `client.config.baseUrl` if you need to know where a request went.
+    return new W6wClient({
+        baseUrl: requireAbsolute(baseUrl.trim()),
+        token: requireSendableToken(token),
+        project: options.project,
+        fetch: options.fetch,
+    });
+}
+//# sourceMappingURL=client.js.map

package/dist/src/client.js.map

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

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

@@ -0,0 +1,13 @@
+/**
+ * `w6w connections list` — discovery, and nothing more (D4).
+ *
+ * One command, one SDK call, no filters and no pagination: the operation
+ * exists so a caller can find a `conn_…` id to pass to `w6w run`, and nothing
+ * about creating, testing or reconnecting an app lives here — that is
+ * `outOfScope` in `endpoints.json` for this version.
+ *
+ * @module
+ */
+import type { CommandRegistry } from "../../mod.ts";
+export declare const CONNECTION_COMMANDS: CommandRegistry;
+//# sourceMappingURL=connections.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connections.d.ts","sourceRoot":"","sources":["../../../src/commands/connections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAkB,eAAe,EAAE,MAAM,cAAc,CAAC;AAsBpE,eAAO,MAAM,mBAAmB,EAAE,eAEjC,CAAC"}

package/dist/src/commands/connections.js

@@ -0,0 +1,30 @@
+/**
+ * `w6w connections list` — discovery, and nothing more (D4).
+ *
+ * One command, one SDK call, no filters and no pagination: the operation
+ * exists so a caller can find a `conn_…` id to pass to `w6w run`, and nothing
+ * about creating, testing or reconnecting an app lives here — that is
+ * `outOfScope` in `endpoints.json` for this version.
+ *
+ * @module
+ */
+import { noExtraArguments, table } from "./shared.js";
+/** One connection, as a table row. */
+function row(connection) {
+    return [connection.id, connection.appId, connection.state, connection.displayName];
+}
+/** The listing: one line per connection, or a line saying there are none. */
+function renderList(connections, styles) {
+    if (connections.length === 0)
+        return styles.dim("No connections.");
+    return table(["ID", "APP", "STATE", "NAME"], connections.map(row), styles);
+}
+const list = async (context) => {
+    noExtraArguments(context, 0);
+    const connections = await context.client().connections.list();
+    context.out.emit(connections, (styles) => renderList(connections, styles));
+};
+export const CONNECTION_COMMANDS = {
+    "connections list": list,
+};
+//# sourceMappingURL=connections.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connections.js","sourceRoot":"","sources":["../../../src/commands/connections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEtD,sCAAsC;AACtC,SAAS,GAAG,CAAC,UAA6B;IACxC,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;AACrF,CAAC;AAED,6EAA6E;AAC7E,SAAS,UAAU,CAAC,WAAgC,EAAE,MAAc;IAClE,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnE,OAAO,KAAK,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;AAC7E,CAAC;AAED,MAAM,IAAI,GAAmB,KAAK,EAAE,OAAO,EAAE,EAAE;IAC7C,gBAAgB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAC7B,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;IAC9D,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;AAC7E,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAoB;IAClD,kBAAkB,EAAE,IAAI;CACzB,CAAC"}

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

@@ -0,0 +1,34 @@
+/**
+ * `w6w documents …` — the document store at the command line.
+ *
+ * Six commands, **one SDK call each**. Nothing here composes two requests,
+ * filters a list, sorts a result or resolves a key by scanning: a wrapper that
+ * has to compose two calls is describing an operation that belongs in the API
+ * (`README.md`, "What a wrapper is"), and the CLI is a wrapper like the other
+ * two. Addressing mirrors the server exactly — **create by `key`, read by id or
+ * by key, update and delete by id** (`docs/implementation.md` §7).
+ *
+ * Everything a handler does falls into four steps, in this order: read its own
+ * arguments, call one method on `client.documents`, render, return. Errors are
+ * not caught here — `main()` reports a throw once, on stderr, and maps it to an
+ * exit code through `src/exit.ts`, so an `ApiError` exits 2 and a usage error
+ * exits 1 without any command deciding that for itself.
+ *
+ * **`--project` belongs to this group and not to `w6w vars`.** Documents are
+ * project-scoped and every route below takes an optional `?project=`; variables
+ * are not, and `src/commands/vars.ts` refuses the flag rather than accepting one
+ * the server would ignore.
+ *
+ * @module
+ */
+import type { CommandRegistry } from "../../mod.ts";
+/**
+ * The six `w6w documents` 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_documents_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 DOCUMENT_COMMANDS: CommandRegistry;
+//# sourceMappingURL=documents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../../src/commands/documents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAkC,eAAe,EAAE,MAAM,cAAc,CAAC;AA4JpF;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,eAO/B,CAAC"}