@pixel-point/toolcraft 0.0.14 → 0.0.15

package/templates/starter/scripts/check-toolcraft-integrity.mjs

@@ -5,59 +5,18 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { validateIntegrityManifest } from "./toolcraft-integrity-manifest.mjs";
+import { getToolcraftContractDocIntegrityFailures } from "./toolcraft-contract-doc-integrity.mjs";
+import {
+  requiredPackageScriptNames,
+  requiredProtectedTrustRootFilePaths,
+  reservedGeneratedVerificationConfigPatterns,
+} from "./toolcraft-integrity-policy.mjs";
+
 const appRoot = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
+const platformOnly = process.argv.includes("--platform-only");
 const toolcraftRoot = path.join(appRoot, "src/toolcraft");
 const manifestPath = path.join(toolcraftRoot, ".toolcraft-manifest.json");
-const appSourceRoot = path.join(appRoot, "src/app");
-const routesSourceRoot = path.join(appRoot, "src/routes");
-const runtimeSurfaceComponentNames = [
-  "ToolcraftRoot",
-  "CanvasShell",
-  "ControlsPanel",
-  "LayersPanel",
-  "TimelinePanel",
-  "ToolbarPanel",
-];
-const runtimeSurfaceNamePattern = runtimeSurfaceComponentNames.join("|");
-const lowLevelRuntimeSurfaceImportPattern = new RegExp(
-  `import\\s*\\{[^}]*\\b(?:${runtimeSurfaceNamePattern})\\b[^}]*\\}\\s*from\\s*["'][^"']*runtime/react["']`,
-);
-const manualRuntimeSurfaceRenderPattern = new RegExp(
-  `<\\s*(?:(?:${runtimeSurfaceNamePattern})\\b|[A-Za-z_$][\\w$]*\\.(?:${runtimeSurfaceNamePattern})\\b)|React\\.createElement\\s*\\(\\s*(?:(?:${runtimeSurfaceNamePattern})\\b|[A-Za-z_$][\\w$]*\\.(?:${runtimeSurfaceNamePattern})\\b)`,
-);
-const builtInControlComponentNames = [
-  "ActionsControl",
-  "AnchorGridControl",
-  "ChannelMixerControl",
-  "CheckboxControl",
-  "CodeTextareaControl",
-  "ColorControl",
-  "ColorOpacityControl",
-  "CurvesControl",
-  "FileDropControl",
-  "FontPickerControl",
-  "GradientControl",
-  "ImagePickerControl",
-  "PaletteControl",
-  "PanelActionsControl",
-  "RangeInputControl",
-  "RangeSliderControl",
-  "SegmentedControl",
-  "SelectControl",
-  "SliderControl",
-  "SwitchControl",
-  "TextInputControl",
-  "VectorControl",
-];
-const builtInControlNamePattern = builtInControlComponentNames.join("|");
-const repoUiImportPattern = "@repo" + "/ui";
-const builtInControlImportSourcePattern = ["toolcraft/ui", repoUiImportPattern].join("|");
-const builtInControlImportPattern = new RegExp(
-  `import\\s*\\{[^}]*\\b(?:${builtInControlNamePattern})\\b[^}]*\\}\\s*from\\s*["'][^"']*(?:${builtInControlImportSourcePattern})[^"']*["']`,
-);
-const directBuiltInControlRenderPattern = new RegExp(
-  `<\\s*(?:(?:${builtInControlNamePattern})\\b|[A-Za-z_$][\\w$]*\\.(?:${builtInControlNamePattern})\\b)|React\\.createElement\\s*\\(\\s*(?:(?:${builtInControlNamePattern})\\b|[A-Za-z_$][\\w$]*\\.(?:${builtInControlNamePattern})\\b)`,
-);
 
 async function pathExists(filePath) {
   try {
@@ -73,42 +32,25 @@ async function hashFile(filePath) {
   return crypto.createHash("sha256").update(buffer).digest("hex");
 }
 
-async function collectFiles(rootDir) {
-  const files = [];
-
-  async function visit(currentDir) {
-    const entries = await fs.readdir(currentDir, { withFileTypes: true });
-
-    for (const entry of entries) {
-      const filePath = path.join(currentDir, entry.name);
-
-      if (entry.isDirectory()) {
-        await visit(filePath);
-        continue;
-      }
+function reportIntegrityFailures(failures) {
+  console.error("Toolcraft generated app integrity check failed.");
+  console.error(
+    "Do not edit src/toolcraft or framework-owned verification infrastructure in generated apps.",
+  );
+  console.error(
+    "Fix the source runtime in the monorepo, generate a fresh app folder, then move product-owned app source deliberately.",
+  );
 
-      if (entry.isFile() && entry.name !== ".toolcraft-manifest.json") {
-        files.push(path.relative(rootDir, filePath).split(path.sep).join("/"));
-      }
-    }
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
   }
 
-  await visit(rootDir);
-  return files.sort();
-}
-
-function stripJsComments(source) {
-  return source
-    .replace(/\/\*[\s\S]*?\*\//g, "")
-    .replace(/(^|[^:])\/\/.*$/gm, "$1");
+  process.exit(1);
 }
 
-async function collectSourceText(rootDir, { excludeTests = false } = {}) {
-  if (!(await pathExists(rootDir))) {
-    return "";
-  }
-
-  const chunks = [];
+async function collectToolcraftInventory(rootDir) {
+  const files = [];
+  const unsupportedEntries = [];
 
   async function visit(currentDir) {
     const entries = await fs.readdir(currentDir, { withFileTypes: true });
@@ -121,112 +63,167 @@ async function collectSourceText(rootDir, { excludeTests = false } = {}) {
         continue;
       }
 
-      if (!entry.isFile() || !/\.[cm]?[jt]sx?$/.test(entry.name)) {
+      if (entry.isFile() && entry.name !== ".toolcraft-manifest.json") {
+        files.push(path.relative(rootDir, filePath).split(path.sep).join("/"));
         continue;
       }
 
-      if (excludeTests && /\.(test|spec)\.[cm]?[jt]sx?$/.test(entry.name)) {
-        continue;
+      if (!entry.isFile()) {
+        unsupportedEntries.push(
+          path.relative(rootDir, filePath).split(path.sep).join("/"),
+        );
       }
-
-      chunks.push(await fs.readFile(filePath, "utf8"));
     }
   }
 
   await visit(rootDir);
-  return stripJsComments(chunks.join("\n"));
+  return {
+    files: files.sort(),
+    unsupportedEntries: unsupportedEntries.sort(),
+  };
+}
+
+if (!(await pathExists(toolcraftRoot))) {
+  reportIntegrityFailures([
+    "Missing generated Toolcraft source tree src/toolcraft.",
+  ]);
 }
 
 if (!(await pathExists(manifestPath))) {
-  console.log("Toolcraft integrity manifest not found; skipping copied source check.");
-  process.exit(0);
+  reportIntegrityFailures([
+    "Missing src/toolcraft/.toolcraft-manifest.json; generated apps must preserve the integrity manifest.",
+  ]);
 }
 
 const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
-const expectedFiles = new Map(
-  Object.entries(manifest.files ?? {}).map(([relativePath, hash]) => [
-    relativePath,
-    String(hash),
-  ]),
-);
-const actualFiles = await collectFiles(toolcraftRoot);
-const actualFileSet = new Set(actualFiles);
-const failures = [];
-const routesSource = await collectSourceText(routesSourceRoot, { excludeTests: true });
-const implementationSource = [
-  routesSource,
-  await collectSourceText(appSourceRoot, { excludeTests: true }),
-].join("\n");
-
-if (!/\bToolcraftApp\b/.test(implementationSource)) {
-  failures.push(
-    "app shell bypass: src/routes or src/app must render ToolcraftApp instead of replacing the Toolcraft runtime shell",
-  );
+const manifestValidation = validateIntegrityManifest({
+  appRoot,
+  manifest,
+  requiredPackageScriptNames,
+  requiredProtectedTrustRootFilePaths,
+  toolcraftRoot,
+});
+
+if (manifestValidation.failures.length > 0) {
+  reportIntegrityFailures(manifestValidation.failures);
 }
 
-if (lowLevelRuntimeSurfaceImportPattern.test(implementationSource)) {
-  failures.push(
-    "app shell bypass: app-specific source must not import low-level runtime surfaces; render ToolcraftApp and use schema, canvasContent, controlRenderers, onPanelAction, and runtime commands",
-  );
-}
+const {
+  expectedPackageScripts,
+  resolvedExpectedFiles,
+  resolvedProtectedFiles,
+} = manifestValidation;
 
-if (manualRuntimeSurfaceRenderPattern.test(implementationSource)) {
-  failures.push(
-    "app shell bypass: app-specific source must not render low-level runtime surfaces such as CanvasShell, ControlsPanel, TimelinePanel, LayersPanel, or ToolbarPanel directly",
-  );
-}
+const toolcraftInventory = await collectToolcraftInventory(toolcraftRoot);
+const actualFiles = toolcraftInventory.files;
+const actualFileSet = new Set(actualFiles);
+const failures = toolcraftInventory.unsupportedEntries.map(
+  (relativePath) => `unsupported Toolcraft entry ${relativePath}`,
+);
 
-if (builtInControlImportPattern.test(implementationSource)) {
-  failures.push(
-    "control bypass: app-specific source must not import built-in Toolcraft control components directly; declare schema controls or register a true custom controlRenderer",
-  );
+const rootEntries = await fs.readdir(appRoot, { withFileTypes: true });
+for (const entry of rootEntries) {
+  if (
+    reservedGeneratedVerificationConfigPatterns.some((pattern) =>
+      pattern.test(entry.name),
+    ) &&
+    !resolvedProtectedFiles.has(entry.name)
+  ) {
+    failures.push(`unapproved verification config ${entry.name}`);
+  }
 }
 
-if (directBuiltInControlRenderPattern.test(implementationSource)) {
-  failures.push(
-    "control bypass: app-specific source must not render built-in Toolcraft control components directly; declare schema controls or register a true custom controlRenderer",
+try {
+  const packageJson = JSON.parse(
+    await fs.readFile(path.join(appRoot, "package.json"), "utf8"),
   );
+  const actualPackageScripts = packageJson.scripts ?? {};
+
+  for (const [scriptName, expectedCommand] of expectedPackageScripts) {
+    if (actualPackageScripts[scriptName] !== expectedCommand) {
+      failures.push(`modified package script ${scriptName}`);
+    }
+  }
+
+  for (const scriptName of Object.keys(actualPackageScripts)) {
+    const lifecycleTarget = scriptName.startsWith("pre")
+      ? scriptName.slice("pre".length)
+      : scriptName.startsWith("post")
+        ? scriptName.slice("post".length)
+        : "";
+
+    if (
+      expectedPackageScripts.has(lifecycleTarget) &&
+      !expectedPackageScripts.has(scriptName)
+    ) {
+      failures.push(`added package lifecycle script ${scriptName}`);
+    }
+  }
+} catch {
+  failures.push("missing or invalid package.json");
 }
 
-if (/<\s*iframe\b|React\.createElement\s*\(\s*["']iframe["']/i.test(routesSource)) {
-  failures.push(
-    "app shell bypass: route files must not render a full-page iframe; preserve reference behavior inside ToolcraftApp canvasContent",
-  );
+if (!platformOnly) {
+  const {
+    evaluateToolcraftProductBoundary,
+    printToolcraftProductBoundaryResult,
+    toolcraftProductBoundaryPassed,
+  } = await import("./toolcraft-product-boundary.mjs");
+  const productBoundaryResult = await evaluateToolcraftProductBoundary({
+    protectedFilePaths: resolvedProtectedFiles.keys(),
+    rootDir: appRoot,
+  });
+
+  if (!toolcraftProductBoundaryPassed(productBoundaryResult)) {
+    const boundaryMessages = [];
+    printToolcraftProductBoundaryResult(productBoundaryResult, {
+      error(message) {
+        boundaryMessages.push(message.replace(/^- /u, ""));
+      },
+    });
+    failures.push(...boundaryMessages);
+  }
 }
 
-for (const relativePath of expectedFiles.keys()) {
+for (const [relativePath, { expectedHash, filePath }] of resolvedExpectedFiles) {
   if (!actualFileSet.has(relativePath)) {
     failures.push(`deleted ${relativePath}`);
     continue;
   }
 
-  const actualHash = await hashFile(path.join(toolcraftRoot, relativePath));
+  const actualHash = await hashFile(filePath);
 
-  if (actualHash !== expectedFiles.get(relativePath)) {
+  if (actualHash !== expectedHash) {
     failures.push(`modified ${relativePath}`);
   }
 }
 
 for (const relativePath of actualFiles) {
-  if (!expectedFiles.has(relativePath)) {
+  if (!resolvedExpectedFiles.has(relativePath)) {
     failures.push(`added ${relativePath}`);
   }
 }
 
-if (failures.length > 0) {
-  console.error("Toolcraft generated app integrity check failed.");
-  console.error(
-    "Do not edit src/toolcraft or replace the Toolcraft runtime shell in generated apps.",
-  );
-  console.error(
-    "Fix the app schema/source runtime in the monorepo, preserve ToolcraftApp, then regenerate.",
-  );
+for (const [relativePath, { expectedHash, filePath }] of resolvedProtectedFiles) {
+  if (!(await pathExists(filePath))) {
+    failures.push(`deleted ${relativePath}`);
+    continue;
+  }
 
-  for (const failure of failures) {
-    console.error(`- ${failure}`);
+  if ((await hashFile(filePath)) !== expectedHash) {
+    failures.push(`modified ${relativePath}`);
   }
+}
 
-  process.exit(1);
+failures.push(
+  ...(await getToolcraftContractDocIntegrityFailures({
+    appRoot,
+    protectedRelativePaths: resolvedProtectedFiles.keys(),
+  })),
+);
+
+if (failures.length > 0) {
+  reportIntegrityFailures(failures);
 }
 
 console.log(`Toolcraft integrity check passed (${actualFiles.length} files).`);

package/templates/starter/scripts/run-browser-performance.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+import { access, mkdir, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import spawn from "cross-spawn";
+
+import {
+  TOOLCRAFT_PERFORMANCE_RECEIPT_VERSION,
+  assertToolcraftVerificationInputsUnchanged,
+  clearToolcraftPerformanceReceipt,
+  collectToolcraftVerificationInputs,
+  getToolcraftPerformanceReceiptPath,
+} from "./toolcraft-verification-receipt.mjs";
+
+const projectDir = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+);
+const [, , ...requestedArguments] = process.argv;
+const unsupportedArguments = requestedArguments.filter(
+  (argument) => argument !== "--",
+);
+if (unsupportedArguments.length > 0) {
+  throw new Error(
+    `Toolcraft protected performance checkpoints do not accept Playwright arguments: ${unsupportedArguments.join(" ")}. Run Playwright directly for targeted diagnosis.`,
+  );
+}
+
+function getBinaryPath(name) {
+  return path.join(
+    projectDir,
+    "node_modules",
+    ".bin",
+    process.platform === "win32" ? `${name}.cmd` : name,
+  );
+}
+
+const playwrightBin = getBinaryPath("playwright");
+const tscBin = getBinaryPath("tsc");
+const viteBin = getBinaryPath("vite");
+
+const baselineInventory = await collectToolcraftVerificationInputs(projectDir);
+await clearToolcraftPerformanceReceipt(projectDir);
+
+await Promise.all([playwrightBin, tscBin, viteBin].map((filePath) => access(filePath)));
+
+function runBinary(binaryPath, args, env = process.env) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(binaryPath, args, { env, stdio: "inherit" });
+
+    child.on("error", reject);
+    child.on("exit", (code, signal) => {
+      if (signal) {
+        reject(new Error(`${path.basename(binaryPath)} exited after signal ${signal}.`));
+        return;
+      }
+      if (code !== 0) {
+        reject(new Error(`${path.basename(binaryPath)} exited with code ${code ?? 1}.`));
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+async function writeToolcraftPerformanceCheckpointReceipt(inventory) {
+  const receiptPath = getToolcraftPerformanceReceiptPath(projectDir);
+  const temporaryPath = `${receiptPath}.${process.pid}.tmp`;
+  await mkdir(path.dirname(receiptPath), { recursive: true });
+  await writeFile(
+    temporaryPath,
+    `${JSON.stringify(
+      {
+        completedAt: new Date().toISOString(),
+        files: inventory.entries,
+        kind: "performance-checkpoint",
+        runner: "playwright-fallback",
+        sourceHash: inventory.sourceHash,
+        status: "passed",
+        version: TOOLCRAFT_PERFORMANCE_RECEIPT_VERSION,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  await rename(temporaryPath, receiptPath);
+}
+
+await runBinary(tscBin, ["-p", "tsconfig.json", "--noEmit"]);
+await runBinary(viteBin, ["build"]);
+assertToolcraftVerificationInputsUnchanged({
+  baseline: baselineInventory,
+  current: await collectToolcraftVerificationInputs(projectDir),
+  phase: "during the production build",
+});
+await runBinary(playwrightBin, ["install", "chromium"]);
+await runBinary(
+  playwrightBin,
+  [
+    "test",
+    "--grep",
+    "browser perf:",
+    "--workers=1",
+  ],
+  {
+    ...process.env,
+    TOOLCRAFT_BROWSER_SERVER_MODE: "preview",
+  },
+);
+const verifiedInventory = await collectToolcraftVerificationInputs(projectDir);
+assertToolcraftVerificationInputsUnchanged({
+  baseline: baselineInventory,
+  current: verifiedInventory,
+  phase: "during Playwright",
+});
+await writeToolcraftPerformanceCheckpointReceipt(verifiedInventory);

package/templates/starter/scripts/run-browser-performance.test.mjs

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const scriptsDir = path.dirname(fileURLToPath(import.meta.url));
+const projectDir = path.dirname(scriptsDir);
+const runnerPath = path.join(scriptsDir, "run-browser-performance.mjs");
+
+test("protected performance runner rejects Playwright filters before launching tools", () => {
+  const receiptPath = path.join(
+    projectDir,
+    ".toolcraft",
+    "verification",
+    "performance.json",
+  );
+  const hadReceipt = existsSync(receiptPath);
+  const originalReceipt = hadReceipt ? readFileSync(receiptPath) : undefined;
+  const sentinelReceipt = Buffer.from("protected receipt sentinel\n");
+  mkdirSync(path.dirname(receiptPath), { recursive: true });
+  writeFileSync(receiptPath, sentinelReceipt);
+
+  try {
+    const result = spawnSync(
+      process.execPath,
+      [runnerPath, "e2e/app-performance.spec.ts"],
+      {
+        cwd: projectDir,
+        encoding: "utf8",
+        timeout: 5_000,
+      },
+    );
+
+    assert.equal(result.signal, null);
+    assert.notEqual(result.status, 0);
+    assert.match(
+      `${result.stdout}\n${result.stderr}`,
+      /do not accept Playwright arguments.*app-performance\.spec\.ts/iu,
+    );
+    assert.deepEqual(readFileSync(receiptPath), sentinelReceipt);
+  } finally {
+    if (originalReceipt) writeFileSync(receiptPath, originalReceipt);
+    else rmSync(receiptPath, { force: true });
+  }
+});