@bctrl/cli 0.1.0 → 0.1.2

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.2',
         io: options.io,
         config,
         apiClient: async () => createBctrlApiClient(await config()),

package/dist/generated/help.d.ts

@@ -0,0 +1,205 @@
+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 examples: readonly [{
+            readonly command: "bctrl runtime start rt_123";
+        }];
+        readonly next: readonly [{
+            readonly command: "bctrl runtime connection create <runtimeId>";
+        }];
+    };
+    readonly "runtime.connection.create": {
+        readonly kind: "command";
+        readonly command: "runtime.connection.create";
+        readonly summary: "Create a short-lived CDP connection lease for a started runtime.";
+        readonly usage: "bctrl runtime connection create <runtimeId> [flags]";
+        readonly flags: readonly [{
+            readonly name: "--protocol";
+            readonly value: "<protocol>";
+            readonly description: "Connection protocol. Defaults to cdp.";
+            readonly mapsTo: "input.protocol";
+        }, {
+            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: "protocol";
+                readonly type: "\"cdp\"";
+                readonly values: readonly ["\"cdp\""];
+                readonly required: true;
+            }, {
+                readonly name: "options";
+                readonly type: "object";
+                readonly required: false;
+            }];
+        };
+        readonly output: {
+            readonly fields: readonly [{
+                readonly name: "id";
+                readonly type: "uuid";
+                readonly required: true;
+            }, {
+                readonly name: "protocol";
+                readonly type: "\"cdp\" | \"cua\" | \"rdp\" | \"vnc\" | \"mcp\" | \"http\"";
+                readonly values: readonly ["\"cdp\"", "\"cua\"", "\"rdp\"", "\"vnc\"", "\"mcp\"", "\"http\""];
+                readonly required: true;
+            }, {
+                readonly name: "status";
+                readonly type: "\"active\" | \"expired\" | \"revoked\" | \"closed\"";
+                readonly values: readonly ["\"active\"", "\"expired\"", "\"revoked\"", "\"closed\""];
+                readonly required: true;
+            }, {
+                readonly name: "runId";
+                readonly type: "uuid";
+                readonly required: true;
+            }, {
+                readonly name: "createdAt";
+                readonly type: "datetime";
+                readonly required: true;
+            }, {
+                readonly name: "expiresAt";
+                readonly type: "datetime | null";
+                readonly required: true;
+            }, {
+                readonly name: "closedAt";
+                readonly type: "datetime | null";
+                readonly required: false;
+            }, {
+                readonly name: "revokedAt";
+                readonly type: "datetime | null";
+                readonly required: false;
+            }, {
+                readonly name: "endpoint";
+                readonly type: "object";
+                readonly required: true;
+            }];
+        };
+        readonly examples: readonly [{
+            readonly command: "bctrl runtime connection create rt_123";
+        }];
+        readonly next: readonly [{
+            readonly command: "bctrl run events <runId>";
+        }];
+    };
+};
+export type CliHelpCommandId = keyof typeof CLI_HELP_COMMANDS;