@pixel-point/toolcraft 0.0.14 → 0.0.15

package/src/generated-integrity-manifest.mjs

@@ -0,0 +1,127 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const integrityManifestPrivateKey = `-----BEGIN PRIVATE KEY-----
+MC4CAQAwBQYDK2VwBCIEILS7vsf4OtBXySuK44JF2ooQuvSm7xGR58/fZmh5a7kF
+-----END PRIVATE KEY-----`;
+
+async function hashFile(filePath) {
+  const buffer = await fs.readFile(filePath);
+  return crypto.createHash("sha256").update(buffer).digest("hex");
+}
+
+function toPosixPath(filePath) {
+  return filePath.split(path.sep).join("/");
+}
+
+function compareCodeUnits(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+async function collectRelativeFiles(rootDir, relativeRoot = "") {
+  const files = [];
+  const entries = await fs.readdir(rootDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const filePath = path.join(rootDir, entry.name);
+    const relativePath = toPosixPath(path.join(relativeRoot, entry.name));
+
+    if (entry.isDirectory()) {
+      files.push(...(await collectRelativeFiles(filePath, relativePath)));
+      continue;
+    }
+
+    if (entry.isFile() && entry.name !== ".toolcraft-manifest.json") {
+      files.push(relativePath);
+    }
+  }
+
+  return files.sort(compareCodeUnits);
+}
+
+async function hashRelativeFiles(rootDir, relativePaths) {
+  const hashes = {};
+
+  for (const relativePath of relativePaths) {
+    hashes[relativePath] = await hashFile(
+      path.join(rootDir, ...relativePath.split("/")),
+    );
+  }
+
+  return Object.fromEntries(
+    Object.entries(hashes).sort(([left], [right]) =>
+      compareCodeUnits(left, right),
+    ),
+  );
+}
+
+function sortManifestFileRecord(value) {
+  return Object.fromEntries(
+    Object.entries(value).sort(([left], [right]) =>
+      compareCodeUnits(left, right),
+    ),
+  );
+}
+
+export function createManifestSignaturePayload({
+  files,
+  packageScripts,
+  protectedFiles,
+  version,
+}) {
+  return JSON.stringify({
+    files: sortManifestFileRecord(files),
+    packageScripts: sortManifestFileRecord(packageScripts),
+    protectedFiles: sortManifestFileRecord(protectedFiles),
+    version,
+  });
+}
+
+export function signGeneratedIntegrityManifest(manifest) {
+  return crypto
+    .sign(
+      null,
+      Buffer.from(createManifestSignaturePayload(manifest)),
+      integrityManifestPrivateKey,
+    )
+    .toString("base64");
+}
+
+export async function collectFrameworkOwnedGeneratedFiles(starterRoot) {
+  const policyUrl = pathToFileURL(
+    path.join(starterRoot, "scripts/toolcraft-source-ownership.mjs"),
+  );
+  const { collectToolcraftFrameworkOwnedGeneratedPaths } = await import(
+    policyUrl.href
+  );
+
+  return collectToolcraftFrameworkOwnedGeneratedPaths(starterRoot);
+}
+
+export async function writeGeneratedIntegrityManifest({
+  appRoot,
+  packageScripts,
+  starterRoot,
+  toolcraftRoot,
+}) {
+  const toolcraftRelativeFiles = await collectRelativeFiles(toolcraftRoot);
+  const protectedRelativeFiles = await collectFrameworkOwnedGeneratedFiles(
+    starterRoot,
+  );
+  const manifest = {
+    description:
+      "Integrity manifest for copied Toolcraft and framework-owned generated sources.",
+    files: await hashRelativeFiles(toolcraftRoot, toolcraftRelativeFiles),
+    packageScripts: sortManifestFileRecord(packageScripts),
+    protectedFiles: await hashRelativeFiles(appRoot, protectedRelativeFiles),
+    version: 3,
+  };
+  const signature = signGeneratedIntegrityManifest(manifest);
+
+  await fs.writeFile(
+    path.join(toolcraftRoot, ".toolcraft-manifest.json"),
+    `${JSON.stringify({ ...manifest, signature }, null, 2)}\n`,
+  );
+}

package/src/generated-integrity-manifest.test.mjs

@@ -0,0 +1,151 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, it } from "node:test";
+
+import {
+  collectFrameworkOwnedGeneratedFiles,
+  createManifestSignaturePayload,
+} from "./generated-integrity-manifest.mjs";
+
+const cliSrcDir = path.dirname(fileURLToPath(import.meta.url));
+const starterRoot = path.resolve(cliSrcDir, "../../starter");
+
+async function collectFiles(rootDir, relativeRoot) {
+  const files = [];
+
+  async function visit(currentDir, currentRelativeDir) {
+    for (const entry of await fs.readdir(currentDir, { withFileTypes: true })) {
+      const filePath = path.join(currentDir, entry.name);
+      const relativePath = path.posix.join(currentRelativeDir, entry.name);
+
+      if (entry.isDirectory()) {
+        await visit(filePath, relativePath);
+      } else if (entry.isFile() && entry.name !== ".toolcraft-manifest.json") {
+        files.push(relativePath);
+      }
+    }
+  }
+
+  await visit(rootDir, relativeRoot);
+  return files;
+}
+
+function mapExpectedGeneratedPath(starterPath) {
+  return starterPath.startsWith("src/app/starter-")
+    ? starterPath.replace(/^src\/app\/starter-/, "src/app/app-")
+    : starterPath;
+}
+
+const independentlyProductOwnedPaths = new Set([
+  "docs/toolcraft/agent-worklog.md",
+  "e2e/app-controls.spec.ts",
+  "src/app/app-acceptance-data.ts",
+  "src/app/app-composition.tsx",
+  "src/app/app-performance.ts",
+  "src/app/app-schema.test.ts",
+  "src/app/app-schema.ts",
+]);
+const independentlyOwnedRootFiles = [
+  "AGENTS.md",
+  "LICENSE.md",
+  "NOTICE.md",
+  "index.html",
+  "playwright.config.ts",
+  "src/main.tsx",
+  "src/router.tsx",
+  "src/routes/index.tsx",
+  "src/routes/root.tsx",
+  "src/styles.css",
+  "tsconfig.json",
+  "vite.config.ts",
+];
+
+async function collectStarterOwnershipCandidates() {
+  const roots = ["docs/toolcraft", "scripts", "src/app", "e2e"];
+  const rootedFiles = (
+    await Promise.all(
+      roots.map((relativeRoot) =>
+        collectFiles(path.join(starterRoot, relativeRoot), relativeRoot),
+      ),
+    )
+  ).flat();
+
+  return [
+    ...independentlyOwnedRootFiles,
+    ...rootedFiles,
+  ]
+    .map(mapExpectedGeneratedPath)
+    .sort();
+}
+
+describe("collectFrameworkOwnedGeneratedFiles", () => {
+  it("matches the complete independently derived framework ownership set", async () => {
+    const candidates = await collectStarterOwnershipCandidates();
+    for (const productOwnedPath of independentlyProductOwnedPaths) {
+      assert.ok(
+        candidates.includes(productOwnedPath),
+        `Missing product-owned starter exception: ${productOwnedPath}`,
+      );
+    }
+    const expectedProtectedFiles = candidates.filter(
+      (relativePath) => !independentlyProductOwnedPaths.has(relativePath),
+    );
+    const protectedFiles = await collectFrameworkOwnedGeneratedFiles(starterRoot);
+
+    assert.deepEqual(protectedFiles, expectedProtectedFiles);
+    for (const relativePath of independentlyOwnedRootFiles) {
+      assert.ok(protectedFiles.includes(relativePath));
+    }
+    assert.ok(protectedFiles.includes("docs/toolcraft/core/layout.md"));
+    assert.ok(!protectedFiles.includes("docs/toolcraft/agent-worklog.md"));
+  });
+
+  it("protects every starter-owned operational script through an independent invariant", async () => {
+    const expectedScripts = (
+      await collectFiles(path.join(starterRoot, "scripts"), "scripts")
+    ).sort();
+    const protectedScripts = (
+      await collectFrameworkOwnedGeneratedFiles(starterRoot)
+    ).filter((relativePath) => relativePath.startsWith("scripts/"));
+
+    assert.deepEqual(protectedScripts, expectedScripts);
+  });
+});
+
+describe("createManifestSignaturePayload", () => {
+  it("uses locale-independent canonical path order", () => {
+    const left = createManifestSignaturePayload({
+      files: { "z.ts": "z", "A.ts": "a" },
+      packageScripts: { test: "node check.mjs", "verify:final": "pnpm test" },
+      protectedFiles: { "src/z.ts": "z", "src/A.ts": "a" },
+      version: 3,
+    });
+    const right = createManifestSignaturePayload({
+      files: { "A.ts": "a", "z.ts": "z" },
+      packageScripts: { "verify:final": "pnpm test", test: "node check.mjs" },
+      protectedFiles: { "src/A.ts": "a", "src/z.ts": "z" },
+      version: 3,
+    });
+
+    assert.equal(left, right);
+  });
+
+  it("includes protected package scripts in the signed payload", () => {
+    const baseline = createManifestSignaturePayload({
+      files: { "index.ts": "hash" },
+      packageScripts: { test: "node scripts/check-toolcraft-integrity.mjs" },
+      protectedFiles: { "AGENTS.md": "hash" },
+      version: 3,
+    });
+    const modified = createManifestSignaturePayload({
+      files: { "index.ts": "hash" },
+      packageScripts: { test: "echo skipped" },
+      protectedFiles: { "AGENTS.md": "hash" },
+      version: 3,
+    });
+
+    assert.notEqual(baseline, modified);
+  });
+});

package/src/generated-source-policy.mjs

@@ -0,0 +1,22 @@
+const generatedTestFilePattern = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
+const generatedTestSupportFilePattern = /-test-(?:fixtures|utils)\.[cm]?[jt]sx?$/;
+
+function isGeneratedTestSupportDirectoryName(segment) {
+  return (
+    segment === "__tests__" ||
+    segment === "test-fixtures" ||
+    segment.endsWith("-test-fixtures")
+  );
+}
+
+export function isGeneratedTestSupportPath(relativePath) {
+  const normalizedPath = String(relativePath).replaceAll("\\", "/");
+  const pathSegments = normalizedPath.split("/").filter(Boolean);
+  const fileName = pathSegments.at(-1) ?? "";
+
+  return (
+    pathSegments.some(isGeneratedTestSupportDirectoryName) ||
+    generatedTestFilePattern.test(fileName) ||
+    generatedTestSupportFilePattern.test(fileName)
+  );
+}

package/src/generated-source-policy.test.mjs

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import {
+  isGeneratedTestSupportPath,
+} from "./generated-source-policy.mjs";
+
+describe("isGeneratedTestSupportPath", () => {
+  it("distinguishes production runtime source from test support", () => {
+    const productionPaths = [
+      "react/panel.tsx",
+      "react/contest-fixtures/index.ts",
+      "react/latest-fixtures/index.ts",
+      "testing/performance-fixture-values.ts",
+      "testing/performance-coverage-validator.ts",
+    ];
+    const testSupportPaths = [
+      "react/panel.test.tsx",
+      "react/panel.spec.ts",
+      "react/panel-test-utils.tsx",
+      "testing/performance-test-fixtures.ts",
+      "testing/performance-test-fixtures/scenarios.ts",
+      "react/__tests__/fixture.ts",
+      "react\\__tests__\\fixture.ts",
+    ];
+
+    for (const relativePath of productionPaths) {
+      assert.equal(isGeneratedTestSupportPath(relativePath), false, relativePath);
+    }
+
+    for (const relativePath of testSupportPaths) {
+      assert.equal(isGeneratedTestSupportPath(relativePath), true, relativePath);
+    }
+  });
+});

package/src/generated-target-policy.mjs

@@ -0,0 +1,55 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { pathExists } from "./copy-recursive.mjs";
+
+const generatedTargetMarkers = Object.freeze({
+  integrityChecker: "scripts/check-toolcraft-integrity.mjs",
+  integrityManifest: "src/toolcraft/.toolcraft-manifest.json",
+  runtimeRoot: "src/toolcraft",
+});
+const integrityCheckerCommand = "scripts/check-toolcraft-integrity.mjs";
+
+async function packageInvokesGeneratedIntegrity(targetDir) {
+  const packagePath = path.join(targetDir, "package.json");
+  if (!(await pathExists(packagePath))) {
+    return false;
+  }
+
+  const packageSource = await fs.readFile(packagePath, "utf8");
+  try {
+    const packageJson = JSON.parse(packageSource);
+    return Object.values(packageJson.scripts ?? {}).some((command) =>
+      String(command).includes(integrityCheckerCommand),
+    );
+  } catch {
+    return packageSource.includes(integrityCheckerCommand);
+  }
+}
+
+export async function getGeneratedTargetMarkers(targetDir) {
+  const markers = [];
+
+  for (const [marker, relativePath] of Object.entries(generatedTargetMarkers)) {
+    if (await pathExists(path.join(targetDir, relativePath))) {
+      markers.push(marker);
+    }
+  }
+
+  if (await packageInvokesGeneratedIntegrity(targetDir)) {
+    markers.push("integrityPackageCommand");
+  }
+
+  return markers;
+}
+
+export async function assertTargetIsNotGeneratedApp(targetDir) {
+  const markers = await getGeneratedTargetMarkers(targetDir);
+  if (markers.length === 0) {
+    return;
+  }
+
+  throw new Error(
+    `Refusing to regenerate an existing Toolcraft app in place: ${targetDir}. Detected generated-app markers: ${markers.join(", ")}. Generate a fresh folder and move product-owned app source deliberately; --force is destructive creation, not migration.`,
+  );
+}

package/src/generation-transaction.mjs

@@ -0,0 +1,135 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { copyDirectory, pathExists, removeDirectory } from "./copy-recursive.mjs";
+
+const DISPOSABLE_FORCE_STAGING_NAMES = new Set([
+  ".DS_Store",
+  ".next",
+  ".turbo",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "out",
+  "playwright-report",
+  "storybook-static",
+  "test-results",
+]);
+
+function getTransactionPrefix(targetDir, kind) {
+  const targetName = path.basename(targetDir) || "toolcraft-app";
+  return path.join(path.dirname(targetDir), `.${targetName}.toolcraft-${kind}-`);
+}
+
+async function getTargetDirectoryState(targetDir, { force }) {
+  if (!(await pathExists(targetDir))) {
+    return { exists: false };
+  }
+
+  const stats = await fs.lstat(targetDir);
+  if (stats.isSymbolicLink() || !stats.isDirectory()) {
+    throw new Error(`Target path must be an ordinary directory: ${targetDir}`);
+  }
+
+  const entries = await fs.readdir(targetDir);
+  const meaningfulEntries = entries.filter((entry) => entry !== ".DS_Store");
+  if (meaningfulEntries.length > 0 && !force) {
+    throw new Error(
+      `Target directory is not empty: ${targetDir}. Use --force to write into it.`,
+    );
+  }
+
+  return { exists: true };
+}
+
+export async function prepareGenerationTransaction({ force = false, targetDir }) {
+  const parentDir = path.dirname(targetDir);
+  await fs.mkdir(parentDir, { recursive: true });
+
+  const targetState = await getTargetDirectoryState(targetDir, { force });
+  const stagingDir = await fs.mkdtemp(getTransactionPrefix(targetDir, "stage"));
+
+  try {
+    if (targetState.exists) {
+      await copyDirectory(targetDir, stagingDir, {
+        // .git is deliberately absent from this list so forced generation keeps
+        // repository identity while disposable install/build output is rebuilt.
+        ignoredNames: DISPOSABLE_FORCE_STAGING_NAMES,
+      });
+    }
+  } catch (error) {
+    await removeDirectory(stagingDir);
+    throw error;
+  }
+
+  return {
+    originalTargetExists: targetState.exists,
+    stagingDir,
+    targetDir,
+  };
+}
+
+async function restoreOriginalTarget({ backupDir, targetDir, targetWasPromoted }) {
+  if (targetWasPromoted && (await pathExists(targetDir))) {
+    await removeDirectory(targetDir);
+  }
+
+  if (backupDir && (await pathExists(backupDir))) {
+    await fs.rename(backupDir, targetDir);
+  }
+}
+
+export async function commitGenerationTransaction(transaction, hooks = {}) {
+  const { originalTargetExists, stagingDir, targetDir } = transaction;
+  const backupDir = originalTargetExists
+    ? `${getTransactionPrefix(targetDir, "backup")}${randomUUID()}`
+    : undefined;
+  let originalTargetMoved = false;
+  let targetWasPromoted = false;
+
+  try {
+    await hooks.beforeCommit?.({ stagingDir, targetDir });
+
+    if (originalTargetExists) {
+      if (!(await pathExists(targetDir))) {
+        throw new Error(`Target directory disappeared before commit: ${targetDir}`);
+      }
+      await fs.rename(targetDir, backupDir);
+      originalTargetMoved = true;
+      await hooks.afterTargetBackup?.({ backupDir, stagingDir, targetDir });
+    } else if (await pathExists(targetDir)) {
+      throw new Error(`Target directory appeared before commit: ${targetDir}`);
+    }
+
+    await fs.rename(stagingDir, targetDir);
+    targetWasPromoted = true;
+
+    if (backupDir) {
+      await removeDirectory(backupDir);
+      originalTargetMoved = false;
+    }
+  } catch (error) {
+    try {
+      if (originalTargetMoved || targetWasPromoted) {
+        await restoreOriginalTarget({
+          backupDir,
+          targetDir,
+          targetWasPromoted,
+        });
+      }
+      await removeDirectory(stagingDir);
+    } catch (rollbackError) {
+      throw new AggregateError(
+        [error, rollbackError],
+        `Toolcraft generation failed and rollback could not complete for ${targetDir}.`,
+      );
+    }
+    throw error;
+  }
+}
+
+export async function abortGenerationTransaction(transaction) {
+  await removeDirectory(transaction.stagingDir);
+}

package/src/generation-transaction.test.mjs

@@ -0,0 +1,74 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { after, test } from "node:test";
+
+import {
+  abortGenerationTransaction,
+  prepareGenerationTransaction,
+} from "./generation-transaction.mjs";
+
+const tempRoots = [];
+
+after(async () => {
+  await Promise.all(
+    tempRoots.map((tempRoot) => fs.rm(tempRoot, { force: true, recursive: true })),
+  );
+});
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+test("forced staging preserves .git and product files without copying disposable output", async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-transaction-"));
+  tempRoots.push(tempRoot);
+  const targetDir = path.join(tempRoot, "existing-product");
+  await Promise.all([
+    fs.mkdir(path.join(targetDir, ".git"), { recursive: true }),
+    fs.mkdir(path.join(targetDir, "node_modules", "package"), { recursive: true }),
+    fs.mkdir(path.join(targetDir, "dist"), { recursive: true }),
+    fs.mkdir(path.join(targetDir, "playwright-report"), { recursive: true }),
+    fs.mkdir(path.join(targetDir, "test-results"), { recursive: true }),
+  ]);
+  await Promise.all([
+    fs.writeFile(path.join(targetDir, ".git", "config"), "repository\n"),
+    fs.writeFile(path.join(targetDir, "product-source.ts"), "export const product = true;\n"),
+    fs.writeFile(path.join(targetDir, "node_modules", "package", "index.js"), "cached\n"),
+    fs.writeFile(path.join(targetDir, "dist", "bundle.js"), "built\n"),
+    fs.writeFile(path.join(targetDir, "playwright-report", "index.html"), "report\n"),
+    fs.writeFile(path.join(targetDir, "test-results", "result.json"), "{}\n"),
+  ]);
+
+  const transaction = await prepareGenerationTransaction({
+    force: true,
+    targetDir,
+  });
+
+  try {
+    assert.equal(
+      await fs.readFile(path.join(transaction.stagingDir, ".git", "config"), "utf8"),
+      "repository\n",
+    );
+    assert.equal(
+      await fs.readFile(path.join(transaction.stagingDir, "product-source.ts"), "utf8"),
+      "export const product = true;\n",
+    );
+    for (const disposableName of [
+      "node_modules",
+      "dist",
+      "playwright-report",
+      "test-results",
+    ]) {
+      assert.equal(await exists(path.join(transaction.stagingDir, disposableName)), false);
+    }
+  } finally {
+    await abortGenerationTransaction(transaction);
+  }
+});

package/src/package-json.mjs

@@ -55,13 +55,30 @@ export function createGeneratedPackageJson({
     throw new Error("starterPackageJson is required to create a generated package manifest.");
   }
 
+  const {
+    "test:generated": generatedTestScript,
+    ...starterScripts
+  } = starterPackageJson.scripts ?? {};
+
+  if (!generatedTestScript) {
+    throw new Error(
+      "starterPackageJson.scripts.test:generated is required to create a generated package manifest.",
+    );
+  }
+  if (!starterScripts["verify:receipt"]) {
+    throw new Error(
+      "starterPackageJson.scripts.verify:receipt is required to create a generated package manifest.",
+    );
+  }
+
   const packageJson = {
     name: sanitizePackageName(name),
     private: true,
     license: starterPackageJson.license,
     type: starterPackageJson.type ?? "module",
     scripts: {
-      ...(starterPackageJson.scripts ?? {}),
+      ...starterScripts,
+      test: generatedTestScript,
       ...createVerificationScripts(packageManager),
     },
   };