@forumulate/cli 0.5.0 → 0.9.0

package/dist/commands/groups.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GROUPS = void 0;
+exports.findGroup = findGroup;
+const groups_api_1 = require("./groups-api");
+const groups_community_1 = require("./groups-community");
+const groups_content_1 = require("./groups-content");
+const groups_docs_1 = require("./groups-docs");
+const groups_org_1 = require("./groups-org");
+const groups_site_1 = require("./groups-site");
+const groups_spaces_1 = require("./groups-spaces");
+const groups_types_1 = require("./groups-types");
+/**
+ * The resource commands, as data. Each verb is one operation in the bundled
+ * spec; `resource.ts` derives the flags. `operations.test.ts` asserts every
+ * operationId named here exists, so a renamed route breaks the build, not a
+ * customer's script.
+ *
+ * The verbs are the same everywhere — list, get, create, update, delete, and
+ * publish where a thing has a draft — because that is what `gh`, `stripe` and
+ * `vercel` taught people to type. A sub-resource is a two-word verb
+ * (`libraries keys rotate`, `docs schedule set`), never a third word.
+ *
+ * One file per domain (`groups-*.ts`), each with its own reason in its header;
+ * this one only puts them in the order `forumulate help` lists them.
+ */
+const SEARCH = {
+    name: 'search',
+    noun: 'result',
+    about: 'unified search across docs, forum and blog, and what it is missing',
+    verbs: {
+        query: {
+            op: 'UnifiedSearch_search_',
+            about: 'Search (--type docs|forum|blog, --limit); `search query <words>` for a verb word',
+            args: ['q...'],
+            columns: ['sourceType', 'title', 'url'],
+        },
+        semantic: {
+            op: 'UnifiedSearch_semanticSearch',
+            about: 'Search by meaning (your embedding provider; --mode)',
+            args: ['q...'],
+            columns: ['sourceType', 'title', 'url', 'score'],
+        },
+        recent: { op: 'UnifiedSearch_recent', about: 'Your recent searches' },
+        tags: { op: 'UnifiedSearch_tags', about: 'Every tag across the organization' },
+        tag: { op: 'UnifiedSearch_tagHub_', about: 'Everything carrying one tag', args: ['tag'] },
+        gaps: {
+            op: 'UnifiedSearch_gaps',
+            about: 'Searches that found nothing (--days)',
+            columns: ['query', 'count', 'lastSearchedAt'],
+        },
+        reindex: { op: 'UnifiedSearch_reindex', about: 'Rebuild the search index' },
+    },
+    defaultVerb: 'query',
+    bareArgs: true,
+};
+exports.GROUPS = [
+    ...groups_org_1.ORG_GROUPS,
+    ...groups_spaces_1.SPACE_GROUPS,
+    ...groups_docs_1.DOCS_GROUPS,
+    ...groups_api_1.API_GROUPS,
+    ...groups_community_1.COMMUNITY_GROUPS,
+    ...groups_types_1.TYPE_GROUPS,
+    ...groups_content_1.CONTENT_GROUPS,
+    ...groups_site_1.SITE_GROUPS,
+    SEARCH,
+];
+function findGroup(name) {
+    return exports.GROUPS.find((g) => g.name === name || g.aliases?.includes(name));
+}
+//# sourceMappingURL=groups.js.map

package/dist/commands/groups.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups.js","sourceRoot":"","sources":["../../src/commands/groups.ts"],"names":[],"mappings":";;;AAmEA,8BAEC;AArED,6CAA0C;AAC1C,yDAAsD;AACtD,qDAAkD;AAClD,+CAA4C;AAC5C,6CAA0C;AAC1C,+CAA4C;AAC5C,mDAA+C;AAC/C,iDAA6C;AAG7C;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,GAAa;IACvB,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,QAAQ;IACd,KAAK,EAAE,oEAAoE;IAC3E,KAAK,EAAE;QACL,KAAK,EAAE;YACL,EAAE,EAAE,uBAAuB;YAC3B,KAAK,EAAE,kFAAkF;YACzF,IAAI,EAAE,CAAC,MAAM,CAAC;YACd,OAAO,EAAE,CAAC,YAAY,EAAE,OAAO,EAAE,KAAK,CAAC;SACxC;QACD,QAAQ,EAAE;YACR,EAAE,EAAE,8BAA8B;YAClC,KAAK,EAAE,qDAAqD;YAC5D,IAAI,EAAE,CAAC,MAAM,CAAC;YACd,OAAO,EAAE,CAAC,YAAY,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC;SACjD;QACD,MAAM,EAAE,EAAE,EAAE,EAAE,sBAAsB,EAAE,KAAK,EAAE,sBAAsB,EAAE;QACrE,IAAI,EAAE,EAAE,EAAE,EAAE,oBAAoB,EAAE,KAAK,EAAE,mCAAmC,EAAE;QAC9E,GAAG,EAAE,EAAE,EAAE,EAAE,uBAAuB,EAAE,KAAK,EAAE,6BAA6B,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE;QACzF,IAAI,EAAE;YACJ,EAAE,EAAE,oBAAoB;YACxB,KAAK,EAAE,sCAAsC;YAC7C,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,gBAAgB,CAAC;SAC9C;QACD,OAAO,EAAE,EAAE,EAAE,EAAE,uBAAuB,EAAE,KAAK,EAAE,0BAA0B,EAAE;KAC5E;IACD,WAAW,EAAE,OAAO;IACpB,QAAQ,EAAE,IAAI;CACf,CAAC;AAEW,QAAA,MAAM,GAAe;IAChC,GAAG,uBAAU;IACb,GAAG,4BAAY;IACf,GAAG,yBAAW;IACd,GAAG,uBAAU;IACb,GAAG,mCAAgB;IACnB,GAAG,0BAAW;IACd,GAAG,+BAAc;IACjB,GAAG,yBAAW;IACd,MAAM;CACP,CAAC;AAEF,SAAgB,SAAS,CAAC,IAAY;IACpC,OAAO,cAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;AAC1E,CAAC"}

package/dist/commands/index.d.ts

@@ -0,0 +1,25 @@
+import { Http } from '../api/http';
+/**
+ * The commands added for API parity — `api`, `config`, `completion`, and the
+ * resource groups — routed before the older `switch` in `run.ts`.
+ *
+ * Returns undefined for anything it does not own, and for the older
+ * positional forms (`spaces <orgId>`, `items <orgId> <spaceId>`,
+ * `search <orgId> <query…>`, `domains [verify] <orgId> <spaceId>`), which keep
+ * their exact output: scripts parse it.
+ */
+export interface RouteDeps {
+    out: (l: string) => void;
+    err: (l: string) => void;
+    env?: NodeJS.ProcessEnv;
+    baseUrl?: string;
+    http?: Http;
+    ask?: (q: string) => Promise<string>;
+    readFile?: (path: string) => string | Buffer;
+    writeFile?: (path: string, data: Buffer | string) => void;
+    readStdin?: () => Promise<string>;
+    userAgent?: string;
+}
+export declare function readAllStdin(): Promise<string>;
+export declare function route(cmd: string, argv: string[], deps: RouteDeps): Promise<number | undefined>;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,IAAI,EAAe,MAAM,aAAa,CAAC;AAShD;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACzB,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,CAAC;IAC7C,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,KAAK,IAAI,CAAC;IAC1D,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAQ9C;AAmCD,wBAAsB,KAAK,CACzB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA8D7B"}

package/dist/commands/index.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readAllStdin = readAllStdin;
+exports.route = route;
+const node_fs_1 = require("node:fs");
+const args_1 = require("../api/args");
+const command_1 = require("../api/command");
+const http_1 = require("../api/http");
+const api_base_1 = require("../api-base");
+const credentials_1 = require("../credentials");
+const config_1 = require("./config");
+const completion_1 = require("./completion");
+const groups_1 = require("./groups");
+const resource_1 = require("./resource");
+function readAllStdin() {
+    return new Promise((resolve, reject) => {
+        let text = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (c) => (text += c));
+        process.stdin.on('end', () => resolve(text));
+        process.stdin.on('error', reject);
+    });
+}
+function commandDeps(argv, deps) {
+    const env = deps.env ?? process.env;
+    const config = (0, config_1.readConfig)(env);
+    const parsed = (0, args_1.parseArgs)(argv);
+    const baseUrl = deps.baseUrl ?? (0, api_base_1.apiBaseFromEnv)(env);
+    const onRetry = ({ waitMs, status }) => deps.err(`${status ? `HTTP ${status}` : 'Connection failed'}; retrying in ${Math.ceil(waitMs / 1000)}s…`);
+    const apiVersion = (0, config_1.setting)('api-version', (0, args_1.flag)(parsed, 'api-version'), env, config);
+    const http = deps.http
+        ? new http_1.Http({ onRetry, ...deps.http.opts, ...(apiVersion ? { apiVersion } : {}) })
+        : new http_1.Http({
+            baseUrl,
+            token: (0, credentials_1.resolveToken)(baseUrl, env),
+            userAgent: deps.userAgent ?? '@forumulate/cli',
+            apiVersion,
+            onRetry,
+        });
+    return {
+        http,
+        out: deps.out,
+        err: deps.err,
+        env,
+        config,
+        ask: deps.ask,
+        readFile: deps.readFile ?? ((p) => (0, node_fs_1.readFileSync)(p)),
+        writeFile: deps.writeFile ?? ((p, d) => (0, node_fs_1.writeFileSync)(p, d)),
+        readStdin: deps.readStdin ?? readAllStdin,
+        defaultOrg: (0, config_1.setting)('org', undefined, env, config),
+    };
+}
+async function route(cmd, argv, deps) {
+    // Everything after the command word; flags before it are kept.
+    const at = argv.indexOf(cmd);
+    const tail = [...argv.slice(0, at), ...argv.slice(at + 1)];
+    if (cmd === '__complete') {
+        for (const c of (0, completion_1.complete)(tail))
+            deps.out(c);
+        return 0;
+    }
+    if (cmd === 'completion') {
+        const script = (0, completion_1.completionScript)(tail.find((a) => !a.startsWith('-')) ?? '');
+        if (!script) {
+            deps.err('Usage: forumulate completion bash|zsh|fish');
+            return 1;
+        }
+        deps.out(script);
+        return 0;
+    }
+    if (cmd === 'config') {
+        const p = (0, args_1.parseArgs)(tail);
+        if ((0, args_1.has)(p, 'help')) {
+            deps.out(config_1.CONFIG_HELP);
+            return 0;
+        }
+        return (0, config_1.runConfig)(p.positionals, (0, args_1.has)(p, 'json'), {
+            out: deps.out,
+            err: deps.err,
+            env: deps.env ?? process.env,
+        });
+    }
+    const group = (0, groups_1.findGroup)(cmd);
+    if (cmd !== 'api' && !group)
+        return undefined;
+    const ctx = commandDeps(tail, deps);
+    try {
+        if (cmd === 'api')
+            return await (0, command_1.runApi)(tail, ctx);
+        const orgKnown = (p) => Boolean((0, config_1.setting)('org', (0, args_1.flag)(p, 'org'), ctx.env, ctx.config));
+        const legacy = (p, isVerb) => {
+            if (isVerb)
+                return (group.name === 'domains' && p.positionals[0] === 'verify' && p.positionals.length >= 3);
+            const n = p.positionals.length;
+            switch (group.name) {
+                case 'orgs':
+                    return n === 0;
+                case 'spaces':
+                    return n > 0 || !orgKnown(p);
+                case 'items':
+                    return n > 0;
+                case 'search':
+                    return !orgKnown(p);
+                case 'domains':
+                    return n >= 2;
+                default:
+                    return false;
+            }
+        };
+        return await (0, resource_1.runGroup)(group, tail, ctx, legacy);
+    }
+    catch (e) {
+        for (const l of (0, http_1.formatError)(e))
+            deps.err(l);
+        return 1;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/index.js.map

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

package/dist/commands/resource.d.ts

@@ -0,0 +1,86 @@
+import { type Parsed } from '../api/args';
+import { type CommandDeps } from './context';
+/**
+ * The resource commands — `spaces list`, `webhooks create`, `tokens rotate` —
+ * as DATA over the same operations `forumulate api` calls.
+ *
+ * Each verb names an operationId and how its positionals map; everything else
+ * is derived from the bundled spec, which is why there is no per-command code
+ * for flags: every query parameter of the operation is a flag (`--limit`,
+ * `--state`), every top-level body field is a flag (`--name`, `--visibility`),
+ * and `--data`/`--field` work as they do under `api`. A verb whose operation
+ * disappears from the spec fails `operations.test.ts` rather than at a
+ * customer's terminal.
+ *
+ * Consistent across every group:
+ *  - `--org` (default from `forumulate config set org`), `--space`, `--library`
+ *    accept an id or a slug.
+ *  - `list`/`get`/`create`/`update`/`delete` are the verbs where they apply;
+ *    `delete` asks first (`--yes` to skip; required with no terminal).
+ *  - `--json` prints the API's answer untouched; `--paginate` walks a list.
+ */
+export interface VerbDef {
+    op: string;
+    about: string;
+    /**
+     * Positionals, in order. A path param of the operation fills it
+     * (`spaceId`), a query param becomes that flag (`q`), anything else fills
+     * that BODY field (`name`, `hostname`), so `spaces create Docs` reads as
+     * English. A trailing `...` joins the rest (`search <q...>`).
+     */
+    args?: string[];
+    /** The body field `--file <markdown>` fills (front matter sets title/slug). */
+    markdown?: string;
+    /** With `--file`, send the body through this operation instead (items: PUT …/content). */
+    contentOp?: string;
+    destructive?: boolean;
+    columns?: string[];
+    /** Query defaults the operation needs to be useful here (`include=sections,body`). */
+    query?: Record<string, string>;
+    /** After a create: `--publish` calls this operation on the new id. */
+    publishOp?: string;
+    /** Print this key of the answer as the list (the status board's `incidents`). */
+    pick?: string;
+    /** A path param that may be given by name: listed through `listOp`, matched on `match`. */
+    lookup?: Record<string, {
+        listOp: string;
+        match: string[];
+    }>;
+    /**
+     * The multipart field a positional names a LOCAL FILE for (`assets upload
+     * ./logo.png`): its bytes are sent, not the path as text.
+     */
+    upload?: string;
+    /**
+     * The answer is a file (an SDK archive, a PDF, a CSV export): kept as bytes,
+     * written to `--out <file>` (default: this name), or printed when it is
+     * text and no `--out` is given.
+     */
+    download?: string;
+    /**
+     * Query parameters the route reads but the published spec does not declare
+     * (`DELETE /translation-overrides?locale=&key=`). Sent as written, so the
+     * command works now; the spec gap is the API's to close.
+     */
+    extraQuery?: string[];
+}
+export interface GroupDef {
+    name: string;
+    aliases?: string[];
+    /** Singular, for "delete space docs?". */
+    noun: string;
+    about: string;
+    verbs: Record<string, VerbDef>;
+    /** Verb used when none is given (e.g. `forumulate members` → list). */
+    defaultVerb?: string;
+    /** Positionals with no verb go to the default verb (`search rate limits`). */
+    bareArgs?: boolean;
+}
+export declare function groupHelp(g: GroupDef): string;
+/**
+ * Run `forumulate <group> <verb> …`. Returns undefined when `legacy` claims
+ * the invocation, so the caller can run the older positional form
+ * (`forumulate spaces <orgId>`) that scripts already depend on.
+ */
+export declare function runGroup(g: GroupDef, argv: string[], deps: CommandDeps, legacy?: (parsed: Parsed, isVerb: boolean) => boolean): Promise<number | undefined>;
+//# sourceMappingURL=resource.d.ts.map

package/dist/commands/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/commands/resource.ts"],"names":[],"mappings":"AACA,OAAO,EAAwB,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAOhE,OAAO,EAAiC,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAE5E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAC7D;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAoBD,wBAAgB,SAAS,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAkB7C;AAgBD;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,CAAC,EAAE,QAAQ,EACX,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,EAAE,WAAW,EACjB,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,OAAO,GACpD,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAyC7B"}

package/dist/commands/resource.js

@@ -0,0 +1,314 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.groupHelp = groupHelp;
+exports.runGroup = runGroup;
+const frontmatter_1 = require("../publish/frontmatter");
+const args_1 = require("../api/args");
+const output_1 = require("../api/output");
+const request_1 = require("../api/request");
+const send_1 = require("../api/send");
+const spec_1 = require("../api/spec");
+const config_1 = require("./config");
+const context_1 = require("./context");
+/** Flags the resource layer consumes; everything else is handed to the operation. */
+const OWN = new Set([
+    'org',
+    'space',
+    'library',
+    'yes',
+    'file',
+    'json',
+    'columns',
+    'help',
+    'paginate',
+    'max-pages',
+    'dry-run',
+    'include-headers',
+    'publish',
+    'out',
+]);
+function groupHelp(g) {
+    const lines = [`forumulate ${g.name} — ${g.about}`, '', 'Usage:'];
+    for (const [verb, v] of Object.entries(g.verbs)) {
+        const op = (0, spec_1.findById)(v.op);
+        const args = (v.args ?? []).map((a) => `<${a.replace('...', '…')}>`).join(' ');
+        lines.push(`  forumulate ${g.name} ${verb}${args ? ` ${args}` : ''}${op ? scopeFlags(op, v) : ''}`);
+        lines.push(`      ${v.about}${op ? `  [${op.id}]` : ''}`);
+    }
+    lines.push('', 'Every query parameter and top-level body field of the operation is a flag', '(see `forumulate api describe <operationId>`). --json prints the raw answer,', '--paginate walks a list, --data/--field set a body as under `forumulate api`,', '--dry-run prints the request instead of sending it.');
+    return lines.join('\n');
+}
+function scopeFlags(op, v) {
+    const params = (0, spec_1.pathParams)(op);
+    const own = new Set(v.args ?? []);
+    const parts = [];
+    if (params.includes('orgId') && !own.has('orgId'))
+        parts.push('[--org <org>]');
+    if (params.includes('spaceId') && !own.has('spaceId'))
+        parts.push('--space <space>');
+    if (params.includes('libraryId') && !own.has('libraryId'))
+        parts.push('--library <library>');
+    if (v.markdown)
+        parts.push('[--file <file.md>]');
+    if (v.publishOp)
+        parts.push('[--publish]');
+    if (v.download)
+        parts.push(`[--out ${v.download}]`);
+    if (v.destructive)
+        parts.push('[--yes]');
+    return parts.length ? ` ${parts.join(' ')}` : '';
+}
+/**
+ * Run `forumulate <group> <verb> …`. Returns undefined when `legacy` claims
+ * the invocation, so the caller can run the older positional form
+ * (`forumulate spaces <orgId>`) that scripts already depend on.
+ */
+async function runGroup(g, argv, deps, legacy) {
+    const parsed = (0, args_1.parseArgs)(argv);
+    const [w0, w1, ...more] = parsed.positionals;
+    let verb;
+    let rest = [];
+    if (w0 && w1 && `${w0} ${w1}` in g.verbs) {
+        verb = `${w0} ${w1}`;
+        rest = more;
+    }
+    else if (w0 && w0 in g.verbs) {
+        verb = w0;
+        rest = parsed.positionals.slice(1);
+    }
+    if (w0 === 'help' || ((0, args_1.has)(parsed, 'help') && (!w0 || verb))) {
+        deps.out(groupHelp(g));
+        return 0;
+    }
+    if (legacy?.(parsed, Boolean(verb)))
+        return undefined;
+    if (!verb) {
+        if (g.defaultVerb && (!w0 || g.bareArgs)) {
+            verb = g.defaultVerb;
+            rest = parsed.positionals;
+        }
+        else {
+            const sub = Object.keys(g.verbs).filter((k) => k.startsWith(`${w0} `));
+            deps.err(w0
+                ? `Unknown ${g.name} command: ${w0}${sub.length ? ` (try: ${sub.join(', ')})` : ''}`
+                : `Usage: forumulate ${g.name} <command>`);
+            deps.out(groupHelp(g));
+            return 1;
+        }
+    }
+    try {
+        return await runVerb(g, verb, g.verbs[verb], parsed, rest, deps);
+    }
+    catch (e) {
+        if (e instanceof request_1.UsageError) {
+            deps.err(`Usage: ${e.message}`);
+            return 1;
+        }
+        throw e;
+    }
+}
+const src = (deps) => ({ readFile: deps.readFile, readStdin: deps.readStdin });
+async function runVerb(g, verb, v, parsed, positionals, deps) {
+    const op = (0, spec_1.findById)(v.op);
+    if (!op)
+        throw new request_1.UsageError(`${v.op} is not in this CLI's bundled spec`);
+    const params = (0, spec_1.pathParams)(op);
+    const queryNames = new Set((op.q ?? []).filter((p) => p.in === 'query').map((p) => p.n));
+    const bodyProps = op.b ? (0, spec_1.bodyProperties)(op) : {};
+    const preset = {};
+    const fields = [];
+    const queryArgs = {};
+    const extra = {};
+    for (const name of v.extraQuery ?? []) {
+        const given = (0, args_1.flag)(parsed, name);
+        if (given !== undefined)
+            extra[name] = given;
+    }
+    const place = (name, value) => {
+        if (params.includes(name))
+            preset[name] = value;
+        else if (queryNames.has(name))
+            queryArgs[name] = value;
+        else if (v.extraQuery?.includes(name))
+            extra[name] = value;
+        else if (name === v.upload)
+            fields.push(`${name}=@${value}`);
+        else
+            fields.push(`${name}=${value}`);
+    };
+    const queue = [...positionals];
+    for (const name of v.args ?? []) {
+        if (name.endsWith('...')) {
+            if (queue.length)
+                place(name.slice(0, -3), queue.join(' '));
+            queue.length = 0;
+        }
+        else if (queue.length)
+            place(name, queue.shift());
+    }
+    if (queue.length)
+        throw new request_1.UsageError(`unexpected argument "${queue.join(' ')}". ${usageLine(g, verb, v)}`);
+    const missing = (v.args ?? []).filter((a) => params.includes(a) && !preset[a]);
+    if (missing.length)
+        throw new request_1.UsageError(usageLine(g, verb, v));
+    if (params.includes('orgId') && !preset.orgId) {
+        const org = (0, config_1.setting)('org', (0, args_1.flag)(parsed, 'org'), deps.env, deps.config);
+        if (!org)
+            throw new request_1.UsageError(`${g.name} ${verb} needs --org <id|slug> (or: forumulate config set org <slug>)`);
+        preset.orgId = org;
+    }
+    for (const what of ['space', 'library']) {
+        const param = `${what}Id`;
+        const given = (0, config_1.setting)(what, (0, args_1.flag)(parsed, what), deps.env, deps.config);
+        if (params.includes(param)) {
+            const ref = preset[param] ?? given;
+            if (!ref)
+                throw new request_1.UsageError(`${g.name} ${verb} needs --${what} <id|slug>`);
+            preset[param] = await (0, context_1.resolveChild)(deps, what, preset.orgId, ref);
+        }
+        else if (param in bodyProps && (0, args_1.flag)(parsed, what) && preset.orgId) {
+            // `webhooks create --space docs`: the space is a body field there.
+            fields.push(`${param}=${await (0, context_1.resolveChild)(deps, what, preset.orgId, (0, args_1.flag)(parsed, what))}`);
+        }
+    }
+    for (const [param, how] of Object.entries(v.lookup ?? {}))
+        if (preset[param])
+            preset[param] = await lookup(deps, how, preset, preset[param]);
+    const forwarded = {
+        positionals: [],
+        flags: new Map([...parsed.flags].filter(([k]) => !OWN.has(k) && !v.extraQuery?.includes(k))),
+    };
+    for (const [k, val] of Object.entries({ ...v.query, ...queryArgs }))
+        if (!forwarded.flags.has(k) || k in queryArgs)
+            forwarded.flags.set(k, [val]);
+    // `--file page.md`: the body, and title/slug from its front matter unless given.
+    const file = (0, args_1.flag)(parsed, 'file');
+    let content;
+    if (file && !v.markdown)
+        throw new request_1.UsageError(`${g.name} ${verb} takes no --file`);
+    if (file) {
+        const { data, body } = (0, frontmatter_1.splitFront)(String(deps.readFile(file)));
+        content = body;
+        for (const k of ['title', 'slug']) {
+            const given = forwarded.flags.has(k) || fields.some((f) => f.startsWith(`${k}=`));
+            if (!given && typeof data[k] === 'string' && k in bodyProps)
+                fields.push(`${k}=${data[k]}`);
+        }
+    }
+    if (content !== undefined && !v.contentOp)
+        fields.push(`${v.markdown}=${content}`);
+    if (fields.length)
+        forwarded.flags.set('field', [...fields, ...(forwarded.flags.get('field') ?? [])]);
+    const requests = [];
+    if (content !== undefined && v.contentOp) {
+        const cop = (0, spec_1.findById)(v.contentOp);
+        const contentFlags = {
+            positionals: [],
+            flags: new Map([['field', [`${v.markdown}=${content}`]]]),
+        };
+        requests.push((await (0, request_1.planRequest)(cop, contentFlags, [], src(deps), preset)).request);
+    }
+    // With `--file` and nothing else to change, the content write is the whole command.
+    if (!(v.contentOp && content !== undefined && forwarded.flags.size === 0))
+        requests.push((await (0, request_1.planRequest)(op, forwarded, [], src(deps), preset)).request);
+    const main = requests.at(-1);
+    if (Object.keys(extra).length)
+        main.query = { ...main.query, ...extra };
+    if (v.download)
+        main.raw = true;
+    if ((0, args_1.has)(parsed, 'dry-run')) {
+        for (const r of requests)
+            (0, send_1.printRequest)(deps.http, r, deps);
+        return 0;
+    }
+    if (v.destructive) {
+        const target = Object.entries(preset)
+            .filter(([k]) => k !== 'orgId')
+            .at(-1)?.[1] ?? preset.orgId;
+        if (!(await (0, context_1.confirm)(deps, (0, args_1.has)(parsed, 'yes'), `${verb} ${g.noun} ${target}?`)))
+            return 1;
+    }
+    const json = (0, args_1.has)(parsed, 'json');
+    const opts = {
+        json,
+        paginate: (0, args_1.has)(parsed, 'paginate'),
+        maxPages: Number((0, args_1.flag)(parsed, 'max-pages') ?? 1000),
+        columns: (0, args_1.flag)(parsed, 'columns')?.split(',') ?? v.columns,
+        includeHeaders: (0, args_1.has)(parsed, 'include-headers'),
+    };
+    if (v.download)
+        return download(deps, main, v.download, (0, args_1.flag)(parsed, 'out'));
+    let result;
+    for (const request of requests) {
+        if (v.pick && !opts.paginate) {
+            const res = await deps.http.send(request);
+            result = res.data;
+            const picked = res.data?.[v.pick];
+            (0, send_1.print)(json ? picked : { [v.pick]: picked ?? [] }, opts, deps);
+        }
+        else
+            result = await (0, send_1.sendAndPrint)(deps.http, request, opts, deps);
+    }
+    if (v.publishOp && (0, args_1.has)(parsed, 'publish')) {
+        const id = createdId(result);
+        const pub = (0, spec_1.findById)(v.publishOp);
+        if (!id || !pub)
+            throw new Error('Created, but the answer carried no id to publish.');
+        const last = (0, spec_1.pathParams)(pub).at(-1);
+        const { request } = await (0, request_1.planRequest)(pub, { positionals: [], flags: new Map() }, [], src(deps), { ...preset, [last]: id });
+        await deps.http.send(request);
+        if (!json)
+            deps.out(`Published ${id}.`);
+    }
+    return 0;
+}
+/**
+ * A file answer: to `--out`, or to the terminal when it is text. A binary
+ * answer printed to a terminal is noise, and to a pipe it is corrupted by the
+ * line handling, so with no `--out` it lands in the suggested file instead.
+ */
+async function download(deps, request, suggested, out) {
+    const res = await deps.http.send(request);
+    const bytes = res.data;
+    const type = res.headers.get('content-type') ?? '';
+    const text = /^text\/|json|xml|csv|svg|markdown/.test(type);
+    if (!out && text) {
+        deps.out(bytes.toString('utf8').replace(/\n$/, ''));
+        return 0;
+    }
+    const file = out ?? suggested;
+    deps.writeFile(file, bytes);
+    deps.err(`Wrote ${bytes.length} bytes to ${file}.`);
+    return 0;
+}
+/** The id of what a create made: `data` (the uniform create envelope), else the named resource. */
+function createdId(result) {
+    const r = result;
+    const data = r?.data;
+    if (data?.id)
+        return data.id;
+    for (const v of Object.values(r ?? {}))
+        if (v && typeof v === 'object' && typeof v.id === 'string')
+            return v.id;
+    return undefined;
+}
+/** `tokens revoke ci-deploy` → the token whose name is `ci-deploy`. */
+async function lookup(deps, how, preset, ref) {
+    if ((0, context_1.isUuid)(ref))
+        return ref;
+    const listOp = (0, spec_1.findById)(how.listOp);
+    if (!listOp)
+        return ref;
+    const { request } = await (0, request_1.planRequest)(listOp, { positionals: [], flags: new Map() }, [], src(deps), preset);
+    const rows = ((0, output_1.rowsOf)((await deps.http.send(request)).data)?.rows ?? []);
+    const hits = rows.filter((r) => r.id === ref || how.match.some((m) => String(r[m] ?? '').toLowerCase() === ref.toLowerCase()));
+    if (hits.length === 1)
+        return String(hits[0].id);
+    if (hits.length > 1)
+        throw new request_1.UsageError(`"${ref}" matches ${hits.length}; pass the id`);
+    return ref; // Not a name we know: let the API answer for the id as given.
+}
+function usageLine(g, verb, v) {
+    return `forumulate ${g.name} ${verb}${(v.args ?? []).map((a) => ` <${a.replace('...', '…')}>`).join('')}`;
+}
+//# sourceMappingURL=resource.js.map