@pixel-point/toolcraft 0.0.14 → 0.0.15

package/README.md

@@ -21,9 +21,12 @@ 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 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
+After dependencies are installed, Toolcraft installs external workflow skills
 in a batch through the `skills` CLI. The skill installer uses the same agent,
-scope, and installation prompts as `npx skills add`.
+scope, and installation prompts as `npx skills add`. These skills improve the
+agent workflow, while the generated app's signed local `AGENTS.md` and
+`docs/toolcraft/*` remain the mandatory self-contained contract. `--no-skills`
+therefore skips installation without disabling local verification.
 
 Example:
 
@@ -40,12 +43,20 @@ coding agent and prompt for the creative output you want, for example:
 Build an app that applies an ASCII effect to an uploaded image.
 ```
 
+The generated bootstrap, route host, runtime copy, contract docs, and verification
+reporter are signed platform files. Product code stays open through a typed
+`appComposition` (`schema`, `canvasContent`, custom renderers, panel actions, and
+default-media choice), while AST and runtime-evidence checks prevent replacing
+the shell or satisfying acceptance/performance with source-code-shaped stubs.
+
 Scripted usage:
 
 ```bash
 npx @pixel-point/toolcraft create my-toolcraft-app --name my-toolcraft-app --yes --force
 ```
 
+Generation is transactional. Toolcraft assembles the app in a sibling staging directory, runs dependency-free local-doc and signed platform-integrity validation there, then promotes it with an atomic rename. A failed new generation leaves no target. With `--force`, an ordinary existing folder is staged as the merge base so non-colliding files and `.git` keep the documented behavior; disposable install, build, coverage, and browser-report directories are not duplicated. A semantic-validation, pre-commit, or swap failure preserves the original folder and removes transaction artifacts. Existing generated Toolcraft apps are still never migrated in place.
+
 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixel-point/toolcraft",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
   "bin": {

package/scripts/prepare-pack.mjs

@@ -1,34 +1,8 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import fs from "node:fs/promises";
-
-import { copyDirectory, removeDirectory } from "../src/copy-recursive.mjs";
+import { preparePackTemplates } from "../src/prepare-pack-templates.mjs";
 
 const packageRoot = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
 const repoRoot = path.resolve(packageRoot, "..");
-const templatesRoot = path.join(packageRoot, "templates");
-
-const sources = [
-  {
-    from: path.join(repoRoot, "starter"),
-    to: path.join(templatesRoot, "starter"),
-  },
-  {
-    from: path.join(repoRoot, "packages/ui/src"),
-    to: path.join(templatesRoot, "ui"),
-  },
-  {
-    from: path.join(repoRoot, "packages/toolcraft-runtime/src"),
-    to: path.join(templatesRoot, "runtime"),
-  },
-];
-
-await removeDirectory(templatesRoot);
-
-for (const source of sources) {
-  await copyDirectory(source.from, source.to);
-}
 
-const starterGitignorePath = path.join(templatesRoot, "starter/.gitignore");
-const starterPackGitignorePath = path.join(templatesRoot, "starter/gitignore");
-await fs.copyFile(starterGitignorePath, starterPackGitignorePath);
+await preparePackTemplates({ packageRoot, repoRoot });

package/src/cli-io.mjs

@@ -0,0 +1,174 @@
+import readline from "node:readline/promises";
+
+import spawn from "cross-spawn";
+import { cancel, confirm, isCancel, spinner, text } from "@clack/prompts";
+
+export function writeLine(stream, message = "") {
+  stream.write(`${message}\n`);
+}
+
+export function writeBlock(stream, message) {
+  stream.write(message.endsWith("\n") ? message : `${message}\n`);
+}
+
+export function getStdout(context) {
+  return context.stdout ?? process.stdout;
+}
+
+export function getStderr(context) {
+  return context.stderr ?? process.stderr;
+}
+
+export function getStdin(context) {
+  return context.stdin ?? process.stdin;
+}
+
+export function setExitCode(context, exitCode) {
+  if (typeof context.setExitCode === "function") {
+    context.setExitCode(exitCode);
+    return;
+  }
+
+  process.exitCode = exitCode;
+}
+
+export function canPrompt(context) {
+  const stdin = getStdin(context);
+  const stdout = getStdout(context);
+  return Boolean(context.forcePrompts || (stdin.isTTY && stdout.isTTY));
+}
+
+export function canUseClack(context) {
+  return Boolean(
+    !context.disableClack &&
+      !context.prompts &&
+      getStdin(context).isTTY &&
+      getStdout(context).isTTY,
+  );
+}
+
+function handleCancel(value) {
+  if (!isCancel(value)) {
+    return value;
+  }
+
+  cancel("Operation cancelled");
+  throw new Error("Operation cancelled.");
+}
+
+function createMissingValueError(valueName) {
+  return new Error(`${valueName} is required. Pass it with a flag, or run in an interactive terminal.`);
+}
+
+export async function runWithSpinner(context, startMessage, successMessage, task) {
+  if (!canUseClack(context)) {
+    writeLine(getStdout(context), startMessage);
+    return task();
+  }
+
+  const taskSpinner = spinner();
+  taskSpinner.start(startMessage);
+
+  try {
+    const result = await task();
+    taskSpinner.stop(successMessage);
+    return result;
+  } catch (error) {
+    taskSpinner.stop("Failed");
+    throw error;
+  }
+}
+
+export async function promptText(context, label, defaultValue) {
+  if (context.prompts?.text) {
+    return context.prompts.text({ label, defaultValue });
+  }
+
+  if (!canPrompt(context)) {
+    throw createMissingValueError(label);
+  }
+
+  if (canUseClack(context)) {
+    const answer = handleCancel(
+      await text({
+        message: label,
+        placeholder: defaultValue,
+        defaultValue,
+      }),
+    );
+    return String(answer).trim() || defaultValue;
+  }
+
+  const rl = readline.createInterface({
+    input: getStdin(context),
+    output: getStdout(context),
+  });
+
+  try {
+    const answer = await rl.question(`? ${label} (${defaultValue}): `);
+    return answer.trim() || defaultValue;
+  } finally {
+    rl.close();
+  }
+}
+
+export async function promptConfirm(context, label, defaultValue = false) {
+  if (context.prompts?.confirm) {
+    return context.prompts.confirm({ label, defaultValue });
+  }
+
+  if (!canPrompt(context)) {
+    return defaultValue;
+  }
+
+  if (canUseClack(context)) {
+    return handleCancel(
+      await confirm({
+        message: label,
+        initialValue: defaultValue,
+      }),
+    );
+  }
+
+  const suffix = defaultValue ? "Y/n" : "y/N";
+  const rl = readline.createInterface({
+    input: getStdin(context),
+    output: getStdout(context),
+  });
+
+  try {
+    const answer = (await rl.question(`? ${label} (${suffix}): `)).trim().toLowerCase();
+    if (!answer) {
+      return defaultValue;
+    }
+
+    return ["y", "yes"].includes(answer);
+  } finally {
+    rl.close();
+  }
+}
+
+export 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: options.shell ?? false,
+      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}.`));
+    });
+  });
+}

package/src/cli-package-manager-flow.test.mjs

@@ -0,0 +1,206 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { after, describe, it } from "node:test";
+
+import { runToolcraftCli } from "./cli.mjs";
+
+const tempRoots = [];
+
+after(async () => {
+  await Promise.all(
+    tempRoots.map((tempRoot) => fs.rm(tempRoot, { force: true, recursive: true })),
+  );
+});
+
+function createWritableCapture() {
+  return {
+    text: "",
+    write(chunk) {
+      this.text += String(chunk);
+    },
+  };
+}
+
+async function createTempRoot() {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-cli-run-"));
+  tempRoots.push(tempRoot);
+  return tempRoot;
+}
+
+describe("runToolcraftCli package manager flows", () => {
+  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 && npm run verify:receipt",
+    );
+
+    const playwrightConfigSource = await fs.readFile(
+      path.join(tempRoot, "install-app/playwright.config.ts"),
+      "utf8",
+    );
+    assert.match(playwrightConfigSource, /npm exec -- vite \$\{browserServerMode\}/);
+    assert.match(playwrightConfigSource, /=== "preview" \? "preview" : "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/);
+  });
+});