@devries-cameron20 / composio-1 / commits / 5c6c0ec2c
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

feat(cli): add VHS recording script for CLI demo generation

Add a recording infrastructure that produces SVG and asciicast demos from a declarative YAML config. Supports dynamic height auto-sizing, parallel execution, and progress reporting via Clack UI.

jkomyno committed Feb 19, 2026 at 01:16 UTC 5c6c0ec2c85f80345f7487d819a812f2f1753e8a
5 files changed +558 -1
.claude/skills/implement-cli-command/SKILL.md
+50
@@ -472,9 +472,59 @@ When implementing a new command:
472 6. Register in `src/commands/index.ts` (or in the parent group's command file)
473 7. If using a new service, add its layer to `src/bin.ts`
474 8. Build to verify: `cd ts/packages/cli && pnpm build`
475 +9. Add recordings for the new command (see **Recording** below)
476
477 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.
478
479 +## Recording
480 +
481 +New commands should have VHS recordings for documentation. Recordings produce SVGs and asciicasts that demonstrate the command in action.
482 +
483 +### Step 1: Add Entries to recordings.yaml
484 +
485 +Add recording entries to `ts/packages/cli/recordings/recordings.yaml` under the appropriate group:
486 +
487 +```yaml
488 +recordings:
489 + my-command:
490 + - name: help
491 + description: Show my-command help
492 + command: "composio my-command --help"
493 + height: dynamic # Use for commands whose output exceeds 750px
494 +
495 + - name: basic
496 + description: Run my-command with default options
497 + command: "composio my-command"
498 +```
499 +
500 +Each entry has:
501 +- `name` — filename for the recording (produces `<name>.svg`, `<name>.ascii`, `<name>.tape`)
502 +- `command` — the exact shell command to record
503 +- `description` — (optional) comment shown instantly above the command
504 +- `sleepAfterEnter` — (optional) override the default wait time after Enter (default: `6s`)
505 +- `height` — (optional) `'dynamic'` for auto-sizing via two-pass recording, or a fixed pixel number. Omit to use the default height (750px)
506 +
507 +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).
508 +
509 +### Step 2: Run the Recorder
510 +
511 +```bash
512 +cd ts/packages/cli
513 +bun scripts/record.ts
514 +```
515 +
516 +Requires `COMPOSIO_API_KEY` in the environment and `vhs` + `composio` on `PATH`.
517 +
518 +### Output Structure
519 +
520 +```
521 +recordings/
522 +├── recordings.yaml # Config
523 +├── tapes/<group>/<name>.tape # Generated VHS tape files (committed)
524 +├── svgs/<group>/<name>.svg # SVG recordings
525 +└── ascii/<group>/<name>.ascii # Asciicast recordings
526 +```
527 +
528 ## Reference Files
529
530 | File | Purpose |
ts/packages/cli/AGENTS.md
+41
@@ -289,3 +289,44 @@ For principles on how to design CLI interactions (arguments, flags, help text, o
289 - **Claude skill**: `.claude/skills/create-cli/SKILL.md` (standalone, trimmed for Claude Code context)
290
291 Use these guidelines when adding new commands, designing flag interfaces, or making UX decisions for the CLI.
292 +
293 +---
294 +
295 +## Recording CLI Demos
296 +
297 +New commands should have VHS recordings for documentation. The recording script produces SVGs and asciicasts that demonstrate the CLI in action.
298 +
299 +### Adding Recordings
300 +
301 +1. Add entries to `recordings/recordings.yaml` under the appropriate group
302 +2. Run `bun scripts/record.ts` (requires `COMPOSIO_API_KEY` and `vhs` on PATH)
303 +
304 +### Recording Config
305 +
306 +Each entry in `recordings.yaml` accepts:
307 +
308 +| Field | Required | Description |
309 +| ----------------- | -------- | --------------------------------------------------------------------------------------- |
310 +| `name` | Yes | Filename stem (`<name>.svg`, `<name>.ascii`, `<name>.tape`) |
311 +| `command` | Yes | Shell command to record |
312 +| `description` | No | Comment shown instantly above the command (via VHS `Hide`/`Show`) |
313 +| `sleepAfterEnter` | No | Wait time after Enter (default: `6s` from `vhs.sleepAfterEnter`) |
314 +| `height` | No | `'dynamic'` for two-pass auto-sizing, or a fixed pixel number. Omit for default (750px) |
315 +
316 +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`).
317 +
318 +### Output Structure
319 +
320 +```
321 +recordings/
322 +├── recordings.yaml # Config
323 +├── tapes/<group>/<name>.tape # Generated VHS tape files
324 +├── svgs/<group>/<name>.svg # SVG recordings
325 +└── ascii/<group>/<name>.ascii # Asciicast recordings
326 +```
327 +
328 +### Key Files
329 +
330 +- **Config**: `recordings/recordings.yaml`
331 +- **Script**: `scripts/record.ts` — Bun + Effect.ts, parallel VHS execution
332 +- **Shared tape**: `recordings/tapes/shared-config.tape` — common VHS settings (auto-generated)
ts/packages/cli/package.json
+2 -1
@@ -36,7 +36,8 @@
36 "prepublishOnly": "pnpm run build && pnpm run build:bin",
37 "typecheck:src": "tsc --noEmit -p ./tsconfig.src.json",
38 "typecheck:test": "tsc --noEmit -p ./tsconfig.test.json",
39 - "typecheck": "pnpm run typecheck:src && pnpm run typecheck:test"
39 + "typecheck": "pnpm run typecheck:src && pnpm run typecheck:test",
40 + "record": "bun run ./scripts/record.ts"
41 },
42 "keywords": [
43 "composio",
ts/packages/cli/scripts/record.ts new
+451
@@ -0,0 +1,451 @@
1 +#!/usr/bin/env bun
2 +
3 +/**
4 + * Record CLI demo SVGs and asciicasts using VHS.
5 + *
6 + * Usage: `bun scripts/record.ts`
7 + *
8 + * Reads `recordings/recordings.yaml` and, for each recording entry:
9 + * 1. Generates a VHS `.tape` file → `recordings/tapes/<group>/<name>.tape`
10 + * 2. Runs VHS to produce an SVG → `recordings/svgs/<group>/<name>.svg`
11 + * 3. Runs VHS to produce an asciicast → `recordings/ascii/<group>/<name>.ascii`
12 + *
13 + * Recordings run in parallel (concurrency = cpu count − 1).
14 + * Requires `vhs` and `composio` on PATH, and COMPOSIO_API_KEY in the environment.
15 + */
16 +
17 +import process from 'node:process';
18 +import path from 'node:path';
19 +import os from 'node:os';
20 +import { Cause, Config, ConfigProvider, Effect, Exit, Logger, Layer, LogLevel, Ref } from 'effect';
21 +import { BunContext, BunFileSystem, BunRuntime } from '@effect/platform-bun';
22 +import { FileSystem } from '@effect/platform';
23 +import type { Teardown } from '@effect/platform/Runtime';
24 +import { $ } from 'bun';
25 +import * as p from '@clack/prompts';
26 +import color from 'picocolors';
27 +
28 +// --- Env vars ---
29 +
30 +declare module 'bun' {
31 + interface Env {
32 + COMPOSIO_API_KEY: string;
33 + }
34 +}
35 +
36 +/**
37 + * Validates that env vars needed by the `composio` cli during VHS recording don't have undefined values.
38 + *
39 + * @param env - Environment variable dictionary
40 + * @throws Error if any env vars have undefined values
41 + */
42 +function validateRequiredEnvVars(env: Record<string, string | undefined> | undefined): void {
43 + if (!env) return;
44 +
45 + const missingVars = Object.entries(env)
46 + .filter(([, value]) => value === undefined)
47 + .map(([key]) => key);
48 +
49 + if (missingVars.length > 0) {
50 + throw new Error(
51 + `Missing required environment variables: ${missingVars.join(', ')}\n` +
52 + `Set these variables before running the tests.`
53 + );
54 + }
55 +}
56 +
57 +// Env vars to forward into VHS recordings.
58 +const env = {
59 + // Disables Clack interactive decorations so .ascii output is readable.
60 + // See https://github.com/bombshell-dev/clack/pull/169
61 + CI: 'true',
62 + COMPOSIO_API_KEY: Bun.env.COMPOSIO_API_KEY,
63 +};
64 +
65 +validateRequiredEnvVars(env);
66 +
67 +// --- Constannts ---
68 +
69 +const CONCURRENCY = Math.max(os.cpus().length - 1, 1);
70 +
71 +// --- Types ---
72 +
73 +interface VhsConfig {
74 + shell: string;
75 + width: number;
76 + height: number;
77 + fontSize: number;
78 + fontFamily: string;
79 + padding: number;
80 + theme: string;
81 + typingSpeed: string;
82 + framerate: number;
83 + cursorBlink: boolean;
84 + windowBar: string;
85 + sleepAfterEnter: string;
86 +}
87 +
88 +interface Recording {
89 + name: string;
90 + command: string;
91 + description?: string;
92 + sleepAfterEnter?: string;
93 + height?: 'dynamic' | number;
94 +}
95 +
96 +interface RecordingsConfig {
97 + vhs: VhsConfig;
98 + recordings: Record<string, Recording[]>;
99 +}
100 +
101 +// --- Tape generation ---
102 +
103 +function generateSharedTape(vhs: VhsConfig, env: Record<string, string>): string {
104 + const lines = [
105 + `Require composio`,
106 + ...Object.entries(env).map(([k, v]) => `Env ${k} "${v}"`),
107 + `Set Shell ${vhs.shell}`,
108 + `Set Width ${vhs.width}`,
109 + // Height is intentionally omitted — set per-recording tape to support dynamic heights.
110 + `Set FontSize ${vhs.fontSize}`,
111 + `Set FontFamily "${vhs.fontFamily}"`,
112 + `Set Padding ${vhs.padding}`,
113 + `Set Theme "${vhs.theme}"`,
114 + `Set TypingSpeed ${vhs.typingSpeed}`,
115 + `Set Framerate ${vhs.framerate}`,
116 + `Set CursorBlink ${vhs.cursorBlink}`,
117 + `Set WindowBar ${vhs.windowBar}`,
118 + ];
119 + return lines.join('\n') + '\n';
120 +}
121 +
122 +function generateRecordingTape(opts: {
123 + sharedTapePath: string;
124 + outputPaths: string[];
125 + command: string;
126 + description?: string;
127 + sleepAfterEnter: string;
128 + height: number;
129 +}): string {
130 + const lines = [`Set Height ${opts.height}`, `Source "${opts.sharedTapePath}"`];
131 + lines.push(...opts.outputPaths.map(p => `Output "${p}"`), '');
132 +
133 + if (opts.description) {
134 + lines.push('Hide');
135 + lines.push(`Type "# ${opts.description}"`);
136 + lines.push('Enter');
137 + lines.push('Show');
138 + }
139 +
140 + lines.push(`Type "${opts.command}"`, 'Sleep 300ms', 'Enter', `Sleep ${opts.sleepAfterEnter}`);
141 +
142 + return lines.join('\n') + '\n';
143 +}
144 +
145 +// --- Dynamic height ---
146 +
147 +/** Pixel overhead for window bar + padding + chrome (VHS height 750 → 480px content area). */
148 +const CHROME_PX = 270;
149 +
150 +/**
151 + * Parse a VHS-generated SVG to find the maximum `y` attribute from `<text>` elements
152 + * in the last animation frame. Returns the pixel offset of the lowest text line.
153 + */
154 +function parseMaxContentY(svg: string): number {
155 + // Find the last animation frame (highest translate X value).
156 + const frameRe = /<g transform="translate\((\d+),0\)">/g;
157 + let maxX = 0;
158 + let lastFrameIdx = 0;
159 + let m: RegExpExecArray | null;
160 + while ((m = frameRe.exec(svg)) !== null) {
161 + const x = parseInt(m[1]!, 10);
162 + if (x >= maxX) {
163 + maxX = x;
164 + lastFrameIdx = m.index;
165 + }
166 + }
167 +
168 + // Slice the last frame (up to the next frame or closing container tag).
169 + const nextFrame = svg.indexOf('<g transform="translate(', lastFrameIdx + 1);
170 + const frame = svg.slice(lastFrameIdx, nextFrame > lastFrameIdx ? nextFrame : undefined);
171 +
172 + // Find the max y across all <text> elements in that frame.
173 + const yRe = /<text y="(\d+)"/g;
174 + let maxY = 0;
175 + while ((m = yRe.exec(frame)) !== null) {
176 + maxY = Math.max(maxY, parseInt(m[1]!, 10));
177 + }
178 + return maxY;
179 +}
180 +
181 +// --- Progress bar ---
182 +
183 +const BAR_SIZE = 30;
184 +
185 +function drawBar(current: number, max: number): string {
186 + const filled = Math.round((current / max) * BAR_SIZE);
187 + const empty = BAR_SIZE - filled;
188 + return `${color.green('━'.repeat(filled))}${color.gray('─'.repeat(empty))}`;
189 +}
190 +
191 +// --- Recording ---
192 +
193 +function runVhs(tapePath: string, cliRoot: string, label: string) {
194 + return Effect.tryPromise({
195 + try: async () => {
196 + const r = await $`vhs ${tapePath}`.cwd(cliRoot).quiet().nothrow();
197 + if (r.exitCode !== 0) {
198 + throw new Error(`vhs exited with code ${r.exitCode}\n${r.stderr.toString()}`);
199 + }
200 + },
201 + catch: err => new Error(`Failed to record ${label}: ${err}`),
202 + });
203 +}
204 +
205 +function recordCommand(opts: {
206 + group: string;
207 + recording: Recording;
208 + defaultSleepAfterEnter: string;
209 + sharedTapePath: string;
210 + svgsDir: string;
211 + asciiDir: string;
212 + tapesDir: string;
213 + cliRoot: string;
214 + vhsHeight: number;
215 +}) {
216 + return Effect.gen(function* () {
217 + const fs = yield* FileSystem.FileSystem;
218 + const {
219 + group,
220 + recording,
221 + defaultSleepAfterEnter,
222 + sharedTapePath,
223 + svgsDir,
224 + asciiDir,
225 + tapesDir,
226 + cliRoot,
227 + vhsHeight,
228 + } = opts;
229 + const rel = (absPath: string) => path.relative(cliRoot, absPath);
230 + const label = `${group}/${recording.name}`;
231 +
232 + const sleepAfterEnter = recording.sleepAfterEnter ?? defaultSleepAfterEnter;
233 + const maxHeight = vhsHeight * 2;
234 +
235 + // Resolve the recording height: explicit number, dynamic (two-pass), or default.
236 + let height = vhsHeight;
237 + if (typeof recording.height === 'number') {
238 + height = recording.height;
239 + } else if (recording.height === 'dynamic') {
240 + const probeSvgPath = path.join(tapesDir, group, `${recording.name}.probe.svg`);
241 + const probeTapePath = path.join(tapesDir, group, `${recording.name}.probe.tape`);
242 +
243 + const probeTape = generateRecordingTape({
244 + sharedTapePath: rel(sharedTapePath),
245 + outputPaths: [rel(probeSvgPath)],
246 + command: recording.command,
247 + description: recording.description,
248 + sleepAfterEnter,
249 + height: maxHeight,
250 + });
251 + yield* fs.writeFileString(probeTapePath, probeTape);
252 + yield* runVhs(probeTapePath, cliRoot, `${label} (probe)`);
253 +
254 + // Parse the probe SVG for the lowest text line in the final frame.
255 + const svg = yield* fs.readFileString(probeSvgPath);
256 + const maxY = parseMaxContentY(svg);
257 + height = Math.min(Math.max(maxY + CHROME_PX, vhsHeight), maxHeight);
258 +
259 + yield* Effect.logDebug(`[probe] ${label}: maxY=${maxY} → height=${height}`);
260 +
261 + // Clean up probe artifacts.
262 + yield* fs.remove(probeSvgPath).pipe(Effect.orElse(() => Effect.void));
263 + yield* fs.remove(probeTapePath).pipe(Effect.orElse(() => Effect.void));
264 + }
265 +
266 + // Final recording pass (or the only pass for fixed-height recordings).
267 + const tapeContent = generateRecordingTape({
268 + sharedTapePath: rel(sharedTapePath),
269 + outputPaths: [
270 + rel(path.join(svgsDir, group, `${recording.name}.svg`)),
271 + rel(path.join(asciiDir, group, `${recording.name}.ascii`)),
272 + ],
273 + command: recording.command,
274 + description: recording.description,
275 + sleepAfterEnter,
276 + height,
277 + });
278 +
279 + const tapePath = path.join(tapesDir, group, `${recording.name}.tape`);
280 + yield* fs.writeFileString(tapePath, tapeContent);
281 + yield* runVhs(tapePath, cliRoot, label);
282 + });
283 +}
284 +
285 +function recordAll() {
286 + return Effect.gen(function* () {
287 + const fs = yield* FileSystem.FileSystem;
288 +
289 + yield* Effect.sync(() => p.intro('composio record'));
290 +
291 + // Tape-embedded paths are relative to the cli package root (ts/packages/cli/).
292 + const scriptDir = path.resolve(
293 + import.meta.dirname ?? path.dirname(new URL(import.meta.url).pathname)
294 + );
295 + const cliRoot = path.resolve(scriptDir, '..');
296 + const recordingsDir = path.resolve(scriptDir, '..', 'recordings');
297 + const configPath = path.join(recordingsDir, 'recordings.yaml');
298 +
299 + yield* Effect.logDebug(`Reading config from ${configPath}`);
300 +
301 + const configRaw = yield* fs.readFileString(configPath);
302 + const config = Bun.YAML.parse(configRaw) as RecordingsConfig;
303 +
304 + // Output directories for generated tapes, SVGs, and asciicasts.
305 + const tapesDir = path.join(recordingsDir, 'tapes');
306 + const svgsDir = path.join(recordingsDir, 'svgs');
307 + const asciiDir = path.join(recordingsDir, 'ascii');
308 + yield* fs.makeDirectory(tapesDir, { recursive: true });
309 + yield* fs.makeDirectory(svgsDir, { recursive: true });
310 + yield* fs.makeDirectory(asciiDir, { recursive: true });
311 +
312 + // Write shared config tape.
313 + const sharedTapePath = path.join(tapesDir, 'shared-config.tape');
314 + yield* fs.writeFileString(sharedTapePath, generateSharedTape(config.vhs, env));
315 +
316 + yield* Effect.sync(() =>
317 + p.log.step(`Loaded config from ${color.dim(path.relative(process.cwd(), configPath))}`)
318 + );
319 +
320 + // Flatten all recordings across groups.
321 + const groups = Object.entries(config.recordings);
322 + const allRecordings = groups.flatMap(([group, recordings]) =>
323 + recordings.map(recording => ({ group, recording }))
324 + );
325 + const total = allRecordings.length;
326 +
327 + // Create all group directories upfront.
328 + const groupNames = [...new Set(groups.map(([g]) => g))];
329 + yield* Effect.forEach(
330 + groupNames,
331 + group =>
332 + Effect.all([
333 + fs.makeDirectory(path.join(svgsDir, group), { recursive: true }),
334 + fs.makeDirectory(path.join(asciiDir, group), { recursive: true }),
335 + fs.makeDirectory(path.join(tapesDir, group), { recursive: true }),
336 + ]),
337 + { concurrency: 'unbounded' }
338 + );
339 +
340 + // Record all with bounded concurrency and a single progress spinner.
341 + yield* Effect.sync(() =>
342 + p.log.step(
343 + `Recording ${color.bold(String(total))} commands ${color.dim(`(concurrency: ${CONCURRENCY})`)}`
344 + )
345 + );
346 + const completed = yield* Ref.make(0);
347 + const spin = p.spinner();
348 + yield* Effect.sync(() => spin.start(`${drawBar(0, total)} ${color.dim(`0/${total}`)}`));
349 +
350 + yield* Effect.forEach(
351 + allRecordings,
352 + ({ group, recording }) =>
353 + recordCommand({
354 + group,
355 + recording,
356 + defaultSleepAfterEnter: config.vhs.sleepAfterEnter,
357 + sharedTapePath,
358 + svgsDir,
359 + asciiDir,
360 + tapesDir,
361 + cliRoot,
362 + vhsHeight: config.vhs.height,
363 + }).pipe(
364 + Effect.tap(() =>
365 + Ref.updateAndGet(completed, c => c + 1).pipe(
366 + Effect.tap(n =>
367 + Effect.sync(() =>
368 + spin.message(
369 + `${drawBar(n, total)} ${color.dim(`${n}/${total}`)} ${group}/${recording.name}`
370 + )
371 + )
372 + )
373 + )
374 + ),
375 + Effect.tapError(err =>
376 + Ref.get(completed).pipe(
377 + Effect.tap(n =>
378 + Effect.sync(() => {
379 + spin.error(
380 + `${drawBar(n, total)} ${color.bold(group)} failed at ${recording.name}`
381 + );
382 + p.log.error(String(err));
383 + })
384 + )
385 + )
386 + )
387 + ),
388 + { concurrency: CONCURRENCY }
389 + );
390 +
391 + yield* Effect.sync(() =>
392 + spin.stop(`${drawBar(total, total)} ${color.dim(`${total}/${total}`)} ${color.green('done')}`)
393 + );
394 +
395 + // Collect file sizes.
396 + let totalBytes = 0n;
397 + for (const { group, recording } of allRecordings) {
398 + for (const filePath of [
399 + path.join(svgsDir, group, `${recording.name}.svg`),
400 + path.join(asciiDir, group, `${recording.name}.ascii`),
401 + ]) {
402 + const stat = yield* fs
403 + .stat(filePath)
404 + .pipe(Effect.orElse(() => Effect.succeed({ size: 0n } as { size: bigint })));
405 + totalBytes += BigInt(stat.size);
406 + }
407 + }
408 +
409 + const totalKB = (Number(totalBytes) / 1024).toFixed(1);
410 +
411 + yield* Effect.sync(() =>
412 + p.note(
413 + [
414 + `${color.bold(String(total))} recordings`,
415 + `${color.bold(totalKB)} KB total`,
416 + color.dim(`${path.relative(process.cwd(), recordingsDir)}/`),
417 + ].join('\n'),
418 + 'Summary'
419 + )
420 + );
421 +
422 + yield* Effect.sync(() => p.outro('Recording complete'));
423 + });
424 +}
425 +
426 +// --- Bootstrap ---
427 +
428 +export const teardown: Teardown = <E, A>(exit: Exit.Exit<E, A>, onExit: (code: number) => void) => {
429 + const shouldFail = Exit.isFailure(exit) && !Cause.isInterruptedOnly(exit.cause);
430 + const errorCode = Number(process.exitCode ?? 1);
431 + onExit(shouldFail ? errorCode : 0);
432 +};
433 +
434 +const ConfigLive = Effect.gen(function* () {
435 + const logLevel = yield* Config.logLevel('COMPOSIO_LOG_LEVEL').pipe(
436 + Config.withDefault(LogLevel.Info)
437 + );
438 +
439 + return Logger.minimumLogLevel(logLevel);
440 +}).pipe(Layer.unwrapEffect, Layer.merge(Layer.setConfigProvider(ConfigProvider.fromEnv())));
441 +
442 +recordAll().pipe(
443 + Effect.provide(ConfigLive),
444 + Effect.provide(Logger.pretty),
445 + Effect.provide(BunContext.layer),
446 + Effect.provide(BunFileSystem.layer),
447 + Effect.map(() => ({ message: 'Process completed successfully.' })),
448 + BunRuntime.runMain({
449 + teardown,
450 + })
451 +);
turbo.jsonc
+14
@@ -51,6 +51,20 @@
51 },
52 "//#clean": {
53 "cache": false
54 + },
55 + "record": {
56 + "dependsOn": ["^build"],
57 + "inputs": [
58 + "src/**",
59 + "scripts/record.ts",
60 + "recordings/recordings.yaml"
61 + ],
62 + "outputs": [
63 + "recordings/tapes/**",
64 + "recordings/svgs/**",
65 + "recordings/ascii/**"
66 + ],
67 + "env": ["COMPOSIO_API_KEY"]
68 }
69 }
70 }