@mindscraft/branch-video-agent-cli 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# Branch Video Agent CLI
+
+`@mindscraft/branch-video-agent-cli` 是一个可脱离当前代码仓库使用的发布版 CLI，用于通过 Bearer agent token 调用 branch-video 与 AIHub agent API。
+
+## 安装与执行
+
+推荐直接使用 `npx`：
+
+```powershell
+npx -y @mindscraft/branch-video-agent-cli --help
+```
+
+中国大陆用户如果希望更稳定、更快地安装，可以走 npm 的公开镜像：
+
+```powershell
+npx -y --registry=https://registry.npmmirror.com @mindscraft/branch-video-agent-cli --help
+```
+
+也可以全局安装：
+
+```powershell
+npm install -g @mindscraft/branch-video-agent-cli
+branch-video-agent --help
+```
+
+环境变量：
+
+- `AIHUB_AGENT_TOKEN`
+- `BRANCH_VIDEO_AGENT_BASE_URL`
+
+最小调用示例：
+
+```powershell
+@'
+{
+  "filter": "mine",
+  "page": 1,
+  "limit": 20
+}
+'@ | npx -y @mindscraft/branch-video-agent-cli project list
+```
+
+## 在仓库内构建发布包
+
+从仓库根目录执行：
+
+```powershell
+npm run agent:cli:package:build
+npm run agent:cli:package:smoke
+```
+
+产物输出到：
+
+```text
+packages/branch-video-agent-cli/dist/
+```
+
+## 发布步骤
+
+从仓库根目录先完成构建与 smoke check，然后进入子包目录执行发布：
+
+```powershell
+npm run agent:cli:package:build
+npm run agent:cli:package:smoke
+Set-Location packages/branch-video-agent-cli
+npm login --registry=https://registry.npmjs.org/
+npm pack
+npm publish
+```
+
+当前子包已经固定为发布到 `https://registry.npmjs.org/`，不会沿用仓库根目录的内网 `.npmrc`。
+
+发布前请先确认两件事：
+
+1. 你在 npmjs 上拥有当前包名对应的 scope 权限；如果没有 `@nd` scope，需要先改包名，例如改成你实际拥有的 scope，或改成非 scope 包名。
+2. 如果要让中国大陆用户安装体验更稳定，建议仍以 npmjs 作为唯一发布源，再让用户通过 `npmmirror` 安装；不要把 GitHub Packages 当作主发布仓库，因为安装门槛和网络可达性都更差。

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from './index.js';
+process.exitCode = await main(process.argv.slice(2));

package/dist/commands/production.d.ts

@@ -0,0 +1,2 @@
+import type { CommandHandler } from '../lib/types.js';
+export declare const productionCommands: Record<string, CommandHandler>;

package/dist/commands/production.js

@@ -0,0 +1,75 @@
+import { CliCommandError } from '../lib/errors.js';
+import { getRequiredString, pickDefined } from '../lib/payload.js';
+const terminalProductionStatuses = new Set(['succeeded', 'failed', 'interrupted', 'cancelled']);
+async function waitForProduction(projectId, handler) {
+    const { client, flags, runtime } = handler;
+    const startedAt = runtime.now();
+    while (runtime.now() - startedAt <= flags.timeoutMs) {
+        const status = await client.request(`/api/branch-video/${encodeURIComponent(projectId)}/production`, {
+            method: 'GET',
+        });
+        const statusValue = String(status.data?.status || '');
+        if (terminalProductionStatuses.has(statusValue)) {
+            if (statusValue !== 'succeeded') {
+                throw new CliCommandError(String(status.data?.error || 'Production failed'), 'PRODUCTION_FAILED', status.data, status.requestId);
+            }
+            return {
+                data: status.data,
+                requestId: status.requestId,
+            };
+        }
+        await runtime.sleep(flags.pollIntervalMs);
+    }
+    throw new CliCommandError('Production wait timed out', 'TIMEOUT', { projectId });
+}
+export const productionCommands = {
+    schema: async ({ client, payload }) => {
+        const result = await client.request('/api/branch-video/production/aihub/schema', {
+            method: 'GET',
+            query: pickDefined(payload, ['mode']),
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    start: async (context) => {
+        const result = await context.client.request('/api/branch-video/production/aihub/start', {
+            method: 'POST',
+            body: context.payload,
+        });
+        if (!context.flags.wait) {
+            return { data: result.data, requestId: result.requestId };
+        }
+        const projectId = getRequiredString(result.data, 'projectId');
+        const finalStatus = await waitForProduction(projectId, context);
+        return {
+            data: {
+                start: result.data,
+                status: finalStatus.data,
+            },
+            requestId: finalStatus.requestId || result.requestId,
+        };
+    },
+    status: async ({ client, payload }) => {
+        const projectId = getRequiredString(payload, 'projectId');
+        const result = await client.request(`/api/branch-video/${encodeURIComponent(projectId)}/production`, {
+            method: 'GET',
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    retry: async (context) => {
+        const projectId = getRequiredString(context.payload, 'projectId');
+        const result = await context.client.request(`/api/branch-video/${encodeURIComponent(projectId)}/production/retry`, {
+            method: 'POST',
+        });
+        if (!context.flags.wait) {
+            return { data: result.data, requestId: result.requestId };
+        }
+        const finalStatus = await waitForProduction(projectId, context);
+        return {
+            data: {
+                retry: result.data,
+                status: finalStatus.data,
+            },
+            requestId: finalStatus.requestId || result.requestId,
+        };
+    },
+};

package/dist/commands/project.d.ts

@@ -0,0 +1,2 @@
+import type { CommandHandler } from '../lib/types.js';
+export declare const projectCommands: Record<string, CommandHandler>;

package/dist/commands/project.js

@@ -0,0 +1,39 @@
+import { getRequiredString, omitKeys, pickDefined } from '../lib/payload.js';
+export const projectCommands = {
+    list: async ({ client, payload }) => {
+        const result = await client.request('/api/branch-video', {
+            method: 'GET',
+            query: pickDefined(payload, ['filter', 'page', 'limit', 'sort', 'order']),
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    get: async ({ client, payload }) => {
+        const projectId = getRequiredString(payload, 'projectId');
+        const result = await client.request(`/api/branch-video/${encodeURIComponent(projectId)}/project`, {
+            method: 'GET',
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    create: async ({ client, payload }) => {
+        const result = await client.request('/api/branch-video', {
+            method: 'POST',
+            body: payload,
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    update: async ({ client, payload }) => {
+        const projectId = getRequiredString(payload, 'projectId');
+        const result = await client.request(`/api/branch-video/${encodeURIComponent(projectId)}`, {
+            method: 'PUT',
+            body: omitKeys(payload, ['projectId']),
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    delete: async ({ client, payload }) => {
+        const projectId = getRequiredString(payload, 'projectId');
+        const result = await client.request(`/api/branch-video/${encodeURIComponent(projectId)}`, {
+            method: 'DELETE',
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+};

package/dist/commands/version.d.ts

@@ -0,0 +1,2 @@
+import type { CommandHandler } from '../lib/types.js';
+export declare const versionCommands: Record<string, CommandHandler>;

package/dist/commands/version.js

@@ -0,0 +1,26 @@
+import { getRequiredInt, getRequiredString, omitKeys } from '../lib/payload.js';
+export const versionCommands = {
+    list: async ({ client, payload }) => {
+        const projectId = getRequiredString(payload, 'projectId');
+        const result = await client.request(`/api/branch-video/${encodeURIComponent(projectId)}/versions`, {
+            method: 'GET',
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    get: async ({ client, payload }) => {
+        const projectId = getRequiredString(payload, 'projectId');
+        const version = getRequiredInt(payload, 'version');
+        const result = await client.request(`/api/branch-video/${encodeURIComponent(projectId)}/versions/${version}`, {
+            method: 'GET',
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    publish: async ({ client, payload }) => {
+        const projectId = getRequiredString(payload, 'projectId');
+        const result = await client.request(`/api/branch-video/${encodeURIComponent(projectId)}/publish`, {
+            method: 'POST',
+            body: omitKeys(payload, ['projectId']),
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+};

package/dist/commands/workflow.d.ts

@@ -0,0 +1,2 @@
+import type { CommandHandler } from '../lib/types.js';
+export declare const workflowCommands: Record<string, CommandHandler>;

package/dist/commands/workflow.js

@@ -0,0 +1,54 @@
+import { CliCommandError } from '../lib/errors.js';
+import { getRequiredString } from '../lib/payload.js';
+const terminalWorkflowStatuses = new Set(['succeeded', 'failed']);
+export const workflowCommands = {
+    run: async ({ client, payload, flags, runtime }) => {
+        const run = await client.request('/api/agent/aihub/workflows/run', {
+            method: 'POST',
+            body: payload,
+        });
+        if (!flags.wait) {
+            return { data: run.data, requestId: run.requestId };
+        }
+        const runId = getRequiredString(run.data, 'runId');
+        const startedAt = runtime.now();
+        while (runtime.now() - startedAt <= flags.timeoutMs) {
+            const status = await client.request(`/api/agent/aihub/workflows/runs/${encodeURIComponent(runId)}`, {
+                method: 'GET',
+            });
+            const statusValue = String(status.data?.status || '');
+            if (terminalWorkflowStatuses.has(statusValue)) {
+                if (statusValue !== 'succeeded') {
+                    throw new CliCommandError(String(status.data?.error?.message || status.data?.error || 'Workflow failed'), 'RUN_FAILED', { run: run.data, status: status.data }, status.requestId);
+                }
+                const outputs = await client.request(`/api/agent/aihub/workflows/runs/${encodeURIComponent(runId)}/outputs`, {
+                    method: 'GET',
+                });
+                return {
+                    data: {
+                        run: run.data,
+                        status: status.data,
+                        outputs: outputs.data,
+                    },
+                    requestId: outputs.requestId || status.requestId || run.requestId,
+                };
+            }
+            await runtime.sleep(flags.pollIntervalMs);
+        }
+        throw new CliCommandError('Workflow wait timed out', 'TIMEOUT', { runId });
+    },
+    status: async ({ client, payload }) => {
+        const runId = getRequiredString(payload, 'runId');
+        const result = await client.request(`/api/agent/aihub/workflows/runs/${encodeURIComponent(runId)}`, {
+            method: 'GET',
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+    outputs: async ({ client, payload }) => {
+        const runId = getRequiredString(payload, 'runId');
+        const result = await client.request(`/api/agent/aihub/workflows/runs/${encodeURIComponent(runId)}/outputs`, {
+            method: 'GET',
+        });
+        return { data: result.data, requestId: result.requestId };
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { type CliRuntime } from './lib/runtime.js';
+export declare function main(argv: string[], runtime?: CliRuntime): Promise<number>;

package/dist/index.js

@@ -0,0 +1,102 @@
+import { productionCommands } from './commands/production.js';
+import { projectCommands } from './commands/project.js';
+import { versionCommands } from './commands/version.js';
+import { workflowCommands } from './commands/workflow.js';
+import { CliCommandError } from './lib/errors.js';
+import { getCliHelpText, parseCliArgs, resolveCliConfig } from './lib/flags.js';
+import { CliHttpClient } from './lib/http.js';
+import { ensureObject } from './lib/payload.js';
+import { createProcessRuntime } from './lib/runtime.js';
+const commandRegistry = {
+    workflow: workflowCommands,
+    project: projectCommands,
+    version: versionCommands,
+    production: productionCommands,
+};
+function normalizeError(error) {
+    if (error instanceof CliCommandError) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new CliCommandError(error.message || 'Unexpected error');
+    }
+    return new CliCommandError(String(error || 'Unexpected error'));
+}
+function writeJson(runtime, value) {
+    runtime.writeStdout(`${JSON.stringify(value, null, 2)}\n`);
+}
+function writeError(runtime, command, raw, error) {
+    if (raw) {
+        writeJson(runtime, error.data ?? {
+            error: error.message,
+            code: error.code,
+            requestId: error.requestId || null,
+        });
+        return;
+    }
+    writeJson(runtime, {
+        ok: false,
+        data: null,
+        error: error.message,
+        code: error.code,
+        requestId: error.requestId || null,
+        meta: { command },
+    });
+}
+export async function main(argv, runtime = createProcessRuntime()) {
+    let commandName = '';
+    let rawOutput = false;
+    try {
+        const parsed = parseCliArgs(argv);
+        rawOutput = parsed.flags.raw;
+        commandName = [parsed.group, parsed.action].filter(Boolean).join('.');
+        if (parsed.flags.help || !parsed.group || !parsed.action) {
+            runtime.writeStdout(`${getCliHelpText()}\n`);
+            return 0;
+        }
+        const group = commandRegistry[parsed.group];
+        const command = group?.[parsed.action];
+        if (!group || !command) {
+            throw new CliCommandError(`Unknown command: ${commandName || argv.join(' ')}`, 'VALIDATION_ERROR');
+        }
+        const stdinText = await runtime.readStdinText();
+        let stdinPayload = {};
+        if (stdinText.trim()) {
+            try {
+                stdinPayload = ensureObject(JSON.parse(stdinText));
+            }
+            catch (error) {
+                throw new CliCommandError(`Invalid stdin JSON: ${error?.message || error}`, 'VALIDATION_ERROR');
+            }
+        }
+        const { baseUrl, token, commandPayload } = await resolveCliConfig(stdinPayload, parsed.flags, runtime);
+        const client = new CliHttpClient(baseUrl, token, runtime.fetchImpl);
+        const result = await command({
+            payload: commandPayload,
+            flags: parsed.flags,
+            client,
+            runtime,
+        });
+        if (parsed.flags.raw) {
+            writeJson(runtime, result.data);
+            return 0;
+        }
+        writeJson(runtime, {
+            ok: true,
+            data: result.data,
+            error: null,
+            code: null,
+            requestId: result.requestId || null,
+            meta: {
+                command: commandName,
+                wait: parsed.flags.wait,
+                ...(result.meta || {}),
+            },
+        });
+        return 0;
+    }
+    catch (error) {
+        writeError(runtime, commandName, rawOutput, normalizeError(error));
+        return 1;
+    }
+}

package/dist/lib/errors.d.ts

@@ -0,0 +1,7 @@
+export declare class CliCommandError extends Error {
+    code: string;
+    data?: unknown;
+    requestId?: string | null;
+    status?: number;
+    constructor(message: string, code?: string, data?: unknown, requestId?: string | null, status?: number);
+}

package/dist/lib/errors.js

@@ -0,0 +1,14 @@
+export class CliCommandError extends Error {
+    code;
+    data;
+    requestId;
+    status;
+    constructor(message, code = 'CLI_ERROR', data, requestId, status) {
+        super(message);
+        this.name = 'CliCommandError';
+        this.code = code;
+        this.data = data;
+        this.requestId = requestId;
+        this.status = status;
+    }
+}

package/dist/lib/flags.d.ts

@@ -0,0 +1,24 @@
+import { type JsonObject } from './payload.js';
+import type { CliRuntime } from './runtime.js';
+export type CliFlags = {
+    raw: boolean;
+    wait: boolean;
+    help: boolean;
+    timeoutMs: number;
+    pollIntervalMs: number;
+    baseUrlArg: string;
+    tokenArg: string;
+    tokenFile: string;
+};
+export type ParsedCliArgs = {
+    group: string;
+    action: string;
+    flags: CliFlags;
+};
+export declare function resolveCliConfig(payload: JsonObject, flags: CliFlags, runtime: CliRuntime): Promise<{
+    baseUrl: string;
+    token: string;
+    commandPayload: JsonObject;
+}>;
+export declare function parseCliArgs(argv: string[]): ParsedCliArgs;
+export declare function getCliHelpText(): string;

package/dist/lib/flags.js

@@ -0,0 +1,102 @@
+import { CliCommandError } from './errors.js';
+import { getOptionalString, omitKeys } from './payload.js';
+export async function resolveCliConfig(payload, flags, runtime) {
+    const envBaseUrl = String(runtime.env.BRANCH_VIDEO_AGENT_BASE_URL || '').trim();
+    const envToken = String(runtime.env.AIHUB_AGENT_TOKEN || '').trim();
+    const stdinBaseUrl = getOptionalString(payload, 'baseUrl');
+    const stdinToken = getOptionalString(payload, 'token');
+    const fileToken = flags.tokenFile ? String(await runtime.readTextFile(flags.tokenFile)).trim() : '';
+    const baseUrl = envBaseUrl || stdinBaseUrl || flags.baseUrlArg;
+    const token = envToken || stdinToken || fileToken || flags.tokenArg;
+    if (!baseUrl) {
+        throw new CliCommandError('Missing base URL', 'VALIDATION_ERROR');
+    }
+    if (!token) {
+        throw new CliCommandError('Missing agent token', 'VALIDATION_ERROR');
+    }
+    return {
+        baseUrl,
+        token,
+        commandPayload: omitKeys(payload, ['baseUrl', 'token']),
+    };
+}
+function readValue(args, index, flag) {
+    const value = args[index + 1];
+    if (!value || value.startsWith('--')) {
+        throw new CliCommandError(`Missing value for ${flag}`, 'VALIDATION_ERROR');
+    }
+    return value;
+}
+export function parseCliArgs(argv) {
+    const positionals = [];
+    const flags = {
+        raw: false,
+        wait: false,
+        help: false,
+        timeoutMs: 300000,
+        pollIntervalMs: 1000,
+        baseUrlArg: '',
+        tokenArg: '',
+        tokenFile: '',
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (!arg.startsWith('--')) {
+            positionals.push(arg);
+            continue;
+        }
+        switch (arg) {
+            case '--help':
+            case '-h':
+                flags.help = true;
+                break;
+            case '--raw':
+                flags.raw = true;
+                break;
+            case '--wait':
+                flags.wait = true;
+                break;
+            case '--timeout':
+                flags.timeoutMs = Number(readValue(argv, index, arg));
+                index += 1;
+                break;
+            case '--poll-interval':
+                flags.pollIntervalMs = Number(readValue(argv, index, arg));
+                index += 1;
+                break;
+            case '--base-url':
+                flags.baseUrlArg = readValue(argv, index, arg).trim();
+                index += 1;
+                break;
+            case '--token':
+                flags.tokenArg = readValue(argv, index, arg).trim();
+                index += 1;
+                break;
+            case '--token-file':
+                flags.tokenFile = readValue(argv, index, arg).trim();
+                index += 1;
+                break;
+            default:
+                throw new CliCommandError(`Unknown flag: ${arg}`, 'VALIDATION_ERROR');
+        }
+    }
+    return {
+        group: positionals[0] || '',
+        action: positionals[1] || '',
+        flags,
+    };
+}
+export function getCliHelpText() {
+    return [
+        'Usage: branch-video-agent <group> <action> [--wait] [--raw] [--timeout <ms>] [--base-url <url>] [--token <token>] [--token-file <path>]',
+        '',
+        'Groups:',
+        '  workflow   run | status | outputs',
+        '  project    list | get | create | update | delete',
+        '  version    list | get | publish',
+        '  production schema | start | status | retry',
+        '',
+        'Config precedence:',
+        '  AIHUB_AGENT_TOKEN / BRANCH_VIDEO_AGENT_BASE_URL > stdin JSON or --token-file > command flags',
+    ].join('\n');
+}

package/dist/lib/http.d.ts

@@ -0,0 +1,18 @@
+type RequestOptions = {
+    method: string;
+    body?: unknown;
+    query?: Record<string, unknown>;
+};
+type RequestResult<T> = {
+    data: T;
+    status: number;
+    requestId: string | null;
+};
+export declare class CliHttpClient {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly fetchImpl;
+    constructor(baseUrl: string, token: string, fetchImpl: typeof fetch);
+    request<T>(path: string, options: RequestOptions): Promise<RequestResult<T>>;
+}
+export {};

package/dist/lib/http.js

@@ -0,0 +1,73 @@
+import { CliCommandError } from './errors.js';
+function normalizeBaseUrl(baseUrl) {
+    return baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+}
+function buildUrl(baseUrl, path, query) {
+    const url = new URL(path.replace(/^\//, ''), normalizeBaseUrl(baseUrl));
+    for (const [key, value] of Object.entries(query || {})) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+}
+function extractRequestId(response, parsed) {
+    return response.headers.get('x-request-id')
+        || response.headers.get('x-correlation-id')
+        || (typeof parsed?.requestId === 'string' ? parsed.requestId : null);
+}
+export class CliHttpClient {
+    baseUrl;
+    token;
+    fetchImpl;
+    constructor(baseUrl, token, fetchImpl) {
+        this.baseUrl = baseUrl;
+        this.token = token;
+        this.fetchImpl = fetchImpl;
+    }
+    async request(path, options) {
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+        };
+        if (options.body !== undefined) {
+            headers['content-type'] = 'application/json';
+        }
+        let response;
+        try {
+            response = await this.fetchImpl(buildUrl(this.baseUrl, path, options.query), {
+                method: options.method,
+                headers,
+                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+            });
+        }
+        catch (error) {
+            throw new CliCommandError(error?.message || 'Network request failed', 'NETWORK_ERROR');
+        }
+        const text = await response.text();
+        const parsed = text
+            ? (() => {
+                try {
+                    return JSON.parse(text);
+                }
+                catch {
+                    return text;
+                }
+            })()
+            : null;
+        const requestId = extractRequestId(response, parsed);
+        if (!response.ok) {
+            const errorMessage = typeof parsed === 'object' && parsed && typeof parsed.error === 'string'
+                ? String(parsed.error)
+                : response.statusText || 'Request failed';
+            const errorCode = typeof parsed === 'object' && parsed && typeof parsed.code === 'string'
+                ? String(parsed.code)
+                : `HTTP_${response.status}`;
+            throw new CliCommandError(errorMessage, errorCode, parsed, requestId, response.status);
+        }
+        return {
+            data: parsed,
+            status: response.status,
+            requestId,
+        };
+    }
+}

package/dist/lib/payload.d.ts

@@ -0,0 +1,7 @@
+export type JsonObject = Record<string, unknown>;
+export declare function ensureObject(value: unknown, fieldName?: string): JsonObject;
+export declare function getRequiredString(payload: JsonObject, key: string): string;
+export declare function getOptionalString(payload: JsonObject, key: string): string;
+export declare function getRequiredInt(payload: JsonObject, key: string): number;
+export declare function omitKeys(payload: JsonObject, keys: string[]): JsonObject;
+export declare function pickDefined(payload: JsonObject, keys: string[]): JsonObject;

package/dist/lib/payload.js

@@ -0,0 +1,49 @@
+import { CliCommandError } from './errors.js';
+export function ensureObject(value, fieldName = 'stdin payload') {
+    if (!value)
+        return {};
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        throw new CliCommandError(`${fieldName} must be a JSON object`, 'VALIDATION_ERROR');
+    }
+    return value;
+}
+export function getRequiredString(payload, key) {
+    const value = payload[key];
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new CliCommandError(`Missing ${key}`, 'VALIDATION_ERROR');
+    }
+    return value.trim();
+}
+export function getOptionalString(payload, key) {
+    const value = payload[key];
+    if (typeof value !== 'string')
+        return '';
+    return value.trim();
+}
+export function getRequiredInt(payload, key) {
+    const value = payload[key];
+    const normalized = typeof value === 'string' ? value.trim() : value;
+    const parsed = typeof normalized === 'number' ? normalized : Number(normalized);
+    if (!Number.isInteger(parsed)) {
+        throw new CliCommandError(`Invalid ${key}`, 'VALIDATION_ERROR');
+    }
+    return parsed;
+}
+export function omitKeys(payload, keys) {
+    const omitted = new Set(keys);
+    return Object.entries(payload).reduce((acc, [key, value]) => {
+        if (!omitted.has(key)) {
+            acc[key] = value;
+        }
+        return acc;
+    }, {});
+}
+export function pickDefined(payload, keys) {
+    return keys.reduce((acc, key) => {
+        const value = payload[key];
+        if (value !== undefined && value !== null && value !== '') {
+            acc[key] = value;
+        }
+        return acc;
+    }, {});
+}

package/dist/lib/runtime.d.ts

@@ -0,0 +1,11 @@
+export interface CliRuntime {
+    env: Record<string, string | undefined>;
+    fetchImpl: typeof fetch;
+    readStdinText: () => Promise<string>;
+    readTextFile: (filePath: string) => Promise<string>;
+    writeStdout: (text: string) => void;
+    writeStderr: (text: string) => void;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+}
+export declare function createProcessRuntime(): CliRuntime;

package/dist/lib/runtime.js

@@ -0,0 +1,26 @@
+import { readFile } from 'fs/promises';
+async function readProcessStdinText() {
+    if (process.stdin.isTTY)
+        return '';
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+export function createProcessRuntime() {
+    return {
+        env: process.env,
+        fetchImpl: fetch,
+        readStdinText: readProcessStdinText,
+        readTextFile: (filePath) => readFile(filePath, 'utf8'),
+        writeStdout: (text) => {
+            process.stdout.write(text);
+        },
+        writeStderr: (text) => {
+            process.stderr.write(text);
+        },
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: () => Date.now(),
+    };
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,16 @@
+import type { CliFlags } from './flags.js';
+import type { CliHttpClient } from './http.js';
+import type { JsonObject } from './payload.js';
+import type { CliRuntime } from './runtime.js';
+export type CommandResult = {
+    data: unknown;
+    requestId?: string | null;
+    meta?: Record<string, unknown>;
+};
+export type CommandContext = {
+    payload: JsonObject;
+    flags: CliFlags;
+    client: CliHttpClient;
+    runtime: CliRuntime;
+};
+export type CommandHandler = (context: CommandContext) => Promise<CommandResult>;

package/dist/lib/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@mindscraft/branch-video-agent-cli",
+  "version": "0.1.0",
+  "description": "Published CLI for branch-video and AIHub agent APIs.",
+  "type": "module",
+  "bin": {
+    "branch-video-agent": "./dist/bin.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "branch-video",
+    "aihub",
+    "cli",
+    "interactive-video"
+  ],
+  "scripts": {
+    "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "smoke:help": "npm run build && node dist/bin.js --help"
+  }
+}