sscli 2.6.1
Seed & Source CLI - Multi-tenant SaaS scaffolding with Merchant Dashboard
Requires Python: >=3.9

# Seed & Source CLI

Unified interface for Seed & Source templates. Now with **Seed & Source Core** and **The Central Vault**.

## 🎯 What is sscli?

`sscli` scaffolds complete, enterprise-grade SaaS stacks. As part of the **Great Decoupling**, our templates are now "Lean Cores", with high-value proprietary features (Commerce, Admin, Tunnels, Merchant Dashboard) managed via a central vault and injected at setup time.

- ✅ **Lean Cores**: Free, high-performance base templates for Rails, Python, and Astro.
- ✅ **The Vault**: Proprietary high-value features (Commerce, Admin, Tunnels) injected on-demand.
- ✅ **Multi-tenant isolation**: Pre-configured database-level security.
- ✅ **Hexagonal Architecture**: Clean separation between domain logic and infrastructure.

## 📦 Quick Install

```bash
# Via pip
pip install sscli

# Via pipx (recommended)
pipx install sscli

# Verify
sscli --version
```

## 🚀 Quick Start

### Create a Multi-Tenant Rails API (Lean Core + Commerce Vault)

```bash
sscli new \
  --template rails-api \
  --name my-saas-api \
  --with-commerce
```

This scaffolds:
- Rails 8.0 API with PostgreSQL (Lean Core)
- **Vault Injection**: Pluggable Commerce adapters and and webhooks.
- Multi-tenant core (Tenants, API Keys, etc.)
- HMAC webhook validation
- Row-Level Security (RLS) enforcement

### Create a Python SaaS Backend

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

This scaffolds:
- Python 3.11+ FastAPI or Django
- SQLAlchemy ORM
- Pydantic validation
- Pre-configured logging

### Create a React Client

```bash
sscli new \
  --template react-client \
  --name my-frontend \
  --with-tailwind
```

This scaffolds:
- React 18+ with Vite
- React Query for state
- Tailwind CSS
- TypeScript

## 📋 Available Templates (Lean Cores)

| Template | Tier | Description |
|----------|------|-------------|
| `rails-api` | **FREE** | Multi-tenant Rails API |
| `python-saas` | **FREE** | Python SaaS Boilerplate |
| `static-landing` | **FREE** | Astro Static Landing Page |
| `react-client` | ALPHA | React + Vite frontend |
| `data-pipeline` | ALPHA | dbt + Airflow pipeline |

## 💎 High-Value Feature Vault (Premium)

These modules are managed in the central private vault and injected on-demand into the Lean Cores:

| Feature | Tier | Description |
|---------|------|-------------|
| `commerce` | **PRO** | Shopify/Stripe adapters, webhooks, and commerce models |
| `merchant-dashboard` | **PRO** | Complete order/analytics UI for merchants (requires commerce) |
| `admin` | **PRO** | Standalone NiceGUI-based admin dashboard |
| `tunnel` | **PRO** | Automated ngrok config for local webhook testing |
| `sqlite` | ALPHA | Local persistence adapter (SQLAlchemy/Alembic) |
| `ingestor` | **PRO** | Data Ingestor adapter for raw normalization |

## 🔧 CLI Commands

```bash
sscli new              # Create new project
sscli interactive      # Interactive mode
sscli explore          # List available templates
sscli verify           # Verify template integrity
sscli obs              # Project observability (diffs & workspaces)
sscli dev mount        # Feature mounting for live development
```

## 📚 Documentation

Detailed guides are available in the `docs/` folder:

- **[AST-Based Codemods](docs/AST_CODEMODS.md)**: Technical manual for the transformation engine.
- **[Development Workflow](docs/DEVELOPMENT_WORKFLOW.md)**: Guide for feature mounting and integration tests.
- **[Integration Testing](docs/DEVELOPMENT_WORKFLOW.md#integration-test-matrix)**: Running the feature/template matrix validation.

### Domain Models

```ruby
# SaaS customer
Tenant.create!(name: "Organization", subdomain: "org")

# Platform credentials (Shopify, Stripe, etc.)
Integration.create!(
  tenant: tenant,
  platform_domain: "store.myshopify.com",
  provider_type: "shopify",
  platform_token: "access_token_here"
)

# Order/contract bridge
agreement = CommercialAgreement.create!(provider_id: "shopify_order_123")

# Access grant
token = SecurityToken.generate_for(agreement)
# => token.token = "secure_random_hex"
```

### Security Features

- ✅ **HMAC Validation**: All webhooks are signature-verified
- ✅ **Row-Level Security**: PostgreSQL policies enforce tenant isolation
- ✅ **Idempotency**: Duplicate webhooks don't create duplicate resources
- ✅ **Tenant Scoping**: All queries automatically scoped by `ActsAsTenant`

### Architecture

```
External System (Shopify) → HMAC Validator → ShopifyAdapter → 
Provisioning::IssueResource → CommercialAgreement + SecurityToken
```

## 🎯 Use Cases

### Use Case: SaaS with Shopify Integration

```bash
sscli new \
  --template rails-api \
  --name shopify-saas \
  --with-commerce \
  --with-shopify

cd shopify-saas
rails db:migrate
# Create Tenant and Integration records
# Configure Shopify webhooks
rails server
```

### Use Case: Multi-Provider Payment Platform

```bash
# Start with Shopify
sscli new \
  --template rails-api \
  --name payment-platform \
  --with-shopify

# Add Stripe adapter later (v1.2.0)
# One codebase, multiple providers
```

### Use Case: Data-Critical SaaS

```bash
# Create Rails API
sscli new --template rails-api --name analytics-api

# Create data pipeline
sscli new --template data-pipeline --name analytics-pipeline

# They integrate seamlessly
```

## 🔌 Adding Custom Adapters

Create a new provider adapter in 3 steps:

1. **Implement the Port** (`ICommerceProvider`):
```ruby
module Commerce
  class MyAdapter
    include ICommerceProvider
    
    def handle_webhook(event_type, payload)
      # Your logic here
    end
  end
end
```

2. **Register in Controller**:
```ruby
# app/controllers/api/v1/webhooks_controller.rb
adapter = Commerce::MyAdapter.new(tenant)
adapter.handle_webhook(topic, payload)
```

3. **Test**:
```bash
curl -X POST http://localhost:3000/api/v1/webhooks/myservice \
  -H "X-Signature: ..." \
  -d '{...}'
```

## 🧪 Testing Templates

Verify templates work correctly:

```bash
sscli verify --template rails-api
sscli verify --template python-saas
sscli verify --template react-client
```

## 🚀 Deployment

Each template includes deployment configs for:
- Docker
- Heroku
- AWS ECS
- Kubernetes

See individual template READMEs for details.

## 🔄 Updates

Update to latest version:

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

## 💻 Local Development

### Prerequisites

- Python 3.11+
- Git

### Setup

1. **Clone the repository**:
   ```bash
   git clone https://github.com/seed-source/foundry-meta.git
   cd foundry-meta/tooling/stack-cli
   ```

2. **Create a Python virtual environment**:
   ```bash
   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install in editable mode**:
   ```bash
   pip install -e .
   ```

4. **Verify installation**:
   ```bash
   sscli --help
   ```

### Development Workflow

- **Edit code**: Make changes in `foundry/` and `tests/` — they're immediately available to `sscli` since it's installed in editable mode.
- **Run tests**: `pytest tests/`
- **Release**: Bump the version in `pyproject.toml`, commit, and push a Git tag (e.g., `git tag -a v2.0.5 -m "..."`)

### Deactivate Development Environment

```bash
deactivate
```

This switch you back to your system `sscli` (or uninstalled if you only use editable mode).

## ❓ Troubleshooting

### Command not found

```bash
# Ensure installation worked
sscli --version

# If not found, reinstall
pipx uninstall sscli
pipx install sscli
```

### Template not creating correctly

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

# Use verbose mode
sscli new --template rails-api --name test --verbose
```

## 📞 Support

- **GitHub**: [seed-source/foundry-meta](https://github.com/seed-source/foundry-meta)
- **Docs**: [Seed & Source Docs](https://docs.seedsource.dev)
- **Email**: support@seedsource.dev

## 📄 License

MIT