@writepanda/cli 1.222.0 → 1.225.0

package/README.md

@@ -54,6 +54,13 @@ pandastudio caption.set-template --templateId=bold
 pandastudio export.start --id=$ID
 ```
 
+Review items: the user can pin notes, drawings and picked graphics on the editor preview and send them to the agent. Read and close them with:
+
+```bash
+pandastudio review.list --json        # open project; each item has imagePath (frame crop)
+pandastudio review.resolve --id=$ID --annotationIds='["ITEM_ID"]'
+```
+
 Same Tier-3 PixiJS render pipeline the in-app Export Video button uses (v1.24+ — convergence release). Reuses an open editor window if it's already on the target project, otherwise spawns a hidden one for the duration of the render. Identical output to a UI-driven export.
 
 ## For AI agents (Claude Code, Claude Desktop)
@@ -111,3 +118,9 @@ English, Parakeet's European set and the Whisper languages. Provider is
 `local|apple|deepgram|elevenlabs`. Never use cloud or apple with `auto`; choose a language first.
 Cloud needs a connected key and user consent to upload audio. Surface job `warnings`
 when a network/provider failure caused a local fallback.
+
+### Close a timeline gap
+
+`pandastudio project.close-gap --id=PROJECT --startMs=2500 --endMs=4000 --lane=media:0 --json`
+
+The timeline's right-click "Close gap". Times are edited milliseconds. Omit `lane` (or use `main`) to ripple-delete the range from the video; inserted pauses inside it are shortened or removed rather than cutting footage, and anchored regions follow. Use `media[:index]`, `audio[:index]` or `effects[:index]` to close an empty span of that sub-lane: every later item in the lane shifts left. Sub-lanes are zero based and packed by start time, matching the editor; speed changes never move. A range that is not empty fails and changes nothing. `expectedRevision` is supported. MCP: `project_close_gap`.

package/bin/pandastudio.mjs

@@ -40,7 +40,7 @@ for (const stream of [process.stdout, process.stderr]) {
 	});
 }
 
-const VERSION = "1.222.0";
+const VERSION = "1.225.0";
 
 function configDir() {
 	// PANDASTUDIO_CONFIG_DIR mirrors the override the main process
@@ -69,6 +69,17 @@ USAGE
   pandastudio transcript.transcribe --id=ID --force=true --language=tamil --provider=deepgram
   pandastudio transcript.detect-language --id=ID --clipId=CLIP
   pandastudio --version                            Print CLI version
+  pandastudio brand.list-assets --json             List workspace brand media
+  pandastudio brand.add-asset --path=/absolute/logo.png --role=logo
+  pandastudio project.add-brand-asset --id=<project> --assetId=<asset> --atMs=0
+  pandastudio brand.remove-asset --id=<asset>
+  pandastudio motion.variables --source=@generatedFrom.json   Typed variables of a graphic
+  pandastudio motion.generate --templateId=creator-card --variables='{"headline":"Client A"}'
+  pandastudio project.update-motion-graphic --id=ID --overlayId=OVERLAY --variables='{"headline":"New"}'
+  pandastudio project.update-motion-graphic --id=ID --overlayId=OVERLAY --preset="Client A lower third"
+  pandastudio motion.save-preset --source=@generatedFrom.json --name="Client A lower third" --variables=@values.json
+  pandastudio motion.list-presets --templateId=creator-card
+  pandastudio motion.delete-preset --templateId=creator-card --name="Client A lower third"
   pandastudio commands                             List every available verb.noun
 
 OPTIONS
@@ -389,22 +400,6 @@ async function fetchJson(port, pathSuffix, opts = {}) {
 	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;
-	}
-}
-
 /**
  * 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
@@ -509,7 +504,61 @@ function appLaunchEnv(env) {
 	return out;
 }
 
-async function autoLaunchAndWait(opts, log) {
+// Launch guard (mirrors ensureApp in packages/mcp/bin/appConnection.mjs; this
+// script ships as one standalone file). Launching whenever the port file's
+// server didn't answer started a NEW PandaStudio while one was busy, booting,
+// or had its token/port files replaced (Jared, Windows 2.1.15: "it restarted
+// with every request"). Launch only when nothing says PandaStudio is running,
+// and at most once per LAUNCH_DEBOUNCE_MS from any process on the machine.
+const DEFAULT_AUTOMATION_PORT = 7878;
+const INSTANCE_STALE_MS = 20_000;
+const LAUNCH_DEBOUNCE_MS = 90_000;
+
+function pidAlive(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return err?.code === "EPERM";
+	}
+}
+
+/** instance.json names a live PandaStudio with a fresh heartbeat. */
+async function appInstanceAlive() {
+	try {
+		const raw = await fs.readFile(path.join(configDir(), "instance.json"), "utf-8");
+		const rec = JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw);
+		const beat = Number(rec?.heartbeatAt);
+		if (!Number.isFinite(beat) || Date.now() - beat > INSTANCE_STALE_MS) return false;
+		return pidAlive(rec.pid);
+	} catch {
+		return false;
+	}
+}
+
+async function lastLaunchAgeMs() {
+	try {
+		const at = Number(
+			(await fs.readFile(path.join(configDir(), "launch-requested"), "utf-8")).trim(),
+		);
+		if (!Number.isFinite(at) || at > Date.now()) return null;
+		return Date.now() - at;
+	} catch {
+		return null;
+	}
+}
+
+async function recordLaunch() {
+	try {
+		await fs.mkdir(configDir(), { recursive: true });
+		await fs.writeFile(path.join(configDir(), "launch-requested"), String(Date.now()), "utf-8");
+	} catch {
+		/* best-effort */
+	}
+}
+
+function launchApp(opts, log) {
 	const bin = findInstalledApp(opts.appOverride);
 	log(`auto-launching ${bin}`);
 	try {
@@ -521,31 +570,76 @@ async function autoLaunchAndWait(opts, log) {
 			// program's first window too).
 			windowsHide: false,
 		});
+		child.on("error", () => {
+			/* reported by the readiness wait */
+		});
 		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.
+async function autoLaunchAndWait(opts, log) {
+	const started = Date.now();
+	const deadline = started + opts.timeoutSeconds * 1000;
+	let launched = false;
+	let last = { state: null, alive: false, preferred: null };
+	for (;;) {
+		// Re-read credentials each round: the app writes them only after
+		// binding, and its heartbeat rewrites them if they drifted.
+		let creds = null;
+		let state = null;
 		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;
-			}
+			creds = await readCredentials(opts);
+			state = await probeHealthState(creds.port, 1500);
 		} catch {
 			/* token/port not written yet */
 		}
+		if (state === "up") {
+			if (launched) log(`ready after ${Math.round((Date.now() - started) / 1000)}s`);
+			return creds;
+		}
+		const alive = await appInstanceAlive();
+		let preferred = null;
+		if (!alive && state !== "busy" && creds?.port !== DEFAULT_AUTOMATION_PORT) {
+			preferred = await probeHealthState(DEFAULT_AUTOMATION_PORT, 1000);
+		}
+		last = { state, alive, preferred };
+		const age = launched ? 0 : await lastLaunchAgeMs();
+		const mayLaunch =
+			state !== "busy" &&
+			!alive &&
+			preferred !== "up" &&
+			preferred !== "busy" &&
+			(age === null || age >= LAUNCH_DEBOUNCE_MS);
+		if (mayLaunch) {
+			await recordLaunch();
+			launched = true;
+			launchApp(opts, log);
+		} else if (!launched && Date.now() - started < 600) {
+			log("PandaStudio is already running; waiting for it to answer (not launching another)");
+		}
+		if (Date.now() >= deadline) break;
 		await new Promise((r) => setTimeout(r, 500));
 	}
+	const secs = opts.timeoutSeconds;
+	if (last.state === "busy") {
+		throw new Error(
+			`PandaStudio is running but busy: it didn't answer for ${secs}s. Try again in a moment; nothing was relaunched.`,
+		);
+	}
+	if (last.alive) {
+		throw new Error(
+			`PandaStudio is running but its automation server didn't answer within ${secs}s. In PandaStudio open Settings → Automation and make sure Local automation is on.`,
+		);
+	}
+	if (last.preferred === "up") {
+		throw new Error(
+			`A PandaStudio is answering on 127.0.0.1:${DEFAULT_AUTOMATION_PORT} but its access files in ${configDir()} are missing or stale. Quit PandaStudio completely and open it again.`,
+		);
+	}
 	throw new Error(
-		`PandaStudio did not become ready within ${opts.timeoutSeconds}s. Open PandaStudio, go to Settings → Automation and turn on Local automation.`,
+		`PandaStudio did not become ready within ${secs}s. Open PandaStudio, go to Settings → Automation and turn on Local automation.`,
 	);
 }
 

package/package.json

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