@bbigbang/cli 0.1.0

package/dist/commandCatalog.d.ts

@@ -0,0 +1,36 @@
+import type { Command } from 'commander';
+export interface BigbangCatalogArgument {
+    name: string;
+    required: boolean;
+    variadic: boolean;
+    description: string;
+}
+export interface BigbangCatalogOption {
+    flags: string;
+    short?: string;
+    long?: string;
+    required: boolean;
+    optional: boolean;
+    variadic: boolean;
+    mandatory: boolean;
+    description: string;
+    defaultValue?: string | number | boolean | string[] | null;
+}
+export interface BigbangCatalogCommand {
+    path: string[];
+    name: string;
+    description: string;
+    arguments: BigbangCatalogArgument[];
+    options: BigbangCatalogOption[];
+    children: BigbangCatalogCommand[];
+}
+export interface BigbangCommandCatalog {
+    schemaVersion: 1;
+    generatedBy: 'bigbang-command-catalog';
+    root: BigbangCatalogCommand;
+    commands: BigbangCatalogCommand[];
+}
+export declare function collectBigbangCommandCatalog(program: Command): BigbangCommandCatalog;
+export declare function renderBigbangCommandManual(catalog: BigbangCommandCatalog): string;
+export declare function renderBigbangCommandSummary(catalog: BigbangCommandCatalog): string[];
+export declare function renderBigbangSharedCatalogModule(catalog: BigbangCommandCatalog): string;

package/dist/commandCatalog.js

@@ -0,0 +1,152 @@
+export function collectBigbangCommandCatalog(program) {
+    const root = collectCommand(program, [], true);
+    const commands = flattenCommands(root);
+    return {
+        schemaVersion: 1,
+        generatedBy: 'bigbang-command-catalog',
+        root,
+        commands,
+    };
+}
+export function renderBigbangCommandManual(catalog) {
+    const lines = [
+        '# Bigbang Command Reference',
+        '',
+        '<!-- Generated by `pnpm --filter @bbigbang/cli generate:catalog`. Do not edit by hand. -->',
+        '',
+        'This reference is generated from the assembled Commander program. For workflow guidance, read `bigbang manual get cli-overview` and `bigbang manual get examples`.',
+        '',
+        '## Command Summary',
+        '',
+        ...renderSummaryLines(catalog).map((line) => `- \`${line}\``),
+        '',
+        '## Commands',
+        '',
+    ];
+    for (const command of catalog.commands) {
+        if (command.path.length === 0 || command.children.length > 0)
+            continue;
+        lines.push(`### \`bigbang ${command.path.join(' ')}\``);
+        lines.push('');
+        if (command.description) {
+            lines.push(command.description);
+            lines.push('');
+        }
+        if (command.arguments.length > 0) {
+            lines.push('Arguments:');
+            for (const argument of command.arguments) {
+                lines.push(`- \`${argument.required ? `<${argument.name}>` : `[${argument.name}]`}\`${argument.description ? ` — ${argument.description}` : ''}`);
+            }
+            lines.push('');
+        }
+        if (command.options.length > 0) {
+            lines.push('Options:');
+            for (const option of command.options) {
+                const defaultSuffix = option.defaultValue === undefined ? '' : ` Default: \`${String(option.defaultValue)}\`.`;
+                lines.push(`- \`${option.flags}\`${option.description ? ` — ${option.description}` : ''}${option.mandatory ? ' Required.' : ''}${defaultSuffix}`);
+            }
+            lines.push('');
+        }
+    }
+    return `${lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()}\n`;
+}
+export function renderBigbangCommandSummary(catalog) {
+    return renderSummaryLines(catalog);
+}
+export function renderBigbangSharedCatalogModule(catalog) {
+    return [
+        '/* Generated by `pnpm --filter @bbigbang/cli generate:catalog`. Do not edit by hand. */',
+        '',
+        `export const BIGBANG_COMMAND_CATALOG = ${JSON.stringify(catalog, null, 2)} as const;`,
+        '',
+        `export const BIGBANG_COMMAND_SUMMARY_LINES = ${JSON.stringify(renderBigbangCommandSummary(catalog), null, 2)} as const;`,
+        '',
+    ].join('\n');
+}
+function collectCommand(command, path, isRoot = false) {
+    const name = command.name();
+    const nextPath = isRoot ? [] : [...path, name];
+    const children = command.commands
+        .filter((child) => !isHiddenCommand(child))
+        .map((child) => collectCommand(child, nextPath));
+    return {
+        path: nextPath,
+        name,
+        description: command.description() || '',
+        arguments: command.registeredArguments.map((argument) => ({
+            name: argument.name(),
+            required: argument.required,
+            variadic: argument.variadic,
+            description: argument.description || '',
+        })),
+        options: command.options
+            .filter((option) => !option.hidden)
+            .map((option) => ({
+            flags: option.flags,
+            ...(option.short ? { short: option.short } : {}),
+            ...(option.long ? { long: option.long } : {}),
+            required: option.required,
+            optional: option.optional,
+            variadic: option.variadic,
+            mandatory: option.mandatory,
+            description: option.description || '',
+            ...(option.defaultValue === undefined ? {} : { defaultValue: normalizeDefaultValue(option.defaultValue) }),
+        })),
+        children,
+    };
+}
+function flattenCommands(root) {
+    const result = [];
+    const visit = (command) => {
+        result.push(command);
+        for (const child of command.children)
+            visit(child);
+    };
+    visit(root);
+    return result;
+}
+function isHiddenCommand(command) {
+    return Boolean(command._hidden);
+}
+function normalizeDefaultValue(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+        return value;
+    if (Array.isArray(value) && value.every((item) => typeof item === 'string'))
+        return value;
+    return undefined;
+}
+function renderSummaryLines(catalog) {
+    const byGroup = new Map();
+    for (const command of catalog.commands) {
+        if (command.path.length === 0 || command.children.length > 0)
+            continue;
+        const [group, ...rest] = command.path;
+        if (!group || rest.length === 0)
+            continue;
+        const existing = byGroup.get(group) ?? [];
+        existing.push(rest.join(' '));
+        byGroup.set(group, existing);
+    }
+    const lines = [];
+    for (const [group, leaves] of byGroup) {
+        const simple = [];
+        const nested = new Map();
+        for (const leaf of leaves) {
+            const parts = leaf.split(' ');
+            if (parts.length === 1) {
+                simple.push(parts[0] ?? leaf);
+                continue;
+            }
+            const [head, ...tail] = parts;
+            const bucket = nested.get(head) ?? [];
+            bucket.push(tail.join(' '));
+            nested.set(head, bucket);
+        }
+        const pieces = [...simple.sort()];
+        for (const [head, subLeaves] of [...nested.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+            pieces.push(`${head} ${subLeaves.sort().join('|')}`);
+        }
+        lines.push(`bigbang ${group} ${pieces.join('|')}`);
+    }
+    return lines;
+}

package/dist/commands/actionCommands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type BuildBigbangProgramOptions } from '../cliSupport.js';
+export declare function registerActionCommands(program: Command, options: BuildBigbangProgramOptions): void;

package/dist/commands/actionCommands.js

@@ -0,0 +1,43 @@
+import { AGENT_COMMAND_ERROR_CODES, AgentCommandError, MUTATION_HINTS, appendCommonBody, createRuntime, parseJsonStdinOrThrow, parsePositiveInteger, requireString, responseError, summarizeActionPrepare, withHint, writeOutput, } from '../cliSupport.js';
+export function registerActionCommands(program, options) {
+    const action = program.command('action').description('Prepare core-authoritative human-confirmed platform actions');
+    action.command('prepare')
+        .description('Prepare an action card from stdin JSON for human confirmation')
+        .option('--conversation-id <id>', 'Origin conversation id; defaults to managed runtime context')
+        .option('--expires-in-minutes <n>', 'Pending card lifetime in minutes; defaults to 1440')
+        .option('--reason <text>', 'Human-readable audit reason for the proposed action')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const input = await parseJsonStdinOrThrow(runtime, 'action prepare JSON payload');
+        const actionType = typeof input.actionType === 'string'
+            ? input.actionType.trim()
+            : typeof input.action_type === 'string'
+                ? input.action_type.trim()
+                : '';
+        if (!actionType) {
+            throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_ARG, 'action prepare JSON requires actionType.', { suggestedNextAction: 'Use {"actionType":"channel:create","payload":{...}}.' });
+        }
+        const conversationId = typeof opts.conversationId === 'string' && opts.conversationId.trim()
+            ? requireString(opts.conversationId, '--conversation-id')
+            : runtime.context.conversationId;
+        if (!conversationId) {
+            throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.MISSING_CONVERSATION_ID, 'action prepare requires BIGBANG_CONVERSATION_ID or --conversation-id.', { suggestedNextAction: 'Run from a managed Bigbang runtime or pass --conversation-id.' });
+        }
+        const expiresInMinutes = parsePositiveInteger('expires-in-minutes', opts.expiresInMinutes);
+        const expiresAt = expiresInMinutes ? Date.now() + expiresInMinutes * 60 * 1000 : undefined;
+        const reason = typeof opts.reason === 'string' && opts.reason.trim()
+            ? requireString(opts.reason, '--reason')
+            : undefined;
+        const body = appendCommonBody(runtime, {
+            actionType,
+            payload: input.payload ?? input.action,
+            ...(expiresAt ? { expiresAt } : {}),
+            ...(reason ? { reason } : {}),
+        });
+        body.conversationId = conversationId;
+        const response = await runtime.client.request('POST', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/actions/prepare`, body);
+        if (!response.ok)
+            throw responseError(response, 'action prepare failed');
+        writeOutput(runtime, withHint(summarizeActionPrepare(response.data), MUTATION_HINTS.actionPrepare), response.data);
+    });
+}

package/dist/commands/authManualCommands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { BuildBigbangProgramOptions } from '../cliSupport.js';
+export declare function registerAuthManualCommands(program: Command, options: BuildBigbangProgramOptions): void;

package/dist/commands/authManualCommands.js

@@ -0,0 +1,60 @@
+import { AGENT_COMMAND_ERROR_CODES, AgentCommandError, MANUAL_TOPICS, createRuntime, isManualTopic, readManualTopic, readCommandCatalog, writeJson } from '../cliSupport.js';
+export function registerAuthManualCommands(program, options) {
+    const auth = program.command('auth').description('Authentication and runtime context helpers');
+    auth.command('whoami')
+        .description('Print the agent command context with secrets redacted')
+        .action(() => {
+        const runtime = createRuntime(program, options);
+        writeJson(runtime, {
+            ok: true,
+            data: {
+                agentId: runtime.context.agentId,
+                serverUrl: runtime.context.serverUrl,
+                conversationId: runtime.context.conversationId ?? null,
+                runId: runtime.runId ?? null,
+                turnId: runtime.turnId ?? null,
+                traceId: runtime.traceId ?? null,
+                runContextPath: runtime.context.runContextPath ?? null,
+                tokenSource: runtime.context.tokenSource,
+            },
+        });
+    });
+    const manual = program.command('manual').description('Built-in command reference');
+    manual.command('get')
+        .description('Read a manual topic')
+        .argument('<topic>', 'Manual topic: index, cli-overview, examples, or commands')
+        .action(async (topic) => {
+        const runtime = createRuntime(program, options);
+        if (!isManualTopic(topic)) {
+            if (runtime.outputFormat === 'text') {
+                let indexContent;
+                try {
+                    indexContent = readManualTopic(runtime, 'index');
+                }
+                catch {
+                    indexContent = MANUAL_TOPICS.map((t) => `- ${t}`).join('\n');
+                }
+                runtime.io.stdout.write(`Unknown topic '${topic}'. Available topics:\n${indexContent}\n\nNext action: Run \`bigbang manual get index\` to list available topics.\n`);
+                return;
+            }
+            throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.NOT_FOUND, `Unknown manual topic: ${topic}`, { suggestedNextAction: 'Run bigbang manual get index to list available topics.' });
+        }
+        const content = readManualTopic(runtime, topic);
+        if (runtime.outputFormat === 'json') {
+            if (topic === 'index') {
+                writeJson(runtime, [...MANUAL_TOPICS]);
+            }
+            else {
+                writeJson(runtime, { topic, content });
+            }
+            return;
+        }
+        runtime.io.stdout.write(content);
+    });
+    manual.command('catalog')
+        .description('Print the generated machine-readable command catalog')
+        .action(() => {
+        const runtime = createRuntime(program, options);
+        writeJson(runtime, readCommandCatalog(runtime));
+    });
+}

package/dist/commands/channelWorkspaceCommands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { BuildBigbangProgramOptions } from '../cliSupport.js';
+export declare function registerChannelWorkspaceCommands(program: Command, options: BuildBigbangProgramOptions): void;

package/dist/commands/channelWorkspaceCommands.js

@@ -0,0 +1,105 @@
+import { AGENT_COMMAND_ERROR_CODES, AgentCommandError, appendRunContextParams, createRuntime, requireString, responseError, summarizeChannelMembers, summarizeChannelMutation, summarizeServerDirectory, summarizeThreadUnfollow, summarizeWorkspaceFile, summarizeWorkspaceInspect, summarizeWorkspaceTree, writeOutput } from '../cliSupport.js';
+export function registerChannelWorkspaceCommands(program, options) {
+    const channel = program.command('channel').description('Channel discovery and membership helpers');
+    channel.command('list')
+        .description('List channels, agents, and known humans')
+        .action(async () => {
+        const runtime = createRuntime(program, options);
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/server`);
+        if (!response.ok)
+            throw responseError(response, 'server directory failed');
+        writeOutput(runtime, summarizeServerDirectory(response.data), response.data);
+    });
+    channel.command('members')
+        .description('List agent members in a joined channel')
+        .requiredOption('--channel <target>', 'Channel target such as #general or a raw channel id')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const params = new URLSearchParams();
+        params.set('channel', requireString(opts.channel, '--channel'));
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/channel-members?${params.toString()}`);
+        if (!response.ok)
+            throw responseError(response, 'channel members failed');
+        writeOutput(runtime, summarizeChannelMembers(response.data), response.data);
+    });
+    channel.command('join')
+        .description('Join the current agent to a channel')
+        .requiredOption('--channel <target>', 'Channel target such as #general or a raw channel id')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const response = await runtime.client.request('POST', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/channels/join`, { channel: requireString(opts.channel, '--channel') });
+        if (!response.ok)
+            throw responseError(response, 'channel join failed');
+        writeOutput(runtime, summarizeChannelMutation(response.data, 'joined'), response.data);
+    });
+    channel.command('leave')
+        .description('Leave a channel and clear current agent channel-local participant state')
+        .requiredOption('--channel <target>', 'Channel target such as #general or a raw channel id')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const response = await runtime.client.request('POST', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/channels/leave`, { channel: requireString(opts.channel, '--channel') });
+        if (!response.ok)
+            throw responseError(response, 'channel leave failed');
+        writeOutput(runtime, summarizeChannelMutation(response.data, 'left'), response.data);
+    });
+    const thread = program.command('thread').description('Thread participation helpers');
+    thread.command('unfollow')
+        .description('Unfollow a channel thread for the current agent')
+        .option('--target <target>', 'Thread target such as #general:abc12345')
+        .option('--channel <target>', 'Channel target used with --thread-root')
+        .option('--thread-root <id>', 'Thread root id or short id used with --channel')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const target = typeof opts.target === 'string' ? opts.target.trim() : '';
+        const channelTarget = typeof opts.channel === 'string' ? opts.channel.trim() : '';
+        const threadRootId = typeof opts.threadRoot === 'string' ? opts.threadRoot.trim() : '';
+        if (!target && (!channelTarget || !threadRootId)) {
+            throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_ARG, 'thread unfollow requires --target or both --channel and --thread-root.', { suggestedNextAction: 'Pass a full thread target such as --target #general:abc12345.' });
+        }
+        const response = await runtime.client.request('POST', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/threads/unfollow`, {
+            ...(target ? { target } : {}),
+            ...(channelTarget ? { channel: channelTarget } : {}),
+            ...(threadRootId ? { threadRootId } : {}),
+        });
+        if (!response.ok)
+            throw responseError(response, 'thread unfollow failed');
+        writeOutput(runtime, summarizeThreadUnfollow(response.data), response.data);
+    });
+    const workspace = program.command('workspace').description('Read-only current agent workspace helpers');
+    workspace.command('inspect')
+        .description('Inspect current agent workspace git/directory facts')
+        .action(async () => {
+        const runtime = createRuntime(program, options);
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/workspace-inspect`);
+        if (!response.ok)
+            throw responseError(response, 'workspace inspect failed');
+        writeOutput(runtime, summarizeWorkspaceInspect(response.data), response.data);
+    });
+    workspace.command('tree')
+        .description('List current agent workspace directory entries')
+        .option('--path <path>', 'Relative directory path inside the current workspace')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const params = appendRunContextParams(runtime, new URLSearchParams());
+        const workspacePath = typeof opts.path === 'string' ? opts.path.trim() : '';
+        if (workspacePath)
+            params.set('path', workspacePath);
+        const qs = params.toString();
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/workspace-tree${qs ? `?${qs}` : ''}`);
+        if (!response.ok)
+            throw responseError(response, 'workspace tree failed');
+        writeOutput(runtime, summarizeWorkspaceTree(response.data), response.data);
+    });
+    workspace.command('file')
+        .description('Read a text file from the current agent workspace')
+        .requiredOption('--path <path>', 'Relative file path inside the current workspace')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const params = appendRunContextParams(runtime, new URLSearchParams());
+        params.set('path', requireString(opts.path, '--path'));
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/workspace-file?${params.toString()}`);
+        if (!response.ok)
+            throw responseError(response, 'workspace file failed');
+        writeOutput(runtime, summarizeWorkspaceFile(response.data), response.data);
+    });
+}

package/dist/commands/contextCommands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { BuildBigbangProgramOptions } from '../cliSupport.js';
+export declare function registerContextCommands(program: Command, options: BuildBigbangProgramOptions): void;