@pixel-point/toolcraft 0.0.9 → 0.0.12

package/README.md

@@ -1,6 +1,19 @@
 # Toolcraft CLI
 
-Package entrypoint for creating standalone Toolcraft apps.
+Create standalone Toolcraft apps from the command line.
+
+Toolcraft is a Pixel Point starter kit and UI/runtime library for building
+personal creative design tools with AI. It gives generated apps a ready canvas,
+control panel, export flow, AI workflow instructions, and verification checks so
+you can focus prompts on the visual idea instead of rebuilding common creative
+tool plumbing.
+
+You use Toolcraft when a custom tool is faster or clearer than forcing a broad
+design app to fit one specific job: procedural graphics, image effects, branded
+asset generators, animation controllers, shader experiments, or quick visual
+tools for client work.
+
+## Usage
 
 ```bash
 npx @pixel-point/toolcraft create
@@ -12,14 +25,20 @@ After dependencies are installed, Toolcraft installs the required workflow skill
 in a batch through the `skills` CLI. The skill installer uses the same agent,
 scope, and installation prompts as `npx skills add`.
 
-## License
+Example:
 
-Toolcraft is distributed under the Toolcraft Designer License in `LICENSE.md`.
-Designer client work is permitted under that license. Using AI coding assistants
-or agents such as Codex, Claude, ChatGPT, Cursor, or similar tools to work on
-generated apps is permitted. Platform, generator, AI software product,
-app-builder, website-builder, template-marketplace, and resale uses require a
-separate commercial license from Pixel Point.
+```bash
+npx @pixel-point/toolcraft create my-ascii-tool
+cd my-ascii-tool
+pnpm dev
+```
+
+Then open the generated folder in Codex, Claude Code, Cursor, or another AI
+coding agent and prompt for the creative output you want, for example:
+
+```text
+Build an app that applies an ASCII effect to an uploaded image.
+```
 
 Scripted usage:
 
@@ -50,5 +69,19 @@ Local tarball test, matching the published package layout:
 cd cli
 npm pack --pack-destination /tmp
 cd ..
-TOOLCRAFT_SKIP_INSTALL=1 TOOLCRAFT_SKIP_SKILLS=1 npm exec --package /tmp/pixel-point-toolcraft-0.0.2.tgz -- toolcraft create /tmp/toolcraft-pack-exec-test --name pack-exec-test --yes --force
+TOOLCRAFT_SKIP_INSTALL=1 TOOLCRAFT_SKIP_SKILLS=1 npm exec --package /tmp/pixel-point-toolcraft-0.0.10.tgz -- toolcraft create /tmp/toolcraft-pack-exec-test --name pack-exec-test --yes --force
 ```
+
+## Learn more
+
+- [How to craft personal design tools with AI](https://pixelpoint.io/blog/how-to-craft-personal-design-tools-with-toolcraft/)
+- [Toolcraft YouTube tutorial](https://youtu.be/-QlmkGZLzFo)
+
+## License
+
+Toolcraft is distributed under the Toolcraft Designer License in `LICENSE.md`.
+Designer client work is permitted under that license. Using AI coding assistants
+or agents such as Codex, Claude, ChatGPT, Cursor, or similar tools to work on
+generated apps is permitted. Platform, generator, AI software product,
+app-builder, website-builder, template-marketplace, and resale uses require a
+separate commercial license from Pixel Point.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixel-point/toolcraft",
-  "version": "0.0.9",
+  "version": "0.0.12",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
   "bin": {
@@ -24,6 +24,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.6.0",
+    "cross-spawn": "^7.0.6",
     "skills": "^1.5.12"
   }
 }

package/src/cli.mjs

@@ -1,10 +1,10 @@
-import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import fs from "node:fs/promises";
 import path from "node:path";
 import readline from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 
+import spawn from "cross-spawn";
 import {
   cancel,
   confirm,
@@ -364,7 +364,7 @@ function runCommand(command, args, options = {}, context = {}) {
     const child = spawn(command, args, {
       cwd: options.cwd,
       env: options.env,
-      shell: process.platform === "win32",
+      shell: options.shell ?? false,
       stdio: options.stdio ?? "inherit",
     });
 
@@ -439,6 +439,7 @@ async function installToolcraftSkills(parsedOptions, targetDir, context = {}) {
         ...process.env,
         ...(context.env ?? {}),
       },
+      shell: false,
       stdio: "inherit",
     },
     context,
@@ -493,6 +494,7 @@ export async function runCreateCommand(parsedOptions, context = {}) {
           ...process.env,
           ...(context.env ?? {}),
         },
+        shell: false,
         stdio: "inherit",
       },
       context,

package/src/cli.test.mjs

@@ -259,7 +259,7 @@ describe("runToolcraftCli", () => {
       throwOnError: true,
       toolcraftSkillsSourceDir: skillsSourceDir,
       async runCommand(command, args, options) {
-        installs.push({ args, command, cwd: options.cwd });
+        installs.push({ args, command, cwd: options.cwd, shell: options.shell });
       },
     });
 
@@ -268,11 +268,13 @@ describe("runToolcraftCli", () => {
         args: ["install"],
         command: "pnpm",
         cwd: path.join(tempRoot, "install-app"),
+        shell: false,
       },
       {
         args: [skillsCliPath, "add", skillsSourceDir, "--skill", "*", "--yes"],
         command: process.execPath,
         cwd: path.join(tempRoot, "install-app"),
+        shell: false,
       },
     ]);
     assert.match(stdout.text, /Installing dependencies with pnpm/);
@@ -308,7 +310,7 @@ describe("runToolcraftCli", () => {
         throwOnError: true,
         toolcraftSkillsSourceDir: skillsSourceDir,
         async runCommand(command, args, options) {
-          skillsCommands.push({ args, command, cwd: options.cwd });
+          skillsCommands.push({ args, command, cwd: options.cwd, shell: options.shell });
         },
       },
     );
@@ -331,6 +333,7 @@ describe("runToolcraftCli", () => {
         ],
         command: process.execPath,
         cwd: path.join(tempRoot, "skills-options-app"),
+        shell: false,
       },
     ]);
   });

package/src/generate.mjs

@@ -32,6 +32,10 @@ function escapeHtmlText(value) {
     .replaceAll(">", ">");
 }
 
+function escapeHtmlAttribute(value) {
+  return escapeHtmlText(value).replaceAll('"', """);
+}
+
 async function readJson(filePath) {
   return JSON.parse(await fs.readFile(filePath, "utf8"));
 }
@@ -114,12 +118,16 @@ async function restoreGeneratedGitignore(targetDir) {
 async function writeGeneratedProjectTitle(targetDir, title) {
   const indexPath = path.join(targetDir, "index.html");
   const source = await fs.readFile(indexPath, "utf8");
-  const nextSource = source.replace(
-    /<title>.*?<\/title>/,
-    `<title>${escapeHtmlText(title)}</title>`,
-  );
-
-  if (nextSource === source) {
+  const escapedTitle = escapeHtmlText(title);
+  const escapedTitleAttribute = escapeHtmlAttribute(title);
+  const withTitle = source.replace(/<title>.*?<\/title>/, `<title>${escapedTitle}</title>`);
+  const identityMeta = `<meta name="toolcraft-app-title" content="${escapedTitleAttribute}" />`;
+  const identityMetaPattern = /<meta\b(?=[^>]*\bname=["']toolcraft-app-title["'])[^>]*>/i;
+  const nextSource = identityMetaPattern.test(withTitle)
+    ? withTitle.replace(identityMetaPattern, identityMeta)
+    : withTitle.replace(/<head>/i, `<head>\n    ${identityMeta}`);
+
+  if (!nextSource.includes(`<title>${escapedTitle}</title>`) || !nextSource.includes(identityMeta)) {
     throw new Error(`Unable to update generated app title in ${indexPath}.`);
   }
 

package/src/generate.test.mjs

@@ -93,14 +93,18 @@ describe("generateToolcraft", () => {
       packageJson.scripts.test,
       "node scripts/check-toolcraft-docs.mjs && node scripts/check-toolcraft-integrity.mjs && node --test scripts/*.test.mjs && vitest run src --passWithNoTests",
     );
-    assert.equal(packageJson.scripts["test:browser"], "playwright install chromium && playwright test");
+    assert.equal(
+      packageJson.scripts["test:browser"],
+      'playwright install chromium && playwright test --grep-invert "browser perf:"',
+    );
     assert.equal(
       packageJson.scripts["test:browser:perf"],
-      "playwright install chromium && playwright test e2e/app-performance.spec.ts --workers=1 && playwright test --grep \"browser perf:\" --workers=1 --pass-with-no-tests",
+      "playwright install chromium && playwright test --grep \"browser perf:\" --workers=1 --pass-with-no-tests",
     );
     assert.equal(packageJson.scripts["verify:quick"], "pnpm ai:check && pnpm test");
     assert.equal(packageJson.scripts["verify:ui"], "pnpm test:browser");
     assert.equal(packageJson.scripts["verify:perf"], "pnpm test:browser:perf");
+    assert.equal(packageJson.scripts["verify:perf:playwright"], "pnpm test:browser:perf");
     assert.equal(
       packageJson.scripts["verify:final"],
       "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser",
@@ -108,6 +112,7 @@ describe("generateToolcraft", () => {
 
     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" \/>/);
 
     assert.ok(await fs.stat(path.join(targetDir, "playwright.config.ts")));
     const playwrightConfigSource = await fs.readFile(
@@ -158,6 +163,9 @@ describe("generateToolcraft", () => {
       "utf8",
     );
     assert.match(appPerformanceSource, /defineToolcraftPerformance/);
+    assert.match(appPerformanceSource, /preferredRunner:\s*"agent-browser"/);
+    assert.match(appPerformanceSource, /fallbackRunner:\s*"playwright"/);
+    assert.match(appPerformanceSource, /agent-browser-unavailable/);
     assert.doesNotMatch(appPerformanceSource, /function\s+validateToolcraftPerformanceCoverage/);
     assert.doesNotMatch(
       appPerformanceSource,
@@ -337,4 +345,27 @@ describe("generateToolcraft", () => {
       /Target directory is not empty/,
     );
   });
+
+  it("writes the app identity marker when the generated title matches the template title", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-cli-"));
+    tempRoots.push(tempRoot);
+
+    await generateToolcraft({
+      cwd: tempRoot,
+      force: true,
+      name: "toolcraft-app-template",
+      targetDir: "toolcraft-app-template",
+    });
+
+    const indexHtmlSource = await fs.readFile(
+      path.join(tempRoot, "toolcraft-app-template", "index.html"),
+      "utf8",
+    );
+
+    assert.match(indexHtmlSource, /<title>Toolcraft App Template<\/title>/);
+    assert.match(
+      indexHtmlSource,
+      /<meta name="toolcraft-app-title" content="Toolcraft App Template" \/>/,
+    );
+  });
 });