create-shape-app 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shape Network
+
+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,72 @@
+# create-shape-app
+
+CLI for scaffolding Shape apps from the Builder Kit template pinned to release tags.
+
+## Quick Start
+
+```bash
+bun create shape-app my-app --yes
+cd my-app
+bun run type-check
+bun run lint
+bun run contracts:compile
+```
+
+Equivalent commands:
+- `npm create shape-app@latest my-app -- --yes`
+- `pnpm dlx create-shape-app my-app --yes`
+- `yarn create shape-app my-app --yes`
+
+## CLI Usage
+
+```bash
+create-shape-app [project-name] [options]
+```
+
+Options:
+- `-y, --yes`
+- `--pm <bun|npm|pnpm|yarn>`
+- `--skip-install`
+- `--skip-git`
+- `--template-ref <tag>`
+
+## Behavior
+- Scaffolds from `shape-network/builder-kit` release tags only (`latest` by default).
+- Rejects non-release refs (for example `main`) and canary tags.
+- Copies template files, excluding VCS/internal maintainer metadata.
+- Applies defaults:
+  - Root `package.json` name is set from the project directory name.
+  - `.env.example` is copied to `.env` when present.
+  - Dependencies are installed unless `--skip-install` is set.
+  - Git is initialized unless `--skip-git` is set.
+
+## Troubleshooting
+- GitHub API rate limit during template lookup:
+  - retry later, set `GITHUB_TOKEN`, or pass `--template-ref <tag>`.
+- Git init or commit failure:
+  - scaffold still succeeds; run `git init && git add -A && git commit -m "Initial commit"` manually.
+- Dependency install failure:
+  - rerun your package manager (`bun install`, `npm install`, `pnpm install`, or `yarn install`) inside generated app.
+
+## Local Development
+
+```bash
+bun install
+bun run lint
+bun run type-check
+bun run test
+```
+
+Builder Kit README quickstart update snippet is tracked in:
+- `docs/builder-kit-quickstart.md`
+
+## Publish
+- Trigger: GitHub release publish event.
+- Guard: workflow checks release tag matches `package.json` version.
+- Requirement: repository secret `NPM_TOKEN` must be configured.
+- Publish target: npm package `create-shape-app`.
+
+## Community
+- Contribution guide: `CONTRIBUTING.md`
+- Security policy: `SECURITY.md`
+- Code of conduct: `CODE_OF_CONDUCT.md`

package/bin/create-shape-app.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runCLI } from '../dist/index.js';
+
+const exitCode = await runCLI(process.argv.slice(2));
+process.exit(exitCode);

package/dist/cli/args.d.ts

@@ -0,0 +1,12 @@
+export type PackageManager = 'bun' | 'npm' | 'pnpm' | 'yarn';
+export interface CliOptions {
+    help: boolean;
+    version: boolean;
+    yes: boolean;
+    skipInstall: boolean;
+    skipGit: boolean;
+    projectName?: string;
+    packageManager?: PackageManager;
+    templateRef?: string;
+}
+export declare function parseArgs(argv: string[]): CliOptions;

package/dist/cli/args.js

@@ -0,0 +1,82 @@
+import { CliUsageError } from './errors.js';
+const VALID_PACKAGE_MANAGERS = new Set(['bun', 'npm', 'pnpm', 'yarn']);
+export function parseArgs(argv) {
+    const options = {
+        help: false,
+        version: false,
+        yes: false,
+        skipInstall: false,
+        skipGit: false,
+    };
+    let nextValueFor;
+    for (const arg of argv) {
+        if (nextValueFor) {
+            assignFlagValue(options, nextValueFor, arg);
+            nextValueFor = undefined;
+            continue;
+        }
+        if (arg === '--yes' || arg === '-y') {
+            options.yes = true;
+            continue;
+        }
+        if (arg === '--skip-install') {
+            options.skipInstall = true;
+            continue;
+        }
+        if (arg === '--skip-git') {
+            options.skipGit = true;
+            continue;
+        }
+        if (arg === '--help' || arg === '-h') {
+            options.help = true;
+            continue;
+        }
+        if (arg === '--version' || arg === '-v') {
+            options.version = true;
+            continue;
+        }
+        if (arg === '--pm' || arg === '--template-ref') {
+            nextValueFor = arg;
+            continue;
+        }
+        if (arg.startsWith('--pm=')) {
+            assignPackageManager(options, arg.slice('--pm='.length));
+            continue;
+        }
+        if (arg.startsWith('--template-ref=')) {
+            options.templateRef = parseRequiredValue('--template-ref', arg.slice('--template-ref='.length));
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            throw new CliUsageError(`Unknown option: ${arg}`);
+        }
+        if (options.projectName) {
+            throw new CliUsageError('Only one project name may be provided.');
+        }
+        options.projectName = arg;
+    }
+    if (nextValueFor) {
+        throw new CliUsageError(`Missing value for ${nextValueFor}`);
+    }
+    return options;
+}
+function assignFlagValue(options, flag, value) {
+    const nextValue = parseRequiredValue(flag, value);
+    if (flag === '--pm') {
+        assignPackageManager(options, nextValue);
+        return;
+    }
+    options.templateRef = nextValue;
+}
+function assignPackageManager(options, value) {
+    if (!VALID_PACKAGE_MANAGERS.has(value)) {
+        throw new CliUsageError(`Unsupported package manager: ${value}`);
+    }
+    options.packageManager = value;
+}
+function parseRequiredValue(flag, value) {
+    if (!value.trim()) {
+        throw new CliUsageError(`Missing value for ${flag}`);
+    }
+    return value;
+}

package/dist/cli/errors.d.ts

@@ -0,0 +1,3 @@
+export declare class CliUsageError extends Error {
+    constructor(message: string);
+}

package/dist/cli/errors.js

@@ -0,0 +1,6 @@
+export class CliUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CliUsageError';
+    }
+}

package/dist/cli/help.d.ts

@@ -0,0 +1 @@
+export declare const HELP_TEXT: string;

package/dist/cli/help.js

@@ -0,0 +1,18 @@
+export const HELP_TEXT = `
+create-shape-app - Scaffold Shape Builder Kit apps from release tags
+
+Usage:
+  create-shape-app [project-name] [options]
+
+Notes:
+  If project-name is omitted in an interactive terminal, you will be prompted.
+
+Options:
+  -y, --yes                 Skip confirmation prompts
+  --pm <bun|npm|pnpm|yarn>  Select package manager
+  --skip-install            Skip dependency install step
+  --skip-git                Skip git init + initial commit
+  --template-ref <tag>      Optional tag override (must still be a release tag)
+  -h, --help                Show help
+  -v, --version             Show version
+`.trim();

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { type PostScaffoldSetupOptions, type PostScaffoldSetupResult } from './scaffold/post-setup.js';
+import { type MaterializedTemplate } from './template/materialize.js';
+import { type TemplateRelease } from './template/release.js';
+export declare const CLI_VERSION: string;
+interface CliRuntime {
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    stdinIsTTY: boolean;
+    stdoutIsTTY: boolean;
+    print: (message: string) => void;
+    printError: (message: string) => void;
+    prompt: (message: string) => Promise<string>;
+    confirm: (message: string) => Promise<boolean>;
+    resolveTemplateRelease: (templateRef?: string) => Promise<TemplateRelease>;
+    materializeTemplate: (release: TemplateRelease) => Promise<MaterializedTemplate>;
+    prepareTargetDirectory: (targetDirectory: string) => Promise<void>;
+    copyTemplateToDirectory: (templateRoot: string, targetDirectory: string) => Promise<void>;
+    runPostScaffoldSetup: (options: PostScaffoldSetupOptions) => Promise<PostScaffoldSetupResult>;
+}
+export declare function runCLI(argv: string[], runtimeOverrides?: Partial<CliRuntime>): Promise<number>;
+export {};

package/dist/index.js

@@ -0,0 +1,181 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+import readline from 'node:readline/promises';
+import { parseArgs } from './cli/args.js';
+import { CliUsageError } from './cli/errors.js';
+import { HELP_TEXT } from './cli/help.js';
+import { runPostScaffoldSetup, } from './scaffold/post-setup.js';
+import { materializeTemplateFromRelease } from './template/materialize.js';
+import { copyTemplateToDirectory, prepareTargetDirectory } from './template/project.js';
+import { fetchTemplateRelease } from './template/release.js';
+const require = createRequire(import.meta.url);
+const packageJson = require('../package.json');
+export const CLI_VERSION = packageJson.version ?? '0.0.0';
+const DEFAULT_PROJECT_NAME_PROMPT = 'Project name: ';
+const DEFAULT_CONFIRM_PROMPT = 'Continue? (y/N): ';
+export async function runCLI(argv, runtimeOverrides = {}) {
+    const runtime = createRuntime(runtimeOverrides);
+    try {
+        const options = parseArgs(argv);
+        if (options.help) {
+            runtime.print(HELP_TEXT);
+            return 0;
+        }
+        if (options.version) {
+            runtime.print(CLI_VERSION);
+            return 0;
+        }
+        const projectName = await resolveProjectName(options.projectName, runtime);
+        if (!projectName) {
+            runtime.printError('Missing required project name.');
+            runtime.printError('');
+            runtime.printError(HELP_TEXT);
+            return 1;
+        }
+        assertValidProjectName(projectName);
+        const packageManager = options.packageManager ?? detectPackageManager(runtime.env.npm_config_user_agent);
+        const targetDirectory = path.resolve(runtime.cwd, projectName);
+        if (!options.yes) {
+            if (!isInteractive(runtime)) {
+                runtime.printError('Interactive confirmation is unavailable in non-interactive mode.');
+                runtime.printError('Re-run with --yes to proceed.');
+                return 1;
+            }
+            runtime.print('');
+            runtime.print('Scaffold request');
+            runtime.print(`  project: ${projectName}`);
+            runtime.print(`  target directory: ${targetDirectory}`);
+            runtime.print(`  package manager: ${packageManager}`);
+            runtime.print(`  skip install: ${formatBool(options.skipInstall)}`);
+            runtime.print(`  skip git: ${formatBool(options.skipGit)}`);
+            runtime.print(`  template ref: ${options.templateRef ?? 'latest release tag'}`);
+            runtime.print('');
+            const shouldContinue = await runtime.confirm(DEFAULT_CONFIRM_PROMPT);
+            if (!shouldContinue) {
+                runtime.printError('Aborted.');
+                return 1;
+            }
+        }
+        const release = await runtime.resolveTemplateRelease(options.templateRef);
+        runtime.print(`Using Builder Kit release ${release.tag}`);
+        const materializedTemplate = await runtime.materializeTemplate(release);
+        try {
+            await runtime.prepareTargetDirectory(targetDirectory);
+            await runtime.copyTemplateToDirectory(materializedTemplate.templateRoot, targetDirectory);
+        }
+        finally {
+            await materializedTemplate.cleanup();
+        }
+        const setupResult = await runtime.runPostScaffoldSetup({
+            targetDirectory,
+            projectName,
+            packageManager,
+            skipInstall: options.skipInstall,
+            skipGit: options.skipGit,
+        });
+        runtime.print(`Scaffolded ${projectName} from builder-kit@${release.tag}.`);
+        runtime.print(`Dependencies: ${options.skipInstall ? 'skipped' : `installed via ${packageManager}`}`);
+        if (setupResult.gitStatus === 'initialized') {
+            runtime.print('Git setup: initialized with initial commit');
+        }
+        else if (setupResult.gitStatus === 'skipped') {
+            runtime.print('Git setup: skipped');
+        }
+        else {
+            runtime.print('Git setup: skipped due to git initialization failure');
+            runtime.printError(`Warning: ${setupResult.gitFailureMessage ?? 'Unable to initialize git repository.'}`);
+        }
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unexpected error';
+        runtime.printError(message);
+        if (error instanceof CliUsageError) {
+            runtime.printError('');
+            runtime.printError(HELP_TEXT);
+        }
+        return 1;
+    }
+}
+function createRuntime(overrides) {
+    const env = process.env;
+    return {
+        env,
+        cwd: process.cwd(),
+        stdinIsTTY: Boolean(process.stdin.isTTY),
+        stdoutIsTTY: Boolean(process.stdout.isTTY),
+        print: console.log,
+        printError: console.error,
+        prompt: defaultPrompt,
+        confirm: defaultConfirm,
+        resolveTemplateRelease: (templateRef) => fetchTemplateRelease({
+            templateRef,
+            githubToken: env.GITHUB_TOKEN,
+        }),
+        materializeTemplate: materializeTemplateFromRelease,
+        prepareTargetDirectory,
+        copyTemplateToDirectory,
+        runPostScaffoldSetup,
+        ...overrides,
+    };
+}
+async function resolveProjectName(projectName, runtime) {
+    if (projectName) {
+        return projectName.trim();
+    }
+    if (!isInteractive(runtime)) {
+        return undefined;
+    }
+    const answer = await runtime.prompt(DEFAULT_PROJECT_NAME_PROMPT);
+    const nextProjectName = answer.trim();
+    return nextProjectName || undefined;
+}
+function isInteractive(runtime) {
+    return runtime.stdinIsTTY && runtime.stdoutIsTTY;
+}
+async function defaultPrompt(message) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        return await rl.question(message);
+    }
+    finally {
+        rl.close();
+    }
+}
+async function defaultConfirm(message) {
+    const answer = await defaultPrompt(message);
+    return /^(y|yes)$/i.test(answer.trim());
+}
+function assertValidProjectName(projectName) {
+    if (projectName === '.' || projectName === '..') {
+        throw new CliUsageError('Invalid project name: "." and ".." are not allowed.');
+    }
+    if (!/^[a-zA-Z0-9._-]+$/.test(projectName)) {
+        throw new CliUsageError('Invalid project name: use only letters, numbers, ".", "-", or "_" and no path separators.');
+    }
+}
+function detectPackageManager(userAgent) {
+    if (typeof userAgent === 'string') {
+        if (userAgent.startsWith('pnpm/')) {
+            return 'pnpm';
+        }
+        if (userAgent.startsWith('yarn/')) {
+            return 'yarn';
+        }
+        if (userAgent.startsWith('bun/')) {
+            return 'bun';
+        }
+    }
+    return 'npm';
+}
+function formatBool(value) {
+    return value ? 'yes' : 'no';
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    const code = await runCLI(process.argv.slice(2));
+    process.exit(code);
+}

package/dist/scaffold/post-setup.d.ts

@@ -0,0 +1,16 @@
+import type { PackageManager } from '../cli/args.js';
+export interface PostScaffoldSetupOptions {
+    targetDirectory: string;
+    projectName: string;
+    packageManager: PackageManager;
+    skipInstall: boolean;
+    skipGit: boolean;
+}
+export interface PostScaffoldSetupResult {
+    gitStatus: 'initialized' | 'skipped' | 'failed';
+    gitFailureMessage?: string;
+}
+type CommandRunner = (command: string, args: string[], cwd: string) => Promise<void>;
+export declare function runPostScaffoldSetup(options: PostScaffoldSetupOptions, runCommand?: CommandRunner): Promise<PostScaffoldSetupResult>;
+export declare function getInstallCommand(packageManager: PackageManager): [string, string[]];
+export {};

package/dist/scaffold/post-setup.js

@@ -0,0 +1,101 @@
+import { copyFile, readFile, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+const INITIAL_COMMIT_MESSAGE = 'Initial commit from create-shape-app';
+export async function runPostScaffoldSetup(options, runCommand = executeCommand) {
+    await applyProjectDefaults(options.targetDirectory, options.projectName);
+    if (!options.skipInstall) {
+        const [command, args] = getInstallCommand(options.packageManager);
+        await runCommand(command, args, options.targetDirectory);
+    }
+    if (options.skipGit) {
+        return { gitStatus: 'skipped' };
+    }
+    try {
+        await runCommand('git', ['init'], options.targetDirectory);
+        await runCommand('git', ['add', '--all'], options.targetDirectory);
+        await runCommand('git', ['commit', '-m', INITIAL_COMMIT_MESSAGE], options.targetDirectory);
+        return { gitStatus: 'initialized' };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown git error';
+        return {
+            gitStatus: 'failed',
+            gitFailureMessage: message,
+        };
+    }
+}
+export function getInstallCommand(packageManager) {
+    if (packageManager === 'bun') {
+        return ['bun', ['install']];
+    }
+    if (packageManager === 'pnpm') {
+        return ['pnpm', ['install']];
+    }
+    if (packageManager === 'yarn') {
+        return ['yarn', ['install']];
+    }
+    return ['npm', ['install']];
+}
+async function applyProjectDefaults(targetDirectory, projectName) {
+    await applyPackageNameSubstitution(targetDirectory, projectName);
+    await applyEnvFileDefaults(targetDirectory);
+}
+async function applyPackageNameSubstitution(targetDirectory, projectName) {
+    const packageJsonPath = join(targetDirectory, 'package.json');
+    if (!(await pathExists(packageJsonPath))) {
+        return;
+    }
+    const raw = await readFile(packageJsonPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    parsed.name = toPackageName(projectName);
+    await writeFile(packageJsonPath, `${JSON.stringify(parsed, null, 2)}\n`, 'utf8');
+}
+async function applyEnvFileDefaults(targetDirectory) {
+    const sourcePath = join(targetDirectory, '.env.example');
+    const targetPath = join(targetDirectory, '.env');
+    if (!(await pathExists(sourcePath)) || (await pathExists(targetPath))) {
+        return;
+    }
+    await copyFile(sourcePath, targetPath);
+}
+function toPackageName(projectName) {
+    const normalized = projectName.trim().toLowerCase().replace(/[^a-z0-9._-]/g, '-');
+    const withoutLeading = normalized.replace(/^[._-]+/, '');
+    if (!withoutLeading) {
+        throw new Error('Unable to derive package name from project name.');
+    }
+    return withoutLeading;
+}
+async function pathExists(targetPath) {
+    try {
+        await stat(targetPath);
+        return true;
+    }
+    catch (error) {
+        const code = error instanceof Error && 'code' in error ? error.code : undefined;
+        if (code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+async function executeCommand(command, args, cwd) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd,
+            stdio: 'inherit',
+            env: process.env,
+        });
+        child.once('error', (error) => {
+            reject(new Error(`Failed to start command "${command}": ${error.message}`));
+        });
+        child.once('close', (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`Command "${[command, ...args].join(' ')}" failed with exit code ${String(code)}`));
+        });
+    });
+}

package/dist/template/materialize.d.ts

@@ -0,0 +1,6 @@
+import type { TemplateRelease } from './release.js';
+export interface MaterializedTemplate {
+    templateRoot: string;
+    cleanup: () => Promise<void>;
+}
+export declare function materializeTemplateFromRelease(release: TemplateRelease, fetchImpl?: typeof fetch): Promise<MaterializedTemplate>;

package/dist/template/materialize.js

@@ -0,0 +1,63 @@
+import { mkdtemp, mkdir, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { spawn } from 'node:child_process';
+export async function materializeTemplateFromRelease(release, fetchImpl = fetch) {
+    const tempRoot = await mkdtemp(join(tmpdir(), 'create-shape-app-'));
+    const tarballPath = join(tempRoot, 'template.tar.gz');
+    const extractedPath = join(tempRoot, 'extracted');
+    try {
+        await downloadTarball(release.tarballUrl, tarballPath, fetchImpl);
+        await mkdir(extractedPath, { recursive: true });
+        await extractTarball(tarballPath, extractedPath);
+        const templateRoot = await findArchiveRootDirectory(extractedPath);
+        return {
+            templateRoot,
+            cleanup: async () => {
+                await rm(tempRoot, { recursive: true, force: true });
+            },
+        };
+    }
+    catch (error) {
+        await rm(tempRoot, { recursive: true, force: true });
+        throw error;
+    }
+}
+async function downloadTarball(url, outputPath, fetchImpl) {
+    const response = await fetchImpl(url, {
+        headers: {
+            Accept: 'application/octet-stream',
+            'User-Agent': 'create-shape-app',
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to download template tarball: HTTP ${response.status}`);
+    }
+    const data = Buffer.from(await response.arrayBuffer());
+    await writeFile(outputPath, data);
+}
+async function extractTarball(tarballPath, outputDir) {
+    await new Promise((resolve, reject) => {
+        const child = spawn('tar', ['-xzf', tarballPath, '-C', outputDir], {
+            stdio: 'ignore',
+        });
+        child.once('error', (error) => {
+            reject(new Error(`Failed to run tar: ${error.message}`));
+        });
+        child.once('close', (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`tar extraction failed with exit code ${String(code)}`));
+        });
+    });
+}
+async function findArchiveRootDirectory(extractedPath) {
+    const entries = await readdir(extractedPath, { withFileTypes: true });
+    const rootDirectory = entries.find((entry) => entry.isDirectory());
+    if (!rootDirectory) {
+        throw new Error('Template archive did not contain a root directory.');
+    }
+    return join(extractedPath, basename(rootDirectory.name));
+}

package/dist/template/project.d.ts

@@ -0,0 +1,2 @@
+export declare function prepareTargetDirectory(targetDirectory: string): Promise<void>;
+export declare function copyTemplateToDirectory(templateRoot: string, targetDirectory: string): Promise<void>;

package/dist/template/project.js

@@ -0,0 +1,40 @@
+import { cp, mkdir, readdir, stat } from 'node:fs/promises';
+import { basename } from 'node:path';
+const EXCLUDED_TEMPLATE_ENTRIES = new Set(['.git', '.claude', 'AGENTS.md', 'CLAUDE.md', '.DS_Store']);
+export async function prepareTargetDirectory(targetDirectory) {
+    const directoryExists = await pathExists(targetDirectory);
+    if (!directoryExists) {
+        await mkdir(targetDirectory, { recursive: true });
+        return;
+    }
+    const metadata = await stat(targetDirectory);
+    if (!metadata.isDirectory()) {
+        throw new Error(`Target path exists and is not a directory: ${targetDirectory}`);
+    }
+    const entries = await readdir(targetDirectory);
+    if (entries.length > 0) {
+        throw new Error(`Target directory is not empty: ${targetDirectory}`);
+    }
+}
+export async function copyTemplateToDirectory(templateRoot, targetDirectory) {
+    await cp(templateRoot, targetDirectory, {
+        recursive: true,
+        force: false,
+        filter(sourcePath) {
+            return !EXCLUDED_TEMPLATE_ENTRIES.has(basename(sourcePath));
+        },
+    });
+}
+async function pathExists(targetPath) {
+    try {
+        await stat(targetPath);
+        return true;
+    }
+    catch (error) {
+        const code = error instanceof Error && 'code' in error ? error.code : undefined;
+        if (code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}

package/dist/template/release.d.ts

@@ -0,0 +1,14 @@
+export interface TemplateRelease {
+    tag: string;
+    tarballUrl: string;
+}
+export interface FetchTemplateReleaseOptions {
+    owner?: string;
+    repo?: string;
+    templateRef?: string;
+    githubToken?: string;
+    fetchImpl?: typeof fetch;
+    sleepImpl?: (milliseconds: number) => Promise<void>;
+}
+export declare function assertTagIsSupported(tag: string): void;
+export declare function fetchTemplateRelease(options?: FetchTemplateReleaseOptions): Promise<TemplateRelease>;

package/dist/template/release.js

@@ -0,0 +1,127 @@
+const DEFAULT_OWNER = 'shape-network';
+const DEFAULT_REPO = 'builder-kit';
+const RELEASE_TAG_PATTERN = /^v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+export function assertTagIsSupported(tag) {
+    if (!RELEASE_TAG_PATTERN.test(tag)) {
+        throw new Error(`Invalid release tag "${tag}". Only semantic-version tags like "v1.2.3" are supported.`);
+    }
+    if (tag.toLowerCase().includes('canary')) {
+        throw new Error(`Unsupported release tag "${tag}". Canary tags are not allowed.`);
+    }
+}
+export async function fetchTemplateRelease(options = {}) {
+    const owner = options.owner ?? DEFAULT_OWNER;
+    const repo = options.repo ?? DEFAULT_REPO;
+    const templateRef = options.templateRef;
+    const githubToken = options.githubToken;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const sleepImpl = options.sleepImpl ?? sleep;
+    const maxAttempts = 3;
+    if (templateRef) {
+        assertTagIsSupported(templateRef);
+    }
+    const endpoint = templateRef
+        ? `https://api.github.com/repos/${owner}/${repo}/releases/tags/${encodeURIComponent(templateRef)}`
+        : `https://api.github.com/repos/${owner}/${repo}/releases/latest`;
+    let response;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        response = await fetchImpl(endpoint, {
+            headers: buildHeaders(githubToken),
+        });
+        if (response.ok) {
+            break;
+        }
+        if (!isRetryableStatus(response.status) || attempt === maxAttempts) {
+            break;
+        }
+        await sleepImpl(getRetryDelayMilliseconds(response, attempt));
+    }
+    if (!response) {
+        throw new Error('Failed to resolve template release: no response received.');
+    }
+    if (!response.ok) {
+        throw new Error(await buildReleaseLookupError(response, templateRef));
+    }
+    const payload = (await response.json());
+    const tagName = payload.tag_name;
+    const tarballUrl = payload.tarball_url;
+    if (typeof tagName !== 'string' || typeof tarballUrl !== 'string') {
+        throw new Error('Invalid release payload from GitHub API.');
+    }
+    assertTagIsSupported(tagName);
+    return {
+        tag: tagName,
+        tarballUrl,
+    };
+}
+function buildHeaders(githubToken) {
+    const headers = {
+        Accept: 'application/vnd.github+json',
+        'User-Agent': 'create-shape-app',
+    };
+    if (githubToken) {
+        headers.Authorization = `Bearer ${githubToken}`;
+    }
+    return headers;
+}
+async function buildReleaseLookupError(response, templateRef) {
+    const refLabel = templateRef ? `release tag "${templateRef}"` : 'latest release';
+    const apiMessage = await readApiMessage(response);
+    const rateLimited = response.status === 429 ||
+        (response.status === 403 && response.headers.get('x-ratelimit-remaining') === '0');
+    if (rateLimited) {
+        const resetHint = getRateLimitResetHint(response.headers.get('x-ratelimit-reset'));
+        return [
+            `Failed to resolve ${refLabel}: GitHub API rate limit reached (HTTP ${response.status}).`,
+            resetHint,
+            'Retry later or set GITHUB_TOKEN.',
+        ]
+            .filter(Boolean)
+            .join(' ');
+    }
+    if (apiMessage) {
+        return `Failed to resolve ${refLabel}: ${apiMessage} (HTTP ${response.status}).`;
+    }
+    return `Failed to resolve ${refLabel}: HTTP ${response.status}.`;
+}
+async function readApiMessage(response) {
+    try {
+        const payload = (await response.clone().json());
+        if (typeof payload.message === 'string' && payload.message.trim()) {
+            return payload.message.trim();
+        }
+    }
+    catch {
+        // Ignore parse failures and fall back to status-only messaging.
+    }
+    return undefined;
+}
+function getRateLimitResetHint(resetEpochSeconds) {
+    if (!resetEpochSeconds) {
+        return undefined;
+    }
+    const reset = Number(resetEpochSeconds);
+    if (!Number.isFinite(reset)) {
+        return undefined;
+    }
+    const resetDate = new Date(reset * 1000);
+    return `GitHub API reset time: ${resetDate.toISOString()}.`;
+}
+function isRetryableStatus(status) {
+    return status === 429 || status >= 500;
+}
+function getRetryDelayMilliseconds(response, attempt) {
+    const retryAfterHeader = response.headers.get('retry-after');
+    if (retryAfterHeader) {
+        const asSeconds = Number(retryAfterHeader);
+        if (!Number.isNaN(asSeconds) && asSeconds >= 0) {
+            return Math.floor(asSeconds * 1000);
+        }
+    }
+    return Math.min(250 * attempt, 1500);
+}
+async function sleep(milliseconds) {
+    await new Promise((resolve) => {
+        setTimeout(resolve, milliseconds);
+    });
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "create-shape-app",
+  "version": "0.1.2",
+  "description": "Scaffold Shape Builder Kit projects from pinned release tags.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shape-network/create-shape-app.git"
+  },
+  "bugs": {
+    "url": "https://github.com/shape-network/create-shape-app/issues"
+  },
+  "homepage": "https://github.com/shape-network/create-shape-app#readme",
+  "keywords": [
+    "cli",
+    "create",
+    "scaffold",
+    "shape",
+    "builder-kit"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": "./bin/create-shape-app.js",
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.18.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "type-check": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint . --max-warnings=0",
+    "lint:fix": "eslint . --fix",
+    "test": "bun run build && node --test ./test/*.test.mjs",
+    "dev": "bun run build && node ./bin/create-shape-app.js --help",
+    "prepack": "bun run lint && bun run type-check && bun run test"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^25.2.2",
+    "@typescript-eslint/parser": "^8.46.3",
+    "eslint": "^9.39.1",
+    "globals": "^16.4.0",
+    "typescript": "^5.9.3"
+  }
+}