@skenora/tooling 0.1.2

package/README.md

@@ -0,0 +1,32 @@
+# @skenora/tooling
+
+Offline developer tooling and MCP adapters for Skenora. The package owns the
+`skenora` CLI, versioned documentation/example/schema resources, static scene
+checks, Node/browser doctor reports, a read-only stdio/loopback-HTTP server,
+and transport-neutral MCP handlers with optional host-injected ScenePlan tools.
+
+It is deliberately not a dependency of browser products or Runtime. Run
+`skenora --help` after installing the package.
+
+The installed immutable gallery is available through `skenora examples
+list|search|show|pull`. The default MCP exposes list/search/get/source without
+filesystem mutation; only the CLI `pull` command writes. All manifests and
+source artifacts are verified against the package-versioned resource hash.
+
+Use `skenora mcp` for stdio or `skenora mcp --transport http` for a read-only
+loopback Web MCP. Applications can import `@skenora/tooling/mcp` and
+`@skenora/tooling/mcp/http` to inject an authenticated, handle-scoped
+`ScenePlanGateway` adapter. Authoring composition requires an explicit
+authorization callback; HTTP additionally requires authentication. Write
+authorization receives a canonical plan hash and revision/idempotency intent,
+and scene inspection returns a revision-bound paginated safe outline. See the
+[Web MCP guide](https://github.com/zhangjiadi225/skenora/blob/main/docs/WEB_MCP.md).
+
+`@skenora/tooling/wgsl` is an isolated optional audience that reflects trusted
+MaterialProgram-generated WGSL with `@vgpu/wgsl` and can validate it with a
+caller-supplied WebGPU device. `skenora wgsl inspect` runs the parser/reflection
+half and therefore reports `unverified` until a device participates.
+
+Repository maintainers run `pnpm check:tooling-resources` for manifest drift.
+After an intentional resource edit, `pnpm baseline:tooling-resources` updates
+hashes and the package version; unlisted or missing resource files still fail.

package/bin/skenora-mcp-http.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+import { createServer } from "node:http";
+import { pathToFileURL } from "node:url";
+import {
+  createSkenoraMcpHttpHandler,
+  createSkenoraMcpServer,
+} from "../dist/index.js";
+
+export async function runMcpHttpServer(options = {}) {
+  const hostname = options.hostname ?? "127.0.0.1";
+  const port = options.port ?? 8787;
+  const path = options.path ?? "/mcp";
+  const maxBodyBytes = options.maxBodyBytes ?? 1024 * 1024;
+  const mcp = options.server ?? createSkenoraMcpServer();
+  const handler = createSkenoraMcpHttpHandler(mcp, {
+    path,
+    maxBodyBytes,
+    allowedHosts: options.allowedHosts ?? [hostname, "localhost"],
+    ...(options.allowedOrigins
+      ? { allowedOrigins: options.allowedOrigins }
+      : {}),
+    ...(options.authenticate ? { authenticate: options.authenticate } : {}),
+    ...(options.authorizationMetadataUrl
+      ? { authorizationMetadataUrl: options.authorizationMetadataUrl }
+      : {}),
+  });
+  const http = createServer(async (request, response) => {
+    const disconnected = new AbortController();
+    const abortRequest = () => disconnected.abort();
+    const abortResponse = () => {
+      if (!response.writableEnded) disconnected.abort();
+    };
+    request.once("aborted", abortRequest);
+    response.once("close", abortResponse);
+    try {
+      const body = await readBody(request, maxBodyBytes);
+      const host = request.headers.host ?? `${hostname}:${port}`;
+      const method = request.method ?? "GET";
+      const webRequest = new Request(`http://${host}${request.url ?? "/"}`, {
+        method,
+        headers: toWebHeaders(request.headers),
+        signal: disconnected.signal,
+        ...(body.length === 0 || method === "GET" || method === "HEAD"
+          ? {}
+          : { body }),
+      });
+      const webResponse = await handler(webRequest);
+      response.statusCode = webResponse.status;
+      for (const [name, value] of webResponse.headers) {
+        response.setHeader(name, value);
+      }
+      response.end(Buffer.from(await webResponse.arrayBuffer()));
+    } catch (error) {
+      response.statusCode =
+        error instanceof RequestBodyTooLargeError ? 413 : 500;
+      response.setHeader("content-type", "text/plain; charset=utf-8");
+      response.end(
+        error instanceof RequestBodyTooLargeError
+          ? "Request body too large\n"
+          : "Internal error\n",
+      );
+    } finally {
+      request.off("aborted", abortRequest);
+      response.off("close", abortResponse);
+    }
+  });
+  await new Promise((resolve, reject) => {
+    http.once("error", reject);
+    http.listen(port, hostname, () => {
+      http.off("error", reject);
+      resolve();
+    });
+  });
+  process.stderr.write(
+    `Skenora MCP listening on http://${hostname}:${port}${path}\n`,
+  );
+  return http;
+}
+
+function readBody(request, maxBodyBytes) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let bytes = 0;
+    let settled = false;
+    const onData = (chunk) => {
+      if (settled) return;
+      bytes += chunk.length;
+      if (bytes > maxBodyBytes) {
+        settled = true;
+        chunks.length = 0;
+        request.off("data", onData);
+        request.resume();
+        reject(new RequestBodyTooLargeError());
+        return;
+      }
+      chunks.push(chunk);
+    };
+    request.on("data", onData);
+    request.on("end", () => {
+      if (settled) return;
+      settled = true;
+      resolve(Buffer.concat(chunks));
+    });
+    request.on("error", (error) => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    });
+  });
+}
+
+class RequestBodyTooLargeError extends Error {}
+
+function toWebHeaders(input) {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(input)) {
+    if (Array.isArray(value)) {
+      for (const item of value) headers.append(name, item);
+    } else if (value !== undefined) {
+      headers.set(name, value);
+    }
+  }
+  return headers;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  await runMcpHttpServer();
+}

package/bin/skenora-mcp.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { createInterface } from "node:readline";
+import { pathToFileURL } from "node:url";
+import {
+  SKENORA_MCP_LEGACY_PROTOCOL_VERSION,
+  SKENORA_MCP_PROTOCOL_VERSION,
+  createSkenoraMcpErrorResponse,
+  createSkenoraMcpServer,
+  getSkenoraMcpRequestProtocolVersion,
+} from "../dist/index.js";
+
+export async function runMcpServer(options = {}) {
+  const server = options.server ?? createSkenoraMcpServer();
+  const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  let protocolVersion;
+  for await (const line of lines) {
+    if (!line.trim()) continue;
+    let request;
+    try {
+      request = JSON.parse(line);
+    } catch {
+      write(createSkenoraMcpErrorResponse(null, -32700, "Parse error"));
+      continue;
+    }
+    protocolVersion ??= selectOpeningProtocolVersion(request);
+    const response = await server.handle(request, {
+      transport: "stdio",
+      protocolVersion,
+    });
+    if (response) write(response);
+  }
+}
+
+function selectOpeningProtocolVersion(request) {
+  const claimed = getSkenoraMcpRequestProtocolVersion(request);
+  return request?.method === "server/discover" || claimed !== undefined
+    ? SKENORA_MCP_PROTOCOL_VERSION
+    : SKENORA_MCP_LEGACY_PROTOCOL_VERSION;
+}
+
+function write(value) {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  await runMcpServer();
+}

package/bin/skenora.mjs

@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve } from "node:path";
+import { stdin, stdout } from "node:process";
+import {
+  checkSceneInput,
+  createDoctorReport,
+  getInstalledSkenoraExample,
+  getInstalledSkenoraExampleSource,
+  getToolingResource,
+  listInstalledSkenoraExamples,
+  listToolingResources,
+  searchInstalledSkenoraExamples,
+  searchToolingResources,
+  verifyToolingResources,
+} from "../dist/index.js";
+
+const args = process.argv.slice(2);
+const json = takeFlag(args, "--json");
+const command = args.shift();
+
+try {
+  switch (command) {
+    case "check":
+      await runCheck(args, json);
+      break;
+    case "doctor":
+      await runDoctor(args, json);
+      break;
+    case "docs":
+      await runResources(args, "documentation", json);
+      break;
+    case "examples":
+      await runExamples(args, json);
+      break;
+    case "resources":
+      await runResourceMaintenance(args, json);
+      break;
+    case "wgsl":
+      await runWgsl(args, json);
+      break;
+    case "mcp": {
+      await runMcp(args);
+      break;
+    }
+    case "help":
+    case "--help":
+    case "-h":
+    case undefined:
+      stdout.write(helpText());
+      break;
+    default:
+      throw new CliError(`Unknown command: ${command}`, 64);
+  }
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (json) stdout.write(`${JSON.stringify({ error: message }, null, 2)}\n`);
+  else process.stderr.write(`skenora: ${message}\n`);
+  process.exitCode = error instanceof CliError ? error.exitCode : 1;
+}
+
+async function runCheck(commandArgs, asJson) {
+  const inputPath = commandArgs.shift();
+  if (!inputPath || commandArgs.length)
+    throw new CliError("Usage: skenora check <file|-> [--json]", 64);
+  const text =
+    inputPath === "-" ? await readStdin() : await readFile(inputPath, "utf8");
+  const report = checkSceneInput(text);
+  output(report, asJson, formatCheckReport);
+  if (report.status === "invalid") process.exitCode = 1;
+}
+
+async function runDoctor(commandArgs, asJson) {
+  const reportFlag = takeOption(commandArgs, "--probe-report");
+  if (commandArgs.length)
+    throw new CliError(
+      "Usage: skenora doctor [--probe-report <file>] [--json]",
+      64,
+    );
+  const probe = reportFlag
+    ? JSON.parse(await readFile(reportFlag, "utf8"))
+    : undefined;
+  const report = createDoctorReport(probe);
+  output(report, asJson, formatDoctorReport);
+  process.exitCode =
+    report.verdict === "healthy" ? 0 : report.verdict === "unhealthy" ? 1 : 2;
+}
+
+async function runResources(commandArgs, kind, asJson) {
+  const action = commandArgs.shift() ?? "list";
+  if (action === "list") {
+    if (commandArgs.length)
+      throw new CliError(
+        `Usage: skenora ${kind === "example" ? "examples" : "docs"} list`,
+        64,
+      );
+    const entries = await listToolingResources(kind);
+    output(
+      entries,
+      asJson,
+      (items) =>
+        `${items.map((entry) => `${entry.id}\t${entry.title}`).join("\n")}\n`,
+    );
+    return;
+  }
+  if (action === "get") {
+    const id = commandArgs.shift();
+    if (!id || commandArgs.length)
+      throw new CliError("A single resource ID is required", 64);
+    const resource = await getToolingResource(id);
+    if (resource.entry.kind !== kind)
+      throw new CliError(`Resource ${id} is not a ${kind} resource`, 64);
+    output(resource, asJson, (value) => value.text);
+    return;
+  }
+  if (action === "search") {
+    const query = commandArgs.join(" ").trim();
+    if (!query) throw new CliError("A search query is required", 64);
+    const entries = await searchToolingResources(query, { kind });
+    output(
+      entries,
+      asJson,
+      (items) =>
+        `${items.map((entry) => `${entry.id}\t${entry.title}`).join("\n")}\n`,
+    );
+    return;
+  }
+  throw new CliError(`Unknown resource action: ${action}`, 64);
+}
+
+async function runExamples(commandArgs, asJson) {
+  const action = commandArgs.shift() ?? "list";
+  if (action === "list") {
+    if (commandArgs.length)
+      throw new CliError("Usage: skenora examples list [--json]", 64);
+    const examples = await listInstalledSkenoraExamples();
+    output(examples, asJson, formatExampleList);
+    return;
+  }
+  if (action === "search") {
+    const query = commandArgs.join(" ").trim();
+    if (!query) throw new CliError("A search query is required", 64);
+    const examples = await searchInstalledSkenoraExamples(query);
+    output(examples, asJson, formatExampleList);
+    return;
+  }
+  if (action === "show" || action === "get") {
+    const id = commandArgs.shift();
+    if (!id || commandArgs.length)
+      throw new CliError("A single example ID is required", 64);
+    const example = await getInstalledSkenoraExample(id);
+    output(example, asJson, (value) => `${JSON.stringify(value, null, 2)}\n`);
+    return;
+  }
+  if (action === "pull") {
+    const id = commandArgs.shift();
+    const out = takeOption(commandArgs, "--out");
+    if (!id || !out || commandArgs.length)
+      throw new CliError(
+        "Usage: skenora examples pull <id> --out <directory>",
+        64,
+      );
+    const example = await getInstalledSkenoraExample(id);
+    const destination = resolve(out);
+    if (await stat(destination).catch(() => undefined))
+      throw new CliError(`Output directory already exists: ${destination}`, 73);
+    await mkdir(destination, { recursive: true });
+    await writeFile(
+      resolve(destination, "manifest.json"),
+      `${JSON.stringify(example.manifest, null, 2)}\n`,
+      "utf8",
+    );
+    for (const source of example.sources) {
+      const target = resolve(destination, source.path);
+      const fromDestination = relative(destination, target);
+      if (
+        fromDestination === "" ||
+        fromDestination === ".." ||
+        fromDestination.startsWith(`..${pathSeparator()}`)
+      )
+        throw new Error(`Unsafe installed example path: ${source.path}`);
+      const content = await getInstalledSkenoraExampleSource(
+        example.manifest.id,
+        source.path,
+      );
+      await mkdir(dirname(target), { recursive: true });
+      await writeFile(
+        target,
+        content.encoding === "utf8"
+          ? content.content
+          : Buffer.from(content.content, "base64"),
+      );
+    }
+    output(
+      {
+        id: example.manifest.id,
+        directory: destination,
+        files: example.sources.length + 1,
+      },
+      asJson,
+      (value) =>
+        `Pulled ${value.id} to ${value.directory} (${value.files} files).\n`,
+    );
+    return;
+  }
+  throw new CliError(`Unknown example action: ${action}`, 64);
+}
+
+async function runResourceMaintenance(commandArgs, asJson) {
+  const action = commandArgs.shift();
+  if (action !== "verify" || commandArgs.length)
+    throw new CliError("Usage: skenora resources verify [--json]", 64);
+  const report = await verifyToolingResources();
+  output(report, asJson, (value) =>
+    value.valid
+      ? `Verified ${value.checked} tooling resources.\n`
+      : `Resource verification failed:\n${value.failures
+          .map(
+            (failure) =>
+              `- ${failure.id}: ${failure.actual} != ${failure.expected}`,
+          )
+          .join("\n")}\n`,
+  );
+  if (!report.valid) process.exitCode = 1;
+}
+
+async function runWgsl(commandArgs, asJson) {
+  const action = commandArgs.shift();
+  const inputPath = commandArgs.shift();
+  if (action !== "inspect" || !inputPath || commandArgs.length)
+    throw new CliError(
+      "Usage: skenora wgsl inspect <material-program.json> [--json]",
+      64,
+    );
+  const input = JSON.parse(await readFile(inputPath, "utf8"));
+  const { inspectMaterialProgramWgsl } = await import("../dist/wgsl.js");
+  const report = await inspectMaterialProgramWgsl(input);
+  output(report, asJson, (value) => {
+    const lines = [
+      `${value.status.toUpperCase()} parser=${value.parser} device=${value.deviceValidation}`,
+      ...value.diagnostics.map(
+        (diagnostic) =>
+          `[${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`,
+      ),
+    ];
+    return `${lines.join("\n")}\n`;
+  });
+  process.exitCode =
+    report.status === "valid" ? 0 : report.status === "invalid" ? 1 : 2;
+}
+
+async function runMcp(commandArgs) {
+  const transport = takeOption(commandArgs, "--transport") ?? "stdio";
+  if (transport === "stdio") {
+    if (commandArgs.length) {
+      throw new CliError("Usage: skenora mcp [--transport stdio]", 64);
+    }
+    const { runMcpServer } = await import("./skenora-mcp.mjs");
+    await runMcpServer();
+    return;
+  }
+  if (transport === "http") {
+    const portValue = takeOption(commandArgs, "--port");
+    const path = takeOption(commandArgs, "--path") ?? "/mcp";
+    if (commandArgs.length) {
+      throw new CliError(
+        "Usage: skenora mcp --transport http [--port <number>] [--path </mcp>]",
+        64,
+      );
+    }
+    const port = portValue === undefined ? 8787 : Number(portValue);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new CliError("MCP HTTP port must be an integer in 1..65535", 64);
+    }
+    const { runMcpHttpServer } = await import("./skenora-mcp-http.mjs");
+    await runMcpHttpServer({ port, path });
+    return;
+  }
+  throw new CliError(`Unknown MCP transport: ${transport}`, 64);
+}
+
+function output(value, asJson, format) {
+  stdout.write(asJson ? `${JSON.stringify(value, null, 2)}\n` : format(value));
+}
+
+function formatCheckReport(report) {
+  const lines = [
+    `${report.status.toUpperCase()} ${report.inputKind} (${report.source})`,
+    `entities=${report.summary.entities} materials=${report.summary.materials} resources=${report.summary.resources} compiled=${report.summary.compiled}`,
+  ];
+  for (const diagnostic of report.diagnostics) {
+    lines.push(
+      `[${diagnostic.severity}] ${diagnostic.code} ${formatPath(diagnostic.path)}: ${diagnostic.message}`,
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function formatDoctorReport(report) {
+  const lines = [
+    `${report.verdict.toUpperCase()} runtime=${report.environment.runtime}`,
+  ];
+  for (const diagnostic of report.diagnostics) {
+    lines.push(
+      `[${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`,
+    );
+    if (diagnostic.repair) lines.push(`  repair: ${diagnostic.repair}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function formatExampleList(examples) {
+  return `${examples
+    .map(
+      ({ manifest }) =>
+        `${manifest.id}\t${manifest.mode}\t${manifest.tier}\t${manifest.title}`,
+    )
+    .join("\n")}\n`;
+}
+
+function pathSeparator() {
+  return process.platform === "win32" ? "\\" : "/";
+}
+
+function formatPath(path) {
+  if (!path?.length) return "$";
+  return path.reduce(
+    (value, segment) =>
+      typeof segment === "number"
+        ? `${value}[${segment}]`
+        : `${value}.${segment}`,
+    "$",
+  );
+}
+
+function takeFlag(values, flag) {
+  const index = values.indexOf(flag);
+  if (index < 0) return false;
+  values.splice(index, 1);
+  return true;
+}
+
+function takeOption(values, flag) {
+  const index = values.indexOf(flag);
+  if (index < 0) return undefined;
+  const value = values[index + 1];
+  if (!value || value.startsWith("--"))
+    throw new CliError(`${flag} requires a value`, 64);
+  values.splice(index, 2);
+  return value;
+}
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let value = "";
+    stdin.setEncoding("utf8");
+    stdin.on("data", (chunk) => (value += chunk));
+    stdin.on("end", () => resolve(value));
+    stdin.on("error", reject);
+  });
+}
+
+function helpText() {
+  return `Skenora developer tooling
+
+Usage:
+  skenora check <file|-> [--json]
+  skenora doctor [--probe-report <file>] [--json]
+  skenora docs <list|get|search> [value] [--json]
+  skenora examples list [--json]
+  skenora examples search <query> [--json]
+  skenora examples show <id> [--json]
+  skenora examples pull <id> --out <directory> [--json]
+  skenora resources verify [--json]
+  skenora wgsl inspect <material-program.json> [--json]
+  skenora mcp [--transport stdio]
+  skenora mcp --transport http [--port <number>] [--path </mcp>]
+
+Exit codes: 0 success/healthy, 1 invalid/unhealthy, 2 unverified, 64 usage.
+`;
+}
+
+class CliError extends Error {
+  constructor(message, exitCode) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}

package/dist/doctor.d.ts

@@ -0,0 +1,3 @@
+import { type SkenoraDoctorReport } from "@skenora/contracts";
+export declare function createDoctorReport(probe?: unknown): SkenoraDoctorReport;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,mBAAmB,EACzB,MAAM,oBAAoB,CAAC;AAE5B,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,mBAAmB,CAqCvE"}