@factiii/stack 0.1.201 → 0.7.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025-present Factiii.io
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025-present Factiii.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,403 +1,95 @@
-# Stack
-
-Infrastructure management CLI for deploying full-stack applications with plugin-based configuration.
-
-## Quick Start
-
-```bash
-# Install in your project
-npm install @factiii/stack
-
-# Initialize configuration (run this first!)
-npx stack init
-
-# This creates:
-# - stack.yml (user-editable config)
-# - stackAuto.yml (auto-detected config)
-# - .github/workflows/ (CI/CD workflows)
-
-# Edit stack.yml to replace EXAMPLE_ values
-# Then run:
-npx stack scan    # Check for issues
-npx stack fix     # Auto-fix issues
-npx stack deploy --staging  # Deploy to staging
-```
-
-## How It Works
-
-Stack uses a **plugin-based architecture** where each plugin:
-1. Defines its own configuration schema
-2. Auto-detects project settings
-3. Validates and fixes issues
-4. Handles deployment for its domain
-
-### The Two Config Files
-
-**`stack.yml`** - User-Editable Configuration
-```yaml
-name: my-app
-
-# Environment configurations
-staging:
-  domain: staging.myapp.com
-  server: mac             # OS type: mac, ubuntu, windows, amazon-linux
-  server_mode: true       # Enable server hardening (default: true)
-
-prod:
-  domain: myapp.com
-  server: ubuntu          # OS type for production
-  pipeline: aws           # Use AWS pipeline for deployment
-  config: free-tier       # AWS tier: ec2, free-tier, standard, enterprise
-  access_key_id: AKIAXXXXXXXX
-  region: us-east-1
-
-prisma:
-  schema_path: null  # Optional override
-  version: null      # Optional override
-
-# Exclude Docker containers from unmanaged container cleanup
-container_exclusions:
-  - factiii_postgres
-  - legacy_container
-```
-
-**`stackAuto.yml`** - Auto-Detected Configuration
-```yaml
-# Auto-detected by plugins
-factiii_version: 1.0.0
-has_prisma: true
-has_trpc: true
-prisma_schema: prisma/schema.prisma
-prisma_version: 5.0.0
-ssh_user: ubuntu
-dockerfile: Dockerfile
-package_manager: pnpm
-node_version: 20
-pnpm_version: 9
-aws_cli_installed: true
-```
-
-## CLI Commands
-
-### Init (Run This First!)
-
-Scans your project and generates configuration files:
-
-```bash
-npx stack init          # Initialize Stack
-npx stack init --force  # Regenerate configs
-```
-
-**What it does:**
-- Detects which plugins are relevant to your project
-- Generates `stack.yml` with only relevant sections
-- Generates `stackAuto.yml` with auto-detected values
-- Creates GitHub Actions workflows
-
-### Scan
-
-Checks all environments for issues:
-
-```bash
-npx stack scan           # Scan all (dev, secrets, staging, prod)
-npx stack scan --dev     # Scan dev only
-npx stack scan --staging # Scan staging only
-npx stack scan --prod    # Scan prod only
-```
-
-**Note:** Requires `stack.yml` (or legacy factiii.yml) to exist. Run `npx stack init` first.
-
-### Fix
-
-Automatically fixes issues where possible:
-
-```bash
-npx stack fix           # Fix all environments
-npx stack fix --dev     # Fix dev only
-npx stack fix --staging # Fix staging only
-npx stack fix --prod    # Fix prod only
-```
-
-**Note:** Requires `stack.yml` (or legacy factiii.yml) to exist. Run `npx stack init` first.
-
-### Deploy
-
-Deploys to environments (runs scan first, aborts on issues):
-
-```bash
-npx stack deploy --dev      # Start local dev containers
-npx stack deploy --staging  # Deploy to staging server
-npx stack deploy --prod     # Deploy to production server
-```
-
-**Note:** Requires `stack.yml` (or legacy factiii.yml) to exist. Run `npx stack init` first.
-
-### AWS EC2 Deployment (2 Commands)
-
-Deploy your full-stack app to AWS EC2 with just two commands:
-
-```bash
-# 1. Provision all AWS infrastructure
-npx factiii fix
-
-# Creates: VPC, Security Groups, EC2 instance, RDS database,
-# S3 bucket, ECR repository, IAM users, SES email
-
-# 2. Deploy your application
-npx factiii deploy --prod
-
-# Configures: Docker, Nginx, SSL certificates, pulls images, starts containers
-```
-
-**Prerequisites:** You need an IAM user with the `factiii-bootstrap` policy configured via `aws configure`.
-
-See [docs/aws-setup-guide.md](docs/aws-setup-guide.md) for the full step-by-step setup guide including the IAM policy JSON.
-
-### Secrets Management
-
-Manage secrets via Ansible Vault and deploy them directly to servers:
-
-```bash
-# List all secrets (SSH keys + environment variables)
-npx stack deploy --secrets list
-
-# Set SSH keys (required for deployment)
-npx stack deploy --secrets set STAGING_SSH
-npx stack deploy --secrets set PROD_SSH
-
-# Set environment variables for each stage
-npx stack deploy --secrets set-env DATABASE_URL --staging
-npx stack deploy --secrets set-env JWT_SECRET --staging
-npx stack deploy --secrets set-env DATABASE_URL --prod
-npx stack deploy --secrets set-env JWT_SECRET --prod
-
-# List environment variables
-npx stack deploy --secrets list-env --staging
-npx stack deploy --secrets list-env --prod
-
-# Deploy secrets to servers via SSH
-npx stack deploy --secrets deploy --staging  # Deploy to staging server
-npx stack deploy --secrets deploy --prod     # Deploy to production server
-npx stack deploy --secrets deploy --all      # Deploy to all servers
-
-# Options
-npx stack deploy --secrets deploy --staging --restart   # Restart container after deploy
-npx stack deploy --secrets deploy --staging --dry-run   # Show what would be deployed
-```
-
-**How it works:**
-1. Secrets are stored locally in Ansible Vault (encrypted)
-2. When you run `secrets deploy`, Factiii:
-   - Reads the SSH key from the vault
-   - Connects to the server via SSH
-   - Writes a `.env.{stage}` file with your environment variables
-3. Your application reads the `.env.{stage}` file on startup
-
-**Note:** Requires `stack.yml` with Ansible Vault configured. Run `npx stack init` first.
-
-## Stage Execution
-
-Stack commands work with four stages: `dev`, `secrets`, `staging`, `prod`.
-
-### Running Commands
-
-```bash
-npx stack scan              # Scan all reachable stages
-npx stack scan --dev        # Scan only dev stage
-npx stack scan --staging    # Scan only staging stage
-
-npx stack fix               # Fix all reachable stages
-npx stack fix --staging     # Fix only staging stage
-
-npx stack deploy --staging  # Deploy to staging
-npx stack deploy --prod     # Deploy to prod
-```
-
-### How Stages Are Reached
-
-The pipeline plugin decides how to reach each stage:
-
-| Stage | How it's reached |
-|-------|------------------|
-| dev | Always runs locally |
-| secrets | Runs locally (needs Ansible Vault configured) |
-| staging | Via workflow → SSH → runs with `--staging` |
-| prod | Via workflow → SSH → runs with `--prod` |
-
-### For Pipeline Plugin Authors
-
-When your CI/CD workflow SSHs to a server to run commands, you **MUST** specify the stage:
-
-```bash
-# In your workflow, after SSH to staging server:
-GITHUB_ACTIONS=true npx stack fix --staging     # ✅ Correct
-npx stack fix                                    # ❌ Wrong - will try to run all stages
-```
-
-This prevents the command from trying to reach stages it can't access from the server.
-
-See [STANDARDS.md](STANDARDS.md) for full documentation of the stage execution pattern.
-
-## Plugin Architecture
-
-### Built-in Plugins
-
-**Pipelines**
-- `factiii` - GitHub Actions CI/CD with thin workflows
-- `aws` - AWS infrastructure (EC2, ECR, free-tier configs)
-
-**Servers (OS Types)**
-- `mac` - macOS (Homebrew, launchctl)
-- `ubuntu` - Ubuntu Linux (apt, systemd)
-- `windows` - Windows Server (Chocolatey) - template
-- `amazon-linux` - Amazon Linux 2023 (dnf, systemd)
-
-**Frameworks**
-- `prisma-trpc` - Prisma database + tRPC API
-
-**Addons**
-- `server-mode` - Configure machines as deployment servers (disable sleep, enable SSH, etc.)
-
-### How Plugins Work
-
-Each plugin defines:
-
-```javascript
-class MyPlugin {
-  static id = 'my-plugin';
-  static category = 'framework'; // or: pipeline, server, addon
-  
-  // Schema for factiii.yml (user-editable)
-  static configSchema = {
-    my_plugin: {
-      setting: 'default-value'
-    }
-  };
-  
-  // Schema for factiiiAuto.yml (auto-detected)
-  static autoConfigSchema = {
-    has_my_plugin: 'boolean',
-    my_plugin_version: 'string'
-  };
-  
-  // Auto-detect configuration
-  static async detectConfig(rootDir) {
-    return {
-      has_my_plugin: true,
-      my_plugin_version: '1.0.0'
-    };
-  }
-  
-  // Fixes array - issues this plugin can detect and resolve
-  static fixes = [
-    {
-      id: 'missing-config',
-      stage: 'dev',
-      severity: 'critical',
-      description: 'Configuration missing',
-      scan: async (config, rootDir) => {
-        // Return true if problem exists
-        return !config.my_plugin;
-      },
-      fix: async (config, rootDir) => {
-        // Auto-fix the problem
-        return true;
-      },
-      manualFix: 'Add my_plugin config to factiii.yml'
-    }
-  ];
-  
-  // Deploy method
-  async deploy(config, environment) {
-    // Handle deployment for this environment
-  }
-}
-```
-
-## Thin Workflows
-
-GitHub Actions workflows are intentionally minimal - they just SSH into servers and call the CLI:
-
-```yaml
-# .github/workflows/factiii-staging.yml
-- name: Deploy via CLI
-  run: |
-    ssh user@host << EOF
-      cd ~/.factiii/my-app
-      git pull
-      GITHUB_ACTIONS=true npx stack deploy --staging
-    EOF
-```
-
-**CRITICAL: Workflows MUST specify the stage flag (`--staging` or `--prod`) when running commands on servers.**
-
-All deployment logic runs on the server in testable JavaScript, not in workflow bash scripts.
-
-## Secrets Configuration
-
-Secrets are managed via Ansible Vault (see CLI commands above). Add this to `stack.yml`:
-
-```yaml
-ansible:
-  vault_path: group_vars/all/vault.yml
-  vault_password_file: ~/.vault_pass      # or set ANSIBLE_VAULT_PASSWORD env var
-```
-
-**Required secrets:** `STAGING_SSH`, `PROD_SSH`, and `AWS_SECRET_ACCESS_KEY` (if using AWS).
-
-**CI/CD:** Add `ANSIBLE_VAULT_PASSWORD` to your GitHub repo secrets. Workflows use `npx stack deploy --secrets write-ssh-keys` to extract SSH keys for deployment.
-
-**Security:** Never commit the vault password or decrypted vault file to git.
-
-## Environment Variables
-
-Plugins declare required environment variables:
-
-```javascript
-class MyPlugin {
-  static requiredEnvVars = ['DATABASE_URL', 'API_KEY'];
-}
-```
-
-These are automatically validated against:
-- `.env.example` (template, committed to git)
-- `.env` (local dev, gitignored, auto-created from example)
-- `.env.staging` (staging values, user creates)
-- `.env.prod` (production values, user creates)
-
-## AWS Configuration Bundles
-
-The AWS plugin supports multiple configuration bundles:
-
-```yaml
-# factiii.yml
-aws:
-  config: free-tier  # Choose your bundle
-  region: us-east-1
-```
-
-**Available Bundles:**
-- `ec2` - Basic EC2 instance
-- `free-tier` - Complete free tier (EC2 + RDS + S3 + ECR)
-- `standard` - Production-ready setup (coming soon)
-- `enterprise` - HA, multi-AZ, auto-scaling (coming soon)
-
-## External Plugins
-
-Install external plugins via npm:
-
-```bash
-npm install @factiii/stack-plugin-nextjs
-```
-
-Factiii automatically loads plugins from `node_modules` that match:
-- `@factiii/stack-plugin-*`
-- Listed in `factiii.yml` under `plugins`
-
-## Development
-
-See [STANDARDS.md](STANDARDS.md) for plugin development guide.
-
-## License
-
-MIT
+# @factiii/stack
+
+Infrastructure management CLI. Scan, fix, and deploy Node.js apps to AWS with Docker, Nginx, and GitHub Actions.
+
+## Install
+
+```bash
+npm install @factiii/stack
+```
+
+## Quick Start
+
+```bash
+npx stack              # Self-bootstrap + scan
+npx stack init         # First-time vault/secrets setup
+npx stack scan --dev   # Read-only issue detection
+npx stack fix --dev    # Auto-fix detected issues
+npx stack deploy --staging  # Scan then deploy
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx stack` | Self-bootstrap + scan (default) |
+| `npx stack init` | First-time vault/secrets setup |
+| `npx stack scan [--stage]` | Read-only issue detection |
+| `npx stack fix [--stage]` | Auto-fix detected issues |
+| `npx stack deploy --<stage>` | Scan then deploy |
+| `npx stack deploy --secrets <action>` | Manage Ansible Vault secrets |
+| `npx stack db <cmd> --<stage>` | Database operations (migrate, seed, reset, status) |
+| `npx stack ops <cmd> --<stage>` | Server operations (logs, restart, shell, status) |
+| `npx stack backup <cmd> --<stage>` | Database backup/restore |
+| `npx stack dev-reset [--dry-run]` | Reset local config/secrets for fresh bootstrap |
+
+## Stages
+
+`--dev`, `--secrets`, `--staging`, `--prod`
+
+Routing priority:
+1. `dev` / `secrets` → always runs locally
+2. `staging` / `prod` → tries SSH key (`~/.ssh/{stage}_deploy_key`) → falls back to GitHub Actions workflow → unreachable
+
+## Config Files
+
+| File | Purpose | Editable By |
+|------|---------|-------------|
+| `stack.yml` | Manual settings (committed) | User |
+| `stackAuto.yml` | Auto-detected settings | Stack CLI |
+| `stack.local.yml` | Per-developer overrides (gitignored) | User |
+
+Legacy `factiii.yml` is also supported.
+
+## Plugins
+
+**Pipelines** — CI/CD routing: `factiii`, `aws`
+
+**Servers** — OS-specific commands: `mac`, `ubuntu`, `windows`, `amazon-linux`
+
+**Frameworks** — App scaffolding: `prisma-trpc`, `expo`
+
+**Addons** — Extensions: `server-mode` (hardening), `openclaw` (AI agent), `auth` (@factiii/auth integration)
+
+Plugins auto-detect from your project. No manual registration needed.
+
+## AWS Strategy
+
+Two IAM users per project:
+- **Dev account** (dev + staging): `factiii-{project}-dev`
+- **Prod account** (prod only): `factiii-{project}-prod`
+
+Provisioning covers EC2, RDS, VPC, ECR, Route 53, and S3.
+
+## Deployment Flow
+
+1. `npx stack` — bootstrap (installs deps, detects frameworks, generates config)
+2. `npx stack init` — create vault, store secrets
+3. `npx stack fix --staging` — provision infrastructure, push workflows
+4. `npx stack deploy --staging` — scan, build, deploy via SSH or GitHub Actions
+
+Workflows are ultra-thin: trigger + secrets + SSH + CLI call. No setup/clone/build logic in CI.
+
+```yaml
+ssh -i ~/.ssh/deploy_key "$USER@$HOST" \
+  "GITHUB_ACTIONS=true npx stack deploy --staging"
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- pnpm, npm, or yarn
+
+## License
+
+MIT