@devinilabs/reelstack 1.2.0

package/cli/scaffold.js

@@ -0,0 +1,239 @@
+/**
+ * `reelstack scaffold` — copies a family template into the buyer's
+ * src/<Name>Reel.tsx, substitutes preset metadata (palette, BEATs,
+ * frame count, copy), and patches src/Root.tsx to register the new
+ * composition.
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const { info, success, fail, warn, c, REELSTACK_HOME } = require("./utils");
+
+const REELSTACK_PKG = path.dirname(__dirname); // resolves to the package root
+const TEMPLATES_DIR = path.join(REELSTACK_PKG, "templates");
+const FAMILIES_DIR  = path.join(REELSTACK_PKG, "families");
+
+const VALID_FAMILIES = ["glass", "paper", "dark", "warm", "forbidden"];
+
+/**
+ * Find the reference reel for a given family + preset, falling back from the
+ * post-init runtime location to the in-package dev location. Returns the
+ * absolute path if found, else null.
+ *
+ *   1. ~/.reelstack/reference/<family>/<preset>.tsx   (post-init)
+ *   2. <package-root>/reference/<family>/<preset>.tsx (dev / fresh install)
+ */
+function findReference(family, preset) {
+  const candidates = [
+    path.join(REELSTACK_HOME, "reference", family, `${preset}.tsx`),
+    path.join(REELSTACK_PKG, "reference", family, `${preset}.tsx`),
+  ];
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * Resolve the reference path for the chosen preset, optionally overridden by
+ * the buyer-supplied `--reference=<preset>` flag. Searches all families when
+ * the override is given (the buyer can cite any preset name without having
+ * to also state its family). Falls back to the canonical reference if the
+ * override doesn't resolve. Returns { path, source: "canonical"|"override" }
+ * or null if no reference exists at all.
+ */
+function resolveReference(family, preset, overridePreset) {
+  if (overridePreset) {
+    // Try the chosen family first, then walk the rest.
+    for (const f of [family, ...VALID_FAMILIES.filter((x) => x !== family)]) {
+      const p = findReference(f, overridePreset);
+      if (p) return { path: p, source: "override" };
+    }
+    warn(`--reference=${overridePreset} not found in any family. Falling back to canonical reference for ${preset}.`);
+  }
+  const canonical = findReference(family, preset);
+  return canonical ? { path: canonical, source: "canonical" } : null;
+}
+
+function loadPreset(family, presetName) {
+  const presetFile = path.join(FAMILIES_DIR, family, "presets", `${presetName}.ts`);
+  if (!fs.existsSync(presetFile)) {
+    throw new Error(`Preset "${presetName}" not found in family "${family}".`);
+  }
+  // Read the TS source and naively extract the exported `preset` object via
+  // regex. We don't want a TS runtime dependency in the CLI. The preset
+  // files are simple by design: a single `export const preset = { … } as const;`.
+  const src = fs.readFileSync(presetFile, "utf8");
+  // We don't need the full structure for scaffolding — only the fields we
+  // template into the output. Hand-roll a tiny extractor for the keys we use.
+  const grab = (key) => {
+    const m = src.match(new RegExp(`${key}\\s*:\\s*([0-9]+)`));
+    return m ? Number(m[1]) : null;
+  };
+  const grabStr = (key) => {
+    const m = src.match(new RegExp(`${key}\\s*:\\s*"([^"]+)"`));
+    return m ? m[1] : null;
+  };
+  return {
+    name: presetName,
+    family,
+    durationFrames: grab("durationFrames"),
+    fps: grab("fps") || 30,
+    hook: grabStr("hook") || "",
+    sub: grabStr("sub") || "",
+    cta: grabStr("cta") || "",
+    source: grabStr("source") || "",
+  };
+}
+
+function loadTemplate(family) {
+  const tplFile = path.join(TEMPLATES_DIR, family, "template.tsx");
+  if (!fs.existsSync(tplFile)) {
+    throw new Error(`Template for family "${family}" not found at ${tplFile}.`);
+  }
+  return fs.readFileSync(tplFile, "utf8");
+}
+
+function substitute(template, preset, name) {
+  return template
+    .replace(/__REEL_NAME__/g, name)
+    .replace(/__PRESET_NAME__/g, preset.name)
+    .replace(/__SOURCE_REEL__/g, preset.source)
+    .replace(/__DURATION_FRAMES__/g, String(preset.durationFrames || 1800))
+    .replace(/__FPS__/g, String(preset.fps))
+    .replace(/__HOOK__/g, preset.hook)
+    .replace(/__SUB__/g, preset.sub)
+    .replace(/__CTA__/g, preset.cta);
+}
+
+/**
+ * Inject a `/** REFERENCE: <abs-path> *\/` comment block into a scaffolded
+ * reel right after the auto-generated header JSDoc and before the first
+ * import. The buyer's Claude Code instance picks this up on subsequent
+ * iteration ("make this scene punchier") and reads the reference to ground
+ * its motion-vocabulary suggestions.
+ */
+function injectReferenceComment(tsx, refPath) {
+  const block = `/** REFERENCE: ${refPath} */\n`;
+  // Find the end of the leading auto-generated /** ... */ header JSDoc.
+  const headerEnd = tsx.indexOf("*/");
+  if (headerEnd === -1) {
+    // No header — prepend instead.
+    return block + tsx;
+  }
+  const insertAt = headerEnd + "*/".length;
+  // Skip the immediate newline so the comment lands on its own line.
+  const after = tsx[insertAt] === "\n" ? insertAt + 1 : insertAt;
+  return tsx.slice(0, after) + block + tsx.slice(after);
+}
+
+function patchRoot(rootPath, name, durationFrames) {
+  if (!fs.existsSync(rootPath)) {
+    fail(`src/Root.tsx not found at ${rootPath}. Skipping registration.`);
+    return false;
+  }
+  const src = fs.readFileSync(rootPath, "utf8");
+  if (src.includes(`id="${name}Reel"`)) {
+    info(`${name}Reel already registered in Root.tsx — skipping.`);
+    return true;
+  }
+  // Insert a Composition before the closing tag of the parent <Folder> or root.
+  // We insert right before the last </> or </Folder>.
+  const importLine = `import { ${name}Reel } from "./${name}Reel";\n`;
+  const compositionBlock = `
+        <Composition
+          id="${name}Reel"
+          component={${name}Reel}
+          durationInFrames={${durationFrames}}
+          fps={30}
+          width={1080}
+          height={1920}
+        />
+`;
+  // Add import after the last existing import.
+  const lastImport = src.lastIndexOf("\nimport ");
+  const afterLastImport = src.indexOf("\n", lastImport + 1);
+  let next = src.slice(0, afterLastImport + 1) + importLine + src.slice(afterLastImport + 1);
+  // Insert composition before the last </Folder> or </> closer.
+  const insertAt = next.lastIndexOf("</Folder>") !== -1
+    ? next.lastIndexOf("</Folder>")
+    : next.lastIndexOf("</>");
+  if (insertAt === -1) {
+    fail("Could not find </Folder> or </> in Root.tsx. Add the composition manually.");
+    return false;
+  }
+  next = next.slice(0, insertAt) + compositionBlock + next.slice(insertAt);
+  fs.writeFileSync(rootPath, next, "utf8");
+  return true;
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (const a of argv) {
+    const m = a.match(/^--([^=]+)=(.*)$/);
+    if (m) args[m[1]] = m[2];
+  }
+  return args;
+}
+
+async function run(argv, opts = {}) {
+  const args = parseArgs(argv);
+  const family = args.family;
+  const preset = args.preset;
+  const name = args.name;
+  const cwd = opts.cwd || process.cwd();
+
+  if (!family || !preset || !name) {
+    fail("Usage: reelstack scaffold --family=<f> --preset=<p> --name=<MyReel> [--vo=<path>] [--reference=<preset>]");
+    process.exit(2);
+  }
+  if (!VALID_FAMILIES.includes(family)) {
+    fail(`Unknown family "${family}". Valid: ${VALID_FAMILIES.join(", ")}.`);
+    process.exit(2);
+  }
+
+  const presetMeta = loadPreset(family, preset);
+  const template = loadTemplate(family);
+  let tsx = substitute(template, presetMeta, name);
+
+  // v1.1.1+ — resolve the reference reel for this preset (or buyer's override
+  // via --reference=<preset>) so a `/** REFERENCE: <path> */` comment can be
+  // injected into the scaffold, and a hint surfaced after Studio.
+  const ref = resolveReference(family, preset, args.reference);
+  if (ref) {
+    tsx = injectReferenceComment(tsx, ref.path);
+  }
+
+  const outFile = path.join(cwd, "src", `${name}Reel.tsx`);
+  if (fs.existsSync(outFile) && !args.force) {
+    fail(`${outFile} already exists. Pass --force to overwrite.`);
+    process.exit(2);
+  }
+  fs.mkdirSync(path.dirname(outFile), { recursive: true });
+  fs.writeFileSync(outFile, tsx, "utf8");
+  success(`Created ${path.relative(cwd, outFile)}`);
+
+  const rootPath = path.join(cwd, "src", "Root.tsx");
+  const registered = patchRoot(rootPath, name, presetMeta.durationFrames || 1800);
+  if (registered) success(`Registered ${name}Reel in src/Root.tsx`);
+
+  if (args.vo) {
+    info(`Voiceover passed: ${args.vo}. Run \`reelstack beats ${args.vo}\` to lock motion to whisper-cli output.`);
+  }
+
+  console.log("");
+  console.log(c.gray(`  Family:        `) + family);
+  console.log(c.gray(`  Preset:        `) + `${preset} (from ${presetMeta.source})`);
+  console.log(c.gray(`  Frame count:   `) + `${presetMeta.durationFrames} (${(presetMeta.durationFrames / 30).toFixed(1)}s @ 30fps)`);
+  console.log(c.gray(`  Output:        `) + path.relative(cwd, outFile));
+  console.log("");
+  console.log(c.cyan("→ ") + `Open Remotion Studio with ${c.bold("npm run dev")} and select "${name}Reel" from the comp list.`);
+  if (ref) {
+    console.log(c.cyan("ℹ ") + `Reference reel available: ${ref.path}`);
+    console.log(c.gray("  Claude will study this reel when iterating on your scaffold. Open it"));
+    console.log(c.gray("  yourself to learn the family's motion vocabulary."));
+  }
+  console.log("");
+}
+
+module.exports = { run };

package/cli/smoke.js

@@ -0,0 +1,76 @@
+/**
+ * Tier 4: smoke test. Runs after Tiers 1-3 pass and proves the full stack
+ * actually loads. Three fast, non-destructive checks.
+ *
+ * Steps:
+ *   1. scaffold-demo        — reelstack scaffold --family=glass --preset=graphify --name=Demo
+ *   2. remotion-compositions — npx remotion compositions   (proves Demo registers)
+ *   3. ffmpeg-version       — ffmpeg -version              (proves binary executes)
+ */
+const { spawnSync } = require("node:child_process");
+const { info, success, fail, c } = require("./utils");
+const scaffold = require("./scaffold");
+
+const STEPS = [
+  {
+    name: "scaffold-demo",
+    label: "Scaffolding Demo.tsx",
+    async run({ projectDir, scaffoldFn }) {
+      const fn = scaffoldFn || scaffold.run;
+      await fn(["--family=glass", "--preset=graphify", "--name=Demo"], { cwd: projectDir });
+      return { ok: true };
+    },
+  },
+  {
+    name: "remotion-compositions",
+    label: "Loading Remotion compositions",
+    async run({ projectDir, spawnFn }) {
+      const fn = spawnFn || spawnSync;
+      const result = fn("npx", ["remotion", "compositions"], {
+        cwd: projectDir,
+        stdio: "pipe",
+        encoding: "utf8",
+      });
+      return result.status === 0
+        ? { ok: true }
+        : { ok: false, message: (result.stderr || result.stdout || "unknown error").toString().trim() };
+    },
+  },
+  {
+    name: "ffmpeg-version",
+    label: "Validating ffmpeg",
+    async run({ spawnFn }) {
+      const fn = spawnFn || spawnSync;
+      const result = fn("ffmpeg", ["-version"], { stdio: "pipe", encoding: "utf8" });
+      return result.status === 0
+        ? { ok: true }
+        : { ok: false, message: (result.stderr || result.stdout || "ffmpeg failed").toString().trim() };
+    },
+  },
+];
+
+async function runAll(opts) {
+  for (const step of STEPS) {
+    info(step.label + "…");
+    let outcome;
+    try {
+      outcome = await step.run(opts);
+    } catch (err) {
+      outcome = { ok: false, message: err.message };
+    }
+    if (!outcome.ok) {
+      fail(`Smoke test failed at: ${step.name}`);
+      if (outcome.message) {
+        const lines = outcome.message.split("\n").filter((l) => l.trim());
+        const lastLine = lines[lines.length - 1] || outcome.message;
+        const truncated = lastLine.length > 200 ? lastLine.slice(0, 197) + "…" : lastLine;
+        console.log(c.gray("  " + truncated));
+      }
+      return { passed: false, failedAt: step.name };
+    }
+    success(step.label);
+  }
+  return { passed: true, failedAt: null };
+}
+
+module.exports = { STEPS, runAll };

package/cli/update.js

@@ -0,0 +1,26 @@
+/**
+ * `reelstack update` — print guidance for upgrading via npm.
+ *
+ * ReelStack updates are now distributed via npm. Running
+ * `npx @devinilabs/reelstack@latest init` is the canonical upgrade path:
+ * it re-validates the license, installs the latest runtime into
+ * ~/.reelstack/, and refreshes ~/.claude/skills/reelstack/.
+ *
+ * State (license key, machine-id, ~/.reelstack/state.json) is preserved
+ * across updates because init never overwrites those files on a re-run.
+ */
+const { banner, info, c } = require("./utils");
+
+async function run() {
+  banner();
+  console.log("");
+  info("ReelStack updates are now distributed via npm.");
+  console.log("");
+  console.log(c.gray("  Run this from any Remotion project to upgrade to the latest:"));
+  console.log(`    ${c.cyan("npx @devinilabs/reelstack@latest init")}`);
+  console.log("");
+  console.log(c.gray("  Your license key + ~/.reelstack/state.json are preserved across updates."));
+  console.log("");
+}
+
+module.exports = { run };

package/cli/utils.js

@@ -0,0 +1,184 @@
+/**
+ * Shared CLI helpers: ANSI colors, banner, readline prompts, file ops.
+ * No external dependencies — keeps the install lean.
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+const readline = require("node:readline");
+const os = require("node:os");
+const { spawnSync } = require("node:child_process");
+
+const NO_COLOR = process.env.NO_COLOR === "1" || !process.stdout.isTTY;
+
+const wrap = (open, close) => (s) =>
+  NO_COLOR ? String(s) : `\x1b[${open}m${s}\x1b[${close}m`;
+
+const c = {
+  bold:    wrap(1, 22),
+  dim:     wrap(2, 22),
+  red:     wrap(31, 39),
+  green:   wrap(32, 39),
+  yellow:  wrap(33, 39),
+  blue:    wrap(34, 39),
+  magenta: wrap(35, 39),
+  cyan:    wrap(36, 39),
+  gray:    wrap(90, 39),
+};
+
+const REELSTACK_HOME = path.join(os.homedir(), ".reelstack");
+const LICENSE_CACHE = path.join(REELSTACK_HOME, ".license");
+const CLAUDE_SKILLS_HOME = path.join(os.homedir(), ".claude", "skills");
+const CLAUDE_COMMANDS_HOME = path.join(os.homedir(), ".claude", "commands");
+
+function banner() {
+  // Read version from package.json so the banner stays in sync across releases.
+  const PKG_VERSION = require("../package.json").version;
+  // Pad-right to keep the box visually balanced regardless of version length.
+  const versionLine = `  v${PKG_VERSION}   ·   reelstack.dev`;
+  const padded = versionLine.padEnd(43, " ");
+  const lines = [
+    "",
+    c.magenta("  ┌─────────────────────────────────────────┐"),
+    c.magenta("  │") + "  " + c.bold(c.cyan("ReelStack")) + c.gray(" — Premium 9:16 Reel OS  ") + c.magenta("│"),
+    c.magenta("  │") + c.gray(padded) + c.magenta("│"),
+    c.magenta("  └─────────────────────────────────────────┘"),
+    "",
+  ];
+  console.log(lines.join("\n"));
+}
+
+function info(msg)    { console.log(c.cyan("ℹ ") + msg); }
+function success(msg) { console.log(c.green("✓ ") + msg); }
+function warn(msg)    { console.warn(c.yellow("⚠ ") + msg); }
+function fail(msg)    { console.error(c.red("✗ ") + msg); }
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function writeFileSafe(file, contents) {
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, contents, "utf8");
+}
+
+function ask(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(c.cyan("? ") + question + " ", (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function askYesNo(question, defaultYes = true) {
+  const suffix = defaultYes ? "(Y/n)" : "(y/N)";
+  const answer = (await ask(`${question} ${suffix}`)).toLowerCase();
+  if (!answer) return defaultYes;
+  return answer === "y" || answer === "yes";
+}
+
+function which(bin) {
+  const PATH = (process.env.PATH || "").split(path.delimiter);
+  const exts = process.platform === "win32"
+    ? (process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM").split(";")
+    : [""];
+  for (const dir of PATH) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, bin + ext);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+const STATE_FILE = path.join(REELSTACK_HOME, "state.json");
+
+function loadState() {
+  try {
+    return JSON.parse(fs.readFileSync(STATE_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function saveState(patch) {
+  const current = loadState();
+  const next = { ...current, ...patch };
+  ensureDir(path.dirname(STATE_FILE));
+  fs.writeFileSync(STATE_FILE, JSON.stringify(next, null, 2), "utf8");
+}
+
+// Returns { kind, command, install }:
+//   kind: "auto"  — install() can run silently with user consent (e.g. brew on macOS)
+//   kind: "guide" — print command and let the user run it themselves
+function getPlatformInstaller(platform, bin, opts = {}) {
+  const whichFn = opts.whichFn || which;
+
+  if (platform === "darwin") {
+    if (whichFn("brew")) {
+      return {
+        kind: "auto",
+        command: `brew install ${bin}`,
+        install() {
+          return spawnSync("brew", ["install", bin], { stdio: "inherit" });
+        },
+      };
+    }
+    return {
+      kind: "guide",
+      command: `Install Homebrew (https://brew.sh), then: brew install ${bin}`,
+      install: null,
+    };
+  }
+
+  if (platform === "linux") {
+    return {
+      kind: "guide",
+      command: [
+        `apt-get install ${bin}     # Debian/Ubuntu`,
+        `dnf install ${bin}         # Fedora`,
+        `pacman -S ${bin}           # Arch`,
+      ].join("\n  "),
+      install: null,
+    };
+  }
+
+  if (platform === "win32") {
+    return {
+      kind: "guide",
+      command: [
+        `choco install ${bin}       # Chocolatey`,
+        `scoop install ${bin}       # Scoop`,
+      ].join("\n  "),
+      install: null,
+    };
+  }
+
+  return {
+    kind: "guide",
+    command: `Install ${bin} via your platform's package manager`,
+    install: null,
+  };
+}
+
+module.exports = {
+  c,
+  banner,
+  info, success, warn, fail,
+  ensureDir, readJson, writeFileSafe,
+  ask, askYesNo,
+  which,
+  REELSTACK_HOME,
+  LICENSE_CACHE,
+  CLAUDE_SKILLS_HOME,
+  CLAUDE_COMMANDS_HOME,
+  STATE_FILE,
+  loadState,
+  saveState,
+  getPlatformInstaller,
+};