@pixel-point/toolcraft 0.0.17 → 0.0.19

package/src/packaged-template-fallback-helpers.mjs

@@ -0,0 +1,254 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+
+import { copyDirectory } from "./copy-recursive.mjs";
+
+const execFileAsync = promisify(execFile);
+const cliSrcDir = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(cliSrcDir, "../..");
+
+export async function readUtf8(rootDir, relativePath) {
+  return fs.readFile(path.join(rootDir, relativePath), "utf8");
+}
+
+export async function execFileWithDiagnostics(command, args, options) {
+  try {
+    return await execFileAsync(command, args, options);
+  } catch (error) {
+    const stdout = String(error.stdout ?? "").trim();
+    const stderr = String(error.stderr ?? "").trim();
+    assert.fail([
+      `Command failed: ${command} ${args.join(" ")}`,
+      stdout ? `stdout:\n${stdout}` : undefined,
+      stderr ? `stderr:\n${stderr}` : undefined,
+      !stdout && !stderr ? String(error) : undefined,
+    ].filter(Boolean).join("\n"));
+  }
+}
+
+export async function importModule(rootDir, relativePath) {
+  return import(pathToFileURL(path.join(rootDir, relativePath)).href);
+}
+
+export async function stagePackageRepository(stagedRepoRoot) {
+  await Promise.all([
+    copyDirectory(path.join(repoRoot, "cli"), path.join(stagedRepoRoot, "cli")),
+    copyDirectory(path.join(repoRoot, "starter"), path.join(stagedRepoRoot, "starter")),
+    copyDirectory(
+      path.join(repoRoot, "packages/ui/src"),
+      path.join(stagedRepoRoot, "packages/ui/src"),
+    ),
+    copyDirectory(
+      path.join(repoRoot, "packages/toolcraft-runtime/src"),
+      path.join(stagedRepoRoot, "packages/toolcraft-runtime/src"),
+    ),
+  ]);
+}
+
+async function collectRelativeFiles(rootDir, relativeDir = "") {
+  const entries = await fs.readdir(path.join(rootDir, relativeDir), {
+    withFileTypes: true,
+  });
+  const files = [];
+
+  for (const entry of entries) {
+    const relativePath = path.posix.join(relativeDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await collectRelativeFiles(rootDir, relativePath)));
+    } else if (entry.isFile() || entry.isSymbolicLink()) {
+      files.push(relativePath);
+    }
+  }
+  return files.sort();
+}
+
+async function assertPreparedTemplateSource({
+  derivedTargetFiles = [],
+  sourceDir,
+  targetDir,
+}) {
+  const [sourceFiles, targetFiles] = await Promise.all([
+    collectRelativeFiles(sourceDir),
+    collectRelativeFiles(targetDir),
+  ]);
+  assert.deepEqual(
+    targetFiles,
+    [
+      ...sourceFiles,
+      ...derivedTargetFiles.map(([targetPath]) => targetPath),
+    ].sort(),
+    `Prepared template inventory must match ${sourceDir}.`,
+  );
+  for (const relativePath of sourceFiles) {
+    assert.deepEqual(
+      await fs.readFile(path.join(targetDir, relativePath)),
+      await fs.readFile(path.join(sourceDir, relativePath)),
+      `Prepared template content mismatch: ${relativePath}`,
+    );
+  }
+  for (const [targetPath, sourcePath] of derivedTargetFiles) {
+    assert.deepEqual(
+      await fs.readFile(path.join(targetDir, targetPath)),
+      await fs.readFile(path.join(sourceDir, sourcePath)),
+      `Prepared derived template content mismatch: ${targetPath}`,
+    );
+  }
+}
+
+export async function prepareStagedCliPackage(stagedCliRoot, environment) {
+  const packageJson = JSON.parse(await readUtf8(stagedCliRoot, "package.json"));
+  assert.equal(
+    packageJson.scripts.prepack,
+    "node scripts/prepare-pack.mjs",
+    "The published package must keep the canonical prepare entry point.",
+  );
+  await fs.rm(path.join(stagedCliRoot, "templates"), {
+    force: true,
+    recursive: true,
+  });
+  await execFileWithDiagnostics(
+    process.execPath,
+    [path.join(stagedCliRoot, "scripts/prepare-pack.mjs")],
+    { cwd: stagedCliRoot, env: environment },
+  );
+  const stagedRepoRoot = path.resolve(stagedCliRoot, "..");
+  const starterTemplateRoot = path.join(stagedCliRoot, "templates/starter");
+  await Promise.all([
+    assertPreparedTemplateSource({
+      derivedTargetFiles: [["gitignore", ".gitignore"]],
+      sourceDir: path.join(stagedRepoRoot, "starter"),
+      targetDir: starterTemplateRoot,
+    }),
+    assertPreparedTemplateSource({
+      sourceDir: path.join(stagedRepoRoot, "packages/toolcraft-runtime/src"),
+      targetDir: path.join(stagedCliRoot, "templates/runtime"),
+    }),
+    assertPreparedTemplateSource({
+      sourceDir: path.join(stagedRepoRoot, "packages/ui/src"),
+      targetDir: path.join(stagedCliRoot, "templates/ui"),
+    }),
+  ]);
+  return collectPackagedTemplateOwnership(starterTemplateRoot);
+}
+
+export async function linkPackagedCliDependencies(packageRoot) {
+  const packageJson = JSON.parse(
+    await fs.readFile(path.join(packageRoot, "package.json"), "utf8"),
+  );
+
+  for (const packageName of Object.keys(packageJson.dependencies ?? {})) {
+    const sourcePath = await fs.realpath(
+      path.join(repoRoot, "cli/node_modules", packageName),
+    );
+    const targetPath = path.join(packageRoot, "node_modules", packageName);
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.symlink(sourcePath, targetPath, "dir");
+  }
+}
+
+export function createPassedTestTask({ annotations = [], filePath, name }) {
+  return {
+    annotations: () => annotations,
+    module: { moduleId: filePath },
+    name,
+    options: { fails: false },
+    result: () => ({ state: "passed" }),
+  };
+}
+
+export async function collectPackagedTemplateOwnership(templateRoot) {
+  const sourceOwnership = await importModule(
+    templateRoot,
+    "scripts/toolcraft-source-ownership.mjs",
+  );
+  const [expectedPaths, templateLocalPaths] = await Promise.all([
+    sourceOwnership.collectToolcraftFrameworkOwnedGeneratedPaths(templateRoot),
+    sourceOwnership.collectToolcraftFrameworkOwnedLocalPaths(templateRoot),
+  ]);
+  assert.equal(
+    templateLocalPaths.length,
+    expectedPaths.length,
+    "Packaged template ownership normalization must not hide path collisions.",
+  );
+  const templateSourcePaths = Object.fromEntries(
+    templateLocalPaths.map((relativePath) => [
+      sourceOwnership.toToolcraftGeneratedPath(relativePath),
+      relativePath,
+    ]),
+  );
+  assert.deepEqual(
+    Object.keys(templateSourcePaths).sort(),
+    expectedPaths,
+    "Packaged template ownership normalization must be complete and unique.",
+  );
+  const templateHashes = Object.fromEntries(
+    await Promise.all(
+      expectedPaths.map(async (relativePath) => [
+        relativePath,
+        createHash("sha256")
+          .update(
+            await fs.readFile(
+              path.join(templateRoot, templateSourcePaths[relativePath]),
+            ),
+          )
+          .digest("hex"),
+      ]),
+    ),
+  );
+  return { expectedPaths, templateHashes, templateSourcePaths };
+}
+
+export async function verifyCanonicalProtectedManifest({
+  expectedPaths,
+  generatedManifest,
+  integrityPolicy,
+  targetDir,
+  templateHashes,
+  templateRoot,
+  templateSourcePaths,
+}) {
+  const protectedPaths = Object.keys(generatedManifest.protectedFiles).sort();
+  assert.deepEqual(
+    protectedPaths,
+    expectedPaths,
+    "The package manifest must cover the complete canonical ownership set.",
+  );
+  for (const relativePath of integrityPolicy.requiredProtectedTrustRootFilePaths) {
+    assert.ok(
+      protectedPaths.includes(relativePath),
+      `Missing canonical generated trust root: ${relativePath}`,
+    );
+  }
+  for (const relativePath of expectedPaths) {
+    const templatePath = path.join(
+      templateRoot,
+      templateSourcePaths[relativePath],
+    );
+    const generatedPath = path.join(targetDir, relativePath);
+    assert.equal(
+      (await fs.stat(templatePath)).isFile(),
+      true,
+      `Missing packaged template owner: ${templateSourcePaths[relativePath]}`,
+    );
+    assert.equal(
+      createHash("sha256").update(await fs.readFile(templatePath)).digest("hex"),
+      templateHashes[relativePath],
+      `Packaged template owner hash mismatch: ${templateSourcePaths[relativePath]}`,
+    );
+    assert.equal(
+      (await fs.stat(generatedPath)).isFile(),
+      true,
+      `Missing generated protected owner: ${relativePath}`,
+    );
+    assert.equal(
+      generatedManifest.protectedFiles[relativePath],
+      createHash("sha256").update(await fs.readFile(generatedPath)).digest("hex"),
+      `Generated protected owner hash mismatch: ${relativePath}`,
+    );
+  }
+}

package/src/packaged-template-fallback.test.mjs

@@ -1,47 +1,25 @@
 import assert from "node:assert/strict";
-import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { promisify } from "node:util";
 import { it } from "node:test";
 
-import { copyDirectory } from "./copy-recursive.mjs";
-
-const execFileAsync = promisify(execFile);
-const cliSrcDir = path.dirname(fileURLToPath(import.meta.url));
-const repoRoot = path.resolve(cliSrcDir, "../..");
-
-async function stagePackageRepository(stagedRepoRoot) {
-  await Promise.all([
-    copyDirectory(path.join(repoRoot, "cli"), path.join(stagedRepoRoot, "cli")),
-    copyDirectory(path.join(repoRoot, "starter"), path.join(stagedRepoRoot, "starter")),
-    copyDirectory(
-      path.join(repoRoot, "packages/ui/src"),
-      path.join(stagedRepoRoot, "packages/ui/src"),
-    ),
-    copyDirectory(
-      path.join(repoRoot, "packages/toolcraft-runtime/src"),
-      path.join(stagedRepoRoot, "packages/toolcraft-runtime/src"),
-    ),
-  ]);
-}
-
-async function linkPackagedCliDependencies(packageRoot) {
-  const packageJson = JSON.parse(
-    await fs.readFile(path.join(packageRoot, "package.json"), "utf8"),
-  );
-
-  for (const packageName of Object.keys(packageJson.dependencies ?? {})) {
-    const sourcePath = await fs.realpath(
-      path.join(repoRoot, "cli/node_modules", packageName),
-    );
-    const targetPath = path.join(packageRoot, "node_modules", packageName);
-    await fs.mkdir(path.dirname(targetPath), { recursive: true });
-    await fs.symlink(sourcePath, targetPath, "dir");
-  }
-}
+import {
+  createGeneratedCommandEnvironment,
+} from "./generate-test-dependency-sandbox.mjs";
+import {
+  collectPackagedTemplateOwnership,
+  execFileWithDiagnostics,
+  importModule,
+  linkPackagedCliDependencies,
+  prepareStagedCliPackage,
+  readUtf8,
+  stagePackageRepository,
+  verifyCanonicalProtectedManifest,
+} from "./packaged-template-fallback-helpers.mjs";
+import {
+  verifyPackagedRuntimeSelection,
+} from "./packaged-template-runtime-assertions.mjs";
 
 it("packs, executes, and verifies the isolated npm package fallback", async () => {
   const tempRoot = await fs.mkdtemp(
@@ -59,19 +37,42 @@ it("packs, executes, and verifies the isolated npm package fallback", async () =
       fs.mkdir(tarballRoot, { recursive: true }),
       fs.mkdir(extractedRoot, { recursive: true }),
       fs.mkdir(outputRoot, { recursive: true }),
+      fs.mkdir(path.join(tempRoot, "npm-cache"), { recursive: true }),
     ]);
 
-    const packResult = await execFileAsync(
+    const packageEnvironment = createGeneratedCommandEnvironment("npm", {
+      NODE_TEST_CONTEXT: "reserved-parent-test-state",
+      npm_config_cache: path.join(tempRoot, "npm-cache"),
+    });
+    assert.equal(
+      Object.hasOwn(packageEnvironment, "NODE_TEST_CONTEXT"),
+      false,
+      "npm lifecycle commands must not inherit Node's parent test context.",
+    );
+    assert.equal(
+      packageEnvironment.npm_config_cache,
+      path.join(tempRoot, "npm-cache"),
+      "npm package tests must isolate their cache under the test root.",
+    );
+    const preparedTemplateOwnership = await prepareStagedCliPackage(
+      stagedCliRoot,
+      packageEnvironment,
+    );
+    const packResult = await execFileWithDiagnostics(
       "npm",
-      ["pack", "--silent", "--json", "--pack-destination", tarballRoot],
-      { cwd: stagedCliRoot },
+      ["pack", "--ignore-scripts", "--json", "--pack-destination", tarballRoot],
+      { cwd: stagedCliRoot, env: packageEnvironment },
     );
     const [packedArtifact] = JSON.parse(packResult.stdout);
     assert.ok(packedArtifact?.filename, "npm pack must report its tarball filename.");
 
     const tarballPath = path.join(tarballRoot, packedArtifact.filename);
-    await execFileAsync("tar", ["-xzf", tarballPath, "-C", extractedRoot]);
+    await execFileWithDiagnostics(
+      "tar",
+      ["-xzf", tarballPath, "-C", extractedRoot],
+    );
     const packageRoot = path.join(extractedRoot, "package");
+    const templateRoot = path.join(packageRoot, "templates/starter");
     const packagedFiles = [
       "bin/create-toolcraft-app.mjs",
       "bin/toolcraft.mjs",
@@ -80,6 +81,9 @@ it("packs, executes, and verifies the isolated npm package fallback", async () =
       "src/generate-test-windows-job.mjs",
       "src/generate-test-windows-job.ps1",
       "templates/starter/package.json",
+      "templates/starter/scripts/toolcraft-delivery-plan.mjs",
+      "templates/starter/scripts/toolcraft-vitest-runtime-contract.mjs",
+      "templates/starter/scripts/toolcraft-vitest-runtime-evidence-reporter.mjs",
       "templates/runtime/index.ts",
       "templates/ui/index.ts",
     ];
@@ -90,9 +94,17 @@ it("packs, executes, and verifies the isolated npm package fallback", async () =
         `Missing packaged file: ${relativePath}`,
       );
     }
-
+    const packagedTemplateOwnership =
+      await collectPackagedTemplateOwnership(templateRoot);
+    assert.deepEqual(
+      packagedTemplateOwnership,
+      preparedTemplateOwnership,
+      "The tarball must preserve the complete prepared ownership inventory.",
+    );
+    const { expectedPaths, templateHashes, templateSourcePaths } =
+      packagedTemplateOwnership;
     await linkPackagedCliDependencies(packageRoot);
-    await execFileAsync(
+    await execFileWithDiagnostics(
       process.execPath,
       [
         path.join(packageRoot, "bin/toolcraft.mjs"),
@@ -107,7 +119,7 @@ it("packs, executes, and verifies the isolated npm package fallback", async () =
       ],
       { cwd: outputRoot },
     );
-    const compatibilityHelp = await execFileAsync(
+    const compatibilityHelp = await execFileWithDiagnostics(
       process.execPath,
       [path.join(packageRoot, "bin/create-toolcraft-app.mjs"), "--help"],
       { cwd: outputRoot },
@@ -115,7 +127,70 @@ it("packs, executes, and verifies the isolated npm package fallback", async () =
     assert.match(compatibilityHelp.stdout, /Usage:/);
 
     const targetDir = path.join(outputRoot, "packaged-app");
-    const integrityResult = await execFileAsync(
+    const [
+      planModule,
+      runtimeContract,
+      runtimeReporter,
+      integrityPolicy,
+    ] =
+      await Promise.all([
+        importModule(targetDir, "scripts/toolcraft-delivery-plan.mjs"),
+        importModule(targetDir, "scripts/toolcraft-vitest-runtime-contract.mjs"),
+        importModule(
+          targetDir,
+          "scripts/toolcraft-vitest-runtime-evidence-reporter.mjs",
+        ),
+        importModule(targetDir, "scripts/toolcraft-integrity-policy.mjs"),
+      ]);
+    assert.equal(planModule.TOOLCRAFT_DELIVERY_PLAN_VERSION, 6);
+    await verifyPackagedRuntimeSelection({
+      runtimeContract,
+      runtimeReporter,
+      targetDir,
+    });
+    const generatedPackageJson = JSON.parse(
+      await readUtf8(targetDir, "package.json"),
+    );
+    assert.equal(
+      generatedPackageJson.scripts["reference:study"],
+      "node scripts/create-toolcraft-motion-reference-study.mjs",
+    );
+    const generatedManifest = JSON.parse(
+      await readUtf8(targetDir, "src/toolcraft/.toolcraft-manifest.json"),
+    );
+    await verifyCanonicalProtectedManifest({
+      expectedPaths,
+      generatedManifest,
+      integrityPolicy,
+      targetDir,
+      templateHashes,
+      templateRoot,
+      templateSourcePaths,
+    });
+    const trustRootPaths = new Set(
+      integrityPolicy.requiredProtectedTrustRootFilePaths,
+    );
+    const omittedPath = expectedPaths.find(
+      (relativePath) =>
+        relativePath.startsWith("scripts/") && !trustRootPaths.has(relativePath),
+    );
+    assert.equal(typeof omittedPath, "string");
+    assert.equal(trustRootPaths.has(omittedPath), false);
+    const incompleteManifest = structuredClone(generatedManifest);
+    delete incompleteManifest.protectedFiles[omittedPath];
+    await assert.rejects(
+      verifyCanonicalProtectedManifest({
+        expectedPaths,
+        generatedManifest: incompleteManifest,
+        integrityPolicy,
+        targetDir,
+        templateHashes,
+        templateRoot,
+        templateSourcePaths,
+      }),
+      /complete canonical ownership set/iu,
+    );
+    const integrityResult = await execFileWithDiagnostics(
       process.execPath,
       [
         path.join(targetDir, "scripts/check-toolcraft-integrity.mjs"),

package/src/packaged-template-runtime-assertions.mjs

@@ -0,0 +1,150 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+
+import { createPassedTestTask } from "./packaged-template-fallback-helpers.mjs";
+
+export async function verifyPackagedRuntimeSelection({
+  runtimeContract,
+  runtimeReporter,
+  targetDir,
+}) {
+  const runtimeRequirements = [
+    {
+      kind: "acceptance",
+      requirementId: "appearance.opacity",
+      testName: "opacity changes product output",
+    },
+    {
+      kind: "acceptance",
+      requirementId: "material.host",
+      testName: "keeps the material host valid",
+    },
+  ];
+  const targetedSelection =
+    runtimeContract.serializeToolcraftVitestRuntimeAcceptanceSelection([
+      "appearance.opacity",
+    ]);
+  assert.deepEqual(
+    runtimeContract.parseToolcraftVitestRuntimeAcceptanceSelection(
+      targetedSelection,
+    ),
+    ["appearance.opacity"],
+  );
+  const inheritedEnvironment = {
+    KEEP_ME: "yes",
+    [runtimeContract.TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV]:
+      "stale-selection",
+  };
+  const fullEnvironment =
+    runtimeContract.getToolcraftProductTestProcessEnvironment(
+      null,
+      inheritedEnvironment,
+    );
+  assert.equal(fullEnvironment.KEEP_ME, "yes");
+  assert.equal(
+    Object.hasOwn(
+      fullEnvironment,
+      runtimeContract.TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV,
+    ),
+    false,
+  );
+  const targetedEnvironment =
+    runtimeContract.getToolcraftProductTestProcessEnvironment(
+      ["appearance.opacity"],
+      inheritedEnvironment,
+    );
+  assert.deepEqual(
+    runtimeContract.selectToolcraftVitestRuntimeRequirements(
+      runtimeRequirements,
+      targetedEnvironment[
+        runtimeContract.TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV
+      ],
+    ),
+    [runtimeRequirements[0]],
+  );
+  assert.throws(
+    () => runtimeContract.selectToolcraftVitestRuntimeRequirements(
+      runtimeRequirements,
+      runtimeContract.serializeToolcraftVitestRuntimeAcceptanceSelection([
+        "unknown.requirement",
+      ]),
+    ),
+    /unknown acceptance requirement/iu,
+  );
+  assert.equal(typeof runtimeReporter.default, "function");
+  await assert.rejects(
+    new runtimeReporter.default().onTestRunEnd([]),
+    /marker was not executed/iu,
+  );
+
+  const previousSelection =
+    process.env[runtimeContract.TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV];
+  try {
+    const marker = createPassedTestTask({
+      annotations: [{
+        message:
+          runtimeContract.serializeToolcraftVitestRuntimeRequirements(
+            runtimeRequirements,
+          ),
+        type:
+          runtimeContract.TOOLCRAFT_VITEST_RUNTIME_REQUIREMENTS_ANNOTATION_TYPE,
+      }],
+      filePath: path.join(
+        targetDir,
+        "src/app/app-automated-runtime-evidence.test.ts",
+      ),
+      name: runtimeContract.TOOLCRAFT_VITEST_RUNTIME_MARKER_TEST_NAME,
+    });
+    const selectedProductTest = createPassedTestTask({
+      filePath: path.join(targetDir, "src/app/app-schema.test.ts"),
+      name: runtimeRequirements[0].testName,
+    });
+    const selectedTestModule = {
+      children: {
+        allTests: () => [marker, selectedProductTest],
+      },
+    };
+    process.env[
+      runtimeContract.TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV
+    ] = targetedSelection;
+    await new runtimeReporter.default().onTestRunEnd([selectedTestModule]);
+
+    delete process.env[
+      runtimeContract.TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV
+    ];
+    await assert.rejects(
+      new runtimeReporter.default().onTestRunEnd([selectedTestModule]),
+      /Missing required automated test.*material host/iu,
+    );
+
+    const emptyMarker = createPassedTestTask({
+      annotations: [{
+        message:
+          runtimeContract.serializeToolcraftVitestRuntimeRequirements([]),
+        type:
+          runtimeContract.TOOLCRAFT_VITEST_RUNTIME_REQUIREMENTS_ANNOTATION_TYPE,
+      }],
+      filePath: path.join(
+        targetDir,
+        "src/app/app-automated-runtime-evidence.test.ts",
+      ),
+      name: runtimeContract.TOOLCRAFT_VITEST_RUNTIME_MARKER_TEST_NAME,
+    });
+    await assert.rejects(
+      new runtimeReporter.default().onTestRunEnd([{
+        children: { allTests: () => [emptyMarker] },
+      }]),
+      /at least one runtime requirement/iu,
+    );
+  } finally {
+    if (previousSelection === undefined) {
+      delete process.env[
+        runtimeContract.TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV
+      ];
+    } else {
+      process.env[
+        runtimeContract.TOOLCRAFT_VITEST_RUNTIME_ACCEPTANCE_SELECTION_ENV
+      ] = previousSelection;
+    }
+  }
+}