@clubedge/create-clubedge-app 0.2.1 → 0.4.0

package/dist/core/customize.js

@@ -0,0 +1,95 @@
+// 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 } : {}),
+        ...(provenance.framework ? { framework: provenance.framework } : {}),
+    };
+    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 frameworkLine = provenance.frameworkName ? `\n- Framework: ${provenance.frameworkName}` : "";
+    const origin = `## Generated from\n\n` +
+        `- Starter repository: \`${provenance.starterRepository}\`\n` +
+        `- Starter ref: \`${provenance.starterRef}\`${commitLine}${frameworkLine}\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");
+}
+/** Gives the selected framework's app the package name generated projects use. */
+export function customizeAppManifest(source, appPackage) {
+    const manifest = JSON.parse(source);
+    manifest.name = appPackage;
+    return json(manifest);
+}
+/**
+ * Keeps pnpm-lock.yaml in step with the selected framework so `pnpm install --frozen-lockfile`
+ * works. Importers are keyed by workspace path at two-space indentation; package entries that
+ * are no longer used are harmless, and pnpm prunes them on the next lockfile update.
+ */
+export function customizeLockfile(source, { remove, rename }) {
+    const output = [];
+    let inImporters = false;
+    let skipping = false;
+    for (const line of source.split("\n")) {
+        if (/^\S/.test(line)) {
+            inImporters = line === "importers:";
+            skipping = false;
+        }
+        else if (inImporters) {
+            // An importer key, with its value on the next lines or inline ("packages/core: {}").
+            const key = /^ {2}([^\s:][^:]*):(?: |$)/.exec(line)?.[1];
+            if (key !== undefined) {
+                skipping = remove.includes(key);
+                if (!skipping && key === rename?.from) {
+                    output.push(`  ${rename.to}:`);
+                    continue;
+                }
+            }
+            if (skipping)
+                continue;
+        }
+        output.push(line);
+    }
+    return output.join("\n");
+}

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,119 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+export const MANIFEST_FILE = "clubedge.template.json";
+export const SUPPORTED_SCHEMA_VERSION = 2;
+/** Schema 1 Starters ship a single Next.js app at the generated location. */
+function singleNextFramework(app, envExample) {
+    return {
+        defaultFramework: "next",
+        frameworks: { next: { name: "Next.js", app, envExample, dockerfile: "Dockerfile" } },
+    };
+}
+/** 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",
+    ...singleNextFramework("apps/web", ".env.example"),
+    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.`);
+    }
+    const app = requireString(data, "app");
+    const envExample = requireString(env, "example", "env.");
+    return {
+        schemaVersion,
+        name: requireString(data, "name"),
+        packageManager: "pnpm",
+        app,
+        ...(schemaVersion >= 2 ? { appPackage: requireString(data, "appPackage") } : {}),
+        siteConfig: requireString(data, "siteConfig"),
+        env: { example: envExample, target: requireString(env, "target", "env.") },
+        dockerImage: requireString(data, "dockerImage"),
+        ...(schemaVersion >= 2 ? parseFrameworks(data) : singleNextFramework(app, envExample)),
+        exclude: data.exclude ?? [],
+    };
+}
+function parseFrameworks(data) {
+    const { frameworks } = data;
+    if (!isRecord(frameworks) || Object.keys(frameworks).length === 0) {
+        throw new ManifestError(`${MANIFEST_FILE}: frameworks must describe at least one framework.`);
+    }
+    const parsed = {};
+    for (const [id, entry] of Object.entries(frameworks)) {
+        if (!/^[a-z][a-z0-9-]*$/.test(id)) {
+            throw new ManifestError(`${MANIFEST_FILE}: "${id}" is not a valid framework id.`);
+        }
+        if (!isRecord(entry))
+            throw new ManifestError(`${MANIFEST_FILE}: frameworks.${id} must be an object.`);
+        const prefix = `frameworks.${id}.`;
+        parsed[id] = {
+            name: requireString(entry, "name", prefix),
+            app: requireString(entry, "app", prefix),
+            envExample: requireString(entry, "envExample", prefix),
+            dockerfile: requireString(entry, "dockerfile", prefix),
+        };
+    }
+    const defaultFramework = requireString(data, "defaultFramework");
+    if (!parsed[defaultFramework]) {
+        throw new ManifestError(`${MANIFEST_FILE}: defaultFramework "${defaultFramework}" is not in frameworks.`);
+    }
+    return { defaultFramework, frameworks: parsed };
+}
+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,132 @@
+import { customizeAppManifest, customizeLegacySource, customizeLockfile, customizeReadme, customizeRootManifest, customizeSiteConfig, legacyBrandedFiles, } from "./customize.js";
+export class FrameworkError extends Error {
+    name = "FrameworkError";
+}
+const LOCKFILE = "pnpm-lock.yaml";
+const isWithin = (path, directory) => path === directory || path.startsWith(`${directory.replace(/\/$/, "")}/`);
+function isExcluded(path, exclude) {
+    return exclude.some((entry) => isWithin(path, entry));
+}
+/** Resolves the requested framework, or the default, with a helpful error for unknown ids. */
+export function selectFramework(manifest, requested) {
+    const id = requested ?? manifest.defaultFramework;
+    const framework = manifest.frameworks[id];
+    if (!framework) {
+        const choices = Object.keys(manifest.frameworks).join(", ");
+        throw new FrameworkError(`Unknown framework "${id}". This Starter offers: ${choices}.`);
+    }
+    return { id, ...framework };
+}
+/**
+ * Where a Starter file lands in the generated project, or null when it belongs to a framework
+ * that was not selected. The selected app moves to `manifest.app`, and its environment example
+ * and Dockerfile move to the generated project's locations.
+ */
+function relocate(path, manifest, selected, others) {
+    if (path === selected.envExample)
+        return manifest.env.example;
+    if (path === selected.dockerfile)
+        return "Dockerfile";
+    if (isWithin(path, selected.app))
+        return manifest.app + path.slice(selected.app.length);
+    const belongsToOther = others.some((other) => isWithin(path, other.app) || path === other.envExample || path === other.dockerfile);
+    return belongsToOther ? null : path;
+}
+export function createPlan(input) {
+    const { manifest, identity, source } = input;
+    const framework = selectFramework(manifest, input.framework);
+    const others = Object.entries(manifest.frameworks)
+        .filter(([id]) => id !== framework.id)
+        .map(([, other]) => other);
+    const multipleFrameworks = others.length > 0;
+    const provenance = {
+        cliVersion: input.cliVersion,
+        starterRepository: source.repository,
+        starterRef: source.ref,
+        ...(source.commit ? { starterCommit: source.commit } : {}),
+        ...(multipleFrameworks ? { framework: framework.id, frameworkName: framework.name } : {}),
+    };
+    const files = [];
+    for (const file of source.files) {
+        if (isExcluded(file.to, manifest.exclude))
+            continue;
+        const to = relocate(file.to, manifest, framework, others);
+        if (to !== null && to !== manifest.env.target)
+            files.push({ from: file.from, to });
+    }
+    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),
+        });
+    }
+    const appManifest = `${manifest.app}/package.json`;
+    if (manifest.appPackage && framework.app !== manifest.app && has(appManifest)) {
+        const appPackage = manifest.appPackage;
+        edits.push({
+            path: appManifest,
+            description: `Name the ${framework.name} app "${appPackage}"`,
+            apply: (text) => customizeAppManifest(text, appPackage),
+        });
+    }
+    if (multipleFrameworks && has(LOCKFILE)) {
+        const changes = {
+            remove: others.map((other) => other.app).filter((app) => app !== framework.app),
+            ...(framework.app !== manifest.app ? { rename: { from: framework.app, to: manifest.app } } : {}),
+        };
+        edits.push({
+            path: LOCKFILE,
+            description: `Keep only the ${framework.name} app in the lockfile`,
+            apply: (text) => customizeLockfile(text, changes),
+        });
+    }
+    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,
+        framework: { id: framework.id, name: framework.name },
+        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}`,
+        ...(plan.provenance.framework ? [`Use ${plan.framework.name}`] : []),
+        `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,160 @@
+import { cancel, intro, isCancel, log, outro, select, 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, selectFramework } 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;
+}
+/**
+ * The framework from --framework, a prompt when the Starter offers several, or the default.
+ * Returns null when the prompt is cancelled.
+ */
+async function chooseFramework(manifest, requested, interactive) {
+    if (requested)
+        return selectFramework(manifest, requested).id;
+    const ids = Object.keys(manifest.frameworks);
+    if (!interactive || ids.length < 2)
+        return manifest.defaultFramework;
+    const value = await select({
+        message: "Which framework should the app use?",
+        initialValue: manifest.defaultFramework,
+        options: ids.map((id) => ({
+            value: id,
+            label: manifest.frameworks[id].name,
+            ...(id === manifest.defaultFramework ? { hint: "default" } : {}),
+        })),
+    });
+    return isCancel(value) ? null : 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;
+    });
+    // The spinner runs while the manifest is read and again while files are written.
+    let spinning = "preparing";
+    try {
+        const manifest = await readTemplateManifest(source.root);
+        progress.stop(`Starter ${source.ref} ready`);
+        spinning = null;
+        const framework = await chooseFramework(manifest, args.framework, interactive);
+        if (framework === null) {
+            cancel("Operation cancelled.");
+            return;
+        }
+        const plan = createPlan({
+            targetDirectory,
+            identity,
+            source,
+            manifest,
+            framework,
+            cliVersion,
+            git: args.git,
+            install: args.install,
+        });
+        if (args.dryRun) {
+            log.message(describePlan(plan).map((line) => `• ${line}`).join("\n"));
+            outro("Dry run: nothing was written. Run again without --dry-run to create the project.");
+            return;
+        }
+        spinning = "writing";
+        progress.start(`Writing ${plan.files.length} files`);
+        await executePlan(plan, source);
+        progress.stop(`Created ${identity.packageName} with ${plan.framework.name} from Starter ${source.ref}`);
+        spinning = null;
+    }
+    catch (error) {
+        if (spinning === "preparing")
+            progress.stop("Could not read the Starter");
+        if (spinning === "writing")
+            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";