@writepanda/cli 1.119.0 → 1.180.0

package/bin/pandastudio.mjs

@@ -21,7 +21,9 @@
 //   %ProgramFiles%/PandaStudio/cli/pandastudio.exe (Windows installer)
 
 import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
 import fs from "node:fs/promises";
+import http from "node:http";
 import os from "node:os";
 import path from "node:path";
 import process from "node:process";
@@ -74,6 +76,12 @@ OPTIONS
   --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.
+  --key=@file.json        Read one argument's value from a file (JSON, else text).
+  --args-file=<path>      Read all arguments as one JSON object from a file
+                          (also: pandastudio <command> @args.json; - = stdin).
+  --args-stdin            Read all arguments as one JSON object from stdin.
+  --dry-run               Print the command + arguments that would be sent; don't call the app.
+  --help-windows          How to pass JSON arguments from cmd.exe / PowerShell / Git Bash.
 
 EXAMPLES
   pandastudio system.status
@@ -89,10 +97,23 @@ DOCS
 }
 
 function parseArgv(argv) {
-	const args = { _: [], flags: {}, json: false, noLaunch: false, timeoutSeconds: 60 };
-	for (const raw of argv) {
+	const args = { _: [], flags: {}, rawFlags: {}, json: false, noLaunch: false, timeoutSeconds: 60 };
+	for (let i = 0; i < argv.length; i++) {
+		const raw = argv[i];
 		if (raw === "--help" || raw === "-h") {
 			args.help = true;
+		} else if (raw === "--help-windows") {
+			args.helpWindows = true;
+		} else if (raw === "--dry-run") {
+			args.dryRun = true;
+		} else if (raw === "--args-stdin") {
+			args.argsStdin = true;
+		} else if (raw.startsWith("--args-file=")) {
+			args.argsFile = raw.slice("--args-file=".length);
+		} else if (raw === "--args-file") {
+			// The one flag that also takes the `--flag value` form: a path is
+			// easy to mistype that way and the error would be baffling.
+			args.argsFile = argv[++i] ?? "";
 		} else if (raw === "--version" || raw === "-v") {
 			args.version = true;
 		} else if (raw === "--json") {
@@ -116,8 +137,17 @@ function parseArgv(argv) {
 			} else {
 				const key = raw.slice(2, eq);
 				const value = raw.slice(eq + 1);
+				args.rawFlags[key] = value;
 				args.flags[key] = parseScalar(value);
 			}
+		} else if (
+			args._.length > 0 &&
+			raw.length > 1 &&
+			raw.startsWith("@") &&
+			!raw.startsWith("@@")
+		) {
+			// `pandastudio project.add-zoom @args.json` = --args-file=args.json
+			args.argsFile = raw.slice(1);
 		} else {
 			args._.push(raw);
 		}
@@ -125,6 +155,172 @@ function parseArgv(argv) {
 	return args;
 }
 
+/**
+ * Detects JSON a Windows shell mangled on the way in, returning a short
+ * reason or null. Two shapes:
+ *   - quotes stripped (cmd.exe, Windows PowerShell 5.1, Git Bash calling a
+ *     .cmd): `[{"timeMs":0,"x":"a"}]` arrives as `[{timeMs:0,x:a}]`;
+ *   - quotes left escaped (PowerShell 7.3+ given the 5.1 recipe):
+ *     `[{\"timeMs\":0}]`.
+ * Only text that becomes valid JSON once repaired counts, so an ordinary
+ * string that happens to start with a bracket (`[Note: hi]`) passes through.
+ */
+export function detectMangledJson(value) {
+	if (typeof value !== "string") return null;
+	const t = value.trim();
+	if (!(t.startsWith("{") || t.startsWith("["))) return null;
+	try {
+		JSON.parse(t);
+		return null;
+	} catch {
+		/* not JSON as given; see whether a shell broke it */
+	}
+	if (t.includes('\\"')) {
+		try {
+			JSON.parse(t.replace(/\\"/g, '"'));
+			return 'its double quotes arrived escaped as \\"';
+		} catch {
+			/* not that either */
+		}
+	}
+	// Needs real structure (an object, or a list of several items) so a
+	// bracketed word like "[draft]" stays plain text.
+	const structured = (t.includes("{") && t.includes(":")) || (t.startsWith("[") && t.includes(","));
+	const repaired = structured ? requoteBareJson(t) : null;
+	if (repaired !== null) {
+		try {
+			JSON.parse(repaired);
+			return "its double quotes were removed by the shell";
+		} catch {
+			/* not JSON-shaped */
+		}
+	}
+	return null;
+}
+
+/** Puts double quotes back around bare keys and bare string values
+ *  (`{a:b c,d:[e,1]}` → `{"a":"b c","d":["e",1]}`); null when the text has
+ *  a quote of its own (then it wasn't simply stripped). */
+function requoteBareJson(t) {
+	if (t.includes('"')) return null;
+	const quoteToken = (tok) => {
+		const s = tok.trim();
+		if (s === "") return tok;
+		if (/^(true|false|null)$/.test(s) || /^-?\d+(\.\d+)?([eE][+-]?\d+)?$/.test(s)) return tok;
+		return tok.replace(s, JSON.stringify(s));
+	};
+	// Split on structural characters, keeping them, and quote everything in
+	// between that isn't a number/literal.
+	return t
+		.split(/([{}[\],:])/)
+		.map((part) => (/^[{}[\],:]$/.test(part) ? part : quoteToken(part)))
+		.join("");
+}
+
+const WINDOWS_QUOTING_HELP = `Windows shells change JSON arguments on the way in: cmd.exe and Windows
+PowerShell 5.1 strip the double quotes, so
+--keyframes=[{"timeMs":0}] arrives as [{timeMs:0}]. These work on every shell:
+  --keyframes=@keyframes.json     read one value from a file (JSON, else text)
+  --args-file=args.json           all arguments as one JSON object from a file
+  pandastudio <command> @args.json   (same as --args-file)
+  --args-stdin                    all arguments as one JSON object on stdin,
+                                  e.g. Get-Content args.json | pandastudio <command> --args-stdin
+Inline, if you must:
+  cmd.exe:                "--keyframes=[{\\"timeMs\\":0}]"
+  Windows PowerShell 5.1: '--keyframes=[{\\"timeMs\\":0}]'
+  PowerShell 7.3+:        '--keyframes=[{"timeMs":0}]'
+Add --dry-run to print the exact arguments that would be sent, without calling the app.
+A literal value starting with @ is written @@ (--text=@@handle sends "@handle").`;
+
+/**
+ * The final args object: --args-file / --args-stdin first, then the
+ * command-line flags on top. A value `@path` is read from that file (JSON
+ * when it parses, else the text; `@@x` is the literal "@x"). Errors (a
+ * missing file, an args file that isn't an object, JSON a Windows shell
+ * mangled) come back as `error` so nothing half-parsed is ever sent.
+ */
+export async function resolveArgs(opts, { readStdin, cwd = process.cwd() } = {}) {
+	const out = {};
+	const readStdinText = () => (readStdin ? readStdin() : readAllStdin());
+	const readJsonObject = (text, where) => {
+		let v;
+		try {
+			v = JSON.parse(text.replace(/^/, ""));
+		} catch (e) {
+			const why = detectMangledJson(text);
+			throw new Error(
+				why
+					? `${where} is not valid JSON: ${why}.\n\n${WINDOWS_QUOTING_HELP}`
+					: `${where} is not valid JSON (${e.message}).`,
+			);
+		}
+		if (!v || typeof v !== "object" || Array.isArray(v)) {
+			throw new Error(
+				`${where} must be a JSON object of arguments, e.g. {"id":"abc","atMs":1000}.`,
+			);
+		}
+		return v;
+	};
+	try {
+		if (opts.argsFile === "") throw new Error("--args-file needs a path: --args-file=args.json");
+		if (opts.argsFile === "-") {
+			Object.assign(out, readJsonObject(await readStdinText(), "--args-file=- (stdin)"));
+		} else if (opts.argsFile) {
+			const p = path.resolve(cwd, opts.argsFile);
+			let text;
+			try {
+				text = await fs.readFile(p, "utf-8");
+			} catch {
+				throw new Error(`--args-file: can't read ${p}.`);
+			}
+			Object.assign(out, readJsonObject(text, `--args-file ${p}`));
+		}
+		if (opts.argsStdin) {
+			Object.assign(out, readJsonObject(await readStdinText(), "--args-stdin input"));
+		}
+		for (const [key, value] of Object.entries(opts.flags)) {
+			const raw = opts.rawFlags?.[key];
+			if (typeof raw === "string" && raw.startsWith("@@")) {
+				out[key] = raw.slice(1);
+			} else if (typeof raw === "string" && raw.length > 1 && raw.startsWith("@")) {
+				const p = path.resolve(cwd, raw.slice(1));
+				let text;
+				try {
+					text = await fs.readFile(p, "utf-8");
+				} catch {
+					throw new Error(
+						`--${key}=@${raw.slice(1)}: can't read ${p}. (A literal value starting with @ is written @@.)`,
+					);
+				}
+				const trimmed = text.replace(/^/, "").replace(/\r?\n$/, "");
+				try {
+					out[key] = JSON.parse(trimmed);
+				} catch {
+					const why = detectMangledJson(trimmed);
+					if (why)
+						throw new Error(`--${key}=@${raw.slice(1)}: the file is not valid JSON (${why}).`);
+					out[key] = trimmed;
+				}
+			} else if (typeof raw === "string" && detectMangledJson(raw)) {
+				throw new Error(
+					`--${key}=${raw} looks like JSON that the shell changed: ${detectMangledJson(raw)}. Nothing was sent.\n\n${WINDOWS_QUOTING_HELP}`,
+				);
+			} else {
+				out[key] = value;
+			}
+		}
+	} catch (err) {
+		return { error: err?.message ?? String(err) };
+	}
+	return { args: out };
+}
+
+async function readAllStdin() {
+	const chunks = [];
+	for await (const c of process.stdin) chunks.push(c);
+	return Buffer.concat(chunks).toString("utf-8");
+}
+
 function parseScalar(value) {
 	// JSON pass-through for objects/arrays/booleans/numbers; fall back
 	// to the literal string. Lets `--slots='{"title":"x"}'` work without
@@ -155,13 +351,33 @@ async function readCredentials(opts) {
 	return { port, token };
 }
 
+// The app answers /v1/call when the command finishes, and some commands run
+// for many minutes (an AI presenter take, a long music track). Node's global
+// fetch gives up on a response after 5 minutes ("fetch failed"), so calls go
+// through node:http, which waits as long as the command takes.
+function httpRequestLocal(port, pathSuffix, { method = "GET", headers = {}, body } = {}) {
+	return new Promise((resolve, reject) => {
+		const req = http.request(
+			{ host: "127.0.0.1", port, path: pathSuffix, method, headers },
+			(res) => {
+				const chunks = [];
+				res.on("data", (c) => chunks.push(c));
+				res.on("end", () =>
+					resolve({ status: res.statusCode ?? 0, text: Buffer.concat(chunks).toString("utf-8") }),
+				);
+				res.on("error", reject);
+			},
+		);
+		req.on("error", reject);
+		req.setTimeout(0);
+		if (body !== undefined) req.write(body);
+		req.end();
+	});
+}
+
 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();
+	const res = await httpRequestLocal(port, pathSuffix, opts);
+	const text = res.text;
 	let parsed;
 	try {
 		parsed = text.length === 0 ? null : JSON.parse(text);
@@ -187,32 +403,86 @@ async function probeHealth(port, timeoutMs) {
 	}
 }
 
+/**
+ * One health probe: "up" (answered), "busy" (the socket is open but no answer
+ * within `timeoutMs`: the app's main process is stalled, e.g. creating an
+ * editor window on a loaded machine) or "down" (connection refused / reset:
+ * not running).
+ */
+async function probeHealthState(port, timeoutMs) {
+	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 });
+		return res.ok ? "up" : "down";
+	} catch {
+		return ctrl.signal.aborted ? "busy" : "down";
+	} finally {
+		clearTimeout(t);
+	}
+}
+
+/**
+ * Is the app reachable? A busy app is waited for (up to `busyWaitMs`) rather
+ * than reported as not running: a single 1.5 s probe used to fail whenever the
+ * main process stalled for longer (window creation takes ~0.4 s idle and
+ * several seconds under load), so agents saw "not reachable" at random.
+ */
+async function appReachable(port, { probeMs = 1500, busyWaitMs = 30_000, onBusy } = {}) {
+	const deadline = Date.now() + busyWaitMs;
+	let warned = false;
+	for (;;) {
+		const s = await probeHealthState(port, probeMs);
+		if (s === "up") return true;
+		if (s === "down" || Date.now() >= deadline) return false;
+		if (!warned && onBusy) onBusy();
+		warned = true;
+		probeMs = Math.min(probeMs * 2, 5000);
+	}
+}
+
 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");
+	// The app records its own location (it can live anywhere on Windows,
+	// and in ~/Applications on a Mac).
+	try {
+		const recorded = readFileSync(path.join(configDir(), "app-path"), "utf-8").trim();
+		if (recorded && existsSync(recorded)) return recorded;
+	} catch {
+		/* older app, or never launched */
 	}
-	// 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";
+	const candidates =
+		process.platform === "darwin"
+			? [
+					"/Applications/PandaStudio.app/Contents/MacOS/PandaStudio",
+					path.join(
+						os.homedir(),
+						"Applications",
+						"PandaStudio.app",
+						"Contents",
+						"MacOS",
+						"PandaStudio",
+					),
+				]
+			: process.platform === "win32"
+				? [
+						// Per-user install (the installer default).
+						path.join(
+							process.env.LOCALAPPDATA ?? path.join(os.homedir(), "AppData", "Local"),
+							"Programs",
+							"PandaStudio",
+							"PandaStudio.exe",
+						),
+						path.join(
+							process.env.ProgramFiles ?? "C:\\Program Files",
+							"PandaStudio",
+							"PandaStudio.exe",
+						),
+					]
+				: ["/opt/PandaStudio/pandastudio"];
+	// spawn() surfaces ENOENT clearly when none exists.
+	return candidates.find((c) => existsSync(c)) ?? candidates[0];
 }
 
 async function autoLaunchAndWait(opts, log) {
@@ -248,7 +518,7 @@ async function autoLaunchAndWait(opts, log) {
 		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.`,
+		`PandaStudio did not become ready within ${opts.timeoutSeconds}s. Open PandaStudio, go to Settings → Automation and turn on Local automation.`,
 	);
 }
 
@@ -337,6 +607,10 @@ async function main() {
 		process.stdout.write(`${VERSION}\n`);
 		return 0;
 	}
+	if (opts.helpWindows) {
+		process.stdout.write(`${WINDOWS_QUOTING_HELP}\n`);
+		return 0;
+	}
 	if (opts.help || (opts._.length === 0 && Object.keys(opts.flags).length === 0)) {
 		printHelp();
 		return 0;
@@ -362,6 +636,16 @@ async function main() {
 		return 2;
 	}
 
+	const resolved = await resolveArgs(opts);
+	if (resolved.error) {
+		process.stderr.write(`error: ${resolved.error}\n`);
+		return 2;
+	}
+	if (opts.dryRun) {
+		process.stdout.write(`${JSON.stringify({ command, args: resolved.args }, null, 2)}\n`);
+		return 0;
+	}
+
 	let creds;
 	try {
 		creds = await readCredentials(opts);
@@ -369,11 +653,15 @@ async function main() {
 		creds = null;
 	}
 
-	let alive = creds ? await probeHealth(creds.port, 1500) : false;
+	let alive = creds
+		? await appReachable(creds.port, {
+				onBusy: () => log("PandaStudio is busy; waiting for it to answer"),
+			})
+		: 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",
+				"error: PandaStudio is not reachable and --no-launch was set.\n  Open PandaStudio, go to Settings → Automation and turn on Local automation.\n",
 			);
 			return 3;
 		}
@@ -389,7 +677,7 @@ async function main() {
 	// 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 callBody = { command, args: resolved.args };
 	const result = await fetchJson(creds.port, "/v1/call", {
 		method: "POST",
 		headers: {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@writepanda/cli",
-	"version": "1.119.0",
+	"version": "1.180.0",
 	"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",