create-stacksfinder 0.1.0

package/README.md

@@ -0,0 +1,235 @@
+# 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`, `ecommerce`, `api`, `content`, `internal`
+3. **Scale** — `mvp`, `growth`, `enterprise`
+4. **Ecosystem** — `javascript`, `typescript`, `rust`
+5. **Priorities** — Pick up to 3: `speed`, `dx`, `cost`, `scale`, `security`, `compliance`
+6. **Constraints** — `real-time`, `offline-first`, `edge`, `ai-features`, etc.
+
+### 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
+```
+
+### With Project Name
+
+Skip the name prompt:
+
+```bash
+bun create stacksfinder my-app
+```
+
+## 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
+
+| Flag | Alias | Description |
+|------|-------|-------------|
+| `--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
+
+## 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