@bctrl/cli 0.1.0 → 0.1.3

package/dist/commands/shared/help.d.ts

@@ -0,0 +1,24 @@
+import type { Command } from 'commander';
+import { type CliHelpCommandId } from '../../generated/help.js';
+export type CommandHelpField = {
+    name: string;
+    type: string;
+    required?: boolean;
+    description?: string;
+};
+export type CommandHelpFlag = {
+    name: string;
+    value?: string;
+    description: string;
+    mapsTo?: string;
+};
+export type CommandHelpSpec = {
+    purpose: string;
+    flags?: CommandHelpFlag[];
+    input?: CommandHelpField[];
+    output?: CommandHelpField[];
+    examples?: string[];
+    next?: string[];
+};
+export declare function addStructuredHelp(command: Command, spec: CommandHelpSpec): Command;
+export declare function addCliHelp(command: Command, commandId: CliHelpCommandId): Command;

package/dist/commands/shared/help.js

@@ -0,0 +1,72 @@
+import { CLI_HELP_COMMANDS } from '../../generated/help.js';
+export function addStructuredHelp(command, spec) {
+    command.addHelpText('after', `\n${renderStructuredHelp(spec)}`);
+    return command;
+}
+export function addCliHelp(command, commandId) {
+    return addStructuredHelp(command, toCommandHelpSpec(CLI_HELP_COMMANDS[commandId]));
+}
+function toCommandHelpSpec(help) {
+    const raw = help;
+    return {
+        purpose: raw.summary,
+        flags: raw.flags?.map((flag) => ({ ...flag })),
+        input: raw.input?.fields.map((field) => ({ ...field })),
+        output: raw.output?.fields.map((field) => ({ ...field })),
+        examples: raw.examples?.map(formatHelpItem).filter((value) => Boolean(value)),
+        next: raw.next?.map(formatHelpItem).filter((value) => Boolean(value)),
+    };
+}
+function formatHelpItem(value) {
+    if (typeof value === 'string')
+        return value;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (typeof record.command === 'string')
+        return record.command;
+    if (typeof record.topic === 'string')
+        return record.topic;
+    return undefined;
+}
+function renderStructuredHelp(spec) {
+    const sections = [
+        renderPurpose(spec.purpose),
+        spec.flags && spec.flags.length > 0 ? renderFlags(spec.flags) : '',
+        spec.input && spec.input.length > 0 ? renderFields('Input', spec.input) : '',
+        spec.output && spec.output.length > 0 ? renderFields('Output', spec.output) : '',
+        spec.examples && spec.examples.length > 0 ? renderList('Examples', spec.examples) : '',
+        spec.next && spec.next.length > 0 ? renderList('Next', spec.next) : '',
+    ].filter(Boolean);
+    return sections.join('\n\n');
+}
+function renderPurpose(purpose) {
+    return `Purpose:\n  ${purpose}`;
+}
+function renderFlags(flags) {
+    const rows = flags.map((flag) => {
+        const left = [flag.name, flag.value].filter(Boolean).join(' ');
+        const suffix = flag.mapsTo ? ` Maps to ${flag.mapsTo}.` : '';
+        return { left, right: `${flag.description}${suffix}` };
+    });
+    return renderRows('Flags', rows);
+}
+function renderFields(title, fields) {
+    const rows = fields.map((field) => ({
+        left: field.name,
+        right: [
+            field.type,
+            field.required === true ? 'required' : 'optional',
+            field.description,
+        ].filter(Boolean).join(' '),
+    }));
+    return renderRows(title, rows);
+}
+function renderRows(title, rows) {
+    const width = Math.max(...rows.map((row) => row.left.length));
+    const lines = rows.map((row) => `  ${row.left.padEnd(width)}  ${row.right}`);
+    return `${title}:\n${lines.join('\n')}`;
+}
+function renderList(title, lines) {
+    return `${title}:\n${lines.map((line) => `  ${line}`).join('\n')}`;
+}

package/dist/commands/shared/io.js

@@ -8,7 +8,7 @@ export async function readText(path) {
     }
     return readFile(path, 'utf8');
 }
-export async function readJsonFile(path, label = '--from-file') {
+export async function readJsonFile(path, label = '--input') {
     const text = await readText(path);
     try {
         return JSON.parse(text);

package/dist/commands/shared/rest.d.ts

@@ -16,7 +16,7 @@ export declare function requestAndPrint(deps: ApiDeps, method: ClientMethod, pat
     body?: unknown;
     output?: OutputFlags;
 }): Promise<void>;
-export declare function bodyFromFileOption(path: string | undefined): Promise<unknown>;
+export declare function bodyFromInputOption(path: string | undefined): Promise<unknown>;
 export declare function createListCommand(factory: Factory, config: {
     name?: string;
     description: string;

package/dist/commands/shared/rest.js

@@ -12,7 +12,7 @@ export function addPaginationFlags(command) {
         .option('--cursor <cursor>', 'Pagination cursor');
 }
 export function addJsonBodyFlag(command) {
-    return command.option('--from-file <path>', 'Read JSON request body from file, or - for stdin');
+    return command.option('--input <path>', 'Read JSON request body from file, or - for stdin');
 }
 export async function requestAndPrint(deps, method, path, options) {
     const client = await deps.apiClient();
@@ -27,7 +27,7 @@ export async function requestAndPrint(deps, method, path, options) {
                     : await client.delete(path, options);
     await outputData(deps.io, result, options?.output);
 }
-export async function bodyFromFileOption(path) {
+export async function bodyFromInputOption(path) {
     return path ? readJsonFile(path) : {};
 }
 export function createListCommand(factory, config) {
@@ -89,7 +89,7 @@ export function createJsonBodyCommand(factory, config) {
         const args = {};
         for (let i = 0; i < argNames.length; i += 1)
             args[argNames[i]] = String(actionArgs[i]);
-        const body = config.body ? await config.body(args, options) : await bodyFromFileOption(String(options.fromFile ?? ''));
+        const body = config.body ? await config.body(args, options) : await bodyFromInputOption(String(options.input ?? ''));
         await requestAndPrint(factory, config.method, pathTemplate(config.path, args), {
             body,
             query: config.query ? config.query(args, options) : undefined,

package/dist/commands/space/index.js

@@ -19,10 +19,10 @@ export function createSpaceCommand(factory) {
             .option('--name <name>', 'Space name')
             .option('--region <region>', 'Space region')
             .option('--subaccount-id <id>', 'Subaccount id')
-            .option('--from-file <path>', 'Read JSON request body from file, or - for stdin'),
+            .option('--input <path>', 'Read JSON request body from file, or - for stdin'),
         body: async (_args, options) => {
-            if (typeof options.fromFile === 'string')
-                return readJsonFile(options.fromFile);
+            if (typeof options.input === 'string')
+                return readJsonFile(options.input);
             return {
                 name: options.name,
                 region: options.region,
@@ -38,10 +38,10 @@ export function createSpaceCommand(factory) {
         argNames: ['id'],
         configure: (cmd) => cmd
             .option('--name <name>', 'Space name')
-            .option('--from-file <path>', 'Read JSON request body from file, or - for stdin'),
+            .option('--input <path>', 'Read JSON request body from file, or - for stdin'),
         body: async (_args, options) => {
-            if (typeof options.fromFile === 'string')
-                return readJsonFile(options.fromFile);
+            if (typeof options.input === 'string')
+                return readJsonFile(options.input);
             return { name: options.name };
         },
     }));

package/dist/commands/subaccount/index.js

@@ -23,10 +23,10 @@ export function createSubaccountCommand(factory) {
             .option('--name <name>', 'Subaccount name')
             .option('--external-id <id>', 'External id')
             .option('--metadata-file <path>', 'Metadata JSON file')
-            .option('--from-file <path>', 'Read full JSON request body from file, or - for stdin'),
+            .option('--input <path>', 'Read full JSON request body from file, or - for stdin'),
         body: async (_args, options) => {
-            if (typeof options.fromFile === 'string')
-                return readJsonFile(options.fromFile);
+            if (typeof options.input === 'string')
+                return readJsonFile(options.input);
             return {
                 name: options.name,
                 externalId: options.externalId,
@@ -46,10 +46,10 @@ export function createSubaccountCommand(factory) {
             .option('--name <name>', 'Subaccount name')
             .option('--external-id <id>', 'External id')
             .option('--metadata-file <path>', 'Metadata JSON file')
-            .option('--from-file <path>', 'Read full JSON request body from file, or - for stdin'),
+            .option('--input <path>', 'Read full JSON request body from file, or - for stdin'),
         body: async (_args, options) => {
-            if (typeof options.fromFile === 'string')
-                return readJsonFile(options.fromFile);
+            if (typeof options.input === 'string')
+                return readJsonFile(options.input);
             return {
                 name: options.name,
                 externalId: options.externalId,
@@ -112,10 +112,10 @@ function createSubaccountLimitsCommand(factory) {
             .option('--max-spaces <number>', 'Maximum spaces')
             .option('--max-active-runs <number>', 'Maximum active runs')
             .option('--monthly-spend-micro-usd <number>', 'Monthly spend limit in micro USD')
-            .option('--from-file <path>', 'Read full JSON request body from file, or - for stdin'),
+            .option('--input <path>', 'Read full JSON request body from file, or - for stdin'),
         body: async (_args, options) => {
-            if (typeof options.fromFile === 'string')
-                return readJsonFile(options.fromFile);
+            if (typeof options.input === 'string')
+                return readJsonFile(options.input);
             return {
                 spaces: options.maxSpaces ? { max: Number(options.maxSpaces) } : undefined,
                 runs: options.maxActiveRuns ? { maxActive: Number(options.maxActiveRuns) } : undefined,
@@ -145,10 +145,10 @@ function createSubaccountKeyCommand(factory) {
         argNames: ['id'],
         configure: (cmd) => cmd
             .option('--name <name>', 'API key name')
-            .option('--from-file <path>', 'Read full JSON request body from file, or - for stdin'),
+            .option('--input <path>', 'Read full JSON request body from file, or - for stdin'),
         body: async (_args, options) => {
-            if (typeof options.fromFile === 'string')
-                return readJsonFile(options.fromFile);
+            if (typeof options.input === 'string')
+                return readJsonFile(options.input);
             return { name: options.name };
         },
     }));

package/dist/commands/vault/index.js

@@ -63,10 +63,10 @@ function createVaultSetCommand(factory) {
             .option('--label <label>', 'Display label')
             .option('--origin <origin...>', 'Allowed origin')
             .option('--origin-pattern <pattern...>', 'Allowed origin pattern')
-            .option('--from-file <path>', 'Read full JSON request body from file, or - for stdin'),
+            .option('--input <path>', 'Read full JSON request body from file, or - for stdin'),
         body: async (args, options) => {
-            if (typeof options.fromFile === 'string')
-                return readJsonFile(options.fromFile);
+            if (typeof options.input === 'string')
+                return readJsonFile(options.input);
             const password = typeof options.passwordFromFile === 'string'
                 ? (await readText(options.passwordFromFile)).trimEnd()
                 : options.password;

package/dist/config/auth-store.d.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 export declare const StoredWhoamiSchema: z.ZodObject<{
     authenticated: z.ZodLiteral<true>;
+    email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     keyKind: z.ZodEnum<{
         user: "user";
         subaccount: "subaccount";
@@ -17,6 +18,7 @@ export declare const StoredAuthSchema: z.ZodObject<{
     token: z.ZodString;
     whoami: z.ZodObject<{
         authenticated: z.ZodLiteral<true>;
+        email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         keyKind: z.ZodEnum<{
             user: "user";
             subaccount: "subaccount";

package/dist/config/auth-store.js

@@ -6,6 +6,7 @@ const DEFAULT_AUTH_FILE_NAME = 'auth.json';
 export const StoredWhoamiSchema = z
     .object({
     authenticated: z.literal(true),
+    email: z.string().email().nullable().optional(),
     keyKind: z.enum(['user', 'subaccount']),
     organizationId: z.string().min(1),
     subaccountId: z.string().min(1).nullable().optional(),

package/dist/config/config.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { readStoredAuth } from './auth-store.js';
-const DEFAULT_API_BASE_URL = 'https://api.bctrl.ai/v2';
+const DEFAULT_API_BASE_URL = 'https://api.bctrl.ai/v1';
 const EnvSchema = z.object({
     BCTRL_API_KEY: z.string().optional(),
     BCTRL_API_URL: z.string().url().optional(),

package/dist/factory.js

@@ -7,7 +7,7 @@ export function createFactory(options) {
         return configPromise;
     };
     return {
-        version: options.version ?? '0.1.0',
+        version: options.version ?? '0.1.3',
         io: options.io,
         config,
         apiClient: async () => createBctrlApiClient(await config()),

package/dist/generated/help.d.ts

@@ -0,0 +1,134 @@
+export declare const CLI_HELP_COMMANDS: {
+    readonly "runtime.create": {
+        readonly kind: "command";
+        readonly command: "runtime.create";
+        readonly summary: "Create a browser runtime definition. This does not start the browser.";
+        readonly usage: "bctrl runtime create [flags]";
+        readonly flags: readonly [{
+            readonly name: "--space";
+            readonly value: "<id>";
+            readonly description: "Owning space id.";
+            readonly mapsTo: "input.spaceId";
+        }, {
+            readonly name: "--name";
+            readonly value: "<name>";
+            readonly description: "Runtime name.";
+            readonly mapsTo: "input.name";
+        }, {
+            readonly name: "--config-file";
+            readonly value: "<path>";
+            readonly description: "Read runtime config JSON from a file.";
+            readonly mapsTo: "input.config";
+        }, {
+            readonly name: "--metadata-file";
+            readonly value: "<path>";
+            readonly description: "Read runtime metadata JSON from a file.";
+            readonly mapsTo: "input.metadata";
+        }, {
+            readonly name: "--input";
+            readonly value: "<path>";
+            readonly description: "Read the full JSON request body from a file, or - for stdin.";
+        }];
+        readonly input: {
+            readonly fields: readonly [{
+                readonly name: "spaceId";
+                readonly type: "uuid";
+                readonly required: true;
+            }, {
+                readonly name: "type";
+                readonly type: "\"browser\"";
+                readonly values: readonly ["\"browser\""];
+                readonly required: true;
+            }, {
+                readonly name: "name";
+                readonly type: "string";
+                readonly required: false;
+            }, {
+                readonly name: "metadata";
+                readonly type: "object";
+                readonly required: false;
+            }, {
+                readonly name: "config";
+                readonly type: "object";
+                readonly required: false;
+            }];
+        };
+        readonly output: {
+            readonly fields: readonly [{
+                readonly name: "id";
+                readonly type: "uuid";
+                readonly required: true;
+            }, {
+                readonly name: "name";
+                readonly type: "string";
+                readonly required: true;
+            }, {
+                readonly name: "type";
+                readonly type: "\"browser\" | \"desktop\" | \"spreadsheet\"";
+                readonly values: readonly ["\"browser\"", "\"desktop\"", "\"spreadsheet\""];
+                readonly required: true;
+            }, {
+                readonly name: "status";
+                readonly type: "\"active\" | \"stopped\" | \"failed\"";
+                readonly values: readonly ["\"active\"", "\"stopped\"", "\"failed\""];
+                readonly required: true;
+            }, {
+                readonly name: "activeRunId";
+                readonly type: "uuid | null";
+                readonly required: true;
+            }, {
+                readonly name: "createdAt";
+                readonly type: "string";
+                readonly required: true;
+            }, {
+                readonly name: "updatedAt";
+                readonly type: "string";
+                readonly required: true;
+            }, {
+                readonly name: "config";
+                readonly type: "object";
+                readonly required: false;
+            }, {
+                readonly name: "metadata";
+                readonly type: "object | null";
+                readonly required: false;
+            }];
+        };
+        readonly examples: readonly [{
+            readonly command: "bctrl runtime create --space sp_123 --name checkout-test";
+        }, {
+            readonly command: "bctrl runtime create --input runtime.json";
+        }];
+        readonly next: readonly [{
+            readonly command: "bctrl runtime start <runtimeId>";
+        }];
+    };
+    readonly "runtime.start": {
+        readonly kind: "command";
+        readonly command: "runtime.start";
+        readonly summary: "Start a runtime and open its active run.";
+        readonly usage: "bctrl runtime start <runtimeId>";
+        readonly output: {
+            readonly fields: readonly [{
+                readonly name: "runtime";
+                readonly type: "object";
+                readonly required: true;
+            }, {
+                readonly name: "run";
+                readonly type: "object";
+                readonly required: true;
+            }, {
+                readonly name: "browser";
+                readonly type: "object";
+                readonly required: true;
+            }];
+        };
+        readonly examples: readonly [{
+            readonly command: "bctrl runtime start rt_123";
+        }];
+        readonly next: readonly [{
+            readonly command: "bctrl run events <runId>";
+        }];
+    };
+};
+export type CliHelpCommandId = keyof typeof CLI_HELP_COMMANDS;

package/dist/generated/help.js

@@ -0,0 +1,179 @@
+// Generated by scripts/generate/cli-help.mjs. Do not edit by hand.
+export const CLI_HELP_COMMANDS = {
+    "runtime.create": {
+        "kind": "command",
+        "command": "runtime.create",
+        "summary": "Create a browser runtime definition. This does not start the browser.",
+        "usage": "bctrl runtime create [flags]",
+        "flags": [
+            {
+                "name": "--space",
+                "value": "<id>",
+                "description": "Owning space id.",
+                "mapsTo": "input.spaceId"
+            },
+            {
+                "name": "--name",
+                "value": "<name>",
+                "description": "Runtime name.",
+                "mapsTo": "input.name"
+            },
+            {
+                "name": "--config-file",
+                "value": "<path>",
+                "description": "Read runtime config JSON from a file.",
+                "mapsTo": "input.config"
+            },
+            {
+                "name": "--metadata-file",
+                "value": "<path>",
+                "description": "Read runtime metadata JSON from a file.",
+                "mapsTo": "input.metadata"
+            },
+            {
+                "name": "--input",
+                "value": "<path>",
+                "description": "Read the full JSON request body from a file, or - for stdin."
+            }
+        ],
+        "input": {
+            "fields": [
+                {
+                    "name": "spaceId",
+                    "type": "uuid",
+                    "required": true
+                },
+                {
+                    "name": "type",
+                    "type": "\"browser\"",
+                    "values": [
+                        "\"browser\""
+                    ],
+                    "required": true
+                },
+                {
+                    "name": "name",
+                    "type": "string",
+                    "required": false
+                },
+                {
+                    "name": "metadata",
+                    "type": "object",
+                    "required": false
+                },
+                {
+                    "name": "config",
+                    "type": "object",
+                    "required": false
+                }
+            ]
+        },
+        "output": {
+            "fields": [
+                {
+                    "name": "id",
+                    "type": "uuid",
+                    "required": true
+                },
+                {
+                    "name": "name",
+                    "type": "string",
+                    "required": true
+                },
+                {
+                    "name": "type",
+                    "type": "\"browser\" | \"desktop\" | \"spreadsheet\"",
+                    "values": [
+                        "\"browser\"",
+                        "\"desktop\"",
+                        "\"spreadsheet\""
+                    ],
+                    "required": true
+                },
+                {
+                    "name": "status",
+                    "type": "\"active\" | \"stopped\" | \"failed\"",
+                    "values": [
+                        "\"active\"",
+                        "\"stopped\"",
+                        "\"failed\""
+                    ],
+                    "required": true
+                },
+                {
+                    "name": "activeRunId",
+                    "type": "uuid | null",
+                    "required": true
+                },
+                {
+                    "name": "createdAt",
+                    "type": "string",
+                    "required": true
+                },
+                {
+                    "name": "updatedAt",
+                    "type": "string",
+                    "required": true
+                },
+                {
+                    "name": "config",
+                    "type": "object",
+                    "required": false
+                },
+                {
+                    "name": "metadata",
+                    "type": "object | null",
+                    "required": false
+                }
+            ]
+        },
+        "examples": [
+            {
+                "command": "bctrl runtime create --space sp_123 --name checkout-test"
+            },
+            {
+                "command": "bctrl runtime create --input runtime.json"
+            }
+        ],
+        "next": [
+            {
+                "command": "bctrl runtime start <runtimeId>"
+            }
+        ]
+    },
+    "runtime.start": {
+        "kind": "command",
+        "command": "runtime.start",
+        "summary": "Start a runtime and open its active run.",
+        "usage": "bctrl runtime start <runtimeId>",
+        "output": {
+            "fields": [
+                {
+                    "name": "runtime",
+                    "type": "object",
+                    "required": true
+                },
+                {
+                    "name": "run",
+                    "type": "object",
+                    "required": true
+                },
+                {
+                    "name": "browser",
+                    "type": "object",
+                    "required": true
+                }
+            ]
+        },
+        "examples": [
+            {
+                "command": "bctrl runtime start rt_123"
+            }
+        ],
+        "next": [
+            {
+                "command": "bctrl run events <runId>"
+            }
+        ]
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bctrl/cli",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "BCTRL command-line interface",
   "type": "module",
   "bin": {
@@ -15,15 +15,6 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "clean": "rm -rf dist",
-    "build": "pnpm run clean && tsc -p tsconfig.json",
-    "dev": "tsx src/bin/bctrl.ts",
-    "prepack": "pnpm run build",
-    "test": "tsx --test \"tests/**/*.test.ts\"",
-    "typecheck": "tsc --noEmit",
-    "typecheck:tests": "tsc --noEmit -p tests/tsconfig.json"
-  },
   "keywords": [
     "bctrl",
     "cli",
@@ -32,7 +23,6 @@
   ],
   "author": "",
   "license": "ISC",
-  "packageManager": "pnpm@10.12.4",
   "dependencies": {
     "commander": "^14.0.3",
     "handlebars": "^4.7.9",
@@ -43,5 +33,13 @@
     "@types/node": "^25.7.0",
     "tsx": "^4.21.0",
     "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "pnpm run clean && tsc -p tsconfig.json",
+    "dev": "tsx src/bin/bctrl.ts",
+    "test": "tsx --test \"tests/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit",
+    "typecheck:tests": "tsc --noEmit -p tests/tsconfig.json"
   }
-}
+}