stylegallery 0.1.4 → 0.1.7

package/scripts/compiler/mcp.mjs

@@ -0,0 +1,53 @@
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+
+import { createStyleGalleryMcpServer } from "../agent-native/mcp-adapter.mjs";
+import { agentNativeRegistry } from "../agent-native/registry.mjs";
+import { compilerOperations, compilerToolDefinitions } from "./operations.mjs";
+import { withCompilerDiscovery } from "./cli.mjs";
+import { executeCompiler, failure } from "./runtime.mjs";
+
+// Compose at the transport boundary. The byte-frozen v1 server, registry,
+// conformance receipts, and resources remain independently usable.
+export function createSgMcpServer(config = {}) {
+  const server = createStyleGalleryMcpServer();
+  const lifetime = new AbortController();
+  server.server.onclose = () => lifetime.abort();
+  const legacy = agentNativeRegistry.operations.filter(({ read_only }) => read_only);
+  const legacyByName = new Map(legacy.map((operation) => [operation.name, operation]));
+  const legacyTools = legacy.map((operation) => {
+    const inputSchema = structuredClone(operation.input_schema);
+    if (Object.hasOwn(inputSchema.properties ?? {}, "reference")) {
+      inputSchema.properties.stable_ref = structuredClone(inputSchema.properties.reference);
+      inputSchema.required = (inputSchema.required ?? []).filter((key) => key !== "reference");
+      inputSchema.anyOf = [{ required: ["reference"] }, { required: ["stable_ref"] }];
+    }
+    return {
+      name: operation.name, description: operation.description, inputSchema,
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    };
+  });
+  server.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [...legacyTools, ...compilerToolDefinitions()].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0),
+  }));
+  const callSchema = CallToolRequestSchema.extend({
+    params: CallToolRequestSchema.shape.params.extend({ arguments: z.unknown().optional() }),
+  });
+  server.server.setRequestHandler(callSchema, async (request, extra) => {
+    const operation = request.params.name;
+    let input = request.params.arguments ?? {};
+    let report;
+    if (Object.hasOwn(compilerOperations, operation) || operation === "workflow") {
+      const signals = [lifetime.signal, extra.signal, config.signal].filter(Boolean);
+      report = await executeCompiler(operation, input, { ...config, signal: AbortSignal.any(signals) });
+    } else if (legacyByName.has(operation)) {
+      if (input && typeof input === "object" && !Array.isArray(input) && Object.hasOwn(input, "stable_ref")) {
+        input = { ...input, reference: input.reference ?? input.stable_ref };
+        delete input.stable_ref;
+      }
+      report = withCompilerDiscovery(agentNativeRegistry.invoke(operation, input), config);
+    } else report = failure(operation, "operation_not_exposed", `Operation ${operation} is not exposed.`);
+    return { content: [{ type: "text", text: JSON.stringify(report) }], structuredContent: report, isError: report.ok !== true };
+  });
+  return server;
+}

package/scripts/compiler/operations.mjs

@@ -0,0 +1,70 @@
+import { z } from "zod";
+
+export const upstream = Object.freeze({
+  repository: "https://github.com/changeroa/site-compiler",
+  verified_revision: "371849141ba68d12d578c804cc53fe7267c899b0",
+  verified_at: "2026-09-22",
+});
+
+const text = z.string().min(1).refine((value) => !value.includes("\0"), "must not contain NUL");
+const file = text.describe("Filesystem path; relative paths resolve from the SG caller's working directory.");
+const positive = z.number().int().positive();
+const url = z.url().refine((value) => ["http:", "https:"].includes(new URL(value).protocol), "use an HTTP or HTTPS URL");
+const optional = (shape) => Object.fromEntries(Object.entries(shape).map(([key, value]) => [key, value.optional()]));
+const viewport = { width: positive.max(16384), height: positive.max(16384), wait: z.number().int().min(0).max(60000) };
+const capture = { ...viewport, step: positive, quality: positive.max(100), grow: z.boolean() };
+const batch = { only: text, force: z.boolean(), parallel: positive.max(32), timeout_ms: positive };
+const model = { ...batch, model: text, timeout_ms: positive, stylegallery: file };
+const operation = (script, description, required, options = {}, paths = [], extra = {}) => ({
+  script, description, paths,
+  schema: z.strictObject({ ...required, ...optional(options), runner_timeout_ms: positive.max(21600000).optional() }),
+  ...extra,
+});
+
+// This registry owns both public transports. Upstream scripts remain in the
+// separately installed checkout and are never admitted as gallery material.
+export const compilerOperations = Object.freeze({
+  compile: operation("compile.mjs", "Capture a live website as scenes.json, scene frames, and mounted text. Writes to out; does not transcribe the frames.",
+    { url, out: file }, { ...viewport, substep: positive }, ["out"]),
+  timeline: operation("timeline.mjs", "Capture dense scroll frames and a pixel-difference curve. Writes timeline-curve.json and dense/ to out.",
+    { url, out: file }, { ...capture, max_height: positive }, ["out"]),
+  transcribe: operation("transcribe.mjs", "Transcribe captured packs into SceneBook and Timeline documents using the installed Claude CLI. May incur model usage. Inspect transcribe.json for per-pack outcomes.",
+    { in: file }, { ...model, image_budget: positive, phase: z.enum(["both", "scenebook", "timeline"]) }, ["in", "stylegallery"], { ledger: "transcribe.json" }),
+  sale: operation("sale-edition.mjs", "Generate a sale edition and a private copy audit from transcribed documents. Does not publish or establish rights clearance.",
+    { in: file, out: file }, { audit: file }, ["in", "out", "audit"]),
+  gate: operation("qa-gate.mjs", "Check capture/transcription consistency and optionally a sale edition. A failed gate returns a nonzero exit code; json optionally writes the report.",
+    { in: file }, { sale: file, json: file, max_gap_ratio: z.number().min(0).max(1), max_gaps_per_scene: z.number().int().min(0), static_score: z.number().min(0), high_score: z.number().min(0) }, ["in", "sale", "json"]),
+  build: operation("build.mjs", "Build package previews from sale editions with original-page and external-media access restricted. Not the faithful-reconstruction route. Uses the installed Claude CLI and may incur model usage. Inspect build.json for per-pack outcomes.",
+    { packs: file, out: file }, model, ["packs", "out", "stylegallery"], { ledger: "build.json" }),
+  shots: operation("shots.mjs", "Render built sites into desktop/mobile screenshots and a reduced-motion report under each build's shots/ directory.",
+    { slug: text, builds: file }, { steps: positive.max(1000) }, ["builds"]),
+  probe: operation("probe-scroll.mjs", "Inspect website scroll geometry with Chromium; chrome selects installed Chrome. Returns the upstream diagnostic log.",
+    { url }, { chrome: z.boolean() }, [], { positional: ["url"] }),
+  "batch-triage": operation("batch-triage.mjs", "Capture candidate sites for triage. Inspect runs.json for individual failures even when the process exits successfully.",
+    { candidates: file, out: file }, { ...batch, step: positive, wait: viewport.wait, quality: capture.quality, grow: z.boolean() }, ["candidates", "out"], { ledger: "runs.json" }),
+  triage: operation("triage.mjs", "Rank captured scroll curves and write a triage report. This is heuristic ranking, not product verification.",
+    { in: file }, { json: file, md: file, min_height: positive, pin_score: z.number().min(0), spike_score: z.number().min(0) }, ["in", "json", "md"]),
+  "batch-capture": operation("batch-capture.mjs", "Capture scenes and timelines for candidate sites. Inspect capture.json for per-pack outcomes.",
+    { candidates: file, out: file }, { ...batch, step: positive, quality: capture.quality }, ["candidates", "out"], { ledger: "capture.json" }),
+  "pack-status": operation("pack-status.mjs", "Update pack status, generating sale editions and running gates as needed. Writes status reports into in.",
+    { candidates: file, in: file }, { force: z.boolean() }, ["candidates", "in"]),
+  "pack-release": operation("pack-release.mjs", "Package products from the compiler checkout's out/packs and out/builds into out/release. Replaces matching release folders and ZIP files locally; does not upload or publish.",
+    { products: file }, { only: text }, ["products"]),
+});
+
+export const workflowSchema = z.strictObject({ document: z.enum(["workflow", "readme"]).default("workflow") });
+
+export function compilerToolDefinitions() {
+  return Object.entries(compilerOperations).map(([name, operation]) => {
+    const { $schema, ...inputSchema } = z.toJSONSchema(operation.schema);
+    return {
+      name, description: operation.description, inputSchema,
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    };
+  }).concat({
+    name: "workflow",
+    description: "Read the installed compiler's current workflow or README with revision and content hash, plus the SG component and motion contract routes.",
+    inputSchema: { type: "object", properties: { document: { type: "string", enum: ["workflow", "readme"], default: "workflow" } }, additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  });
+}

package/scripts/compiler/runtime.mjs

@@ -0,0 +1,156 @@
+import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compilerOperations, compilerToolDefinitions, upstream, workflowSchema } from "./operations.mjs";
+
+const galleryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const logLimit = 65536;
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const handoff = { consumer_reference: "consumer-reference/agent-native/registry.json" };
+
+export function failure(operation, code, message) {
+  return { ok: false, operation, failures: [{ code, message }] };
+}
+
+function compilerLocation(config) {
+  const configured = config.compilerRoot ?? process.env.SG_COMPILER_ROOT;
+  if (!configured) throw Object.assign(new Error("Set SG_COMPILER_ROOT to your site-compiler checkout, or pass --compiler-root to the CLI."), { code: "compiler_not_configured" });
+  const root = fs.realpathSync(path.resolve(config.cwd ?? process.cwd(), configured));
+  const manifest = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+  if (manifest.name !== "site-compiler") throw Object.assign(new Error("SG_COMPILER_ROOT must contain the site-compiler package."), { code: "compiler_invalid" });
+  const revision = spawnSync("git", ["-C", root, "rev-parse", "HEAD"], { encoding: "utf8", timeout: 5000 });
+  const gitRoot = spawnSync("git", ["-C", root, "rev-parse", "--show-toplevel"], { encoding: "utf8", timeout: 5000 });
+  const isCheckout = gitRoot.status === 0 && fs.realpathSync(gitRoot.stdout.trim()) === root;
+  const status = isCheckout ? spawnSync("git", ["-C", root, "status", "--porcelain", "--untracked-files=no"], { encoding: "utf8", timeout: 5000 }) : null;
+  const actualRevision = isCheckout && revision.status === 0 ? revision.stdout.trim() : null;
+  return {
+    root, package_version: manifest.version, revision: actualRevision,
+    tracked_changes: status?.status === 0 ? status.stdout.length > 0 : null,
+    matches_verified_revision: actualRevision === upstream.verified_revision && status?.status === 0 && status.stdout.length === 0,
+  };
+}
+
+export function compilerDiscovery(config = {}) {
+  let installation;
+  try { installation = { configured: true, ...compilerLocation(config) }; }
+  catch (error) { installation = { configured: false, code: error.code ?? "compiler_unavailable", message: error.message }; }
+  return {
+    ...upstream, installation,
+    operations: compilerToolDefinitions(),
+    contracts: ["design-engineering/component-contract.md", "motion/observed-choreography.md"],
+    ...handoff,
+  };
+}
+
+function checkedFile(root, name) {
+  const target = path.join(root, name);
+  if (fs.realpathSync(target) !== target || !fs.statSync(target).isFile()) {
+    throw Object.assign(new Error(`Compiler entry must be a regular file within its checkout: ${name}`), { code: "compiler_entry_invalid" });
+  }
+  return target;
+}
+
+function runProcess(script, args, { cwd, timeout, signal }) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve({ exit_code: null, signal: null, cancelled: true, timed_out: false, stdout: "", stderr: "" });
+    const child = spawn(process.execPath, [script, ...args], {
+      cwd, shell: false, detached: process.platform !== "win32", stdio: ["ignore", "pipe", "pipe"],
+    });
+    const logs = { stdout: Buffer.alloc(0), stderr: Buffer.alloc(0) };
+    const truncated = { stdout: false, stderr: false };
+    let timedOut = false;
+    let cancelled = false;
+    let spawnError;
+    let forceTimer;
+    const kill = (signalName) => {
+      try {
+        if (process.platform === "win32" && child.pid) {
+          spawnSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true, timeout: 5000 });
+        }
+        else if (child.pid) process.kill(-child.pid, signalName);
+      } catch (error) { if (error.code !== "ESRCH") spawnError ??= error.message; }
+    };
+    const stop = () => {
+      kill("SIGTERM");
+      forceTimer ??= setTimeout(() => kill("SIGKILL"), 1000);
+      forceTimer.unref();
+    };
+    const abort = () => { cancelled = true; stop(); };
+    const timer = setTimeout(() => { timedOut = true; stop(); }, timeout);
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
+    for (const channel of ["stdout", "stderr"]) child[channel].on("data", (chunk) => {
+      const combined = Buffer.concat([logs[channel], chunk]);
+      truncated[channel] ||= combined.length > logLimit;
+      logs[channel] = combined.subarray(Math.max(0, combined.length - logLimit));
+    });
+    child.on("error", (error) => { spawnError = error.message; });
+    child.on("close", (exitCode, exitSignal) => {
+      clearTimeout(timer);
+      if (forceTimer) { kill("SIGKILL"); clearTimeout(forceTimer); }
+      signal?.removeEventListener("abort", abort);
+      resolve({
+        exit_code: exitCode, signal: exitSignal, timed_out: timedOut, cancelled,
+        stdout: logs.stdout.toString("utf8"), stderr: logs.stderr.toString("utf8"),
+        stdout_truncated: truncated.stdout, stderr_truncated: truncated.stderr,
+        ...(spawnError ? { spawn_error: spawnError } : {}),
+      });
+    });
+  });
+}
+
+export async function executeCompiler(operation, input = {}, config = {}) {
+  const spec = Object.hasOwn(compilerOperations, operation) ? compilerOperations[operation] : null;
+  if (!spec && operation !== "workflow") return failure(operation, "command_unknown", `Unknown compiler command: ${operation}`);
+  const parsed = (operation === "workflow" ? workflowSchema : spec.schema).safeParse(input);
+  if (!parsed.success) return failure(operation, "input_invalid", parsed.error.message);
+  try {
+    const compiler = compilerLocation(config);
+    if (operation === "workflow") {
+      const name = parsed.data.document === "readme" ? "README.md" : "SKILL.md";
+      const bytes = fs.readFileSync(checkedFile(compiler.root, name));
+      return { ok: true, operation, result: { compiler, source: name, sha256: hash(bytes), text: bytes.toString("utf8"), contracts: compilerDiscovery(config).contracts, ...handoff } };
+    }
+    const script = checkedFile(compiler.root, spec.script);
+    const scriptHash = hash(fs.readFileSync(script));
+    const values = { ...parsed.data };
+    const timeout = values.runner_timeout_ms ?? 1800000;
+    delete values.runner_timeout_ms;
+    if (operation === "transcribe" || operation === "build") values.stylegallery ??= galleryRoot;
+    for (const key of spec.paths) if (values[key] !== undefined) values[key] = path.resolve(config.cwd ?? process.cwd(), values[key]);
+    if (operation === "sale") {
+      if (values.in === values.out) return failure(operation, "input_invalid", "sale requires a separate output directory.");
+      values.audit ??= path.join(path.dirname(values.out), "copy-audit.private.json");
+      const relative = path.relative(values.out, values.audit);
+      if (relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative))) {
+        return failure(operation, "input_invalid", "The private copy audit must be outside the sale directory.");
+      }
+    }
+    const args = [];
+    for (const key of spec.positional ?? []) args.push(values[key]);
+    for (const [key, value] of Object.entries(values)) {
+      if (spec.positional?.includes(key) || value === false) continue;
+      args.push(`--${key.replaceAll("_", "-")}`);
+      if (value !== true) args.push(String(value));
+    }
+    const execution = await runProcess(script, args, { cwd: compiler.root, timeout, signal: config.signal });
+    const ok = execution.exit_code === 0 && !execution.timed_out && !execution.cancelled && !execution.spawn_error;
+    const result = {
+      compiler, script: spec.script, script_sha256: scriptHash,
+      arguments: args, paths: Object.fromEntries(spec.paths.filter((key) => values[key] !== undefined).map((key) => [key, values[key]])),
+      ...execution, ...handoff,
+      ...(spec.ledger ? { ledger: path.join(values.out ?? values.in, spec.ledger), success_scope: "process_exit_only; inspect ledger for each pack" } : {}),
+      ...(operation === "pack-release" ? { output: path.join(compiler.root, "out/release") } : {}),
+    };
+    return {
+      ok, operation, result,
+      ...(!ok ? { failures: [{
+        code: execution.cancelled ? "compiler_cancelled" : execution.timed_out ? "compiler_timeout" : "compiler_failed",
+        message: execution.spawn_error ?? (execution.cancelled ? "Compiler execution cancelled." : execution.timed_out ? `Compiler exceeded ${timeout}ms.` : `Compiler exited with ${execution.exit_code ?? execution.signal}.`),
+      }] } : {}),
+    };
+  } catch (error) { return failure(operation, error.code ?? "compiler_unavailable", error.message); }
+}

package/scripts/sg-entry.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+try {
+  const { runSgCli } = await import("./compiler/cli.mjs");
+  const controller = new AbortController();
+  const cancel = () => controller.abort();
+  process.once("SIGINT", cancel);
+  process.once("SIGTERM", cancel);
+  try {
+    const result = await runSgCli(process.argv.slice(2), { signal: controller.signal });
+    process.stdout.write(result.output);
+    process.exitCode = result.exitCode;
+  } finally {
+    process.removeListener("SIGINT", cancel);
+    process.removeListener("SIGTERM", cancel);
+  }
+} catch (error) {
+  process.stdout.write(`${JSON.stringify({ ok: false, operation: null, failures: [{ code: error.code ?? "cli_failed", message: error.message }] }, null, 2)}\n`);
+  process.exitCode = 1;
+}

package/scripts/sg-server.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createSgMcpServer } from "./compiler/mcp.mjs";
+
+try {
+  const controller = new AbortController();
+  const server = createSgMcpServer({ signal: controller.signal });
+  const shutdown = () => {
+    controller.abort();
+    server.close().catch(() => {});
+  };
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+  process.stdin.once("end", shutdown);
+  await server.connect(new StdioServerTransport());
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}