@pixel-point/toolcraft 0.0.8 → 0.0.11

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.8",
+  "version": "0.0.11",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
   "bin": {

package/src/generate.mjs

@@ -11,7 +11,11 @@ import {
   pathExists,
   removeDirectory,
 } from "./copy-recursive.mjs";
-import { createGeneratedPackageJson, createGeneratedTsConfig } from "./package-json.mjs";
+import {
+  createGeneratedPackageJson,
+  createGeneratedTsConfig,
+  normalizeProjectTitle,
+} from "./package-json.mjs";
 import { rewriteGeneratedText, rewriteTextFiles } from "./rewrite-imports.mjs";
 
 const PACKAGE_ROOT = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
@@ -21,6 +25,17 @@ function writeJson(filePath, value) {
   return fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
 }
 
+function escapeHtmlText(value) {
+  return String(value)
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
+function escapeHtmlAttribute(value) {
+  return escapeHtmlText(value).replaceAll('"', "&quot;");
+}
+
 async function readJson(filePath) {
   return JSON.parse(await fs.readFile(filePath, "utf8"));
 }
@@ -100,6 +115,25 @@ async function restoreGeneratedGitignore(targetDir) {
   await fs.rename(npmSafeGitignorePath, gitignorePath);
 }
 
+async function writeGeneratedProjectTitle(targetDir, title) {
+  const indexPath = path.join(targetDir, "index.html");
+  const source = await fs.readFile(indexPath, "utf8");
+  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}.`);
+  }
+
+  await fs.writeFile(indexPath, nextSource);
+}
+
 async function removeToolcraftTestFiles(toolcraftRoot) {
   async function visit(currentDir) {
     const entries = await fs.readdir(currentDir, { withFileTypes: true });
@@ -190,6 +224,12 @@ export async function generateToolcraft(options = {}) {
   await assertDirectory(sourcePaths.uiSrc, "UI package source");
   await assertDirectory(sourcePaths.toolcraftSrc, "Toolcraft template runtime package source");
   const starterPackageJson = await readJson(path.join(sourcePaths.starterDir, "package.json"));
+  const packageJson = createGeneratedPackageJson({
+    name: options.name ?? path.basename(targetDir),
+    starterPackageJson,
+  });
+  const projectTitle = normalizeProjectTitle(packageJson.name);
+
   await ensureWritableTargetDirectory(targetDir, { force: options.force });
 
   await copyDirectory(sourcePaths.starterDir, targetDir);
@@ -206,11 +246,8 @@ export async function generateToolcraft(options = {}) {
   const changedFiles = await rewriteTextFiles(targetDir, (source) =>
     rewriteGeneratedAppText(source),
   );
+  await writeGeneratedProjectTitle(targetDir, projectTitle);
   await writeToolcraftIntegrityManifest(toolcraftRoot);
-  const packageJson = createGeneratedPackageJson({
-    name: options.name ?? path.basename(targetDir),
-    starterPackageJson,
-  });
 
   await writeJson(path.join(targetDir, "package.json"), packageJson);
   await writeJson(path.join(targetDir, "tsconfig.json"), createGeneratedTsConfig());

package/src/generate.test.mjs

@@ -79,7 +79,15 @@ describe("generateToolcraft", () => {
     assert.equal(packageJson.devDependencies["@playwright/test"], "^1.51.1");
     assert.equal(packageJson.scripts["ai:check"], "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,
@@ -93,11 +101,16 @@ describe("generateToolcraft", () => {
     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",
     );
 
+    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(
       path.join(targetDir, "playwright.config.ts"),
@@ -121,6 +134,7 @@ describe("generateToolcraft", () => {
     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/);
     assert.ok(await fs.stat(path.join(targetDir, "scripts/check-ai-skills.mjs")));
     assert.ok(await fs.stat(path.join(targetDir, "scripts/toolcraft-port.mjs")));
@@ -146,6 +160,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,
@@ -325,4 +342,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" \/>/,
+    );
+  });
 });

package/src/package-json.mjs

@@ -9,6 +9,21 @@ export function sanitizePackageName(value) {
   return sanitized || "toolcraft-app";
 }
 
+export function normalizeProjectTitle(value) {
+  const words = String(value ?? "")
+    .trim()
+    .replace(/^@/, "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean);
+
+  const title = words
+    .map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1).toLowerCase()}`)
+    .join(" ");
+
+  return title || "Toolcraft App";
+}
+
 function isWorkspaceDependency(name, specifier) {
   return name.startsWith("@repo/") || String(specifier).startsWith("workspace:");
 }

package/src/package-json.test.mjs

@@ -1,7 +1,11 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 
-import { createGeneratedPackageJson, sanitizePackageName } from "./package-json.mjs";
+import {
+  createGeneratedPackageJson,
+  normalizeProjectTitle,
+  sanitizePackageName,
+} from "./package-json.mjs";
 
 describe("sanitizePackageName", () => {
   it("normalizes package names for generated apps", () => {
@@ -11,6 +15,15 @@ describe("sanitizePackageName", () => {
   });
 });
 
+describe("normalizeProjectTitle", () => {
+  it("creates a human-readable title from generated project names", () => {
+    assert.equal(normalizeProjectTitle("mesh-gradient"), "Mesh Gradient");
+    assert.equal(normalizeProjectTitle("mesh_gradient.app"), "Mesh Gradient App");
+    assert.equal(normalizeProjectTitle("@pixel-point/mesh-gradient"), "Pixel Point Mesh Gradient");
+    assert.equal(normalizeProjectTitle(""), "Toolcraft App");
+  });
+});
+
 describe("createGeneratedPackageJson", () => {
   it("uses the starter package manifest as source of truth", () => {
     const packageJson = createGeneratedPackageJson({