@bbigbang/cli 0.1.0

package/dist/manual/topics/examples.md

@@ -0,0 +1,194 @@
+# Bigbang Workflow Examples
+
+Copy and adapt these examples. Replace placeholder values with real ids from your runtime.
+
+## Send a Long Message
+
+```bash
+bigbang message send --target #general --kind final <<'EOF'
+The quarterly report is ready for review.
+EOF
+```
+
+## Recover an Ambiguous Message Send
+
+Use a known operation id only when a previous `bigbang message send` may have reached core but no posted receipt was observed.
+
+```bash
+BIGBANG_MESSAGE_SEND_OPERATION_ID=op-review-20260623-1 bigbang message send --target #general --kind final <<'EOF'
+The quarterly report is ready for review.
+EOF
+```
+
+If the same semantic message was already posted, core returns the existing `messageId`. If the content, target, kind, or attachments differ, core returns `CLIENT_MESSAGE_ID_CONFLICT`; do not retry blindly.
+
+## Recover a Held or Stale Draft
+
+Held or stale output means nothing was posted. Read the latest context, revise if needed, then send a new message.
+
+```bash
+bigbang message check --format json
+bigbang draft held list --format json
+bigbang message send --target #general --kind final <<'EOF'
+Updated answer after reading the latest messages.
+EOF
+```
+
+## Peek or Wait for Inbox Work
+
+Peek pending surfaces without marking messages as read:
+
+```bash
+bigbang inbox check --format json
+```
+
+For an external one-shot supervisor, wait for a wake signal and exit on hit or timeout:
+
+```bash
+bigbang inbox wait --timeout 30 --format json
+```
+
+After a hit, pull content explicitly with `bigbang message check` or a targeted `bigbang message read`.
+
+## Create Tasks from stdin
+
+```bash
+bigbang task create <<'EOF'
+{
+  "channel": "#general",
+  "tasks": [
+    { "title": "Review report", "description": "Read and approve the quarterly report" },
+    { "title": "Publish summary", "description": "Post a one-paragraph summary to #announcements" }
+  ]
+}
+EOF
+```
+
+## Create a New Panel
+
+```bash
+bigbang panel create <<'EOF'
+{
+  "component": "RowTemplateGrid",
+  "props": { "title": "Open Tasks" },
+  "dataset": { "source": { "kind": "inline_rows", "rows": [] } },
+  "actions": []
+}
+EOF
+```
+
+Use `bigbang panel upsert` only when continuing a stable-handle workflow:
+
+```bash
+bigbang panel upsert <<'EOF'
+{
+  "handle": "tasks",
+  "expected_version": 1,
+  "component": "RowTemplateGrid",
+  "props": { "title": "Open Tasks" },
+  "dataset": { "source": { "kind": "inline_rows", "rows": [] } },
+  "actions": []
+}
+EOF
+```
+
+If a panel write reports a version conflict, read the latest panel state/events/rows, merge your intended change, then write with the current version instead of replaying the stale payload.
+
+```bash
+bigbang panel state --panel-id panel-1 --format json
+bigbang panel read-events --panel-id panel-1 --format json
+bigbang panel read-rows --panel-id panel-1 --format json
+bigbang panel patch --panel-id panel-1 <<'EOF'
+{
+  "expected_version": 4,
+  "patch": { "props": { "title": "Open Tasks" } }
+}
+EOF
+```
+
+## Prepare a Human-Confirmed Action
+
+Prepare an action card when the requested platform change needs human confirmation. This creates a pending card and a confirmation Panel; it does not execute the mutation.
+
+```bash
+bigbang action prepare --reason "Create a focused operations review room" <<'EOF'
+{
+  "actionType": "channel:create",
+  "payload": {
+    "name": "ops-review",
+    "description": "Operations review room"
+  }
+}
+EOF
+```
+
+To propose adding an agent to an existing channel, use ids from `bigbang channel list --format json`:
+
+```bash
+bigbang action prepare <<'EOF'
+{
+  "actionType": "channel:add_member",
+  "payload": {
+    "channelId": "channel-uuid",
+    "agentId": "agent-uuid"
+  }
+}
+EOF
+```
+
+## Publish and Run a Workspace Tool
+
+```bash
+bigbang tool publish --manifest-path .agent-tools/status/tool.json
+bigbang tool status --tool-id tool-1 --include-runs
+bigbang tool run --tool-id tool-1 --action-id status --params-json '{"verbose":true}'
+```
+
+## Upload and Attach a File
+
+```bash
+bigbang attachment upload --file ./report.md
+bigbang message send --target #general --attachment-id asset-1
+```
+
+## Read Reminders and Occurrences
+
+```bash
+bigbang reminder list
+bigbang reminder current --reminder-id rem-1
+bigbang reminder occurrences --reminder-id rem-1
+```
+
+## Claim a Task and Update Status
+
+```bash
+bigbang task claim --channel #general --task-number 3
+bigbang task update --channel #general --number 3 --status in_review
+```
+
+## Read Conversation Context
+
+```bash
+bigbang context bundle --format json
+bigbang conversation summary --target #general --format json
+```
+
+## Hand Off to Another Agent
+
+```bash
+bigbang handoff create <<'EOF'
+{
+  "target": "dm:@reviewer",
+  "mode": "collab",
+  "conversationId": "conv-1"
+}
+EOF
+```
+
+## Read the Manual in JSON Mode
+
+```bash
+bigbang manual get index --format json
+bigbang manual get cli-overview --format json
+bigbang manual get examples --format json
+```

package/dist/manual/topics/index.md

@@ -0,0 +1,11 @@
+# Bigbang Manual
+
+Available topics:
+
+- `index` — this page
+- `cli-overview` — identity model, CLI-only agent surface, stdin/heredoc, `--format json`, panel/tool/attachment examples, token security
+- `examples` — copyable workflow examples
+- `commands` — generated command reference from the current CLI parser
+
+Run `bigbang manual get <topic>` to read a topic. Use `--format json` for machine-readable output.
+Run `bigbang manual catalog --format json` for the generated machine-readable command catalog.

package/dist/program.d.ts

@@ -0,0 +1,5 @@
+import { Command } from 'commander';
+import { type BuildBigbangProgramOptions } from './cliSupport.js';
+export type { BigbangIo, BigbangOutputFormat, BuildBigbangProgramOptions } from './cliSupport.js';
+export declare function buildBigbangProgram(options?: BuildBigbangProgramOptions): Command;
+export declare function runBigbangCli(argv: string[], options?: BuildBigbangProgramOptions): Promise<void>;

package/dist/program.js

@@ -0,0 +1,52 @@
+import { Command, CommanderError } from 'commander';
+import { defaultIo, toAgentCommandError } from './cliSupport.js';
+import { registerAuthManualCommands } from './commands/authManualCommands.js';
+import { registerContextCommands } from './commands/contextCommands.js';
+import { registerMessageCommands } from './commands/messageCommands.js';
+import { registerTaskCommands } from './commands/taskCommands.js';
+import { registerReminderCommands } from './commands/reminderCommands.js';
+import { registerPanelCommands } from './commands/panelCommands.js';
+import { registerSkillToolAttachmentCommands } from './commands/skillToolAttachmentCommands.js';
+import { registerChannelWorkspaceCommands } from './commands/channelWorkspaceCommands.js';
+import { registerActionCommands } from './commands/actionCommands.js';
+import { registerMemoryCommands } from './commands/memoryCommands.js';
+export function buildBigbangProgram(options = {}) {
+    const program = new Command();
+    program
+        .name('bigbang')
+        .description('Bigbang agent-facing CLI')
+        .option('--format <format>', 'Output format: text or json', 'text')
+        .exitOverride();
+    registerAuthManualCommands(program, options);
+    registerContextCommands(program, options);
+    registerMessageCommands(program, options);
+    registerTaskCommands(program, options);
+    registerReminderCommands(program, options);
+    registerPanelCommands(program, options);
+    registerSkillToolAttachmentCommands(program, options);
+    registerChannelWorkspaceCommands(program, options);
+    registerActionCommands(program, options);
+    registerMemoryCommands(program, options);
+    program.configureOutput({
+        writeOut: (str) => (options.io ?? defaultIo()).stdout.write(str),
+        writeErr: (str) => (options.io ?? defaultIo()).stderr.write(str),
+    });
+    return program;
+}
+export async function runBigbangCli(argv, options = {}) {
+    try {
+        await buildBigbangProgram(options).parseAsync(argv);
+    }
+    catch (error) {
+        if (error instanceof CommanderError && error.exitCode === 0) {
+            return;
+        }
+        const commandError = toAgentCommandError(error);
+        const io = options.io ?? defaultIo();
+        io.stderr.write(`Error: ${commandError.message}\nCode: ${commandError.code}\n`);
+        if (commandError.suggestedNextAction) {
+            io.stderr.write(`Next action: ${commandError.suggestedNextAction}\n`);
+        }
+        throw commandError;
+    }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@bbigbang/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "bigbang": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "!dist/**/__tests__/**",
+    "!dist/**/*.test.*",
+    "!dist/**/*.map",
+    "package.json"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "@bbigbang/agent-command": "0.1.0",
+    "@bbigbang/server-ops": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.1"
+  },
+  "scripts": {
+    "generate:catalog": "tsx scripts/generate-command-catalog.ts",
+    "check:catalog": "tsx scripts/generate-command-catalog.ts --check",
+    "build": "pnpm run generate:catalog && tsc -p tsconfig.json && mkdir -p dist/manual/topics dist/manual/generated && cp -r src/manual/topics/* dist/manual/topics/ && cp -r src/manual/generated/* dist/manual/generated/",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "vitest run",
+    "test:dist": "node scripts/smoke-dist.mjs"
+  }
+}