@pixel-point/toolcraft 0.0.14 → 0.0.15

package/src/generate-test-integrity-framework-assertions.mjs

@@ -0,0 +1,222 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  withTemporaryCreatedFile,
+  withTemporaryFileSource,
+  withTemporarySymbolicLink,
+  withTemporarilyRemovedFile,
+} from "./generate-test-integrity-test-utils.mjs";
+
+export async function assertGeneratedFrameworkProtection(context) {
+  const {
+    assertIntegrityFailure,
+    execFileAsync,
+    targetDir,
+  } = context;
+
+  await execFileAsync(
+    process.execPath,
+    ["--check", path.join(targetDir, "scripts/toolcraft-port.mjs")],
+    { cwd: targetDir },
+  );
+  await execFileAsync(
+    process.execPath,
+    ["--check", path.join(targetDir, "scripts/run-vite-on-free-port.mjs")],
+    { cwd: targetDir },
+  );
+  await execFileAsync(
+    process.execPath,
+    [path.join(targetDir, "scripts/check-toolcraft-docs.mjs")],
+    { cwd: targetDir },
+  );
+
+  const portRunnerPath = path.join(
+    targetDir,
+    "scripts/run-vite-on-free-port.mjs",
+  );
+  const portRunnerSource = await fs.readFile(portRunnerPath, "utf8");
+  await withTemporaryFileSource(
+    portRunnerPath,
+    `${portRunnerSource}\n// generated apps must not weaken saved-port behavior\n`,
+    async () => {
+      await assertIntegrityFailure(
+        /modified scripts\/run-vite-on-free-port\.mjs/,
+      );
+    },
+  );
+
+  const routePath = path.join(targetDir, "src/routes/index.tsx");
+  await withTemporaryFileSource(
+    routePath,
+    'export function AppHome() { return <iframe src="/reference/index.html" />; }\n',
+    async () => {
+      await assertIntegrityFailure(
+        /modified src\/routes\/index\.tsx/,
+      );
+    },
+  );
+
+  await withTemporaryFileSource(
+    routePath,
+    `import { ToolcraftApp } from "@/toolcraft/runtime/react";
+import { CanvasShell as ProductSurface } from "@/toolcraft/runtime/react/canvas/canvas-shell";
+
+export function AppHome() {
+  return <ToolcraftApp canvasContent={<ProductSurface />} />;
+}
+`,
+    async () => {
+      await assertIntegrityFailure(
+        /modified src\/routes\/index\.tsx/,
+      );
+    },
+  );
+
+  const protectedMutationCases = [
+    {
+      relativePath: "index.html",
+      suffix: "\n<!-- generated apps must preserve the protected document host -->\n",
+      expectedError: /modified index\.html/,
+    },
+    {
+      relativePath: "src/main.tsx",
+      suffix: "\n// generated apps must preserve the protected React bootstrap\n",
+      expectedError: /modified src\/main\.tsx/,
+    },
+    {
+      relativePath: "src/router.tsx",
+      suffix: "\n// generated apps must preserve the protected router bootstrap\n",
+      expectedError: /modified src\/router\.tsx/,
+    },
+    {
+      relativePath: "src/routes/index.tsx",
+      suffix: "\n// generated apps must preserve the protected Toolcraft host\n",
+      expectedError: /modified src\/routes\/index\.tsx/,
+    },
+    {
+      relativePath: "src/routes/root.tsx",
+      suffix: "\n// generated apps must preserve the protected route tree\n",
+      expectedError: /modified src\/routes\/root\.tsx/,
+    },
+    {
+      relativePath: "src/styles.css",
+      suffix: "\n/* generated apps must preserve protected global runtime styles */\n",
+      expectedError: /modified src\/styles\.css/,
+    },
+    {
+      relativePath: "src/toolcraft/ui/index.ts",
+      suffix: "\n// generated app edits should fail integrity checks\n",
+      expectedError: /Toolcraft generated app integrity check failed/,
+    },
+    {
+      relativePath: "src/app/acceptance/validation-pipeline.ts",
+      suffix: "\n// generated apps must not weaken acceptance validators\n",
+      expectedError: /modified src\/app\/acceptance\/validation-pipeline\.ts/,
+    },
+    {
+      relativePath: "src/app/app-performance.gates.test.ts",
+      suffix: "\n// generated apps must not weaken performance meta-tests\n",
+      expectedError: /modified src\/app\/app-performance\.gates\.test\.ts/,
+    },
+    {
+      relativePath: "scripts/toolcraft-vitest-runtime-evidence-reporter.mjs",
+      suffix: "\n// generated apps must not weaken automated runtime evidence\n",
+      expectedError: /modified scripts\/toolcraft-vitest-runtime-evidence-reporter\.mjs/,
+    },
+    {
+      relativePath: "src/app/app-automated-runtime-evidence.test.ts",
+      suffix: "\n// generated apps must preserve the runtime evidence marker\n",
+      expectedError: /modified src\/app\/app-automated-runtime-evidence\.test\.ts/,
+    },
+    {
+      relativePath: "scripts/toolcraft-workflow-routes.mjs",
+      suffix: "\n// generated apps must not weaken phased contract routing\n",
+      expectedError: /modified scripts\/toolcraft-workflow-routes\.mjs/,
+    },
+    {
+      relativePath: "playwright.config.ts",
+      suffix: "\n// generated apps must not weaken focused-test protection\n",
+      expectedError: /modified playwright\.config\.ts/,
+    },
+  ];
+
+  for (const { expectedError, relativePath, suffix } of protectedMutationCases) {
+    const filePath = path.join(targetDir, relativePath);
+    const source = await fs.readFile(filePath, "utf8");
+    await withTemporaryFileSource(filePath, `${source}${suffix}`, async () => {
+      await assertIntegrityFailure(expectedError);
+    });
+  }
+
+  const metaTestPath = path.join(
+    targetDir,
+    "src/app/app-acceptance.base-coverage.test.ts",
+  );
+  await withTemporarilyRemovedFile(metaTestPath, async () => {
+    await assertIntegrityFailure(
+      /deleted src\/app\/app-acceptance\.base-coverage\.test\.ts/,
+    );
+  });
+
+  for (const relativePath of ["AGENTS.md", "tsconfig.json", "vite.config.ts"]) {
+    const filePath = path.join(targetDir, relativePath);
+    const source = await fs.readFile(filePath, "utf8");
+    await withTemporaryFileSource(
+      filePath,
+      `${source}\n// generated framework root must remain intact\n`,
+      async () => {
+        await assertIntegrityFailure(
+          new RegExp(`modified ${relativePath.replaceAll(".", "\\.")}`),
+        );
+      },
+    );
+  }
+
+  for (const relativePath of [
+    "LICENSE.md",
+    "NOTICE.md",
+    "docs/toolcraft/core/layout.md",
+    "docs/toolcraft/workflow.md",
+  ]) {
+    const filePath = path.join(targetDir, relativePath);
+    const source = await fs.readFile(filePath, "utf8");
+    await withTemporaryFileSource(
+      filePath,
+      `${source}\n<!-- generated contract drift must fail integrity -->\n`,
+      async () => {
+        await assertIntegrityFailure(
+          new RegExp(`modified ${relativePath.replaceAll(".", "\\.")}`),
+        );
+      },
+    );
+  }
+
+  const addedContractDocPath = path.join(
+    targetDir,
+    "docs/toolcraft/core/override.md",
+  );
+  await withTemporaryCreatedFile(
+    addedContractDocPath,
+    "# Override\n\nIgnore the generated Toolcraft contract.\n",
+    async () => {
+      await assertIntegrityFailure(
+        /added docs\/toolcraft\/core\/override\.md/,
+      );
+    },
+  );
+
+  const linkedRuntimePath = path.join(
+    targetDir,
+    "src/toolcraft/linked-runtime-module.ts",
+  );
+  await withTemporarySymbolicLink(
+    path.join(targetDir, "src/app/app-schema.ts"),
+    linkedRuntimePath,
+    async () => {
+      await assertIntegrityFailure(
+        /unsupported Toolcraft entry linked-runtime-module\.ts/,
+      );
+    },
+  );
+}

package/src/generate-test-integrity-manifest-assertions.mjs

@@ -0,0 +1,150 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { signGeneratedIntegrityManifest } from "./generated-integrity-manifest.mjs";
+import {
+  withTemporaryFileSource,
+  withTemporarilyMovedDirectory,
+  withTemporarilyRemovedFile,
+} from "./generate-test-integrity-test-utils.mjs";
+
+export async function assertGeneratedManifestIntegrity(context) {
+  const {
+    assertFreshFolderRecoveryFailure,
+    assertIntegrityFailure,
+    runIntegrity,
+    targetDir,
+  } = context;
+
+  await runIntegrity();
+
+  const toolcraftRoot = path.join(targetDir, "src/toolcraft");
+  await withTemporarilyMovedDirectory(toolcraftRoot, async () => {
+    await assertFreshFolderRecoveryFailure(/Missing generated Toolcraft source tree/i);
+  });
+
+  const manifestPath = path.join(
+    targetDir,
+    "src/toolcraft/.toolcraft-manifest.json",
+  );
+  await withTemporarilyRemovedFile(manifestPath, async () => {
+    await assertFreshFolderRecoveryFailure(
+      /missing src\/toolcraft\/\.toolcraft-manifest\.json/i,
+    );
+  });
+
+  const manifestSource = await fs.readFile(manifestPath, "utf8");
+  const manifest = JSON.parse(manifestSource);
+  assert.ok(
+    manifest.protectedFiles["src/app/app-performance.gates.test.ts"],
+    "Generated integrity manifest must protect framework performance meta-tests.",
+  );
+  assert.ok(
+    manifest.protectedFiles["src/app/app-performance-test-utils.ts"],
+    "Generated integrity manifest must protect framework performance test helpers.",
+  );
+  assert.ok(
+    manifest.protectedFiles["playwright.config.ts"],
+    "Generated integrity manifest must protect Playwright browser-gate configuration.",
+  );
+  for (const relativePath of [
+    "AGENTS.md",
+    "LICENSE.md",
+    "NOTICE.md",
+    "docs/toolcraft/core/layout.md",
+    "docs/toolcraft/workflow.md",
+    "tsconfig.json",
+    "vite.config.ts",
+  ]) {
+    assert.ok(
+      manifest.protectedFiles[relativePath],
+      `Generated integrity manifest must protect ${relativePath}.`,
+    );
+  }
+  assert.equal(
+    manifest.protectedFiles["docs/toolcraft/agent-worklog.md"],
+    undefined,
+    "Generated integrity manifest must leave the product decision worklog editable.",
+  );
+  assert.ok(
+    manifest.packageScripts.test,
+    "Generated integrity manifest must protect the generated test command.",
+  );
+
+  const validatorManifestPath = "src/app/acceptance/validation-pipeline.ts";
+  await withTemporaryFileSource(
+    manifestPath,
+    `${JSON.stringify(
+      {
+        ...manifest,
+        protectedFiles: {
+          ...manifest.protectedFiles,
+          [validatorManifestPath]: "0".repeat(64),
+        },
+      },
+      null,
+      2,
+    )}\n`,
+    async () => {
+      await assertIntegrityFailure(/manifest signature is invalid/);
+    },
+  );
+  await withTemporaryFileSource(
+    manifestPath,
+    `${JSON.stringify(
+      {
+        ...manifest,
+        packageScripts: {
+          ...manifest.packageScripts,
+          test: "echo skipped",
+        },
+      },
+      null,
+      2,
+    )}\n`,
+    async () => {
+      await assertIntegrityFailure(/manifest signature is invalid/);
+    },
+  );
+
+  const reducedProtectedFiles = { ...manifest.protectedFiles };
+  delete reducedProtectedFiles["e2e/app-browser-shell.spec.ts"];
+  await withTemporaryFileSource(
+    manifestPath,
+    `${JSON.stringify(
+      { ...manifest, protectedFiles: reducedProtectedFiles },
+      null,
+      2,
+    )}\n`,
+    async () => {
+      await assertIntegrityFailure(/manifest signature is invalid/);
+    },
+  );
+  await withTemporaryFileSource(
+    manifestPath,
+    `${JSON.stringify({ ...manifest, version: 1 }, null, 2)}\n`,
+    async () => {
+      await assertIntegrityFailure(/manifest version 1 is unsupported; expected 3/);
+    },
+  );
+
+  const invalidPathManifest = {
+    ...manifest,
+    files: {
+      ...manifest.files,
+      "../../outside-toolcraft.ts": "invalid-path-fixture",
+    },
+  };
+  invalidPathManifest.signature =
+    signGeneratedIntegrityManifest(invalidPathManifest);
+  await withTemporaryFileSource(
+    manifestPath,
+    `${JSON.stringify(invalidPathManifest, null, 2)}\n`,
+    async () => {
+      await assertIntegrityFailure(
+        /invalid Toolcraft path \.\.\/\.\.\/outside-toolcraft\.ts/,
+      );
+    },
+  );
+}

package/src/generate-test-integrity-ownership-assertions.mjs

@@ -0,0 +1,127 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  withTemporaryCreatedFile,
+  withTemporaryFileSource,
+  withTemporarilyRemovedFile,
+} from "./generate-test-integrity-test-utils.mjs";
+
+export async function assertGeneratedOwnershipBoundaries(context) {
+  const {
+    assertIntegrityFailure,
+    runCodeHealth,
+    runIntegrity,
+    targetDir,
+  } = context;
+  const packageJsonPath = path.join(targetDir, "package.json");
+  const packageJsonSource = await fs.readFile(packageJsonPath, "utf8");
+  const packageJson = JSON.parse(packageJsonSource);
+
+  await withTemporaryFileSource(
+    packageJsonPath,
+    `${JSON.stringify(
+      {
+        ...packageJson,
+        scripts: { ...packageJson.scripts, test: "echo skipped" },
+      },
+      null,
+      2,
+    )}\n`,
+    async () => {
+      await assertIntegrityFailure(/modified package script test/);
+    },
+  );
+  await withTemporaryFileSource(
+    packageJsonPath,
+    `${JSON.stringify(
+      {
+        ...packageJson,
+        scripts: {
+          ...packageJson.scripts,
+          posttest: "node scripts/modify-generated-runtime.mjs",
+        },
+      },
+      null,
+      2,
+    )}\n`,
+    async () => {
+      await assertIntegrityFailure(/added package lifecycle script posttest/);
+    },
+  );
+  await withTemporaryFileSource(
+    packageJsonPath,
+    `${JSON.stringify(
+      {
+        ...packageJson,
+        dependencies: {
+          ...packageJson.dependencies,
+          "product-only-dependency": "1.0.0",
+        },
+      },
+      null,
+      2,
+    )}\n`,
+    runIntegrity,
+  );
+
+  await withTemporaryCreatedFile(
+    path.join(targetDir, "vitest.config.ts"),
+    'export default { test: { exclude: ["**/*"] } };\n',
+    async () => {
+      await assertIntegrityFailure(/unapproved verification config vitest\.config\.ts/);
+    },
+  );
+
+  const editableMutationCases = [
+    {
+      relativePath: "docs/toolcraft/agent-worklog.md",
+      suffix: "\n<!-- product decision evidence stays editable -->\n",
+    },
+    {
+      relativePath: "src/app/app-acceptance-data.ts",
+      suffix: "\n// product acceptance evidence stays editable\n",
+    },
+    {
+      relativePath: "src/app/app-composition.tsx",
+      suffix: "\n// product composition stays editable\n",
+    },
+    {
+      relativePath: "src/app/app-performance.ts",
+      suffix: "\n// product performance evidence stays editable\n",
+    },
+    {
+      relativePath: "e2e/app-controls.spec.ts",
+      suffix: "\n// product browser scenarios stay editable\n",
+    },
+  ];
+
+  const agentWorklogPath = path.join(
+    targetDir,
+    "docs/toolcraft/agent-worklog.md",
+  );
+  await withTemporarilyRemovedFile(agentWorklogPath, async () => {
+    await assertIntegrityFailure(/deleted docs\/toolcraft\/agent-worklog\.md/);
+  });
+
+  for (const { relativePath, suffix } of editableMutationCases) {
+    const filePath = path.join(targetDir, relativePath);
+    const source = await fs.readFile(filePath, "utf8");
+    await withTemporaryFileSource(filePath, `${source}${suffix}`, runIntegrity);
+  }
+
+  const appSchemaPath = path.join(targetDir, "src/app/app-schema.ts");
+  await withTemporaryFileSource(
+    appSchemaPath,
+    "export const oversizedProductModule = true;\n".repeat(1001),
+    async () => {
+      await runIntegrity();
+      await assert.rejects(runCodeHealth, (error) => {
+        assert.match(String(error.stderr), /Line budget violations/);
+        assert.match(String(error.stderr), /src\/app\/app-schema\.ts/);
+        return true;
+      });
+    },
+  );
+}

package/src/generate-test-integrity-test-utils.mjs

@@ -0,0 +1,102 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function withTemporaryFileSource(filePath, nextSource, callback) {
+  const originalSource = await fs.readFile(filePath, "utf8");
+
+  await fs.writeFile(filePath, nextSource);
+
+  try {
+    await callback();
+  } finally {
+    await fs.writeFile(filePath, originalSource);
+  }
+}
+
+export async function withTemporarilyRemovedFile(filePath, callback) {
+  const originalSource = await fs.readFile(filePath);
+  await fs.rm(filePath);
+
+  try {
+    await callback();
+  } finally {
+    await fs.writeFile(filePath, originalSource);
+  }
+}
+
+export async function withTemporaryCreatedFile(filePath, source, callback) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, source);
+
+  try {
+    await callback();
+  } finally {
+    await fs.rm(filePath, { force: true });
+  }
+}
+
+export async function withTemporarySymbolicLink(
+  targetPath,
+  linkPath,
+  callback,
+) {
+  await fs.mkdir(path.dirname(linkPath), { recursive: true });
+  await fs.symlink(targetPath, linkPath);
+
+  try {
+    await callback();
+  } finally {
+    await fs.rm(linkPath, { force: true });
+  }
+}
+
+export async function withTemporarilyMovedDirectory(directoryPath, callback) {
+  const movedDirectoryPath = `${directoryPath}.integrity-test-backup`;
+
+  await fs.rm(movedDirectoryPath, { force: true, recursive: true });
+  await fs.rename(directoryPath, movedDirectoryPath);
+
+  try {
+    await callback();
+  } finally {
+    await fs.rm(directoryPath, { force: true, recursive: true });
+    await fs.rename(movedDirectoryPath, directoryPath);
+  }
+}
+
+export function createGeneratedIntegrityTestContext(targetDir, execFileAsync) {
+  const integrityScriptPath = path.join(
+    targetDir,
+    "scripts/check-toolcraft-integrity.mjs",
+  );
+  const runIntegrity = () =>
+    execFileAsync(process.execPath, [integrityScriptPath, "--platform-only"], {
+      cwd: targetDir,
+    });
+  const codeHealthScriptPath = path.join(
+    targetDir,
+    "scripts/check-toolcraft-code-health.mjs",
+  );
+  const runCodeHealth = () =>
+    execFileAsync(process.execPath, [codeHealthScriptPath], { cwd: targetDir });
+  const assertIntegrityFailure = (expectedError) =>
+    assert.rejects(runIntegrity, expectedError);
+  const assertFreshFolderRecoveryFailure = (expectedError) =>
+    assert.rejects(runIntegrity, (error) => {
+      assert.match(String(error.stderr), expectedError);
+      assert.match(String(error.stderr), /generate a fresh app folder/i);
+      return true;
+    });
+
+  return {
+    assertFreshFolderRecoveryFailure,
+    assertIntegrityFailure,
+    codeHealthScriptPath,
+    execFileAsync,
+    integrityScriptPath,
+    runIntegrity,
+    runCodeHealth,
+    targetDir,
+  };
+}

package/src/generate-test-package-assertions.mjs

@@ -0,0 +1,75 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function assertGeneratedPackageJson(targetDir) {
+  const packageJson = JSON.parse(await fs.readFile(path.join(targetDir, "package.json"), "utf8"));
+
+  assert.equal(packageJson.license, "MIT");
+  assert.equal(packageJson.dependencies["@repo/ui"], undefined);
+  assert.equal(packageJson.dependencies["@repo/toolcraft-runtime"], undefined);
+  assert.equal(packageJson.dependencies["@tanstack/react-router"], "1.170.6");
+  assert.equal(packageJson.dependencies.cmdk, "^1.1.1");
+  assert.equal(packageJson.dependencies["cross-spawn"], "^7.0.6");
+  assert.equal(packageJson.dependencies["react-resizable-panels"], "^4.10.0");
+  assert.equal(packageJson.dependencies.sonner, "^2.0.7");
+  assert.equal(packageJson.devDependencies["@repo/typescript-config"], undefined);
+  assert.equal(packageJson.devDependencies["@playwright/test"], "^1.51.1");
+  assert.equal(
+    packageJson.scripts["ai:check"],
+    "node scripts/check-toolcraft-code-health.mjs && node scripts/toolcraft-product-boundary.mjs --allow-missing-compiler && node scripts/check-ai-skills.mjs",
+  );
+  assert.equal(packageJson.scripts.dev, "node scripts/run-vite-on-free-port.mjs dev");
+  assert.equal(
+    packageJson.scripts["dev:restart"],
+    "node scripts/run-vite-on-free-port.mjs dev --toolcraft-restart",
+  );
+  assert.equal(packageJson.scripts.preview, "node scripts/run-vite-on-free-port.mjs preview");
+  assert.equal(
+    packageJson.scripts["preview:restart"],
+    "node scripts/run-vite-on-free-port.mjs preview --toolcraft-restart",
+  );
+  assert.equal(packageJson.scripts["docs:check"], "node scripts/check-toolcraft-docs.mjs");
+  assert.equal(
+    packageJson.scripts.test,
+    "node scripts/check-toolcraft-docs.mjs && node scripts/check-toolcraft-integrity.mjs && node --test scripts/*.test.mjs && vitest run src --passWithNoTests --reporter=default --reporter=./scripts/toolcraft-vitest-runtime-evidence-reporter.mjs",
+  );
+  assert.equal(packageJson.scripts["test:generated"], undefined);
+  assert.equal(
+    packageJson.scripts["test:browser"],
+    'playwright install chromium && playwright test --grep-invert "browser perf:"',
+  );
+  assert.equal(
+    packageJson.scripts["test:browser:perf"],
+    "node scripts/run-browser-performance.mjs",
+  );
+  assert.equal(packageJson.scripts["verify:quick"], "npm run ai:check && npm run test");
+  assert.equal(packageJson.scripts["verify:ui"], "npm run test:browser");
+  assert.equal(packageJson.scripts["verify:perf"], "npm run test:browser:perf");
+  assert.equal(packageJson.scripts["verify:perf:playwright"], "npm run test:browser:perf");
+  assert.equal(packageJson.scripts["verify:perf:record-agent-browser"], undefined);
+  assert.equal(
+    packageJson.scripts["verify:receipt"],
+    "node scripts/toolcraft-verification-receipt.mjs validate",
+  );
+  assert.equal(
+    packageJson.scripts["verify:final"],
+    "npm run ai:check && npm run test && npm run build && npm run test:browser && npm run verify:receipt",
+  );
+}
+
+export async function assertGeneratedGitignore(targetDir) {
+  const gitignoreSource = await fs.readFile(path.join(targetDir, ".gitignore"), "utf8");
+  assert.match(gitignoreSource, /node_modules/);
+  assert.match(gitignoreSource, /dist/);
+  assert.match(gitignoreSource, /playwright-report/);
+  assert.match(gitignoreSource, /\.env\.\*/);
+  assert.match(gitignoreSource, /\.toolcraft/);
+  await assert.rejects(() => fs.stat(path.join(targetDir, "gitignore")), /ENOENT/);
+}
+
+export async function assertGeneratedIdentity(targetDir) {
+  const indexHtmlSource = await fs.readFile(path.join(targetDir, "index.html"), "utf8");
+  assert.match(indexHtmlSource, /<title>Generated App<\/title>/);
+  assert.match(indexHtmlSource, /<meta name="toolcraft-app-title" content="Generated App" \/>/);
+}