@bctrl/cli 0.1.0

package/dist/commands/auth/token.d.ts

@@ -0,0 +1,11 @@
+import { Command } from 'commander';
+import type { BctrlConfig } from '../../config/config.js';
+import type { Factory } from '../../factory.js';
+import type { IOStreams } from '../../io/streams.js';
+export type AuthTokenOptions = {
+    io: IOStreams;
+    config: () => Promise<BctrlConfig>;
+    reveal?: boolean;
+};
+export declare function createAuthTokenCommand(factory: Factory, run?: (options: AuthTokenOptions) => Promise<void>): Command;
+export declare function authTokenRun(options: AuthTokenOptions): Promise<void>;

package/dist/commands/auth/token.js

@@ -0,0 +1,24 @@
+import { Command } from 'commander';
+import { AuthError, CliError } from '../../runtime/errors.js';
+export function createAuthTokenCommand(factory, run = authTokenRun) {
+    return new Command('token')
+        .description('Print the active BCTRL API key')
+        .option('--reveal', 'Allow printing the API key to a terminal')
+        .action(async (options) => {
+        await run({
+            io: factory.io,
+            config: factory.config,
+            reveal: options.reveal,
+        });
+    });
+}
+export async function authTokenRun(options) {
+    const config = await options.config();
+    if (!config.activeToken) {
+        throw new AuthError();
+    }
+    if (options.io.isStdoutTTY() && options.reveal !== true) {
+        throw new CliError('Refusing to print API key to a terminal without --reveal');
+    }
+    options.io.writeOut(`${config.activeToken.token}\n`);
+}

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

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import type { Factory } from '../../factory.js';
+export declare function createBrowserCommand(factory: Factory): Command;

package/dist/commands/browser/index.js

@@ -0,0 +1,53 @@
+import { Command } from 'commander';
+import { readBlob, readJsonFile } from '../shared/io.js';
+import { addOutputFlags, outputData } from '../shared/output.js';
+import { createDeleteCommand, createJsonBodyCommand, createListCommand, createViewCommand, } from '../shared/rest.js';
+export function createBrowserCommand(factory) {
+    const command = new Command('browser').description('Manage browser resources');
+    command.addCommand(createBrowserExtensionCommand(factory));
+    return command;
+}
+function createBrowserExtensionCommand(factory) {
+    const command = new Command('extension').description('Manage browser extensions');
+    command.addCommand(createListCommand(factory, {
+        description: 'List browser extensions',
+        path: '/browser-extensions',
+        configure: (cmd) => cmd,
+    }));
+    command.addCommand(createViewCommand(factory, {
+        description: 'View a browser extension',
+        path: '/browser-extensions/{id}',
+    }));
+    command.addCommand(addOutputFlags(new Command('upload')
+        .description('Upload a browser extension package')
+        .argument('<path>'))
+        .action(async (path, options) => {
+        const client = await factory.apiClient();
+        const file = await readBlob(path);
+        const result = await client.uploadFile('/browser-extensions/upload', {
+            file: file.blob,
+            fileName: file.fileName,
+        });
+        await outputData(factory.io, result, options);
+    }));
+    command.addCommand(createJsonBodyCommand(factory, {
+        name: 'import',
+        description: 'Import a browser extension from a URL',
+        method: 'post',
+        path: '/browser-extensions/import',
+        configure: (cmd) => cmd
+            .option('--url <url>', 'Extension URL')
+            .option('--from-file <path>', 'Read full JSON request body from file, or - for stdin'),
+        body: async (_args, options) => {
+            if (typeof options.fromFile === 'string') {
+                return readJsonFile(options.fromFile);
+            }
+            return { source: { type: 'url', url: options.url } };
+        },
+    }));
+    command.addCommand(createDeleteCommand(factory, {
+        description: 'Delete a browser extension',
+        path: '/browser-extensions/{id}',
+    }));
+    return command;
+}

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

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import type { Factory } from '../../factory.js';
+export declare function createFileCommand(factory: Factory): Command;

package/dist/commands/file/index.js

@@ -0,0 +1,88 @@
+import { Command } from 'commander';
+import { readBlob, readJsonFile, writeBinary } from '../shared/io.js';
+import { parsePositiveInteger } from '../shared/options.js';
+import { addOutputFlags, outputData } from '../shared/output.js';
+import { createDeleteCommand, createJsonBodyCommand, createListCommand, createViewCommand, } from '../shared/rest.js';
+export function createFileCommand(factory) {
+    const command = new Command('file').description('Upload, download, and manage BCTRL files');
+    command.addCommand(createListCommand(factory, {
+        description: 'List files',
+        path: '/files',
+        configure: (cmd) => cmd
+            .option('--space <id>', 'Filter by space id')
+            .option('--source <source>', 'Filter by file source')
+            .option('--prefix <path>', 'Filter by path prefix')
+            .option('--query <text>', 'Search query')
+            .option('-L, --limit <number>', 'Maximum number of results to return', parsePositiveInteger)
+            .option('--cursor <cursor>', 'Pagination cursor'),
+        query: (options) => ({
+            spaceId: typeof options.space === 'string' ? options.space : undefined,
+            source: typeof options.source === 'string' ? options.source : undefined,
+            prefix: typeof options.prefix === 'string' ? options.prefix : undefined,
+            query: typeof options.query === 'string' ? options.query : undefined,
+            limit: typeof options.limit === 'number' ? options.limit : undefined,
+            cursor: typeof options.cursor === 'string' ? options.cursor : undefined,
+        }),
+    }));
+    command.addCommand(createViewCommand(factory, {
+        description: 'View file metadata',
+        path: '/files/{fileId}',
+        argName: 'fileId',
+    }));
+    command.addCommand(addOutputFlags(new Command('upload')
+        .description('Upload a file')
+        .argument('<path>')
+        .requiredOption('--space <id>', 'Space id')
+        .option('--path <storagePath>', 'Storage path')
+        .option('--name <name>', 'Display name'))
+        .action(async (path, options) => {
+        const client = await factory.apiClient();
+        const file = await readBlob(path);
+        const result = await client.uploadFile('/files', {
+            file: file.blob,
+            fileName: options.name ?? file.fileName,
+            query: { spaceId: options.space },
+            fields: {
+                ...(options.path ? { path: options.path } : {}),
+                ...(options.name ? { name: options.name } : {}),
+            },
+        });
+        await outputData(factory.io, result, options);
+    }));
+    command.addCommand(new Command('download')
+        .description('Download file content')
+        .argument('<id>')
+        .requiredOption('--to <path>', 'Output path, or - for stdout')
+        .action(async (id, options) => {
+        const client = await factory.apiClient();
+        const data = await client.download(`/files/${encodeURIComponent(id)}/content`);
+        await writeBinary(options.to, data);
+    }));
+    command.addCommand(createJsonBodyCommand(factory, {
+        name: 'edit',
+        description: 'Edit file metadata',
+        method: 'patch',
+        path: '/files/{fileId}',
+        argNames: ['fileId'],
+        configure: (cmd) => cmd
+            .option('--name <name>', 'Display name')
+            .option('--metadata-file <path>', 'Metadata JSON file')
+            .option('--from-file <path>', 'Read full JSON request body from file, or - for stdin'),
+        body: async (_args, options) => {
+            if (typeof options.fromFile === 'string')
+                return readJsonFile(options.fromFile);
+            return {
+                name: options.name,
+                metadata: typeof options.metadataFile === 'string'
+                    ? await readJsonFile(options.metadataFile, '--metadata-file')
+                    : undefined,
+            };
+        },
+    }));
+    command.addCommand(createDeleteCommand(factory, {
+        description: 'Delete a file',
+        path: '/files/{fileId}',
+        argNames: ['fileId'],
+    }));
+    return command;
+}

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

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import type { Factory } from '../../factory.js';
+export declare function createInvocationCommand(factory: Factory): Command;

package/dist/commands/invocation/index.js

@@ -0,0 +1,36 @@
+import { Command } from 'commander';
+import { readJsonFile } from '../shared/io.js';
+import { addOutputFlags } from '../shared/output.js';
+import { createJsonBodyCommand, createViewCommand, requestAndPrint } from '../shared/rest.js';
+export function createInvocationCommand(factory) {
+    const command = new Command('invocation')
+        .description('Inspect and control BCTRL invocations');
+    command.addCommand(createViewCommand(factory, {
+        description: 'View an invocation',
+        path: '/invocations/{id}',
+    }));
+    command.addCommand(createJsonBodyCommand(factory, {
+        name: 'wait',
+        description: 'Wait for an invocation',
+        method: 'post',
+        path: '/invocations/{id}/wait',
+        argNames: ['id'],
+        configure: (cmd) => cmd
+            .option('--timeout-ms <ms>', 'Timeout in milliseconds')
+            .option('--from-file <path>', 'Read JSON request body from file, or - for stdin'),
+        body: async (_args, options) => {
+            if (typeof options.fromFile === 'string')
+                return readJsonFile(options.fromFile);
+            return { timeoutMs: options.timeoutMs ? Number(options.timeoutMs) : undefined };
+        },
+    }));
+    command.addCommand(addOutputFlags(new Command('cancel')
+        .description('Cancel an invocation')
+        .argument('<id>'))
+        .action(async (id, options) => {
+        await requestAndPrint(factory, 'post', `/invocations/${encodeURIComponent(id)}/cancel`, {
+            output: options,
+        });
+    }));
+    return command;
+}

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

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import type { Factory } from '../../factory.js';
+export declare function createRunCommand(factory: Factory): Command;

package/dist/commands/run/index.js

@@ -0,0 +1,247 @@
+import { Command } from 'commander';
+import { CliError } from '../../runtime/errors.js';
+import { readJsonFile, writeBinary } from '../shared/io.js';
+import { parsePositiveInteger } from '../shared/options.js';
+import { addOutputFlags } from '../shared/output.js';
+import { addPaginationFlags, createJsonBodyCommand, createListCommand, createViewCommand, requestAndPrint, } from '../shared/rest.js';
+export function createRunCommand(factory) {
+    const command = new Command('run').description('Inspect and stream BCTRL run history');
+    command.addCommand(createListCommand(factory, {
+        description: 'List runs',
+        path: '/runs',
+        configure: (cmd) => addPaginationFlags(cmd)
+            .option('--space <id>', 'Filter by space id')
+            .option('--runtime <id>', 'Filter by runtime id')
+            .option('--status <status>', 'Filter by run status'),
+        query: (options) => ({
+            spaceId: typeof options.space === 'string' ? options.space : undefined,
+            runtimeId: typeof options.runtime === 'string' ? options.runtime : undefined,
+            status: typeof options.status === 'string' ? options.status : undefined,
+            limit: typeof options.limit === 'number' ? options.limit : undefined,
+            cursor: typeof options.cursor === 'string' ? options.cursor : undefined,
+        }),
+    }));
+    command.addCommand(createViewCommand(factory, {
+        description: 'View a run',
+        path: '/runs/{id}',
+    }));
+    command.addCommand(createRunEventsCommand(factory));
+    command.addCommand(createRunCommandsCommand(factory));
+    command.addCommand(createRunFilesCommand(factory));
+    command.addCommand(createRunExportCommand(factory));
+    command.addCommand(createRunWatchCommand(factory));
+    command.addCommand(createRunWaitCommand(factory));
+    command.addCommand(createRunViewerCommand(factory, 'live', 'Mint a live viewer URL'));
+    command.addCommand(createRunViewerCommand(factory, 'recording', 'Mint a recording viewer URL'));
+    return command;
+}
+function createRunWatchCommand(factory) {
+    return new Command('watch')
+        .description('Stream run events')
+        .argument('<id>')
+        .option('--type <type...>', 'Filter by event type')
+        .option('--category <category...>', 'Filter by event category')
+        .option('--connection <id>', 'Filter by connection id')
+        .option('-L, --limit <number>', 'Maximum number of events per poll', parsePositiveInteger)
+        .option('--cursor <cursor>', 'Start cursor')
+        .action(async (id, options) => {
+        const client = await factory.apiClient();
+        const stream = await client.streamText(`/runs/${encodeURIComponent(id)}/events/stream`, {
+            query: {
+                type: options.type?.join(','),
+                category: options.category?.join(','),
+                connectionId: options.connection,
+                limit: options.limit,
+                cursor: options.cursor,
+            },
+        });
+        await renderSseStream(factory, stream);
+    });
+}
+async function renderSseStream(factory, stream) {
+    let buffer = '';
+    for await (const chunk of stream) {
+        buffer += chunk;
+        let frameEnd = buffer.indexOf('\n\n');
+        while (frameEnd !== -1) {
+            const frame = buffer.slice(0, frameEnd);
+            buffer = buffer.slice(frameEnd + 2);
+            renderSseFrame(factory, frame);
+            frameEnd = buffer.indexOf('\n\n');
+        }
+    }
+    if (buffer.trim())
+        renderSseFrame(factory, buffer);
+}
+function renderSseFrame(factory, frame) {
+    let eventName = 'message';
+    const dataLines = [];
+    for (const line of frame.split(/\r?\n/)) {
+        if (line.startsWith(':'))
+            continue;
+        const separator = line.indexOf(':');
+        const field = separator === -1 ? line : line.slice(0, separator);
+        const value = separator === -1 ? '' : line.slice(separator + 1).trimStart();
+        if (field === 'event')
+            eventName = value;
+        if (field === 'data')
+            dataLines.push(value);
+    }
+    if (eventName === 'heartbeat')
+        return;
+    const rawData = dataLines.join('\n');
+    if (!rawData)
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(rawData);
+    }
+    catch {
+        factory.io.writeOut(`${rawData}\n`);
+        return;
+    }
+    if (!factory.io.isStdoutTTY()) {
+        factory.io.writeOut(`${JSON.stringify(parsed)}\n`);
+        return;
+    }
+    factory.io.writeOut(`${formatRunEvent(parsed)}\n`);
+}
+function formatRunEvent(value) {
+    if (!value || typeof value !== 'object')
+        return JSON.stringify(value);
+    const event = value;
+    const time = typeof event.time === 'string' ? event.time : '';
+    const label = [event.category, event.type].filter((part) => typeof part === 'string').join('/');
+    const status = typeof event.status === 'string' ? ` ${event.status}` : '';
+    const name = typeof event.name === 'string' ? ` ${event.name}` : '';
+    const suffix = event.data && Object.keys(event.data).length > 0 ? ` ${JSON.stringify(event.data)}` : '';
+    return [time, label || 'event'].filter(Boolean).join(' ') + status + name + suffix;
+}
+function createRunEventsCommand(factory) {
+    return addOutputFlags(new Command('events')
+        .description('List run events')
+        .argument('<id>')
+        .option('--type <type...>', 'Filter by event type')
+        .option('--category <category...>', 'Filter by event category')
+        .option('--connection <id>', 'Filter by connection id')
+        .option('-L, --limit <number>', 'Maximum number of results to return', parsePositiveInteger)
+        .option('--cursor <cursor>', 'Pagination cursor'))
+        .action(async (id, options) => {
+        await requestAndPrint(factory, 'get', `/runs/${encodeURIComponent(id)}/events`, {
+            query: {
+                type: options.type?.join(','),
+                category: options.category?.join(','),
+                connectionId: options.connection,
+                limit: options.limit,
+                cursor: options.cursor,
+            },
+            output: options,
+        });
+    });
+}
+function createRunCommandsCommand(factory) {
+    return addOutputFlags(new Command('commands')
+        .description('List run commands')
+        .argument('<id>')
+        .option('--type <type>', 'Filter by command type')
+        .option('--connection <id>', 'Filter by connection id')
+        .option('-L, --limit <number>', 'Maximum number of results to return', parsePositiveInteger)
+        .option('--cursor <cursor>', 'Pagination cursor'))
+        .action(async (id, options) => {
+        await requestAndPrint(factory, 'get', `/runs/${encodeURIComponent(id)}/commands`, {
+            query: {
+                type: options.type,
+                connectionId: options.connection,
+                limit: options.limit,
+                cursor: options.cursor,
+            },
+            output: options,
+        });
+    });
+}
+function createRunFilesCommand(factory) {
+    return addOutputFlags(new Command('files')
+        .description('List run files')
+        .argument('<id>')
+        .option('--type <type>', 'Filter by file type')
+        .option('-L, --limit <number>', 'Maximum number of results to return', parsePositiveInteger)
+        .option('--cursor <cursor>', 'Pagination cursor'))
+        .action(async (id, options) => {
+        await requestAndPrint(factory, 'get', `/runs/${encodeURIComponent(id)}/files`, {
+            query: { type: options.type, limit: options.limit, cursor: options.cursor },
+            output: options,
+        });
+    });
+}
+function createRunExportCommand(factory) {
+    return addOutputFlags(new Command('export')
+        .description('Export run files as an archive')
+        .argument('<id>')
+        .requiredOption('--to <path>', 'Output archive path, or - for stdout')
+        .option('--name <name>', 'Export file name', 'run-files.zip')
+        .option('--type <type...>', 'Filter exported file types'))
+        .action(async (id, options) => {
+        const client = await factory.apiClient();
+        const result = await client.post(`/runs/${encodeURIComponent(id)}/files/export`, {
+            body: {
+                format: 'zip',
+                name: options.name,
+                filter: options.type ? { type: options.type } : undefined,
+            },
+        });
+        const fileId = result.fileId ?? result.id;
+        if (!fileId) {
+            throw new CliError('Expected run export response to include fileId');
+        }
+        const data = await client.download(`/files/${encodeURIComponent(fileId)}/content`);
+        await writeBinary(options.to, data);
+    });
+}
+function createRunWaitCommand(factory) {
+    return createJsonBodyCommand(factory, {
+        name: 'wait',
+        description: 'Wait for a run event',
+        method: 'post',
+        path: '/runs/{id}/events/wait',
+        argNames: ['id'],
+        configure: (cmd) => cmd
+            .option('--type <type...>', 'Event type')
+            .option('--category <category...>', 'Event category')
+            .option('--connection <id>', 'Connection id')
+            .option('--cursor <cursor>', 'Cursor')
+            .option('--timeout-ms <ms>', 'Timeout in milliseconds')
+            .option('--from-file <path>', 'Read JSON request body from file, or - for stdin'),
+        body: async (_args, options) => {
+            if (typeof options.fromFile === 'string')
+                return readJsonFile(options.fromFile);
+            return {
+                type: options.type,
+                category: options.category,
+                connectionId: options.connection,
+                cursor: options.cursor,
+                timeoutMs: options.timeoutMs ? Number(options.timeoutMs) : undefined,
+            };
+        },
+    });
+}
+function createRunViewerCommand(factory, name, description) {
+    return createJsonBodyCommand(factory, {
+        name,
+        description,
+        method: 'post',
+        path: `/runs/{id}/${name}`,
+        argNames: ['id'],
+        configure: (cmd) => cmd
+            .option('--expires-in-seconds <seconds>', 'Viewer expiration in seconds')
+            .option('--control <none|input>', 'Live viewer control mode')
+            .option('--from-file <path>', 'Read JSON request body from file, or - for stdin'),
+        body: async (_args, options) => {
+            if (typeof options.fromFile === 'string')
+                return readJsonFile(options.fromFile);
+            return {
+                expiresInSeconds: options.expiresInSeconds ? Number(options.expiresInSeconds) : undefined,
+                control: name === 'live' ? options.control : undefined,
+            };
+        },
+    });
+}

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

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import type { Factory } from '../../factory.js';
+export declare function createRuntimeCommand(factory: Factory): Command;