Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
feat(cli): add VHS recording script for CLI demo generation
jkomyno5c6c0ec2c85f
diff --git a/.claude/skills/implement-cli-command/SKILL.md b/.claude/skills/implement-cli-command/SKILL.mdindex 12d9a6b38..c1bfd5a61 100644--- a/.claude/skills/implement-cli-command/SKILL.md+++ b/.claude/skills/implement-cli-command/SKILL.md@@ -472,9 +472,59 @@ When implementing a new command:6. Register in `src/commands/index.ts` (or in the parent group's command file)7. If using a new service, add its layer to `src/bin.ts`8. Build to verify: `cd ts/packages/cli && pnpm build`+9. Add recordings for the new command (see **Recording** below)If the build fails, check for: (1) missing service imports, (2) `Option<string>` being used where `string` is expected (use `Option.getOrUndefined` or `Option.match`), (3) the command not being exported from its file.+## Recording++New commands should have VHS recordings for documentation. Recordings produce SVGs and asciicasts that demonstrate the command in action.++### Step 1: Add Entries to recordings.yaml++Add recording entries to `ts/packages/cli/recordings/recordings.yaml` under the appropriate group:++```yaml+recordings:+ my-command:+ - name: help+ description: Show my-command help+ command: "composio my-command --help"+ height: dynamic # Use for commands whose output exceeds 750px++ - name: basic+ description: Run my-command with default options+ command: "composio my-command"+```++Each entry has:+- `name` — filename for the recording (produces `<name>.svg`, `<name>.ascii`, `<name>.tape`)+- `command` — the exact shell command to record+- `description` — (optional) comment shown instantly above the command+- `sleepAfterEnter` — (optional) override the default wait time after Enter (default: `6s`)+- `height` — (optional) `'dynamic'` for auto-sizing via two-pass recording, or a fixed pixel number. Omit to use the default height (750px)++Use `height: dynamic` for commands that produce long output (help text, full listings). Fixed height is fine for short-output commands (version, no-results, limited queries).++### Step 2: Run the Recorder++```bash+cd ts/packages/cli+bun scripts/record.ts+```++Requires `COMPOSIO_API_KEY` in the environment and `vhs` + `composio` on `PATH`.++### Output Structure++```+recordings/+├── recordings.yaml # Config+├── tapes/<group>/<name>.tape # Generated VHS tape files (committed)+├── svgs/<group>/<name>.svg # SVG recordings+└── ascii/<group>/<name>.ascii # Asciicast recordings+```+## Reference Files| File | Purpose |diff --git a/ts/packages/cli/AGENTS.md b/ts/packages/cli/AGENTS.mdindex b7fb1084f..0f2cf00f0 100644--- a/ts/packages/cli/AGENTS.md+++ b/ts/packages/cli/AGENTS.md@@ -289,3 +289,44 @@ For principles on how to design CLI interactions (arguments, flags, help text, o- **Claude skill**: `.claude/skills/create-cli/SKILL.md` (standalone, trimmed for Claude Code context)Use these guidelines when adding new commands, designing flag interfaces, or making UX decisions for the CLI.++---++## Recording CLI Demos++New commands should have VHS recordings for documentation. The recording script produces SVGs and asciicasts that demonstrate the CLI in action.++### Adding Recordings++1. Add entries to `recordings/recordings.yaml` under the appropriate group+2. Run `bun scripts/record.ts` (requires `COMPOSIO_API_KEY` and `vhs` on PATH)++### Recording Config++Each entry in `recordings.yaml` accepts:++| Field | Required | Description |+| ----------------- | -------- | --------------------------------------------------------------------------------------- |+| `name` | Yes | Filename stem (`<name>.svg`, `<name>.ascii`, `<name>.tape`) |+| `command` | Yes | Shell command to record |+| `description` | No | Comment shown instantly above the command (via VHS `Hide`/`Show`) |+| `sleepAfterEnter` | No | Wait time after Enter (default: `6s` from `vhs.sleepAfterEnter`) |+| `height` | No | `'dynamic'` for two-pass auto-sizing, or a fixed pixel number. Omit for default (750px) |++Use `height: dynamic` for commands with long output (help text, full listings). The recorder probes with 2x height, parses the SVG to measure content, then re-records at the computed height (capped at `vhs.height * 2`).++### Output Structure++```+recordings/+├── recordings.yaml # Config+├── tapes/<group>/<name>.tape # Generated VHS tape files+├── svgs/<group>/<name>.svg # SVG recordings+└── ascii/<group>/<name>.ascii # Asciicast recordings+```++### Key Files++- **Config**: `recordings/recordings.yaml`+- **Script**: `scripts/record.ts` — Bun + Effect.ts, parallel VHS execution+- **Shared tape**: `recordings/tapes/shared-config.tape` — common VHS settings (auto-generated)diff --git a/ts/packages/cli/package.json b/ts/packages/cli/package.jsonindex 68ce8b09a..99ab2105d 100644--- a/ts/packages/cli/package.json+++ b/ts/packages/cli/package.json@@ -36,7 +36,8 @@"prepublishOnly": "pnpm run build && pnpm run build:bin","typecheck:src": "tsc --noEmit -p ./tsconfig.src.json","typecheck:test": "tsc --noEmit -p ./tsconfig.test.json",- "typecheck": "pnpm run typecheck:src && pnpm run typecheck:test"+ "typecheck": "pnpm run typecheck:src && pnpm run typecheck:test",+ "record": "bun run ./scripts/record.ts"},"keywords": ["composio",diff --git a/ts/packages/cli/scripts/record.ts b/ts/packages/cli/scripts/record.tsnew file mode 100644index 000000000..6ccd797be--- /dev/null+++ b/ts/packages/cli/scripts/record.ts@@ -0,0 +1,451 @@+#!/usr/bin/env bun++/**+ * Record CLI demo SVGs and asciicasts using VHS.+ *+ * Usage: `bun scripts/record.ts`+ *+ * Reads `recordings/recordings.yaml` and, for each recording entry:+ * 1. Generates a VHS `.tape` file → `recordings/tapes/<group>/<name>.tape`+ * 2. Runs VHS to produce an SVG → `recordings/svgs/<group>/<name>.svg`+ * 3. Runs VHS to produce an asciicast → `recordings/ascii/<group>/<name>.ascii`+ *+ * Recordings run in parallel (concurrency = cpu count − 1).+ * Requires `vhs` and `composio` on PATH, and COMPOSIO_API_KEY in the environment.+ */++import process from 'node:process';+import path from 'node:path';+import os from 'node:os';+import { Cause, Config, ConfigProvider, Effect, Exit, Logger, Layer, LogLevel, Ref } from 'effect';+import { BunContext, BunFileSystem, BunRuntime } from '@effect/platform-bun';+import { FileSystem } from '@effect/platform';+import type { Teardown } from '@effect/platform/Runtime';+import { $ } from 'bun';+import * as p from '@clack/prompts';+import color from 'picocolors';++// --- Env vars ---++declare module 'bun' {+ interface Env {+ COMPOSIO_API_KEY: string;+ }+}++/**+ * Validates that env vars needed by the `composio` cli during VHS recording don't have undefined values.+ *+ * @param env - Environment variable dictionary+ * @throws Error if any env vars have undefined values+ */+function validateRequiredEnvVars(env: Record<string, string | undefined> | undefined): void {+ if (!env) return;++ const missingVars = Object.entries(env)+ .filter(([, value]) => value === undefined)+ .map(([key]) => key);++ if (missingVars.length > 0) {+ throw new Error(+ `Missing required environment variables: ${missingVars.join(', ')}\n` ++ `Set these variables before running the tests.`+ );+ }+}++// Env vars to forward into VHS recordings.+const env = {+ // Disables Clack interactive decorations so .ascii output is readable.+ // See https://github.com/bombshell-dev/clack/pull/169+ CI: 'true',+ COMPOSIO_API_KEY: Bun.env.COMPOSIO_API_KEY,+};++validateRequiredEnvVars(env);++// --- Constannts ---++const CONCURRENCY = Math.max(os.cpus().length - 1, 1);++// --- Types ---++interface VhsConfig {+ shell: string;+ width: number;+ height: number;+ fontSize: number;+ fontFamily: string;+ padding: number;+ theme: string;+ typingSpeed: string;+ framerate: number;+ cursorBlink: boolean;+ windowBar: string;+ sleepAfterEnter: string;+}++interface Recording {+ name: string;+ command: string;+ description?: string;+ sleepAfterEnter?: string;+ height?: 'dynamic' | number;+}++interface RecordingsConfig {+ vhs: VhsConfig;+ recordings: Record<string, Recording[]>;+}++// --- Tape generation ---++function generateSharedTape(vhs: VhsConfig, env: Record<string, string>): string {+ const lines = [+ `Require composio`,+ ...Object.entries(env).map(([k, v]) => `Env ${k} "${v}"`),+ `Set Shell ${vhs.shell}`,+ `Set Width ${vhs.width}`,+ // Height is intentionally omitted — set per-recording tape to support dynamic heights.+ `Set FontSize ${vhs.fontSize}`,+ `Set FontFamily "${vhs.fontFamily}"`,+ `Set Padding ${vhs.padding}`,+ `Set Theme "${vhs.theme}"`,+ `Set TypingSpeed ${vhs.typingSpeed}`,+ `Set Framerate ${vhs.framerate}`,+ `Set CursorBlink ${vhs.cursorBlink}`,+ `Set WindowBar ${vhs.windowBar}`,+ ];+ return lines.join('\n') + '\n';+}++function generateRecordingTape(opts: {+ sharedTapePath: string;+ outputPaths: string[];+ command: string;+ description?: string;+ sleepAfterEnter: string;+ height: number;+}): string {+ const lines = [`Set Height ${opts.height}`, `Source "${opts.sharedTapePath}"`];+ lines.push(...opts.outputPaths.map(p => `Output "${p}"`), '');++ if (opts.description) {+ lines.push('Hide');+ lines.push(`Type "# ${opts.description}"`);+ lines.push('Enter');+ lines.push('Show');+ }++ lines.push(`Type "${opts.command}"`, 'Sleep 300ms', 'Enter', `Sleep ${opts.sleepAfterEnter}`);++ return lines.join('\n') + '\n';+}++// --- Dynamic height ---++/** Pixel overhead for window bar + padding + chrome (VHS height 750 → 480px content area). */+const CHROME_PX = 270;++/**+ * Parse a VHS-generated SVG to find the maximum `y` attribute from `<text>` elements+ * in the last animation frame. Returns the pixel offset of the lowest text line.+ */+function parseMaxContentY(svg: string): number {+ // Find the last animation frame (highest translate X value).+ const frameRe = /<g transform="translate\((\d+),0\)">/g;+ let maxX = 0;+ let lastFrameIdx = 0;+ let m: RegExpExecArray | null;+ while ((m = frameRe.exec(svg)) !== null) {+ const x = parseInt(m[1]!, 10);+ if (x >= maxX) {+ maxX = x;+ lastFrameIdx = m.index;+ }+ }++ // Slice the last frame (up to the next frame or closing container tag).+ const nextFrame = svg.indexOf('<g transform="translate(', lastFrameIdx + 1);+ const frame = svg.slice(lastFrameIdx, nextFrame > lastFrameIdx ? nextFrame : undefined);++ // Find the max y across all <text> elements in that frame.+ const yRe = /<text y="(\d+)"/g;+ let maxY = 0;+ while ((m = yRe.exec(frame)) !== null) {+ maxY = Math.max(maxY, parseInt(m[1]!, 10));+ }+ return maxY;+}++// --- Progress bar ---++const BAR_SIZE = 30;++function drawBar(current: number, max: number): string {+ const filled = Math.round((current / max) * BAR_SIZE);+ const empty = BAR_SIZE - filled;+ return `${color.green('━'.repeat(filled))}${color.gray('─'.repeat(empty))}`;+}++// --- Recording ---++function runVhs(tapePath: string, cliRoot: string, label: string) {+ return Effect.tryPromise({+ try: async () => {+ const r = await $`vhs ${tapePath}`.cwd(cliRoot).quiet().nothrow();+ if (r.exitCode !== 0) {+ throw new Error(`vhs exited with code ${r.exitCode}\n${r.stderr.toString()}`);+ }+ },+ catch: err => new Error(`Failed to record ${label}: ${err}`),+ });+}++function recordCommand(opts: {+ group: string;+ recording: Recording;+ defaultSleepAfterEnter: string;+ sharedTapePath: string;+ svgsDir: string;+ asciiDir: string;+ tapesDir: string;+ cliRoot: string;+ vhsHeight: number;+}) {+ return Effect.gen(function* () {+ const fs = yield* FileSystem.FileSystem;+ const {+ group,+ recording,+ defaultSleepAfterEnter,+ sharedTapePath,+ svgsDir,+ asciiDir,+ tapesDir,+ cliRoot,+ vhsHeight,+ } = opts;+ const rel = (absPath: string) => path.relative(cliRoot, absPath);+ const label = `${group}/${recording.name}`;++ const sleepAfterEnter = recording.sleepAfterEnter ?? defaultSleepAfterEnter;+ const maxHeight = vhsHeight * 2;++ // Resolve the recording height: explicit number, dynamic (two-pass), or default.+ let height = vhsHeight;+ if (typeof recording.height === 'number') {+ height = recording.height;+ } else if (recording.height === 'dynamic') {+ const probeSvgPath = path.join(tapesDir, group, `${recording.name}.probe.svg`);+ const probeTapePath = path.join(tapesDir, group, `${recording.name}.probe.tape`);++ const probeTape = generateRecordingTape({+ sharedTapePath: rel(sharedTapePath),+ outputPaths: [rel(probeSvgPath)],+ command: recording.command,+ description: recording.description,+ sleepAfterEnter,+ height: maxHeight,+ });+ yield* fs.writeFileString(probeTapePath, probeTape);+ yield* runVhs(probeTapePath, cliRoot, `${label} (probe)`);++ // Parse the probe SVG for the lowest text line in the final frame.+ const svg = yield* fs.readFileString(probeSvgPath);+ const maxY = parseMaxContentY(svg);+ height = Math.min(Math.max(maxY + CHROME_PX, vhsHeight), maxHeight);++ yield* Effect.logDebug(`[probe] ${label}: maxY=${maxY} → height=${height}`);++ // Clean up probe artifacts.+ yield* fs.remove(probeSvgPath).pipe(Effect.orElse(() => Effect.void));+ yield* fs.remove(probeTapePath).pipe(Effect.orElse(() => Effect.void));+ }++ // Final recording pass (or the only pass for fixed-height recordings).+ const tapeContent = generateRecordingTape({+ sharedTapePath: rel(sharedTapePath),+ outputPaths: [+ rel(path.join(svgsDir, group, `${recording.name}.svg`)),+ rel(path.join(asciiDir, group, `${recording.name}.ascii`)),+ ],+ command: recording.command,+ description: recording.description,+ sleepAfterEnter,+ height,+ });++ const tapePath = path.join(tapesDir, group, `${recording.name}.tape`);+ yield* fs.writeFileString(tapePath, tapeContent);+ yield* runVhs(tapePath, cliRoot, label);+ });+}++function recordAll() {+ return Effect.gen(function* () {+ const fs = yield* FileSystem.FileSystem;++ yield* Effect.sync(() => p.intro('composio record'));++ // Tape-embedded paths are relative to the cli package root (ts/packages/cli/).+ const scriptDir = path.resolve(+ import.meta.dirname ?? path.dirname(new URL(import.meta.url).pathname)+ );+ const cliRoot = path.resolve(scriptDir, '..');+ const recordingsDir = path.resolve(scriptDir, '..', 'recordings');+ const configPath = path.join(recordingsDir, 'recordings.yaml');++ yield* Effect.logDebug(`Reading config from ${configPath}`);++ const configRaw = yield* fs.readFileString(configPath);+ const config = Bun.YAML.parse(configRaw) as RecordingsConfig;++ // Output directories for generated tapes, SVGs, and asciicasts.+ const tapesDir = path.join(recordingsDir, 'tapes');+ const svgsDir = path.join(recordingsDir, 'svgs');+ const asciiDir = path.join(recordingsDir, 'ascii');+ yield* fs.makeDirectory(tapesDir, { recursive: true });+ yield* fs.makeDirectory(svgsDir, { recursive: true });+ yield* fs.makeDirectory(asciiDir, { recursive: true });++ // Write shared config tape.+ const sharedTapePath = path.join(tapesDir, 'shared-config.tape');+ yield* fs.writeFileString(sharedTapePath, generateSharedTape(config.vhs, env));++ yield* Effect.sync(() =>+ p.log.step(`Loaded config from ${color.dim(path.relative(process.cwd(), configPath))}`)+ );++ // Flatten all recordings across groups.+ const groups = Object.entries(config.recordings);+ const allRecordings = groups.flatMap(([group, recordings]) =>+ recordings.map(recording => ({ group, recording }))+ );+ const total = allRecordings.length;++ // Create all group directories upfront.+ const groupNames = [...new Set(groups.map(([g]) => g))];+ yield* Effect.forEach(+ groupNames,+ group =>+ Effect.all([+ fs.makeDirectory(path.join(svgsDir, group), { recursive: true }),+ fs.makeDirectory(path.join(asciiDir, group), { recursive: true }),+ fs.makeDirectory(path.join(tapesDir, group), { recursive: true }),+ ]),+ { concurrency: 'unbounded' }+ );++ // Record all with bounded concurrency and a single progress spinner.+ yield* Effect.sync(() =>+ p.log.step(+ `Recording ${color.bold(String(total))} commands ${color.dim(`(concurrency: ${CONCURRENCY})`)}`+ )+ );+ const completed = yield* Ref.make(0);+ const spin = p.spinner();+ yield* Effect.sync(() => spin.start(`${drawBar(0, total)} ${color.dim(`0/${total}`)}`));++ yield* Effect.forEach(+ allRecordings,+ ({ group, recording }) =>+ recordCommand({+ group,+ recording,+ defaultSleepAfterEnter: config.vhs.sleepAfterEnter,+ sharedTapePath,+ svgsDir,+ asciiDir,+ tapesDir,+ cliRoot,+ vhsHeight: config.vhs.height,+ }).pipe(+ Effect.tap(() =>+ Ref.updateAndGet(completed, c => c + 1).pipe(+ Effect.tap(n =>+ Effect.sync(() =>+ spin.message(+ `${drawBar(n, total)} ${color.dim(`${n}/${total}`)} ${group}/${recording.name}`+ )+ )+ )+ )+ ),+ Effect.tapError(err =>+ Ref.get(completed).pipe(+ Effect.tap(n =>+ Effect.sync(() => {+ spin.error(+ `${drawBar(n, total)} ${color.bold(group)} failed at ${recording.name}`+ );+ p.log.error(String(err));+ })+ )+ )+ )+ ),+ { concurrency: CONCURRENCY }+ );++ yield* Effect.sync(() =>+ spin.stop(`${drawBar(total, total)} ${color.dim(`${total}/${total}`)} ${color.green('done')}`)+ );++ // Collect file sizes.+ let totalBytes = 0n;+ for (const { group, recording } of allRecordings) {+ for (const filePath of [+ path.join(svgsDir, group, `${recording.name}.svg`),+ path.join(asciiDir, group, `${recording.name}.ascii`),+ ]) {+ const stat = yield* fs+ .stat(filePath)+ .pipe(Effect.orElse(() => Effect.succeed({ size: 0n } as { size: bigint })));+ totalBytes += BigInt(stat.size);+ }+ }++ const totalKB = (Number(totalBytes) / 1024).toFixed(1);++ yield* Effect.sync(() =>+ p.note(+ [+ `${color.bold(String(total))} recordings`,+ `${color.bold(totalKB)} KB total`,+ color.dim(`${path.relative(process.cwd(), recordingsDir)}/`),+ ].join('\n'),+ 'Summary'+ )+ );++ yield* Effect.sync(() => p.outro('Recording complete'));+ });+}++// --- Bootstrap ---++export const teardown: Teardown = <E, A>(exit: Exit.Exit<E, A>, onExit: (code: number) => void) => {+ const shouldFail = Exit.isFailure(exit) && !Cause.isInterruptedOnly(exit.cause);+ const errorCode = Number(process.exitCode ?? 1);+ onExit(shouldFail ? errorCode : 0);+};++const ConfigLive = Effect.gen(function* () {+ const logLevel = yield* Config.logLevel('COMPOSIO_LOG_LEVEL').pipe(+ Config.withDefault(LogLevel.Info)+ );++ return Logger.minimumLogLevel(logLevel);+}).pipe(Layer.unwrapEffect, Layer.merge(Layer.setConfigProvider(ConfigProvider.fromEnv())));++recordAll().pipe(+ Effect.provide(ConfigLive),+ Effect.provide(Logger.pretty),+ Effect.provide(BunContext.layer),+ Effect.provide(BunFileSystem.layer),+ Effect.map(() => ({ message: 'Process completed successfully.' })),+ BunRuntime.runMain({+ teardown,+ })+);diff --git a/turbo.jsonc b/turbo.jsoncindex 4fdc0c53d..9741ce1fc 100644--- a/turbo.jsonc+++ b/turbo.jsonc@@ -51,6 +51,20 @@},"//#clean": {"cache": false+ },+ "record": {+ "dependsOn": ["^build"],+ "inputs": [+ "src/**",+ "scripts/record.ts",+ "recordings/recordings.yaml"+ ],+ "outputs": [+ "recordings/tapes/**",+ "recordings/svgs/**",+ "recordings/ascii/**"+ ],+ "env": ["COMPOSIO_API_KEY"]}}}