@contractspec/example.video-docs-terminal 2.1.0

package/src/build-tutorial.ts

@@ -0,0 +1,120 @@
+// ---------------------------------------------------------------------------
+// Build Tutorial Video -- Construct a multi-scene VideoProject from CLI tutorials
+// ---------------------------------------------------------------------------
+
+import type { VideoProject } from '@contractspec/lib.contracts-integrations/integrations/providers/video';
+import { VIDEO_FORMATS } from '@contractspec/lib.video-gen/design/layouts';
+import type { CliTutorial } from './sample-tutorials';
+
+const DEFAULT_FPS = 30;
+const DEFAULT_SCENE_DURATION_SECONDS = 12;
+
+/** Options for building a tutorial video. */
+export interface BuildTutorialOptions {
+  /** Duration per scene in seconds. Default: 12. */
+  sceneDurationSeconds?: number;
+  /** FPS. Default: 30. */
+  fps?: number;
+  /** Terminal prompt string. Default: "$ ". */
+  prompt?: string;
+}
+
+/**
+ * Build a VideoProject from a single CLI tutorial.
+ *
+ * Creates a single-scene project using the TerminalDemo composition.
+ *
+ * @example
+ * ```ts
+ * import { buildTutorialVideo } from "@contractspec/example.video-docs-terminal/build-tutorial";
+ * import { initTutorial } from "@contractspec/example.video-docs-terminal/sample-tutorials";
+ *
+ * const project = buildTutorialVideo(initTutorial);
+ * // project.scenes[0].compositionId === "TerminalDemo"
+ * ```
+ */
+export function buildTutorialVideo(
+  tutorial: CliTutorial,
+  options?: BuildTutorialOptions
+): VideoProject {
+  const fps = options?.fps ?? DEFAULT_FPS;
+  const sceneDuration =
+    options?.sceneDurationSeconds ?? DEFAULT_SCENE_DURATION_SECONDS;
+  const durationInFrames = sceneDuration * fps;
+
+  return {
+    id: `tutorial-${tutorial.id}-${Date.now().toString(36)}`,
+    scenes: [
+      {
+        id: `scene-${tutorial.id}`,
+        compositionId: 'TerminalDemo',
+        props: {
+          title: tutorial.title,
+          subtitle: tutorial.subtitle,
+          lines: tutorial.lines,
+          terminalTitle: tutorial.terminalTitle,
+          prompt: options?.prompt ?? '$ ',
+          summary: tutorial.summary,
+        },
+        durationInFrames,
+      },
+    ],
+    totalDurationInFrames: durationInFrames,
+    fps,
+    format: VIDEO_FORMATS.landscape,
+  };
+}
+
+/**
+ * Build a multi-scene VideoProject from an array of CLI tutorials.
+ *
+ * Each tutorial becomes one scene in the project, played in order.
+ * Useful for creating a comprehensive CLI walkthrough video covering
+ * init → build → validate → deploy.
+ *
+ * @example
+ * ```ts
+ * import { buildTutorialSuite } from "@contractspec/example.video-docs-terminal/build-tutorial";
+ * import { allTutorials } from "@contractspec/example.video-docs-terminal/sample-tutorials";
+ *
+ * const project = buildTutorialSuite(allTutorials);
+ * // project.scenes.length === 4
+ * // Total: ~48 seconds (4 × 12s)
+ * ```
+ */
+export function buildTutorialSuite(
+  tutorials: CliTutorial[],
+  options?: BuildTutorialOptions
+): VideoProject {
+  const fps = options?.fps ?? DEFAULT_FPS;
+  const sceneDuration =
+    options?.sceneDurationSeconds ?? DEFAULT_SCENE_DURATION_SECONDS;
+  const durationInFrames = sceneDuration * fps;
+
+  const scenes = tutorials.map((tutorial) => ({
+    id: `scene-${tutorial.id}`,
+    compositionId: 'TerminalDemo',
+    props: {
+      title: tutorial.title,
+      subtitle: tutorial.subtitle,
+      lines: tutorial.lines,
+      terminalTitle: tutorial.terminalTitle,
+      prompt: options?.prompt ?? '$ ',
+      summary: tutorial.summary,
+    },
+    durationInFrames,
+  }));
+
+  const totalDurationInFrames = scenes.reduce(
+    (sum, s) => sum + s.durationInFrames,
+    0
+  );
+
+  return {
+    id: `tutorial-suite-${Date.now().toString(36)}`,
+    scenes,
+    totalDurationInFrames,
+    fps,
+    format: VIDEO_FORMATS.landscape,
+  };
+}

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './video-docs-terminal.docblock';

package/src/docs/video-docs-terminal.docblock.ts

@@ -0,0 +1,93 @@
+import type { DocBlock } from '@contractspec/lib.contracts-spec/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts-spec/docs';
+
+const blocks: DocBlock[] = [
+  {
+    id: 'docs.examples.video-docs-terminal',
+    title: 'Video Docs Terminal (example)',
+    summary:
+      'Generate terminal demo videos from CLI walkthroughs using the TerminalDemo composition and ScriptGenerator.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/examples/video-docs-terminal',
+    tags: ['video', 'documentation', 'terminal', 'cli', 'example'],
+    body: `## What this example shows
+
+- Defining CLI tutorials as structured \`CliTutorial\` objects with \`TerminalLine\` arrays.
+- Building single-scene and multi-scene \`VideoProject\` instances using the \`TerminalDemo\` composition.
+- Using \`ScriptGenerator\` (deterministic, no LLM) to generate narration from tutorial content briefs.
+- Assembling a full documentation video covering init, build, validate, and deploy workflows.
+
+## Key concepts
+
+- **CliTutorial**: Combines \`TerminalLine[]\` (commands + output) with a \`ContentBrief\` for narration.
+- **TerminalDemo**: The Remotion composition that renders animated terminal sessions.
+- **ScriptGenerator**: Produces narration scripts from content briefs. Deterministic by default.
+- **VideoProject**: The output scene graph -- one scene per tutorial, ready for rendering or preview.
+
+## Notes
+
+- No LLM or voice provider is needed -- the pipeline is fully deterministic.
+- Each tutorial maps to one \`TerminalDemo\` scene in the final video project.
+- The example produces the \`VideoProject\` data structure, not rendered MP4. Use \`LocalRenderer\` for final output.
+`,
+  },
+  {
+    id: 'docs.examples.video-docs-terminal.usage',
+    title: 'Video Docs Terminal -- Usage',
+    summary:
+      'How to generate terminal demo videos and narration from CLI tutorials.',
+    kind: 'usage',
+    visibility: 'public',
+    route: '/docs/examples/video-docs-terminal/usage',
+    tags: ['video', 'terminal', 'usage'],
+    body: `## Usage
+
+### Build a single tutorial video
+
+\`\`\`ts
+import { buildTutorialVideo } from "@contractspec/example.video-docs-terminal/build-tutorial";
+import { initTutorial } from "@contractspec/example.video-docs-terminal/sample-tutorials";
+
+const project = buildTutorialVideo(initTutorial);
+
+console.log(project.scenes.length);          // 1
+console.log(project.scenes[0].compositionId); // "TerminalDemo"
+console.log(project.totalDurationInFrames);   // 360 (12s × 30fps)
+\`\`\`
+
+### Build a multi-scene tutorial suite
+
+\`\`\`ts
+import { buildTutorialSuite } from "@contractspec/example.video-docs-terminal/build-tutorial";
+import { allTutorials } from "@contractspec/example.video-docs-terminal/sample-tutorials";
+
+const project = buildTutorialSuite(allTutorials);
+
+console.log(project.scenes.length); // 4 (init, build, validate, deploy)
+\`\`\`
+
+### Generate narration
+
+\`\`\`ts
+import { generateTutorialNarration } from "@contractspec/example.video-docs-terminal/generate-narration";
+import { buildTutorial } from "@contractspec/example.video-docs-terminal/sample-tutorials";
+
+const narration = await generateTutorialNarration(buildTutorial);
+
+console.log(narration.fullText);              // Full narration text
+console.log(narration.segments.length);       // Per-scene segments
+console.log(narration.estimatedDurationSeconds); // ~12s
+\`\`\`
+
+## Guardrails
+
+- Keep terminal lines concise -- long output slows the typing animation.
+- Target 10-15 lines per tutorial for optimal pacing at 12 seconds per scene.
+- The \`summary\` field is displayed as a call-out after the terminal completes -- keep it to one sentence.
+- Use \`"technical"\` narration style for documentation videos and \`"professional"\` for marketing.
+`,
+  },
+];
+
+registerDocBlocks(blocks);

package/src/example.ts

@@ -0,0 +1,32 @@
+import { defineExample } from '@contractspec/lib.contracts-spec';
+
+const example = defineExample({
+  meta: {
+    key: 'video-docs-terminal',
+    version: '1.0.0',
+    title: 'Video Docs Terminal',
+    description:
+      'Generate terminal demo videos from CLI walkthroughs using the TerminalDemo composition and ScriptGenerator.',
+    kind: 'script',
+    visibility: 'public',
+    stability: 'experimental',
+    owners: ['@platform.core'],
+    tags: ['video', 'documentation', 'terminal', 'cli', 'tutorial'],
+  },
+  docs: {
+    rootDocId: 'docs.examples.video-docs-terminal',
+    usageDocId: 'docs.examples.video-docs-terminal.usage',
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.video-docs-terminal',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['markdown'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+});
+
+export default example;

package/src/generate-narration.ts

@@ -0,0 +1,70 @@
+// ---------------------------------------------------------------------------
+// Generate Narration -- Use ScriptGenerator to produce narration for tutorials
+// ---------------------------------------------------------------------------
+
+import { ScriptGenerator } from '@contractspec/lib.video-gen/generators/script-generator';
+import type { NarrationScript } from '@contractspec/lib.video-gen/generators/script-generator';
+import type { NarrationConfig } from '@contractspec/lib.contracts-integrations/integrations/providers/video';
+import type { CliTutorial } from './sample-tutorials';
+
+/** Options for narration generation. */
+export interface GenerateNarrationOptions {
+  /** Narration style. Default: "technical". */
+  style?: NarrationConfig['style'];
+}
+
+/**
+ * Generate a narration script for a single CLI tutorial.
+ *
+ * Uses the deterministic ScriptGenerator (no LLM) to produce
+ * narration text from the tutorial's content brief.
+ *
+ * @example
+ * ```ts
+ * import { generateTutorialNarration } from "@contractspec/example.video-docs-terminal/generate-narration";
+ * import { buildTutorial } from "@contractspec/example.video-docs-terminal/sample-tutorials";
+ *
+ * const narration = await generateTutorialNarration(buildTutorial);
+ * console.log(narration.fullText);
+ * console.log(narration.estimatedDurationSeconds); // ~12s
+ * ```
+ */
+export async function generateTutorialNarration(
+  tutorial: CliTutorial,
+  options?: GenerateNarrationOptions
+): Promise<NarrationScript> {
+  const generator = new ScriptGenerator();
+  const style = options?.style ?? 'technical';
+
+  return generator.generate(tutorial.brief, { enabled: true, style });
+}
+
+/**
+ * Generate narration scripts for all tutorials in a suite.
+ *
+ * Returns a map of tutorial ID → narration script, useful for
+ * aligning narration with the multi-scene video project.
+ *
+ * @example
+ * ```ts
+ * import { generateSuiteNarration } from "@contractspec/example.video-docs-terminal/generate-narration";
+ * import { allTutorials } from "@contractspec/example.video-docs-terminal/sample-tutorials";
+ *
+ * const narrations = await generateSuiteNarration(allTutorials);
+ * // narrations.get("init")?.fullText — narration for the init tutorial
+ * // narrations.get("build")?.fullText — narration for the build tutorial
+ * ```
+ */
+export async function generateSuiteNarration(
+  tutorials: CliTutorial[],
+  options?: GenerateNarrationOptions
+): Promise<Map<string, NarrationScript>> {
+  const results = await Promise.all(
+    tutorials.map(async (tutorial) => {
+      const script = await generateTutorialNarration(tutorial, options);
+      return [tutorial.id, script] as const;
+    })
+  );
+
+  return new Map(results);
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './sample-tutorials';
+export * from './build-tutorial';
+export * from './generate-narration';
+
+export { default as example } from './example';
+
+import './docs';

package/src/sample-tutorials.ts

@@ -0,0 +1,241 @@
+// ---------------------------------------------------------------------------
+// Sample CLI Tutorials for Terminal Demo Video Generation
+// ---------------------------------------------------------------------------
+
+import type { TerminalLine } from '@contractspec/lib.video-gen/compositions/primitives/terminal';
+import type { ContentBrief } from '@contractspec/lib.content-gen/types';
+
+/**
+ * A CLI tutorial definition combining terminal lines with a content brief
+ * for narration generation.
+ */
+export interface CliTutorial {
+  /** Tutorial identifier */
+  id: string;
+  /** Display title for the scene */
+  title: string;
+  /** Subtitle shown below the title */
+  subtitle?: string;
+  /** Terminal window title */
+  terminalTitle: string;
+  /** Terminal lines (commands + output) */
+  lines: TerminalLine[];
+  /** Summary text shown after the terminal completes */
+  summary?: string;
+  /** Content brief used for narration generation */
+  brief: ContentBrief;
+}
+
+// -- Init Tutorial ----------------------------------------------------------
+
+/**
+ * Tutorial: Initialize a new ContractSpec project.
+ */
+export const initTutorial: CliTutorial = {
+  id: 'init',
+  title: 'Initialize a Project',
+  subtitle: 'Set up a new ContractSpec workspace in seconds',
+  terminalTitle: '~/projects',
+  lines: [
+    { text: 'contractspec init my-api', type: 'command' },
+    { text: 'Creating project my-api...', type: 'output', delay: 15 },
+    { text: '  ├── contracts/', type: 'output', delay: 5 },
+    { text: '  ├── generated/', type: 'output', delay: 5 },
+    { text: '  ├── contractspec.config.ts', type: 'output', delay: 5 },
+    { text: '  └── package.json', type: 'output', delay: 5 },
+    { text: '✓ Project initialized', type: 'success', delay: 10 },
+    { text: 'cd my-api', type: 'command', delay: 15 },
+    { text: 'contractspec status', type: 'command', delay: 15 },
+    {
+      text: '0 contracts · 0 generated files · ready',
+      type: 'output',
+      delay: 10,
+    },
+  ],
+  summary: 'Your project is ready. Define contracts next.',
+  brief: {
+    title: 'Initialize a ContractSpec Project',
+    summary:
+      'The init command scaffolds a new workspace with contracts, generated output, and configuration.',
+    problems: [
+      'Setting up API projects manually is tedious and error-prone',
+      'Teams need a consistent project structure from day one',
+    ],
+    solutions: [
+      'One command creates the entire project scaffold',
+      'Standard structure ensures consistency across teams',
+    ],
+    audience: {
+      role: 'Developer',
+      painPoints: ['Manual project setup', 'Inconsistent project structure'],
+    },
+    callToAction: 'Run contractspec init to get started.',
+  },
+};
+
+// -- Build Tutorial ---------------------------------------------------------
+
+/**
+ * Tutorial: Build and generate code from contracts.
+ */
+export const buildTutorial: CliTutorial = {
+  id: 'build',
+  title: 'Build from Contracts',
+  subtitle: 'Generate all surfaces from a single spec',
+  terminalTitle: '~/projects/my-api',
+  lines: [
+    { text: '# Define a contract first', type: 'comment' },
+    { text: 'contractspec build', type: 'command', delay: 15 },
+    { text: 'Building 3 contracts...', type: 'output', delay: 15 },
+    { text: '  → CreateUser   REST + GraphQL + DB', type: 'output', delay: 8 },
+    { text: '  → ListUsers    REST + GraphQL', type: 'output', delay: 8 },
+    { text: '  → DeleteUser   REST + GraphQL + DB', type: 'output', delay: 8 },
+    { text: '✓ 18 files generated in 0.4s', type: 'success', delay: 12 },
+    { text: 'contractspec status', type: 'command', delay: 15 },
+    {
+      text: '3 contracts · 18 generated files · all up to date',
+      type: 'output',
+      delay: 10,
+    },
+  ],
+  summary: '3 contracts → 18 files. One spec, every surface.',
+  brief: {
+    title: 'Build from Contracts',
+    summary:
+      'The build command reads your contract definitions and generates REST, GraphQL, DB schemas, and more.',
+    problems: [
+      'Manually writing the same logic across REST, GraphQL, and DB',
+      'Generated code drifts out of sync with the spec',
+    ],
+    solutions: [
+      'Deterministic build: same spec always produces the same output',
+      'All surfaces generated in a single pass',
+    ],
+    metrics: [
+      '18 files from 3 contracts in 0.4 seconds',
+      'Zero manual synchronization',
+    ],
+    audience: {
+      role: 'Developer',
+      painPoints: ['Cross-surface code duplication', 'Schema drift'],
+    },
+    callToAction: 'Run contractspec build after defining your contracts.',
+  },
+};
+
+// -- Validate Tutorial ------------------------------------------------------
+
+/**
+ * Tutorial: Validate contracts before building.
+ */
+export const validateTutorial: CliTutorial = {
+  id: 'validate',
+  title: 'Validate Contracts',
+  subtitle: 'Catch errors before they reach production',
+  terminalTitle: '~/projects/my-api',
+  lines: [
+    { text: 'contractspec validate', type: 'command' },
+    { text: 'Validating 3 contracts...', type: 'output', delay: 15 },
+    { text: '  ✓ CreateUser   schema valid', type: 'success', delay: 8 },
+    { text: '  ✓ ListUsers    schema valid', type: 'success', delay: 8 },
+    {
+      text: '  ✗ DeleteUser   missing required field "reason"',
+      type: 'error',
+      delay: 8,
+    },
+    { text: '', type: 'output', delay: 5 },
+    { text: '2 passed · 1 failed', type: 'output', delay: 10 },
+    { text: '# Fix the contract and re-validate', type: 'comment', delay: 15 },
+    { text: 'contractspec validate', type: 'command', delay: 15 },
+    { text: '  ✓ CreateUser   schema valid', type: 'success', delay: 8 },
+    { text: '  ✓ ListUsers    schema valid', type: 'success', delay: 8 },
+    { text: '  ✓ DeleteUser   schema valid', type: 'success', delay: 8 },
+    { text: '✓ All 3 contracts valid', type: 'success', delay: 10 },
+  ],
+  summary: 'Validate early, validate often.',
+  brief: {
+    title: 'Validate Contracts',
+    summary:
+      'The validate command checks all contracts against their schemas before generating code.',
+    problems: [
+      'Invalid schemas slip through to production',
+      'Catching errors late in the pipeline costs time',
+    ],
+    solutions: [
+      'Pre-build validation catches schema errors instantly',
+      'Clear error messages pinpoint exactly what needs fixing',
+    ],
+    audience: {
+      role: 'Developer',
+      painPoints: ['Invalid schemas in production', 'Late error detection'],
+    },
+    callToAction: 'Run contractspec validate as part of your CI pipeline.',
+  },
+};
+
+// -- Deploy Tutorial --------------------------------------------------------
+
+/**
+ * Tutorial: Deploy generated artifacts.
+ */
+export const deployTutorial: CliTutorial = {
+  id: 'deploy',
+  title: 'Deploy Artifacts',
+  subtitle: 'Ship generated code to production',
+  terminalTitle: '~/projects/my-api',
+  lines: [
+    { text: 'contractspec build --production', type: 'command' },
+    {
+      text: '✓ 18 files generated (production mode)',
+      type: 'success',
+      delay: 15,
+    },
+    { text: 'contractspec publish --dry-run', type: 'command', delay: 15 },
+    {
+      text: 'Publishing @my-api/contracts v1.2.0...',
+      type: 'output',
+      delay: 12,
+    },
+    { text: '  → npm pack (dry run)', type: 'output', delay: 8 },
+    { text: '  → 3 contracts, 18 generated files', type: 'output', delay: 8 },
+    { text: '  → Package size: 24.3 KB', type: 'output', delay: 8 },
+    {
+      text: '✓ Dry run complete -- ready to publish',
+      type: 'success',
+      delay: 10,
+    },
+    { text: 'contractspec publish', type: 'command', delay: 15 },
+    { text: '✓ Published @my-api/contracts@1.2.0', type: 'success', delay: 15 },
+  ],
+  summary: 'From spec to production in one pipeline.',
+  brief: {
+    title: 'Deploy Artifacts',
+    summary:
+      'Build in production mode and publish your generated contracts as an npm package.',
+    problems: [
+      'Deploying hand-written API code is risky and manual',
+      'Teams need confidence that generated code matches the spec',
+    ],
+    solutions: [
+      'Production builds are deterministic and reproducible',
+      'Dry-run publishing catches packaging issues before release',
+    ],
+    metrics: [
+      '24.3 KB package with 3 contracts and 18 files',
+      'Entire pipeline runs in seconds',
+    ],
+    audience: {
+      role: 'DevOps Engineer',
+      painPoints: ['Manual deployment processes', 'Spec-to-production drift'],
+    },
+    callToAction: 'Add contractspec publish to your CI/CD pipeline.',
+  },
+};
+
+/** All sample tutorials in recommended presentation order. */
+export const allTutorials: CliTutorial[] = [
+  initTutorial,
+  buildTutorial,
+  validateTutorial,
+  deployTutorial,
+];

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@contractspec/tool.typescript/react-library.json",
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"],
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  }
+}

package/tsdown.config.js

@@ -0,0 +1,3 @@
+import { moduleLibrary } from '@contractspec/tool.bun';
+
+export default { ...moduleLibrary };