@writepanda/cli 1.9.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kamala Kannan Sankarraj
+
+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

@@ -0,0 +1,100 @@
+# @writepanda/cli
+
+The `pandastudio` command-line interface — drive [PandaStudio](https://www.writepanda.ai) (a desktop video editor for YouTube creators) from your terminal, shell scripts, or AI agents.
+
+PandaStudio's signature feature — editing video by deleting words from the transcript — is now scriptable. Plus headless export, motion-graphic generation, FX overlays, lower-thirds, captions, AI title/description generation. Everything the human editor does, callable from the CLI.
+
+> **You also need the desktop app installed.** The CLI is a thin HTTP client; the actual rendering happens in PandaStudio's localhost-only automation server. Get the app at [writepanda.ai](https://www.writepanda.ai).
+
+## Install
+
+```bash
+npm install -g @writepanda/cli
+# or run without installing:
+npx @writepanda/cli system.status
+```
+
+The same `pandastudio` binary also ships bundled inside every PandaStudio install (Settings → Local automation → Install to PATH). The npm version is convenient for AI agents and CI pipelines that want to script the editor without going through the in-app install button.
+
+## Quickstart
+
+```bash
+# 1. Install + open PandaStudio (writepanda.ai). Settings → Local automation → toggle ON.
+
+# 2. Confirm reachability:
+pandastudio system.status
+
+# 3. Discover the surface (62 verb-noun commands):
+pandastudio commands
+
+# 4. Render a motion graphic:
+JOB=$(pandastudio motion.generate \
+  --templateId=title-card-vox \
+  --slots='{"title":"How I Built This","subtitle":"in 24 hours"}' \
+  --aspectRatio=16:9 \
+  --json | jq -r '.data.jobId')
+
+pandastudio job.wait --id="$JOB" --json | jq '.data.job.result.outputPath'
+```
+
+If PandaStudio isn't running, the CLI auto-launches it and waits up to 60s for the HTTP listener. Pass `--no-launch` to opt out.
+
+## The agentic edit flow
+
+The 13-step "agent gets two videos and produces a polished MP4" workflow is documented in full at [writepanda.ai/cli](https://www.writepanda.ai/cli). Headline:
+
+```bash
+pandastudio project.new --withMedia='[...]' --json
+pandastudio transcript.transcribe --id=$ID
+pandastudio transcript.remove-fillers --id=$ID
+pandastudio motion.generate ...
+pandastudio project.add-motion-graphic ...
+pandastudio caption.toggle --enabled=true
+pandastudio caption.set-template --templateId=bold
+pandastudio export.start --id=$ID
+```
+
+Headless. No editor window required. Same Skia native render-helper the in-app Export button uses.
+
+## For AI agents (Claude Code, Claude Desktop)
+
+If you're an agent: install the **bundled Claude Skill** instead — it teaches you the full surface in one auto-discovered SKILL.md. From the running PandaStudio app: Settings → Local automation → Install Skill. The Skill copies to `~/.claude/skills/pandastudio/` and Claude auto-loads it.
+
+For Cursor / Continue / Cline / other MCP clients, use the companion package: [`@writepanda/mcp`](https://www.npmjs.com/package/@writepanda/mcp).
+
+## Auth
+
+Every PandaStudio launch generates a fresh 256-bit token, written 0600 to:
+
+| Platform | Path |
+|---|---|
+| macOS / Linux | `~/.config/pandastudio/{token,port,audit.log}` |
+| Windows | `%APPDATA%\pandastudio\{token,port,audit.log}` |
+
+The CLI reads both files on every invocation; no env vars, no caching. Closing and reopening the desktop app rotates the token automatically. `PANDASTUDIO_CONFIG_DIR` overrides the path (used in tests).
+
+## Licensing
+
+The CLI honours the same license gate the desktop app does:
+
+| State | What's allowed |
+|---|---|
+| Licensed | Every command |
+| Active trial | Every command |
+| Trial expired, no license | Only `system.*` and `window.focus` |
+
+Run `pandastudio system.status` to see `automationGated: true/false` in the response.
+
+## Output modes
+
+- Default: pretty one-line summaries to stdout
+- `--json`: raw `{ ok, data, error }` envelope — pipe through `jq` for scripting
+
+## Documentation
+
+- Full command catalogue + recipes: [writepanda.ai/cli](https://www.writepanda.ai/cli)
+- Source: [github.com/kamskans/openscreen](https://github.com/kamskans/openscreen)
+
+## License
+
+MIT.

package/bin/pandastudio.mjs

@@ -0,0 +1,398 @@
+#!/usr/bin/env node
+// pandastudio — local CLI for the PandaStudio automation surface.
+//
+// Design goals (per the HuggingFace CLI-vs-MCP analysis):
+//   • Token-frugal output. By default we print a one-line success
+//     summary, with `--json` opting into machine-readable payloads.
+//   • Deterministic dispatch. Every command is a `verb.noun` that maps
+//     1:1 to a registered handler in the main process.
+//   • Graceful auto-launch. If the app isn't running, we spawn the
+//     installed PandaStudio.app (or the dev binary) and poll
+//     `/v1/health` until it's ready before sending the actual call.
+//   • No third-party deps — pure Node so it's bundled as a single
+//     file inside the installer.
+//
+// Layout:
+//   ~/.config/pandastudio/{token,port,audit.log}   ← well-known
+//   /usr/local/bin/pandastudio (mac, post-install symlink)
+//   %ProgramFiles%/PandaStudio/cli/pandastudio.exe (Windows installer)
+
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+const VERSION = "1.0.0";
+
+function configDir() {
+	// PANDASTUDIO_CONFIG_DIR mirrors the override the main process
+	// honours in electron/automation/auth.ts. Useful for (a) integration
+	// tests that point both sides at a tmp dir, (b) power users with an
+	// alternate install location.
+	if (process.env.PANDASTUDIO_CONFIG_DIR) {
+		return process.env.PANDASTUDIO_CONFIG_DIR;
+	}
+	if (process.platform === "win32") {
+		const appData = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
+		return path.join(appData, "pandastudio");
+	}
+	return path.join(os.homedir(), ".config", "pandastudio");
+}
+
+const TOKEN_FILE = path.join(configDir(), "token");
+const PORT_FILE = path.join(configDir(), "port");
+
+function printHelp() {
+	process.stdout.write(`pandastudio v${VERSION} — local CLI for the PandaStudio automation surface
+
+USAGE
+  pandastudio <command> [--key value …]            Run a command
+  pandastudio --help                               This message
+  pandastudio --version                            Print CLI version
+  pandastudio commands                             List every available verb.noun
+
+OPTIONS
+  --json                  Emit raw JSON to stdout (machine-readable mode).
+  --no-launch             Don't auto-launch PandaStudio if it isn't running.
+  --timeout=<seconds>     How long to wait for auto-launch readiness (default 60).
+  --token=<value>         Override the on-disk token (rare; for tests).
+  --port=<n>              Override the on-disk port (rare; for tests).
+  --app=<path>            Override the path to the PandaStudio binary used for auto-launch.
+
+EXAMPLES
+  pandastudio system.status
+  pandastudio system.status --json
+  pandastudio motion.list
+  pandastudio motion.generate --templateId=title-card-vox --slots='{"title":"Hello","subtitle":"World"}'
+  pandastudio job.wait --id=<jobId>
+
+DOCS
+  Token + port files live in ${configDir()}.
+  Audit log:                ${path.join(configDir(), "audit.log")}.
+`);
+}
+
+function parseArgv(argv) {
+	const args = { _: [], flags: {}, json: false, noLaunch: false, timeoutSeconds: 60 };
+	for (const raw of argv) {
+		if (raw === "--help" || raw === "-h") {
+			args.help = true;
+		} else if (raw === "--version" || raw === "-v") {
+			args.version = true;
+		} else if (raw === "--json") {
+			args.json = true;
+		} else if (raw === "--no-launch") {
+			args.noLaunch = true;
+		} else if (raw.startsWith("--timeout=")) {
+			args.timeoutSeconds = Number(raw.slice("--timeout=".length)) || 60;
+		} else if (raw.startsWith("--token=")) {
+			args.tokenOverride = raw.slice("--token=".length);
+		} else if (raw.startsWith("--port=")) {
+			args.portOverride = Number(raw.slice("--port=".length));
+		} else if (raw.startsWith("--app=")) {
+			args.appOverride = raw.slice("--app=".length);
+		} else if (raw.startsWith("--")) {
+			// --key=value or --key value (we only support --key=value form
+			// to keep things unambiguous; --flag with no value sets true)
+			const eq = raw.indexOf("=");
+			if (eq < 0) {
+				args.flags[raw.slice(2)] = true;
+			} else {
+				const key = raw.slice(2, eq);
+				const value = raw.slice(eq + 1);
+				args.flags[key] = parseScalar(value);
+			}
+		} else {
+			args._.push(raw);
+		}
+	}
+	return args;
+}
+
+function parseScalar(value) {
+	// JSON pass-through for objects/arrays/booleans/numbers; fall back
+	// to the literal string. Lets `--slots='{"title":"x"}'` work without
+	// a separate `--slots-json` flag.
+	const trimmed = value.trim();
+	if (
+		trimmed.startsWith("{") ||
+		trimmed.startsWith("[") ||
+		trimmed === "true" ||
+		trimmed === "false" ||
+		trimmed === "null" ||
+		(/^-?\d/.test(trimmed) && !Number.isNaN(Number(trimmed)))
+	) {
+		try {
+			return JSON.parse(trimmed);
+		} catch {
+			/* fall through */
+		}
+	}
+	return value;
+}
+
+async function readCredentials(opts) {
+	const port = opts.portOverride ?? Number((await fs.readFile(PORT_FILE, "utf-8")).trim());
+	const token = opts.tokenOverride ?? (await fs.readFile(TOKEN_FILE, "utf-8")).trim();
+	if (!Number.isInteger(port) || port <= 0) throw new Error(`invalid port in ${PORT_FILE}`);
+	if (!token) throw new Error(`empty token in ${TOKEN_FILE}`);
+	return { port, token };
+}
+
+async function fetchJson(port, pathSuffix, opts = {}) {
+	// Use the global fetch (Node 18+ ships it); we only require Node 22
+	// at runtime per the app's package.json engines block, so this is
+	// safe to assume.
+	const url = `http://127.0.0.1:${port}${pathSuffix}`;
+	const res = await fetch(url, opts);
+	const text = await res.text();
+	let parsed;
+	try {
+		parsed = text.length === 0 ? null : JSON.parse(text);
+	} catch {
+		parsed = { raw: text };
+	}
+	return { status: res.status, body: parsed };
+}
+
+async function probeHealth(port, timeoutMs) {
+	// Single short probe with a small AbortController; used as a
+	// liveness check before auto-launching, then in a poll loop after
+	// launch to wait for readiness.
+	const ctrl = new AbortController();
+	const t = setTimeout(() => ctrl.abort(), timeoutMs);
+	try {
+		const res = await fetch(`http://127.0.0.1:${port}/v1/health`, { signal: ctrl.signal });
+		clearTimeout(t);
+		return res.ok;
+	} catch {
+		clearTimeout(t);
+		return false;
+	}
+}
+
+function findInstalledApp(appOverride) {
+	if (appOverride) return appOverride;
+	if (process.env.PANDASTUDIO_BIN) return process.env.PANDASTUDIO_BIN;
+
+	if (process.platform === "darwin") {
+		const macCandidates = [
+			"/Applications/PandaStudio.app/Contents/MacOS/PandaStudio",
+			path.join(
+				os.homedir(),
+				"Applications",
+				"PandaStudio.app",
+				"Contents",
+				"MacOS",
+				"PandaStudio",
+			),
+		];
+		return macCandidates[0]; // best-effort; spawn() will surface ENOENT clearly
+	}
+	if (process.platform === "win32") {
+		const programFiles = process.env["ProgramFiles"] ?? "C:\\Program Files";
+		return path.join(programFiles, "PandaStudio", "PandaStudio.exe");
+	}
+	// Linux is unsupported by the installer today, but scaffolding it
+	// here means the day we publish a .AppImage or .deb the auto-launch
+	// path is one PR away.
+	return "/opt/PandaStudio/pandastudio";
+}
+
+async function autoLaunchAndWait(opts, log) {
+	const bin = findInstalledApp(opts.appOverride);
+	log(`auto-launching ${bin}`);
+	try {
+		const child = spawn(bin, [], {
+			detached: true,
+			stdio: "ignore",
+			env: process.env,
+		});
+		child.unref();
+	} catch (err) {
+		throw new Error(`failed to launch PandaStudio (${bin}): ${err?.message ?? err}`);
+	}
+
+	const deadline = Date.now() + opts.timeoutSeconds * 1000;
+	let credsKnown = null;
+	while (Date.now() < deadline) {
+		// Re-read credentials each iteration — the app writes them only
+		// after binding, so the file may not exist yet.
+		try {
+			credsKnown = await readCredentials(opts);
+			if (await probeHealth(credsKnown.port, 2000)) {
+				log(
+					`ready after ${Math.round((Date.now() - (deadline - opts.timeoutSeconds * 1000)) / 1000)}s`,
+				);
+				return credsKnown;
+			}
+		} catch {
+			/* token/port not written yet */
+		}
+		await new Promise((r) => setTimeout(r, 500));
+	}
+	throw new Error(
+		`PandaStudio did not become ready within ${opts.timeoutSeconds}s. Open the app and enable "Allow local automation" in Settings.`,
+	);
+}
+
+function emit(parsed, opts) {
+	if (opts.json) {
+		process.stdout.write(`${JSON.stringify(parsed.body, null, 2)}\n`);
+		return parsed.body?.ok === false ? 1 : 0;
+	}
+	if (parsed.status >= 400) {
+		process.stderr.write(`HTTP ${parsed.status}: ${parsed.body?.error ?? "unknown error"}\n`);
+		return 1;
+	}
+	if (parsed.body?.ok === false) {
+		process.stderr.write(`error: ${parsed.body.error}\n`);
+		if (parsed.body.details) {
+			process.stderr.write(`${JSON.stringify(parsed.body.details, null, 2)}\n`);
+		}
+		return 1;
+	}
+	prettyPrint(parsed.body?.data);
+	return 0;
+}
+
+function prettyPrint(data) {
+	// Heuristic table-ish output for common shapes. Anything we don't
+	// recognise falls back to JSON, which is still readable without
+	// blowing the user's terminal up.
+	if (data == null) {
+		process.stdout.write("ok\n");
+		return;
+	}
+	if (Array.isArray(data?.commands)) {
+		for (const c of data.commands) {
+			process.stdout.write(`  ${c.command.padEnd(28)} ${c.summary}\n`);
+		}
+		return;
+	}
+	if (Array.isArray(data?.templates)) {
+		for (const t of data.templates) {
+			process.stdout.write(`  ${t.id.padEnd(28)} ${t.name}\n`);
+		}
+		return;
+	}
+	if (Array.isArray(data?.themes)) {
+		for (const t of data.themes) {
+			process.stdout.write(`  ${t.id.padEnd(20)} ${t.name}\n`);
+		}
+		return;
+	}
+	if (Array.isArray(data?.projects)) {
+		for (const p of data.projects) {
+			process.stdout.write(`  ${p.modifiedAt}  ${p.name}\n    ${p.path}\n`);
+		}
+		return;
+	}
+	if (Array.isArray(data?.exports)) {
+		for (const e of data.exports) {
+			process.stdout.write(`  ${new Date(e.exportedAt).toISOString()}  ${e.fileName}\n`);
+		}
+		return;
+	}
+	if (data?.job) {
+		const j = data.job;
+		process.stdout.write(`  job ${j.id}\n  status: ${j.status}\n`);
+		if (j.progress?.message) process.stdout.write(`  progress: ${j.progress.message}\n`);
+		if (j.error) process.stdout.write(`  error: ${j.error}\n`);
+		if (j.result) process.stdout.write(`  result: ${JSON.stringify(j.result)}\n`);
+		return;
+	}
+	process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+}
+
+async function main() {
+	const argv = process.argv.slice(2);
+	const opts = parseArgv(argv);
+
+	if (opts.version) {
+		process.stdout.write(`${VERSION}\n`);
+		return 0;
+	}
+	if (opts.help || (opts._.length === 0 && Object.keys(opts.flags).length === 0)) {
+		printHelp();
+		return 0;
+	}
+
+	const log = (msg) => {
+		if (!opts.json) process.stderr.write(`[pandastudio] ${msg}\n`);
+	};
+
+	let command = opts._[0];
+	if (!command) {
+		process.stderr.write("error: missing command. Try `pandastudio --help`.\n");
+		return 2;
+	}
+
+	// Friendly aliases — `pandastudio commands` → `system.list`.
+	if (command === "commands") command = "system.list";
+	if (command === "status") command = "system.status";
+	if (command === "ping") command = "system.ping";
+
+	if (!command.includes(".")) {
+		process.stderr.write(`error: command must be of the form 'verb.noun' (got '${command}')\n`);
+		return 2;
+	}
+
+	let creds;
+	try {
+		creds = await readCredentials(opts);
+	} catch {
+		creds = null;
+	}
+
+	let alive = creds ? await probeHealth(creds.port, 1500) : false;
+	if (!alive) {
+		if (opts.noLaunch) {
+			process.stderr.write(
+				"error: PandaStudio is not reachable and --no-launch was set.\n  Open the app and enable 'Allow local automation' in Settings.\n",
+			);
+			return 3;
+		}
+		try {
+			creds = await autoLaunchAndWait(opts, log);
+			alive = true;
+		} catch (err) {
+			process.stderr.write(`${err?.message ?? err}\n`);
+			return 4;
+		}
+	}
+
+	// Build the call envelope. Everything after the command is mapped
+	// into the `args` object — the value `--slots='{"a":1}'` becomes
+	// `args.slots = {a:1}` thanks to parseScalar.
+	const callBody = { command, args: { ...opts.flags } };
+	const result = await fetchJson(creds.port, "/v1/call", {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Authorization: `Bearer ${creds.token}`,
+		},
+		body: JSON.stringify(callBody),
+	});
+
+	return emit(result, opts);
+}
+
+// IMPORTANT: do NOT call process.exit() here. process.exit forces an
+// immediate teardown that doesn't wait for stdout/stderr to drain — on
+// macOS the OS pipe buffer caps at 64 KiB, so any response larger than
+// that gets silently truncated mid-write (we hit this with export.list
+// returning 144 KB of JSON — only the first 64 KiB reached the user).
+//
+// Setting process.exitCode and letting Node return naturally lets the
+// streams flush properly. The "no top-level work pending" exit happens
+// after stdout's drain queue is empty.
+main()
+	.then((code) => {
+		process.exitCode = code ?? 0;
+	})
+	.catch((err) => {
+		process.stderr.write(`fatal: ${err?.stack ?? err}\n`);
+		process.exitCode = 99;
+	});

package/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@writepanda/cli",
+	"version": "1.9.3",
+	"description": "Drive PandaStudio (a desktop video editor for YouTube creators) from the command line. Talks to a localhost HTTP API the desktop app exposes.",
+	"keywords": [
+		"pandastudio",
+		"video-editor",
+		"cli",
+		"automation",
+		"agent",
+		"claude-code"
+	],
+	"author": "Kamala Kannan Sankarraj",
+	"license": "MIT",
+	"homepage": "https://www.writepanda.ai/cli",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/kamskans/openscreen.git",
+		"directory": "packages/cli"
+	},
+	"bugs": {
+		"url": "https://github.com/kamskans/openscreen/issues"
+	},
+	"type": "module",
+	"engines": {
+		"node": ">=18"
+	},
+	"bin": {
+		"pandastudio": "./bin/pandastudio.mjs"
+	},
+	"files": [
+		"bin",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"prepublishOnly": "node ../../scripts/sync-cli-to-package.mjs"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}