create-zudo-circuit-doc 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to `create-zudo-circuit-doc` are documented in this file.
+
+The format is based on Keep a Changelog, and release notes are generated from the changelog MDX pages.
+
+## [0.1.0] - 2026-09-27
+
+Initial release of `create-zudo-circuit-doc`, an initializer that creates a ready-to-use
+circuit-development project with a zudo-doc site, the runtime package, canonical project workflows,
+and evidence authoring templates.
+
+## Features
+
+- `pnpm create zudo-circuit-doc <destination>` scaffolds a project from a template kept in sync with
+  the `examples/empty` host, checked for parity with the upstream zudo-doc scaffold.
+- Generated projects depend on `@takazudo/zudo-circuit-doc` through a `^0.1.0` caret range and ship a
+  `circuit.config.ts`, empty evidence data, the canonical agent workflow, skills, and authoring
+  templates.
+- Options: `--name`, `--title`, `--library`, `--agent claude|codex|both|none`, `--yes`,
+  `--install` / `--no-install`, `--git` / `--no-git`, and `--runtime-spec` to override the runtime
+  dependency with a semver range, dist-tag, or absolute `file:` spec.
+- A non-empty destination is rejected and left byte-for-byte unchanged; an existing empty directory
+  is accepted.
+- Generated projects include a README titled after the site, a `contract.md`, and plain-text next
+  steps.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Takeshi Takatsudo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# create-zudo-circuit-doc
+
+Scaffolds a new [zudo-circuit-doc](https://github.com/Takazudo/zudo-circuit-doc) project: a zudo-doc-based circuit-development initializer that opens as useful documentation before any component, board, KiCad file or firmware exists.
+
+**Status:** under construction. See the implementation epic: https://github.com/Takazudo/zudo-circuit-doc/issues/1
+
+## Usage
+
+```
+npm create zudo-circuit-doc@latest [destination]
+# or, in this monorepo:
+pnpm create zudo-circuit-doc [destination]
+```
+
+If `destination` is omitted, the CLI prompts for one on an interactive terminal; on a non-interactive session, or with `--yes`, a missing destination is an error.
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `[destination]` | prompted | Directory to create. Must not exist, or must be empty. Spaces are allowed. |
+| `--name <npm-name>` | `destination`'s basename | The generated `package.json` name (npm grammar, 1-214 chars, no `node_modules`). |
+| `--title <site title>` | title-cased `--name` | The site title. 1-80 printable characters, excluding `" ' \` \\ $ < > { }` and control characters — it is substituted into TS string literals and MDX frontmatter. |
+| `--library <kicad-lib-name>` | `--name` | The KiCad library name (`^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$`). |
+| `--agent claude\|codex\|both\|none` | `both` | Which thin agent-entry file(s) to keep: `claude` keeps `CLAUDE.md`, `codex` keeps `AGENTS.md`, `both` keeps both, `none` keeps neither. `.claude/skills/**` is always kept — it is the evidence storage (ADR-006). |
+| `--yes`, `-y` | off | Never prompt; a missing destination is an error. |
+| `--install` / `--no-install` | `--install` | Run `pnpm install` in the destination after scaffolding. |
+| `--git` / `--no-git` | `--git` | Run `git init -b main` and commit the scaffold. Skipped with a note if the destination is already inside a git work tree. |
+| `--runtime-spec <spec>` | the template's own spec | Overrides the `@takazudo/zudo-circuit-doc` dependency in both `package.json` and `doc/package.json`. Accepts a semver range/dist-tag, or a `file:` spec with an **absolute** path — a relative `file:` path is rejected, since `doc/package.json` sits one directory deeper than `package.json` and one relative string cannot be correct in both. |
+| `--help`, `-h` | | Print usage and exit. |
+| `--version`, `-v` | | Print the installed version and exit. |
+
+There is no force flag: if the destination exists and is not empty, the command reports the collision, exits with status 1, and leaves the destination byte-for-byte unchanged.
+
+## What is generated
+
+The scaffold composes the project atomically (via a staging directory renamed into place, so the destination is never partially written) from the package's own `templates/default`. Its full contents are the epic's **Generated project contract** (https://github.com/Takazudo/zudo-circuit-doc/issues/1), summarized here:
+
+- Root: `package.json`, `pnpm-workspace.yaml`, `circuit.config.ts`, `README.md`, `CLAUDE.md`/`AGENTS.md` (per `--agent`), `.gitignore`, `ZUDO_DEPS_PINS.md`.
+- `circuit/`: the canonical agent workflow (`WORKFLOW.md`, A-G), authoring templates, checks, and empty publication/preflight records.
+- `.claude/skills/`: `component-spec-audit` and `circuit-spec-integration`, the evidence-storage skill bundles.
+- `doc/`: a zudo-doc app — route stub, chrome-bindings shim, and `zfb.config.ts`.
+
+After scaffolding, the printed **Next steps** give the exact commands to run (`cd`, `pnpm install` if it did not already run, `pnpm circuit:doctor`, `pnpm dev`), plus a pointer to `circuit/WORKFLOW.md` for the first task.
+
+## Create-only semantics
+
+This tool only creates new projects. There is no `update` or "adopt an existing directory" mode — running it again against the same non-empty destination is a collision, not a merge or an upgrade.
+
+## Tool requirements
+
+- Node >=22.18.0
+- pnpm (via corepack; the generated project pins `packageManager`)
+- git, if `--git` is not disabled
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/bin/create-zudo-circuit-doc.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { main } from "../dist/cli.js";
+
+const exitCode = await main(process.argv.slice(2));
+if (exitCode !== 0) process.exitCode = exitCode;

package/dist/args.d.ts

@@ -0,0 +1,21 @@
+export declare const AGENT_CHOICES: readonly ["claude", "codex", "both", "none"];
+export type AgentChoice = (typeof AGENT_CHOICES)[number];
+export interface ParsedOptions {
+    help: boolean;
+    version: boolean;
+    yes: boolean;
+    destination: string | undefined;
+    name: string | undefined;
+    title: string | undefined;
+    library: string | undefined;
+    agent: AgentChoice;
+    install: boolean;
+    git: boolean;
+    runtimeSpec: string | undefined;
+}
+/**
+ * Parses argv with node:util parseArgs (strict). `--install`/`--no-install`
+ * and `--git`/`--no-git` are not natively negatable by parseArgs, so both
+ * spellings are declared and the last one seen on the command line wins.
+ */
+export declare function parseCliArgs(argv: string[]): ParsedOptions;

package/dist/args.js

@@ -0,0 +1,71 @@
+import { parseArgs } from "node:util";
+import { CliUsageError } from "./errors.js";
+export const AGENT_CHOICES = ["claude", "codex", "both", "none"];
+/**
+ * Parses argv with node:util parseArgs (strict). `--install`/`--no-install`
+ * and `--git`/`--no-git` are not natively negatable by parseArgs, so both
+ * spellings are declared and the last one seen on the command line wins.
+ */
+export function parseCliArgs(argv) {
+    let result;
+    try {
+        result = parseArgs({
+            args: argv,
+            strict: true,
+            allowPositionals: true,
+            tokens: true,
+            options: {
+                help: { type: "boolean", short: "h" },
+                version: { type: "boolean", short: "v" },
+                yes: { type: "boolean", short: "y" },
+                name: { type: "string" },
+                title: { type: "string" },
+                library: { type: "string" },
+                agent: { type: "string" },
+                install: { type: "boolean" },
+                "no-install": { type: "boolean" },
+                git: { type: "boolean" },
+                "no-git": { type: "boolean" },
+                "runtime-spec": { type: "string" },
+            },
+        });
+    }
+    catch (error) {
+        throw new CliUsageError(error.message);
+    }
+    const { values, positionals, tokens } = result;
+    if (positionals.length > 1) {
+        throw new CliUsageError(`Too many arguments: expected at most one destination, got ${positionals.length} (${positionals.join(", ")}).`);
+    }
+    let install = true;
+    let git = true;
+    for (const token of tokens) {
+        if (token.kind !== "option")
+            continue;
+        if (token.name === "install")
+            install = true;
+        else if (token.name === "no-install")
+            install = false;
+        else if (token.name === "git")
+            git = true;
+        else if (token.name === "no-git")
+            git = false;
+    }
+    const agentRaw = values.agent ?? "both";
+    if (!AGENT_CHOICES.includes(agentRaw)) {
+        throw new CliUsageError(`Invalid --agent "${agentRaw}": must be one of ${AGENT_CHOICES.join(", ")}.`);
+    }
+    return {
+        help: values.help ?? false,
+        version: values.version ?? false,
+        yes: values.yes ?? false,
+        destination: positionals[0],
+        name: values.name,
+        title: values.title,
+        library: values.library,
+        agent: agentRaw,
+        install,
+        git,
+        runtimeSpec: values["runtime-spec"],
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,27 @@
+import type { Readable } from "node:stream";
+import { type GitRunner } from "./git.ts";
+import { type InstallRunner } from "./install.ts";
+interface WritableLike {
+    write(chunk: string): unknown;
+}
+/**
+ * Every external effect the CLI performs is injectable here, so tests can
+ * run the real orchestration logic against a fixture template, a fake
+ * installer/git runner, and captured streams instead of the real world.
+ */
+export interface CliOverrides {
+    cwd?: string;
+    stdout?: WritableLike;
+    stderr?: WritableLike;
+    stdin?: Readable;
+    isTTY?: boolean;
+    templateDir?: URL | string;
+    runInstall?: InstallRunner;
+    runGit?: GitRunner;
+    randomSuffix?: () => string;
+    /** Test-only seam: called before each template file is copied. */
+    beforeCopyFile?: (relPath: string) => void;
+}
+/** Entry point. `argv` is the CLI's own arguments only (no `node`/script path). */
+export declare function main(argv: string[], overrides?: CliOverrides): Promise<number>;
+export {};

package/dist/cli.js

@@ -0,0 +1,101 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { parseCliArgs } from "./args.js";
+import { CliError, CliUsageError } from "./errors.js";
+import { defaultRunGit } from "./git.js";
+import { HELP_TEXT, USAGE_LINE } from "./help.js";
+import { defaultRunInstall } from "./install.js";
+import { formatNextSteps } from "./next-steps.js";
+import { formatPlan, resolvePlan } from "./plan.js";
+import { promptForDestination } from "./prompt.js";
+import { checkDestinationCollision, composeProject } from "./scaffold.js";
+import { shellQuote } from "./shell-quote.js";
+import { readPackageVersion } from "./version.js";
+function println(stream, text) {
+    stream.write(text.endsWith("\n") ? text : `${text}\n`);
+}
+/** Entry point. `argv` is the CLI's own arguments only (no `node`/script path). */
+export async function main(argv, overrides = {}) {
+    const cwd = overrides.cwd ?? process.cwd();
+    const stdout = overrides.stdout ?? process.stdout;
+    const stderr = overrides.stderr ?? process.stderr;
+    const stdin = overrides.stdin ?? process.stdin;
+    const isTTY = overrides.isTTY ??
+        Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const templateDir = overrides.templateDir ?? new URL("../templates/default/", import.meta.url);
+    const runInstall = overrides.runInstall ?? defaultRunInstall;
+    const runGit = overrides.runGit ?? defaultRunGit;
+    const randomSuffix = overrides.randomSuffix ?? (() => crypto.randomBytes(6).toString("hex"));
+    try {
+        const parsed = parseCliArgs(argv);
+        if (parsed.help) {
+            println(stdout, HELP_TEXT);
+            return 0;
+        }
+        if (parsed.version) {
+            println(stdout, readPackageVersion(import.meta.url));
+            return 0;
+        }
+        let destinationRaw = parsed.destination;
+        if (destinationRaw === undefined) {
+            if (parsed.yes || !isTTY) {
+                throw new CliUsageError("A destination directory is required (pass one, or run on an interactive terminal without --yes to be prompted).");
+            }
+            destinationRaw = await promptForDestination(stdin, stdout);
+            if (destinationRaw.length === 0) {
+                throw new CliUsageError("A destination directory is required.");
+            }
+        }
+        const plan = resolvePlan(parsed, destinationRaw, cwd);
+        const displayDestination = path.relative(cwd, plan.destinationPath) || ".";
+        checkDestinationCollision(plan.destinationPath);
+        println(stdout, formatPlan(plan));
+        composeProject({
+            plan,
+            templateDir,
+            randomSuffix,
+            beforeCopyFile: overrides.beforeCopyFile,
+        });
+        let installRan = false;
+        if (plan.install) {
+            try {
+                await runInstall(plan.destinationPath);
+                installRan = true;
+            }
+            catch (error) {
+                println(stderr, `Error: ${error.message} The generated files are left in place — they form a valid project.`);
+                println(stdout, ["Recovery:", "", `  cd ${shellQuote(displayDestination)}`, "  pnpm install"].join("\n"));
+                return 1;
+            }
+        }
+        let gitFailed = false;
+        if (plan.git) {
+            try {
+                const outcome = await runGit(plan.destinationPath);
+                if (outcome.note)
+                    println(stdout, outcome.note);
+            }
+            catch (error) {
+                gitFailed = true;
+                println(stderr, `Error: git init/commit failed: ${error.message} The generated files are left in place — they form a valid project; run git init yourself.`);
+            }
+        }
+        println(stdout, `Created ${plan.destinationPath}`);
+        println(stdout, "");
+        println(stdout, formatNextSteps({ displayDestination, installRan, runtimeSpec: plan.runtimeSpec }));
+        return gitFailed ? 1 : 0;
+    }
+    catch (error) {
+        if (error instanceof CliUsageError) {
+            println(stderr, `Error: ${error.message}`);
+            println(stderr, USAGE_LINE);
+            return 2;
+        }
+        if (error instanceof CliError) {
+            println(stderr, `Error: ${error.message}`);
+            return 1;
+        }
+        println(stderr, `Error: ${error.message}`);
+        return 1;
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class CliUsageError extends Error {
+}
+export declare class CliError extends Error {
+}

package/dist/errors.js

@@ -0,0 +1,7 @@
+// Two exit-code families the CLI distinguishes throughout: usage/config
+// mistakes the caller can fix by rereading --help (exit 2), and everything
+// else that failed after the input was understood (exit 1).
+export class CliUsageError extends Error {
+}
+export class CliError extends Error {
+}

package/dist/git.d.ts

@@ -0,0 +1,11 @@
+export interface GitOutcome {
+    ran: boolean;
+    note?: string;
+}
+export type GitRunner = (cwd: string) => Promise<GitOutcome>;
+/**
+ * Builds the default GitRunner. `env` is injectable so tests can isolate git
+ * identity discovery (HOME, GIT_CONFIG_*) without mutating process.env.
+ */
+export declare function createGitRunner(env?: NodeJS.ProcessEnv): GitRunner;
+export declare const defaultRunGit: GitRunner;

package/dist/git.js

@@ -0,0 +1,69 @@
+import { execFileSync } from "node:child_process";
+const COMMIT_MESSAGE = "Initial commit from create-zudo-circuit-doc";
+function isInsideExistingWorkTree(cwd, env) {
+    try {
+        const out = execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+            cwd,
+            env,
+            stdio: ["ignore", "pipe", "ignore"],
+        })
+            .toString()
+            .trim();
+        return out === "true";
+    }
+    catch {
+        return false;
+    }
+}
+function hasGitIdentity(cwd, env) {
+    try {
+        const name = execFileSync("git", ["config", "user.name"], {
+            cwd,
+            env,
+            stdio: ["ignore", "pipe", "ignore"],
+        })
+            .toString()
+            .trim();
+        const email = execFileSync("git", ["config", "user.email"], {
+            cwd,
+            env,
+            stdio: ["ignore", "pipe", "ignore"],
+        })
+            .toString()
+            .trim();
+        return name.length > 0 && email.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Builds the default GitRunner. `env` is injectable so tests can isolate git
+ * identity discovery (HOME, GIT_CONFIG_*) without mutating process.env.
+ */
+export function createGitRunner(env = process.env) {
+    return async (cwd) => {
+        if (isInsideExistingWorkTree(cwd, env)) {
+            return {
+                ran: false,
+                note: "Skipped git init: the destination is already inside a git work tree.",
+            };
+        }
+        execFileSync("git", ["init", "-b", "main"], { cwd, env, stdio: "ignore" });
+        let note;
+        const identityArgs = [];
+        if (!hasGitIdentity(cwd, env)) {
+            identityArgs.push("-c", "user.name=create-zudo-circuit-doc", "-c", "user.email=create-zudo-circuit-doc@localhost");
+            note =
+                "No git identity was configured; used a neutral committer identity for the initial commit.";
+        }
+        execFileSync("git", ["add", "-A"], { cwd, env, stdio: "ignore" });
+        execFileSync("git", [...identityArgs, "commit", "-m", COMMIT_MESSAGE], {
+            cwd,
+            env,
+            stdio: "ignore",
+        });
+        return { ran: true, note };
+    };
+}
+export const defaultRunGit = createGitRunner();

package/dist/help.d.ts

@@ -0,0 +1,2 @@
+export declare const USAGE_LINE = "Usage: create-zudo-circuit-doc [destination] [--name <npm-name>] [--title <site title>] [--library <kicad-lib-name>] [--agent claude|codex|both|none] [--yes] [--install|--no-install] [--git|--no-git] [--runtime-spec <spec>] [--help] [--version]";
+export declare const HELP_TEXT: string;

package/dist/help.js

@@ -0,0 +1,21 @@
+export const USAGE_LINE = "Usage: create-zudo-circuit-doc [destination] [--name <npm-name>] [--title <site title>] [--library <kicad-lib-name>] [--agent claude|codex|both|none] [--yes] [--install|--no-install] [--git|--no-git] [--runtime-spec <spec>] [--help] [--version]";
+export const HELP_TEXT = [
+    USAGE_LINE,
+    "",
+    "Also works as: pnpm create zudo-circuit-doc <destination>",
+    "",
+    "Options:",
+    "  --name <npm-name>        Package name (default: the destination's basename)",
+    "  --title <site title>     Site title (default: title-cased --name)",
+    "  --library <lib-name>     KiCad library name (default: --name)",
+    "  --agent <choice>         claude | codex | both | none (default: both)",
+    "  --yes, -y                Do not prompt; a missing destination is an error",
+    "  --install / --no-install Run `pnpm install` after scaffolding (default: on)",
+    "  --git / --no-git         Run `git init` + initial commit (default: on)",
+    "  --runtime-spec <spec>    Override the @takazudo/zudo-circuit-doc dependency",
+    "                           in package.json and doc/package.json: a semver",
+    "                           range/dist-tag, or a \"file:\" spec with an",
+    "                           absolute path (default: the template's own spec)",
+    "  --help, -h               Print this help and exit",
+    "  --version, -v            Print the package version and exit",
+].join("\n");

package/dist/install.d.ts

@@ -0,0 +1,3 @@
+export type InstallRunner = (cwd: string) => Promise<void>;
+/** Runs `pnpm install` in `cwd` with stdio inherited (spec #7). */
+export declare const defaultRunInstall: InstallRunner;

package/dist/install.js

@@ -0,0 +1,17 @@
+import { spawn } from "node:child_process";
+import { CliError } from "./errors.js";
+/** Runs `pnpm install` in `cwd` with stdio inherited (spec #7). */
+export const defaultRunInstall = (cwd) => new Promise((resolve, reject) => {
+    const child = spawn("pnpm", ["install"], { cwd, stdio: "inherit" });
+    child.on("error", (error) => {
+        reject(new CliError(`Failed to run "pnpm install": ${error.message}`));
+    });
+    child.on("exit", (code, signal) => {
+        if (code === 0) {
+            resolve();
+        }
+        else {
+            reject(new CliError(`"pnpm install" exited with ${signal ? `signal ${signal}` : `code ${code}`}.`));
+        }
+    });
+});

package/dist/next-steps.d.ts

@@ -0,0 +1,10 @@
+export interface NextStepsInput {
+    /** Path to print in the `cd` command — relative to the caller's cwd when possible. */
+    displayDestination: string;
+    /** Whether `pnpm install` already ran, so the manual step can be omitted. */
+    installRan: boolean;
+    /** The `--runtime-spec` value applied to package.json/doc/package.json, if any (spec #58). */
+    runtimeSpec?: string;
+}
+/** Builds the exact, machine-extractable "Next steps:" block (spec #8). */
+export declare function formatNextSteps(input: NextStepsInput): string;

package/dist/next-steps.js

@@ -0,0 +1,24 @@
+import { shellQuote } from "./shell-quote.js";
+// #28 (pack-and-install verifier) parses this block back out and runs it
+// verbatim, so the header text and indentation are load-bearing, not
+// cosmetic — keep them exact. No literal ``` fences: some terminals/agents
+// render them as literal text instead of a code block (spec #58 "no fences").
+const HEADER = "Next steps:";
+const HINT = "Open circuit/WORKFLOW.md → Workflow A";
+const COMMAND_INDENT = "  ";
+/** Builds the exact, machine-extractable "Next steps:" block (spec #8). */
+export function formatNextSteps(input) {
+    const commands = [`cd ${shellQuote(input.displayDestination)}`];
+    if (!input.installRan)
+        commands.push("pnpm install");
+    commands.push("pnpm circuit:doctor", "pnpm dev");
+    const lines = [HEADER, "", ...commands.map((command) => `${COMMAND_INDENT}${command}`)];
+    // Only surfaced when install did not already run: that is the one case
+    // where the user (or a resumed `pnpm install`) still needs to know the
+    // dependency spec in package.json/doc/package.json was overridden.
+    if (!input.installRan && input.runtimeSpec !== undefined) {
+        lines.push("", `Applied --runtime-spec ${JSON.stringify(input.runtimeSpec)} to package.json and doc/package.json.`);
+    }
+    lines.push("", HINT);
+    return lines.join("\n");
+}

package/dist/plan.d.ts

@@ -0,0 +1,17 @@
+import type { AgentChoice, ParsedOptions } from "./args.ts";
+export interface Plan {
+    /** Resolved once; every later step reuses this instead of re-resolving. */
+    destinationPath: string;
+    name: string;
+    title: string;
+    library: string;
+    agent: AgentChoice;
+    install: boolean;
+    git: boolean;
+    /** Overrides the template's `@takazudo/zudo-circuit-doc` dependency spec in package.json + doc/package.json (spec #58). `undefined` keeps the template's own spec. */
+    runtimeSpec: string | undefined;
+}
+/** Applies defaults (spec #2) and validates each value separately (spec #3). */
+export declare function resolvePlan(options: ParsedOptions, destinationRaw: string, cwd: string): Plan;
+/** Renders the plan for the pre-flight printout (spec #5). */
+export declare function formatPlan(plan: Plan): string;

package/dist/plan.js

@@ -0,0 +1,59 @@
+import path from "node:path";
+import { CliUsageError } from "./errors.js";
+import { titleCaseFromName, validateLibrary, validateName, validateRuntimeSpec, validateTitle, } from "./validate.js";
+/** Applies defaults (spec #2) and validates each value separately (spec #3). */
+export function resolvePlan(options, destinationRaw, cwd) {
+    const destinationPath = path.resolve(cwd, destinationRaw);
+    const name = options.name ?? path.basename(destinationPath);
+    try {
+        validateName(name);
+    }
+    catch (error) {
+        if (options.name === undefined && error instanceof CliUsageError) {
+            throw new CliUsageError(`Cannot derive a valid package name from "${path.basename(destinationPath)}": ${error.message} Pass --name explicitly.`);
+        }
+        throw error;
+    }
+    const title = options.title ?? titleCaseFromName(name);
+    validateTitle(title);
+    const library = options.library ?? libraryFromName(name);
+    try {
+        validateLibrary(library);
+    }
+    catch (error) {
+        if (options.library === undefined && error instanceof CliUsageError) {
+            throw new CliUsageError(`Cannot derive a valid library name from "${name}": ${error.message} Pass --library explicitly.`);
+        }
+        throw error;
+    }
+    if (options.runtimeSpec !== undefined)
+        validateRuntimeSpec(options.runtimeSpec);
+    return {
+        destinationPath,
+        name,
+        title,
+        library,
+        agent: options.agent,
+        install: options.install,
+        git: options.git,
+        runtimeSpec: options.runtimeSpec,
+    };
+}
+/** Renders the plan for the pre-flight printout (spec #5). */
+export function formatPlan(plan) {
+    return [
+        "Plan:",
+        `  destination: ${plan.destinationPath}`,
+        `  name: ${plan.name}`,
+        `  title: ${plan.title}`,
+        `  library: ${plan.library}`,
+        `  agent: ${plan.agent}`,
+        `  install: ${plan.install ? "yes" : "no"}`,
+        `  git: ${plan.git ? "yes" : "no"}`,
+        `  runtimeSpec: ${plan.runtimeSpec ?? "(template default)"}`,
+    ].join("\n");
+}
+/** Package names may be scoped or dotted; KiCad library names may not. */
+function libraryFromName(name) {
+    return name.replace(/^@[^/]+\//, "").replace(/[^A-Za-z0-9_-]/g, "-").slice(0, 64);
+}

package/dist/prompt.d.ts

@@ -0,0 +1,3 @@
+import type { Readable, Writable } from "node:stream";
+/** Prompts on a TTY for the destination directory (spec #2). */
+export declare function promptForDestination(input: Readable, output: Writable): Promise<string>;

package/dist/prompt.js

@@ -0,0 +1,12 @@
+import readline from "node:readline/promises";
+/** Prompts on a TTY for the destination directory (spec #2). */
+export async function promptForDestination(input, output) {
+    const rl = readline.createInterface({ input, output });
+    try {
+        const answer = await rl.question("Project directory: ");
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/scaffold.d.ts

@@ -0,0 +1,22 @@
+import type { Plan } from "./plan.ts";
+export interface PlaceholderValues {
+    __PROJECT_NAME__: string;
+    __SITE_TITLE__: string;
+    __LIBRARY_NAME__: string;
+}
+export declare function placeholdersFromPlan(plan: Plan): PlaceholderValues;
+/** Throws a CliError, unchanged, if the destination exists and is not empty (spec #4). There is no force flag. */
+export declare function checkDestinationCollision(destinationPath: string): void;
+export interface ComposeParams {
+    plan: Plan;
+    templateDir: URL | string;
+    randomSuffix: () => string;
+    /** Test-only seam: called before each file is copied; throwing simulates a mid-copy failure. */
+    beforeCopyFile?: (relPath: string) => void;
+}
+/**
+ * Composes the project into a sibling staging directory, then renames it
+ * onto the destination in one atomic step (spec #6). On any failure the
+ * staging directory is removed and the destination is left untouched.
+ */
+export declare function composeProject(params: ComposeParams): void;