@pixel-point/toolcraft 0.0.12 → 0.0.14

package/templates/starter/docs/toolcraft/workflow.md

@@ -17,22 +17,24 @@ Before planning or editing app code, runtime code, controls, canvas, panels, ren
 
 Do not edit implementation files until this preflight is complete.
 
+Core modules are required reading when listed by the routing table. Read each listed module fully. Do not rely on a truncated terminal excerpt; reopen the specific module or use a narrower range when a tool output is clipped.
+
 ## Task Routing
 
 Use the smallest reading set that covers the changed surface. If a task touches multiple surfaces, combine every matching row instead of picking only the closest one.
 
 | Task type | Read before editing |
 | --- | --- |
-| App assembly, route structure, generated app porting | `assembly-workflow.md`, `decision-contract.md` |
-| Reference app study, audit, or port | `assembly-workflow.md`, `schema-reference.md`, `acceptance-testing.md`, `decision-contract.md` |
-| Schema, controls, defaults, persistence, actions | `schema-reference.md`, `component-rules.md`, `acceptance-testing.md` |
-| Custom controls | `custom-controls.md`, `component-rules.md`, `acceptance-testing.md` |
-| Renderer, canvas output, visual technique | `renderer-technique.md`, `performance.md`, `acceptance-testing.md` |
-| Timeline, keyframes, animation transport | `decision-contract.md`, `component-rules.md`, `acceptance-testing.md`, `performance.md` |
-| Layers | `decision-contract.md`, `component-rules.md`, `acceptance-testing.md` |
-| Export, copy, media, background | `schema-reference.md`, `component-rules.md`, `acceptance-testing.md`, `performance.md` |
-| Broken control, visual mismatch, failed build, export bug, performance issue | `decision-contract.md`, the relevant component/runtime doc, and the failing test/log first |
-| Figma implementation | Use Figma MCP/design context, then `assembly-workflow.md` and the relevant component docs |
+| App assembly, route structure, generated app porting | `core/runtime-boundary.md`, `assembly-workflow.md`, `decision-contract.md` |
+| Reference app study, audit, or port | `core/reference-study.md`, `core/runtime-boundary.md`, `assembly-workflow.md`, `schema-reference.md`, `acceptance-testing.md`, `decision-contract.md` |
+| Schema, controls, defaults, persistence, actions | `core/control-selection.md`, `core/layout.md`, `schema-reference.md`, `component-rules.md`, `acceptance-testing.md` |
+| Custom controls | `core/control-selection.md`, `core/layout.md`, `custom-controls.md`, `component-rules.md`, `acceptance-testing.md` |
+| Renderer, canvas output, visual technique | `core/runtime-boundary.md`, `core/performance.md`, `renderer-technique.md`, `performance.md`, `acceptance-testing.md` |
+| Timeline, keyframes, animation transport | `core/timeline-animation.md`, `core/performance.md`, `decision-contract.md`, `component-rules.md`, `acceptance-testing.md` |
+| Layers | `core/runtime-boundary.md`, `core/layout.md`, `decision-contract.md`, `component-rules.md`, `acceptance-testing.md` |
+| Export, copy, media, background | `core/setup-export.md`, `core/media-upload.md`, `schema-reference.md`, `component-rules.md`, `acceptance-testing.md`, `performance.md` |
+| Broken control, visual mismatch, failed build, export bug, performance issue | `decision-contract.md`, the relevant `core/*` module, the relevant component/runtime doc, and the failing test/log first |
+| Figma implementation | Use Figma MCP/design context, then `core/reference-study.md`, `core/runtime-boundary.md`, `assembly-workflow.md`, and the relevant component docs |
 
 ## Worklog Gate
 

package/templates/starter/package.json

@@ -34,6 +34,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
+    "cross-spawn": "^7.0.6",
     "lucide-react": "^0.511.0",
     "motion": "^11.16.3",
     "react": "^19.2.0",

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

@@ -19,6 +19,17 @@ const requiredDocs = [
   "component-rules.md",
 ];
 
+const requiredCoreDocs = [
+  "core/runtime-boundary.md",
+  "core/setup-export.md",
+  "core/control-selection.md",
+  "core/layout.md",
+  "core/media-upload.md",
+  "core/timeline-animation.md",
+  "core/performance.md",
+  "core/reference-study.md",
+];
+
 const requiredProjectFiles = ["LICENSE.md", "NOTICE.md"];
 
 const requiredRuleIds = [
@@ -43,17 +54,21 @@ const requiredRuleIds = [
   "workflow-required",
 ];
 
-const requiredAgentsLinks = [
+const requiredAgentsEntryLinks = [
   "workflow.md",
+  "core/",
+];
+
+const requiredWorkflowLinks = [
+  ...requiredCoreDocs,
   "assembly-workflow.md",
   "decision-contract.md",
   "schema-reference.md",
+  "component-rules.md",
   "acceptance-testing.md",
   "performance.md",
   "renderer-technique.md",
-  "agent-worklog.md",
   "custom-controls.md",
-  "component-rules.md",
 ];
 
 const requiredWorkflowTerms = [
@@ -90,7 +105,7 @@ async function fileExists(relativePath) {
 
 const failures = [];
 
-for (const fileName of requiredDocs) {
+for (const fileName of [...requiredDocs, ...requiredCoreDocs]) {
   const relativePath = `docs/toolcraft/${fileName}`;
 
   if (!(await fileExists(relativePath))) {
@@ -118,12 +133,13 @@ for (const ruleId of requiredRuleIds) {
   }
 }
 
-for (const fileName of requiredDocs) {
+for (const fileName of [...requiredDocs, ...requiredCoreDocs]) {
   const source = await readText(`docs/toolcraft/${fileName}`);
   docsSources.push(source);
 }
 
 const combinedSource = docsSources.join("\n");
+const workflowSource = await readText("docs/toolcraft/workflow.md");
 
 for (const pattern of forbiddenTextPatterns) {
   if (pattern.test(combinedSource)) {
@@ -131,12 +147,18 @@ for (const pattern of forbiddenTextPatterns) {
   }
 }
 
-for (const localDoc of requiredAgentsLinks) {
+for (const localDoc of requiredAgentsEntryLinks) {
   if (!agentsSource.includes(`docs/toolcraft/${localDoc}`)) {
     failures.push(`AGENTS.md must link docs/toolcraft/${localDoc}`);
   }
 }
 
+for (const localDoc of requiredWorkflowLinks) {
+  if (!workflowSource.includes(localDoc)) {
+    failures.push(`docs/toolcraft/workflow.md must route to ${localDoc}`);
+  }
+}
+
 for (const term of requiredWorkflowTerms) {
   if (!agentsSource.includes(term)) {
     failures.push(`AGENTS.md must mention "${term}"`);

package/templates/starter/scripts/run-vite-on-free-port.mjs

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 
-import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import spawn from "cross-spawn";
 
 import {
   findAvailablePort,
@@ -14,6 +18,8 @@ import {
 } from "./toolcraft-port.mjs";
 
 const viteCommand = process.argv[2] ?? "dev";
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const projectDir = join(scriptDir, "..");
 const restartArg = "--toolcraft-restart";
 const rawPassthroughArgs = process.argv.slice(3).filter((arg) => arg !== "--");
 const restartSamePort =
@@ -49,7 +55,7 @@ if (savedPort) {
       process.exit(0);
     } catch (error) {
       console.error(
-        `Saved Toolcraft port ${savedPort} is busy, but it is not serving this app. Use pnpm dev:restart or pnpm preview:restart to reclaim the saved port, or remove .toolcraft/server-port.json to assign a new port. ${error?.message ?? ""}`.trim(),
+        `Saved Toolcraft port ${savedPort} is busy, but it is not serving this app. Use the restart script to reclaim the saved port, or remove .toolcraft/server-port.json to assign a new port. ${error?.message ?? ""}`.trim(),
       );
       process.exit(1);
     }
@@ -66,12 +72,25 @@ if (!port) {
   }
 }
 
-const pnpmCommand = process.platform === "win32" ? "pnpm.cmd" : "pnpm";
+const viteBinPath = join(
+  projectDir,
+  "node_modules",
+  ".bin",
+  process.platform === "win32" ? "vite.cmd" : "vite",
+);
+
+try {
+  await access(viteBinPath);
+} catch {
+  console.error(
+    "Vite is not installed. Run this app's dependency installation command before starting the dev server.",
+  );
+  process.exit(1);
+}
+
 const child = spawn(
-  pnpmCommand,
+  viteBinPath,
   [
-    "exec",
-    "vite",
     viteCommand,
     "--host",
     "127.0.0.1",

package/templates/starter/src/app/starter-acceptance.test.ts

@@ -554,8 +554,12 @@ function escapeRegExp(value: string): string {
 
 const incompleteRequiredCheckPattern =
   /\b(?:fail(?:ed|s|ing)?|not complete|not completed|incomplete|pending|blocked|planned|todo|to do|to run|will run|not run|not started|not yet|queued)\b/i;
+const packageScriptPrefixPattern = String.raw`(?:pnpm\s+|npm\s+run\s+)?`;
 const requiredCheckNamePattern =
-  /\b(?:(?:pnpm\s+)?(?:verify:final|verify:perf|test:browser:perf|test:browser|verify:quick|test|build)|browser performance checkpoint|agent-browser|playwright-fallback)\b/i;
+  new RegExp(
+    String.raw`\b(?:${packageScriptPrefixPattern}(?:verify:final|verify:perf|test:browser:perf|test:browser|verify:quick|test|build)|browser performance checkpoint|agent-browser|playwright-fallback)\b`,
+    "i",
+  );
 const browserPerformanceCheckpointPattern =
   /\b(?:agent-browser|browser performance checkpoint|performance checkpoint|verify:perf|test:browser:perf|playwright-fallback)\b/i;
 const fallbackPerfReasonPattern =
@@ -599,7 +603,7 @@ function isPassedAgentBrowserPerfRunLine(line: string): boolean {
 function isPassedPlaywrightFallbackPerfRunLine(line: string): boolean {
   return (
     isVerificationEvidenceLine(line) &&
-    (/\bpnpm\s+verify:perf\b/i.test(line) ||
+    (/\b(?:pnpm\s+verify:perf|npm\s+run\s+verify:perf|verify:perf)\b/i.test(line) ||
       (/\bplaywright-fallback\b/i.test(line) &&
         /\b(?:performance|perf|checkpoint)\b/i.test(line))) &&
     !isIncompleteOrSkippedLine(line)
@@ -643,7 +647,7 @@ function getAgentWorklogVerificationGateErrors(source: string): string[] {
 
   if (!hasPassedPerfRun && !hasAllowedPerfSkip) {
     errors.push(
-      "agent-worklog.md Verification must record the browser performance checkpoint for first working product delivery: use agent-browser when available, or `pnpm verify:perf` with an explicit fallback reason when no agent browser or CI/non-agent automation is used.",
+      "agent-worklog.md Verification must record the browser performance checkpoint for first working product delivery: use agent-browser when available, or this app's verify:perf script with an explicit fallback reason when no agent browser or CI/non-agent automation is used.",
     );
   }
 
@@ -721,7 +725,11 @@ function getAgentWorklogValidationErrors(source: string): string[] {
     );
   }
 
-  if (!/\bpnpm\s+(verify|test|build|typecheck)|browser|Playwright|perf/i.test(verificationBody)) {
+  if (
+    !/\b(?:pnpm\s+(?:verify|test|build|typecheck)|npm\s+run\s+(?:verify|test|build|typecheck)|browser|Playwright|perf)\b/i.test(
+      verificationBody,
+    )
+  ) {
     errors.push("agent-worklog.md Verification must list concrete test/build/browser/performance checks.");
   }
 
@@ -3182,19 +3190,20 @@ describe("Toolcraft template app acceptance coverage", () => {
   });
 
   it("documents control selection inventory and custom built-in fit checks", () => {
-    const schemaReference = readToolcraftDoc("schema-reference.md");
+    const coreControlSelection = readToolcraftDoc("core/control-selection.md");
     const componentRules = readToolcraftDoc("component-rules.md");
     const acceptanceTesting = readToolcraftDoc("acceptance-testing.md");
 
-    expect(schemaReference).toContain("Control Selection Inventory");
-    expect(schemaReference).toContain("Product need:");
-    expect(schemaReference).toContain("Candidate built-ins checked:");
-    expect(schemaReference).toContain("Rejected alternatives:");
+    expect(coreControlSelection).toContain("Control Selection Inventory");
+    expect(coreControlSelection).toContain("Product need:");
+    expect(coreControlSelection).toContain("Candidate built-ins checked:");
+    expect(coreControlSelection).toContain("Best built-in:");
+    expect(coreControlSelection).toContain("Rejected alternatives:");
+    expect(coreControlSelection).toContain("Target:");
+    expect(coreControlSelection).toContain("Custom Control Gate");
 
     expect(componentRules).toContain("Control Decision Catalog");
-    expect(componentRules).toContain("Exact owner");
-    expect(componentRules).toContain("Best fit");
-    expect(componentRules).toContain("Custom escape hatch");
+    expect(componentRules).toContain("core/control-selection.md");
 
     expect(acceptanceTesting).toContain("wrong-substitution");
     expect(acceptanceTesting).toContain("built-in fit check");
@@ -3689,7 +3698,7 @@ describe("Toolcraft template app acceptance coverage", () => {
       expect.arrayContaining([
         "agent-worklog.md required checks must be passed before final delivery; do not report failed, incomplete, pending, or blocked verification.",
         "agent-worklog.md must not list required checks as skipped unless they are explicitly not required for a post-first-working non-performance edit.",
-        "agent-worklog.md Verification must record the browser performance checkpoint for first working product delivery: use agent-browser when available, or `pnpm verify:perf` with an explicit fallback reason when no agent browser or CI/non-agent automation is used.",
+        "agent-worklog.md Verification must record the browser performance checkpoint for first working product delivery: use agent-browser when available, or this app's verify:perf script with an explicit fallback reason when no agent browser or CI/non-agent automation is used.",
       ]),
     );
   });
@@ -3775,7 +3784,7 @@ describe("Toolcraft template app acceptance coverage", () => {
     `;
 
     expect(getAgentWorklogValidationErrors(missingPerfWorklog)).toContain(
-      "agent-worklog.md Verification must record the browser performance checkpoint for first working product delivery: use agent-browser when available, or `pnpm verify:perf` with an explicit fallback reason when no agent browser or CI/non-agent automation is used.",
+      "agent-worklog.md Verification must record the browser performance checkpoint for first working product delivery: use agent-browser when available, or this app's verify:perf script with an explicit fallback reason when no agent browser or CI/non-agent automation is used.",
     );
   });
 
@@ -3992,7 +4001,7 @@ describe("Toolcraft template app acceptance coverage", () => {
     `;
 
     expect(getAgentWorklogValidationErrors(missingFallbackReasonWorklog)).toContain(
-      "agent-worklog.md Verification must record the browser performance checkpoint for first working product delivery: use agent-browser when available, or `pnpm verify:perf` with an explicit fallback reason when no agent browser or CI/non-agent automation is used.",
+      "agent-worklog.md Verification must record the browser performance checkpoint for first working product delivery: use agent-browser when available, or this app's verify:perf script with an explicit fallback reason when no agent browser or CI/non-agent automation is used.",
     );
   });
 

package/templates/starter/src/app/starter-performance.test.ts

@@ -321,6 +321,8 @@ describe("Toolcraft template app performance coverage", () => {
     const packageJson = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8")) as {
       scripts?: Record<string, string>;
     };
+    const runScriptPattern = (scriptName: string) =>
+      `(?:pnpm ${scriptName}|npm run ${scriptName})`;
 
     expect(
       packageJson.scripts?.["test:browser"],
@@ -332,14 +334,22 @@ describe("Toolcraft template app performance coverage", () => {
     ).toBe(
       'playwright install chromium && playwright test --grep "browser perf:" --workers=1 --pass-with-no-tests',
     );
-    expect(packageJson.scripts?.["verify:quick"]).toBe("pnpm ai:check && pnpm test");
-    expect(packageJson.scripts?.["verify:ui"]).toBe("pnpm test:browser");
-    expect(packageJson.scripts?.["verify:perf"]).toBe("pnpm test:browser:perf");
-    expect(packageJson.scripts?.["verify:perf:playwright"]).toBe(
-      "pnpm test:browser:perf",
+    expect(packageJson.scripts?.["verify:quick"]).toMatch(
+      new RegExp(`^${runScriptPattern("ai:check")} && ${runScriptPattern("test")}$`),
     );
-    expect(packageJson.scripts?.["verify:final"]).toBe(
-      "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser",
+    expect(packageJson.scripts?.["verify:ui"]).toMatch(
+      new RegExp(`^${runScriptPattern("test:browser")}$`),
+    );
+    expect(packageJson.scripts?.["verify:perf"]).toMatch(
+      new RegExp(`^${runScriptPattern("test:browser:perf")}$`),
+    );
+    expect(packageJson.scripts?.["verify:perf:playwright"]).toMatch(
+      new RegExp(`^${runScriptPattern("test:browser:perf")}$`),
+    );
+    expect(packageJson.scripts?.["verify:final"]).toMatch(
+      new RegExp(
+        `^${runScriptPattern("ai:check")} && ${runScriptPattern("test")} && ${runScriptPattern("build")} && ${runScriptPattern("test:browser")}$`,
+      ),
     );
   });