@glissade/cli 0.30.0 → 0.31.0-pre.0

package/dist/cli.js

@@ -78,6 +78,8 @@ const USAGE = `usage:
   gs cache verify <scene-module> [--range a..b] [--sample <n>]   assert cache hits == cold renders (§3.5)
   gs mcp <scene-module>   start an MCP stdio server for this scene: describe / list_targets / apply_patch / undo / render_frame (the AI-native write layer)
   gs build [filter...] [--config <glissade.config.ts>] [--explain]   content-graph DAG runner: narrate→sfx→loudness→render per scene, runs ONLY the stale subtree
+  gs describe [--out <api.json>] [--examples]   snapshot THIS engine's describe() API manifest (stdout, or --out to a file) — the input to gs migrate
+  gs migrate <baseline-api.json> [--json]   diff a saved API manifest against the current engine: moved imports / removed / added / changed, with a suggested fix per breaking item (advisory; never rewrites your files)
 
 render options:
   --out <path>     output directory for a PNG sequence, or .mp4/.webm (needs ffmpeg). default: ./out
@@ -168,7 +170,7 @@ narration-lint options (lint the committed *.narration.timing.json + the real ca
 `;
 async function main() {
 	const [command, ...rest] = process.argv.slice(2);
-	if (command !== "render" && command !== "diff" && command !== "verify-determinism" && command !== "dev" && command !== "import" && command !== "narrate" && command !== "narration-lint" && command !== "sfx" && command !== "prepare" && command !== "measure-loudness" && command !== "fonts" && command !== "cache" && command !== "mcp" && command !== "build") {
+	if (command !== "render" && command !== "diff" && command !== "verify-determinism" && command !== "dev" && command !== "import" && command !== "narrate" && command !== "narration-lint" && command !== "sfx" && command !== "prepare" && command !== "measure-loudness" && command !== "fonts" && command !== "cache" && command !== "mcp" && command !== "build" && command !== "describe" && command !== "migrate") {
 		console.error(USAGE);
 		process.exit(command === void 0 || command === "help" || command === "--help" ? 0 : 1);
 	}
@@ -240,6 +242,39 @@ async function main() {
 		}
 		return;
 	}
+	if (command === "describe") {
+		const { flags: df } = parseArgs(rest);
+		const { describe } = await import("@glissade/scene/describe");
+		if (df.has("examples")) await import("@glissade/scene/examples");
+		const manifest = describe(df.has("examples") ? { examples: true } : {});
+		const json = `${JSON.stringify(manifest, null, 2)}\n`;
+		const outPath = df.get("out");
+		if (outPath) {
+			const { writeFileSync } = await import("node:fs");
+			writeFileSync(outPath, json);
+			process.stderr.write(`gs describe: wrote ${manifest.version} API manifest → ${outPath}\n`);
+		} else process.stdout.write(json);
+		return;
+	}
+	if (command === "migrate") {
+		const { positional: mp, flags: mf } = parseArgs(rest);
+		const baselinePath = mp[0];
+		if (!baselinePath) fail(`gs migrate needs <baseline-api.json> (a manifest from an older 'gs describe --out')\n${USAGE}`);
+		const { readFileSync } = await import("node:fs");
+		const { describe } = await import("@glissade/scene/describe");
+		const { diffManifests, formatReport } = await import("./migrate.js");
+		let baseline;
+		try {
+			baseline = JSON.parse(readFileSync(baselinePath, "utf8"));
+		} catch (err) {
+			fail(`could not read baseline manifest '${baselinePath}': ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (typeof baseline.version !== "string" || baseline.nodes === void 0) fail(`'${baselinePath}' is not a describe() API manifest (missing version/nodes) — did you point at the right file?`);
+		const report = diffManifests(baseline, describe());
+		if (mf.has("json")) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+		else process.stdout.write(`${formatReport(report)}\n`);
+		return;
+	}
 	const { positional, flags } = parseArgs(rest);
 	const modulePath = positional[0];
 	if (!modulePath) fail(`missing ${command === "import" ? "<lottie.json|asset.svg>" : "<scene-module>"}\n${USAGE}`);

package/dist/migrate.js

@@ -0,0 +1,241 @@
+//#region src/migrate.ts
+/** Stable-sorted keys of a plain record (deterministic report order — no Object.keys insertion-order surprises). */
+function keys(obj) {
+	return obj ? Object.keys(obj).sort() : [];
+}
+/** Compare one node's prop against its old shape; push any material changes. */
+function diffProp(nodeName, propName, from, to, out) {
+	const id = `${nodeName}.${propName}`;
+	if (from.type !== to.type) out.push({
+		kind: "changed",
+		category: "prop",
+		name: id,
+		breaking: true,
+		detail: `value type ${from.type} → ${to.type}`,
+		action: `a Track on ${id} now expects a ${to.type} value — VERIFY every keyframe`
+	});
+	if (from.animatable && !to.animatable) out.push({
+		kind: "changed",
+		category: "prop",
+		name: id,
+		breaking: true,
+		detail: `no longer animatable (was driven by target '${from.target ?? id}')`,
+		action: `remove or re-home the Track targeting '${from.target ?? id}'`
+	});
+	else if (!from.animatable && to.animatable) out.push({
+		kind: "changed",
+		category: "prop",
+		name: id,
+		breaking: false,
+		detail: `now animatable via target '${to.target ?? id}'`
+	});
+}
+/**
+* Diff two describe() manifests into a structured, deterministic migration
+* report. Pure: same (from, to) → same report, in stable name order. This is the
+* whole engine — the CLI just loads the two manifests and formats this.
+*/
+function diffManifests(from, to) {
+	const out = [];
+	for (const name of keys(from.nodes)) {
+		const a = from.nodes[name];
+		const b = to.nodes[name];
+		if (a === void 0) continue;
+		if (b === void 0) {
+			out.push({
+				kind: "removed",
+				category: "node",
+				name,
+				breaking: true,
+				detail: `node type removed (was imported from ${a.subpath ?? "@glissade/scene"})`,
+				action: `this node no longer exists — replace it or pin the last engine that had it`
+			});
+			continue;
+		}
+		if ((a.subpath ?? "") !== (b.subpath ?? "")) {
+			const toPath = b.subpath ?? "@glissade/scene";
+			out.push({
+				kind: "moved",
+				category: "node",
+				name,
+				breaking: true,
+				detail: `import moved ${a.subpath ?? "@glissade/scene"} → ${toPath}`,
+				action: `import { ${name} } from '${toPath}'`
+			});
+		}
+		for (const p of keys(a.props)) {
+			const pa = a.props[p];
+			const pb = b.props[p];
+			if (pa === void 0) continue;
+			if (pb === void 0) {
+				out.push({
+					kind: "removed",
+					category: "prop",
+					name: `${name}.${p}`,
+					breaking: true,
+					detail: `prop removed`,
+					action: `remove '${p}' from ${name}(...) — it's no longer a recognized prop`
+				});
+				continue;
+			}
+			diffProp(name, p, pa, pb, out);
+		}
+		for (const p of keys(b.props)) if (a.props[p] === void 0) out.push({
+			kind: "added",
+			category: "prop",
+			name: `${name}.${p}`,
+			breaking: false,
+			detail: `new prop (${b.props[p]?.animatable ? "animatable" : "construction-only"})`
+		});
+	}
+	for (const name of keys(to.nodes)) if (from.nodes[name] === void 0) {
+		const sp = to.nodes[name]?.subpath ?? "@glissade/scene";
+		out.push({
+			kind: "added",
+			category: "node",
+			name,
+			breaking: false,
+			detail: `new node type (import from ${sp})`
+		});
+	}
+	const fromHelpers = new Map(from.helpers.map((h) => [h.name, h]));
+	const toHelpers = new Map(to.helpers.map((h) => [h.name, h]));
+	for (const name of [...fromHelpers.keys()].sort()) {
+		const a = fromHelpers.get(name);
+		const b = toHelpers.get(name);
+		if (b === void 0) {
+			out.push({
+				kind: "removed",
+				category: "helper",
+				name,
+				breaking: true,
+				detail: `helper removed (was imported from ${a.import})`,
+				action: `this helper no longer exists — replace it or pin the last engine that had it`
+			});
+			continue;
+		}
+		if (a.import !== b.import) out.push({
+			kind: "moved",
+			category: "helper",
+			name,
+			breaking: true,
+			detail: `import moved ${a.import} → ${b.import}`,
+			action: `import { ${name} } from '${b.import}'`
+		});
+		if (a.usage !== b.usage) out.push({
+			kind: "changed",
+			category: "helper",
+			name,
+			breaking: true,
+			detail: `signature changed: ${a.usage} → ${b.usage}`,
+			action: `update call sites of ${name}(...) to the new shape — VERIFY`
+		});
+	}
+	for (const name of [...toHelpers.keys()].sort()) if (!fromHelpers.has(name)) out.push({
+		kind: "added",
+		category: "helper",
+		name,
+		breaking: false,
+		detail: `new helper (import from ${toHelpers.get(name).import})`
+	});
+	const fromB = new Map(from.builder.methods.map((m) => [m.name, m]));
+	const toB = new Map(to.builder.methods.map((m) => [m.name, m]));
+	for (const name of [...fromB.keys()].sort()) {
+		const a = fromB.get(name);
+		const b = toB.get(name);
+		if (b === void 0) {
+			out.push({
+				kind: "removed",
+				category: "builder",
+				name: `tl.${name}`,
+				breaking: true,
+				detail: `builder method removed`,
+				action: `tl.${name}(...) no longer exists — replace it`
+			});
+			continue;
+		}
+		if (a.signature !== b.signature) out.push({
+			kind: "changed",
+			category: "builder",
+			name: `tl.${name}`,
+			breaking: true,
+			detail: `signature changed: ${a.signature} → ${b.signature}`,
+			action: `update tl.${name}(...) call sites to the new signature — VERIFY`
+		});
+	}
+	for (const name of [...toB.keys()].sort()) if (!fromB.has(name)) out.push({
+		kind: "added",
+		category: "builder",
+		name: `tl.${name}`,
+		breaking: false,
+		detail: `new builder method`
+	});
+	diffStringSet("valueType", from.valueTypes, to.valueTypes, out);
+	diffStringSet("easing", from.easings, to.easings, out);
+	diffStringSet("subpath", keys(from.subpaths), keys(to.subpaths), out);
+	const breaking = out.filter((c) => c.breaking).length;
+	return {
+		from: from.version,
+		to: to.version,
+		changes: out,
+		summary: {
+			breaking,
+			additive: out.length - breaking,
+			total: out.length
+		}
+	};
+}
+/** Diff two flat string lists (value types / easings / subpath entries): removed = breaking, added = additive. */
+function diffStringSet(category, from, to, out) {
+	const toSet = new Set(to);
+	const fromSet = new Set(from);
+	for (const name of [...from].sort()) if (!toSet.has(name)) out.push({
+		kind: "removed",
+		category,
+		name,
+		breaking: true,
+		detail: `${category} removed`,
+		action: `'${name}' is no longer a registered ${category} — replace it`
+	});
+	for (const name of [...to].sort()) if (!fromSet.has(name)) out.push({
+		kind: "added",
+		category,
+		name,
+		breaking: false,
+		detail: `new ${category}`
+	});
+}
+const KIND_MARK = {
+	moved: "→",
+	removed: "✗",
+	changed: "~",
+	added: "+"
+};
+/** Render a report as grouped, human-readable text (the default CLI output). */
+function formatReport(r) {
+	const lines = [];
+	lines.push(`gs migrate: ${r.from} → ${r.to}`);
+	if (r.changes.length === 0) {
+		lines.push("  no API changes — nothing to migrate. ✓");
+		return lines.join("\n");
+	}
+	lines.push(`  ${r.summary.breaking} breaking · ${r.summary.additive} additive · ${r.summary.total} total`);
+	const breaking = r.changes.filter((c) => c.breaking);
+	const additive = r.changes.filter((c) => !c.breaking);
+	if (breaking.length > 0) {
+		lines.push("");
+		lines.push("BREAKING — action needed:");
+		for (const c of breaking) {
+			lines.push(`  ${KIND_MARK[c.kind]} [${c.category}] ${c.name}: ${c.detail}`);
+			if (c.action !== void 0) lines.push(`      ↳ ${c.action}`);
+		}
+	}
+	if (additive.length > 0) {
+		lines.push("");
+		lines.push("ADDITIVE — new in this engine:");
+		for (const c of additive) lines.push(`  ${KIND_MARK[c.kind]} [${c.category}] ${c.name}: ${c.detail}`);
+	}
+	return lines.join("\n");
+}
+//#endregion
+export { diffManifests, formatReport };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/cli",
-  "version": "0.30.0",
+  "version": "0.31.0-pre.0",
   "description": "glissade CLI: headless rendering via backend-skia (+ FFmpeg mux).",
   "license": "Apache-2.0",
   "engines": {
@@ -28,15 +28,15 @@
     "@napi-rs/canvas": "^0.1.65",
     "esbuild": "0.28.0",
     "jiti": "^2.4.2",
-    "@glissade/backend-skia": "0.30.0",
-    "@glissade/core": "0.30.0",
-    "@glissade/interact": "0.30.0",
-    "@glissade/lottie": "0.30.0",
-    "@glissade/narrate": "0.30.0",
-    "@glissade/player": "0.30.0",
-    "@glissade/scene": "0.30.0",
-    "@glissade/sfx": "0.30.0",
-    "@glissade/svg": "0.30.0"
+    "@glissade/backend-skia": "0.31.0-pre.0",
+    "@glissade/core": "0.31.0-pre.0",
+    "@glissade/interact": "0.31.0-pre.0",
+    "@glissade/lottie": "0.31.0-pre.0",
+    "@glissade/narrate": "0.31.0-pre.0",
+    "@glissade/player": "0.31.0-pre.0",
+    "@glissade/scene": "0.31.0-pre.0",
+    "@glissade/sfx": "0.31.0-pre.0",
+    "@glissade/svg": "0.31.0-pre.0"
   },
   "repository": {
     "type": "git",