@elah/cli 0.1.0

package/dist/types/bin.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/commands/build.d.ts

@@ -0,0 +1,14 @@
+export interface BuildArgs {
+    spec: string;
+    out?: string;
+    export?: string;
+    codec?: string;
+    height?: string;
+    videoBitrate?: string;
+    audioBitrate?: string;
+    browser?: string;
+    headed: boolean;
+    timeoutSec?: string;
+    verbose: boolean;
+}
+export declare function runBuild(args: BuildArgs): Promise<void>;

package/dist/types/commands/export.d.ts

@@ -0,0 +1,15 @@
+import type { Project } from '@elah/core';
+export interface ExportArgs {
+    project: string;
+    out: string;
+    codec?: string;
+    height?: string;
+    videoBitrate?: string;
+    audioBitrate?: string;
+    browser?: string;
+    headed: boolean;
+    timeoutSec?: string;
+    verbose: boolean;
+}
+export declare function runExport(args: ExportArgs): Promise<void>;
+export declare function runExportForProject(project: Project, projectDir: string, args: Omit<ExportArgs, 'project'>): Promise<void>;

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

@@ -0,0 +1,14 @@
+export interface ServeArgs {
+    port?: string;
+    host?: string;
+    concurrency?: string;
+    mediaRoot?: string;
+    codec?: string;
+    height?: string;
+    videoBitrate?: string;
+    audioBitrate?: string;
+    browser?: string;
+    timeoutSec?: string;
+    verbose: boolean;
+}
+export declare function runServe(args: ServeArgs): Promise<void>;

package/dist/types/commands/split.d.ts

@@ -0,0 +1,10 @@
+import { type Project } from '@elah/core';
+/** The engine silently ignores edits on locked tracks — fail with the real reason instead. */
+export declare function requireUnlockedTrack(project: Project, trackId: string): void;
+export interface SplitArgs {
+    project: string;
+    clip: string;
+    at: string;
+    out?: string;
+}
+export declare function runSplit(args: SplitArgs): void;

package/dist/types/commands/trim.d.ts

@@ -0,0 +1,8 @@
+export interface TrimArgs {
+    project: string;
+    clip: string;
+    start?: string;
+    duration?: string;
+    out?: string;
+}
+export declare function runTrim(args: TrimArgs): void;

package/dist/types/index.d.ts

@@ -0,0 +1,15 @@
+export { buildProject as build } from './lib/build-project';
+export type { BuildProjectArgs, BuildProjectResult, BuildSummary } from './lib/build-project';
+export { exportProject } from './lib/export-project';
+export type { ExportProjectArgs, ExportProjectResult } from './lib/export-project';
+export { createRenderSession, CODECS } from './lib/render-session';
+export type { RenderSession, RenderSessionArgs, RenderJobOptions, RenderCallbacks, VideoCodec, } from './lib/render-session';
+export { CliError, CliError as ElahError } from './lib/errors';
+export { validateSpec, specToProject } from './lib/spec';
+export type { BuildSpec, SpecClip, SpecMediaClip, SpecTextClip, ProbedAsset } from './lib/spec';
+export { probeMedia } from './lib/probe';
+export type { MediaInfo } from './lib/probe';
+export type { ProgressPayload } from './lib/server';
+export { startServe, Semaphore } from './lib/serve';
+export type { ServeOptions, ServeHandle } from './lib/serve';
+export type { Project } from '@elah/core';

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

@@ -0,0 +1,15 @@
+import type { Browser } from 'playwright-core';
+export interface LaunchArgs {
+    /** Explicit executable path (--browser); wins over discovery. */
+    browserPath?: string;
+    headed?: boolean;
+}
+/**
+ * Launch a Chromium-based browser for the export harness. Discovery order:
+ * --browser flag → ELAH_BROWSER env → system Chrome → Chrome Beta → Edge.
+ * Branded Chrome is preferred because Playwright's bundled Chromium lacks
+ * the proprietary codecs (H.264/AAC) that the default export uses.
+ *
+ * playwright-core is imported lazily so split/trim never load it.
+ */
+export declare function launchBrowser(args: LaunchArgs): Promise<Browser>;

package/dist/types/lib/build-project.d.ts

@@ -0,0 +1,18 @@
+import type { Project } from '@elah/core';
+export interface BuildProjectArgs {
+    /** Raw parsed spec JSON — validated internally with path-addressed errors. */
+    spec: unknown;
+    /** Absolute dir that relative asset paths in the spec resolve against. */
+    baseDir: string;
+}
+export interface BuildSummary {
+    tracks: number;
+    clips: number;
+    totalFrames: number;
+    fps: number;
+}
+export interface BuildProjectResult {
+    project: Project;
+    summary: BuildSummary;
+}
+export declare function buildProject(args: BuildProjectArgs): Promise<BuildProjectResult>;

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

@@ -0,0 +1,9 @@
+/**
+ * Exit-code contract: 0 success, 1 validation/runtime failure, 2 usage error.
+ * Thrown CliErrors are caught once in bin.ts; everything else is a bug.
+ */
+export declare class CliError extends Error {
+    readonly exitCode: 1 | 2;
+    constructor(message: string, exitCode?: 1 | 2);
+}
+export declare function usageError(message: string): CliError;

package/dist/types/lib/export-project.d.ts

@@ -0,0 +1,22 @@
+import type { Project } from '@elah/core';
+import { type RenderCallbacks, type VideoCodec } from './render-session';
+export interface ExportProjectArgs {
+    project: Project;
+    /** Base directory for relative clip srcs. Default process.cwd(). */
+    projectDir?: string;
+    /** When set, the MP4 is also written to disk (absolute or cwd-relative). */
+    outPath?: string;
+    videoCodec?: VideoCodec;
+    outputHeight?: number;
+    videoBitrate?: number;
+    audioBitrate?: number;
+    browserPath?: string;
+    headed?: boolean;
+    timeoutMs?: number;
+}
+export interface ExportProjectResult {
+    bytes: Buffer;
+    sizeBytes: number;
+    outPath?: string;
+}
+export declare function exportProject(args: ExportProjectArgs, callbacks?: RenderCallbacks): Promise<ExportProjectResult>;

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

@@ -0,0 +1 @@
+export declare function parsePositiveInt(value: string, flag: string): number;

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

@@ -0,0 +1,12 @@
+/**
+ * The in-browser side of `elah export`, embedded as strings so the CLI ships
+ * a single bundled file. The page deep-imports core's real exportVideo from
+ * the harness server (bypassing core's index.js and everything browser-page
+ * irrelevant) and streams progress + the MP4 bytes back over HTTP.
+ */
+export declare const HARNESS_HTML = "<!doctype html>\n<html>\n  <head><meta charset=\"utf-8\"><title>elah export harness</title></head>\n  <body><script type=\"module\" src=\"/harness.js\"></script></body>\n</html>\n";
+/**
+ * The callback routes carry a per-run random token so no other local process
+ * can post a forged /result into the output file or read the media routes.
+ */
+export declare function harnessJs(token: string): string;

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

@@ -0,0 +1,11 @@
+export interface MediaInfo {
+    durationSec: number;
+    width?: number;
+    height?: number;
+}
+/**
+ * Probe a media file's duration (and dimensions for video) with mediabunny —
+ * already a core dependency, pure-JS demuxing, no WebCodecs needed in Node.
+ * Remote URLs use ranged reads (UrlSource) instead of buffering the file.
+ */
+export declare function probeMedia(source: string): Promise<MediaInfo>;

package/dist/types/lib/project-io.d.ts

@@ -0,0 +1,19 @@
+import type { Project, Clip } from '@elah/core';
+/** True for http(s) sources, which are proxied rather than read from disk. */
+export declare function isRemoteUrl(src: string): boolean;
+export interface LoadedProject {
+    project: Project;
+    /** Directory of the project JSON — relative clip srcs resolve against it. */
+    dir: string;
+}
+/** Read + parse + structurally validate a Project JSON file. */
+export declare function readProject(path: string): LoadedProject;
+/** Write project JSON to a file, or stdout when no path is given. */
+export declare function writeProject(project: Project, outPath?: string): void;
+/** Locate a clip by id across all tracks. Clip ids are unique by construction. */
+export declare function findClipTrack(project: Project, clipId: string): {
+    clip: Clip;
+    trackId: string;
+};
+/** Resolve a clip src against the project directory. Remote URLs pass through. */
+export declare function resolveMediaSource(src: string, projectDir: string): string;

package/dist/types/lib/render-session.d.ts

@@ -0,0 +1,40 @@
+import type { Project } from '@elah/core';
+import { type ProgressPayload } from './server';
+export type VideoCodec = 'avc' | 'vp9' | 'vp8';
+export declare const CODECS: readonly VideoCodec[];
+export interface RenderSessionArgs {
+    browserPath?: string;
+    headed?: boolean;
+}
+export interface RenderJobOptions {
+    videoCodec?: VideoCodec;
+    outputHeight?: number;
+    videoBitrate?: number;
+    audioBitrate?: number;
+    /** Default 600_000 (10 minutes). */
+    timeoutMs?: number;
+}
+export interface RenderCallbacks {
+    onProgress?: (p: ProgressPayload) => void;
+    /** Audio-clip-skipped warnings and in-page errors. */
+    onWarning?: (message: string) => void;
+    /** Verbose [server]/[browser] log lines. */
+    onLog?: (line: string) => void;
+}
+export interface RenderSession {
+    /** Launch the browser now (idempotent). */
+    warmup(): Promise<void>;
+    browserConnected(): boolean;
+    render(project: Project, projectDir: string, options?: RenderJobOptions, callbacks?: RenderCallbacks): Promise<Buffer>;
+    close(): Promise<void>;
+}
+export declare function createRenderSession(args?: RenderSessionArgs): RenderSession;
+/**
+ * Clone the project with every media clip src rewritten to a token-guarded
+ * local-server route; the map feeds the harness server. Missing local files
+ * fail here, before a browser ever launches.
+ */
+export declare function prepareMedia(project: Project, projectDir: string, token: string): {
+    exportProject: Project;
+    media: Map<string, string>;
+};

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

@@ -0,0 +1,39 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import type { Project } from '@elah/core';
+import type { RenderJobOptions, RenderSession } from './render-session';
+export declare class Semaphore {
+    readonly max: number;
+    private activeCount;
+    constructor(max: number);
+    get active(): number;
+    tryAcquire(): boolean;
+    release(): void;
+}
+export interface ServeHandlerDeps {
+    buildSpec(spec: unknown): Promise<Project>;
+    renderProject(project: Project, jobId: string): Promise<Buffer>;
+    browserConnected(): boolean;
+    semaphore: Semaphore;
+    maxBodyBytes: number;
+    log(line: string): void;
+}
+export declare function createServeHandler(deps: ServeHandlerDeps): (req: IncomingMessage, res: ServerResponse) => void;
+export interface ServeOptions {
+    host: string;
+    /** 0 = ephemeral port (tests). */
+    port: number;
+    concurrency: number;
+    /** Absolute dir that relative spec asset paths resolve against. */
+    mediaRoot: string;
+    /** Server-level codec/height/bitrate/timeout applied to every render. */
+    render: RenderJobOptions;
+    session: RenderSession;
+    maxBodyBytes?: number;
+    log?: (line: string) => void;
+    verbose?: boolean;
+}
+export interface ServeHandle {
+    port: number;
+    close(): Promise<void>;
+}
+export declare function startServe(options: ServeOptions): Promise<ServeHandle>;

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

@@ -0,0 +1,48 @@
+export interface ProgressPayload {
+    frame: number;
+    totalFrames: number;
+}
+export interface HarnessServerArgs {
+    /** Per-run random secret protecting the callback and media routes. */
+    token: string;
+    /** Route path (e.g. '/media/<token>/0') → absolute file path or http(s) URL to proxy. */
+    media: Map<string, string>;
+    onProgress?: (p: ProgressPayload) => void;
+    onAudioIssue?: (message: string, src?: string) => void;
+    log?: (line: string) => void;
+}
+export interface HarnessServer {
+    origin: string;
+    /** Resolves with the exported MP4 bytes; rejects when the page reports an error. */
+    result: Promise<Buffer>;
+    /** Reject the result from the outside (tab crash, browser disconnect). */
+    fail(err: Error): void;
+    close(): Promise<void>;
+}
+interface VendorEntry {
+    root: string;
+    /** Path of the package's browser entry, relative to root (posix). */
+    entry: string;
+    /**
+     * Package-relative paths the package.json `browser` field maps to `false`
+     * (Node-only modules). Bundlers replace these with empty modules; serving
+     * raw files over HTTP must do the same or the browser hits `node:` imports.
+     */
+    browserFalse: Set<string>;
+}
+/**
+ * Resolve a bare specifier to its entry file. Uses import.meta.resolve when
+ * available (bundled Node runtime); falls back to createRequire under tooling
+ * that doesn't expose it (vitest's SSR transform).
+ */
+export declare function resolveModuleFile(spec: string): string;
+/** Replace bare vendor specifiers in served core modules with /vendor/ URLs. */
+export declare function rewriteSpecifiers(source: string, vendors: Map<string, VendorEntry>): string;
+/**
+ * Resolve a /core/* request against core's dist, tolerating the module-URL
+ * quirks of tsc's bundler-resolution output: extensionless relative imports
+ * and the literal `./ExportWorker.ts` worker URL that ships in dist.
+ */
+export declare function resolveDistFile(distRoot: string, urlPath: string): string | undefined;
+export declare function startHarnessServer(args: HarnessServerArgs): Promise<HarnessServer>;
+export {};

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

@@ -0,0 +1,63 @@
+import { type Project } from '@elah/core';
+/**
+ * The AI-friendly build spec: times in seconds, assets by name, no engine
+ * bookkeeping. `elah build` turns this into a full Project via TimelineEngine —
+ * overlaps and track caps are enforced by core; source bounds are enforced
+ * here in frame space (the engine does not validate source windows on update).
+ */
+export interface BuildSpec {
+    /** Frames per second — integer. Default 30. */
+    fps?: number;
+    /** Output canvas in pixels. Default 1920x1080. */
+    stage?: {
+        width: number;
+        height: number;
+    };
+    /** Asset name → file path (relative to the spec file) or http(s) URL. */
+    assets?: Record<string, string>;
+    clips: SpecClip[];
+}
+export interface SpecClipBase {
+    track: 'video' | 'audio' | 'text' | 'image';
+    /** Timeline position in seconds. */
+    start: number;
+    /** Length in seconds. Optional for video/audio (defaults to the rest of the media). */
+    duration?: number;
+    /** Normalized 0..1 position of the clip center on the stage. */
+    x?: number;
+    y?: number;
+    scale?: number;
+    opacity?: number;
+}
+export interface SpecMediaClip extends SpecClipBase {
+    track: 'video' | 'audio' | 'image';
+    /** Name from the spec's assets map. */
+    asset: string;
+    /** Seconds into the source media to start from (video/audio). */
+    sourceStart?: number;
+    volume?: number;
+}
+export interface SpecTextClip extends SpecClipBase {
+    track: 'text';
+    text: string;
+    duration: number;
+    fontSize?: number;
+    color?: string;
+    fontFamily?: string;
+    fontWeight?: 'normal' | 'bold';
+    align?: 'left' | 'center' | 'right';
+}
+export type SpecClip = SpecMediaClip | SpecTextClip;
+export interface ProbedAsset {
+    /** Resolved absolute path or URL, used as the clip src. */
+    src: string;
+    /** Media duration in seconds (video/audio only; images pass undefined). */
+    durationSec?: number;
+}
+/**
+ * Convert a validated spec into a Project through a real TimelineEngine.
+ * `assets` maps asset names to their resolved+probed sources.
+ */
+export declare function specToProject(spec: BuildSpec, assets: Map<string, ProbedAsset>): Project;
+/** Structural validation with clear, path-addressed messages. */
+export declare function validateSpec(value: unknown): BuildSpec;

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

@@ -0,0 +1,6 @@
+/**
+ * Parse a frame position: either a plain integer frame count or a timecode.
+ * Accepted timecode forms (matching core's HH:MM:SS:FF formatter):
+ *   SS:FF · MM:SS:FF · HH:MM:SS:FF
+ */
+export declare function parseFramePosition(value: string, fps: number): number;

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@elah/cli",
+  "version": "0.1.0",
+  "description": "Headless command-line runtime for the Elah video engine — split, trim, and export projects using @elah/core",
+  "type": "module",
+  "bin": {
+    "elah": "./dist/bin.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc --noEmit && tsc -p tsconfig.build.json && node scripts/build.mjs"
+  },
+  "keywords": [
+    "video-editor",
+    "cli",
+    "headless",
+    "timeline",
+    "video-engine",
+    "export",
+    "mp4",
+    "automation",
+    "typescript"
+  ],
+  "homepage": "https://www.elah.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elahlabs/elah.git"
+  },
+  "bugs": {
+    "url": "https://github.com/elahlabs/elah/issues"
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@elah/core": "^0.3.0",
+    "mediabunny": "^1.45.3",
+    "playwright-core": "^1.50.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.6"
+  }
+}