Metadata-Version: 2.4
Name: sscli
Version: 3.2.5
Summary: Seed & Source CLI - Production-ready SaaS scaffolding for Rails, Python, React, Astro, and more
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12.3
Requires-Dist: rich
Requires-Dist: questionary
Requires-Dist: requests
Requires-Dist: python-dotenv
Requires-Dist: pydantic>=2.0.0
Requires-Dist: tomlkit>=0.12.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: packaging
Requires-Dist: libcst>=0.4.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: requires-python

# Seed & Source CLI (sscli)

The unified scaffold tool for the **Seed & Source** template library. Pick a base, bolt on features, ship faster.

## 🎯 What is sscli?

`sscli` is a code-generation CLI that pulls production-ready project templates and injects optional premium modules into them. Every template is a complete, opinionated starting point — not a toy boilerplate.

![sscli workflow](docs/assets/workflow.svg)

- ✅ **Production-ready bases** — Rails API, Python SaaS, React, Astro, mobile, and more
- ✅ **Optional feature injection** — Commerce, Auth, Admin, Tunnels, and others added at scaffold time
- ✅ **Clean architecture** — Hexagonal (Python), standard Rails conventions, functional React
- ✅ **Docker-first** — Every template ships with a multi-stage production `Dockerfile`

---

## 📦 Install

```bash
# Recommended
pipx install sscli

# Or via pip
pip install sscli

# Verify
sscli --version
```

---

## 🚀 Quick Start

```bash
# Interactive mode — guided setup with template picker
sscli interactive

# Or go direct
sscli new --template rails-api --name my-api
```

New to Seed & Source? Start here: [../../docs/public/GETTING_STARTED.md](../../docs/public/GETTING_STARTED.md)

---

## 🗂️ Templates

> Run `sscli explore` to browse all templates interactively in your terminal.

---

### 🛤️ Rails API &nbsp;·&nbsp; `rails-api` &nbsp;·&nbsp; FREE

A production-grade JSON API built on **Rails 8** — opinionated, deployable on day one.

```
app/
├── controllers/api/v1/   # Versioned JSON endpoints
├── models/               # ActiveRecord (PostgreSQL)
├── services/             # Business logic layer
└── serializers/          # JSON serialization
```

**What's in the base:**
- Rails 8.0 + PostgreSQL + Devise (authentication)
- RSpec test suite + FactoryBot
- HMAC webhook validation scaffolding
- Docker + `.env` secrets management
- RuboCop enforced

```bash
sscli new --template rails-api --name my-api
```

<details>
<summary>➕ Available Features (click to expand)</summary>

| Flag | Tier | Description |
|------|------|-------------|
| `--with-commerce` | PRO | Shopify / Stripe adapter pattern, webhook infrastructure, commerce models |
| `--with-merchant-dashboard` | PRO | React order & analytics UI — requires `--with-commerce` |
| `--with-tunnel` | PRO | ngrok local tunnel config for webhook testing |
| `--with-auth` | PRO | Extended authentication flows (JWT, API key management) |
| `--with-landing` | PRO | Injects a companion Astro landing page alongside the API |
| `--with-admin` | PRO | NiceGUI-based admin panel |

**Commerce example:**
```bash
sscli new \
  --template rails-api \
  --name shopify-backend \
  --with-commerce \
  --with-tunnel
```

```
Request Flow:
Shopify Webhook → HMAC Validator → ShopifyAdapter
  → Provisioning::IssueResource → CommercialAgreement + SecurityToken
```
</details>

---

### 🏗️ Rails Fullstack &nbsp;·&nbsp; `rails-fullstack` &nbsp;·&nbsp; PRO

A **Hotwire / Turbo fullstack Rails 8** application — session auth, server-rendered HTML, and the full hexagonal domain layer shared with `rails-api` via `rails-hexagonal-base`.

```
app/
├── domain/         # Pure Ruby ports + entities (shared with rails-api)
├── use_cases/      # Business logic — no HTTP dependency
├── infrastructure/ # AR repositories (shared with rails-api)
├── controllers/    # ActionController::Base, flash & redirects
├── views/          # ERB layouts + Turbo Stream partials
└── components/     # ViewComponent
```

**What's in the base:**
- Rails 8 + Hotwire (Turbo + Stimulus) + Tailwind CSS
- Devise session auth (no JWT — full cookie/CSRF stack)
- ViewComponent + Capybara system specs
- Hexagonal domain layer from `rails-hexagonal-base` (zero drift guarantee)
- RuboCop + Brakeman gate via `bin/ci`
- Docker + `.env` secrets management

```bash
sscli new --template rails-fullstack --name my-app
```

<details>
<summary>➕ Available Features (click to expand)</summary>

| Flag | Tier | Description |
|------|------|-------------|
| `--with-commerce` | PRO | Commerce models, product/order ports, Shopify/Stripe adapters |
| `--with-tunnel` | PRO | ngrok local tunnel config for webhook testing |
| `--with-auth` | PRO | Extended authentication flows (RBAC, API keys) |

</details>

---

### 🐍 Python SaaS &nbsp;·&nbsp; `python-saas` &nbsp;·&nbsp; ALPHA

A **Hexagonal Architecture** Python service — ports and adapters enforced from project root.

```
src/
├── core/
│   ├── entities/          # Pure domain models (no I/O)
│   └── use_cases/         # Business logic (depends only on entities)
└── infrastructure/
    ├── adapters/          # DB, HTTP, external services
    └── ui/                # FastAPI / Django routes
```

**What's in the base:**
- Python 3.11+ with FastAPI or Django
- SQLAlchemy ORM + Pydantic v2 validation
- `ruff` + `mypy` strict mode enforced
- Multi-tier secrets management (**Dotenv**, **Doppler**, **Env-only**)
- pytest with coverage gate (target 95% on codemods)

```bash
sscli new --template python-saas --name my-service
```

<details>
<summary>➕ Available Features (click to expand)</summary>

| Flag | Tier | Description |
|------|------|-------------|
| `--with-commerce` | PRO | Commerce adapter wired into the hexagonal ports |
| `--with-admin` | PRO | NiceGUI admin panel as a standalone service |
| `--with-sqlite` | ALPHA | Local SQLite persistence via SQLAlchemy + Alembic (dev/test) |
| `--with-ingestor` | PRO | Data Ingestor adapter pattern for raw data normalization |
| `--with-tunnel` | PRO | ngrok tunnel config for local webhook testing |
| `--with-auth` | PRO | Authentication flows injected into the use case layer |

```bash
sscli new \
  --template python-saas \
  --name data-service \
  --with-ingestor \
  --with-sqlite
```
</details>

---

### 🌐 Static Landing &nbsp;·&nbsp; `static-landing` &nbsp;·&nbsp; ALPHA

An **Astro-powered** static site built for SaaS marketing pages — multi-theme, blueprint-driven.

```
src/
├── components/   # Astro/React island components
├── pages/        # File-based routing
└── content/      # Markdown + JSON content layer
blueprint.json    # Content & theme configuration file
```

**What's in the base:**
- Astro 5.0 + Tailwind CSS
- Multi-theme system (**Emerging Emerald**, **Midnight Azure**, **Crimson Bloom**, **Vibrant Amber**)
- `blueprint.json` manifest for content/theme customization
- Static build → Nginx Docker image
- Playwright smoke tests

```bash
sscli new --template static-landing --name my-landing

# With custom content & theme
sscli new \
  --template static-landing \
  --name my-landing \
  --content ./my-blueprint.json \
  --theme midnight
```

<details>
<summary>➕ Available Features (click to expand)</summary>

| Flag | Tier | Description |
|------|------|-------------|
| `--with-commerce` | PRO | Storefront components (cart, product, checkout UI) |
| `--with-auth` | PRO | Auth-gated page sections |

</details>

---

### ⚛️ React Client &nbsp;·&nbsp; `react-client` &nbsp;·&nbsp; ALPHA

A **React 18 + Vite** frontend with the full modern stack, ready to connect to any of the backend templates.

```
src/
├── components/   # Functional components only
├── hooks/        # Custom hooks for all business logic
├── pages/        # Route-level components
└── api/          # React Query client bindings
```

**What's in the base:**
- React 18 + Vite + TypeScript
- React Query for server state
- Tailwind CSS
- ESLint + Prettier strict mode
- Jest + Playwright

```bash
sscli new --template react-client --name my-frontend
```

<details>
<summary>➕ Available Features (click to expand)</summary>

| Flag | Tier | Description |
|------|------|-------------|
| `--with-commerce` | PRO | Commerce UI components (cart, order flow) |
| `--with-merchant-dashboard` | PRO | Full merchant dashboard — orders, analytics, settings. Requires `--with-commerce` |
| `--with-auth` | PRO | Auth flows integrated with React Query |

```bash
sscli new \
  --template react-client \
  --name merchant-ui \
  --with-commerce \
  --with-merchant-dashboard
```
</details>

---

### 📊 Data Pipeline &nbsp;·&nbsp; `data-pipeline` &nbsp;·&nbsp; ALPHA

A **dbt + Python** data stack for SaaS analytics and data transformation pipelines.

```bash
sscli new --template data-pipeline --name my-pipeline
```

<details>
<summary>What's included (click to expand)</summary>

- dbt Core with modular transformation layers (staging → marts)
- Python ingestion scripts
- Docker orchestration
- Pre-configured profiles for PostgreSQL / BigQuery

</details>

---

### 📱 Mobile &nbsp;·&nbsp; ALPHA

| Template | Stack | Command |
|----------|-------|---------|
| `mobile-android` | Kotlin + Jetpack Compose | `sscli new --template mobile-android --name my-app` |
| `mobile-ios` | Swift + SwiftUI | `sscli new --template mobile-ios --name my-app` |

---

### 🏗️ Infrastructure &nbsp;·&nbsp; ALPHA

| Template | Stack | Command |
|----------|-------|---------|
| `terraform-infra` | Terraform multi-cloud IaC | `sscli new --template terraform-infra --name my-infra` |
| `wiring` | Docker Compose multi-service orchestration | `sscli new --template wiring --name my-stack` |

---

## 🔧 CLI Reference

| Command | Description |
|---------|-------------|
| `sscli new` | Scaffold a new project from a template |
| `sscli setup` | Run setup scripts for templates |
| `sscli interactive animated` | Guided interactive setup with a robust animated experience |
| `sscli explore` | Browse all templates in an interactive tree view |
| `sscli verify` | Verify template integrity and run smoke tests |
| `sscli health` | Check configuration and template health |
| `sscli validate` | Run smoke test suite against a template |
| `sscli upgrade` | Upgrade a generated project to a newer template version using AST |
| `sscli auth login` | Authenticate with GitHub to unlock ALPHA/PRO templates |
| `sscli whoami` | Show current authenticated user and license tier |
| `sscli logout` | Clear local credentials |
| `sscli obs diff` | 3-way diff between base template and current code |
| `sscli obs workspace` | Manage feature isolation workspaces |

### Feature Flags for `sscli new`

| Flag | Templates | Tier |
|------|-----------|------|
| `--with-commerce` | rails-api, python-saas, react-client, static-landing | PRO |
| `--with-merchant-dashboard` | react-client | PRO |
| `--with-auth` | rails-api, python-saas, react-client, static-landing | PRO |
| `--with-admin` | rails-api, python-saas | PRO |
| `--with-tunnel` | rails-api, python-saas | PRO |
| `--with-landing` | rails-api, python-saas | PRO |
| `--with-ingestor` | python-saas | PRO |
| `--with-sqlite` | python-saas | ALPHA |
| `--secrets <strategy>` | all | FREE |
| `--use-ast-injection` | all (where supported) | ALPHA |
| `--content <file>` | static-landing | ALPHA |
| `--theme <name>` | static-landing | ALPHA |
| `--dry-run` | all | FREE |
| `--json` | all | FREE |

---

## 🔄 Updates

```bash
pipx upgrade sscli
# or
pip install --upgrade sscli
```

---

## ❓ Troubleshooting

<details>
<summary>Command not found after install</summary>

```bash
sscli --version

# If missing, reinstall via pipx
pipx uninstall sscli
pipx install sscli
```
</details>

<details>
<summary>Template not generating correctly</summary>

```bash
# Check template integrity first
sscli verify --template rails-api

# Preview without writing files
sscli new --template rails-api --name test --dry-run
```
</details>

---

## 📞 Support

- **Docs**: [docs.seedsource.dev](https://docs.seedsource.dev)
- **GitHub**: [seed-source/stack-cli](https://github.com/seed-source/stack-cli)
- **Email**: support@seedsource.dev

---

## 📄 License

MIT
