@pixel-point/toolcraft 0.0.14 → 0.0.15

package/src/cli.test.mjs

@@ -7,7 +7,12 @@ import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { after, describe, it } from "node:test";
 
-import { parseCreateArgs, resolveCreateOptions, runToolcraftCli } from "./cli.mjs";
+import {
+  getCreateHelp,
+  parseCreateArgs,
+  resolveCreateOptions,
+  runToolcraftCli,
+} from "./cli.mjs";
 
 const execFileAsync = promisify(execFile);
 const packageRoot = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
@@ -35,6 +40,14 @@ async function createTempRoot() {
 }
 
 describe("parseCreateArgs", () => {
+  it("documents force creation as destructive and not an in-place migration", () => {
+    assert.match(
+      getCreateHelp(),
+      /Destructively write into an ordinary non-empty target folder/,
+    );
+    assert.match(getCreateHelp(), /never migrated in place/);
+  });
+
   it("parses create options for scripted usage", () => {
     assert.deepEqual(
       parseCreateArgs([
@@ -196,7 +209,7 @@ describe("runToolcraftCli", () => {
 
     const result = await runToolcraftCli(["--no-install", "--no-skills"], {
       cwd: tempRoot,
-      env: {},
+      env: { npm_config_user_agent: "npm/10.9.4 node/v24.4.1 darwin arm64" },
       stderr,
       stdout,
       throwOnError: true,
@@ -205,7 +218,7 @@ describe("runToolcraftCli", () => {
     assert.equal(result.ok, true);
     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.doesNotMatch(stdout.text, /^\s*cd(?:\s|$)/mu);
     assert.match(stdout.text, /npm run dev/);
     assert.equal(stderr.text, "");
   });
@@ -228,7 +241,7 @@ describe("runToolcraftCli", () => {
       ],
       {
         cwd: tempRoot,
-        env: {},
+        env: { npm_config_user_agent: "npm/10.9.4 node/v24.4.1 darwin arm64" },
         stderr,
         stdout,
         throwOnError: true,
@@ -244,179 +257,6 @@ describe("runToolcraftCli", () => {
     assert.equal(stderr.text, "");
   });
 
-  it("runs npm install and Toolcraft skills install when launched through npx", async () => {
-    const tempRoot = await createTempRoot();
-    const stdout = createWritableCapture();
-    const installs = [];
-    const skillsCliPath = path.join(tempRoot, "skills-cli.mjs");
-    const skillsSourceDir = path.join(tempRoot, "toolcraft-skills");
-
-    await runToolcraftCli(["create", "install-app", "--name", "Install App", "--yes", "--force"], {
-      cwd: tempRoot,
-      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, shell: options.shell });
-      },
-    });
-
-    assert.deepEqual(installs, [
-      {
-        args: ["install"],
-        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 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 = [];
@@ -499,6 +339,23 @@ describe("runToolcraftCli", () => {
     );
 
     assert.deepEqual(commands, []);
+
+    const cleanHome = path.join(tempRoot, "clean-home");
+    await fs.mkdir(cleanHome, { recursive: true });
+    const aiCheck = await execFileAsync("npm", ["run", "ai:check"], {
+      cwd: path.join(tempRoot, "no-skills-app"),
+      env: {
+        ...process.env,
+        CLAUDE_HOME: path.join(cleanHome, ".claude"),
+        CODEX_HOME: path.join(cleanHome, ".codex"),
+        HOME: cleanHome,
+        XDG_CONFIG_HOME: path.join(cleanHome, ".config"),
+      },
+    });
+
+    assert.match(aiCheck.stdout, /Toolcraft code health check passed/);
+    assert.match(aiCheck.stderr, /Optional AI workflow skills are not installed/);
+    assert.match(aiCheck.stderr, /Continue with the local Toolcraft workflow/);
   });
 
   it("prints create help with the npx command", async () => {

package/src/create-command.mjs

@@ -0,0 +1,152 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { intro, note, outro } from "@clack/prompts";
+
+import { installGeneratedAppDependencies } from "./dependency-install.mjs";
+import { generateToolcraft } from "./generate.mjs";
+import { resolveCreateOptions } from "./create-options.mjs";
+import { canUseClack, getStdout, runCommand, runWithSpinner, writeLine } from "./cli-io.mjs";
+import { createRunScriptCommand, detectPackageManager } from "./package-manager.mjs";
+
+const PACKAGE_ROOT = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
+const require = createRequire(import.meta.url);
+
+function getSkillsCliPath(context = {}) {
+  if (context.skillsCliPath) {
+    return context.skillsCliPath;
+  }
+
+  const skillsPackageJsonPath = require.resolve("skills/package.json");
+  return path.join(path.dirname(skillsPackageJsonPath), "bin/cli.mjs");
+}
+
+function getToolcraftSkillsSourceDir(context = {}) {
+  return context.toolcraftSkillsSourceDir ?? path.join(PACKAGE_ROOT, "toolcraft-skills");
+}
+
+function createSkillsAddArgs(parsedOptions, context = {}) {
+  const args = ["add", getToolcraftSkillsSourceDir(context)];
+
+  if (parsedOptions.skillsAll) {
+    args.push("--all");
+  } else {
+    args.push("--skill", "*");
+  }
+
+  for (const agent of parsedOptions.agent) {
+    args.push("--agent", agent);
+  }
+
+  if (parsedOptions.global) {
+    args.push("--global");
+  }
+
+  if (parsedOptions.copy) {
+    args.push("--copy");
+  }
+
+  if (parsedOptions.yes && !parsedOptions.skillsAll) {
+    args.push("--yes");
+  }
+
+  return args;
+}
+
+async function installToolcraftSkills(parsedOptions, targetDir, context = {}) {
+  const skillsSourceDir = getToolcraftSkillsSourceDir(context);
+  const skillsCliPath = getSkillsCliPath(context);
+
+  const args = createSkillsAddArgs(parsedOptions, {
+    ...context,
+    toolcraftSkillsSourceDir: skillsSourceDir,
+  });
+
+  await runCommand(
+    process.execPath,
+    [skillsCliPath, ...args],
+    {
+      cwd: targetDir,
+      env: {
+        ...process.env,
+        ...(context.env ?? {}),
+      },
+      shell: false,
+      stdio: "inherit",
+    },
+    context,
+  );
+}
+
+function writeFinalSummary(stdout, result, createOptions) {
+  const sameDirectory = result.targetDir === path.resolve(createOptions.cwd);
+  const devCommand = createRunScriptCommand(createOptions.packageManager, "dev");
+
+  writeLine(stdout, "");
+  writeLine(stdout, `Created ${result.packageName} at ${result.targetDir}`);
+  writeLine(stdout, "");
+  writeLine(stdout, "Next steps:");
+  if (!sameDirectory) {
+    const displayTargetDir = path.isAbsolute(createOptions.targetDir)
+      ? result.targetDir
+      : result.relativeTargetDir;
+    writeLine(stdout, `  cd ${displayTargetDir}`);
+  }
+  writeLine(stdout, `  ${devCommand}`);
+}
+
+export async function runCreateCommand(parsedOptions, context = {}) {
+  const cwd = path.resolve(context.cwd ?? process.cwd());
+  const stdout = getStdout(context);
+  const usingClack = canUseClack(context);
+  const packageManager = detectPackageManager({
+    ...process.env,
+    ...(context.env ?? {}),
+  });
+
+  if (usingClack) {
+    intro("Create Toolcraft app");
+  }
+
+  const createOptions = await resolveCreateOptions(parsedOptions, context);
+
+  const result = await runWithSpinner(context, "Creating Toolcraft app...", "Created app", () =>
+    generateToolcraft({
+      cwd,
+      force: createOptions.force,
+      name: createOptions.name,
+      packageManager,
+      targetDir: createOptions.targetDir,
+    }),
+  );
+
+  if (createOptions.install) {
+    await installGeneratedAppDependencies({
+      context,
+      packageManager,
+      result,
+      skillsRequested: createOptions.skills,
+      stdout,
+    });
+  }
+
+  if (createOptions.skills) {
+    writeLine(stdout, "");
+    writeLine(stdout, "Installing Toolcraft skills with skills add...");
+    await installToolcraftSkills(parsedOptions, result.targetDir, context);
+  }
+
+  if (usingClack) {
+    const nextSteps = [
+      ...(result.targetDir === cwd ? [] : [`cd ${result.relativeTargetDir}`]),
+      createRunScriptCommand(packageManager, "dev"),
+    ].join("\n");
+    note(nextSteps, "Next steps");
+    outro(`Created ${result.packageName}`);
+  } else {
+    writeFinalSummary(stdout, result, { ...createOptions, cwd, packageManager });
+  }
+
+  return result;
+}

package/src/create-options.mjs

@@ -0,0 +1,194 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { pathExists } from "./copy-recursive.mjs";
+import { sanitizePackageName } from "./package-json.mjs";
+import { canPrompt, promptConfirm, promptText } from "./cli-io.mjs";
+
+export const DEFAULT_PROJECT_NAME = "my-toolcraft-app";
+
+function defaultNameForTarget(cwd, targetDir) {
+  if (!targetDir) {
+    return sanitizePackageName(path.basename(cwd)) || DEFAULT_PROJECT_NAME;
+  }
+
+  const basename = path.basename(path.resolve(cwd, targetDir));
+  return sanitizePackageName(basename === "." ? path.basename(cwd) : basename) || DEFAULT_PROJECT_NAME;
+}
+
+async function directoryHasMeaningfulEntries(directoryPath) {
+  if (!(await pathExists(directoryPath))) {
+    return false;
+  }
+
+  const stats = await fs.stat(directoryPath);
+  if (!stats.isDirectory()) {
+    return true;
+  }
+
+  const entries = await fs.readdir(directoryPath);
+  return entries.some((entry) => entry !== ".DS_Store");
+}
+
+function readOptionValue(argv, index, optionName) {
+  const value = argv[index + 1];
+  if (!value || value.startsWith("-")) {
+    throw new Error(`${optionName} requires a value.`);
+  }
+
+  return value;
+}
+
+export function parseCreateArgs(argv) {
+  const options = {
+    agent: [],
+    copy: false,
+    force: false,
+    global: false,
+    help: false,
+    install: true,
+    name: undefined,
+    skills: true,
+    skillsAll: false,
+    targetDir: undefined,
+    yes: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === "--force" || arg === "-f") {
+      options.force = true;
+      continue;
+    }
+
+    if (arg === "--global" || arg === "-g") {
+      options.global = true;
+      continue;
+    }
+
+    if (arg === "--copy") {
+      options.copy = true;
+      continue;
+    }
+
+    if (arg === "--all") {
+      options.skillsAll = true;
+      continue;
+    }
+
+    if (arg === "--yes" || arg === "-y") {
+      options.yes = true;
+      continue;
+    }
+
+    if (arg === "--no-install") {
+      options.install = false;
+      continue;
+    }
+
+    if (arg === "--no-skills") {
+      options.skills = false;
+      continue;
+    }
+
+    if (arg === "--name") {
+      options.name = readOptionValue(argv, index, "--name");
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--agent" || arg === "-a") {
+      const startIndex = index;
+      while (argv[index + 1] && !argv[index + 1].startsWith("-")) {
+        options.agent.push(argv[index + 1]);
+        index += 1;
+      }
+
+      if (index === startIndex) {
+        throw new Error(`${arg} requires an agent name.`);
+      }
+
+      continue;
+    }
+
+    if (arg === "--dir") {
+      if (options.targetDir) {
+        throw new Error("Pass either a positional target directory or --dir, not both.");
+      }
+
+      options.targetDir = readOptionValue(argv, index, "--dir");
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+
+    if (options.targetDir) {
+      throw new Error(`Unexpected extra argument: ${arg}`);
+    }
+
+    options.targetDir = arg;
+  }
+
+  return options;
+}
+
+export async function resolveCreateOptions(parsedOptions, context = {}) {
+  const cwd = path.resolve(context.cwd ?? process.cwd());
+  let name = parsedOptions.name?.trim();
+  let targetDir = parsedOptions.targetDir?.trim();
+  let promptedForName = false;
+
+  if (!name) {
+    const defaultName = defaultNameForTarget(cwd, targetDir);
+    const shouldPrompt = !parsedOptions.yes && (context.prompts?.text || canPrompt(context));
+    if (shouldPrompt) {
+      name = await promptText(context, "Project name", defaultName);
+      promptedForName = true;
+    } else {
+      name = defaultName;
+    }
+  }
+
+  name = sanitizePackageName(name);
+
+  if (!targetDir) {
+    const shouldCreateNamedFolder =
+      promptedForName && (await directoryHasMeaningfulEntries(cwd));
+    targetDir = shouldCreateNamedFolder ? `./${name}` : ".";
+  }
+
+  targetDir = targetDir || ".";
+  const resolvedTargetDir = path.resolve(cwd, targetDir);
+  let force = parsedOptions.force;
+
+  if (!force && (await directoryHasMeaningfulEntries(resolvedTargetDir))) {
+    const shouldContinue =
+      !parsedOptions.yes &&
+      (await promptConfirm(context, "Directory is not empty. Continue?", false));
+
+    if (!shouldContinue) {
+      throw new Error(
+        `Target directory is not empty: ${resolvedTargetDir}. Use --force to write into it.`,
+      );
+    }
+
+    force = true;
+  }
+
+  return {
+    force,
+    install: parsedOptions.install && context.env?.TOOLCRAFT_SKIP_INSTALL !== "1",
+    name,
+    skills: parsedOptions.skills && context.env?.TOOLCRAFT_SKIP_SKILLS !== "1",
+    targetDir,
+  };
+}

package/src/generate-test-assertions.mjs

@@ -0,0 +1,27 @@
+import { assertGeneratedDocs } from "./generate-test-doc-assertions.mjs";
+import {
+  assertGeneratedFiles,
+  assertGeneratedRoutesAndStyles,
+  assertGeneratedTextIsStandalone,
+} from "./generate-test-file-assertions.mjs";
+import {
+  assertGeneratedAppPerformance,
+  assertGeneratedIntegrityChecks,
+} from "./generate-test-integrity-assertions.mjs";
+import {
+  assertGeneratedGitignore,
+  assertGeneratedIdentity,
+  assertGeneratedPackageJson,
+} from "./generate-test-package-assertions.mjs";
+
+export async function assertGeneratedStandaloneApp({ execFileAsync, targetDir }) {
+  await assertGeneratedPackageJson(targetDir);
+  await assertGeneratedIdentity(targetDir);
+  await assertGeneratedFiles(targetDir);
+  await assertGeneratedGitignore(targetDir);
+  await assertGeneratedAppPerformance(targetDir);
+  await assertGeneratedIntegrityChecks(targetDir, execFileAsync);
+  await assertGeneratedDocs(targetDir);
+  await assertGeneratedRoutesAndStyles(targetDir);
+  await assertGeneratedTextIsStandalone(targetDir);
+}