@svelteframe/cli 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sumeet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @svelteframe/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line interface for Svelteframe video compositions.
+
+## Prerequisites
+
+- **ffmpeg** installed on your system (`brew install ffmpeg` on macOS, or via your Linux package manager)
+- **Chromium** installed for Playwright (`npx playwright install chromium`)
+
+## Installation
+
+```sh
+npm install -g @svelteframe/cli
+# or install as project dev dependency
+pnpm add -D @svelteframe/cli
+```
+
+## Usage
+
+```sh
+# Render a composition to MP4 video
+svelteframe render <composition-id> [output.mp4]
+
+# Render a single still frame to image
+svelteframe still <composition-id> [output.png] --frame 30
+
+# List available compositions
+svelteframe compositions
+```
+
+## Options
+
+- `--props <json|path>`: Pass props as a JSON string or JSON file path
+- `--port <number>`: Port for the internal dev server
+- `--root <path>`: Root folder of the project containing compositions
+- `--quality <1-100>`: JPEG quality (default: 90)
+- `--format <jpeg|png>`: Image format for intermediate frames
+
+## License
+
+MIT

package/dist/args.js

@@ -0,0 +1,153 @@
+import { parseArgs } from 'node:util';
+/** A mistake in how the command was written; reported with the usage hint, exit code 2. */
+export class UsageError extends Error {
+    name = 'UsageError';
+}
+export const HELP = `svelteframe: render videos made with Svelteframe
+
+Usage:
+  svelteframe render <id> [options]        Render a composition to a video
+  svelteframe still <id> [options]         Capture one frame as an image
+  svelteframe compositions [options]       List the project's compositions
+
+Common options:
+  --root <dir>          the project (default: the current directory)
+  --url <base url>      use a server that is already running instead of starting one
+  --dev                 start the dev server instead of building and previewing the project
+  --chromium <path>     Chromium executable to use
+
+render options:
+  --out <file>          output video (default <id>.mp4)
+  --props <file>        JSON file with input props
+  --concurrency <n>     pages rendering at once (default: half the CPU cores)
+  --quality <0-100>     JPEG quality of captured frames (default 90)
+  --png                 capture PNG frames instead of JPEG
+
+still options:
+  --frame <n>           frame to capture (default 0)
+  --out <file>          output image, .png or .jpg (default <id>.png)
+  --props <file>        JSON file with input props
+  --quality <0-100>     JPEG quality when writing .jpg (default 90)
+
+compositions options:
+  --json                print JSON instead of a table
+
+Other:
+  -h, --help            show this help
+  -v, --version         show the version`;
+const OPTIONS = {
+    root: { type: 'string' },
+    url: { type: 'string' },
+    dev: { type: 'boolean' },
+    chromium: { type: 'string' },
+    out: { type: 'string' },
+    props: { type: 'string' },
+    concurrency: { type: 'string' },
+    quality: { type: 'string' },
+    png: { type: 'boolean' },
+    frame: { type: 'string' },
+    json: { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' },
+    version: { type: 'boolean', short: 'v' }
+};
+const SHARED = ['root', 'url', 'dev', 'chromium'];
+const ALLOWED = {
+    render: [...SHARED, 'out', 'props', 'concurrency', 'quality', 'png'],
+    still: [...SHARED, 'out', 'props', 'frame', 'quality'],
+    compositions: [...SHARED, 'json']
+};
+function whole(value, flag, min) {
+    const n = Number(value);
+    if (value.trim() === '' || !Number.isInteger(n) || n < min) {
+        throw new UsageError(`${flag} must be a whole number of ${min} or more, got "${value}"`);
+    }
+    return n;
+}
+function quality(value) {
+    if (value === undefined)
+        return 90;
+    const n = Number(value);
+    if (value.trim() === '' || !Number.isFinite(n) || n < 0 || n > 100) {
+        throw new UsageError(`--quality must be a number from 0 to 100, got "${value}"`);
+    }
+    return n;
+}
+/** Turn command-line arguments (without `node` and the script) into a command. */
+export function parseCommand(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });
+    }
+    catch (err) {
+        const message = err.message;
+        // A value that starts with "-" reads as another option.
+        const ambiguous = /Option '(--[\w-]+)[^']*' argument is ambiguous/.exec(message);
+        if (ambiguous) {
+            throw new UsageError(`${ambiguous[1]} needs a value. A value that starts with "-" must be written ${ambiguous[1]}=<value>`);
+        }
+        throw new UsageError(message.replace(/\. To specify a positional.*$/s, ''));
+    }
+    const { values, positionals } = parsed;
+    if (values.help)
+        return { name: 'help' };
+    if (values.version)
+        return { name: 'version' };
+    const [name, ...rest] = positionals;
+    if (name === undefined)
+        return { name: 'help' };
+    if (name !== 'render' && name !== 'still' && name !== 'compositions') {
+        throw new UsageError(`Unknown command "${name}". Commands: render, still, compositions`);
+    }
+    for (const option of Object.keys(values)) {
+        if (!ALLOWED[name].includes(option)) {
+            throw new UsageError(`--${option} does not apply to "${name}"`);
+        }
+    }
+    const shared = { root: values.root, url: values.url, dev: values.dev ?? false, chromium: values.chromium };
+    if (shared.url !== undefined) {
+        let protocol;
+        try {
+            protocol = new URL(shared.url).protocol;
+        }
+        catch {
+            // Reported below.
+        }
+        if (protocol !== 'http:' && protocol !== 'https:') {
+            throw new UsageError(`--url must be a full URL such as http://localhost:5173, got "${shared.url}"`);
+        }
+        if (shared.dev)
+            throw new UsageError('--dev has no effect with --url: no server is started');
+    }
+    if (name === 'compositions') {
+        if (rest.length > 0)
+            throw new UsageError(`"compositions" takes no arguments, got "${rest[0]}"`);
+        return { name, ...shared, json: values.json ?? false };
+    }
+    const [id, ...extra] = rest;
+    if (id === undefined) {
+        throw new UsageError(`Missing the composition id: svelteframe ${name} <id>. See "svelteframe compositions".`);
+    }
+    if (extra.length > 0)
+        throw new UsageError(`"${name}" takes one composition id, got extra "${extra[0]}"`);
+    if (name === 'render') {
+        return {
+            name,
+            ...shared,
+            id,
+            out: values.out ?? `${id}.mp4`,
+            props: values.props,
+            concurrency: values.concurrency === undefined ? undefined : whole(values.concurrency, '--concurrency', 1),
+            quality: quality(values.quality),
+            png: values.png ?? false
+        };
+    }
+    return {
+        name,
+        ...shared,
+        id,
+        frame: values.frame === undefined ? 0 : whole(values.frame, '--frame', 0),
+        out: values.out ?? `${id}.png`,
+        props: values.props,
+        quality: quality(values.quality)
+    };
+}

package/dist/bin.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { HELP, UsageError, parseCommand } from './args.js';
+import { run } from './run.js';
+async function main() {
+    let command;
+    try {
+        command = parseCommand(process.argv.slice(2));
+    }
+    catch (err) {
+        if (!(err instanceof UsageError))
+            throw err;
+        process.stderr.write(`${err.message}\nRun "svelteframe --help" for usage.\n`);
+        return 2;
+    }
+    if (command.name === 'help') {
+        process.stdout.write(`${HELP}\n`);
+        return 0;
+    }
+    if (command.name === 'version') {
+        const manifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+        process.stdout.write(`${manifest.version}\n`);
+        return 0;
+    }
+    // Ctrl-C stops the render and shuts the server down before leaving; a second one leaves at once.
+    const controller = new AbortController();
+    process.once('SIGINT', () => {
+        process.stderr.write('\nInterrupted, cleaning up...\n');
+        controller.abort();
+        process.once('SIGINT', () => process.exit(130));
+    });
+    try {
+        await run(command, {
+            cwd: process.cwd(),
+            signal: controller.signal,
+            stdout: process.stdout,
+            stderr: process.stderr,
+            verbose: process.env.SVELTEFRAME_VERBOSE === '1'
+        });
+        return 0;
+    }
+    catch (err) {
+        if (process.stdout.isTTY)
+            process.stdout.write('\n');
+        if (controller.signal.aborted)
+            return 130;
+        process.stderr.write(`${err instanceof Error ? err.message : err}\n`);
+        return 1;
+    }
+}
+process.exit(await main());

package/dist/format.js

@@ -0,0 +1,45 @@
+/** Check what a project served as its composition list. */
+export function parseListing(value) {
+    if (!Array.isArray(value))
+        throw new Error('the composition list is not an array');
+    return value.map((entry, i) => {
+        const where = `composition list entry ${i}`;
+        if (typeof entry !== 'object' || entry === null)
+            throw new Error(`${where} is not an object`);
+        const { id, fps, width, height, durationInFrames, defaultProps, calculatesMetadata } = entry;
+        if (typeof id !== 'string' || id === '')
+            throw new Error(`${where}: id must be a string`);
+        for (const [name, v] of Object.entries({ fps, width, height, durationInFrames })) {
+            if (typeof v !== 'number' || !Number.isFinite(v))
+                throw new Error(`${where} (${id}): ${name} must be a number`);
+        }
+        return {
+            id,
+            fps: fps,
+            width: width,
+            height: height,
+            durationInFrames: durationInFrames,
+            defaultProps: typeof defaultProps === 'object' && defaultProps !== null ? defaultProps : {},
+            calculatesMetadata: calculatesMetadata === true
+        };
+    });
+}
+/** A table of compositions for the terminal. */
+export function formatListing(list) {
+    if (list.length === 0)
+        return 'No compositions found.';
+    const rows = list.map((c) => [
+        c.id,
+        `${c.width}×${c.height}`,
+        String(c.fps),
+        String(c.durationInFrames),
+        `${(c.durationInFrames / c.fps).toFixed(1)}s${c.calculatesMetadata ? '*' : ''}`,
+        Object.keys(c.defaultProps).join(', ') || '-'
+    ]);
+    const table = [['ID', 'SIZE', 'FPS', 'FRAMES', 'LENGTH', 'PROPS'], ...rows];
+    const widths = table[0].map((_, column) => Math.max(...table.map((row) => row[column].length)));
+    const lines = table.map((row) => row.map((cell, i) => cell.padEnd(widths[i])).join('  ').trimEnd());
+    if (list.some((c) => c.calculatesMetadata))
+        lines.push('', '* the length depends on the props');
+    return lines.join('\n');
+}

package/dist/run.js

@@ -0,0 +1,96 @@
+import { resolve } from 'node:path';
+import { buildRenderUrl, readPropsFile, renderStill, renderVideo } from '@svelteframe/renderer';
+import { formatListing, parseListing } from './format.js';
+import { startProjectServer } from './server.js';
+/** Run `work` against the project's server: the one at `--url`, or one started for the occasion. */
+async function withProject(command, io, work) {
+    if (command.url !== undefined)
+        return work(command.url);
+    const server = await startProjectServer({
+        root: resolve(io.cwd, command.root ?? '.'),
+        dev: command.dev,
+        verbose: io.verbose,
+        signal: io.signal,
+        onStatus: (message) => io.stderr.write(`${message}\n`)
+    });
+    try {
+        return await work(server.url);
+    }
+    finally {
+        await server.close();
+    }
+}
+async function readProps(command, io) {
+    return command.props === undefined ? undefined : readPropsFile(resolve(io.cwd, command.props));
+}
+const progressLine = (p) => `frame ${p.frame}/${p.total}  ${(p.elapsedMs / 1000).toFixed(1)}s  ${p.fps.toFixed(1)} fps`;
+async function render(command, io) {
+    const output = resolve(io.cwd, command.out);
+    const props = await readProps(command, io);
+    await withProject(command, io, async (base) => {
+        const tty = io.stdout.isTTY;
+        const result = await renderVideo({
+            url: buildRenderUrl({ url: base, composition: command.id, props }),
+            output,
+            imageFormat: command.png ? 'png' : 'jpeg',
+            quality: command.quality,
+            chromiumPath: command.chromium,
+            concurrency: command.concurrency,
+            signal: io.signal,
+            onProgress: (p) => {
+                if (tty)
+                    io.stdout.write(`\r${progressLine(p)}`);
+                else if (p.frame % 30 === 0 || p.frame === p.total)
+                    io.stdout.write(`${progressLine(p)}\n`);
+            }
+        });
+        if (tty)
+            io.stdout.write('\n');
+        const audio = result.audioSegments > 0 ? ` with ${result.audioSegments} audio segment(s)` : '';
+        const workers = result.concurrency > 1 ? ` using ${result.concurrency} workers` : '';
+        io.stdout.write(`Rendered ${result.frame} frames${audio}${workers} to ${output}\n`);
+    });
+}
+async function still(command, io) {
+    const output = resolve(io.cwd, command.out);
+    const props = await readProps(command, io);
+    await withProject(command, io, async (base) => {
+        const result = await renderStill({
+            url: buildRenderUrl({ url: base, composition: command.id, props }),
+            output,
+            frame: command.frame,
+            quality: command.quality,
+            chromiumPath: command.chromium,
+            signal: io.signal
+        });
+        io.stdout.write(`Saved frame ${result.frame} of ${command.id} (${result.width}×${result.height}) to ${output}\n`);
+    });
+}
+async function compositions(command, io) {
+    const listing = await withProject(command, io, async (base) => {
+        const endpoint = new URL('svelteframe/compositions.json', base.endsWith('/') ? base : `${base}/`);
+        const response = await fetch(endpoint, { signal: io.signal });
+        if (!response.ok) {
+            throw new Error(`${endpoint} answered ${response.status}. The project needs a route at /svelteframe/compositions.json ` +
+                'that returns describeCompositions(compositions) from @svelteframe/core.');
+        }
+        try {
+            return parseListing(await response.json());
+        }
+        catch (err) {
+            throw new Error(`${endpoint} did not return a composition list: ${err.message}`);
+        }
+    });
+    io.stdout.write(command.json ? `${JSON.stringify(listing, null, 2)}\n` : `${formatListing(listing)}\n`);
+}
+/** Run a command that talks to the project. Rejects with the reason when it fails. */
+export async function run(command, io) {
+    switch (command.name) {
+        case 'render':
+            return render(command, io);
+        case 'still':
+            return still(command, io);
+        case 'compositions':
+            return compositions(command, io);
+    }
+}

package/dist/server.js

@@ -0,0 +1,173 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { createServer as createNetServer } from 'node:net';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { format } from 'node:util';
+/**
+ * The directory that has `name` in its `node_modules`, searching from `from` upwards. Unlike
+ * `require.resolve`, this ignores `NODE_PATH` (which pnpm sets), so it cannot find some other copy.
+ */
+function findInstalled(name, from) {
+    for (let dir = from;; dir = dirname(dir)) {
+        if (existsSync(join(dir, 'node_modules', name, 'package.json')))
+            return dir;
+        if (dirname(dir) === dir)
+            return undefined;
+    }
+}
+/** Import the Vite that is installed in the project, whatever version it is. */
+async function loadProjectVite(root) {
+    const installedAt = findInstalled('vite', root);
+    if (!installedAt) {
+        throw new Error(`Could not find "vite" in ${root}. Are the project's dependencies installed?`);
+    }
+    const entry = createRequire(join(installedAt, 'package.json')).resolve('vite');
+    return (await import(pathToFileURL(entry).href));
+}
+/**
+ * Run `work` with console output held back. Build tools print progress straight to the console,
+ * which would end up in the middle of our own output (`--json` must stay clean). If `work` fails,
+ * what it printed is added to the error, as that is usually the explanation.
+ */
+async function withQuietConsole(work) {
+    const methods = ['log', 'info', 'warn', 'error'];
+    const original = Object.fromEntries(methods.map((method) => [method, console[method]]));
+    const captured = [];
+    for (const method of methods)
+        console[method] = (...args) => void captured.push(format(...args));
+    try {
+        return await work();
+    }
+    catch (err) {
+        const output = captured.join('\n').trim();
+        if (err instanceof Error && output)
+            err.message += `\n\nOutput of the build:\n${output}`;
+        throw err;
+    }
+    finally {
+        Object.assign(console, original);
+    }
+}
+/** Where the lock for a project lives: outside the project, and always writable. */
+export function lockPathFor(root) {
+    return join(tmpdir(), `svelteframe-lock-${createHash('sha1').update(resolve(root)).digest('hex').slice(0, 12)}`);
+}
+const isAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means it exists but belongs to someone else.
+        return err.code === 'EPERM';
+    }
+};
+/**
+ * Building writes to the project's own build folder, which the preview server then serves from.
+ * Two commands doing that at once would break each other, so they take turns: the lock is held
+ * from the build until the server is closed. A lock left behind by a process that is gone is ignored.
+ * Returns a function that releases it.
+ */
+async function acquireBuildLock(root, options) {
+    const lock = lockPathFor(root);
+    let announced = false;
+    for (;;) {
+        options.signal?.throwIfAborted();
+        try {
+            await mkdir(lock);
+            await writeFile(join(lock, 'pid'), String(process.pid));
+            return () => rm(lock, { recursive: true, force: true });
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+        }
+        const owner = Number(await readFile(join(lock, 'pid'), 'utf8').catch(() => ''));
+        // No pid yet means it was only just taken, unless it has been like that for a while.
+        const age = await stat(lock).then((info) => Date.now() - info.mtimeMs, () => 0);
+        if ((owner > 0 && !isAlive(owner)) || (!owner && age > 10_000)) {
+            await rm(lock, { recursive: true, force: true });
+            continue;
+        }
+        if (!announced) {
+            announced = true;
+            options.onStatus?.(`Another svelteframe command${owner ? ` (process ${owner})` : ''} is using this project; waiting for it...`);
+        }
+        await new Promise((done) => setTimeout(done, 250));
+    }
+}
+/** A port nothing is listening on right now. */
+export function getFreePort() {
+    return new Promise((resolvePort, reject) => {
+        const probe = createNetServer();
+        probe.once('error', reject);
+        probe.listen(0, '127.0.0.1', () => {
+            const { port } = probe.address();
+            probe.close(() => resolvePort(port));
+        });
+    });
+}
+/**
+ * Serve the project with its own Vite: `vite build` then `vite preview` by default, which is
+ * steady and what you ship, or the dev server with `dev`. Returns once it answers.
+ *
+ * The working directory moves to the project while it runs, as it would if you had run Vite
+ * there; server routes that read files relative to it depend on that. `close()` moves it back.
+ * Building and previewing take turns between commands (see `acquireBuildLock`).
+ */
+export async function startProjectServer(options) {
+    const root = resolve(options.root);
+    if (!existsSync(join(root, 'package.json'))) {
+        throw new Error(`No project at ${root}: there is no package.json. Run this in your project, or pass --root.`);
+    }
+    const vite = await loadProjectVite(root);
+    const port = await getFreePort();
+    const logLevel = options.verbose ? 'info' : 'warn';
+    const host = '127.0.0.1';
+    const releaseLock = options.dev ? async () => { } : await acquireBuildLock(root, options);
+    const previousDirectory = process.cwd();
+    process.chdir(root);
+    try {
+        let server;
+        if (options.dev) {
+            options.onStatus?.('Starting the dev server...');
+            const dev = await vite.createServer({ root, logLevel, server: { host, port, strictPort: true } });
+            await dev.listen();
+            server = dev;
+        }
+        else {
+            options.onStatus?.('Building the project...');
+            // `build()` alone builds only the client; an app with server code needs every environment.
+            const build = async () => {
+                if (vite.createBuilder)
+                    await (await vite.createBuilder({ root, logLevel })).buildApp();
+                else
+                    await vite.build({ root, logLevel });
+            };
+            await (options.verbose ? build() : withQuietConsole(build));
+            options.onStatus?.('Starting the preview server...');
+            server = await vite.preview({ root, logLevel, preview: { host, port, strictPort: true } });
+        }
+        return {
+            url: server.resolvedUrls?.local?.[0] ?? `http://${host}:${port}/`,
+            close: async () => {
+                try {
+                    await server.close();
+                }
+                finally {
+                    process.chdir(previousDirectory);
+                    await releaseLock();
+                }
+            }
+        };
+    }
+    catch (err) {
+        process.chdir(previousDirectory);
+        await releaseLock();
+        throw err;
+    }
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@svelteframe/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Command-line interface for rendering Svelteframe video compositions",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "svelteframe": "./dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@svelteframe/renderer": "^0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "playwright": "^1.64.1",
+    "tsx": "^4.23.15",
+    "typescript": "^6.0.3"
+  },
+  "keywords": [
+    "svelte",
+    "svelteframe",
+    "video",
+    "cli"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "precheck": "pnpm --filter @svelteframe/renderer build",
+    "check": "tsc --noEmit",
+    "pretest": "pnpm --filter @svelteframe/renderer build && pnpm run build",
+    "test": "tsx --test src/*.test.ts"
+  }
 }