demo-dev 0.0.1-alpha.0

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "demo-dev",
+  "version": "0.0.1-alpha.0",
+  "description": "Generate polished product demo videos with one command. Just give a URL and a prompt.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "demo-dev": "bin/demo-cli.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src",
+    "skills",
+    "README.md",
+    "demo.dev.config.example.json",
+    "tsconfig.json"
+  ],
+  "keywords": [
+    "pi-package",
+    "agent-skill",
+    "pr-demo",
+    "playwright",
+    "ffmpeg",
+    "ghost-cursor"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --dts --format esm --outDir dist --clean",
+    "demo-cli": "tsx src/cli.ts",
+    "demo": "tsx src/cli.ts demo",
+    "init": "tsx src/cli.ts init",
+    "doctor": "tsx src/cli.ts doctor",
+    "config": "tsx src/cli.ts config",
+    "providers": "tsx src/cli.ts providers",
+    "plan": "tsx src/cli.ts plan",
+    "probe": "tsx src/cli.ts probe",
+    "auth": "tsx src/cli.ts auth",
+    "capture": "tsx src/cli.ts capture",
+    "voice": "tsx src/cli.ts voice",
+    "render": "tsx src/cli.ts render",
+    "comment": "tsx src/cli.ts comment",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "citty": "^0.2.2",
+    "ghost-cursor-playwright": "^2.1.0",
+    "playwright": "^1.52.0",
+    "tsx": "^4.19.3",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.30",
+    "tsup": "^8.5.1",
+    "typescript": "^5.8.3"
+  }
+}

package/skills/demo-dev/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: demo-dev
+description: Generate PR demo videos for any web app repo using demo.dev. Use when a user wants an agent to turn a PR, diff, feature branch, or live app flow into a product demo video, especially for authenticated SaaS flows, launch-style walkthroughs, or PR review artifacts.
+allowed-tools: Bash Read Edit Write
+---
+
+# demo-dev
+
+Use this skill when the user wants an agent to create or update a demo video with the `demo.dev` pipeline.
+
+## What this skill does
+
+- Reads project config from `demo.dev.config.json`
+- Runs the pipeline from diff -> plan -> probe -> capture -> render
+- Supports authenticated products via storage state
+- Can also create manual plans for feature-specific demos
+- Produces artifacts like mp4, manifest, captures, and PR comments
+
+## Default workflow
+
+### 1. Inspect config
+
+```bash
+demo-dev config
+demo-dev config --field baseUrl
+demo-dev doctor
+```
+
+If config is missing, run `demo-dev init` or create one from [`../../demo.dev.config.example.json`](../../demo.dev.config.example.json).
+
+See [references/configuration.md](references/configuration.md).
+
+### 2. If auth is required, bootstrap login
+
+```bash
+demo-dev auth:bootstrap \
+  --email you@example.com \
+  --password 'your-password'
+```
+
+This writes storage state using the configured path or `artifacts/storage-state.json`.
+
+### 3. Run the full pipeline
+
+```bash
+demo-dev pr-demo
+```
+
+Or explicitly:
+
+```bash
+demo-dev pr-demo --base-url http://localhost:3000 --base-ref origin/main
+```
+
+### 4. Re-render only when capture and manifest already exist
+
+```bash
+demo-dev render --manifest artifacts/render-manifest.json --out artifacts/pr-demo.mp4
+```
+
+## When to use manual plans
+
+Use a manual plan when:
+- the feature is behind auth or deep navigation
+- the planner cannot infer the correct route from diff
+- the user wants a specific product moment, such as AI editing, onboarding, settings, inbox, or dashboards
+- the user wants a more launch-style product film rather than raw replay
+
+Place plans in an artifacts folder such as:
+
+```bash
+artifacts/manual-plan.json
+```
+
+Then run capture / manifest / render around that plan.
+
+See [references/recipes.md](references/recipes.md).
+
+## Recommended agent behavior
+
+1. Prefer stable, product-facing flows over exhaustive QA coverage.
+2. For the same route, keep one screen object and move the camera instead of cutting to a new screen.
+3. Prefer stable states over loading transitions.
+4. If auth is required, verify storage state early.
+5. If planner output is weak, create a tighter manual plan instead of forcing bad automation.
+6. Keep copy concise and product-first.
+
+## Core commands
+
+Preferred first-class CLI:
+
+```bash
+demo-dev config
+demo-dev providers
+demo-dev plan
+demo-dev probe
+demo-dev auth:bootstrap --email you@example.com --password 'your-password'
+demo-dev capture
+demo-dev voice
+demo-dev manifest
+demo-dev render --manifest artifacts/render-manifest.json --out artifacts/pr-demo.mp4
+demo-dev comment --output-dir artifacts --pr-number 123
+demo-dev pr-demo
+```
+
+Repo-local fallback:
+
+```bash
+npm run config
+npm run providers
+npm run plan
+npm run probe
+npm run auth:bootstrap
+npm run capture
+npm run voice
+npm run manifest
+npm run render -- --manifest artifacts/render-manifest.json --out artifacts/pr-demo.mp4
+npm run comment -- --output-dir artifacts --pr-number 123
+npm run pr-demo
+```
+
+## Outputs to check
+
+- `artifacts/demo-context.json`
+- `artifacts/demo-plan.initial.json`
+- `artifacts/page-probes.json`
+- `artifacts/demo-plan.json`
+- `artifacts/captures.json`
+- `artifacts/render-manifest.json`
+- `artifacts/pr-demo.mp4`
+
+## Troubleshooting
+
+- If the app requires auth, run `auth:bootstrap` first.
+- If the video is wrong, inspect `captures.json` and `render-manifest.json` before changing renderer code.
+- If the planner misses the feature, create a manual plan.
+- If the route is unstable, add project hints in config.
+
+## Share this skill
+
+Other users can install this repo as a pi package or point pi at this repo's `skills/` directory.
+
+Example:
+
+```bash
+pi install /absolute/path/to/demo.dev
+```
+
+or
+
+```bash
+pi install git:github.com/your-org/demo.dev
+```

package/skills/demo-dev/references/configuration.md

@@ -0,0 +1,102 @@
+# demo.dev skill configuration
+
+## Quick bootstrap
+
+A fast way to bootstrap a repo is:
+
+```bash
+demo-dev init
+```
+
+That writes a starter config plus the workflow template.
+
+## Minimal config
+
+Create `demo.dev.config.json` in the target repo:
+
+```json
+{
+  "projectName": "My App",
+  "baseUrl": "http://localhost:3000",
+  "readyUrl": "http://localhost:3000",
+  "devCommand": "npm run dev",
+  "baseRef": "origin/main",
+  "outputDir": "artifacts",
+  "preferredRoutes": ["/", "/dashboard"],
+  "featureHints": ["home", "dashboard"]
+}
+```
+
+## Auth-enabled config
+
+```json
+{
+  "projectName": "My SaaS",
+  "baseUrl": "https://app.example.com",
+  "readyUrl": "https://app.example.com",
+  "baseRef": "origin/main",
+  "outputDir": "artifacts",
+  "storageStatePath": "artifacts/storage-state.json",
+  "saveStorageStatePath": "artifacts/storage-state.json",
+  "preferredRoutes": ["/dashboard", "/settings"],
+  "featureHints": ["dashboard", "settings"],
+  "authRequiredRoutes": ["/dashboard", "/settings"],
+  "auth": {
+    "loginPath": "/login",
+    "emailTarget": { "strategy": "css", "value": "#email" },
+    "passwordTarget": { "strategy": "css", "value": "#password" },
+    "submitTarget": { "strategy": "role", "role": "button", "name": "Login" },
+    "postSubmitWaitMs": 1500
+  }
+}
+```
+
+## Useful overrides
+
+You can override config through:
+
+- CLI flags like `--base-url`, `--output-dir`, `--base-ref`
+- env vars like `DEMO_STORAGE_STATE`, `DEMO_SAVE_STORAGE_STATE`, `DEMO_CONFIG`
+- GitHub Variables in workflow:
+  - `DEMO_BASE_URL`
+  - `DEMO_READY_URL`
+  - `DEMO_DEV_COMMAND`
+  - `DEMO_OUTPUT_DIR`
+
+## AI and TTS environment variables
+
+`demo.dev` uses explicit `DEMO_*` env vars for provider credentials.
+It does not fall back to generic provider keys such as `OPENAI_API_KEY` or `ELEVENLABS_API_KEY`.
+
+Common values:
+
+- `DEMO_OPENAI_API_KEY`
+- `DEMO_OPENAI_BASE_URL`
+- `DEMO_OPENAI_MODEL`
+- `DEMO_AI_PROVIDER`
+- `DEMO_AI_MODEL`
+- `DEMO_TTS_PROVIDER`
+- `DEMO_TTS_MODEL`
+- `DEMO_TTS_VOICE`
+- `DEMO_ELEVENLABS_API_KEY`
+- `DEMO_ELEVENLABS_VOICE_ID`
+
+Example:
+
+```bash
+DEMO_OPENAI_API_KEY=your_openai_key
+DEMO_AI_PROVIDER=openai
+DEMO_TTS_PROVIDER=openai
+```
+
+## Suggested setup for other repos
+
+1. Copy `demo.dev.config.example.json` into the target repo.
+2. Adjust `baseUrl`, `devCommand`, and `auth`.
+3. Validate the repo:
+
+```bash
+demo-dev doctor
+demo-dev config
+demo-dev pr-demo
+```

package/skills/demo-dev/references/recipes.md

@@ -0,0 +1,83 @@
+# demo.dev skill recipes
+
+## Recipe: run on a simple local app
+
+```bash
+npm install
+npx playwright install chromium
+demo-dev doctor
+demo-dev pr-demo
+```
+
+## Recipe: authenticated SaaS
+
+```bash
+demo-dev auth:bootstrap \
+  --email you@example.com \
+  --password 'your-password'
+
+demo-dev pr-demo
+```
+
+## Recipe: OpenAI for planning and TTS
+
+```bash
+DEMO_OPENAI_API_KEY=your_openai_key \
+DEMO_AI_PROVIDER=openai \
+DEMO_TTS_PROVIDER=openai \
+demo-dev pr-demo
+```
+
+This repo only reads `DEMO_*` provider keys for AI and TTS credentials.
+
+## Recipe: inspect plan quality first
+
+```bash
+demo-dev plan
+demo-dev probe
+```
+
+Use this when the feature is not obvious from the diff.
+
+## Recipe: re-render without recapturing
+
+```bash
+demo-dev render --manifest artifacts/render-manifest.json --out artifacts/pr-demo.mp4
+```
+
+## Recipe: add background music
+
+```bash
+DEMO_BGM_PATH=./assets/music/bed.mp3 \
+DEMO_BGM_VOLUME=0.14 \
+DEMO_BGM_DUCKING=0.28 \
+demo-dev pr-demo
+```
+
+This will loop the music bed across the full video, fade it in and out, and lower it automatically while narration is playing.
+
+## Recipe: manual feature film
+
+Use a manual plan when you need a specific flow like:
+- AI editing
+- inbox triage
+- onboarding
+- dashboard walkthrough
+
+Suggested flow:
+
+1. Create `artifacts/manual-plan.json`
+2. Run capture against that plan
+3. Build manifest
+4. Render mp4
+
+## Recipe: PR automation
+
+In CI, run:
+
+```bash
+demo-dev pr-demo
+demo-dev comment --output-dir artifacts
+```
+
+If the app needs a server, set `devCommand` and `readyUrl` in config or GitHub Variables.

package/src/ai/provider.ts

@@ -0,0 +1,254 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { z } from "zod";
+
+const execFileAsync = promisify(execFile);
+
+export type AiProvider = "cursor" | "claude" | "codex" | "openai";
+
+interface ProviderConfig {
+  provider: AiProvider | "auto";
+  model?: string;
+  mandatory: boolean;
+}
+
+const extractJson = (text: string) => {
+  const fenced = text.match(/```json\s*([\s\S]*?)```/i)?.[1];
+  if (fenced) return fenced.trim();
+
+  const firstBrace = text.indexOf("{");
+  const lastBrace = text.lastIndexOf("}");
+  if (firstBrace !== -1 && lastBrace !== -1 && lastBrace > firstBrace) {
+    return text.slice(firstBrace, lastBrace + 1);
+  }
+
+  return text.trim();
+};
+
+const runCommand = async (command: string, args: string[], stdin?: string) => {
+  if (stdin) {
+    const { spawn } = await import("node:child_process");
+    return new Promise<{ stdout: string; stderr: string }>((resolve, reject) => {
+      const child = spawn(command, args, { cwd: process.cwd(), stdio: ["pipe", "pipe", "pipe"] });
+      let stdout = "";
+      let stderr = "";
+      child.stdout.on("data", (d: Buffer) => { stdout += d.toString(); });
+      child.stderr.on("data", (d: Buffer) => { stderr += d.toString(); });
+      child.on("error", reject);
+      child.on("close", (code) => {
+        if (code !== 0) reject(new Error(`${command} exited with ${code}: ${stderr}`));
+        else resolve({ stdout, stderr });
+      });
+      child.stdin.write(stdin);
+      child.stdin.end();
+    });
+  }
+  const { stdout, stderr } = await execFileAsync(command, args, {
+    cwd: process.cwd(),
+    maxBuffer: 1024 * 1024 * 20,
+  });
+  return { stdout, stderr };
+};
+
+const commandExists = async (command: string) => {
+  try {
+    await execFileAsync("which", [command]);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const getConfig = (): ProviderConfig => ({
+  provider: (process.env.DEMO_AI_PROVIDER as ProviderConfig["provider"]) ?? "auto",
+  model: process.env.DEMO_AI_MODEL,
+  mandatory: process.env.DEMO_AI_MANDATORY !== "false",
+});
+
+const getOpenAiConfig = () => {
+  const apiKey = process.env.DEMO_OPENAI_API_KEY;
+  const baseUrl = process.env.DEMO_OPENAI_BASE_URL ?? "https://api.openai.com/v1";
+  const model = process.env.DEMO_OPENAI_MODEL ?? process.env.DEMO_AI_MODEL ?? "gpt-4.1-mini";
+  return { apiKey, baseUrl, model };
+};
+
+const requestFromOpenAi = async <T>(options: {
+  system: string;
+  prompt: string;
+  schema: z.ZodType<T>;
+}) => {
+  const config = getOpenAiConfig();
+  if (!config.apiKey) throw new Error("OpenAI API key not configured. Set DEMO_OPENAI_API_KEY.");
+
+  const response = await fetch(`${config.baseUrl}/chat/completions`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${config.apiKey}`,
+    },
+    body: JSON.stringify({
+      model: config.model,
+      temperature: 0.2,
+      response_format: { type: "json_object" },
+      messages: [
+        { role: "system", content: options.system },
+        { role: "user", content: options.prompt },
+      ],
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`OpenAI request failed: ${response.status} ${await response.text()}`);
+  }
+
+  const payload = z
+    .object({
+      choices: z.array(z.object({ message: z.object({ content: z.string().nullable().optional() }) })),
+    })
+    .parse(await response.json());
+
+  const content = payload.choices[0]?.message.content;
+  if (!content) throw new Error("OpenAI returned empty content");
+  return options.schema.parse(JSON.parse(extractJson(content)));
+};
+
+const requestFromCursor = async <T>(options: {
+  system: string;
+  prompt: string;
+  schema: z.ZodType<T>;
+  model?: string;
+}) => {
+  if (!(await commandExists("cursor-agent"))) throw new Error("cursor-agent not found");
+
+  const stdinContent = `${options.system}\n\n${options.prompt}`;
+  const args = ["--print", "--output-format", "json", "--trust", "--mode", "plan"];
+  if (options.model) args.push("--model", options.model);
+  // Pass prompt via stdin to avoid exceeding argument length limits
+  args.push("-");
+
+  const { stdout } = await runCommand("cursor-agent", args, stdinContent);
+  const payload = JSON.parse(stdout) as { result?: string; is_error?: boolean };
+  if (payload.is_error) throw new Error(payload.result ?? "Cursor provider returned error");
+  if (!payload.result) throw new Error("Cursor provider returned empty result");
+  return options.schema.parse(JSON.parse(extractJson(payload.result)));
+};
+
+const requestFromClaude = async <T>(options: {
+  system: string;
+  prompt: string;
+  schema: z.ZodType<T>;
+  model?: string;
+}) => {
+  if (!(await commandExists("claude"))) throw new Error("claude not found");
+
+  const stdinContent = `${options.prompt}\n\nReturn strict JSON only.`;
+  const args = [
+    "-p",
+    "--output-format",
+    "json",
+    "--system-prompt",
+    options.system,
+    "--allowedTools",
+    "",
+  ];
+  if (options.model) args.push("--model", options.model);
+  // Pass prompt via stdin to avoid exceeding argument length limits
+  args.push("-");
+
+  const { stdout } = await runCommand("claude", args, stdinContent);
+  const payload = JSON.parse(stdout) as { result?: string; is_error?: boolean };
+  if (payload.is_error) throw new Error(payload.result ?? "Claude provider returned error");
+  if (!payload.result) throw new Error("Claude provider returned empty result");
+  return options.schema.parse(JSON.parse(extractJson(payload.result)));
+};
+
+const requestFromCodex = async <T>(options: {
+  system: string;
+  prompt: string;
+  schema: z.ZodType<T>;
+  model?: string;
+}) => {
+  if (!(await commandExists("codex"))) throw new Error("codex not found");
+
+  const tempDir = await mkdtemp(join(tmpdir(), "demo-dev-codex-"));
+  const outputPath = join(tempDir, "last-message.json");
+
+  try {
+    const fullPrompt = `${options.system}\n\n${options.prompt}\n\nReturn strict JSON only.`;
+    const args = [
+      "exec",
+      "--skip-git-repo-check",
+      "--sandbox",
+      "read-only",
+      "--output-last-message",
+      outputPath,
+    ];
+    if (options.model) args.push("--model", options.model);
+    args.push(fullPrompt);
+
+    await runCommand("codex", args);
+    const content = await readFile(outputPath, "utf8");
+    return options.schema.parse(JSON.parse(extractJson(content)));
+  } finally {
+    await rm(tempDir, { recursive: true, force: true }).catch(() => undefined);
+  }
+};
+
+const PROVIDERS: readonly AiProvider[] = ["cursor", "claude", "codex", "openai"];
+
+export const listAvailableProviders = async () => {
+  const openaiConfig = getOpenAiConfig();
+  return {
+    cursor: await commandExists("cursor-agent"),
+    claude: await commandExists("claude"),
+    codex: await commandExists("codex"),
+    openai: Boolean(openaiConfig.apiKey),
+    selected: getConfig().provider,
+  };
+};
+
+export const requestAiJson = async <T>(options: {
+  system: string;
+  prompt: string;
+  schema: z.ZodType<T>;
+  temperature?: number;
+}) => {
+  const config = getConfig();
+  const providers = config.provider === "auto" ? PROVIDERS : [config.provider];
+  const errors: string[] = [];
+
+  for (const provider of providers) {
+    let prompt = options.prompt;
+
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      try {
+        switch (provider) {
+          case "cursor":
+            return await requestFromCursor({ ...options, prompt, model: config.model });
+          case "claude":
+            return await requestFromClaude({ ...options, prompt, model: config.model });
+          case "codex":
+            return await requestFromCodex({ ...options, prompt, model: config.model });
+          case "openai":
+            return await requestFromOpenAi({ ...options, prompt });
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (attempt === 0) {
+          prompt = `${options.prompt}\n\nYour previous response failed validation with this error:\n${message}\n\nReturn corrected strict JSON only.`;
+          continue;
+        }
+        errors.push(`${provider}: ${message}`);
+        break;
+      }
+    }
+
+    if (config.provider !== "auto") break;
+  }
+
+  if (!config.mandatory) return null;
+  throw new Error(`No AI provider succeeded. ${errors.join(" | ")}`);
+};