@elah/cli 0.1.0 → 0.1.1

package/README.md

@@ -3,6 +3,27 @@
 Headless command-line runtime for the Elah video engine. A thin consumer of
 `@elah/core`'s public APIs — no rendering or timeline logic lives here.
 
+[![npm](https://img.shields.io/npm/v/@elah/cli)](https://www.npmjs.com/package/@elah/cli)
+[![node](https://img.shields.io/node/v/@elah/cli)](https://www.npmjs.com/package/@elah/cli)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/elahlabs/elah/blob/main/LICENSE)
+
+---
+
+## Install
+
+```bash
+npm install -g @elah/cli
+```
+
+Or without installing, via `npx @elah/cli <command>`. Requires Node >= 18.17.
+`export`/`build --export`/`serve` additionally require a system Google Chrome
+(or `--browser <path>` / `ELAH_BROWSER`) — see [Serve mode](#serve-mode) and
+[Docker](#docker) for headless environments.
+
+---
+
+## Commands
+
 ```
 elah split  --project <in.json> --clip <clipId> --at <frame|timecode> [--out <out.json>]
 elah trim   --project <in.json> --clip <clipId> [--start <frame|timecode>] [--duration <frames|timecode>] [--out <out.json>]
@@ -18,6 +39,8 @@ output is identical to Editor output by construction. Exit codes: `0` success,
 `1` validation/runtime failure, `2` usage error. Diagnostics go to stderr;
 `split`/`trim` print the resulting project JSON to stdout unless `--out` is given.
 
+---
+
 ## The build spec — the AI-generation contract
 
 `elah build` consumes a seconds-based spec, probes each media asset's real
@@ -68,6 +91,8 @@ Rules:
 Then: `elah build --spec spec.json --export final.mp4` (add `--out project.json`
 to keep the editable project; export options like `--height` pass through).
 
+---
+
 ## Library API
 
 `@elah/cli` is also importable — no shelling out, no stderr parsing:
@@ -100,6 +125,8 @@ await session.close()
 Errors throw `CliError` (aliased `ElahError`) with a `.message` that is
 already the human-readable, path-addressed text (`clips[2].duration must be …`).
 
+---
+
 ## Serve mode
 
 `elah serve` runs a long-lived HTTP render server with a warm browser, so
@@ -123,12 +150,16 @@ There is no job queue — this is a synchronous, retry-on-503 contract. See
 [docs/deploy-render-server.md](../../docs/deploy-render-server.md) for the
 full contract, security notes, and deployment options.
 
+---
+
 ## Docker
 
 A Dockerfile that installs branded Chrome + fonts and runs `elah serve` is at
 [`Dockerfile`](./Dockerfile) (build from the repo root — see
 [docs/deploy-render-server.md](../../docs/deploy-render-server.md)).
 
+---
+
 ## Validation tooling
 
 - `ELAH_E2E=1 npm test --workspace=packages/cli` additionally runs a browser
@@ -142,3 +173,29 @@ A Dockerfile that installs branded Chrome + fonts and runs `elah serve` is at
   both pipelines are individually deterministic).
 
 Full documentation lands with the release phase; see `elah --help`.
+
+---
+
+## Package layers
+
+```
+@elah/core      — engine, playback, resolver, stores, media, export (framework-agnostic)
+@elah/timeline  — React timeline UI components and hooks
+@elah/editor    — EditorProvider, Preview, AssetPanel + re-exports everything above
+@elah/cli       — headless split/trim/build/export/serve on top of @elah/core (this package)
+```
+
+Use `@elah/cli` for automation, AI-generation pipelines, and server-side rendering.
+Use `@elah/editor` when you need an interactive, in-browser editing UI.
+
+---
+
+## Links
+
+- [Website](https://www.elah.dev)
+- [GitHub](https://github.com/elahlabs/elah)
+- [Engine — @elah/core](https://www.npmjs.com/package/@elah/core)
+- [React timeline UI — @elah/timeline](https://www.npmjs.com/package/@elah/timeline)
+- [Full editor SDK — @elah/editor](https://www.npmjs.com/package/@elah/editor)
+- [License](https://github.com/elahlabs/elah/blob/main/LICENSE)
+- [Commercial licensing](mailto:paul@elah.dev)

package/dist/bin.js

@@ -39879,6 +39879,46 @@ var init_build = __esm({
 // src/lib/serve.ts
 import { createServer as createServer2 } from "node:http";
 import { randomUUID as randomUUID2 } from "node:crypto";
+function curlExample(origin) {
+  return `curl -X POST ${origin}/render -H 'content-type: application/json' -d '${HELLO_SPEC}' -o hello.mp4`;
+}
+function powershellExample(origin) {
+  return `Invoke-RestMethod -Uri "${origin}/render" -Method Post -ContentType "application/json" -Body '${HELLO_SPEC}' -OutFile hello.mp4`;
+}
+function welcomePage(origin, browserConnected) {
+  const escapedCurl = curlExample(origin).replace(/</g, "&lt;");
+  const escapedPowershell = powershellExample(origin).replace(/</g, "&lt;");
+  return `<!doctype html>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>elah serve</title>
+<style>
+  body { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+         max-width: 720px; margin: 3rem auto; padding: 0 1rem; line-height: 1.6;
+         background: #0d1117; color: #e6edf3; }
+  h1 { font-size: 1.3rem; } h1 span { color: #7ee787; }
+  code, pre { background: #161b22; border: 1px solid #30363d; border-radius: 6px; }
+  code { padding: 0.1em 0.4em; }
+  pre { padding: 0.8em 1em; overflow-x: auto; white-space: pre-wrap; word-break: break-all; }
+  table { border-collapse: collapse; } td { padding: 0.15em 1em 0.15em 0; vertical-align: top; }
+  a { color: #58a6ff; }
+  .muted { color: #8b949e; }
+</style>
+<h1>elah serve <span>&#9679; ${browserConnected ? "browser connected" : "browser disconnected"}</span></h1>
+<p>Headless render server for the <a href="https://www.elah.dev">elah</a> video engine.
+POST a build spec, get an MP4 back.</p>
+<table>
+  <tr><td><code>GET /healthz</code></td><td class="muted">status + browser state</td></tr>
+  <tr><td><code>POST /render</code></td><td class="muted">build spec JSON in, <code>video/mp4</code> out</td></tr>
+</table>
+<p>Render your first video (no media files needed):</p>
+<pre>${escapedCurl}</pre>
+<p class="muted">On Windows PowerShell, <code>curl</code> is aliased to Invoke-WebRequest and won't accept <code>-H</code>/<code>-d</code> the curl way &mdash; use this instead:</p>
+<pre>${escapedPowershell}</pre>
+<p class="muted">Spec schema: assets map + clips array &mdash; see the
+<a href="https://github.com/elahlabs/elah/tree/main/packages/cli#readme">@elah/cli README</a>.</p>
+`;
+}
 function createServeHandler(deps) {
   return (req, res) => {
     void handle(req, res, deps).catch((err) => {
@@ -39890,6 +39930,17 @@ function createServeHandler(deps) {
 }
 async function handle(req, res, deps) {
   const url2 = new URL(req.url ?? "/", "http://localhost");
+  if (url2.pathname === "/") {
+    if (req.method !== "GET") {
+      writeJson(res, 405, { error: "method not allowed" });
+      return;
+    }
+    const origin = `http://${req.headers.host ?? "localhost"}`;
+    const html = welcomePage(origin, deps.browserConnected());
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8", "content-length": Buffer.byteLength(html) });
+    res.end(html);
+    return;
+  }
   if (url2.pathname === "/healthz") {
     if (req.method !== "GET") {
       writeJson(res, 405, { error: "method not allowed" });
@@ -40029,7 +40080,7 @@ async function startServe(options) {
     })
   };
 }
-var Semaphore, DEFAULT_MAX_BODY_BYTES;
+var Semaphore, DEFAULT_MAX_BODY_BYTES, HELLO_SPEC;
 var init_serve = __esm({
   "src/lib/serve.ts"() {
     "use strict";
@@ -40053,6 +40104,7 @@ var init_serve = __esm({
       }
     };
     DEFAULT_MAX_BODY_BYTES = 5 * 1024 * 1024;
+    HELLO_SPEC = '{"clips":[{"track":"text","text":"Hello from elah","start":0,"duration":3,"fontSize":96}]}';
   }
 });
 
@@ -40097,6 +40149,15 @@ async function runServe(args) {
   if (host !== "127.0.0.1") {
     stderr("warning: no authentication \u2014 expose only on a trusted network");
   }
+  stderr("");
+  const renderOrigin = `http://${host}:${handle2.port}`;
+  stderr("render your first video:");
+  if (process.platform === "win32") {
+    stderr(`  ${powershellExample(renderOrigin)}`);
+    stderr(`  (or, with curl.exe: ${curlExample(renderOrigin)})`);
+  } else {
+    stderr(`  ${curlExample(renderOrigin)}`);
+  }
   await new Promise((resolve4) => {
     let shuttingDown = false;
     const shutdown = () => {

package/dist/index.js

@@ -39395,6 +39395,47 @@ var Semaphore = class {
   }
 };
 var DEFAULT_MAX_BODY_BYTES = 5 * 1024 * 1024;
+var HELLO_SPEC = '{"clips":[{"track":"text","text":"Hello from elah","start":0,"duration":3,"fontSize":96}]}';
+function curlExample(origin) {
+  return `curl -X POST ${origin}/render -H 'content-type: application/json' -d '${HELLO_SPEC}' -o hello.mp4`;
+}
+function powershellExample(origin) {
+  return `Invoke-RestMethod -Uri "${origin}/render" -Method Post -ContentType "application/json" -Body '${HELLO_SPEC}' -OutFile hello.mp4`;
+}
+function welcomePage(origin, browserConnected) {
+  const escapedCurl = curlExample(origin).replace(/</g, "&lt;");
+  const escapedPowershell = powershellExample(origin).replace(/</g, "&lt;");
+  return `<!doctype html>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>elah serve</title>
+<style>
+  body { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+         max-width: 720px; margin: 3rem auto; padding: 0 1rem; line-height: 1.6;
+         background: #0d1117; color: #e6edf3; }
+  h1 { font-size: 1.3rem; } h1 span { color: #7ee787; }
+  code, pre { background: #161b22; border: 1px solid #30363d; border-radius: 6px; }
+  code { padding: 0.1em 0.4em; }
+  pre { padding: 0.8em 1em; overflow-x: auto; white-space: pre-wrap; word-break: break-all; }
+  table { border-collapse: collapse; } td { padding: 0.15em 1em 0.15em 0; vertical-align: top; }
+  a { color: #58a6ff; }
+  .muted { color: #8b949e; }
+</style>
+<h1>elah serve <span>&#9679; ${browserConnected ? "browser connected" : "browser disconnected"}</span></h1>
+<p>Headless render server for the <a href="https://www.elah.dev">elah</a> video engine.
+POST a build spec, get an MP4 back.</p>
+<table>
+  <tr><td><code>GET /healthz</code></td><td class="muted">status + browser state</td></tr>
+  <tr><td><code>POST /render</code></td><td class="muted">build spec JSON in, <code>video/mp4</code> out</td></tr>
+</table>
+<p>Render your first video (no media files needed):</p>
+<pre>${escapedCurl}</pre>
+<p class="muted">On Windows PowerShell, <code>curl</code> is aliased to Invoke-WebRequest and won't accept <code>-H</code>/<code>-d</code> the curl way &mdash; use this instead:</p>
+<pre>${escapedPowershell}</pre>
+<p class="muted">Spec schema: assets map + clips array &mdash; see the
+<a href="https://github.com/elahlabs/elah/tree/main/packages/cli#readme">@elah/cli README</a>.</p>
+`;
+}
 function createServeHandler(deps) {
   return (req, res) => {
     void handle(req, res, deps).catch((err) => {
@@ -39406,6 +39447,17 @@ function createServeHandler(deps) {
 }
 async function handle(req, res, deps) {
   const url2 = new URL(req.url ?? "/", "http://localhost");
+  if (url2.pathname === "/") {
+    if (req.method !== "GET") {
+      writeJson(res, 405, { error: "method not allowed" });
+      return;
+    }
+    const origin = `http://${req.headers.host ?? "localhost"}`;
+    const html = welcomePage(origin, deps.browserConnected());
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8", "content-length": Buffer.byteLength(html) });
+    res.end(html);
+    return;
+  }
   if (url2.pathname === "/healthz") {
     if (req.method !== "GET") {
       writeJson(res, 405, { error: "method not allowed" });

package/dist/types/lib/serve.d.ts

@@ -17,6 +17,18 @@ export interface ServeHandlerDeps {
     maxBodyBytes: number;
     log(line: string): void;
 }
+/**
+ * Text-only spec (no media assets) so the copy-paste example renders on a
+ * machine with nothing but the server running. fps/stage fall back to spec
+ * defaults (30, 1920x1080).
+ */
+export declare const HELLO_SPEC = "{\"clips\":[{\"track\":\"text\",\"text\":\"Hello from elah\",\"start\":0,\"duration\":3,\"fontSize\":96}]}";
+export declare function curlExample(origin: string): string;
+/**
+ * PowerShell aliases `curl` to Invoke-WebRequest, which doesn't accept -H/-d
+ * the curl way. Point Windows users at curl.exe (or Invoke-RestMethod).
+ */
+export declare function powershellExample(origin: string): string;
 export declare function createServeHandler(deps: ServeHandlerDeps): (req: IncomingMessage, res: ServerResponse) => void;
 export interface ServeOptions {
     host: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elah/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Headless command-line runtime for the Elah video engine — split, trim, and export projects using @elah/core",
   "type": "module",
   "bin": {