create-blitzpack 0.1.14 → 0.1.16

package/README.md

@@ -24,7 +24,16 @@ pnpm create blitzpack [project-name] [options]
 - **Web**: Next.js 16 + React 19 + Tailwind CSS v4 + shadcn/ui
 - **API**: Fastify 5 + Prisma 7 + PostgreSQL + Better Auth
 - **Monorepo**: Turborepo + pnpm workspaces
-- **Production-ready**: Auth, admin dashboard, logging, validation, testing, Docker
+- **Production-ready app stack**: Auth, admin dashboard, logging, validation, testing
+- **Optional deployment assets**: Dockerfiles + production compose + CD workflow
+
+## Setup Profiles
+
+The scaffold wizard supports three profiles:
+
+- **Recommended**: All app features plus Docker deployment assets and CD workflow.
+- **Platform-First**: All app features, without deployment assets.
+- **Custom**: Pick app features and deployment options independently.
 
 ## Requirements
 

package/dist/index.js

@@ -155,7 +155,7 @@ var REPLACEABLE_FILES = [
   "README.md"
 ];
 var DEFAULT_DESCRIPTION = "A full-stack TypeScript monorepo built with Blitzpack";
-var OPTIONAL_FEATURES = [
+var APP_FEATURES = [
   {
     key: "testing",
     name: "Testing",
@@ -170,11 +170,18 @@ var OPTIONAL_FEATURES = [
     key: "uploads",
     name: "File Uploads",
     description: "S3 storage, upload routes, file components"
+  }
+];
+var DEPLOYMENT_FEATURES = [
+  {
+    key: "dockerDeploy",
+    name: "Docker Deployment",
+    description: "Dockerfiles for API/Web and production Docker Compose"
   },
   {
-    key: "deployment",
-    name: "Deployment",
-    description: "Dockerfile, CI/CD workflows, production configs"
+    key: "ciCd",
+    name: "CD Workflow",
+    description: "GitHub Actions workflow to build and publish Docker images"
   }
 ];
 var FEATURE_EXCLUSIONS = {
@@ -218,7 +225,13 @@ var FEATURE_EXCLUSIONS = {
     "packages/ui/src/file-upload-input.tsx",
     "packages/types/src/upload.ts"
   ],
-  deployment: ["Dockerfile", "Dockerfile.web", "docker-compose.prod.yml", ".github"]
+  dockerDeploy: [
+    "apps/api/.dockerignore",
+    "apps/api/Dockerfile",
+    "apps/web/Dockerfile",
+    "deploy/docker"
+  ],
+  ciCd: [".github/workflows/cd.yml"]
 };
 
 // src/utils.ts
@@ -397,16 +410,21 @@ async function promptFeatureSelection() {
     {
       type: "select",
       name: "setupType",
-      message: "Setup type:",
+      message: "Project profile:",
       choices: [
         {
           title: "Recommended",
-          description: "all features included",
+          description: "all app features + Docker deploy assets + CD workflow",
           value: "recommended"
         },
         {
-          title: "Customize",
-          description: "choose features",
+          title: "Platform-First",
+          description: "all app features, no deployment assets",
+          value: "platform"
+        },
+        {
+          title: "Custom",
+          description: "choose app and deployment features",
           value: "customize"
         }
       ],
@@ -427,21 +445,55 @@ async function promptFeatureSelection() {
       testing: true,
       admin: true,
       uploads: true,
-      deployment: true
+      dockerDeploy: true,
+      ciCd: true
+    };
+  }
+  if (setupType === "platform") {
+    return {
+      testing: true,
+      admin: true,
+      uploads: true,
+      dockerDeploy: false,
+      ciCd: false
     };
   }
-  const featureChoices = OPTIONAL_FEATURES.map((feature) => ({
+  const appFeatureChoices = APP_FEATURES.map((feature) => ({
+    title: feature.name,
+    description: feature.description,
+    value: feature.key,
+    selected: true
+  }));
+  const { selectedAppFeatures } = await prompts(
+    {
+      type: "multiselect",
+      name: "selectedAppFeatures",
+      message: "Select app features:",
+      choices: appFeatureChoices,
+      hint: "- Space to toggle, Enter to confirm",
+      instructions: false
+    },
+    {
+      onCancel: () => {
+        cancelled = true;
+      }
+    }
+  );
+  if (cancelled) {
+    return null;
+  }
+  const deploymentFeatureChoices = DEPLOYMENT_FEATURES.map((feature) => ({
     title: feature.name,
     description: feature.description,
     value: feature.key,
     selected: false
   }));
-  const { selectedFeatures } = await prompts(
+  const { selectedDeploymentFeatures } = await prompts(
     {
       type: "multiselect",
-      name: "selectedFeatures",
-      message: "Select features to include:",
-      choices: featureChoices,
+      name: "selectedDeploymentFeatures",
+      message: "Select deployment options (optional):",
+      choices: deploymentFeatureChoices,
       hint: "- Space to toggle, Enter to confirm",
       instructions: false
     },
@@ -454,12 +506,24 @@ async function promptFeatureSelection() {
   if (cancelled) {
     return null;
   }
-  const selected = selectedFeatures || [];
+  const selectedApp = selectedAppFeatures || [];
+  const selectedDeployment = selectedDeploymentFeatures || [];
+  const includesCiCd = selectedDeployment.includes("ciCd");
+  const includesDockerDeploy = selectedDeployment.includes("dockerDeploy") || includesCiCd;
+  if (includesCiCd && !selectedDeployment.includes("dockerDeploy")) {
+    console.log();
+    console.log(
+      chalk3.dim(
+        "  \u2139 CD workflow requires Docker deployment assets, enabling both."
+      )
+    );
+  }
   return {
-    testing: selected.includes("testing"),
-    admin: selected.includes("admin"),
-    uploads: selected.includes("uploads"),
-    deployment: selected.includes("deployment")
+    testing: selectedApp.includes("testing"),
+    admin: selectedApp.includes("admin"),
+    uploads: selectedApp.includes("uploads"),
+    dockerDeploy: includesDockerDeploy,
+    ciCd: includesCiCd
   };
 }
 async function promptAutomaticSetup() {
@@ -480,7 +544,7 @@ async function promptAutomaticSetup() {
   const { runSetup } = await prompts({
     type: "confirm",
     name: "runSetup",
-    message: "Run initial setup now? (docker compose + database migrations)",
+    message: "Run local setup now? (start PostgreSQL with Docker + run migrations)",
     initial: true
   });
   return runSetup || false;
@@ -546,6 +610,193 @@ async function countFiles(dir) {
 // src/transform.ts
 import fs2 from "fs-extra";
 import path3 from "path";
+
+// src/agent-doc-template.ts
+var AGENT_DOC_TEMPLATE = `# CLAUDE.md
+
+You are a Senior Full-stack Developer and an Expert in TypeScript, Next.js 16, React 19, Fastify, Prisma v7, PostgreSQL, TailwindCSS v5, and shadcn/ui. You are collaborating with a human developer on a production-ready full-stack application.
+
+---
+
+## Critical Requirements & Constraints
+
+### Forbidden Behaviors
+
+- NEVER create markdown files unless the user explicitly asks for it. This is very important
+- NEVER create \`index.ts\` barrel files. This is a strict requirement
+- AVOID writing comments in code unless absolutely necessary for non-obvious edge cases
+
+### Workflow Requirements
+
+- Make sure you aggressively prefer planning and waiting for user confirmation before writing code for medium to big tasks. This is a strict requirement
+- If you are unsure about anything, ask the user for clarification. This is a strict requirement
+- Prefer using commands or exec scripts (like \`pnpm dlx\`) for setup related tasks instead of making all the files manually. In case the command requires interactive input, ask the user to do it themselves and provide them with suitable guidance
+
+### Collaboration Principles
+
+- Always be unbiased towards the code, the user's preference and opinions. If you do not agree with the user, make it clear with them. Treat them like a peer
+- Always mention alternative approaches to the user if you think it's necessary
+- Do not be afraid of hurting the user's feelings or making them feel bad about their skills. Having well-written and maintainable code is significantly more important than cozying up to the user
+- Always give a brief and compact summary of all the changes done
+
+---
+
+## Common Commands
+
+### Development Commands
+
+\`\`\`bash
+pnpm dev
+pnpm build
+pnpm typecheck
+pnpm lint
+\`\`\`
+
+<!-- @feature testing -->
+\`\`\`bash
+pnpm test
+pnpm test:unit
+pnpm test:integration
+\`\`\`
+<!-- @endfeature -->
+
+### Individual Package Commands
+
+\`\`\`bash
+# Web (Next.js on port 3000)
+cd apps/web
+pnpm dev
+pnpm typecheck
+
+# API (Fastify on port 8080)
+cd apps/api
+pnpm dev
+pnpm start
+\`\`\`
+
+### Database Commands (run from \`apps/api\`)
+
+\`\`\`bash
+pnpm db:generate      # Generate Prisma Client
+pnpm db:migrate       # Create and apply migrations
+pnpm db:push          # Push schema changes (no migration files)
+pnpm db:studio        # Open Prisma Studio UI
+pnpm db:seed          # Seed database
+\`\`\`
+
+---
+
+## Coding Standards
+
+### Code Style
+
+- Type Definitions: Prefer \`interface\` for public-facing types and object shapes, \`type\` for unions, intersections, and computed types
+- Use descriptive variable names with auxiliary verbs (\`isLoading\`, \`hasError\`, \`canSubmit\`)
+- Favor default exports for pages and named exports for utilities or functions
+- **IMPORTANT**: Always use import aliases for files in apps. For packages, use relative imports.
+
+### Error Handling
+
+- Use our custom error classes from \`packages/utils/src/errors.ts\`
+- Provide user-friendly error messages and avoid leaking implementation details
+
+---
+
+## Project Architecture
+
+### Packages
+
+- All packages (\`@repo/packages-types\`, \`@repo/packages-utils\`) are consumed directly as TypeScript source files
+- No build or watch required for these packages
+
+### Environment
+
+- Environment variables are managed per-app with Zod validation
+- Web: Only \`NEXT_PUBLIC_*\` variables are exposed to the browser
+- Prisma CLI commands are wrapped with \`dotenv-cli\` to read from \`.env.local\`
+
+### Database
+
+- The API uses Prisma 7 as the ORM with PostgreSQL
+- Prisma queries are automatically logged based on \`LOG_LEVEL\`
+
+### Type Safety & Validation
+
+- The codebase emphasizes runtime and compile-time type safety with **Zod v4 as the single validation library** across the entire stack
+- No class-validator
+
+<!-- @feature testing -->
+### Testing
+
+Unit Tests: \`*.spec.ts\`
+Integration Tests: \`*.integration.spec.ts\`
+<!-- @endfeature -->
+
+### Authentication
+
+- Uses Better Auth
+- When creating users with password auth, set \`accountId\` to the user's email (not user.id)
+
+---
+
+## Web Architecture Patterns
+
+### State Management
+
+- TanStack Query (React Query): For API calls and data synchronization
+- Jotai: For client-side global state (UI state, user preferences)
+
+### API Integration
+
+- API config centralized in \`apps/web/src/lib/api.ts\`
+- **API Response Unwrapping**: The \`api.ts\` fetcher unwraps \`{ data: T }\` to \`T\` but preserves \`{ data: T[], pagination: {...} }\` responses intact
+
+### Authentication & Protected Routes
+
+The web app uses Better Auth for authentication with modern patterns:
+
+- **Auth Client**: Configured in \`apps/web/src/lib/auth.ts\`
+  - Provides \`useSession()\` hook for accessing current user/session
+  - Handles sign in/out, session persistence via cookies
+- **Protected Routes**: \`<ProtectedRoute>\` wrapper component for page-level protection
+
+### UI Component Patterns
+
+- Use Shadcn UI components as base, extend them before creating custom ones
+- Implement thoughtful micro-interactions and hover states wherever needed
+- Use Framer Motion for animations, Lucide React for icons
+- Prefer using \`Skeleton\` components for loading states instead of spinners (especially for data fetching components)
+- Always create a proper loading state for data fetching components.
+- Always use \`cn\` helper for dynamic classnames
+- Never write svg code. Always use existing icons from code or Lucide.
+
+---
+
+## API Architecture Patterns
+
+### Fastify Structure
+
+- The Fastify API follows a plugin-based architecture
+- Validation: Zod schemas directly in route definitions via \`fastify-type-provider-zod\`
+- Dependency Injection: Manual DI via Fastify decorators
+
+### Logging
+
+- The API uses Pino for structured logging with request tracing
+- Verbosity controlled by \`LOG_LEVEL\` env var: \`minimal\` | \`normal\` | \`detailed\` | \`verbose\`
+- **IMPORTANT**: Never use \`console.log\` in the API. Use the logger service instead
+
+**Log Methods:**
+
+- \`logger.info(message, context?)\` - Standard information
+- \`logger.error(message, error?, context?)\` - Errors with automatic Error serialization
+- \`logger.warn(message, context?)\` - Warnings
+- \`logger.debug(message, context?)\` - Debug information (detailed+ level)
+- \`logger.trace(message, context?)\` - Trace logs (verbose level only)
+- \`logger.perf(message, metrics)\` - Performance metrics
+`;
+
+// src/transform.ts
 var TESTING_SCRIPTS = [
   "test",
   "test:unit",
@@ -564,6 +815,15 @@ var TESTING_ROOT_DEVDEPS = [
 ];
 var TESTING_APP_DEVDEPS = ["vitest", "vite-tsconfig-paths"];
 var UPLOADS_API_DEPS = ["@aws-sdk/client-s3", "sharp"];
+var TESTING_DIR_NAMES = /* @__PURE__ */ new Set(["__tests__", "test", "tests"]);
+var TESTING_FILE_PATTERNS = [
+  /\.test\.[^/]+$/i,
+  /\.spec\.[^/]+$/i,
+  /^vitest(?:\.[^.]+)*\.(?:[cm]?[jt]sx?)$/i,
+  /^test-config\.(?:[cm]?[jt]sx?)$/i
+];
+var TS_CONFIG_FILE_PATTERN = /^tsconfig(?:\.[^.]+)?\.json$/;
+var AGENT_DOC_TARGETS = ["CLAUDE.md", "AGENTS.md"];
 var MARKER_FILES = [
   "apps/api/src/app.ts",
   "apps/api/src/plugins/services.ts",
@@ -573,22 +833,23 @@ function stripFeatureBlocks(content, disabledFeatures) {
   const lines = content.split("\n");
   const result = [];
   let skipUntilEnd = false;
-  let currentFeature = null;
   for (const line of lines) {
-    const featureStart = line.match(/\/\/\s*@feature\s+(\w+)/);
-    const featureEnd = line.match(/\/\/\s*@endfeature/);
+    const featureStart = line.match(
+      /^\s*(?:\/\/|<!--)\s*@feature\s+(\w+)\s*(?:-->)?\s*$/
+    );
+    const featureEnd = line.match(
+      /^\s*(?:\/\/|<!--)\s*@endfeature\s*(?:-->)?\s*$/
+    );
     if (featureStart) {
       const feature = featureStart[1];
       if (disabledFeatures.includes(feature)) {
         skipUntilEnd = true;
-        currentFeature = feature;
       }
       continue;
     }
     if (featureEnd) {
       if (skipUntilEnd) {
         skipUntilEnd = false;
-        currentFeature = null;
       }
       continue;
     }
@@ -736,6 +997,8 @@ async function applyFeatureTransforms(targetDir, features) {
   if (!features.testing) disabledFeatures.push("testing");
   if (!features.admin) disabledFeatures.push("admin");
   if (!features.uploads) disabledFeatures.push("uploads");
+  if (!features.dockerDeploy) disabledFeatures.push("dockerDeploy");
+  if (!features.ciCd) disabledFeatures.push("ciCd");
   for (const relativePath of MARKER_FILES) {
     const filePath = path3.join(targetDir, relativePath);
     if (await fs2.pathExists(filePath)) {
@@ -748,8 +1011,12 @@ async function applyFeatureTransforms(targetDir, features) {
   if (!features.testing) {
     await transformForNoTesting(targetDir);
   }
+  await transformAgentDocs(targetDir, disabledFeatures);
 }
 async function transformForNoTesting(targetDir) {
+  await removeTestingArtifacts(targetDir);
+  await stripTestingFromWorkspacePackageJson(targetDir);
+  await stripTestingFromTsConfigs(targetDir);
   const turboPath = path3.join(targetDir, "turbo.json");
   if (await fs2.pathExists(turboPath)) {
     const content = await fs2.readFile(turboPath, "utf-8");
@@ -759,6 +1026,7 @@ async function transformForNoTesting(targetDir) {
     delete turbo.tasks?.["test:integration"];
     delete turbo.tasks?.["test:watch"];
     delete turbo.tasks?.["test:coverage"];
+    delete turbo.tasks?.["test:parallel"];
     await fs2.writeFile(turboPath, JSON.stringify(turbo, null, 2) + "\n");
   }
   const huskyPath = path3.join(targetDir, ".husky/pre-push");
@@ -766,6 +1034,149 @@ async function transformForNoTesting(targetDir) {
     await fs2.writeFile(huskyPath, "pnpm typecheck\n");
   }
 }
+function isTestingDependency(name) {
+  return name === "vitest" || name.startsWith("@vitest/") || name.startsWith("@testing-library/") || name === "jsdom" || name === "vite-tsconfig-paths";
+}
+function isTestingIncludeEntry(value) {
+  return value.includes("__tests__") || value.includes("/test") || value.includes("test/") || value.includes("tests/") || value.includes(".test.") || value.includes(".spec.");
+}
+async function removeTestingArtifacts(currentDir) {
+  const entries = await fs2.readdir(currentDir);
+  for (const entry of entries) {
+    if (entry === ".git" || entry === "node_modules") {
+      continue;
+    }
+    const fullPath = path3.join(currentDir, entry);
+    const stat = await fs2.stat(fullPath);
+    if (stat.isDirectory()) {
+      if (TESTING_DIR_NAMES.has(entry)) {
+        await fs2.remove(fullPath);
+        continue;
+      }
+      await removeTestingArtifacts(fullPath);
+      continue;
+    }
+    if (TESTING_FILE_PATTERNS.some((pattern) => pattern.test(entry))) {
+      await fs2.remove(fullPath);
+    }
+  }
+}
+async function stripTestingFromWorkspacePackageJson(currentDir) {
+  const entries = await fs2.readdir(currentDir);
+  for (const entry of entries) {
+    if (entry === ".git" || entry === "node_modules") {
+      continue;
+    }
+    const fullPath = path3.join(currentDir, entry);
+    const stat = await fs2.stat(fullPath);
+    if (stat.isDirectory()) {
+      await stripTestingFromWorkspacePackageJson(fullPath);
+      continue;
+    }
+    if (entry !== "package.json") {
+      continue;
+    }
+    const content = await fs2.readFile(fullPath, "utf-8");
+    const pkg = JSON.parse(content);
+    let changed = false;
+    if (pkg.scripts && typeof pkg.scripts === "object") {
+      for (const scriptName of Object.keys(pkg.scripts)) {
+        if (scriptName === "test" || scriptName.startsWith("test:")) {
+          delete pkg.scripts[scriptName];
+          changed = true;
+        }
+      }
+    }
+    const dependencySections = [
+      "dependencies",
+      "devDependencies",
+      "peerDependencies",
+      "optionalDependencies"
+    ];
+    for (const section of dependencySections) {
+      if (!pkg[section] || typeof pkg[section] !== "object") {
+        continue;
+      }
+      for (const depName of Object.keys(pkg[section])) {
+        if (isTestingDependency(depName)) {
+          delete pkg[section][depName];
+          changed = true;
+        }
+      }
+    }
+    if ("vitest" in pkg) {
+      delete pkg.vitest;
+      changed = true;
+    }
+    if (changed) {
+      await fs2.writeFile(fullPath, JSON.stringify(pkg, null, 2) + "\n");
+    }
+  }
+}
+async function stripTestingFromTsConfigs(currentDir) {
+  const entries = await fs2.readdir(currentDir);
+  for (const entry of entries) {
+    if (entry === ".git" || entry === "node_modules") {
+      continue;
+    }
+    const fullPath = path3.join(currentDir, entry);
+    const stat = await fs2.stat(fullPath);
+    if (stat.isDirectory()) {
+      await stripTestingFromTsConfigs(fullPath);
+      continue;
+    }
+    if (!TS_CONFIG_FILE_PATTERN.test(entry)) {
+      continue;
+    }
+    const content = await fs2.readFile(fullPath, "utf-8");
+    const tsconfig = JSON.parse(content);
+    let changed = false;
+    const compilerOptions = tsconfig.compilerOptions;
+    if (compilerOptions && typeof compilerOptions === "object") {
+      if (Array.isArray(compilerOptions.types)) {
+        const nextTypes = compilerOptions.types.filter(
+          (value) => typeof value === "string" && !value.includes("vitest") && !value.includes("@testing-library")
+        );
+        if (nextTypes.length !== compilerOptions.types.length) {
+          compilerOptions.types = nextTypes;
+          changed = true;
+        }
+      }
+      if (compilerOptions.paths && typeof compilerOptions.paths === "object") {
+        if ("@test/*" in compilerOptions.paths) {
+          delete compilerOptions.paths["@test/*"];
+          changed = true;
+        }
+        if ("@tests/*" in compilerOptions.paths) {
+          delete compilerOptions.paths["@tests/*"];
+          changed = true;
+        }
+      }
+    }
+    if (Array.isArray(tsconfig.include)) {
+      const nextInclude = tsconfig.include.filter(
+        (value) => typeof value === "string" && !isTestingIncludeEntry(value)
+      );
+      if (nextInclude.length !== tsconfig.include.length) {
+        tsconfig.include = nextInclude;
+        changed = true;
+      }
+    }
+    if (changed) {
+      await fs2.writeFile(fullPath, JSON.stringify(tsconfig, null, 2) + "\n");
+    }
+  }
+}
+async function transformAgentDocs(targetDir, disabledFeatures) {
+  let content = stripFeatureBlocks(AGENT_DOC_TEMPLATE, disabledFeatures);
+  content = cleanEmptyLines(content).trimEnd() + "\n";
+  for (const fileName of AGENT_DOC_TARGETS) {
+    const filePath = path3.join(targetDir, fileName);
+    const heading = fileName === "AGENTS.md" ? "# AGENTS.md" : "# CLAUDE.md";
+    const fileContent = content.replace(/^#\s+CLAUDE\.md/m, heading);
+    await fs2.writeFile(filePath, fileContent, "utf-8");
+  }
+}
 
 // src/commands/create.ts
 var ENV_FILES = [
@@ -816,6 +1227,12 @@ function printDryRun(options) {
   console.log(
     `    ${featureStatus(options.features.uploads)} File Uploads ${chalk4.dim("(S3 storage, upload routes)")}`
   );
+  console.log(
+    `    ${featureStatus(options.features.dockerDeploy)} Docker Deployment ${chalk4.dim("(API/Web Dockerfiles, production compose)")}`
+  );
+  console.log(
+    `    ${featureStatus(options.features.ciCd)} CD Workflow ${chalk4.dim("(GitHub Actions image build/push)")}`
+  );
   console.log();
   console.log(chalk4.bold("  Would run:"));
   console.log();

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "create-blitzpack",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Create a new Blitzpack project - full-stack TypeScript monorepo with Next.js and Fastify",
   "type": "module",
   "bin": {
-    "create-blitzpack": "./dist/index.js"
+    "create-blitzpack": "dist/index.js"
   },
   "files": [
     "dist"
@@ -47,7 +47,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/CarboxyDev/blitzpack"
+    "url": "git+https://github.com/CarboxyDev/blitzpack.git"
   },
   "homepage": "https://github.com/CarboxyDev/blitzpack",
   "engines": {