@clipkit/cli 1.0.0

package/dist/commands/still.js

@@ -0,0 +1,58 @@
+// `clipkit still <file> -o poster.png` — render ONE frame of a Source to a PNG,
+// locally (headless Chrome via @clipkit/renderer). A fast visual sanity
+// check / thumbnail without a full encode. Same engine + setup as
+// `render --local` (the package is an optional peer; needs Google Chrome).
+import { writeFile } from 'node:fs/promises';
+import { validate } from '@clipkit/protocol';
+import { loadSource } from '../load-source.js';
+import { printValidationErrors, fmtBytes } from '../util.js';
+export function stillCommand(program) {
+    program
+        .command('still <file>')
+        .description('Render one frame of a Source to a PNG (local headless Chrome)')
+        .option('-o, --out <path>', 'output PNG path', 'still.png')
+        .option('-t, --time <seconds>', 'composition time to capture', '0')
+        .option('-b, --backend <backend>', 'auto | webgpu | webgl2', 'auto')
+        .action(async (file, opts) => {
+        const { path, source } = await loadSource(file);
+        const result = validate(source);
+        if (!result.valid) {
+            printValidationErrors(path, result.errors);
+            process.exit(1);
+        }
+        const time = Number(opts.time);
+        if (!Number.isFinite(time) || time < 0) {
+            process.stderr.write(`✗ invalid --time "${opts.time}".\n`);
+            process.exit(1);
+        }
+        if (!isBackend(opts.backend)) {
+            process.stderr.write(`✗ invalid --backend "${opts.backend}" (expected auto | webgpu | webgl2).\n`);
+            process.exit(1);
+        }
+        let mod;
+        try {
+            mod = (await import('@clipkit/renderer'));
+        }
+        catch {
+            process.stderr.write('Stills need the @clipkit/renderer engine (and Google Chrome).\n\n' +
+                '  npm i -g @clipkit/renderer playwright\n');
+            process.exit(1);
+        }
+        process.stderr.write(`Capturing frame at ${time}s…\n`);
+        let png;
+        try {
+            png = await mod.renderStill({ source: result.data, time, backend: opts.backend });
+        }
+        catch (e) {
+            process.stderr.write(`✗ Still failed: ${e instanceof Error ? e.message : String(e)}\n` +
+                '  (Local stills use your installed Google Chrome.)\n');
+            process.exit(1);
+        }
+        await writeFile(opts.out, png);
+        process.stdout.write(`✓ Wrote ${opts.out} (${fmtBytes(png.length)})\n`);
+    });
+}
+function isBackend(v) {
+    return v === 'auto' || v === 'webgpu' || v === 'webgl2';
+}
+//# sourceMappingURL=still.js.map

package/dist/commands/still.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"still.js","sourceRoot":"","sources":["../../src/commands/still.ts"],"names":[],"mappings":"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"}

package/dist/commands/transcribe.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function transcribeCommand(program: Command): void;
+//# sourceMappingURL=transcribe.d.ts.map

package/dist/commands/transcribe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcribe.d.ts","sourceRoot":"","sources":["../../src/commands/transcribe.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAapC,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqCxD"}

package/dist/commands/transcribe.js

@@ -0,0 +1,52 @@
+// `clipkit transcribe <file>` — transcribe an audio/video file into
+// word-timestamped captions (the protocol's `caption` element `words[]`).
+//
+// Runs Whisper locally via @clipkit/speech-to-text (no API, no key). Prints the
+// words[] JSON by default, or a full caption element with --element. Progress
+// goes to stderr so stdout stays clean, machine-readable JSON — the agent path.
+//
+// The model runs in an isolated worker (transcribeFile), so onnxruntime-node's
+// harmless teardown abort never affects this process — clean exit 0 on success.
+import { writeFile } from 'node:fs/promises';
+import { toCaptionWords } from '@clipkit/speech-to-text';
+import { transcribeFile } from '@clipkit/speech-to-text/node';
+export function transcribeCommand(program) {
+    program
+        .command('transcribe <file>')
+        .description('Transcribe an audio/video file into caption words (local Whisper; needs ffmpeg)')
+        .option('-m, --model <id>', 'Whisper model id (Hugging Face)', 'Xenova/whisper-base')
+        .option('-l, --language <code>', 'force a language (e.g. en); default auto-detect')
+        .option('-o, --out <file>', 'write JSON here (default: stdout)')
+        .option('-e, --element', 'emit a full caption element instead of just words[]')
+        .option('-t, --layer <n>', 'layer for --element (lower = nearer front)', '3')
+        .action(async (file, opts) => {
+        const log = (s) => void process.stderr.write(s);
+        log(`transcribing ${file} (${opts.model})…\n`);
+        const seen = new Set();
+        const result = await transcribeFile(file, {
+            model: opts.model,
+            language: opts.language,
+            onLog: (line) => {
+                // The worker logs "  ↓ <file>" lines as the model downloads.
+                if (line.includes('↓') && !seen.has(line)) {
+                    seen.add(line);
+                    log(line);
+                }
+            },
+        });
+        const words = toCaptionWords(result);
+        log(`  ${words.length} words, ${result.duration.toFixed(1)}s\n`);
+        const payload = opts.element
+            ? { type: 'caption', time: 0, layer: Number(opts.layer) || 3, words }
+            : words;
+        const json = JSON.stringify(payload, null, 2);
+        if (opts.out) {
+            await writeFile(opts.out, json + '\n');
+            log(`wrote ${opts.out}\n`);
+        }
+        else {
+            process.stdout.write(json + '\n');
+        }
+    });
+}
+//# sourceMappingURL=transcribe.js.map

package/dist/commands/transcribe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcribe.js","sourceRoot":"","sources":["../../src/commands/transcribe.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,0EAA0E;AAC1E,EAAE;AACF,gFAAgF;AAChF,8EAA8E;AAC9E,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAGhF,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAU9D,MAAM,UAAU,iBAAiB,CAAC,OAAgB;IAChD,OAAO;SACJ,OAAO,CAAC,mBAAmB,CAAC;SAC5B,WAAW,CAAC,iFAAiF,CAAC;SAC9F,MAAM,CAAC,kBAAkB,EAAE,iCAAiC,EAAE,qBAAqB,CAAC;SACpF,MAAM,CAAC,uBAAuB,EAAE,iDAAiD,CAAC;SAClF,MAAM,CAAC,kBAAkB,EAAE,mCAAmC,CAAC;SAC/D,MAAM,CAAC,eAAe,EAAE,qDAAqD,CAAC;SAC9E,MAAM,CAAC,iBAAiB,EAAE,4CAA4C,EAAE,GAAG,CAAC;SAC5E,MAAM,CAAC,KAAK,EAAE,IAAY,EAAE,IAAU,EAAE,EAAE;QACzC,MAAM,GAAG,GAAG,CAAC,CAAS,EAAQ,EAAE,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC9D,GAAG,CAAC,gBAAgB,IAAI,KAAK,IAAI,CAAC,KAAK,MAAM,CAAC,CAAC;QAE/C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE;YACxC,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE;gBACd,6DAA6D;gBAC7D,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;oBAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;oBAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBAAC,CAAC;YAC3E,CAAC;SACF,CAAC,CAAC;QAEH,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;QACrC,GAAG,CAAC,KAAK,KAAK,CAAC,MAAM,WAAW,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAEjE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO;YAC1B,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE;YACrE,CAAC,CAAC,KAAK,CAAC;QACV,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAC9C,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,MAAM,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,GAAG,IAAI,CAAC,CAAC;YACvC,GAAG,CAAC,SAAS,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QAC7B,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;QACpC,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/commands/validate.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function validateCommand(program: Command): void;
+//# sourceMappingURL=validate.d.ts.map

package/dist/commands/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuCtD"}

package/dist/commands/validate.js

@@ -0,0 +1,46 @@
+// `clipkit validate <file>` — check a Source against the Clipkit Protocol.
+//
+// Loads the file (JSON or TS), runs @clipkit/protocol's validator, and reports
+// any errors with their JSON path. Exits 0 on success, 1 on failure. With
+// `--explain` it also surfaces protocol-aware warnings on success (things that
+// validate but the runtime will silently drop/clip) and adds guidance on
+// failure.
+import { validate, CLIPKIT_PROTOCOL_VERSION } from '@clipkit/protocol';
+import { lintSource } from '@clipkit/lint';
+import { loadSource } from '../load-source.js';
+import { printValidationErrors } from '../util.js';
+export function validateCommand(program) {
+    program
+        .command('validate <file>')
+        .description('Validate a Clipkit Source against the protocol')
+        .option('--explain', 'add protocol-aware warnings (success) and guidance (failure)')
+        .action(async (file, opts) => {
+        const { path, source } = await loadSource(file);
+        const result = validate(source);
+        if (result.valid) {
+            process.stdout.write(`✓ ${path} is a valid Clipkit Protocol v${CLIPKIT_PROTOCOL_VERSION} document.\n`);
+            if (opts.explain) {
+                const warnings = lintSource(result.data);
+                if (warnings.length === 0) {
+                    process.stdout.write("✓ No warnings — nothing the runtime will silently drop or clip.\n");
+                }
+                else {
+                    process.stdout.write(`\n⚠ ${warnings.length} warning${warnings.length === 1 ? '' : 's'} (valid, but worth a look):\n`);
+                    for (const w of warnings)
+                        process.stdout.write(`  - ${w.where}: ${w.message}\n`);
+                }
+            }
+            return;
+        }
+        printValidationErrors(path, result.errors);
+        if (opts.explain) {
+            process.stderr.write('\nHints:\n' +
+                '  - An error path like `elements.2.type` points at the 3rd element\'s `type` field.\n' +
+                '  - "Invalid discriminator value" means a bad `type` — allowed: video, image, text,\n' +
+                '    shape, audio, caption, group, particles.\n' +
+                '  - Read the field rules:  clipkit docs protocol\n');
+        }
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=validate.js.map

package/dist/commands/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,EAAE;AACF,+EAA+E;AAC/E,0EAA0E;AAC1E,+EAA+E;AAC/E,yEAAyE;AACzE,WAAW;AAGX,OAAO,EAAE,QAAQ,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAEvE,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO;SACJ,OAAO,CAAC,iBAAiB,CAAC;SAC1B,WAAW,CAAC,gDAAgD,CAAC;SAC7D,MAAM,CAAC,WAAW,EAAE,8DAA8D,CAAC;SACnF,MAAM,CAAC,KAAK,EAAE,IAAY,EAAE,IAA2B,EAAE,EAAE;QAC1D,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;QAChD,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;QAEhC,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,KAAK,IAAI,iCAAiC,wBAAwB,cAAc,CACjF,CAAC;YACF,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjB,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,IAAc,CAAC,CAAC;gBACnD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mEAAmE,CAAC,CAAC;gBAC5F,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,OAAO,QAAQ,CAAC,MAAM,WAAW,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,+BAA+B,CACjG,CAAC;oBACF,KAAK,MAAM,CAAC,IAAI,QAAQ;wBAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC;gBACnF,CAAC;YACH,CAAC;YACD,OAAO;QACT,CAAC;QAED,qBAAqB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAC3C,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,YAAY;gBACV,uFAAuF;gBACvF,uFAAuF;gBACvF,gDAAgD;gBAChD,oDAAoD,CACvD,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+export declare const DEFAULT_API_URL = "https://clipkit.dev";
+export interface Config {
+    apiKey?: string;
+    /** Non-default API host, persisted only when the user overrides it. */
+    apiUrl?: string;
+}
+export declare function configDir(): string;
+export declare function configPath(): string;
+export declare function readConfig(): Promise<Config>;
+export declare function writeConfig(config: Config): Promise<void>;
+export declare function clearConfig(): Promise<void>;
+export declare function resolveApiKey(flag?: string): Promise<string | undefined>;
+export declare function resolveApiUrl(flag?: string): Promise<string>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,eAAe,wBAAwB,CAAC;AAErD,MAAM,WAAW,MAAM;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,SAAS,IAAI,MAAM,CAGlC;AAED,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAsB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CASlD;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM/D;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAEjD;AAID,wBAAsB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAK9E;AAED,wBAAsB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOlE"}

package/dist/config.js

@@ -0,0 +1,58 @@
+// Persistent CLI config — the API key (and optional API host) used by the
+// cloud commands (`render --cloud`, and team-owned `share`). Stored at
+// $XDG_CONFIG_HOME/clipkit/config.json (falls back to ~/.config/clipkit),
+// chmod 0600 so the key isn't world-readable.
+//
+// Resolution order for both key and host: explicit flag → environment
+// variable → config file → built-in default. The env vars (CLIPKIT_API_KEY /
+// CLIPKIT_API_URL) are the same ones the MCP server reads, so a machine wired
+// up for one is wired up for both.
+import { readFile, writeFile, mkdir, rm, chmod } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const DEFAULT_API_URL = 'https://clipkit.dev';
+export function configDir() {
+    const base = process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), '.config');
+    return join(base, 'clipkit');
+}
+export function configPath() {
+    return join(configDir(), 'config.json');
+}
+export async function readConfig() {
+    try {
+        const raw = await readFile(configPath(), 'utf8');
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        // Missing or unreadable file → empty config (the common first-run case).
+        return {};
+    }
+}
+export async function writeConfig(config) {
+    await mkdir(configDir(), { recursive: true });
+    const path = configPath();
+    await writeFile(path, JSON.stringify(config, null, 2) + '\n', 'utf8');
+    // Best-effort lock-down; filesystems that ignore mode bits (Windows) just won't.
+    await chmod(path, 0o600).catch(() => { });
+}
+export async function clearConfig() {
+    await rm(configPath(), { force: true });
+}
+// ── Resolution: flag → env → config file → default ──────────────────────────
+export async function resolveApiKey(flag) {
+    if (flag?.trim())
+        return flag.trim();
+    const env = process.env.CLIPKIT_API_KEY?.trim();
+    if (env)
+        return env;
+    return (await readConfig()).apiKey;
+}
+export async function resolveApiUrl(flag) {
+    const pick = flag?.trim() ||
+        process.env.CLIPKIT_API_URL?.trim() ||
+        (await readConfig()).apiUrl ||
+        DEFAULT_API_URL;
+    return pick.replace(/\/+$/, '');
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,uEAAuE;AACvE,0EAA0E;AAC1E,8CAA8C;AAC9C,EAAE;AACF,sEAAsE;AACtE,6EAA6E;AAC7E,8EAA8E;AAC9E,mCAAmC;AAEnC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,CAAC,MAAM,eAAe,GAAG,qBAAqB,CAAC;AAQrD,MAAM,UAAU,SAAS;IACvB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IAC/E,OAAO,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,IAAI,CAAC,SAAS,EAAE,EAAE,aAAa,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,UAAU,EAAE,EAAE,MAAM,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;QAC1C,OAAO,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAiB,CAAC,CAAC,CAAC,EAAE,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;QACzE,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAAc;IAC9C,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;IAC1B,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;IACtE,iFAAiF;IACjF,MAAM,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,MAAM,EAAE,CAAC,UAAU,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED,+EAA+E;AAE/E,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAa;IAC/C,IAAI,IAAI,EAAE,IAAI,EAAE;QAAE,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;IACrC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC;IAChD,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC;IACpB,OAAO,CAAC,MAAM,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC;AACrC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAa;IAC/C,MAAM,IAAI,GACR,IAAI,EAAE,IAAI,EAAE;QACZ,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE;QACnC,CAAC,MAAM,UAAU,EAAE,CAAC,CAAC,MAAM;QAC3B,eAAe,CAAC;IAClB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAClC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// @clipkit/cli — local-first authoring + validation + rendering surface.
+//
+// Subcommands, each in its own file under ./commands:
+//   clipkit init [name]            — scaffold a project
+//   clipkit new <template>         — scaffold a Source from the pattern library
+//   clipkit validate <file>        — schema-check a Source (--explain for hints)
+//   clipkit explain <file>         — plain-language read-back + warnings
+//   clipkit preview <file>         — open a Source in the web editor (share link)
+//   clipkit render <file> --out X  — render to a video file (local or --cloud)
+//   clipkit still <file> --out X   — render one frame to a PNG
+//   clipkit transcribe <file>      — audio/video → caption words (local Whisper)
+//   clipkit docs [topic]           — print the authoring docs / protocol spec
+//   clipkit schema                 — print the protocol JSON Schema
+//   clipkit mcp                    — run the MCP server (wire up an AI agent)
+//   clipkit login / logout         — store an API key for the cloud commands
+import { Command } from 'commander';
+import { CLIPKIT_PROTOCOL_VERSION } from '@clipkit/protocol';
+import { initCommand } from './commands/init.js';
+import { newCommand } from './commands/new.js';
+import { validateCommand } from './commands/validate.js';
+import { explainCommand } from './commands/explain.js';
+import { previewCommand } from './commands/preview.js';
+import { renderCommand } from './commands/render.js';
+import { stillCommand } from './commands/still.js';
+import { transcribeCommand } from './commands/transcribe.js';
+import { docsCommand } from './commands/docs.js';
+import { schemaCommand } from './commands/schema.js';
+import { mcpCommand } from './commands/mcp.js';
+import { loginCommand } from './commands/login.js';
+const program = new Command();
+program
+    .name('clipkit')
+    .description(`The Clipkit CLI — author and render Clipkit Protocol videos locally.\n` +
+    `Implements Clipkit Protocol v${CLIPKIT_PROTOCOL_VERSION} (CKP/${CLIPKIT_PROTOCOL_VERSION}).`)
+    .version('0.0.0', '-v, --version', 'print the CLI version');
+initCommand(program);
+newCommand(program);
+validateCommand(program);
+explainCommand(program);
+previewCommand(program);
+renderCommand(program);
+stillCommand(program);
+transcribeCommand(program);
+docsCommand(program);
+schemaCommand(program);
+mcpCommand(program);
+loginCommand(program);
+program.parseAsync(process.argv).catch((err) => {
+    process.stderr.write(`\nclipkit: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,yEAAyE;AACzE,EAAE;AACF,sDAAsD;AACtD,wDAAwD;AACxD,gFAAgF;AAChF,iFAAiF;AACjF,yEAAyE;AACzE,kFAAkF;AAClF,+EAA+E;AAC/E,+DAA+D;AAC/D,iFAAiF;AACjF,8EAA8E;AAC9E,oEAAoE;AACpE,8EAA8E;AAC9E,6EAA6E;AAE7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,SAAS,CAAC;KACf,WAAW,CACV,wEAAwE;IACtE,gCAAgC,wBAAwB,SAAS,wBAAwB,IAAI,CAChG;KACA,OAAO,CAAC,OAAO,EAAE,eAAe,EAAE,uBAAuB,CAAC,CAAC;AAE9D,WAAW,CAAC,OAAO,CAAC,CAAC;AACrB,UAAU,CAAC,OAAO,CAAC,CAAC;AACpB,eAAe,CAAC,OAAO,CAAC,CAAC;AACzB,cAAc,CAAC,OAAO,CAAC,CAAC;AACxB,cAAc,CAAC,OAAO,CAAC,CAAC;AACxB,aAAa,CAAC,OAAO,CAAC,CAAC;AACvB,YAAY,CAAC,OAAO,CAAC,CAAC;AACtB,iBAAiB,CAAC,OAAO,CAAC,CAAC;AAC3B,WAAW,CAAC,OAAO,CAAC,CAAC;AACrB,aAAa,CAAC,OAAO,CAAC,CAAC;AACvB,UAAU,CAAC,OAAO,CAAC,CAAC;AACpB,YAAY,CAAC,OAAO,CAAC,CAAC;AAEtB,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IAC7C,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,cAAc,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CACnE,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/lint.d.ts

@@ -0,0 +1,8 @@
+import type { Source } from '@clipkit/protocol';
+export interface LintWarning {
+    /** Element id, or '(source)' for composition-level issues. */
+    where: string;
+    message: string;
+}
+export declare function lintSource(source: Source): LintWarning[];
+//# sourceMappingURL=lint.d.ts.map

package/dist/lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAWD,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CAmExD"}

package/dist/lint.js

@@ -0,0 +1,75 @@
+// Protocol-aware "soft" checks — things that pass schema validation but will
+// surprise you at render time. Shared by `clipkit explain` and
+// `clipkit validate --explain`.
+// The runtime text/caption renderer uses a fixed ASCII coverage-font atlas;
+// any non-ASCII glyph (emoji, accents, smart quotes, CJK) is silently dropped.
+const NON_ASCII = /[^\x00-\x7F]/;
+function firstNonAscii(s) {
+    const m = NON_ASCII.exec(s);
+    return m ? m[0] : null;
+}
+export function lintSource(source) {
+    const warnings = [];
+    const comp = source;
+    const compDuration = typeof comp.duration === 'number' ? comp.duration : undefined;
+    if (compDuration === undefined) {
+        warnings.push({
+            where: '(source)',
+            message: "No top-level `duration` — the runtime can't tell how long the composition is. Set `duration` (seconds).",
+        });
+    }
+    const elements = Array.isArray(comp.elements) ? comp.elements : [];
+    for (const el of elements) {
+        const e = el;
+        const id = typeof e.id === 'string' ? e.id : `(${String(e.type ?? 'element')})`;
+        const time = typeof e.time === 'number' ? e.time : 0;
+        const dur = typeof e.duration === 'number' ? e.duration : undefined;
+        // Runs past the composition's end → it'll be cut off.
+        if (compDuration !== undefined && dur !== undefined && time + dur > compDuration + 1e-6) {
+            warnings.push({
+                where: id,
+                message: `Ends at ${(time + dur).toFixed(2)}s, past the composition's ${compDuration}s — it'll be cut off.`,
+            });
+        }
+        // Non-ASCII in text-bearing fields (dropped by the ASCII atlas).
+        if (e.type === 'text') {
+            const texts = [];
+            if (typeof e.text === 'string')
+                texts.push(e.text);
+            if (Array.isArray(e.spans)) {
+                for (const sp of e.spans) {
+                    const t = sp?.text;
+                    if (typeof t === 'string')
+                        texts.push(t);
+                }
+            }
+            for (const t of texts) {
+                const ch = firstNonAscii(t);
+                if (ch) {
+                    warnings.push({
+                        where: id,
+                        message: `Text has a non-ASCII character ("${ch}") — the runtime's ASCII font atlas drops these (emoji, accents, smart quotes, CJK). Use plain ASCII.`,
+                    });
+                    break;
+                }
+            }
+        }
+        if (e.type === 'caption' && Array.isArray(e.words)) {
+            for (const w of e.words) {
+                const t = w?.text;
+                if (typeof t === 'string') {
+                    const ch = firstNonAscii(t);
+                    if (ch) {
+                        warnings.push({
+                            where: id,
+                            message: `Caption word has a non-ASCII character ("${ch}") — dropped by the runtime's ASCII atlas.`,
+                        });
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    return warnings;
+}
+//# sourceMappingURL=lint.js.map

package/dist/lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"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"}

package/dist/load-source.d.ts

@@ -0,0 +1,5 @@
+export declare function loadSource(filePath: string): Promise<{
+    path: string;
+    source: unknown;
+}>;
+//# sourceMappingURL=load-source.d.ts.map

package/dist/load-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-source.d.ts","sourceRoot":"","sources":["../src/load-source.ts"],"names":[],"mappings":"AAkBA,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC,CAwBD"}

package/dist/load-source.js

@@ -0,0 +1,63 @@
+// Load a Clipkit Source from a file. Supports .json and .ts/.tsx/.mts/.cts.
+//
+// For TypeScript files, we use jiti — a small runtime TS loader that
+// understands ESM + CJS + TS and is fast enough for one-off CLI runs.
+// The file MUST export the Source as either a default export or a named
+// export called `source`, `video`, or `default`.
+import { readFile } from 'node:fs/promises';
+import { resolve as resolvePath, extname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createJiti } from 'jiti';
+const TS_EXTS = new Set(['.ts', '.tsx', '.mts', '.cts']);
+const JSON_EXTS = new Set(['.json']);
+const JS_EXTS = new Set(['.js', '.mjs', '.cjs']);
+const CANDIDATE_NAMED_EXPORTS = ['source', 'video', 'project', 'composition'];
+export async function loadSource(filePath) {
+    const abs = resolvePath(process.cwd(), filePath);
+    const ext = extname(abs).toLowerCase();
+    if (JSON_EXTS.has(ext)) {
+        const raw = await readFile(abs, 'utf8');
+        return { path: abs, source: JSON.parse(raw) };
+    }
+    if (TS_EXTS.has(ext) || JS_EXTS.has(ext)) {
+        const mod = await loadModule(abs);
+        const source = pickSource(mod);
+        if (source === undefined) {
+            throw new Error(`${filePath}: no Clipkit Source found. Export it as ` +
+                `\`default\` or one of: ${CANDIDATE_NAMED_EXPORTS.join(', ')}.`);
+        }
+        return { path: abs, source };
+    }
+    throw new Error(`${filePath}: unsupported extension "${ext}". Expected one of: .json, .ts, .tsx, .mts, .cts, .js, .mjs, .cjs.`);
+}
+async function loadModule(abs) {
+    const ext = extname(abs).toLowerCase();
+    if (TS_EXTS.has(ext)) {
+        // Use jiti for TS — handles .ts in a Node process without a build step.
+        const jiti = createJiti(pathToFileURL(abs).href, {
+            interopDefault: true,
+            cache: false,
+        });
+        const mod = (await jiti.import(abs, {}));
+        return mod;
+    }
+    // Plain JS — native dynamic import.
+    return (await import(pathToFileURL(abs).href));
+}
+function pickSource(mod) {
+    // Prefer a named export from our candidate list.
+    for (const name of CANDIDATE_NAMED_EXPORTS) {
+        if (mod[name] !== undefined)
+            return mod[name];
+    }
+    // Fall back to `default`. With interopDefault: true this is unwrapped
+    // if the file used `export default`.
+    if (mod.default !== undefined)
+        return mod.default;
+    // Single named export — accept it.
+    const keys = Object.keys(mod).filter((k) => k !== 'default');
+    if (keys.length === 1)
+        return mod[keys[0]];
+    return undefined;
+}
+//# sourceMappingURL=load-source.js.map

package/dist/load-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-source.js","sourceRoot":"","sources":["../src/load-source.ts"],"names":[],"mappings":"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"}