create-stacksfinder 0.5.0 → 0.6.1

package/README.md

@@ -1,330 +1,330 @@
-# create-stacksfinder
-
-[![npm version](https://img.shields.io/npm/v/create-stacksfinder.svg)](https://www.npmjs.com/package/create-stacksfinder)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
-
-```
-  ╔═══════════════════════════════════════════════════════╗
-  ║                                                       ║
-  ║   ███████╗████████╗ █████╗  ██████╗██╗  ██╗███████╗   ║
-  ║   ██╔════╝╚══██╔══╝██╔══██╗██╔════╝██║ ██╔╝██╔════╝   ║
-  ║   ███████╗   ██║   ███████║██║     █████╔╝ ███████╗   ║
-  ║   ╚════██║   ██║   ██╔══██║██║     ██╔═██╗ ╚════██║   ║
-  ║   ███████║   ██║   ██║  ██║╚██████╗██║  ██╗███████║   ║
-  ║   ╚══════╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝╚══════╝   ║
-  ║                         finder                        ║
-  ║                                                       ║
-  ╚═══════════════════════════════════════════════════════╝
-```
-
-**Scaffold optimized tech stacks with deterministic scoring.**
-
-CLI tool that recommends and generates production-ready projects based on your requirements. No AI hallucinations — just data-driven recommendations from versioned lookup tables.
-
-## Quick Start
-
-```bash
-# With Bun (recommended)
-bun create stacksfinder my-app
-
-# With npm
-npx create-stacksfinder@latest my-app
-
-# With pnpm
-pnpm create stacksfinder my-app
-```
-
-## Features
-
-- **Deterministic Scoring** — Same input = same output, always. 80+ technologies scored across 6 dimensions.
-- **Interactive Prompts** — Choose project type, scale, ecosystem, priorities, and constraints.
-- **Project Generation** — Scaffolds Next.js, SvelteKit, Nuxt, or Remix with your recommended stack.
-- **Offline Mode** — Embedded scoring data, works without internet.
-- **Minimal ASCII Style** — Clean terminal output, no emojis.
-
-## Usage
-
-### Interactive Mode (default)
-
-```bash
-bun create stacksfinder
-```
-
-You'll be prompted for:
-1. **Project Name** — e.g., `my-saas-app`
-2. **Project Type** — `saas`, `web-app`, `marketplace`, `api`, `e-commerce`, `blog`, `portfolio`
-3. **Scale** — `mvp`, `startup`, `growth`, `enterprise`
-4. **Priority** — Your top priority: `speed`, `dx`, `perf`, `cost`, `scale`, `security`
-5. **Constraints** — Optional: configure technical requirements (opt-in)
-
-### Quick Mode
-
-Skip all prompts with CLI flags:
-
-```bash
-# Basic quick mode (defaults: saas, mvp, speed)
-bun create stacksfinder my-app --quick
-
-# With custom options
-bun create stacksfinder my-app --quick --type saas --scale startup --priority dx
-```
-
-**Quick Mode Flags:**
-- `-q, --quick` — Skip prompts, use defaults
-- `--type <type>` — `saas`, `web-app`, `marketplace`, `api`, `e-commerce`, `blog`, `portfolio`
-- `--scale <scale>` — `mvp`, `startup`, `growth`, `enterprise`
-- `--priority <priority>` — `speed`, `dx`, `perf`, `cost`, `scale`, `security`
-
-### Compare Mode
-
-Compare two preset configurations side-by-side:
-
-```bash
-# Default: mvp vs enterprise
-bun create stacksfinder --compare
-
-# Custom presets
-bun create stacksfinder --compare --preset1 startup --preset2 agency
-```
-
-**Available Presets:** `mvp`, `startup`, `enterprise`, `agency`, `ecommerce`, `api`
-
-### Blueprint Mode (Pro)
-
-Generate a project from a saved blueprint:
-
-```bash
-bun create stacksfinder my-app --from-blueprint abc123 --api-key sk_...
-```
-
-Or use the environment variable:
-```bash
-export STACKSFINDER_API_KEY=sk_...
-bun create stacksfinder my-app --from-blueprint abc123
-```
-
-> Requires a Pro/Team subscription. Get your API key at [stacksfinder.dev/settings/api-keys](https://stacksfinder.dev/settings/api-keys)
-
-### Recommend Only
-
-Get recommendations without generating a project:
-
-```bash
-bun create stacksfinder --recommend-only
-# or
-bun create stacksfinder -r
-```
-
-### JSON Output
-
-Output recommendations as JSON for automation:
-
-```bash
-bun create stacksfinder --json
-# or
-bun create stacksfinder -j
-```
-
-### Expert Mode
-
-Configure all 27 constraints:
-
-```bash
-bun create stacksfinder my-app --expert
-```
-
-## Example Output
-
-```
-  ╔═══════════════════════════════════════════════════════╗
-  ║   ███████╗████████╗ █████╗  ██████╗██╗  ██╗███████╗   ║
-  ║   ...                                                 ║
-  ╚═══════════════════════════════════════════════════════╝
-
-  Scaffold optimized tech stacks
-  Powered by deterministic scoring
-
-  STEP 1: Project Configuration
-
-  Project Name:  my-saas-demo
-  Project Type:  saas
-  Scale:         mvp
-  Ecosystem:     javascript
-  Priorities:    speed, dx, cost
-  Constraints:   real-time
-
-  STEP 2: Analyzing 50+ Technologies...
-
-  > Scoring completed in 2ms
-
-  STEP 3: Recommended Stack
-
-  ==================================================
-  Framework    SvelteKit       [A]  Excellent fit
-               Alt: Next.js (A-), Nuxt (B+)
-  Database     Supabase        [A]  Excellent fit
-               Alt: Neon (A-), PlanetScale (B+)
-  ORM          Drizzle         [A+] Perfect fit
-               Alt: Prisma (A), Kysely (B+)
-  Auth         Better Auth     [A]  Excellent fit
-  Hosting      Vercel          [A]  Excellent fit
-  Payments     Paddle          [A]  Excellent fit
-  ==================================================
-
-  Stack Score: A (86/100)
-  Production-ready stack with excellent balance
-
-  Confidence: HIGH
-    - Clear winner in most categories
-    - Strong compatibility between choices
-    - Well-tested combination
-
-  ------------------------------------------------
-  Fine-tune with 25+ constraints:
-  stacksfinder.dev/builder
-```
-
-## Scoring Dimensions
-
-All technologies are scored across 6 dimensions (0-100):
-
-| Dimension | Description |
-|-----------|-------------|
-| **Performance** | Runtime speed, bundle size, optimization |
-| **DX** | Learning curve, tooling, documentation |
-| **Ecosystem** | Community size, integrations, job market |
-| **Maintainability** | Long-term code health, upgrade path |
-| **Cost** | Hosting costs, licensing, operational overhead |
-| **Compliance** | Security features, audit readiness |
-
-## Generated Project Structure
-
-```
-my-app/
-├── package.json          # Dependencies for your stack
-├── tsconfig.json         # TypeScript configuration
-├── .env.example          # Environment variables template
-├── .gitignore
-├── README.md             # Getting started guide
-├── src/                  # Framework-specific structure
-│   └── ...
-├── drizzle.config.ts     # If using Drizzle ORM
-└── prisma/               # If using Prisma ORM
-    └── schema.prisma
-```
-
-## Supported Technologies
-
-### Meta-Frameworks
-Next.js, SvelteKit, Nuxt, Remix, Astro, SolidStart
-
-### Databases
-PostgreSQL, Supabase, Neon, PlanetScale, Turso, MongoDB, SQLite
-
-### ORMs
-Drizzle, Prisma, Kysely, TypeORM, Sequelize
-
-### Auth
-Better Auth, Lucia, Auth.js, Clerk, Supabase Auth
-
-### Hosting
-Vercel, Netlify, Railway, Fly.io, Cloudflare, AWS
-
-### Payments
-Stripe, Paddle, LemonSqueezy
-
-## Options
-
-### Quick Mode
-| Flag | Alias | Description |
-|------|-------|-------------|
-| `--quick` | `-q` | Skip prompts, use defaults |
-| `--type <type>` | | Project type (saas, web-app, etc.) |
-| `--scale <scale>` | | Scale (mvp, startup, growth, enterprise) |
-| `--priority <priority>` | | Top priority (speed, dx, perf, cost, scale, security) |
-
-### Advanced
-| Flag | Description |
-|------|-------------|
-| `--from-blueprint <id>` | Generate from saved blueprint (requires API key) |
-| `--api-key <key>` | API key (or use STACKSFINDER_API_KEY env) |
-| `--compare` | Compare two preset stacks side-by-side |
-| `--preset1 <name>` | First preset (mvp, startup, enterprise, agency, ecommerce, api) |
-| `--preset2 <name>` | Second preset (default: enterprise) |
-
-### Other
-| Flag | Alias | Description |
-|------|-------|-------------|
-| `--expert` | `-e` | Configure all 27 constraints |
-| `--recommend-only` | `-r` | Only show recommendations, skip generation |
-| `--json` | `-j` | Output as JSON |
-| `--version` | `-v` | Show version and data versions |
-| `--help` | `-h` | Show help |
-
-## Programmatic Usage
-
-```typescript
-import { scoreStack } from 'create-stacksfinder/scoring';
-
-const context = {
-  projectName: 'my-app',
-  projectType: 'saas',
-  scale: 'mvp',
-  ecosystem: 'typescript',
-  priorities: ['speed', 'dx', 'cost'],
-  constraints: ['real-time'],
-};
-
-const stack = scoreStack(context);
-console.log(stack.categories); // Recommended technologies
-console.log(stack.stackScore); // Overall grade
-```
-
-## Pro Features
-
-Want more control? Visit [stacksfinder.dev](https://stacksfinder.dev) for:
-
-- **25+ Constraints** — Fine-tune recommendations with advanced filters
-- **AI Narratives** — Get detailed explanations for each choice
-- **Blueprints** — Save and share your stack configurations
-- **Audits** — Analyze existing projects for technical debt
-- **MCP Server** — Use in Claude, Cursor, Windsurf, VS Code
-
-## Telemetry
-
-This CLI collects **anonymous** usage data to help us improve the product. We track:
-
-- CLI version
-- Action type (recommend/generate)
-- Project type, scale, ecosystem (no project names)
-- Priority and constraint counts
-- OS platform
-
-We **never** collect: IP addresses, machine IDs, project names, file paths, or any personally identifiable information.
-
-### Opt-out
-
-Set any of these environment variables to disable telemetry:
-
-```bash
-# Option 1: StacksFinder-specific
-export STACKSFINDER_TELEMETRY_DISABLED=1
-
-# Option 2: Standard Do Not Track
-export DO_NOT_TRACK=1
-
-# Option 3: CI environments (auto-disabled)
-export CI=true
-```
-
-The telemetry code is [open source](https://github.com/hoklims/stacksfinder/blob/main/packages/create-stacksfinder/src/telemetry.ts) — inspect it yourself.
-
-## Related
-
-- **Website**: [stacksfinder.dev](https://stacksfinder.dev)
-- **MCP Server**: [@stacksfinder/mcp-server](https://www.npmjs.com/package/@stacksfinder/mcp-server)
-- **GitHub**: [github.com/hoklims/stacksfinder](https://github.com/hoklims/stacksfinder)
-
-## License
-
-MIT
+# create-stacksfinder
+
+[![npm version](https://img.shields.io/npm/v/create-stacksfinder.svg)](https://www.npmjs.com/package/create-stacksfinder)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+```
+  ╔═══════════════════════════════════════════════════════╗
+  ║                                                       ║
+  ║   ███████╗████████╗ █████╗  ██████╗██╗  ██╗███████╗   ║
+  ║   ██╔════╝╚══██╔══╝██╔══██╗██╔════╝██║ ██╔╝██╔════╝   ║
+  ║   ███████╗   ██║   ███████║██║     █████╔╝ ███████╗   ║
+  ║   ╚════██║   ██║   ██╔══██║██║     ██╔═██╗ ╚════██║   ║
+  ║   ███████║   ██║   ██║  ██║╚██████╗██║  ██╗███████║   ║
+  ║   ╚══════╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝╚══════╝   ║
+  ║                         finder                        ║
+  ║                                                       ║
+  ╚═══════════════════════════════════════════════════════╝
+```
+
+**Scaffold optimized tech stacks with deterministic scoring.**
+
+CLI tool that recommends and generates production-ready projects based on your requirements. No AI hallucinations — just data-driven recommendations from versioned lookup tables.
+
+## Quick Start
+
+```bash
+# With Bun (recommended)
+bun create stacksfinder my-app
+
+# With npm
+npx create-stacksfinder@latest my-app
+
+# With pnpm
+pnpm create stacksfinder my-app
+```
+
+## Features
+
+- **Deterministic Scoring** — Same input = same output, always. 80+ technologies scored across 6 dimensions.
+- **Interactive Prompts** — Choose project type, scale, ecosystem, priorities, and constraints.
+- **Project Generation** — Scaffolds Next.js, SvelteKit, Nuxt, or Remix with your recommended stack.
+- **Offline Mode** — Embedded scoring data, works without internet.
+- **Minimal ASCII Style** — Clean terminal output, no emojis.
+
+## Usage
+
+### Interactive Mode (default)
+
+```bash
+bun create stacksfinder
+```
+
+You'll be prompted for:
+1. **Project Name** — e.g., `my-saas-app`
+2. **Project Type** — `saas`, `web-app`, `marketplace`, `api`, `e-commerce`, `blog`, `portfolio`
+3. **Scale** — `mvp`, `startup`, `growth`, `enterprise`
+4. **Priority** — Your top priority: `speed`, `dx`, `perf`, `cost`, `scale`, `security`
+5. **Constraints** — Optional: configure technical requirements (opt-in)
+
+### Quick Mode
+
+Skip all prompts with CLI flags:
+
+```bash
+# Basic quick mode (defaults: saas, mvp, speed)
+bun create stacksfinder my-app --quick
+
+# With custom options
+bun create stacksfinder my-app --quick --type saas --scale startup --priority dx
+```
+
+**Quick Mode Flags:**
+- `-q, --quick` — Skip prompts, use defaults
+- `--type <type>` — `saas`, `web-app`, `marketplace`, `api`, `e-commerce`, `blog`, `portfolio`
+- `--scale <scale>` — `mvp`, `startup`, `growth`, `enterprise`
+- `--priority <priority>` — `speed`, `dx`, `perf`, `cost`, `scale`, `security`
+
+### Compare Mode
+
+Compare two preset configurations side-by-side:
+
+```bash
+# Default: mvp vs enterprise
+bun create stacksfinder --compare
+
+# Custom presets
+bun create stacksfinder --compare --preset1 startup --preset2 agency
+```
+
+**Available Presets:** `mvp`, `startup`, `enterprise`, `agency`, `ecommerce`, `api`
+
+### Blueprint Mode (Pro)
+
+Generate a project from a saved blueprint:
+
+```bash
+bun create stacksfinder my-app --from-blueprint abc123 --api-key sk_...
+```
+
+Or use the environment variable:
+```bash
+export STACKSFINDER_API_KEY=sk_...
+bun create stacksfinder my-app --from-blueprint abc123
+```
+
+> Requires a Pro/Team subscription. Get your API key at [stacksfinder.com/settings/api-keys](https://stacksfinder.com/settings/api-keys)
+
+### Recommend Only
+
+Get recommendations without generating a project:
+
+```bash
+bun create stacksfinder --recommend-only
+# or
+bun create stacksfinder -r
+```
+
+### JSON Output
+
+Output recommendations as JSON for automation:
+
+```bash
+bun create stacksfinder --json
+# or
+bun create stacksfinder -j
+```
+
+### Expert Mode
+
+Configure all 27 constraints:
+
+```bash
+bun create stacksfinder my-app --expert
+```
+
+## Example Output
+
+```
+  ╔═══════════════════════════════════════════════════════╗
+  ║   ███████╗████████╗ █████╗  ██████╗██╗  ██╗███████╗   ║
+  ║   ...                                                 ║
+  ╚═══════════════════════════════════════════════════════╝
+
+  Scaffold optimized tech stacks
+  Powered by deterministic scoring
+
+  STEP 1: Project Configuration
+
+  Project Name:  my-saas-demo
+  Project Type:  saas
+  Scale:         mvp
+  Ecosystem:     javascript
+  Priorities:    speed, dx, cost
+  Constraints:   real-time
+
+  STEP 2: Analyzing 50+ Technologies...
+
+  > Scoring completed in 2ms
+
+  STEP 3: Recommended Stack
+
+  ==================================================
+  Framework    SvelteKit       [A]  Excellent fit
+               Alt: Next.js (A-), Nuxt (B+)
+  Database     Supabase        [A]  Excellent fit
+               Alt: Neon (A-), PlanetScale (B+)
+  ORM          Drizzle         [A+] Perfect fit
+               Alt: Prisma (A), Kysely (B+)
+  Auth         Better Auth     [A]  Excellent fit
+  Hosting      Vercel          [A]  Excellent fit
+  Payments     Paddle          [A]  Excellent fit
+  ==================================================
+
+  Stack Score: A (86/100)
+  Production-ready stack with excellent balance
+
+  Confidence: HIGH
+    - Clear winner in most categories
+    - Strong compatibility between choices
+    - Well-tested combination
+
+  ------------------------------------------------
+  Fine-tune with 25+ constraints:
+  stacksfinder.com/builder
+```
+
+## Scoring Dimensions
+
+All technologies are scored across 6 dimensions (0-100):
+
+| Dimension | Description |
+|-----------|-------------|
+| **Performance** | Runtime speed, bundle size, optimization |
+| **DX** | Learning curve, tooling, documentation |
+| **Ecosystem** | Community size, integrations, job market |
+| **Maintainability** | Long-term code health, upgrade path |
+| **Cost** | Hosting costs, licensing, operational overhead |
+| **Compliance** | Security features, audit readiness |
+
+## Generated Project Structure
+
+```
+my-app/
+├── package.json          # Dependencies for your stack
+├── tsconfig.json         # TypeScript configuration
+├── .env.example          # Environment variables template
+├── .gitignore
+├── README.md             # Getting started guide
+├── src/                  # Framework-specific structure
+│   └── ...
+├── drizzle.config.ts     # If using Drizzle ORM
+└── prisma/               # If using Prisma ORM
+    └── schema.prisma
+```
+
+## Supported Technologies
+
+### Meta-Frameworks
+Next.js, SvelteKit, Nuxt, Remix, Astro, SolidStart
+
+### Databases
+PostgreSQL, Supabase, Neon, PlanetScale, Turso, MongoDB, SQLite
+
+### ORMs
+Drizzle, Prisma, Kysely, TypeORM, Sequelize
+
+### Auth
+Better Auth, Lucia, Auth.js, Clerk, Supabase Auth
+
+### Hosting
+Vercel, Netlify, Railway, Fly.io, Cloudflare, AWS
+
+### Payments
+Stripe, Paddle, LemonSqueezy
+
+## Options
+
+### Quick Mode
+| Flag | Alias | Description |
+|------|-------|-------------|
+| `--quick` | `-q` | Skip prompts, use defaults |
+| `--type <type>` | | Project type (saas, web-app, etc.) |
+| `--scale <scale>` | | Scale (mvp, startup, growth, enterprise) |
+| `--priority <priority>` | | Top priority (speed, dx, perf, cost, scale, security) |
+
+### Advanced
+| Flag | Description |
+|------|-------------|
+| `--from-blueprint <id>` | Generate from saved blueprint (requires API key) |
+| `--api-key <key>` | API key (or use STACKSFINDER_API_KEY env) |
+| `--compare` | Compare two preset stacks side-by-side |
+| `--preset1 <name>` | First preset (mvp, startup, enterprise, agency, ecommerce, api) |
+| `--preset2 <name>` | Second preset (default: enterprise) |
+
+### Other
+| Flag | Alias | Description |
+|------|-------|-------------|
+| `--expert` | `-e` | Configure all 27 constraints |
+| `--recommend-only` | `-r` | Only show recommendations, skip generation |
+| `--json` | `-j` | Output as JSON |
+| `--version` | `-v` | Show version and data versions |
+| `--help` | `-h` | Show help |
+
+## Programmatic Usage
+
+```typescript
+import { scoreStack } from 'create-stacksfinder/scoring';
+
+const context = {
+  projectName: 'my-app',
+  projectType: 'saas',
+  scale: 'mvp',
+  ecosystem: 'typescript',
+  priorities: ['speed', 'dx', 'cost'],
+  constraints: ['real-time'],
+};
+
+const stack = scoreStack(context);
+console.log(stack.categories); // Recommended technologies
+console.log(stack.stackScore); // Overall grade
+```
+
+## Pro Features
+
+Want more control? Visit [stacksfinder.com](https://stacksfinder.com) for:
+
+- **25+ Constraints** — Fine-tune recommendations with advanced filters
+- **AI Narratives** — Get detailed explanations for each choice
+- **Blueprints** — Save and share your stack configurations
+- **Audits** — Analyze existing projects for technical debt
+- **MCP Server** — Use in Claude, Cursor, Windsurf, VS Code
+
+## Telemetry
+
+This CLI collects **anonymous** usage data to help us improve the product. We track:
+
+- CLI version
+- Action type (recommend/generate)
+- Project type, scale, ecosystem (no project names)
+- Priority and constraint counts
+- OS platform
+
+We **never** collect: IP addresses, machine IDs, project names, file paths, or any personally identifiable information.
+
+### Opt-out
+
+Set any of these environment variables to disable telemetry:
+
+```bash
+# Option 1: StacksFinder-specific
+export STACKSFINDER_TELEMETRY_DISABLED=1
+
+# Option 2: Standard Do Not Track
+export DO_NOT_TRACK=1
+
+# Option 3: CI environments (auto-disabled)
+export CI=true
+```
+
+The telemetry code is [open source](https://github.com/hoklims/stacksfinder/blob/main/packages/create-stacksfinder/src/telemetry.ts) — inspect it yourself.
+
+## Related
+
+- **Website**: [stacksfinder.com](https://stacksfinder.com)
+- **MCP Server**: [@stacksfinder/mcp-server](https://www.npmjs.com/package/@stacksfinder/mcp-server)
+- **GitHub**: [github.com/hoklims/stacksfinder](https://github.com/hoklims/stacksfinder)
+
+## License
+
+MIT