Files
2026-08-12 02:11:40 -07:00

357 lines
15 KiB
JavaScript

#!/usr/bin/env node
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { resolve } from "node:path";
const STAGES = ["briefed", "directed", "selected", "planned", "built", "verified"];
const ROLES = new Set(["structure", "navigation", "signature", "motion", "asset-language"]);
const LANES = new Set(["native", "signature", "experimental"]);
const GATES = ["code", "visual", "temporal", "human"];
const GATE_STATUSES = new Set(["pending", "pass", "fail", "blocked"]);
const MEDIA_STATUSES = new Set(["planned", "running", "complete", "blocked", "rejected"]);
function fail(message, code = 1) {
console.error(`Studio run error: ${message}`);
process.exit(code);
}
function parseArgs(argv) {
const [command, ...rest] = argv;
const options = {};
for (let i = 0; i < rest.length; i += 1) {
const token = rest[i];
if (!token.startsWith("--")) fail(`unexpected argument ${token}`);
const key = token.slice(2);
const value = rest[i + 1];
if (!value || value.startsWith("--")) fail(`missing value for --${key}`);
options[key] = value;
i += 1;
}
return { command, options };
}
function slugify(value) {
return value
.normalize("NFKD")
.toLowerCase()
.replace(/[^a-z0-9]+/g, "-")
.replace(/^-+|-+$/g, "")
.slice(0, 48) || "studio-run";
}
function now() {
return new Date().toISOString();
}
function readJson(path) {
try {
return JSON.parse(readFileSync(path, "utf8"));
} catch (error) {
fail(`cannot read ${path}: ${error.message}`);
}
}
function writeJson(path, value) {
writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
}
function projectRoot(options) {
return resolve(options["project-root"] || process.cwd());
}
function runDir(options) {
const id = options.run;
if (!id) fail("--run is required");
return resolve(projectRoot(options), ".styleseed", "studio", id);
}
function requireRun(options) {
const dir = runDir(options);
const path = resolve(dir, "run.json");
if (!existsSync(path)) fail(`run not found: ${dir}`);
return { dir, path, run: readJson(path) };
}
function requiredString(value, label, failures) {
if (typeof value !== "string" || !value.trim()) failures.push(`${label} is required`);
}
function validateDirection(direction, index, failures) {
const prefix = `directions[${index}]`;
for (const key of [
"id", "lane", "name", "promise", "grammar", "recipe", "palette", "composition",
"navigationChrome", "typeAndMaterial", "assetDirection", "motionDirection", "signatureMove",
"cost", "risk",
]) requiredString(direction?.[key], `${prefix}.${key}`, failures);
if (!LANES.has(direction?.lane)) failures.push(`${prefix}.lane is invalid`);
if (!Array.isArray(direction?.tradeoffs) || direction.tradeoffs.length === 0) {
failures.push(`${prefix}.tradeoffs must contain at least one item`);
}
}
function validateTarget(dir, run, target) {
const failures = [];
if (!STAGES.includes(target)) failures.push(`unknown target stage ${target}`);
const briefPath = resolve(dir, "brief.md");
if (!existsSync(briefPath) || readFileSync(briefPath, "utf8").trim().length < 40) {
failures.push("brief.md must contain a concrete product brief");
}
if (STAGES.indexOf(target) >= STAGES.indexOf("directed")) {
const references = readJson(resolve(dir, "references.json"));
if (!Array.isArray(references.items)) failures.push("references.json items must be an array");
else references.items.forEach((item, index) => {
requiredString(item.id, `references[${index}].id`, failures);
if (!ROLES.has(item.role)) failures.push(`references[${index}].role is invalid`);
for (const key of ["source", "observedAt", "observation", "principle", "confidence", "rights"])
requiredString(item[key], `references[${index}].${key}`, failures);
});
const directions = readJson(resolve(dir, "directions.json"));
if (!Array.isArray(directions.directions) || directions.directions.length !== 3) {
failures.push("directions.json must contain exactly three directions");
} else {
directions.directions.forEach((direction, index) => validateDirection(direction, index, failures));
const lanes = new Set(directions.directions.map((direction) => direction.lane));
for (const lane of LANES) if (!lanes.has(lane)) failures.push(`missing ${lane} direction`);
const ids = new Set(directions.directions.map((direction) => direction.id));
if (ids.size !== 3) failures.push("direction ids must be unique");
}
}
if (STAGES.indexOf(target) >= STAGES.indexOf("selected")) {
const selection = readJson(resolve(dir, "selection.json"));
const directions = readJson(resolve(dir, "directions.json")).directions || [];
requiredString(selection.selectedDirectionId, "selection.selectedDirectionId", failures);
requiredString(selection.decisionBy, "selection.decisionBy", failures);
requiredString(selection.decidedAt, "selection.decidedAt", failures);
requiredString(selection.rationale, "selection.rationale", failures);
if (!directions.some((direction) => direction.id === selection.selectedDirectionId)) {
failures.push("selection does not match a direction id");
}
}
if (STAGES.indexOf(target) >= STAGES.indexOf("planned")) {
const scenes = readJson(resolve(dir, "scenes.json"));
if (!Array.isArray(scenes.scenes) || scenes.scenes.length === 0) failures.push("at least one interaction scene is required");
else scenes.scenes.forEach((scene, index) => {
for (const key of ["id", "trigger", "from", "to", "feedback", "interrupt", "reducedMotion"])
requiredString(scene[key], `scenes[${index}].${key}`, failures);
for (const key of ["continuity", "enter", "exit", "rendererTargets"])
if (!Array.isArray(scene[key])) failures.push(`scenes[${index}].${key} must be an array`);
});
const assets = readJson(resolve(dir, "assets.json"));
if (!Array.isArray(assets.jobs)) failures.push("assets.json jobs must be an array");
else assets.jobs.forEach((job, index) => {
for (const key of ["id", "role", "kind", "capability", "provider", "prompt", "status", "provenance", "rights", "fallback", "consumingScene"])
requiredString(job[key], `assets[${index}].${key}`, failures);
if (!Array.isArray(job.inputs)) failures.push(`assets[${index}].inputs must be an array`);
if (!MEDIA_STATUSES.has(job.status)) failures.push(`assets[${index}].status is invalid`);
if (job.status === "complete") requiredString(job.output, `assets[${index}].output`, failures);
});
const video = readJson(resolve(dir, "video.json"));
if (video.mode !== "prototype-first") failures.push("video.mode must be prototype-first");
if (!Array.isArray(video.shots) || !video.shots.some((shot) => shot.sourceType === "prototype-recording")) {
failures.push("video plan must contain at least one prototype-recording shot");
}
}
if (STAGES.indexOf(target) >= STAGES.indexOf("built")) {
requiredString(run.outputs?.prototype, "run.outputs.prototype", failures);
}
if (STAGES.indexOf(target) >= STAGES.indexOf("verified")) {
requiredString(run.outputs?.recording, "run.outputs.recording", failures);
const verification = readJson(resolve(dir, "verification.json"));
for (const gate of GATES) {
if (verification.gates?.[gate] !== "pass") failures.push(`verification gate ${gate} must pass`);
}
if (!Array.isArray(verification.evidence) || verification.evidence.length < 4) {
failures.push("verification needs evidence for all four gates");
}
requiredString(verification.reviewer, "verification.reviewer", failures);
requiredString(verification.acceptedAt, "verification.acceptedAt", failures);
}
return failures;
}
function init(options) {
for (const key of ["name", "brief", "surface", "platform"]) if (!options[key]) fail(`--${key} is required`);
const root = projectRoot(options);
const baseId = slugify(options.name);
let id = baseId;
let suffix = 2;
while (existsSync(resolve(root, ".styleseed", "studio", id))) id = `${baseId}-${suffix++}`;
const dir = resolve(root, ".styleseed", "studio", id);
mkdirSync(resolve(dir, "assets", "generated"), { recursive: true });
mkdirSync(resolve(dir, "evidence", "frames"), { recursive: true });
mkdirSync(resolve(dir, "evidence", "recordings"), { recursive: true });
const createdAt = now();
writeJson(resolve(dir, "run.json"), {
schemaVersion: 1,
id,
title: options.name,
createdAt,
updatedAt: createdAt,
stage: "briefed",
surface: options.surface,
platform: options.platform,
outputs: { prototype: null, recording: null },
});
writeFileSync(resolve(dir, "brief.md"), `# ${options.name}\n\n${options.brief.trim()}\n`);
writeJson(resolve(dir, "references.json"), { items: [] });
writeJson(resolve(dir, "directions.json"), { directions: [] });
writeJson(resolve(dir, "selection.json"), { selectedDirectionId: null, decisionBy: null, decidedAt: null, rationale: null });
writeJson(resolve(dir, "scenes.json"), { scenes: [] });
writeJson(resolve(dir, "assets.json"), { jobs: [] });
writeJson(resolve(dir, "video.json"), { mode: "prototype-first", shots: [] });
writeJson(resolve(dir, "verification.json"), {
gates: Object.fromEntries(GATES.map((gate) => [gate, "pending"])),
evidence: [], reviewer: null, acceptedAt: null, risks: [],
});
console.log(dir);
}
function select(options) {
const { dir, path, run } = requireRun(options);
for (const key of ["direction", "by", "rationale"]) if (!options[key]) fail(`--${key} is required`);
const directedFailures = validateTarget(dir, run, "directed");
if (directedFailures.length) fail(`cannot select before directions pass:\n- ${directedFailures.join("\n- ")}`);
const directions = readJson(resolve(dir, "directions.json")).directions;
if (!directions.some((direction) => direction.id === options.direction)) fail(`unknown direction ${options.direction}`);
writeJson(resolve(dir, "selection.json"), {
selectedDirectionId: options.direction,
decisionBy: options.by,
decidedAt: now(),
rationale: options.rationale,
});
run.stage = "selected";
run.updatedAt = now();
writeJson(path, run);
console.log(`${run.id}: selected ${options.direction}`);
}
function output(options) {
const { path, run } = requireRun(options);
if (!options.prototype && !options.recording) fail("pass --prototype and/or --recording");
if (options.prototype) run.outputs.prototype = options.prototype;
if (options.recording) run.outputs.recording = options.recording;
run.updatedAt = now();
writeJson(path, run);
console.log(`${run.id}: outputs updated`);
}
function media(options) {
const { dir, path, run } = requireRun(options);
for (const key of ["job", "status"]) if (!options[key]) fail(`--${key} is required`);
if (!MEDIA_STATUSES.has(options.status)) {
fail(`--status must be one of ${[...MEDIA_STATUSES].join(", ")}`);
}
const assetsPath = resolve(dir, "assets.json");
const assets = readJson(assetsPath);
const job = assets.jobs?.find((item) => item.id === options.job);
if (!job) fail(`media job not found: ${options.job}`);
if (options.status === "complete") {
for (const key of ["provider", "output", "provenance"]) {
if (!options[key] && !job[key]) fail(`complete media job requires --${key}`);
}
}
job.status = options.status;
if (options.provider) job.provider = options.provider;
if (options.output) job.output = options.output;
if (options.provenance) job.provenance = options.provenance;
job.updatedAt = now();
writeJson(assetsPath, assets);
run.updatedAt = now();
writeJson(path, run);
console.log(`${run.id}: media ${job.id} -> ${job.status}`);
}
function gate(options) {
const { dir, path, run } = requireRun(options);
for (const key of ["gate", "status"]) if (!options[key]) fail(`--${key} is required`);
if (!GATES.includes(options.gate)) fail(`--gate must be one of ${GATES.join(", ")}`);
if (!GATE_STATUSES.has(options.status)) {
fail(`--status must be one of ${[...GATE_STATUSES].join(", ")}`);
}
if (options.gate === "human" && options.status === "pass" && !options.reviewer) {
fail("human pass requires --reviewer");
}
const verificationPath = resolve(dir, "verification.json");
const verification = readJson(verificationPath);
verification.gates[options.gate] = options.status;
if (options.evidence) {
verification.evidence.push({
gate: options.gate,
path: options.evidence,
note: options.note || `${options.gate} ${options.status}`,
recordedAt: now(),
});
}
if (options.reviewer) verification.reviewer = options.reviewer;
if (options.gate === "human" && options.status === "pass") verification.acceptedAt = now();
writeJson(verificationPath, verification);
run.updatedAt = now();
writeJson(path, run);
console.log(`${run.id}: gate ${options.gate} -> ${options.status}`);
}
function advance(options) {
const { dir, path, run } = requireRun(options);
const target = options.stage;
if (!STAGES.includes(target)) fail(`--stage must be one of ${STAGES.join(", ")}`);
const currentIndex = STAGES.indexOf(run.stage);
const targetIndex = STAGES.indexOf(target);
if (targetIndex !== currentIndex + 1) fail(`advance must be sequential: ${run.stage} -> ${STAGES[currentIndex + 1] || "complete"}`);
if (target === "selected") fail("use the select command for the human selection gate");
const failures = validateTarget(dir, run, target);
if (failures.length) fail(`cannot advance to ${target}:\n- ${failures.join("\n- ")}`);
run.stage = target;
run.updatedAt = now();
writeJson(path, run);
console.log(`${run.id}: ${target}`);
}
function validate(options) {
const { dir, run } = requireRun(options);
const target = options.target || run.stage;
const failures = validateTarget(dir, run, target);
if (failures.length) fail(`${target} validation failed:\n- ${failures.join("\n- ")}`, 2);
console.log(`${run.id}: ${target} contract valid`);
}
function status(options) {
const { dir, run } = requireRun(options);
const selection = readJson(resolve(dir, "selection.json"));
const assets = readJson(resolve(dir, "assets.json"));
const video = readJson(resolve(dir, "video.json"));
const verification = readJson(resolve(dir, "verification.json"));
console.log(JSON.stringify({
id: run.id,
stage: run.stage,
surface: run.surface,
platform: run.platform,
selectedDirection: selection.selectedDirectionId,
mediaJobs: assets.jobs.length,
mediaComplete: assets.jobs.filter((job) => job.status === "complete").length,
prototypeShots: video.shots.filter((shot) => shot.sourceType === "prototype-recording").length,
gates: verification.gates,
outputs: run.outputs,
path: dir,
}, null, 2));
}
const { command, options } = parseArgs(process.argv.slice(2));
if (command === "init") init(options);
else if (command === "select") select(options);
else if (command === "output") output(options);
else if (command === "media") media(options);
else if (command === "gate") gate(options);
else if (command === "advance") advance(options);
else if (command === "validate") validate(options);
else if (command === "status") status(options);
else fail("command must be init, select, output, media, gate, advance, validate, or status");