@effect-motion/cli 0.1.0

package/dist/commands/render.js

@@ -0,0 +1,159 @@
+import { Video } from "@effect-motion/export";
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import { FileSystem } from "effect/FileSystem";
+import * as Option from "effect/Option";
+import { Path } from "effect/Path";
+import * as Result from "effect/Result";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import { DEFAULT_OUTPUT_DIR, resolveTarget, } from "../Config.js";
+import { findConfig, loadConfig } from "../ConfigLoader.js";
+import { MotionCliError } from "../MotionCliError.js";
+import { makeViteLoader } from "../ViteLoader.js";
+const opt = (o) => Option.getOrUndefined(o);
+const renderFlags = {
+    config: Flag.optional(Flag.string("config").pipe(Flag.withDescription("Path to a motion.config.ts (tsc -p style)"))),
+    width: Flag.optional(Flag.integer("width")),
+    height: Flag.optional(Flag.integer("height")),
+    fps: Flag.optional(Flag.integer("fps").pipe(Flag.withDescription("Frame rate override"))),
+    dpr: Flag.optional(Flag.float("dpr").pipe(Flag.withDescription("Supersampling factor (output pixels = scene × dpr)"))),
+    seed: Flag.optional(Flag.string("seed")),
+    maxFrames: Flag.optional(Flag.integer("max-frames")),
+    frames: Flag.optional(Flag.integer("frames").pipe(Flag.withDescription("Cap encoded frames (required for infinite scenes)"))),
+    outDir: Flag.optional(Flag.string("out-dir").pipe(Flag.withDescription("Output directory override"))),
+    format: Flag.optional(Flag.choice("format", ["mp4"])),
+    targets: Argument.string("targets").pipe(Argument.withDescription("Target names from the config, or one scene file path"), Argument.variadic()),
+};
+const overridesFrom = (input) => {
+    const raw = {
+        width: opt(input.width),
+        height: opt(input.height),
+        frameRate: opt(input.fps),
+        dpr: opt(input.dpr),
+        seed: opt(input.seed),
+        maxFrames: opt(input.maxFrames),
+        frames: opt(input.frames),
+        outDir: opt(input.outDir),
+        format: opt(input.format),
+    };
+    return Object.fromEntries(Object.entries(raw).filter(([, v]) => v !== undefined));
+};
+// a positional is a scene file (configless mode) iff it looks like a module
+// path — target names never carry an extension
+const isSceneFile = (arg) => /\.(ts|tsx|mts|js|mjs)$/.test(arg);
+const sceneBasename = (file) => {
+    const base = file.split("/").at(-1) ?? file;
+    return base.replace(/\.(ts|tsx|mts|js|mjs)$/, "");
+};
+/** Map a resolved target onto the export package's options shape. */
+const toVideoOptions = (target) => {
+    const { dpr, ...settings } = target.settings;
+    return {
+        // ponytail: VideoSceneSettings doesn't name seed/backgroundColor, but
+        // Video.render passes settings straight through to Scene.stream — the
+        // cast is the CLI-side adaptation decided in design D2; collapse it if
+        // the export package ever widens its settings type
+        settings: settings,
+        ...(dpr !== undefined ? { dpr } : {}),
+        ...(target.frames !== undefined ? { frames: target.frames } : {}),
+    };
+};
+const renderOne = (loader, baseDir, target) => Effect.gen(function* () {
+    const path = yield* Path;
+    const fs = yield* FileSystem;
+    const sceneAbs = path.isAbsolute(target.scene)
+        ? target.scene
+        : path.resolve(baseDir, target.scene);
+    const module_ = yield* loader.load(sceneAbs);
+    const scene = module_.scene;
+    if (scene === undefined) {
+        return yield* new MotionCliError({
+            reason: "SceneLoadFailed",
+            message: `${sceneAbs} has no \`scene\` export`,
+        });
+    }
+    const outDirAbs = path.resolve(baseDir, target.outDir);
+    yield* fs.makeDirectory(outDirAbs, { recursive: true }).pipe(Effect.mapError((cause) => new MotionCliError({
+        reason: "RenderFailed",
+        message: `could not create output directory ${outDirAbs}`,
+        cause,
+    })));
+    const outFile = path.join(outDirAbs, target.fileName);
+    yield* Video.render(scene, outFile, toVideoOptions(target)).pipe(Effect.mapError((cause) => new MotionCliError({
+        reason: "RenderFailed",
+        message: `target "${target.name}" failed to render (${sceneAbs})`,
+        cause,
+    })));
+    return outFile;
+});
+const handler = (input) => Effect.gen(function* () {
+    const path = yield* Path;
+    const cwd = process.cwd();
+    const overrides = overridesFrom(input);
+    // resolve the target list and the directory paths are relative to
+    let baseDir;
+    let resolved;
+    const [first] = input.targets;
+    if (first !== undefined &&
+        input.targets.length === 1 &&
+        isSceneFile(first)) {
+        // configless mode: one scene file, library defaults + flags
+        baseDir = cwd;
+        resolved = [
+            resolveTarget({
+                name: sceneBasename(first),
+                scene: path.resolve(cwd, first),
+                output: DEFAULT_OUTPUT_DIR,
+            }, overrides),
+        ];
+    }
+    else {
+        const configPath = yield* findConfig(cwd, opt(input.config));
+        baseDir = path.dirname(configPath);
+        const loader = yield* makeViteLoader(baseDir);
+        const config = yield* loadConfig(loader, configPath);
+        if (input.targets.length === 0) {
+            resolved = config.targets.map((t) => resolveTarget(t, overrides));
+        }
+        else {
+            const known = new Map(config.targets.map((t) => [t.name, t]));
+            const unknown = input.targets.filter((name) => !known.has(name));
+            if (unknown.length > 0) {
+                return yield* new MotionCliError({
+                    reason: "UnknownTarget",
+                    message: `unknown target${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")} — ` +
+                        `known targets: ${[...known.keys()].join(", ") || "(none)"}`,
+                });
+            }
+            resolved = input.targets.map((name) => 
+            // biome-ignore lint/style/noNonNullAssertion: membership checked above
+            resolveTarget(known.get(name), overrides));
+        }
+        return yield* execute(loader, baseDir, resolved);
+    }
+    const loader = yield* makeViteLoader(baseDir);
+    return yield* execute(loader, baseDir, resolved);
+}).pipe(Effect.scoped);
+// render sequentially: ffmpeg already saturates the CPU per target
+// (ponytail: parallelize only if profiling ever says otherwise)
+const execute = (loader, baseDir, targets) => Effect.gen(function* () {
+    const failures = [];
+    for (const target of targets) {
+        const result = yield* Effect.result(renderOne(loader, baseDir, target));
+        if (Result.isSuccess(result)) {
+            yield* Console.log(`✓ ${target.name} → ${result.success}`);
+        }
+        else {
+            failures.push(result.failure);
+            yield* Console.error(`✗ ${target.name}: ${result.failure.message}`);
+        }
+    }
+    if (failures.length > 0) {
+        return yield* new MotionCliError({
+            reason: "RenderFailed",
+            message: `${failures.length} of ${targets.length} target${targets.length > 1 ? "s" : ""} failed`,
+            cause: failures[0],
+        });
+    }
+});
+export const renderCommand = Command.make("render", renderFlags, handler).pipe(Command.withDescription("Render targets from motion.config.ts (or one scene file) to video"));

package/dist/commands/studio.d.ts

@@ -0,0 +1,10 @@
+import { FileSystem } from "effect/FileSystem";
+import * as Option from "effect/Option";
+import { Path } from "effect/Path";
+import { Command } from "effect/unstable/cli";
+import { MotionCliError } from "../MotionCliError.js";
+export declare const studioCommand: Command.Command<"studio", {
+    readonly config: Option.Option<string>;
+    readonly port: Option.Option<number>;
+    readonly host: Option.Option<string>;
+}, {}, MotionCliError, FileSystem | Path>;

package/dist/commands/studio.js

@@ -0,0 +1,106 @@
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import { FileSystem } from "effect/FileSystem";
+import * as Option from "effect/Option";
+import { Path } from "effect/Path";
+import * as Result from "effect/Result";
+import { Command, Flag } from "effect/unstable/cli";
+import { findConfig } from "../ConfigLoader.js";
+import { MotionCliError } from "../MotionCliError.js";
+const studioFlags = {
+    config: Flag.optional(Flag.string("config")),
+    port: Flag.optional(Flag.integer("port")),
+    host: Flag.optional(Flag.string("host")),
+};
+/** Shipped studio app source (dist/commands/studio.js → ../../studio-app). */
+const studioAppSource = (path) => path.join(path.dirname(new URL(import.meta.url).pathname), "..", "..", "studio-app");
+// The studio app is copied INTO the project (.motion/studio) so its bare
+// imports (react, @effect-motion/react, the config's own imports) resolve
+// against the project's node_modules — the same graph render uses. The
+// generated project.ts pins the project root for /@fs imports.
+const prepareStudioDir = (projectRoot) => Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    const path = yield* Path;
+    const source = studioAppSource(path);
+    const studioDir = path.join(projectRoot, ".motion", "studio");
+    yield* fs.makeDirectory(studioDir, { recursive: true });
+    for (const entry of yield* fs.readDirectory(source)) {
+        yield* fs.copyFile(path.join(source, entry), path.join(studioDir, entry));
+    }
+    yield* fs.writeFileString(path.join(studioDir, "project.ts"), `// generated by \`motion studio\` — do not edit\nexport const projectRoot = ${JSON.stringify(projectRoot)};\n`);
+    return studioDir;
+}).pipe(Effect.mapError((cause) => cause instanceof MotionCliError
+    ? cause
+    : new MotionCliError({
+        reason: "StudioFailed",
+        message: `could not prepare the studio app in ${projectRoot}/.motion/studio`,
+        cause,
+    })));
+const handler = (input) => Effect.gen(function* () {
+    const path = yield* Path;
+    const cwd = process.cwd();
+    // a config is optional for studio: unregistered scenes are previewable,
+    // so "no config" just means "project root = cwd"
+    const found = yield* Effect.result(findConfig(cwd, Option.getOrUndefined(input.config)));
+    const projectRoot = Result.isSuccess(found)
+        ? path.dirname(found.success)
+        : cwd;
+    const studioDir = yield* prepareStudioDir(projectRoot);
+    const server = yield* Effect.acquireRelease(Effect.tryPromise({
+        try: async () => {
+            const { createServer } = await import("vite");
+            const server = await createServer({
+                root: studioDir,
+                configFile: false,
+                server: {
+                    ...(Option.isSome(input.port) ? { port: input.port.value } : {}),
+                    ...(Option.isSome(input.host) ? { host: input.host.value } : {}),
+                    fs: { allow: [projectRoot] },
+                },
+                // one React/effect instance no matter where modules live
+                resolve: {
+                    dedupe: ["react", "react-dom", "effect", "effect-motion"],
+                },
+                plugins: [
+                    {
+                        name: "motion:project-watch",
+                        configureServer(server) {
+                            // the project lives OUTSIDE the vite root
+                            // (.motion/studio); vite's own add/unlink → glob
+                            // invalidation doesn't reach out-of-root dirs, so
+                            // scene add/remove refreshes the picker here
+                            // (ponytail: invalidateAll + full reload — coarse,
+                            // but studio-sized; narrow it if it ever matters)
+                            const onAddUnlink = (file) => {
+                                if (!file.startsWith(projectRoot))
+                                    return;
+                                server.moduleGraph.invalidateAll();
+                                server.ws.send({ type: "full-reload" });
+                            };
+                            server.watcher.on("add", onAddUnlink);
+                            server.watcher.on("unlink", onAddUnlink);
+                        },
+                    },
+                ],
+            });
+            await server.listen();
+            // out-of-root project files aren't watched by default — without
+            // this, editing a scene or the config would not hot reload
+            server.watcher.add([
+                `${projectRoot}/src`,
+                `${projectRoot}/motion.config.ts`,
+            ]);
+            return server;
+        },
+        catch: (cause) => new MotionCliError({
+            reason: "StudioFailed",
+            message: `could not start the studio dev server for ${projectRoot}`,
+            cause,
+        }),
+    }), (server) => Effect.promise(() => server.close()));
+    yield* Console.log("motion studio running:");
+    server.printUrls();
+    // serve until interrupted (Ctrl-C) — teardown runs via the scope
+    yield* Effect.never;
+}).pipe(Effect.scoped);
+export const studioCommand = Command.make("studio", studioFlags, handler).pipe(Command.withDescription("Preview scenes in the browser with hot reload (Player + scene picker)"));

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { DEFAULT_FORMAT, DEFAULT_OUTPUT_DIR, defineConfig, type MotionConfig, type MotionTarget, type OutputFormat, type RenderOverrides, type ResolvedTarget, resolveTarget, type TargetSettings, validateConfig, } from "./Config.js";
+export { MotionCliError, type MotionCliReason } from "./MotionCliError.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+// Public API: the config contract (imported by user motion.config.ts files
+// and the studio app, so this entry must stay browser-safe) and the error
+// type. The commands live behind the `motion` bin, not this entry.
+export { DEFAULT_FORMAT, DEFAULT_OUTPUT_DIR, defineConfig, resolveTarget, validateConfig, } from "./Config.js";
+export { MotionCliError } from "./MotionCliError.js";

package/dist/pins.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Exact versions a scaffolded project is pinned to — the set this CLI
+ * release was built and tested against. The effect pin is a determinism
+ * invariant (upgrading effect can change seeded random sequences), so
+ * scaffolds never use ranges or `latest`. Updated by the CLI's own release
+ * process.
+ */
+export declare const PINS: {
+    readonly effect: "4.0.0-beta.98";
+    readonly "effect-motion": "0.2.0";
+    readonly "@effect-motion/react": "0.2.0";
+    readonly "@effect-motion/export": "0.2.0";
+    readonly "@effect-motion/cli": "0.1.0";
+};
+/** Non-determinism-critical companions; ranges are fine here. */
+export declare const COMPANIONS: {
+    readonly react: "^19.2.0";
+    readonly "react-dom": "^19.2.0";
+    readonly typescript: "^7.0.2";
+    readonly "@types/react": "^19.2.0";
+    readonly "@types/react-dom": "^19.2.0";
+    readonly "@types/node": "^26.1.1";
+};

package/dist/pins.js

@@ -0,0 +1,23 @@
+/**
+ * Exact versions a scaffolded project is pinned to — the set this CLI
+ * release was built and tested against. The effect pin is a determinism
+ * invariant (upgrading effect can change seeded random sequences), so
+ * scaffolds never use ranges or `latest`. Updated by the CLI's own release
+ * process.
+ */
+export const PINS = {
+    effect: "4.0.0-beta.98",
+    "effect-motion": "0.2.0",
+    "@effect-motion/react": "0.2.0",
+    "@effect-motion/export": "0.2.0",
+    "@effect-motion/cli": "0.1.0",
+};
+/** Non-determinism-critical companions; ranges are fine here. */
+export const COMPANIONS = {
+    react: "^19.2.0",
+    "react-dom": "^19.2.0",
+    typescript: "^7.0.2",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@types/node": "^26.1.1",
+};

package/dist/scaffold.d.ts

@@ -0,0 +1,20 @@
+import * as Effect from "effect/Effect";
+import { FileSystem } from "effect/FileSystem";
+import { Path } from "effect/Path";
+import { MotionCliError } from "./MotionCliError.js";
+/**
+ * The non-interactive core of `motion init`: everything except the prompts,
+ * so tests can drive it directly. Copies templates/default into the target
+ * directory and generates package.json from the pinned versions.
+ */
+/** Directory of the shipped templates (dist/scaffold.js → ../templates). */
+export declare const templatesDir: (path: Path) => string;
+/** `.` means "here"; the project is named after the resolved directory. */
+export declare const resolveProjectDir: (path: Path, cwd: string, input: string) => {
+    dir: string;
+    name: string;
+};
+/** Non-empty means anything but dotfiles (a fresh `git init` is fine). */
+export declare const ensureEmptyDir: (dir: string) => Effect.Effect<undefined, MotionCliError, FileSystem>;
+/** Copy the template tree + write the generated package.json. */
+export declare const scaffoldProject: (dir: string, name: string) => Effect.Effect<void, MotionCliError, FileSystem | Path>;

package/dist/scaffold.js

@@ -0,0 +1,86 @@
+import * as Effect from "effect/Effect";
+import { FileSystem } from "effect/FileSystem";
+import { Path } from "effect/Path";
+import { MotionCliError } from "./MotionCliError.js";
+import { COMPANIONS, PINS } from "./pins.js";
+/**
+ * The non-interactive core of `motion init`: everything except the prompts,
+ * so tests can drive it directly. Copies templates/default into the target
+ * directory and generates package.json from the pinned versions.
+ */
+/** Directory of the shipped templates (dist/scaffold.js → ../templates). */
+export const templatesDir = (path) => path.join(path.dirname(new URL(import.meta.url).pathname), "..", "templates", "default");
+/** `.` means "here"; the project is named after the resolved directory. */
+export const resolveProjectDir = (path, cwd, input) => {
+    const dir = path.resolve(cwd, input);
+    return { dir, name: path.basename(dir) };
+};
+/** Non-empty means anything but dotfiles (a fresh `git init` is fine). */
+export const ensureEmptyDir = (dir) => Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    if (!(yield* fs.exists(dir)))
+        return;
+    const entries = yield* fs.readDirectory(dir);
+    const meaningful = entries.filter((entry) => !entry.startsWith("."));
+    if (meaningful.length > 0) {
+        return yield* new MotionCliError({
+            reason: "ScaffoldTargetNotEmpty",
+            message: `${dir} is not empty (found ${meaningful.slice(0, 3).join(", ")}${meaningful.length > 3 ? ", …" : ""}) — choose an empty or new directory`,
+        });
+    }
+}).pipe(wrapFsError("ScaffoldFailed", `could not inspect ${dir}`));
+const wrapFsError = (reason, message) => (effect) => Effect.mapError(effect, (cause) => cause instanceof MotionCliError
+    ? cause
+    : new MotionCliError({ reason, message, cause }));
+const packageJson = (name) => `${JSON.stringify({
+    name,
+    private: true,
+    version: "0.0.0",
+    type: "module",
+    scripts: {
+        studio: "motion studio",
+        render: "motion render",
+    },
+    dependencies: {
+        "@effect-motion/export": PINS["@effect-motion/export"],
+        "@effect-motion/react": PINS["@effect-motion/react"],
+        effect: PINS.effect,
+        "effect-motion": PINS["effect-motion"],
+        react: COMPANIONS.react,
+        "react-dom": COMPANIONS["react-dom"],
+    },
+    devDependencies: {
+        "@effect-motion/cli": PINS["@effect-motion/cli"],
+        "@types/node": COMPANIONS["@types/node"],
+        "@types/react": COMPANIONS["@types/react"],
+        "@types/react-dom": COMPANIONS["@types/react-dom"],
+        typescript: COMPANIONS.typescript,
+    },
+}, null, "\t")}\n`;
+/** Copy the template tree + write the generated package.json. */
+export const scaffoldProject = (dir, name) => Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    const path = yield* Path;
+    const templates = templatesDir(path);
+    yield* fs.makeDirectory(dir, { recursive: true });
+    yield* copyTree(fs, path, templates, dir);
+    // npm mangles nested .gitignore/package.json files in published
+    // tarballs, so both ship outside the template tree
+    yield* fs.writeFileString(path.join(dir, "package.json"), packageJson(name));
+    yield* fs.rename(path.join(dir, "_gitignore"), path.join(dir, ".gitignore"));
+}).pipe(wrapFsError("ScaffoldFailed", `could not scaffold ${dir}`));
+const copyTree = (fs, path, from, to) => Effect.gen(function* () {
+    const entries = yield* fs.readDirectory(from);
+    for (const entry of entries) {
+        const src = path.join(from, entry);
+        const dst = path.join(to, entry);
+        const info = yield* fs.stat(src);
+        if (info.type === "Directory") {
+            yield* fs.makeDirectory(dst, { recursive: true });
+            yield* copyTree(fs, path, src, dst);
+        }
+        else {
+            yield* fs.copyFile(src, dst);
+        }
+    }
+});

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@effect-motion/cli",
+  "version": "0.1.0",
+  "description": "Command line for effect-motion: scaffold projects (init), preview scenes with hot reload (studio), and render videos from motion.config.ts (render)",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/julia-script/effect-motion.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/julia-script/effect-motion#readme",
+  "bugs": "https://github.com/julia-script/effect-motion/issues",
+  "keywords": [
+    "effect",
+    "motion",
+    "cli",
+    "scaffold",
+    "studio",
+    "render",
+    "video"
+  ],
+  "bin": {
+    "motion": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "templates",
+    "studio-app"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@effect/platform-node": "4.0.0-beta.98",
+    "effect": "4.0.0-beta.98",
+    "vite": "^7.0.0",
+    "@effect-motion/export": "^0.2.0",
+    "effect-motion": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "@effect-motion/react": "^0.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "test": "vitest run",
+    "check": "tsc --noEmit"
+  }
+}