@coppsary/motionly 1.1.0 → 1.1.1

package/README.md

@@ -210,7 +210,7 @@ Open Motionly Assistant beside Assets, enter your own provider key, and describe
 
 **Model quality matters.** The AI model you choose directly affects composition, timing, and correct preset use. Smaller models may generate valid syntax but weaker visual decisions. Prefer a current, high-capability model with strong code-generation and instruction-following performance.
 
-For coding agents working inside a project, install the skill with `npx motionly skills add` (or `npx motionly init`, which asks which agent). This writes the `SKILL.md` contract plus a full `references/` library into your agent's folder — Codex (`.agents/`), Claude Code (`.claude/`), Gemini CLI (`.gemini/`), opencode (`.opencode/`), or Kiro (`.kiro/`):
+For coding agents working inside a project, install the skill with `npx @coppsary/motionly skills add` (or `npx @coppsary/motionly init`, which asks which agent). This writes the `SKILL.md` contract plus a full `references/` library into your agent's folder — Codex (`.agents/`), Claude Code (`.claude/`), Gemini CLI (`.gemini/`), opencode (`.opencode/`), or Kiro (`.kiro/`):
 
 | Path | Purpose |
 |---|---|
@@ -223,6 +223,7 @@ Point the agent at `AGENTS.md` and the installed `SKILL.md`, then let it load `r
 Use this short prompt with an LLM or agent working inside the repository:
 
 ```text
+/motionly
 Read AGENTS.md and .agents/skills/write-motionly/SKILL.md first.
 Inspect my assets, storyboard the animation, then create a valid .motion project.
 Use only supported Motionly syntax and presets. Keep one focal subject per shot,
@@ -325,7 +326,7 @@ Motionly ships on npm — no clone and no global install. It needs Node.js `20.1
 ### Create a project
 
 ```bash
-npx motionly init demo
+npx @coppsary/motionly init demo
 ```
 
 `init` scaffolds the project and asks **which agent you're using**, then installs the Motionly agent skill for just that one (or choose "All supported agents"). Supported agents: **Codex, Claude Code, Gemini CLI, opencode, and Kiro**. The install is not a single file: it writes the `SKILL.md` contract plus a full `references/` library (`motion-dsl`, `svg`, `animation`, `timeline`, and more) with an `llms.txt` discovery index.
@@ -333,9 +334,9 @@ npx motionly init demo
 Skip the prompt with flags:
 
 ```bash
-npx motionly init demo --provider opencode   # install for one agent, no prompt
-npx motionly init demo --all                 # every supported agent
-npx motionly init demo --skip-skills          # no agent skills
+npx @coppsary/motionly init demo --provider opencode   # install for one agent, no prompt
+npx @coppsary/motionly init demo --all                 # every supported agent
+npx @coppsary/motionly init demo --skip-skills          # no agent skills
 ```
 
 Provider names are `codex`, `claude`, `gemini`, `opencode`, and `kiro`. Use `--scope project` (default) or `--scope global` to install for every project on your machine.
@@ -354,9 +355,9 @@ demo/
 ### Add skills to an existing project
 
 ```bash
-npx motionly skills add                      # pick scope and agents
-npx motionly skills add --all --scope project
-npx motionly skills add --provider codex --scope global
+npx @coppsary/motionly skills add                      # pick scope and agents
+npx @coppsary/motionly skills add --all --scope project
+npx @coppsary/motionly skills add --provider codex --scope global
 ```
 
 Re-running is safe: existing skill files are kept, never overwritten.
@@ -365,10 +366,10 @@ Re-running is safe: existing skill files are kept, never overwritten.
 
 ```bash
 cd demo
-npx motionly dev
+npx @coppsary/motionly dev
 ```
 
-Motionly opens `http://localhost:4173/editor`, loads `project.motion`, serves media from `assets/`, and saves editor changes back to the project. Add `--port <n>` to change the port or `--no-open` to skip launching the browser. For the no-setup browser editor, run `npx motionly`.
+Motionly opens `http://localhost:4173/editor`, loads `project.motion`, serves media from `assets/`, and saves editor changes back to the project. Add `--port <n>` to change the port or `--no-open` to skip launching the browser. For the no-setup browser editor, run `npx @coppsary/motionly`.
 
 ## Development from source
 

package/bin/ffmpeg-export.js

@@ -0,0 +1,263 @@
+import { Buffer } from 'node:buffer';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { mkdtemp, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+const jobs = new Map();
+const MAX_FRAME_BYTES = 100 * 1024 * 1024;
+const MAX_AUDIO_BYTES = 1024 * 1024 * 1024;
+
+/** Handle an export request in the standalone npm CLI server. */
+export async function handleFfmpegExportRequest(request, response) {
+  const url = new URL(request.url ?? '/', 'http://motionly.local');
+  if (!url.pathname.startsWith('/api/exports')) return false;
+
+  try {
+    await handleExportRequest(request, response, url);
+  } catch (error) {
+    if (response.headersSent) {
+      response.destroy(error instanceof Error ? error : new Error(String(error)));
+    } else {
+      response.statusCode = 500;
+      response.setHeader('content-type', 'text/plain;charset=utf-8');
+      response.end(error instanceof Error ? error.message : String(error));
+    }
+  }
+  return true;
+}
+
+/** Connect-compatible middleware used by the Vite development and preview servers. */
+export function createFfmpegExportMiddleware() {
+  return (request, response, next) => {
+    void handleFfmpegExportRequest(request, response).then((handled) => {
+      if (!handled) next();
+    }, next);
+  };
+}
+
+async function handleExportRequest(request, response, url) {
+  if (request.method === 'POST' && url.pathname === '/api/exports') {
+    await createJob(request, response);
+    return;
+  }
+  const match = /^\/api\/exports\/([a-z0-9-]+)(?:\/(frames\/(\d+)|audio|finish))?$/.exec(
+    url.pathname
+  );
+  if (!match) return respond(response, 404, 'Unknown export endpoint');
+  const id = match[1];
+  const action = match[2];
+  if (!id) return respond(response, 404, 'Unknown export job');
+  const job = jobs.get(id);
+  if (!job) return respond(response, 404, 'Export job not found');
+
+  if (request.method === 'DELETE' && !action) {
+    jobs.delete(id);
+    await rm(job.directory, { recursive: true, force: true });
+    respond(response, 204);
+    return;
+  }
+
+  if (request.method === 'PUT' && action?.startsWith('frames/')) {
+    const index = Number(match[3]);
+    if (!Number.isInteger(index) || index < 0 || index >= job.totalFrames) {
+      return respond(response, 409, `Invalid frame ${index}`);
+    }
+    if (job.receivedFrames.has(index)) return respond(response, 409, `Duplicate frame ${index}`);
+    if (request.headers['content-type'] !== 'image/jpeg') {
+      return respond(response, 415, 'Export frames must be JPEG images');
+    }
+    await writeRequest(
+      request,
+      join(job.directory, `frame-${String(index).padStart(8, '0')}.jpg`),
+      MAX_FRAME_BYTES
+    );
+    job.receivedFrames.add(index);
+    respond(response, 204);
+    return;
+  }
+
+  if (request.method === 'PUT' && action === 'audio') {
+    if (!job.hasAudio) return respond(response, 409, 'This export was not created with audio');
+    await writeRequest(request, join(job.directory, 'audio-input'), MAX_AUDIO_BYTES);
+    job.audioReceived = true;
+    respond(response, 204);
+    return;
+  }
+
+  if (request.method === 'POST' && action === 'finish') {
+    if (job.receivedFrames.size !== job.totalFrames) {
+      return respond(
+        response,
+        409,
+        `Missing ${job.totalFrames - job.receivedFrames.size} export frames`
+      );
+    }
+    if (job.hasAudio && !job.audioReceived) {
+      return respond(response, 409, 'The attached audio file was not uploaded');
+    }
+    await finishJob(id, job, response);
+    return;
+  }
+
+  respond(response, 405, 'Method not allowed');
+}
+
+async function createJob(request, response) {
+  const input = JSON.parse((await readRequest(request, 64 * 1024)).toString('utf8'));
+  positiveInteger(input.width, 'width', 8192);
+  positiveInteger(input.height, 'height', 8192);
+  const fps = positiveNumber(input.fps, 'fps', 240);
+  const duration = positiveNumber(input.duration, 'duration', 24 * 60 * 60);
+  const totalFrames = positiveInteger(input.totalFrames, 'totalFrames', 24 * 60 * 60 * 240);
+  const audioStart = nonNegativeNumber(input.audioStart ?? 0, 'audioStart', duration);
+  const expectedFrames = Math.max(1, Math.ceil(duration * fps));
+  if (totalFrames !== expectedFrames) throw new Error(`Expected ${expectedFrames} frames`);
+  const id = randomUUID();
+  const directory = await mkdtemp(join(tmpdir(), 'motionly-export-'));
+  jobs.set(id, {
+    directory,
+    fps,
+    duration,
+    totalFrames,
+    receivedFrames: new Set(),
+    hasAudio: input.hasAudio === true,
+    audioStart,
+    audioReceived: false,
+  });
+  response.statusCode = 201;
+  response.setHeader('content-type', 'application/json');
+  response.end(JSON.stringify({ id }));
+}
+
+async function finishJob(id, job, response) {
+  const outputPath = join(job.directory, 'motionly.mp4');
+  const framePattern = join(job.directory, 'frame-%08d.jpg');
+  const args = [
+    '-hide_banner',
+    '-loglevel',
+    'error',
+    '-y',
+    '-framerate',
+    String(job.fps),
+    '-start_number',
+    '0',
+    '-i',
+    framePattern,
+  ];
+  if (job.hasAudio) {
+    args.push('-itsoffset', String(job.audioStart), '-i', join(job.directory, 'audio-input'));
+  }
+  args.push('-map', '0:v:0');
+  if (job.hasAudio) args.push('-map', '1:a:0', '-c:a', 'aac', '-b:a', '192k');
+  args.push(
+    '-c:v',
+    'libx264',
+    '-preset',
+    'medium',
+    '-crf',
+    '18',
+    '-vf',
+    'pad=ceil(iw/2)*2:ceil(ih/2)*2:color=black,format=yuv420p',
+    '-frames:v',
+    String(job.totalFrames),
+    '-t',
+    String(job.duration),
+    '-movflags',
+    '+faststart',
+    outputPath
+  );
+
+  jobs.delete(id);
+  try {
+    await runFfmpeg(args);
+    const output = await stat(outputPath);
+    response.statusCode = 200;
+    response.setHeader('content-type', 'video/mp4');
+    response.setHeader('content-length', String(output.size));
+    await pipeline(createReadStream(outputPath), response);
+  } finally {
+    await rm(job.directory, { recursive: true, force: true });
+  }
+}
+
+function runFfmpeg(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('ffmpeg', args, { windowsHide: true });
+    let errorOutput = '';
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => {
+      errorOutput = `${errorOutput}${chunk}`.slice(-16_384);
+    });
+    child.once('error', (error) => {
+      reject(
+        error.code === 'ENOENT'
+          ? new Error('ffmpeg is not installed or is not available on PATH')
+          : error
+      );
+    });
+    child.once('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(errorOutput.trim() || `ffmpeg exited with code ${String(code)}`));
+    });
+  });
+}
+
+async function writeRequest(request, path, maxBytes) {
+  let size = 0;
+  const limiter = new Transform({
+    transform(chunk, _encoding, callback) {
+      size += chunk.byteLength;
+      callback(size > maxBytes ? new Error('Export upload is too large') : null, chunk);
+    },
+  });
+  try {
+    await pipeline(request, limiter, createWriteStream(path));
+  } catch (error) {
+    await rm(path, { force: true });
+    throw error;
+  }
+}
+
+async function readRequest(request, maxBytes) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.byteLength;
+    if (size > maxBytes) throw new Error('Export upload is too large');
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks);
+}
+
+function positiveInteger(value, name, max) {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0 || value > max) {
+    throw new Error(`Invalid export ${name}`);
+  }
+  return value;
+}
+
+function positiveNumber(value, name, max) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > max) {
+    throw new Error(`Invalid export ${name}`);
+  }
+  return value;
+}
+
+function nonNegativeNumber(value, name, max) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > max) {
+    throw new Error(`Invalid export ${name}`);
+  }
+  return value;
+}
+
+function respond(response, status, message) {
+  response.statusCode = status;
+  if (message) response.setHeader('content-type', 'text/plain;charset=utf-8');
+  response.end(message);
+}

package/bin/motionly.js

@@ -2,6 +2,7 @@
 // Zero-dependency Motionly CLI and local editor server.
 
 import { createServer } from 'node:http';
+import { handleFfmpegExportRequest } from './ffmpeg-export.js';
 import { createInterface } from 'node:readline/promises';
 import { spawn } from 'node:child_process';
 import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
@@ -151,7 +152,11 @@ async function copyReferenceLibrary(source, destination) {
     const to = join(destination, entry.name);
     if (entry.isDirectory()) {
       copied += await copyReferenceLibrary(from, to);
-    } else if (entry.name === 'SKILL.md' || entry.name === 'llms.txt' || entry.name === 'AGENTS.md') {
+    } else if (
+      entry.name === 'SKILL.md' ||
+      entry.name === 'llms.txt' ||
+      entry.name === 'AGENTS.md'
+    ) {
       try {
         await writeFile(to, await readFile(from), { flag: 'wx' });
         copied += 1;
@@ -252,7 +257,8 @@ async function promptForAgent(scope) {
 }
 
 async function initProject(name, argv = []) {
-  if (!name || name.startsWith('-')) throw new Error('Usage: npx motionly init <project-folder>');
+  if (!name || name.startsWith('-'))
+    throw new Error('Usage: npx @coppsary/motionly init <project-folder>');
   const target = resolve(name);
   if (await exists(target)) {
     if ((await readdir(target)).length) throw new Error(`Folder is not empty: ${target}`);
@@ -286,7 +292,7 @@ async function initProject(name, argv = []) {
     if (providers.length) await installSkills(skillBase(scope, target), providers);
   }
   if (process.stdin.isTTY && process.stdout.isTTY) {
-    console.log(`\n  To reopen later: cd ${name} && npx motionly dev`);
+    console.log(`\n  To reopen later: cd ${name} && npx @coppsary/motionly dev`);
     await serveEditor(argv, target);
   }
 }
@@ -335,6 +341,8 @@ async function serveEditor(argv, projectFolder = null) {
       const url = new URL(request.url ?? '/', 'http://localhost');
       const pathname = decodeURIComponent(url.pathname);
 
+      if (await handleFfmpegExportRequest(request, response)) return;
+
       if (projectPath && pathname === '/api/motion-project') {
         if (request.method === 'GET' || request.method === 'HEAD') {
           const source = await readFile(projectPath);
@@ -408,7 +416,7 @@ async function serveEditor(argv, projectFolder = null) {
   server.on('error', (error) => {
     if (error.code === 'EADDRINUSE') {
       console.error(
-        `Port ${port} is in use. Try: npx motionly ${projectRoot ? 'dev ' : ''}--port ${port + 1}`
+        `Port ${port} is in use. Try: npx @coppsary/motionly ${projectRoot ? 'dev ' : ''}--port ${port + 1}`
       );
       process.exitCode = 1;
       return;
@@ -420,14 +428,14 @@ async function serveEditor(argv, projectFolder = null) {
 function printHelp() {
   console.log(`Motionly
 
-  npx motionly init <project-folder>            Create a project; asks which agent to set up
-  npx motionly init <folder> --provider codex   Create a project; install for one agent (no prompt)
-  npx motionly init <folder> --all              Create a project; install for every agent
-  npx motionly init <folder> --skip-skills      Create a project without agent skills
-  npx motionly skills add                       Install agent skills into an existing project
-  npx motionly skills add --all
-  npx motionly skills add --provider <codex|claude|gemini|opencode|kiro>
-  npx motionly dev [project-folder]             Reopen and edit a local project
+  npx @coppsary/motionly init <project-folder>            Create a project; asks which agent to set up
+  npx @coppsary/motionly init <folder> --provider codex   Create a project; install for one agent (no prompt)
+  npx @coppsary/motionly init <folder> --all              Create a project; install for every agent
+  npx @coppsary/motionly init <folder> --skip-skills      Create a project without agent skills
+  npx @coppsary/motionly skills add                       Install agent skills into an existing project
+  npx @coppsary/motionly skills add --all
+  npx @coppsary/motionly skills add --provider <codex|claude|gemini|opencode|kiro>
+  npx @coppsary/motionly dev [project-folder]             Reopen and edit a local project
 
 Options: --scope <project|global>, --port <number>, --no-open`);
 }
@@ -438,7 +446,7 @@ async function main() {
   if (command === 'skills') {
     if (subcommand !== 'add')
       throw new Error(
-        'Usage: npx motionly skills add [--provider <name> | --all] [--scope project|global]'
+        'Usage: npx @coppsary/motionly skills add [--provider <name> | --all] [--scope project|global]'
       );
     const options = await resolveSkillOptions(argv.slice(2));
     await installSkills(skillBase(options.scope, process.cwd()), options.providers);