Metadata-Version: 2.4
Name: saasforge
Version: 0.4.0
Summary: Spec-Driven Micro-SaaS Development Toolkit
Author-email: Fahad Khakwani <fahadyousufkhakwani@gmail.com>
License: SaaSForge Commercial License
Project-URL: Homepage, https://github.com/Fahad-FullStackDeveloper/saasforge
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.md
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13
Requires-Dist: jinja2>=3
Dynamic: license-file

# SaaSForge

**Build 450+ Micro-SaaS tools with one DNA-driven workflow.**
AI-native, spec-driven, deploy-ready.

```
pip install saasforge
```

---

## What is SaaSForge?

SaaSForge is a Spec-Driven Micro-SaaS Development Toolkit. It lets you:

- **Scaffold** full-stack Micro-SaaS tools from a single DNA architecture document
- **Work with any AI CLI** — opencode, Claude Code, Gemini CLI, Copilot, Cursor, Aider, KiloCode, and more
- **Track decisions** via an auto-generated constitution and command history
- **Deploy** to Vercel (frontend) + Hugging Face Spaces (backend) with one checklist

Unlike general-purpose scaffolding tools, SaaSForge is **DNA-aware**: it reads your `_system/DNA.md` and generates tools that match your exact tech stack (FastAPI, Turso, Better Auth, R2, etc.).

---

## Quick Start

```bash
# Check your environment
saasforge check

# Initialize a new project
saasforge init my-micro-saas --ai opencode

# Generate workflow commands
cd my-micro-saas
saasforge workflow --ai opencode

# View your project constitution
saasforge constitute --show

# See what commands you've run
saasforge history
```

---

## Full Workflow

### 1. Define Your DNA

Create `_system/DNA.md` with your architecture:

```markdown
FRONTEND:     Next.js + Tailwind + Shadcn → Vercel
BACKEND:      Python FastAPI → Hugging Face Spaces
DATABASE:     Turso SQLite
AUTH:         Better Auth
FILE STORAGE: Cloudflare R2
```

SaaSForge parses this — case-insensitive, spaces-before-colon, aliases all work:

```markdown
FrontEnd : nextjs    ✓
DB : postgres        ✓ (alias works)
File Storage : R2    ✓
```

Validate: `saasforge dna --validate`

### 2. Initialize

```bash
# With any supported AI CLI
saasforge init . --ai opencode      # Current dir
saasforge init my-tool --ai claude  # New folder

# Plain terminal (no AI CLI needed)
saasforge init my-tool --ai terminal
```

This creates adapter config files for your chosen CLI.

### 3. Scaffold a Tool

```bash
saasforge scaffold whatsapp-bot --number 002 --dna _system/DNA.md
```

Generates:

```
_tools/
└── _002-whatsapp-bot/
    ├── frontend/
    ├── backend/
    │   ├── api/
    │   └── src/
    ├── tests/
    ├── Dockerfile
    ├── .dockerignore
    ├── app.py
    ├── requirements.txt
    └── vercel.json
```

Use `--force` to overwrite an existing tool.

### 4. Track Context (Constitution)

```bash
# Show current constitution
saasforge constitute --show

# Regenerate from DNA
saasforge constitute --regenerate

# Open in editor
saasforge constitute --edit
```

The constitution lives in `.saasforge/memory/constitution.md` — AI CLIs read it at session start for continuity.

### 5. Generate Workflow Commands

```bash
saasforge workflow --ai opencode
```

Creates slash commands in `.opencode/commands/`:

| Command | Purpose |
|---------|---------|
| `/sp.specify` | Define what to build |
| `/sp.plan` | Create implementation plan |
| `/sp.tasks` | Break into actionable tasks |
| `/sp.implement` | Execute the plan |
| `/sp.analyze` | Cross-artifact consistency check |

### 6. Deploy

```bash
saasforge deploy ./_tools/_002-whatsapp-bot
```

Shows a readiness checklist:

| Item | Tool 001 |
|------|----------|
| Dockerfile | ✓ |
| app.py | ✓ |
| vercel.json | ✓ |
| frontend/ | ✓ |
| backend/ | ✓ |

---

## Supported AI CLIs (15)

| CLI | Flag | Generates |
|-----|------|-----------|
| opencode | `--ai opencode` | `.opencode/commands/` |
| Claude Code | `--ai claude` | `.claude/commands/` |
| Gemini CLI | `--ai gemini` | `.gemini/` |
| GitHub Copilot | `--ai copilot` | `.github/instructions/` |
| Cursor | `--ai cursor` | `.cursor/rules/` |
| Windsurf | `--ai windsurf` | `.windsurf/` rules |
| Roo Code | `--ai roo` | `.roo/commands/` |
| Codex CLI | `--ai codex` | `.codex/instructions/` |
| Qwen Code | `--ai qwen` | `.qwen/` workflow |
| Qoder CLI | `--ai qoder` | `.qoder/commands/` |
| Antigravity | `--ai antigravity` | `.antigravity/rules/` |
| Aider | `--ai aider` | `.aider/CONVENTIONS.md` |
| KiloCode | `--ai kilocode` | `.kilocode/instructions/` |
| OpenRouter CLI | `--ai openroutercli` | `.openrouter/` |
| Terminal | `--ai terminal` | `.saasforge/config.yml` |

---

## Commands Reference

| Command | Description |
|---------|-------------|
| `check` | Check installed tools (git, python, pnpm, etc.) |
| `init` | Initialize project with AI CLI adapter config |
| `scaffold` | Generate full tool structure from DNA |
| `workflow` | Generate spec-driven slash commands for your CLI |
| `deploy` | Show deployment readiness checklist |
| `dna` | Inspect and validate DNA.md |
| `constitute` | Manage project constitution (memory for AI CLI) |
| `history` | View or clear command history |

### Options

| Flag | Commands | Purpose |
|------|----------|---------|
| `--ai` | init, workflow | Choose AI CLI adapter |
| `--no-git` | init | Skip git init |
| `--here` | init | Init in current directory |
| `--force`, `-f` | scaffold | Overwrite existing tool |
| `--number`, `-n` | scaffold | Tool number (default: 002) |
| `--show`, `-s` | constitute | Display constitution |
| `--edit`, `-e` | constitute | Edit in default editor |
| `--regenerate`, `-r` | constitute | Regenerate from DNA |
| `--limit`, `-n` | history | Entry count (default: 50) |
| `--clear` | history | Delete all history |
| `--validate` | dna | Run validation checks |
| `--version`, `-v` | (global) | Show version |

---

## Use Cases

### Solo Founder — Micro-SaaS Factory

Build 1 tool per week using the same DNA. Each tool gets its own Vercel project, HF Space, Turso DB, and R2 bucket — completely isolated, zero shared infrastructure.

```bash
saasforge scaffold invoice-ocr --number 001
saasforge scaffold whatsapp-bot --number 002
saasforge scaffold blog-writer --number 003
```

### Team — Standardized Architecture

Onboard new developers quickly. DNA.md is the single source of truth. Everyone uses the same stack, same patterns, same deployment flow.

### AI-Only Development

Use `--ai terminal` — no AI CLI required. The `.saasforge/config.yml` file stores your project config. Run `saasforge workflow --ai terminal` to generate instructions that any LLM can follow.

### Education — Learn Full-Stack SaaS

Scaffold a complete SaaS tool structure in seconds. Study the generated Dockerfile, FastAPI backend, Next.js frontend, and deployment config.

---

## Comparison: SaaSForge vs SpecifyPlus

| Capability | SpecifyPlus | SaaSForge |
|------------|-------------|-----------|
| **DNA-aware scaffolding** | ❌ Static templates | ✅ Reads `_system/DNA.md` |
| **CLI adapters** | 18 | 15 (terminal included) |
| **Deploy guide** | ❌ | ✅ Vercel + HF Spaces |
| **DNA validation** | ❌ | ✅ `saasforge dna --validate` |
| **Command history** | ❌ | ✅ `.saasforge/memory/history.yml` |
| **Constitution** | ✅ `.specify/memory/` | ✅ `.saasforge/memory/constitution.md` |
| **`check` command** | ✅ `specifyplus check` | ✅ `saasforge check` |
| **Scaffold `--force`** | ❌ (silent overwrite) | ✅ Explicit flag |
| **DNA parser** | Exact match only | ✅ Case-insensitive, aliases, regex |
| **Terminal-only mode** | ❌ | ✅ `--ai terminal` |
| **License** | MIT | Commercial + MIT credit (NOTICE.md) |
| **Target** | General spec-driven dev | Micro-SaaS factory (450 tools) |

---

## Architecture

```
project-root/
├── _system/
│   └── DNA.md                    ← Single source of truth
├── _tools/
│   ├── _001-invoice-ocr/         ← Isolated Micro-SaaS tool
│   │   ├── frontend/ (Next.js)
│   │   ├── backend/  (FastAPI)
│   │   ├── Dockerfile
│   │   └── app.py
│   ├── _002-whatsapp-bot/
│   └── _003-blog-writer/
├── .saasforge/
│   └── memory/
│       ├── constitution.md       ← Project memory for AI CLI
│       └── history.yml           ← Command audit trail
└── saasforge                     ← CLI tool
```

Each tool is independently deployable:

```
Tool 001  →  Vercel (FE) + HF Space (BE) + Turso DB + R2 Bucket
Tool 002  →  Vercel (FE) + HF Space (BE) + Turso DB + R2 Bucket
...
```

---

## License

- Original SpecifyPlus code: MIT © GitHub, Inc. — see NOTICE.md
- All new code, adapters, CLI, templates, and SaaSForge-specific work: **SaaSForge Commercial License** — see LICENSE

You may use SaaSForge freely in your own projects. Contact the author for commercial redistribution or licensing.
