@devmotion/cli 0.6.3 → 0.8.0

package/README.md

@@ -202,6 +202,19 @@ devmotion mcp --print-config   # print the JSON config snippet to paste into you
 The CLI MCP and the SaaS MCP share the same `mutations.ts` code path, so an
 agent that knows how to drive one knows how to drive the other.
 
+Install the Agent Skill and MCP configuration for Claude Code, Codex, or both:
+
+```bash
+npx @devmotion/cli setup
+# Non-interactive:
+npx @devmotion/cli setup --agent both --scope global
+```
+
+Global skills are installed to `~/.claude/skills/devmotion/SKILL.md` and
+`~/.agents/skills/devmotion/SKILL.md`. Use `--scope project` for repository-local
+configuration. The skill prefers the type-safe MCP operations over editing scene
+HTML by hand.
+
 ---
 
 ## Two ways to use DevMotion

package/dist/index.js

@@ -617,369 +617,155 @@ var mcpCommand = defineCommand4({
 
 // src/commands/setup.ts
 import { defineCommand as defineCommand5 } from "citty";
-import { writeFile as writeFile2, mkdir as mkdir2, readFile } from "fs/promises";
-import { join as join7 } from "path";
 import { existsSync as existsSync6 } from "fs";
-var SKILLS = {
-  "devmotion.md": `# DevMotion \u2014 HTML-first Video Tooling
-
-DevMotion is a code-driven video creation platform. Projects are defined as HTML files with \`data-dm-*\` attributes \u2014 every annotated element becomes a layer on the timeline.
-
-## Project Structure
-
-\`\`\`
-my-video/
-\u251C\u2500\u2500 devmotion.json     # Project config (resolution, FPS, duration, scenes)
-\u251C\u2500\u2500 scenes/
-\u2502   \u251C\u2500\u2500 intro.html     # One HTML file per scene
-\u2502   \u2514\u2500\u2500 outro.html
-\u2514\u2500\u2500 assets/            # Images, videos, fonts
-\`\`\`
-
-## Layers
-
-Each HTML element with \`data-dm-*\` attributes is a layer. Two syntaxes:
-
-### 1. Generic HTML (\`data-dm-*\` attributes)
-\`\`\`html
-<div data-dm-id="my-layer"
-     data-dm-enter="fade-in"
-     data-dm-enter-time="0.5"
-     data-dm-duration="0.8"
-     data-dm-easing="ease-out"
-     data-dm-keyframe-opacity="0:0; 0.5:1; 4:1; 5:0"
-     style="color: white; font-size: 48px;">
-  Hello World
-</div>
-\`\`\`
-
-### 2. Premium \`<dm-*>\` Custom Elements
-16 specialized layer types: dm-phone, dm-video, dm-audio, dm-text, dm-image, dm-browser, dm-laptop, dm-terminal, dm-captions, dm-code, dm-button, dm-icon, dm-shape, dm-html, dm-mouse, dm-group
-
-\`\`\`html
-<dm-phone data-dm-id="demo"
-          data-dm-enter="slide-in-right"
-          data-dm-enter-time="1.5"
-          data-dm-duration="0.6"
-          src="./assets/screen.mp4">
-</dm-phone>
-\`\`\`
-
-## Key Attributes
-
-| Attribute | Description | Example |
-|-----------|-------------|---------|
-| \`data-dm-id\` | Unique layer identifier | \`"title"\` |
-| \`data-dm-enter\` | Entry animation preset | \`"fade-in"\` |
-| \`data-dm-exit\` | Exit animation preset | \`"fade-out"\` |
-| \`data-dm-enter-time\` | Start time in seconds | \`"0.5"\` |
-| \`data-dm-duration\` | How long on screen | \`"2.0"\` |
-| \`data-dm-easing\` | Animation easing | \`"ease-out"\` |
-| \`data-dm-track\` | Timeline track (z-order) | \`"0"\` |
-| \`data-dm-locked\` | Lock layer from edits | \`"true"\` |
-| \`data-dm-hidden\` | Hide layer | (boolean attribute) |
-| \`data-dm-keyframe-*\` | Property animation | \`data-dm-keyframe-opacity="0:0; 1:1@ease-out"\` |
-| \`data-dm-word-separator\` | Optional separator for \`word-reveal\` text keyframes | \`" "\` |
-| \`data-dm-grid-increment\` | Grid step for \`snap-grid\` quantized keyframes | \`"0.25"\` |
-
-### \`dm-text\` reveal transition attributes
-
-For polished letter/word reveals, combine \`@char-reveal\` or \`@word-reveal\`
-with per-fragment transition attributes:
-
-| Attribute | Description | Example |
-|-----------|-------------|---------|
-| \`transition-effects\` | Comma-separated effects for new characters/words | \`"fade,slide-up,blur"\` |
-| \`transition-duration\` | Per-fragment transition duration in ms | \`"350"\` |
-| \`transition-easing\` | Easing for each fragment | \`"ease-in-quad"\` |
-| \`slide-distance\` | Slide distance as % of project width | \`"2.7"\` |
-| \`scale-from\` | Initial scale for \`scale\` effect | \`"0.5"\` |
-| \`blur-amount\` | Initial blur as % of project width | \`"0.78"\` |
-| \`transition-color-from\` | Optional starting color | \`"#7de3ff"\` |
-| \`expand-on-reveal\` | Expand each fragment from zero width | \`"true"\` |
-
-## Keyframe Interpolation Syntax
-
-Keyframes use \`time:value@strategy\`. The \`@strategy\` suffix selects the
-interpolation family automatically:
-
-- Continuous easing: \`linear\`, \`ease-out\`, \`ease-in-out\`, \`ease-out-quad\`, etc.
-- Discrete jumps: \`step-start\`, \`step-end\`, \`step-mid\`
-- Quantized values: \`integer\`, \`snap-grid\` (set \`data-dm-grid-increment\`)
-- Text reveals for \`props.content\`: \`char-reveal\`, \`word-reveal\`
-
-\`\`\`html
-<dm-text
-  data-dm-id="headline"
-  data-dm-keyframe-props-content="0:@char-reveal; 1.4:Welcome to DevMotion@char-reveal"
->
-  Welcome to DevMotion
-</dm-text>
-
-<dm-text
-  data-dm-id="subtitle"
-  transition-effects="fade,slide-up,blur"
-  transition-duration="350"
-  transition-easing="ease-in-quad"
-  slide-distance="2.7"
-  blur-amount="0.78"
-  data-dm-word-separator=" "
-  data-dm-keyframe-props-content="2.7:@word-reveal; 4.1:a prompt away from being a producer@word-reveal"
->
-  a prompt away from being a producer
-</dm-text>
-
-<dm-shape
-  data-dm-id="meter"
-  data-dm-grid-increment="0.25"
-  data-dm-keyframe-scale-x="0:0@snap-grid; 1:1@snap-grid"
-></dm-shape>
-\`\`\`
-
-## Presets
-
-fade-in, fade-out, reveal-up, reveal-right, reveal-left, slide-in-left, slide-in-right, slide-in-top, slide-in-bottom, slide-out-left, slide-out-right, wipe-down, wipe-right, scale-in, scale-out, pop, bounce, bounce-in, rotate-in, spin, pulse, shake, float, glow, zoom-in, zoom-out, flip-in-x, flip-in-y, swing
-
-## Easing Functions
-
-linear, ease-in, ease-out, ease-in-out, ease-in-quad/out/in-out, ease-in-cubic/out/in-out, ease-in-quart/out/in-out, ease-in-quint/out/in-out, ease-in-sine/out/in-out, ease-in-expo/out/in-out, ease-in-circ/out/in-out, ease-in-back/out/in-out, ease-in-bounce/out/in-out, ease-in-elastic/out/in-out
-
-## MCP Tools (available when devmotion MCP is connected)
-
-- \`get_project\` \u2014 Get current project state with all layers
-- \`create_layer\` \u2014 Add a new layer to the timeline
-- \`edit_layer\` \u2014 Modify an existing layer
-- \`remove_layer\` \u2014 Delete a layer
-- \`configure_project\` \u2014 Change project settings (resolution, FPS, etc.)
-
-## Commands
-
-- \`devmotion init <name>\` \u2014 Scaffold new project
-- \`devmotion preview\` \u2014 Open the local Studio for visual editing and render preview
-- \`devmotion render\` \u2014 Render to MP4 (auto-spawns Studio if needed)
-- \`devmotion add-scene <name>\` \u2014 Add a scene (--with gsap|lottie|bare)
-- \`devmotion mcp\` \u2014 Run the local MCP server over stdio
-- \`devmotion mcp --print-config\` \u2014 Print a stdio MCP config snippet
-- \`devmotion doctor\` \u2014 Check ffmpeg & Playwright are installed
-
-## If the \`devmotion\` command is not found
-
-These commands need the DevMotion CLI on the machine. If \`devmotion\` is missing
-(\`command not found\`), do ONE of the following before retrying:
-
-- Run a command without installing globally: prefix it with npx, e.g.
-  \`npx @devmotion/cli render\` or \`npx @devmotion/cli preview\`.
-- Or install it once globally: \`npm i -g @devmotion/cli\`, then use the bare
-  \`devmotion ...\` commands.
-
-Prefer \`npx @devmotion/cli ...\` when you just need to run a single command.
-`,
-  "devmotion-init.md": `# /devmotion-init \u2014 Scaffold a New DevMotion Project
-
-Run \`devmotion init <name>\` to create a new video project from scratch.
-
-## What it does
-
-1. Creates a project directory with:
-   - \`devmotion.json\` \u2014 1920\xD71080, 30fps, 10s, dark background
-   - \`scenes/intro.html\` \u2014 Starter scene with a title and a phone demo
-   - \`assets/\` \u2014 Empty directory for media files
-   - \`.gitignore\` \u2014 Ignores build artifacts
-   - \`README.md\` \u2014 Quick start guide
-
-2. The generated \`intro.html\` includes:
-   - A centered title div with \`data-dm-*\` attributes (fade-in, keyframed opacity)
-   - A \`<dm-phone>\` element with slide-in-right preset
-
-## Usage
-
-\`\`\`
-/devmotion-init my-product-demo
-\`\`\`
-
-Always run this as the FIRST step when a user asks to create a video. After scaffolding:
-- Use the MCP \`create_layer\` tool (or edit HTML directly) to add content
-- Use \`devmotion preview\` to see the result in the Studio
-- Use \`devmotion render\` to export MP4
-
-## Important
-
-- The command creates a subdirectory in the current working directory
-- After init, cd into the new directory before using other devmotion commands
-- If \`devmotion\` is not found, run it via npx \u2014 \`npx @devmotion/cli init <name>\`
-  \u2014 or install once with \`npm i -g @devmotion/cli\`.
-`,
-  "devmotion-add-layer.md": `# /devmotion-add-layer \u2014 Add a Layer to the Timeline
-
-Adds a new animated layer to the current DevMotion project.
-
-## When MCP is connected
-
-Use the \`create_layer\` MCP tool. Required parameters:
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| \`layerType\` | string | One of: phone, video, audio, text, image, browser, laptop, terminal, captions, code, button, icon, shape, html, mouse, group |
-| \`enterTime\` | number | Start time in seconds (default: 0) |
-| \`exitTime\` | number | End time (optional) |
-| \`track\` | integer | Z-order track (default: 0) |
-| \`name\` | string | Human-readable name |
-| \`props\` | object | Layer-specific properties |
-| \`preset\` | string | Entry animation preset |
-| \`presetDuration\` | number | Preset duration in seconds (default: 0.5) |
-| \`easing\` | string | Easing function |
-
-## Layer-specific props
-
-### text
-\`\`\`json
-{ "content": "Hello World", "fontSize": 48, "color": "#ffffff", "fontFamily": "system-ui", "textAlign": "center" }
-\`\`\`
-
-### video / audio
-\`\`\`json
-{ "src": "./assets/demo.mp4", "volume": 100 }
-\`\`\`
-
-### image
-\`\`\`json
-{ "src": "./assets/logo.png", "fit": "cover" }
-\`\`\`
-
-### phone / browser / laptop
-\`\`\`json
-{ "src": "./assets/screen.mp4", "url": "https://example.com" }
-\`\`\`
-
-### shape
-\`\`\`json
-{ "shape": "circle", "color": "#3b82f6", "size": 200 }
-\`\`\`
-
-### button
-\`\`\`json
-{ "label": "Click Me", "url": "https://example.com", "color": "#3b82f6" }
-\`\`\`
-
-### code
-\`\`\`json
-{ "code": "console.log('hello')", "language": "javascript", "showLineNumbers": true }
-\`\`\`
-
-### icon
-\`\`\`json
-{ "icon": "star", "color": "#fbbf24", "size": 64 }
-\`\`\`
-
-## Best Practices
-
-- Layer IDs must be unique within a project
-- Use enterTime to sequence layers (stagger them for professional look)
-- Keep text layers between 0.5-3s for readability
-- Use track to control z-ordering (higher = on top)
-- In HTML, keyframes use \`time:value@strategy\`. Use \`@char-reveal\` or
-  \`@word-reveal\` for text \`props.content\`, \`@step-end\` / \`@step-start\`
-  for discrete jumps, and \`@snap-grid\` with \`data-dm-grid-increment\` for
-  quantized values.
-- For polished \`dm-text\` reveals, add \`transition-effects\` (for example
-  \`fade,slide-up,blur\`), \`transition-duration\`, \`transition-easing\`,
-  \`slide-distance\`, \`scale-from\`, and \`blur-amount\`.
-`,
-  "devmotion-render.md": `# /devmotion-render \u2014 Render Project to MP4
-
-Renders the current DevMotion project to an MP4 video file.
-
-## Usage
-
-\`\`\`
-/devmotion-render
-\`\`\`
-
-## How it works
-
-1. Validates the project structure (devmotion.json + all scene HTML files)
-2. Opens a headless browser (Playwright)
-3. Renders each frame deterministically using the virtualized clock
-4. Pipes frames through ffmpeg to produce H.264 MP4
-5. Output: \`output.mp4\` by default, or the path passed with \`--output\`
-
-## Prerequisites
-
-- The DevMotion CLI. If \`devmotion\` is not found, run it via npx instead:
-  \`npx @devmotion/cli render\` \u2014 or install once with \`npm i -g @devmotion/cli\`.
-- The CLI-bundled ffmpeg and Playwright Chromium. Run \`devmotion doctor\` to verify them.
-- All asset paths in layers are valid (relative to project root)
-
-## Command
-
-Run from a directory that contains \`devmotion.json\`:
-
-\`\`\`bash
-devmotion render
-# or
-npx @devmotion/cli render --output out.mp4
-\`\`\`
-
-\`devmotion render\` starts an ephemeral local Studio automatically if one is not already running.
-
-## After Render
-
-The output MP4 is saved to \`output.mp4\` unless you pass \`--output\`. You can play it, upload it, or use it as a video layer in another DevMotion project.
-`
+import { mkdir as mkdir2, readFile, writeFile as writeFile2 } from "fs/promises";
+import { homedir } from "os";
+import { dirname as dirname2, join as join7 } from "path";
+import { createInterface as createInterface2 } from "readline/promises";
+import { stdin, stdout } from "process";
+var SKILL = `---
+name: devmotion
+description: Create, edit, preview, and render DevMotion videos. Use when the user asks to build or modify an animation, scene, timeline, layer, or video with DevMotion.
+---
+
+# DevMotion
+
+Use DevMotion's local MCP tools as the primary interface. They are type-safe and share the
+same mutation layer as the SaaS editor, so prefer them over writing or rewriting scene HTML.
+
+## Workflow
+
+1. If the current directory has no \`devmotion.json\`, run
+   \`npx @devmotion/cli init <name>\` and work inside the generated directory.
+2. Call \`get_project\` before editing an existing project.
+3. Use the MCP tools to create, edit, remove, group, and animate layers and to configure the
+   project. Prefer small, incremental mutations and preserve existing layer IDs.
+4. Use \`npx @devmotion/cli preview\` for visual inspection.
+5. Use \`npx @devmotion/cli render --output <file.mp4>\` for final output.
+
+## Editing rules
+
+- Prefer MCP operations over hand-authored \`data-dm-*\` HTML. Edit scene HTML directly only
+  when the requested capability is not exposed by MCP, such as custom markup or scripts.
+- When direct HTML is necessary, preserve scripts, styles, comments, IDs, and existing
+  \`data-dm-*\` attributes; then call \`get_project\` to verify the parsed result.
+- Use layer schemas returned by the MCP server rather than guessing property shapes.
+- Sequence layers with readable timing, use animation presets where appropriate, and keep
+  important content inside the project bounds.
+- Do not start the Studio just to mutate project data; the stdio MCP server writes directly to
+  the local project. Preview is for visual verification and render is for export.
+
+## CLI fallback
+
+If the bare \`devmotion\` command is unavailable, always use \`npx @devmotion/cli ...\`.
+Run \`npx @devmotion/cli doctor\` when preview or render dependencies fail.
+`;
+var MCP_SERVER = {
+  command: "npx",
+  args: ["-y", "@devmotion/cli", "mcp"]
 };
+async function readJson(path) {
+  if (!existsSync6(path)) return {};
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    throw new Error(`Cannot parse existing JSON config: ${path}`);
+  }
+}
+async function installClaude(root, scope) {
+  const skillDir = join7(root, ".claude", "skills", "devmotion");
+  await mkdir2(skillDir, { recursive: true });
+  await writeFile2(join7(skillDir, "SKILL.md"), SKILL);
+  const configPath = scope === "global" ? join7(root, ".claude.json") : join7(root, ".mcp.json");
+  const config = await readJson(configPath);
+  config.mcpServers = {
+    ...config.mcpServers ?? {},
+    devmotion: { type: "stdio", ...MCP_SERVER }
+  };
+  await mkdir2(dirname2(configPath), { recursive: true });
+  await writeFile2(configPath, JSON.stringify(config, null, 2) + "\n");
+  return [join7(skillDir, "SKILL.md"), configPath];
+}
+function upsertCodexMcp(source) {
+  const block = `[mcp_servers.devmotion]
+command = "npx"
+args = ["-y", "@devmotion/cli", "mcp"]`;
+  const pattern = /^\[mcp_servers\.devmotion\][\s\S]*?(?=^\[|\s*$)/m;
+  if (pattern.test(source)) return source.replace(pattern, `${block}
+
+`);
+  return `${source.trimEnd()}${source.trim() ? "\n\n" : ""}${block}
+`;
+}
+async function installCodex(root) {
+  const skillDir = join7(root, ".agents", "skills", "devmotion");
+  const configPath = join7(root, ".codex", "config.toml");
+  await mkdir2(skillDir, { recursive: true });
+  await writeFile2(join7(skillDir, "SKILL.md"), SKILL);
+  await mkdir2(dirname2(configPath), { recursive: true });
+  const existing = existsSync6(configPath) ? await readFile(configPath, "utf8") : "";
+  await writeFile2(configPath, upsertCodexMcp(existing));
+  return [join7(skillDir, "SKILL.md"), configPath];
+}
+async function promptChoice() {
+  const rl = createInterface2({ input: stdin, output: stdout });
+  try {
+    const agentAnswer = (await rl.question("Agent [both/claude/codex] (both): ")).trim().toLowerCase();
+    const scopeAnswer = (await rl.question("Install scope [global/project] (global): ")).trim().toLowerCase();
+    const agents = agentAnswer === "claude" ? ["claude"] : agentAnswer === "codex" ? ["codex"] : ["claude", "codex"];
+    return { agents, scope: scopeAnswer === "project" ? "project" : "global" };
+  } finally {
+    rl.close();
+  }
+}
 var setupCommand = defineCommand5({
   meta: {
     name: "setup",
-    description: "Install Claude Code skills and wire MCP server"
+    description: "Install the DevMotion skill and MCP server for Claude Code and/or Codex"
   },
   args: {
     dir: {
       type: "positional",
-      description: "Target project directory (default: cwd)",
+      description: "Project directory used with --scope project",
       required: false
+    },
+    agent: {
+      type: "string",
+      description: "Agent to configure: claude, codex, or both"
+    },
+    scope: {
+      type: "string",
+      description: "Install globally for the current user or in the project: global or project"
     }
   },
   async run({ args }) {
-    const projectDir = args.dir || process.cwd();
-    const skillsDir = join7(projectDir, ".claude", "skills");
-    const settingsPath = join7(projectDir, ".claude", "settings.local.json");
-    await mkdir2(skillsDir, { recursive: true });
-    console.log(`\u{1F4C1} ${skillsDir}/`);
-    for (const [filename, content] of Object.entries(SKILLS)) {
-      const path = join7(skillsDir, filename);
-      await writeFile2(path, content);
-      console.log(`   \u2705 ${filename}`);
+    const suppliedAgent = args.agent;
+    const suppliedScope = args.scope;
+    const interactive = stdin.isTTY && stdout.isTTY && !suppliedAgent && !suppliedScope;
+    const prompted = interactive ? await promptChoice() : {
+      agents: suppliedAgent === "claude" ? ["claude"] : suppliedAgent === "codex" ? ["codex"] : ["claude", "codex"],
+      scope: suppliedScope === "project" ? "project" : "global"
+    };
+    if (suppliedAgent && !["claude", "codex", "both"].includes(suppliedAgent)) {
+      throw new Error("--agent must be claude, codex, or both");
     }
-    let settings = {};
-    if (existsSync6(settingsPath)) {
-      try {
-        const raw = await readFile(settingsPath, "utf-8");
-        settings = JSON.parse(raw);
-      } catch {
-        console.log("\u26A0\uFE0F  Could not parse existing settings.local.json, overwriting.");
-      }
+    if (suppliedScope && !["global", "project"].includes(suppliedScope)) {
+      throw new Error("--scope must be global or project");
+    }
+    const root = prompted.scope === "global" ? homedir() : args.dir || process.cwd();
+    const installed = [];
+    if (prompted.agents.includes("claude")) {
+      installed.push(...await installClaude(root, prompted.scope));
+    }
+    if (prompted.agents.includes("codex")) {
+      installed.push(...await installCodex(root));
     }
-    settings.mcpServers = {
-      ...settings.mcpServers || {},
-      devmotion: {
-        command: "npx",
-        args: ["@devmotion/cli", "mcp"],
-        description: "DevMotion \u2014 HTML-first video tooling. Create/edit video layers via MCP (writes scene HTML)."
-      }
-    };
-    await writeFile2(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-    console.log(`   \u2705 settings.local.json (MCP wired)`);
     console.log(`
-\u2728 DevMotion Claude Code integration installed!
-`);
-    console.log("  Available slash commands:");
-    console.log("    /devmotion-init        \u2014 Scaffold new project");
-    console.log("    /devmotion-add-layer    \u2014 Add a layer");
-    console.log("    /devmotion-render      \u2014 Render to MP4");
-    console.log();
-    console.log("  MCP tools (when in a devmotion project dir):");
-    console.log("    get_project, create_layer, edit_layer, remove_layer, configure_project");
-    console.log();
+DevMotion configured for ${prompted.agents.join(" + ")} (${prompted.scope}).`);
+    for (const path of installed) console.log(`  ${path}`);
+    console.log(
+      "\nThe skill uses the local type-safe MCP tools before editing scene HTML directly."
+    );
   }
 });
 
@@ -987,9 +773,9 @@ var setupCommand = defineCommand5({
 import { defineCommand as defineCommand6 } from "citty";
 import { readFileSync, writeFileSync, existsSync as existsSync7 } from "fs";
 import { writeFile as writeFile3, mkdir as mkdir3 } from "fs/promises";
-import { join as join8, dirname as dirname2, resolve as resolve2 } from "path";
+import { join as join8, dirname as dirname3, resolve as resolve2 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
-var __dirname = dirname2(fileURLToPath3(import.meta.url));
+var __dirname = dirname3(fileURLToPath3(import.meta.url));
 function findTemplatesDir() {
   let dir = __dirname;
   for (let i = 0; i < 6; i++) {