create-pyro 0.1.0 → 0.2.0

package/README.md

@@ -1,35 +1,54 @@
 # Create Pyro
 
-Scaffold a new Pyro monorepo project.
-
-> **Note:** The full monorepo template is still under development. See "What you get" below for current state.
+Scaffold a new Pyro monorepo: a Hono api and a React Router web app with shared, typed packages, Postgres via Drizzle and auth via Better Auth.
 
 ## Usage
 
 ```bash
-npx create-pyro@latest
-# or
 pnpm create pyro
+# or
+npx create-pyro@latest
 
 # With a project name
 pnpm create pyro my-app
 
-# Scaffold into the current directory
+# Scaffold into the current directory (must be empty, or hold only .git)
 pnpm create pyro .
 ```
 
+The CLI asks for anything you don't pass as a flag:
+
+| Flag                         | Default      | What it does                                    |
+| ---------------------------- | ------------ | ----------------------------------------------- |
+| `--scope <name>`             | project name | Scope for workspace packages (`@name/api`, ...) |
+| `--git` / `--no-git`         | yes          | `git init` with an initial commit               |
+| `--install` / `--no-install` | yes          | Run `pnpm install`                              |
+| `-y`, `--yes`                |              | Accept defaults for anything not set by a flag  |
+
+It also writes a `.env` with freshly generated secrets, so the project runs without any manual setup.
+
 ## What you get
 
-Currently scaffolds a minimal starter project (`package.json`, `.gitignore`). Planned for the full template:
+```
+apps/
+  api/        Hono + Better Auth (email and password), Node server
+  web/        React Router 8 with SSR, Tailwind CSS 4, typed api client
+packages/
+  config/     Zod-validated environment, split into lazily-checked scopes
+  db/         Drizzle schema, client and migrations for Postgres
+  shared/     Types and Zod schemas shared by both apps
+infra/nginx/  Reverse proxy for the production stack
+```
+
+Plus pnpm workspaces with a dependency catalog, Turborepo, Biome, tsdown, Vitest, dotenv-run, Docker Compose files for development and production, and a GitHub Actions workflow.
 
-- Turborepo
-- Biome (lint + format)
-- pnpm workspaces
+The web app has a homepage with sign-in and sign-up, and a dashboard that shows the signed-in user and redirects to the homepage otherwise.
 
 ## Requirements
 
 - Node.js 24+
-- pnpm 11+
+- pnpm 12+
+- Docker, for Postgres in development and for the production stack
 
 ## Development
 
@@ -41,6 +60,8 @@ pnpm build
 pnpm test
 ```
 
+The template lives in `template/`. It uses `@repo/` as its package scope and `my-pyro-app` as its name; the CLI replaces both in every file. CI scaffolds a project from it and runs that project's lint, typecheck, tests and build, then brings up the production compose stack.
+
 ## Issues
 
 Found a bug or have a feature request? [Open an issue](https://github.com/poran-dip/create-pyro/issues).

package/dist/index.js

@@ -1,39 +1,159 @@
 #!/usr/bin/env node
-import fs from "node:fs";
+import { spawnSync } from "node:child_process";
 import path from "node:path";
+import { parseArgs } from "node:util";
 import prompts from "prompts";
-const __dirname = import.meta.dirname;
-const arg = process.argv[2];
-const { targetDir } = arg
-    ? { targetDir: arg }
-    : await prompts({
+import { isEmptyDir, normalizeScope, scaffold, TEMPLATE_NAME, toSlug, validateScope, } from "./scaffold.js";
+const HELP = `
+Usage: create-pyro [directory] [options]
+
+Options:
+  --scope <name>    Package scope for workspace packages (default: project name)
+  --git, --no-git   Initialize a git repository (default: ask, then yes)
+  --install, --no-install
+                    Install dependencies with pnpm (default: ask, then yes)
+  -y, --yes         Accept the default for every question not set by a flag
+  -h, --help        Show this help
+`;
+const { values: flags, positionals } = parseArgs({
+    allowPositionals: true,
+    allowNegative: true,
+    options: {
+        scope: { type: "string" },
+        git: { type: "boolean" },
+        install: { type: "boolean" },
+        yes: { type: "boolean", short: "y" },
+        help: { type: "boolean", short: "h" },
+    },
+});
+if (flags.help) {
+    console.log(HELP);
+    process.exit(0);
+}
+const onCancel = () => process.exit(0);
+const useDefaults = flags.yes ?? false;
+const fail = (message) => {
+    console.error(`\n❌ ${message}\n`);
+    process.exit(1);
+};
+// Project directory.
+let targetDir = positionals[0];
+if (!targetDir && useDefaults)
+    targetDir = TEMPLATE_NAME;
+if (!targetDir) {
+    ({ targetDir } = await prompts({
         type: "text",
         name: "targetDir",
         message: "Project name:",
-        initial: "my-pyro-app",
-        validate: (value) => value.trim() ? true : "Project name cannot be empty",
-    }, {
-        onCancel: () => {
-            process.exit(0);
-        },
-    });
+        initial: TEMPLATE_NAME,
+        validate: (value) => toSlug(value === "." ? path.basename(process.cwd()) : value)
+            ? true
+            : "Project name cannot be empty",
+    }, { onCancel }));
+}
 if (!targetDir)
     process.exit(0);
-const dest = targetDir === "." ? process.cwd() : path.resolve(process.cwd(), targetDir);
-const projectName = path.basename(dest);
-if (fs.existsSync(dest) &&
-    fs.readdirSync(dest).length > 0 &&
-    targetDir !== ".") {
-    console.error(`\n❌ Directory "${projectName}" already exists.\n`);
-    process.exit(1);
+const dest = path.resolve(process.cwd(), targetDir);
+const dirName = path.basename(dest);
+const name = toSlug(dirName);
+if (!name)
+    fail(`Can't derive a package name from "${dirName}".`);
+if (!isEmptyDir(dest))
+    fail(`Directory "${dirName}" already exists and is not empty.`);
+// Remaining options: flags win, then --yes defaults, then prompts.
+const flagScope = flags.scope !== undefined ? normalizeScope(flags.scope) : undefined;
+if (flagScope !== undefined) {
+    const valid = validateScope(flagScope);
+    if (valid !== true)
+        fail(`Invalid --scope "${flags.scope}": ${valid}`);
+}
+const answers = await prompts([
+    {
+        type: flagScope !== undefined || useDefaults ? null : "text",
+        name: "scope",
+        message: "Package scope (workspace packages are named @scope/...):",
+        initial: name,
+        format: (value) => normalizeScope(value),
+        validate: (value) => validateScope(normalizeScope(value)),
+    },
+    {
+        type: flags.git !== undefined || useDefaults ? null : "confirm",
+        name: "git",
+        message: "Initialize a git repository?",
+        initial: true,
+    },
+    {
+        type: flags.install !== undefined || useDefaults ? null : "confirm",
+        name: "install",
+        message: "Install dependencies with pnpm?",
+        initial: true,
+    },
+], { onCancel });
+const scope = flagScope ?? answers.scope ?? name;
+const initGit = flags.git ?? answers.git ?? true;
+const install = flags.install ?? answers.install ?? true;
+// Scaffold.
+scaffold({
+    templateDir: path.join(import.meta.dirname, "../template"),
+    dest,
+    name,
+    scope,
+});
+console.log(`\n📦 Scaffolded ${name} with packages scoped @${scope}/*`);
+// On Windows, pnpm is a .cmd shim that only runs through a shell, but a shell
+// joins args unquoted, splitting any with spaces. So only use one for pnpm,
+// and never pass it args with spaces.
+const run = (command, args, quiet = false) => spawnSync(command, args, {
+    cwd: dest,
+    stdio: quiet ? "ignore" : "inherit",
+    shell: process.platform === "win32" && command === "pnpm",
+}).status === 0;
+let installed = false;
+if (install) {
+    if (!run("pnpm", ["--version"], true)) {
+        console.warn("\n⚠️  pnpm isn't on your PATH, so dependencies weren't installed.\n" +
+            "   Enable it with `corepack enable`, then run `pnpm install`.");
+    }
+    else {
+        console.log("\n📥 Installing dependencies...\n");
+        installed = run("pnpm", ["install", "--no-frozen-lockfile"]);
+        if (!installed)
+            console.warn("\n⚠️  `pnpm install` failed. Fix the error above and rerun it.");
+    }
+}
+if (initGit) {
+    if (!run("git", ["--version"], true)) {
+        console.warn("\n⚠️  git isn't on your PATH, so no repository was created.");
+    }
+    else if (run("git", ["rev-parse", "--is-inside-work-tree"], true)) {
+        console.log("\nℹ️  Already inside a git repository, skipped git init.");
+    }
+    else {
+        run("git", ["init", "--quiet", "--initial-branch=main"], true) ||
+            run("git", ["init", "--quiet"], true);
+        run("git", ["add", "-A"], true);
+        const committed = run("git", [
+            "commit",
+            "--quiet",
+            "--no-verify",
+            "-m",
+            "Initial commit from create-pyro",
+        ], true);
+        console.log(committed
+            ? "\n🌱 Initialized a git repository with an initial commit."
+            : "\n🌱 Initialized a git repository (files staged; commit when ready).");
+    }
 }
-fs.cpSync(path.join(__dirname, "../template"), dest, { recursive: true });
-fs.renameSync(`${dest}/gitignore`, `${dest}/.gitignore`);
-const pkgPath = path.join(dest, "package.json");
-const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-pkg.name = projectName;
-fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
-console.log(`\n✅ Created ${projectName}! Now run:\n`);
-console.log(`  cd ${projectName}`);
-console.log(`  pnpm install`);
-console.log(`  pnpm dev\n`);
+// Next steps.
+const steps = [
+    path.relative(process.cwd(), dest) &&
+        `cd ${path.relative(process.cwd(), dest)}`,
+    !installed && "pnpm install",
+    "docker compose -f compose.dev.yml up -d",
+    "pnpm db:migrate",
+    "pnpm dev",
+].filter(Boolean);
+console.log(`\n✅ Created ${name}! Now run:\n`);
+for (const step of steps)
+    console.log(`  ${step}`);
+console.log("\nA .env with fresh secrets is already in place.\n");

package/dist/scaffold.js

@@ -0,0 +1,106 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+/** The placeholders the template uses, rewritten in every scaffolded file. */
+export const TEMPLATE_SCOPE = "repo";
+export const TEMPLATE_NAME = "my-pyro-app";
+/** npm strips these from published packages, so the template stores them renamed. */
+const RENAMED_FILES = {
+    gitignore: ".gitignore",
+};
+const VALID_SCOPE = /^[a-z0-9][a-z0-9._-]*$/;
+/**
+ * Turns a directory name into something valid as an npm package name, a
+ * docker compose project name and a Postgres-friendly identifier.
+ */
+export function toSlug(input) {
+    return input
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^[-_]+|[-_]+$/g, "");
+}
+/** Normalizes a scope as typed (`@acme`, `Acme`) to its bare form (`acme`). */
+export function normalizeScope(input) {
+    return input.trim().replace(/^@/, "").replace(/\/$/, "").toLowerCase();
+}
+export function validateScope(scope) {
+    if (!scope)
+        return "Scope cannot be empty";
+    if (scope.length > 214)
+        return "Scope is too long";
+    if (!VALID_SCOPE.test(scope))
+        return "Use lowercase letters, digits, '-', '.' or '_', starting with a letter or digit";
+    return true;
+}
+/** True when `dir` is missing or has nothing in it but a `.git` folder. */
+export function isEmptyDir(dir) {
+    if (!fs.existsSync(dir))
+        return true;
+    return fs.readdirSync(dir).every((entry) => entry === ".git");
+}
+export function scaffold({ templateDir, dest, name, scope }) {
+    fs.mkdirSync(dest, { recursive: true });
+    fs.cpSync(templateDir, dest, { recursive: true });
+    for (const [from, to] of Object.entries(RENAMED_FILES)) {
+        const source = path.join(dest, from);
+        if (fs.existsSync(source))
+            fs.renameSync(source, path.join(dest, to));
+    }
+    for (const file of walk(dest)) {
+        const buffer = fs.readFileSync(file);
+        if (buffer.includes(0))
+            continue; // binary, leave it alone
+        const original = buffer.toString("utf8");
+        const rewritten = original
+            // A Windows checkout with core.autocrlf has CRLF, which the scaffold's
+            // Biome config (LF) would reject on its first lint.
+            .replaceAll("\r\n", "\n")
+            .replaceAll(`@${TEMPLATE_SCOPE}/`, `@${scope}/`)
+            .replaceAll(TEMPLATE_NAME, name);
+        if (rewritten !== original)
+            fs.writeFileSync(file, rewritten);
+    }
+    writeEnv(dest);
+}
+/**
+ * Creates `.env` from `.env.example` with fresh secrets, so the project runs
+ * without any manual setup.
+ */
+export function writeEnv(dest) {
+    const example = path.join(dest, ".env.example");
+    const target = path.join(dest, ".env");
+    if (!fs.existsSync(example) || fs.existsSync(target))
+        return;
+    const dbPassword = randomBytes(16).toString("hex");
+    const authSecret = randomBytes(32).toString("base64url");
+    const lines = fs
+        .readFileSync(example, "utf8")
+        .split("\n")
+        .map((line) => {
+        if (line.startsWith("POSTGRES_PASSWORD="))
+            return `POSTGRES_PASSWORD=${dbPassword}`;
+        if (line.startsWith("BETTER_AUTH_SECRET="))
+            return `BETTER_AUTH_SECRET=${authSecret}`;
+        if (line.startsWith("DATABASE_URL=")) {
+            const url = new URL(line.slice("DATABASE_URL=".length));
+            url.password = dbPassword;
+            return `DATABASE_URL=${url.toString()}`;
+        }
+        return line;
+    });
+    fs.writeFileSync(target, lines.join("\n"));
+}
+function* walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === "node_modules" || entry.name === ".git")
+                continue;
+            yield* walk(full);
+        }
+        else if (entry.isFile()) {
+            yield full;
+        }
+    }
+}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "create-pyro",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Bootstrap new projects with Pyro.",
   "type": "module",
-  "packageManager": "pnpm@11.9.0",
+  "packageManager": "pnpm@12.15.0+sha512.b3951d6d6ff4a9f13dc7cf56cd28d2b8eb37dbcc9c68e52e1e1191873ea9f82a017287ab50baadc5ccc494f036c67c0e47eb13608c2fa36f47711b61ea128e61",
   "bin": {
     "create-pyro": "./dist/index.js"
   },
@@ -41,14 +41,14 @@
     "prompts": "^2.4.2"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.1",
-    "@types/node": "^26.0.1",
+    "@biomejs/biome": "^2.6.3",
+    "@types/node": "^26.6.5",
     "@types/prompts": "^2.4.9",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.9"
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
   },
   "engines": {
     "node": ">=24",
-    "pnpm": ">=11"
+    "pnpm": ">=12"
   }
 }

package/template/.dockerignore

@@ -0,0 +1,30 @@
+# deps
+node_modules
+**/node_modules
+
+# build outputs
+**/dist
+**/.react-router
+
+# env and logs
+**/.env
+**/.env.*
+!**/.env.example
+**/*.log
+
+# turbo
+.turbo
+**/.turbo
+
+# vcs
+.git
+.gitignore
+
+# editor
+.vscode
+
+# misc
+.DS_Store
+Thumbs.db
+*.tsbuildinfo
+**/*.md

package/template/.env.example

@@ -0,0 +1,23 @@
+# Postgres (docker compose)
+POSTGRES_USER=app
+POSTGRES_PASSWORD=password
+POSTGRES_DB=app
+
+# Database (compose.dev.yml publishes Postgres on 15432)
+DATABASE_URL=postgresql://app:password@localhost:15432/app
+
+# Auth
+BETTER_AUTH_URL=http://localhost:3002
+BETTER_AUTH_SECRET=
+
+# API
+NODE_ENV=development
+API_PORT=3002
+CORS_ORIGIN=http://localhost:3000
+
+# Web
+PUBLIC_API_URL=http://localhost:3002
+INTERNAL_API_URL=http://localhost:3002
+
+# Prod only (compose.yml): the origin nginx is served on
+PUBLIC_ORIGIN=http://localhost

package/template/.gitattributes

@@ -0,0 +1,2 @@
+# Keep LF everywhere, including Windows checkouts (Biome formats with LF).
+* text=auto eol=lf

package/template/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    env:
+      DATABASE_URL: postgresql://app:password@localhost:15432/app
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Start Postgres
+        run: docker compose -f compose.dev.yml up -d --wait
+
+      - uses: pnpm/action-setup@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Lint
+        run: pnpm lint:ci
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Test
+        run: pnpm test
+
+      - name: Postgres logs on failure
+        if: failure()
+        run: docker compose -f compose.dev.yml logs --tail 100

package/template/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["biomejs.biome"]
+}

package/template/.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+  "editor.defaultFormatter": "biomejs.biome",
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.biome": "explicit",
+    "source.organizeImports.biome": "explicit"
+  }
+}

package/template/README.md

@@ -1,14 +1,67 @@
-# Create Pyro App
+# my-pyro-app
 
-**pnpm**:
+A TypeScript monorepo: a Hono api and a React Router web app sharing typed packages, with Postgres via Drizzle and auth via Better Auth.
+
+## Quick start
+
+Requires Node.js 24+, pnpm 12+ and Docker.
 
 ```bash
 pnpm install
+docker compose -f compose.dev.yml up -d   # Postgres on localhost:15432
+pnpm db:migrate
 pnpm dev
 ```
 
-**Docker**:
+Then open http://localhost:3000. The api runs on http://localhost:3002.
+
+`.env` is gitignored, so a fresh clone needs one: copy `.env.example` to `.env` and set `BETTER_AUTH_SECRET` (`openssl rand -base64 32`).
+
+## Layout
+
+```
+apps/
+  api/        Hono server: Better Auth at /api/auth/*, your routes under /api
+  web/        React Router (SSR) + Tailwind; calls the api with a typed client
+packages/
+  config/     Zod-validated env, split into lazily-checked scopes
+  db/         Drizzle schema, client and migrations
+  shared/     Types and Zod schemas used by both apps
+infra/nginx/  Reverse proxy for the production compose stack
+```
+
+Packages build to `dist/` with tsdown. During `pnpm dev`, each package rebuilds on change and the apps pick it up.
+
+## Scripts
+
+| Script             | What it does                                   |
+| ------------------ | ---------------------------------------------- |
+| `pnpm dev`         | Run everything in watch mode                   |
+| `pnpm build`       | Build all packages and apps                    |
+| `pnpm typecheck`   | Typecheck every workspace                      |
+| `pnpm test`        | Run every suite (the api suite needs Postgres) |
+| `pnpm lint`        | Lint and format with Biome, applying fixes     |
+| `pnpm db:generate` | Generate a migration from schema changes       |
+| `pnpm db:migrate`  | Apply pending migrations                       |
+| `pnpm db:push`     | Push the schema directly (prototyping only)    |
+| `pnpm db:studio`   | Open Drizzle Studio                            |
+
+## Environment
+
+Every variable lives in the root `.env`; `.env.example` documents them. `packages/config` validates them per scope (`dbEnv`, `authEnv`, `apiEnv`, `webEnv`), so a process only needs the variables it reads, and a missing one fails with a message naming it.
+
+The api tests run against a separate database: `DATABASE_URL` with `_test` appended to its name, created and migrated automatically. Set `TEST_DATABASE_URL` to use another one.
+
+## Auth
+
+Email and password sign-in is on by default. To add Google or another provider, add its credentials to `authSchema` in `packages/config`, then enable it under `socialProviders` in `apps/api/src/lib/auth.ts`.
+
+## Production
 
 ```bash
-docker compose up --build
+docker compose up --build -d
 ```
+
+This builds the images and starts Postgres, runs migrations once, then starts the api and web behind nginx on port 80. Set `PUBLIC_ORIGIN` to the URL you serve it on.
+
+The Dockerfiles list each workspace's `package.json` explicitly, so when you add or remove an app or package, update the `COPY` lines in each Dockerfile.

package/template/apps/api/Dockerfile

@@ -0,0 +1,46 @@
+FROM node:24-alpine AS builder
+WORKDIR /app
+
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml tsconfig.json ./
+COPY apps/api/package.json ./apps/api/
+COPY apps/web/package.json ./apps/web/
+COPY packages/config/package.json ./packages/config/
+COPY packages/db/package.json ./packages/db/
+COPY packages/shared/package.json ./packages/shared/
+
+RUN corepack enable && pnpm install --frozen-lockfile --filter @repo/api...
+
+COPY apps/api ./apps/api
+COPY packages/config ./packages/config
+COPY packages/db ./packages/db
+COPY packages/shared ./packages/shared
+
+RUN pnpm --filter @repo/api... build
+
+FROM node:24-alpine
+WORKDIR /app
+
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml ./
+COPY apps/api/package.json ./apps/api/
+COPY apps/web/package.json ./apps/web/
+COPY packages/config/package.json ./packages/config/
+COPY packages/db/package.json ./packages/db/
+COPY packages/shared/package.json ./packages/shared/
+
+RUN corepack enable && pnpm install --frozen-lockfile --filter @repo/api... --prod
+
+COPY --from=builder /app/packages/config/dist ./packages/config/dist
+COPY --from=builder /app/packages/db/dist ./packages/db/dist
+COPY --from=builder /app/packages/shared/dist ./packages/shared/dist
+COPY --from=builder /app/apps/api/dist ./apps/api/dist
+
+ENV NODE_ENV=production
+ENV API_PORT=3002
+EXPOSE 3002
+
+USER node
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD node -e "fetch('http://127.0.0.1:3002/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+
+CMD ["node", "apps/api/dist/index.mjs"]