@clubedge/create-clubedge-app 0.2.1 → 0.3.0

package/dist/cli/args.js

@@ -0,0 +1,49 @@
+import { parseArgs } from "node:util";
+export class UsageError extends Error {
+    name = "UsageError";
+}
+export function parseCliArgs(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            allowNegative: true,
+            strict: true,
+            options: {
+                ref: { type: "string" },
+                "template-dir": { type: "string" },
+                install: { type: "boolean", default: true },
+                git: { type: "boolean", default: true },
+                yes: { type: "boolean", short: "y", default: false },
+                "dry-run": { type: "boolean", default: false },
+                help: { type: "boolean", short: "h", default: false },
+                version: { type: "boolean", short: "v", default: false },
+            },
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new UsageError(`${message.split("\n")[0]} Run with --help to see available options.`);
+    }
+    const { values, positionals } = parsed;
+    if (positionals.length > 1)
+        throw new UsageError("Only one project directory can be provided.");
+    if (values.ref !== undefined && !values.ref.trim()) {
+        throw new UsageError("--ref requires a tag, branch, or commit.");
+    }
+    if (values.ref && values["template-dir"]) {
+        throw new UsageError("Use either --ref or --template-dir, not both.");
+    }
+    return {
+        projectDirectory: positionals[0],
+        ref: values.ref,
+        templateDir: values["template-dir"],
+        install: values.install,
+        git: values.git,
+        yes: values.yes,
+        dryRun: values["dry-run"],
+        help: values.help,
+        version: values.version,
+    };
+}

package/dist/cli/ui.js

@@ -0,0 +1,85 @@
+import process from "node:process";
+import { cliUrl, cliVersion, siteUrl, starterPin } from "../package-info.js";
+// Each glyph is 6 rows tall. Rows are padded to a common width when rendered.
+const glyphs = {
+    C: [" ██████╗", "██╔════╝", "██║     ", "██║     ", "╚██████╗", " ╚═════╝"],
+    L: ["██╗     ", "██║     ", "██║     ", "██║     ", "███████╗", "╚══════╝"],
+    U: ["██╗   ██╗", "██║   ██║", "██║   ██║", "██║   ██║", "╚██████╔╝", " ╚═════╝ "],
+    B: ["██████╗ ", "██╔══██╗", "██████╔╝", "██╔══██╗", "██████╔╝", "╚═════╝ "],
+    E: ["███████╗", "██╔════╝", "█████╗  ", "██╔══╝  ", "███████╗", "╚══════╝"],
+    D: ["██████╗ ", "██╔══██╗", "██║  ██║", "██║  ██║", "██████╔╝", "╚═════╝ "],
+    G: [" ██████╗ ", "██╔════╝ ", "██║  ███╗", "██║   ██║", "╚██████╔╝", " ╚═════╝ "],
+    S: ["███████╗", "██╔════╝", "███████╗", "╚════██║", "███████║", "╚══════╝"],
+    T: ["████████╗", "╚══██╔══╝", "   ██║   ", "   ██║   ", "   ██║   ", "   ╚═╝   "],
+    A: [" █████╗ ", "██╔══██╗", "███████║", "██╔══██║", "██║  ██║", "╚═╝  ╚═╝"],
+    R: ["██████╗ ", "██╔══██╗", "██████╔╝", "██╔══██╗", "██║  ██║", "╚═╝  ╚═╝"],
+};
+function renderWord(word) {
+    const letters = [...word].map((letter) => {
+        const rows = glyphs[letter];
+        const width = Math.max(...rows.map((row) => row.length));
+        return rows.map((row) => row.padEnd(width, " "));
+    });
+    return letters[0].map((_, rowIndex) => letters.map((letter) => letter[rowIndex]).join(""));
+}
+const colorEnabled = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR && process.env.TERM !== "dumb";
+const paint = (rgb, value) => colorEnabled ? `\x1b[38;2;${rgb.join(";")}m${value}\x1b[0m` : value;
+export const dim = (value) => (colorEnabled ? `\x1b[2m${value}\x1b[0m` : value);
+export const bold = (value) => (colorEnabled ? `\x1b[1m${value}\x1b[0m` : value);
+// Light violet -> Clubedge brand violet, top to bottom across the banner.
+const gradientFrom = [165, 140, 255];
+const gradientTo = [91, 61, 245];
+const mix = (from, to, t) => from.map((channel, index) => Math.round(channel + (to[index] - channel) * t));
+export function showBanner() {
+    // Stay quiet when output is piped (CI, logs, scripts).
+    if (!process.stdout.isTTY)
+        return;
+    const columns = process.stdout.columns ?? 80;
+    const lines = [...renderWord("CLUBEDGE"), ...renderWord("STARTER")];
+    const widest = Math.max(...lines.map((line) => line.length));
+    console.log("");
+    if (columns >= widest + 2) {
+        lines.forEach((line, index) => {
+            console.log(paint(mix(gradientFrom, gradientTo, index / (lines.length - 1)), line));
+        });
+    }
+    else {
+        // Narrow terminal: compact wordmark instead of wrapping the big letters.
+        console.log(paint(gradientTo, bold("CLUBEDGE STARTER")));
+    }
+    console.log("");
+    console.log(`  ${bold("create-clubedge-app")} ${dim(`v${cliVersion}`)}  ${dim("·")}  ${paint(gradientFrom, cliUrl)}`);
+    console.log(`  ${dim("By Clubedge")}  ${dim("·")}  ${paint(gradientFrom, siteUrl)}`);
+    console.log("");
+}
+export function helpText() {
+    return `
+create-clubedge-app ${cliVersion}
+
+Create a project from the Clubedge Starter reference repository.
+This CLI release scaffolds Starter ${starterPin.starterRef} (commit ${starterPin.starterCommit}).
+
+Usage:
+  pnpm dlx @clubedge/create-clubedge-app [project-directory] [options]
+
+Options:
+  --ref <ref>             Download this Starter tag, branch, or commit from GitHub instead
+  --template-dir <path>   Scaffold from a local Starter checkout (for Starter development)
+  --dry-run               Show what would be created without writing anything
+  -y, --yes               Accept defaults and never prompt (default directory: my-app)
+  --no-install            Skip dependency installation
+  --no-git                Skip Git repository initialization
+  -h, --help              Show this help
+  -v, --version           Show the CLI version
+
+Examples:
+  pnpm dlx @clubedge/create-clubedge-app my-app
+  pnpm dlx @clubedge/create-clubedge-app my-app --dry-run
+  pnpm dlx @clubedge/create-clubedge-app my-app --ref main
+  pnpm dlx @clubedge/create-clubedge-app my-app --template-dir ../clubedge-starter
+
+Learn more:
+  CLI      ${cliUrl}
+  Clubedge ${siteUrl}
+`;
+}

package/dist/core/customize.js

@@ -0,0 +1,56 @@
+// Pure text transforms applied to template files. Keeping them free of I/O makes each one easy
+// to test and lets --dry-run describe them without touching the disk.
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+export function customizeRootManifest(source, { packageName }, provenance, dockerImage) {
+    const manifest = JSON.parse(source);
+    manifest.name = packageName;
+    manifest.clubedge = {
+        cliVersion: provenance.cliVersion,
+        starterRepository: provenance.starterRepository,
+        starterRef: provenance.starterRef,
+        ...(provenance.starterCommit ? { starterCommit: provenance.starterCommit } : {}),
+    };
+    for (const script of ["docker:build", "docker:start"]) {
+        if (typeof manifest.scripts?.[script] === "string") {
+            manifest.scripts[script] = manifest.scripts[script].replaceAll(dockerImage, packageName);
+        }
+    }
+    return json(manifest);
+}
+export function customizeReadme(source, { displayName }, provenance) {
+    const commitLine = provenance.starterCommit
+        ? `\n- Starter commit: \`${provenance.starterCommit}\``
+        : "";
+    const origin = `## Generated from\n\n` +
+        `- Starter repository: \`${provenance.starterRepository}\`\n` +
+        `- Starter ref: \`${provenance.starterRef}\`${commitLine}\n` +
+        `- CLI version: \`${provenance.cliVersion}\``;
+    // Only the first heading is the project title; leave every other line as written.
+    return source.replace(/^# .+$/m, `# ${displayName}\n\n${origin}`);
+}
+export function customizeSiteConfig(source, { packageName, displayName }) {
+    const siteConfig = JSON.parse(source);
+    siteConfig.name = displayName;
+    siteConfig.shortName = displayName;
+    siteConfig.description = `${displayName} application foundation.`;
+    siteConfig.serviceId = packageName;
+    siteConfig.workspaceLabel = "Application workspace";
+    return json(siteConfig);
+}
+/** Starter v0.1.x has no site config; these files carried the project name instead. */
+export const legacyBrandedFiles = [
+    "apps/web/src/app/layout.tsx",
+    "apps/web/src/app/page.tsx",
+    "apps/web/src/app/dashboard/_components/app-sidebar.tsx",
+    "apps/web/src/app/dashboard/page.tsx",
+    "apps/web/src/app/login/page.tsx",
+];
+export function customizeLegacySource(source, { displayName }) {
+    return source
+        .replaceAll('"Clubedge Starter"', JSON.stringify(displayName))
+        .replace("%s · Clubedge Starter", `%s · ${displayName}`)
+        .replace("A production-minded foundation for Clubedge applications.", `${displayName} application foundation.`)
+        .replaceAll("Clubedge Starter", displayName)
+        .replaceAll(">Clubedge<", `>${displayName}<`)
+        .replaceAll("Starter workspace", "Application workspace");
+}

package/dist/core/execute.js

@@ -0,0 +1,60 @@
+import { constants } from "node:fs";
+import { copyFile, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join, parse } from "node:path";
+import { copyTemplateFiles, emptyDirectory } from "../utils/fs.js";
+export class TargetError extends Error {
+    name = "TargetError";
+}
+/** Refuses filesystem roots and non-empty directories. Never deletes or overwrites anything. */
+export async function assertTargetIsUsable(directory) {
+    if (parse(directory).root === directory) {
+        throw new TargetError("Choose a project subdirectory rather than a filesystem root.");
+    }
+    try {
+        const entries = await readdir(directory);
+        if (entries.length > 0)
+            throw new TargetError(`The target directory is not empty: ${directory}`);
+    }
+    catch (error) {
+        if (error instanceof TargetError)
+            throw error;
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT")
+            return;
+        throw error;
+    }
+}
+/**
+ * Writes the project described by the plan. If any step fails, everything written so far is
+ * removed: a directory the CLI created is deleted, and a pre-existing empty one is emptied.
+ */
+export async function executePlan(plan, source) {
+    const target = plan.targetDirectory;
+    await assertTargetIsUsable(target);
+    await mkdir(dirname(target), { recursive: true });
+    let created = false;
+    try {
+        await mkdir(target);
+        created = true;
+    }
+    catch (error) {
+        if (!(error && typeof error === "object" && "code" in error && error.code === "EEXIST"))
+            throw error;
+    }
+    try {
+        await copyTemplateFiles(source.root, target, plan.files);
+        for (const edit of plan.edits) {
+            const path = join(target, edit.path);
+            await writeFile(path, edit.apply(await readFile(path, "utf8")));
+        }
+        if (plan.envFile) {
+            await copyFile(join(target, plan.envFile.from), join(target, plan.envFile.to), constants.COPYFILE_EXCL);
+        }
+    }
+    catch (error) {
+        if (created)
+            await rm(target, { recursive: true, force: true });
+        else
+            await emptyDirectory(target);
+        throw error;
+    }
+}

package/dist/core/manifest.js

@@ -0,0 +1,81 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+export const MANIFEST_FILE = "clubedge.template.json";
+export const SUPPORTED_SCHEMA_VERSION = 1;
+/** Starter releases before v0.3.0 have no manifest; this describes their layout. */
+export const legacyManifest = {
+    schemaVersion: 1,
+    name: "clubedge-starter",
+    packageManager: "pnpm",
+    app: "apps/web",
+    siteConfig: "apps/web/src/config/site.json",
+    env: { example: ".env.example", target: "apps/web/.env.local" },
+    dockerImage: "clubedge-starter",
+    exclude: [],
+};
+export class ManifestError extends Error {
+    name = "ManifestError";
+}
+export function parseTemplateManifest(source) {
+    let data;
+    try {
+        data = JSON.parse(source);
+    }
+    catch {
+        throw new ManifestError(`${MANIFEST_FILE} is not valid JSON.`);
+    }
+    if (!isRecord(data))
+        throw new ManifestError(`${MANIFEST_FILE} must contain an object.`);
+    const { schemaVersion } = data;
+    if (typeof schemaVersion !== "number" || !Number.isInteger(schemaVersion)) {
+        throw new ManifestError(`${MANIFEST_FILE} is missing a numeric schemaVersion.`);
+    }
+    if (schemaVersion > SUPPORTED_SCHEMA_VERSION) {
+        throw new ManifestError(`This Starter uses template schema ${schemaVersion}, but this CLI supports up to ${SUPPORTED_SCHEMA_VERSION}. ` +
+            "Run the latest CLI: pnpm dlx @clubedge/create-clubedge-app@latest");
+    }
+    const env = data.env;
+    if (data.packageManager !== "pnpm") {
+        throw new ManifestError(`${MANIFEST_FILE}: packageManager must be "pnpm".`);
+    }
+    if (!isRecord(env))
+        throw new ManifestError(`${MANIFEST_FILE}: env must be an object.`);
+    if (data.exclude !== undefined && !isStringArray(data.exclude)) {
+        throw new ManifestError(`${MANIFEST_FILE}: exclude must be an array of paths.`);
+    }
+    return {
+        schemaVersion,
+        name: requireString(data, "name"),
+        packageManager: "pnpm",
+        app: requireString(data, "app"),
+        siteConfig: requireString(data, "siteConfig"),
+        env: { example: requireString(env, "example", "env."), target: requireString(env, "target", "env.") },
+        dockerImage: requireString(data, "dockerImage"),
+        exclude: data.exclude ?? [],
+    };
+}
+export async function readTemplateManifest(templateRoot) {
+    let source;
+    try {
+        source = await readFile(join(templateRoot, MANIFEST_FILE), "utf8");
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === "ENOENT")
+            return legacyManifest;
+        throw error;
+    }
+    return parseTemplateManifest(source);
+}
+function requireString(record, key, prefix = "") {
+    const value = record[key];
+    if (typeof value !== "string" || !value) {
+        throw new ManifestError(`${MANIFEST_FILE}: ${prefix}${key} must be a non-empty string.`);
+    }
+    return value;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}

package/dist/core/plan.js

@@ -0,0 +1,67 @@
+import { customizeLegacySource, customizeReadme, customizeRootManifest, customizeSiteConfig, legacyBrandedFiles, } from "./customize.js";
+function isExcluded(path, exclude) {
+    return exclude.some((entry) => path === entry || path.startsWith(`${entry.replace(/\/$/, "")}/`));
+}
+export function createPlan(input) {
+    const { manifest, identity, source } = input;
+    const provenance = {
+        cliVersion: input.cliVersion,
+        starterRepository: source.repository,
+        starterRef: source.ref,
+        ...(source.commit ? { starterCommit: source.commit } : {}),
+    };
+    const files = source.files.filter(({ to }) => !isExcluded(to, manifest.exclude) && to !== manifest.env.target);
+    const has = (path) => files.some(({ to }) => to === path);
+    const edits = [];
+    if (has("package.json")) {
+        edits.push({
+            path: "package.json",
+            description: `Name the package "${identity.packageName}" and record its origin`,
+            apply: (text) => customizeRootManifest(text, identity, provenance, manifest.dockerImage),
+        });
+    }
+    if (has("README.md")) {
+        edits.push({
+            path: "README.md",
+            description: `Title the README "${identity.displayName}" and record its origin`,
+            apply: (text) => customizeReadme(text, identity, provenance),
+        });
+    }
+    if (has(manifest.siteConfig)) {
+        edits.push({
+            path: manifest.siteConfig,
+            description: `Set the project name to "${identity.displayName}"`,
+            apply: (text) => customizeSiteConfig(text, identity),
+        });
+    }
+    else {
+        for (const path of legacyBrandedFiles.filter(has)) {
+            edits.push({
+                path,
+                description: `Replace the Starter name with "${identity.displayName}"`,
+                apply: (text) => customizeLegacySource(text, identity),
+            });
+        }
+    }
+    return {
+        targetDirectory: input.targetDirectory,
+        identity,
+        provenance,
+        files,
+        edits,
+        envFile: has(manifest.env.example) ? { from: manifest.env.example, to: manifest.env.target } : null,
+        git: input.git,
+        install: input.install,
+    };
+}
+export function describePlan(plan) {
+    return [
+        `Create ${plan.targetDirectory}`,
+        `Copy ${plan.files.length} files from ${plan.provenance.starterRepository}@${plan.provenance.starterRef}` +
+            (plan.provenance.starterCommit ? ` (${plan.provenance.starterCommit.slice(0, 8)})` : ""),
+        ...plan.edits.map((edit) => `Edit ${edit.path}: ${edit.description}`),
+        ...(plan.envFile ? [`Create ${plan.envFile.to} from ${plan.envFile.from}`] : []),
+        plan.git ? "Initialize a Git repository on main" : "Skip Git initialization",
+        plan.install ? "Install dependencies with pnpm" : "Skip dependency installation",
+    ];
+}

package/dist/core/source.js

@@ -0,0 +1,107 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { downloadTemplate } from "giget";
+import { starterPin } from "../package-info.js";
+import { fromPackedPath, listTemplateFiles, pathExists } from "../utils/fs.js";
+import { runCapture } from "../utils/process.js";
+// dist/core/source.js (or src/core/source.ts in tests) → the package root.
+const packageRoot = fileURLToPath(new URL("../..", import.meta.url));
+export const bundledTemplateDirectory = join(packageRoot, "template");
+export const bundledLockFile = join(packageRoot, "template.lock.json");
+const noCleanup = async () => { };
+export async function readBundledTemplate(lockFile = bundledLockFile, templateDirectory = bundledTemplateDirectory) {
+    if (!(await pathExists(lockFile)))
+        return null;
+    const lock = JSON.parse(await readFile(lockFile, "utf8"));
+    return {
+        kind: "bundled",
+        root: templateDirectory,
+        files: lock.files.map((from) => ({ from, to: fromPackedPath(from) })),
+        repository: lock.repository,
+        ref: lock.ref,
+        commit: lock.commit,
+        cleanup: noCleanup,
+    };
+}
+export async function readDirectoryTemplate(directory) {
+    const root = resolve(directory);
+    if (!(await pathExists(join(root, "package.json")))) {
+        throw new Error(`No Starter found at ${root}: package.json is missing.`);
+    }
+    const files = await listTemplateFiles(root);
+    let commit;
+    try {
+        commit = await runCapture("git", ["-C", root, "rev-parse", "HEAD"]);
+    }
+    catch {
+        commit = undefined;
+    }
+    return {
+        kind: "directory",
+        root,
+        files: files.map((file) => ({ from: file, to: file })),
+        repository: starterPin.starterRepository,
+        ref: "local",
+        commit,
+        cleanup: noCleanup,
+    };
+}
+/** Resolves a tag to its commit with `git ls-remote`, following annotated tags. */
+export async function resolveTagCommit(repository, tag) {
+    const output = await runCapture("git", [
+        "ls-remote",
+        `https://github.com/${repository}.git`,
+        `refs/tags/${tag}^{}`,
+        `refs/tags/${tag}`,
+    ]);
+    const lines = output.split("\n").map((line) => line.split(/\s+/));
+    const peeled = lines.find(([, ref]) => ref?.endsWith("^{}"));
+    return (peeled ?? lines[0])?.[0] || undefined;
+}
+export async function downloadGitHubTemplate(ref, { repository = starterPin.starterRepository, expectedCommit } = {}) {
+    if (expectedCommit) {
+        const commit = await resolveTagCommit(repository, ref);
+        if (commit !== expectedCommit) {
+            throw new Error(`Starter tag ${ref} resolved to ${commit ?? "no commit"}, expected ${expectedCommit}.`);
+        }
+    }
+    const temporary = await mkdtemp(join(tmpdir(), "create-clubedge-app-"));
+    const cleanup = () => rm(temporary, { recursive: true, force: true });
+    try {
+        const root = join(temporary, "starter");
+        await downloadTemplate(`gh:${repository}#${ref}`, { dir: root, force: true });
+        const files = await listTemplateFiles(root);
+        return {
+            kind: "github",
+            root,
+            files: files.map((file) => ({ from: file, to: file })),
+            repository,
+            ref,
+            commit: expectedCommit,
+            cleanup,
+        };
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+}
+/**
+ * Picks where template files come from: a local directory, an explicit ref from GitHub, or
+ * the Starter bundled into this package. Without a bundle (a CLI checkout that has not run
+ * bundle-template), the pinned release is downloaded and its commit verified.
+ */
+export async function resolveTemplateSource({ ref, templateDir }) {
+    if (templateDir)
+        return readDirectoryTemplate(templateDir);
+    const pinned = !ref || ref === starterPin.starterRef;
+    if (!pinned)
+        return downloadGitHubTemplate(ref);
+    const bundled = await readBundledTemplate();
+    if (bundled && bundled.ref === starterPin.starterRef && bundled.commit === starterPin.starterCommit) {
+        return bundled;
+    }
+    return downloadGitHubTemplate(starterPin.starterRef, { expectedCommit: starterPin.starterCommit });
+}

package/dist/index.js

@@ -0,0 +1,125 @@
+import { cancel, intro, isCancel, log, outro, spinner, text } from "@clack/prompts";
+import { relative, resolve } from "node:path";
+import process from "node:process";
+import { parseCliArgs, UsageError } from "./cli/args.js";
+import { dim, helpText, showBanner } from "./cli/ui.js";
+import { assertTargetIsUsable, executePlan } from "./core/execute.js";
+import { readTemplateManifest } from "./core/manifest.js";
+import { createPlan, describePlan } from "./core/plan.js";
+import { resolveTemplateSource } from "./core/source.js";
+import { cliUrl, cliVersion, siteUrl } from "./package-info.js";
+import { initializeGit } from "./steps/git.js";
+import { detectLauncher, installDependencies, resolvePnpm } from "./steps/install.js";
+import { displayNameFromPackageName, packageNameFromDirectory } from "./utils/names.js";
+const minimumNode = [22, 12];
+export function assertSupportedNode(version = process.versions.node) {
+    const [major = 0, minor = 0] = version.split(".").map(Number);
+    if (major < minimumNode[0] || (major === minimumNode[0] && minor < minimumNode[1])) {
+        throw new UsageError(`Node.js ${minimumNode.join(".")} or newer is required; this is ${version}.`);
+    }
+}
+async function askProjectDirectory() {
+    const value = await text({
+        message: "Where should the new project be created?",
+        placeholder: "my-app",
+        validate: (input) => (input?.trim() ? undefined : "Enter a project directory name."),
+    });
+    if (isCancel(value)) {
+        cancel("Operation cancelled.");
+        process.exit(0);
+    }
+    return value;
+}
+async function createProject(args) {
+    const interactive = Boolean(process.stdin.isTTY) && !args.yes;
+    const requested = args.projectDirectory ?? (interactive ? await askProjectDirectory() : "my-app");
+    const targetDirectory = resolve(process.cwd(), requested);
+    await assertTargetIsUsable(targetDirectory);
+    const packageName = packageNameFromDirectory(targetDirectory);
+    const identity = { packageName, displayName: displayNameFromPackageName(packageName) };
+    const progress = spinner();
+    progress.start("Preparing the Starter");
+    const source = await resolveTemplateSource({ ref: args.ref, templateDir: args.templateDir }).catch((error) => {
+        progress.stop("Could not prepare the Starter");
+        throw error;
+    });
+    try {
+        const manifest = await readTemplateManifest(source.root);
+        const plan = createPlan({
+            targetDirectory,
+            identity,
+            source,
+            manifest,
+            cliVersion,
+            git: args.git,
+            install: args.install,
+        });
+        if (args.dryRun) {
+            progress.stop("Dry run: nothing was written");
+            log.message(describePlan(plan).map((line) => `• ${line}`).join("\n"));
+            outro("Run again without --dry-run to create the project.");
+            return;
+        }
+        progress.message(`Writing ${plan.files.length} files`);
+        await executePlan(plan, source);
+        progress.stop(`Created ${identity.packageName} from Starter ${source.ref}`);
+    }
+    catch (error) {
+        progress.stop("Project scaffold failed; nothing was left behind");
+        throw error;
+    }
+    finally {
+        await source.cleanup();
+    }
+    if (args.git) {
+        await initializeGit(targetDirectory);
+        log.success("Git repository initialized on main");
+    }
+    let pnpmCommand = "pnpm";
+    if (args.install) {
+        const launcher = detectLauncher();
+        if (launcher && launcher !== "pnpm") {
+            log.info(`This project is a pnpm workspace, so dependencies are installed with pnpm (not ${launcher}).`);
+        }
+        const pnpm = await resolvePnpm();
+        if (!pnpm) {
+            log.warn("pnpm was not found. Enable it with `corepack enable`, then run `pnpm install` in the project.");
+        }
+        else {
+            pnpmCommand = pnpm.join(" ");
+            try {
+                await installDependencies(targetDirectory, pnpm);
+                log.success("Dependencies installed");
+            }
+            catch (error) {
+                log.error(`Project created; dependency installation did not complete. ${error instanceof Error ? error.message : ""}`);
+                log.info(`Run \`${pnpmCommand} install\` in the project to retry.`);
+            }
+        }
+    }
+    const directory = relative(process.cwd(), targetDirectory) || ".";
+    outro(`Next steps:\n  cd ${directory}\n  ${pnpmCommand} dev\n\n` +
+        `See SETUP.md for database and provider configuration.\n\n` +
+        `${dim("Docs")}     ${cliUrl}\n${dim("Clubedge")} ${siteUrl}`);
+}
+export async function main(argv = process.argv.slice(2)) {
+    try {
+        const args = parseCliArgs(argv);
+        if (args.version) {
+            console.log(cliVersion);
+            return;
+        }
+        showBanner();
+        if (args.help) {
+            console.log(helpText());
+            return;
+        }
+        assertSupportedNode();
+        intro("Create a project with Clubedge Starter");
+        await createProject(args);
+    }
+    catch (error) {
+        console.error(`\n${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    }
+}

package/dist/package-info.js

@@ -0,0 +1,8 @@
+import { readFileSync } from "node:fs";
+// package.json is the single source for the version and the tested Starter pin. It ships
+// with the package, so the npm registry exposes exactly what each release scaffolds.
+const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+export const cliVersion = packageJson.version;
+export const starterPin = packageJson.clubedge;
+export const siteUrl = "https://clubedge.live";
+export const cliUrl = "https://starter.clubedge.live";

package/dist/steps/git.js

@@ -0,0 +1,11 @@
+import { run } from "../utils/process.js";
+export async function initializeGit(directory) {
+    try {
+        await run("git", ["init", "-b", "main"], directory);
+    }
+    catch {
+        // Git before 2.28 has no -b option.
+        await run("git", ["init"], directory);
+        await run("git", ["branch", "-M", "main"], directory);
+    }
+}