@pixel-point/toolcraft 0.0.11 → 0.0.13

package/README.md

@@ -19,7 +19,7 @@ tools for client work.
 npx @pixel-point/toolcraft create
 ```
 
-The create command uses the current directory when no target directory is passed, prompts for missing project values in an interactive terminal, generates the app, runs `pnpm install`, then prints the command to start the dev server.
+The create command uses the current directory when no target directory is passed, prompts for missing project values in an interactive terminal, generates the app, runs dependency installation with the package manager that launched the CLI, then prints the command to start the dev server.
 
 After dependencies are installed, Toolcraft installs the required workflow skills
 in a batch through the `skills` CLI. The skill installer uses the same agent,
@@ -30,7 +30,7 @@ Example:
 ```bash
 npx @pixel-point/toolcraft create my-ascii-tool
 cd my-ascii-tool
-pnpm dev
+npm run dev
 ```
 
 Then open the generated folder in Codex, Claude Code, Cursor, or another AI
@@ -46,6 +46,8 @@ Scripted usage:
 npx @pixel-point/toolcraft create my-toolcraft-app --name my-toolcraft-app --yes --force
 ```
 
+Toolcraft detects `npm` and `pnpm` from the package manager user agent. For example, `npx @pixel-point/toolcraft create` generates npm-flavored setup commands, while `pnpm dlx @pixel-point/toolcraft create` generates pnpm-flavored setup commands.
+
 Install Toolcraft skills to specific agents or locations:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixel-point/toolcraft",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "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,4 +1,3 @@
-import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -16,8 +15,14 @@ import {
   text,
 } from "@clack/prompts";
 
+import { runCommand } from "./command-runner.mjs";
 import { pathExists } from "./copy-recursive.mjs";
+import { installGeneratedAppDependencies } from "./dependency-install.mjs";
 import { generateToolcraft } from "./generate.mjs";
+import {
+  createRunScriptCommand,
+  detectPackageManager,
+} from "./package-manager.mjs";
 import { sanitizePackageName } from "./package-json.mjs";
 
 const DEFAULT_PROJECT_NAME = "my-toolcraft-app";
@@ -355,31 +360,6 @@ export async function resolveCreateOptions(parsedOptions, context = {}) {
   };
 }
 
-function runCommand(command, args, options = {}, context = {}) {
-  if (context.runCommand) {
-    return context.runCommand(command, args, options);
-  }
-
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
-      cwd: options.cwd,
-      env: options.env,
-      shell: process.platform === "win32",
-      stdio: options.stdio ?? "inherit",
-    });
-
-    child.on("error", reject);
-    child.on("exit", (exitCode) => {
-      if (exitCode === 0) {
-        resolve();
-        return;
-      }
-
-      reject(new Error(`${command} ${args.join(" ")} failed with exit code ${exitCode}.`));
-    });
-  });
-}
-
 function getSkillsCliPath(context = {}) {
   if (context.skillsCliPath) {
     return context.skillsCliPath;
@@ -439,6 +419,7 @@ async function installToolcraftSkills(parsedOptions, targetDir, context = {}) {
         ...process.env,
         ...(context.env ?? {}),
       },
+      shell: false,
       stdio: "inherit",
     },
     context,
@@ -458,7 +439,7 @@ function writeFinalSummary(stdout, result, createOptions) {
       : result.relativeTargetDir;
     writeLine(stdout, `  cd ${displayTargetDir}`);
   }
-  writeLine(stdout, "  pnpm dev");
+  writeLine(stdout, `  ${createRunScriptCommand(createOptions.packageManager, "dev")}`);
 }
 
 export async function runCreateCommand(parsedOptions, context = {}) {
@@ -470,6 +451,7 @@ export async function runCreateCommand(parsedOptions, context = {}) {
     intro("Create Toolcraft app");
   }
 
+  const packageManager = detectPackageManager(context.env ?? process.env);
   const createOptions = await resolveCreateOptions(parsedOptions, context);
 
   const result = await runWithSpinner(context, "Creating Toolcraft app...", "Created app", () =>
@@ -477,26 +459,19 @@ export async function runCreateCommand(parsedOptions, context = {}) {
       cwd,
       force: createOptions.force,
       name: createOptions.name,
+      packageManager,
       targetDir: createOptions.targetDir,
     }),
   );
 
   if (createOptions.install) {
-    writeLine(stdout, "");
-    writeLine(stdout, "Installing dependencies with pnpm...");
-    await runCommand(
-      "pnpm",
-      ["install"],
-      {
-        cwd: result.targetDir,
-        env: {
-          ...process.env,
-          ...(context.env ?? {}),
-        },
-        stdio: "inherit",
-      },
+    await installGeneratedAppDependencies({
       context,
-    );
+      packageManager,
+      result,
+      skillsRequested: createOptions.skills,
+      stdout,
+    });
   }
 
   if (createOptions.skills) {
@@ -508,12 +483,12 @@ export async function runCreateCommand(parsedOptions, context = {}) {
   if (usingClack) {
     const nextSteps = [
       ...(result.targetDir === cwd ? [] : [`cd ${result.relativeTargetDir}`]),
-      "pnpm dev",
+      createRunScriptCommand(packageManager, "dev"),
     ].join("\n");
     note(nextSteps, "Next steps");
     outro(`Created ${result.packageName}`);
   } else {
-    writeFinalSummary(stdout, result, { ...createOptions, cwd });
+    writeFinalSummary(stdout, result, { ...createOptions, cwd, packageManager });
   }
 
   return result;
@@ -548,7 +523,7 @@ Options:
   --copy           Copy skills instead of using the skills CLI default link behavior.
   --all            Install Toolcraft skills to all supported agents without skills prompts.
   --no-skills      Skip Toolcraft skills installation.
-  --no-install     Skip automatic pnpm install. Intended for local CLI tests and automation.
+  --no-install     Skip automatic dependency installation. Intended for local CLI tests and automation.
   --help, -h       Show this help message.`;
 }
 

package/src/cli.test.mjs

@@ -206,7 +206,7 @@ describe("runToolcraftCli", () => {
     assert.ok(await fs.stat(path.join(tempRoot, "src/app/app-schema.ts")));
     assert.match(stdout.text, new RegExp(`Created ${path.basename(tempRoot).toLowerCase()}`));
     assert.doesNotMatch(stdout.text, /cd /);
-    assert.match(stdout.text, /pnpm dev/);
+    assert.match(stdout.text, /npm run dev/);
     assert.equal(stderr.text, "");
   });
 
@@ -239,12 +239,12 @@ describe("runToolcraftCli", () => {
     assert.ok(await fs.stat(path.join(tempRoot, "generated-app/src/app/app-schema.ts")));
     assert.match(stdout.text, /Created generated-app/);
     assert.match(stdout.text, /cd generated-app/);
-    assert.match(stdout.text, /pnpm dev/);
+    assert.match(stdout.text, /npm run dev/);
     assert.doesNotMatch(stdout.text, /pnpm verify:final/);
     assert.equal(stderr.text, "");
   });
 
-  it("runs pnpm install and Toolcraft skills install by default after creating the app", async () => {
+  it("runs npm install and Toolcraft skills install when launched through npx", async () => {
     const tempRoot = await createTempRoot();
     const stdout = createWritableCapture();
     const installs = [];
@@ -253,33 +253,170 @@ describe("runToolcraftCli", () => {
 
     await runToolcraftCli(["create", "install-app", "--name", "Install App", "--yes", "--force"], {
       cwd: tempRoot,
-      env: {},
+      env: {
+        npm_config_user_agent: "npm/10.9.4 node/v24.4.1 darwin arm64",
+      },
       stdout,
       skillsCliPath,
       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 });
       },
     });
 
     assert.deepEqual(installs, [
       {
         args: ["install"],
-        command: "pnpm",
+        command: "npm",
         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/);
+    assert.match(stdout.text, /Installing dependencies with npm/);
     assert.match(stdout.text, /Installing Toolcraft skills/);
+    assert.match(stdout.text, /npm run dev/);
+
+    const packageJson = JSON.parse(
+      await fs.readFile(path.join(tempRoot, "install-app/package.json"), "utf8"),
+    );
+    assert.equal(
+      packageJson.scripts["verify:final"],
+      "npm run ai:check && npm run test && npm run build && npm run test:browser",
+    );
+
+    const playwrightConfigSource = await fs.readFile(
+      path.join(tempRoot, "install-app/playwright.config.ts"),
+      "utf8",
+    );
+    assert.match(playwrightConfigSource, /npm exec -- vite dev/);
+  });
+
+  it("runs pnpm install when launched through pnpm", async () => {
+    const tempRoot = await createTempRoot();
+    const stdout = createWritableCapture();
+    const installs = [];
+
+    await runToolcraftCli(
+      ["create", "pnpm-app", "--name", "Pnpm App", "--yes", "--force", "--no-skills"],
+      {
+        cwd: tempRoot,
+        env: {
+          npm_config_user_agent: "pnpm/10.0.0 npm/? node/v24.4.1 darwin arm64",
+        },
+        stdout,
+        throwOnError: true,
+        async runCommand(command, args, options) {
+          installs.push({ args, command, cwd: options.cwd, shell: options.shell });
+        },
+      },
+    );
+
+    assert.deepEqual(installs, [
+      {
+        args: ["install"],
+        command: "pnpm",
+        cwd: path.join(tempRoot, "pnpm-app"),
+        shell: false,
+      },
+    ]);
+    assert.match(stdout.text, /Installing dependencies with pnpm/);
     assert.match(stdout.text, /pnpm dev/);
   });
 
+  it("reports recovery steps when dependency installation command is missing", async () => {
+    const tempRoot = await createTempRoot();
+    const stdout = createWritableCapture();
+    const stderr = createWritableCapture();
+    const commands = [];
+    let exitCode;
+
+    const result = await runToolcraftCli(
+      ["create", "missing-npm-app", "--name", "Missing Npm App", "--yes", "--force"],
+      {
+        cwd: tempRoot,
+        env: {
+          npm_config_user_agent: "npm/10.9.4 node/v24.4.1 darwin arm64",
+        },
+        stderr,
+        stdout,
+        setExitCode(value) {
+          exitCode = value;
+        },
+        async runCommand(command, args, options) {
+          commands.push({ args, command, cwd: options.cwd });
+          const error = new Error("spawn npm ENOENT");
+          error.code = "ENOENT";
+          throw error;
+        },
+      },
+    );
+
+    assert.equal(result.ok, false);
+    assert.equal(exitCode, 1);
+    assert.deepEqual(commands, [
+      {
+        args: ["install"],
+        command: "npm",
+        cwd: path.join(tempRoot, "missing-npm-app"),
+      },
+    ]);
+    assert.ok(await fs.stat(path.join(tempRoot, "missing-npm-app/src/app/app-schema.ts")));
+    assert.match(stderr.text, /Toolcraft app created at .*missing-npm-app, but setup did not finish/);
+    assert.match(stderr.text, /npm was not found in PATH/);
+    assert.match(stderr.text, /cd .*missing-npm-app/);
+    assert.match(stderr.text, /npm install/);
+    assert.match(stderr.text, /Toolcraft skills were not installed/);
+    assert.match(stderr.text, /npm run dev/);
+    assert.doesNotMatch(stdout.text, /Installing Toolcraft skills/);
+  });
+
+  it("does not mention skipped skills when dependency installation fails with --no-skills", async () => {
+    const tempRoot = await createTempRoot();
+    const stdout = createWritableCapture();
+    const stderr = createWritableCapture();
+    let exitCode;
+
+    const result = await runToolcraftCli(
+      [
+        "create",
+        "missing-npm-no-skills-app",
+        "--name",
+        "Missing Npm No Skills App",
+        "--yes",
+        "--force",
+        "--no-skills",
+      ],
+      {
+        cwd: tempRoot,
+        env: {
+          npm_config_user_agent: "npm/10.9.4 node/v24.4.1 darwin arm64",
+        },
+        stderr,
+        stdout,
+        setExitCode(value) {
+          exitCode = value;
+        },
+        async runCommand() {
+          const error = new Error("spawn npm ENOENT");
+          error.code = "ENOENT";
+          throw error;
+        },
+      },
+    );
+
+    assert.equal(result.ok, false);
+    assert.equal(exitCode, 1);
+    assert.match(stderr.text, /npm was not found in PATH/);
+    assert.doesNotMatch(stderr.text, /Toolcraft skills were not installed/);
+  });
+
   it("forwards skills add compatible options", async () => {
     const tempRoot = await createTempRoot();
     const skillsCommands = [];
@@ -308,7 +445,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 +468,7 @@ describe("runToolcraftCli", () => {
         ],
         command: process.execPath,
         cwd: path.join(tempRoot, "skills-options-app"),
+        shell: false,
       },
     ]);
   });

package/src/command-runner.mjs

@@ -0,0 +1,71 @@
+import spawn from "cross-spawn";
+
+export class CommandRunError extends Error {
+  constructor(command, args, options, details = {}) {
+    super(details.message);
+    this.name = "CommandRunError";
+    this.args = args;
+    this.code = details.code;
+    this.command = command;
+    this.cwd = options.cwd;
+    this.exitCode = details.exitCode;
+    this.signal = details.signal;
+  }
+}
+
+export function getErrorCode(error) {
+  return error && typeof error === "object" ? error.code : undefined;
+}
+
+export function runCommand(command, args, options = {}, context = {}) {
+  if (context.runCommand) {
+    return context.runCommand(command, args, options);
+  }
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const settle = (callback) => {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      callback();
+    };
+
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env,
+      shell: options.shell ?? false,
+      stdio: options.stdio ?? "inherit",
+    });
+
+    child.on("error", (error) => {
+      settle(() =>
+        reject(
+          new CommandRunError(command, args, options, {
+            code: error.code,
+            message:
+              error.code === "ENOENT" ? `Command not found: ${command}` : error.message,
+          }),
+        ),
+      );
+    });
+    child.on("close", (exitCode, signal) => {
+      settle(() => {
+        if (exitCode === 0) {
+          resolve();
+          return;
+        }
+
+        reject(
+          new CommandRunError(command, args, options, {
+            exitCode,
+            message: `${command} ${args.join(" ")} failed with exit code ${exitCode}.`,
+            signal,
+          }),
+        );
+      });
+    });
+  });
+}

package/src/dependency-install.mjs

@@ -0,0 +1,87 @@
+import { getErrorCode, runCommand } from "./command-runner.mjs";
+import {
+  createInstallCommand,
+  createInstallHelp,
+  createRunScriptCommand,
+  normalizePackageManager,
+} from "./package-manager.mjs";
+
+function writeLine(stream, message = "") {
+  stream.write(`${message}\n`);
+}
+
+export function createDependencyInstallError(
+  error,
+  result,
+  packageManager,
+  { skillsRequested = true } = {},
+) {
+  const normalizedPackageManager = normalizePackageManager(packageManager);
+  const installCommand = `${normalizedPackageManager} install`;
+  const devCommand = createRunScriptCommand(normalizedPackageManager, "dev");
+  const commandMissing = getErrorCode(error) === "ENOENT";
+  const lines = [`Toolcraft app created at ${result.targetDir}, but setup did not finish.`, ""];
+
+  if (commandMissing) {
+    lines.push(
+      `Dependency installation failed because ${normalizedPackageManager} was not found in PATH.`,
+      "",
+      `Install ${normalizedPackageManager}:`,
+      "",
+      ...createInstallHelp(normalizedPackageManager),
+    );
+  } else {
+    lines.push(
+      "Dependency installation failed while running:",
+      "",
+      `  ${installCommand}`,
+      "",
+      `Original error: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  lines.push("", "Then finish setup:", "", `  cd ${result.targetDir}`, `  ${installCommand}`);
+
+  if (skillsRequested) {
+    lines.push("", "Toolcraft skills were not installed because dependency installation failed.");
+  }
+
+  lines.push("", "After setup, start the app with:", "", `  ${devCommand}`);
+
+  return new Error(lines.join("\n"));
+}
+
+export async function installGeneratedAppDependencies({
+  context = {},
+  packageManager,
+  result,
+  skillsRequested = true,
+  stdout,
+}) {
+  const normalizedPackageManager = normalizePackageManager(packageManager);
+  const installCommand = createInstallCommand(normalizedPackageManager);
+
+  writeLine(stdout, "");
+  writeLine(stdout, `Installing dependencies with ${normalizedPackageManager}...`);
+
+  try {
+    await runCommand(
+      installCommand.command,
+      installCommand.args,
+      {
+        cwd: result.targetDir,
+        env: {
+          ...process.env,
+          ...(context.env ?? {}),
+        },
+        shell: false,
+        stdio: "inherit",
+      },
+      context,
+    );
+  } catch (error) {
+    throw createDependencyInstallError(error, result, normalizedPackageManager, {
+      skillsRequested,
+    });
+  }
+}

package/src/generate.mjs

@@ -11,6 +11,11 @@ import {
   pathExists,
   removeDirectory,
 } from "./copy-recursive.mjs";
+import {
+  DEFAULT_PACKAGE_MANAGER,
+  normalizePackageManager,
+  replaceGeneratedCommandReferences,
+} from "./package-manager.mjs";
 import {
   createGeneratedPackageJson,
   createGeneratedTsConfig,
@@ -50,8 +55,29 @@ function createRelativePath(fromDir, toDir) {
   return relativePath === "" ? "." : relativePath;
 }
 
-function rewriteGeneratedAppText(source) {
-  return rewriteGeneratedText(source)
+function shouldReplacePackageManagerCommands(filePath, targetDir) {
+  const relativePath = path.relative(targetDir, filePath).split(path.sep).join("/");
+
+  return (
+    relativePath === "AGENTS.md" ||
+    relativePath === "playwright.config.ts" ||
+    relativePath === "scripts/check-toolcraft-docs.mjs" ||
+    /^docs\/toolcraft\/.+\.md$/.test(relativePath)
+  );
+}
+
+function rewriteGeneratedAppText(
+  source,
+  filePath,
+  { packageManager = DEFAULT_PACKAGE_MANAGER, targetDir } = {},
+) {
+  const rewrittenSource = rewriteGeneratedText(source);
+  const commandSource =
+    targetDir && shouldReplacePackageManagerCommands(filePath, targetDir)
+      ? replaceGeneratedCommandReferences(rewrittenSource, packageManager)
+      : rewrittenSource;
+
+  return commandSource
     .replaceAll("starterAcceptance", "appAcceptance")
     .replaceAll("starter-acceptance", "app-acceptance")
     .replaceAll("starterProductReadiness", "appProductReadiness")
@@ -218,6 +244,7 @@ export function getDefaultSourcePaths(repoRoot = REPO_ROOT) {
 export async function generateToolcraft(options = {}) {
   const cwd = options.cwd ?? process.cwd();
   const targetDir = path.resolve(cwd, options.targetDir ?? ".");
+  const packageManager = normalizePackageManager(options.packageManager ?? DEFAULT_PACKAGE_MANAGER);
   const sourcePaths = options.sourcePaths ?? getDefaultSourcePaths(options.repoRoot ?? REPO_ROOT);
 
   await assertDirectory(sourcePaths.starterDir, "Starter app");
@@ -226,6 +253,7 @@ export async function generateToolcraft(options = {}) {
   const starterPackageJson = await readJson(path.join(sourcePaths.starterDir, "package.json"));
   const packageJson = createGeneratedPackageJson({
     name: options.name ?? path.basename(targetDir),
+    packageManager,
     starterPackageJson,
   });
   const projectTitle = normalizeProjectTitle(packageJson.name);
@@ -243,8 +271,8 @@ export async function generateToolcraft(options = {}) {
   await copyDirectory(sourcePaths.toolcraftSrc, path.join(toolcraftRoot, "runtime"));
   await removeToolcraftTestFiles(toolcraftRoot);
 
-  const changedFiles = await rewriteTextFiles(targetDir, (source) =>
-    rewriteGeneratedAppText(source),
+  const changedFiles = await rewriteTextFiles(targetDir, (source, filePath) =>
+    rewriteGeneratedAppText(source, filePath, { packageManager, targetDir }),
   );
   await writeGeneratedProjectTitle(targetDir, projectTitle);
   await writeToolcraftIntegrityManifest(toolcraftRoot);