@factiii/stack 0.1.2

package/README.md

@@ -0,0 +1,420 @@
+# Factiii 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 factiii init
+
+# This creates:
+# - factiii.yml (user-editable config)
+# - factiiiAuto.yml (auto-detected config)
+# - .github/workflows/ (CI/CD workflows)
+
+# Edit factiii.yml to replace EXAMPLE- values
+# Then run:
+npx factiii scan    # Check for issues
+npx factiii fix     # Auto-fix issues
+npx factiii deploy --staging  # Deploy to staging
+```
+
+## How It Works
+
+Factiii 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
+
+**`factiii.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
+```
+
+**`factiiiAuto.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 factiii init          # Initialize Factiii Stack
+npx factiii init --force  # Regenerate configs
+```
+
+**What it does:**
+- Detects which plugins are relevant to your project
+- Generates `factiii.yml` with only relevant sections
+- Generates `factiiiAuto.yml` with auto-detected values
+- Creates GitHub Actions workflows
+
+### Scan
+
+Checks all environments for issues:
+
+```bash
+npx factiii scan           # Scan all (dev, secrets, staging, prod)
+npx factiii scan --dev     # Scan dev only
+npx factiii scan --staging # Scan staging only
+npx factiii scan --prod    # Scan prod only
+```
+
+**Note:** Requires `factiii.yml` to exist. Run `npx factiii init` first.
+
+### Fix
+
+Automatically fixes issues where possible:
+
+```bash
+npx factiii fix           # Fix all environments
+npx factiii fix --dev     # Fix dev only
+npx factiii fix --staging # Fix staging only
+npx factiii fix --prod    # Fix prod only
+```
+
+**Note:** Requires `factiii.yml` to exist. Run `npx factiii init` first.
+
+### Deploy
+
+Deploys to environments (runs scan first, aborts on issues):
+
+```bash
+npx factiii deploy --dev      # Start local dev containers
+npx factiii deploy --staging  # Deploy to staging server
+npx factiii deploy --prod     # Deploy to production server
+```
+
+**Note:** Requires `factiii.yml` to exist. Run `npx factiii init` first.
+
+### Secrets Management
+
+Manage secrets via Ansible Vault and deploy them directly to servers:
+
+```bash
+# List all secrets (SSH keys + environment variables)
+npx factiii secrets list
+
+# Set SSH keys (required for deployment)
+npx factiii secrets set STAGING_SSH
+npx factiii secrets set PROD_SSH
+
+# Set environment variables for each stage
+npx factiii secrets set-env DATABASE_URL --staging
+npx factiii secrets set-env JWT_SECRET --staging
+npx factiii secrets set-env DATABASE_URL --prod
+npx factiii secrets set-env JWT_SECRET --prod
+
+# List environment variables
+npx factiii secrets list-env --staging
+npx factiii secrets list-env --prod
+
+# Deploy secrets to servers via SSH
+npx factiii secrets deploy --staging  # Deploy to staging server
+npx factiii secrets deploy --prod     # Deploy to production server
+npx factiii secrets deploy --all      # Deploy to all servers
+
+# Options
+npx factiii secrets deploy --staging --restart   # Restart container after deploy
+npx factiii 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 `factiii.yml` with Ansible Vault configured. Run `npx factiii init` first.
+
+## Stage Execution
+
+Factiii commands work with four stages: `dev`, `secrets`, `staging`, `prod`.
+
+### Running Commands
+
+```bash
+npx factiii scan              # Scan all reachable stages
+npx factiii scan --dev        # Scan only dev stage
+npx factiii scan --staging    # Scan only staging stage
+
+npx factiii fix               # Fix all reachable stages
+npx factiii fix --staging     # Fix only staging stage
+
+npx factiii deploy --staging  # Deploy to staging
+npx factiii 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 factiii fix --staging     # ✅ Correct
+npx factiii 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 factiii 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 Management
+
+Factiii uses **Ansible Vault** to store and manage deployment secrets (SSH keys, API keys, etc.).
+
+### Configuration
+
+Add Ansible Vault configuration to `factiii.yml`:
+
+```yaml
+# Ansible Vault configuration (for secrets)
+ansible:
+  vault_path: group_vars/all/vault.yml  # Path to vault file
+  vault_password_file: ~/.vault_pass    # Optional: path to password file
+```
+
+### Vault Password
+
+Provide the vault password via one of:
+- **Password file:** Set `ansible.vault_password_file` in `factiii.yml` (e.g. `~/.vault_pass`)
+- **Environment variable:** `ANSIBLE_VAULT_PASSWORD` or `ANSIBLE_VAULT_PASSWORD_FILE`
+
+**Security:** Never commit the vault password or decrypted vault file to git.
+
+### Managing Secrets
+
+```bash
+# List all secrets
+npx factiii secrets list
+
+# Set a secret (interactive prompt)
+npx factiii secrets set STAGING_SSH
+
+# Set a secret (non-interactive)
+npx factiii secrets set STAGING_SSH --value "your-key-here"
+
+# Check if secrets exist
+npx factiii secrets check
+```
+
+### Required Secrets
+
+- **STAGING_SSH** - SSH private key for staging server
+- **PROD_SSH** - SSH private key for production server
+- **AWS_SECRET_ACCESS_KEY** - AWS secret key (if using AWS pipeline)
+
+### CI/CD Integration
+
+In GitHub Actions workflows, provide the vault password as a GitHub secret:
+
+1. Add `ANSIBLE_VAULT_PASSWORD` to your repository secrets
+2. Workflows automatically load SSH keys from Ansible Vault using this password
+
+The workflow step `npx factiii secrets write-ssh-keys` extracts secrets from the vault and writes SSH keys to `~/.ssh/` for deployment steps.
+
+## 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

package/bin/factiii

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const path = require('path');
+
+// Import plugin command registration
+const { registerPluginCommands } = require('../dist/cli/plugin-commands');
+
+// Import CLI commands from compiled TypeScript
+const { init } = require('../dist/cli/init');
+const { scan } = require('../dist/cli/scan');
+const { fix } = require('../dist/cli/fix');
+const { deploy } = require('../dist/cli/deploy');
+const { undeploy } = require('../dist/cli/undeploy');
+const { secrets } = require('../dist/cli/secrets');
+const { upgrade } = require('../dist/cli/upgrade');
+const { validate } = require('../dist/cli/validate');
+const { checkConfig } = require('../dist/cli/check-config');
+const { devSync } = require('../dist/cli/dev-sync');
+
+// Read version from package.json
+const packageJson = require('../package.json');
+
+program
+  .name('factiii')
+  .description('Factiii Stack - Infrastructure management CLI')
+  .version(packageJson.version);
+
+// Init command (primary setup command)
+program
+  .command('init')
+  .description('Initialize Factiii Stack in your project (run this first)')
+  .option('-f, --force', 'Overwrite existing config files')
+  .action(async (options) => {
+    await init(options);
+  });
+
+// Default action: show help when no subcommand provided
+program
+  .action((options, command) => {
+    if (command.args.length === 0) {
+      program.help();
+    }
+  });
+
+// Scan command (explicit)
+program
+  .command('scan')
+  .description('Scan all environments for issues')
+  .option('--dev', 'Scan dev environment only')
+  .option('--staging', 'Scan staging environment only')
+  .option('--prod', 'Scan production environment only')
+  .option('--secrets', 'Scan secrets only')
+  .option('--commit <hash>', 'Commit hash to verify (for deployment verification)')
+  .action(async (options) => {
+    await scan(options);
+  });
+
+// Fix command
+program
+  .command('fix')
+  .description('Fix all environments including uploading secrets to GitHub and installing server dependencies')
+  .option('--dev', 'Fix dev environment only')
+  .option('--staging', 'Fix staging environment only')
+  .option('--prod', 'Fix production environment only')
+  .option('--secrets', 'Fix secrets only')
+  .option('--token <token>', 'GitHub token (or set GITHUB_TOKEN env var)')
+  .option('--continue-on-error', 'Continue even if some fixes fail')
+  .action(async (options) => {
+    await fix(options);
+  });
+
+// Deploy command
+program
+  .command('deploy')
+  .description('Deploy to environments (runs scan first, aborts on issues)')
+  .option('--dev', 'Deploy dev environment only (local containers)')
+  .option('--staging', 'Deploy staging environment only')
+  .option('--prod', 'Deploy production environment only')
+  .option('-e, --environment <env>', 'Environment (staging|prod)')
+  .option('-b, --branch <branch>', 'Branch to deploy from (defaults to current branch)')
+  .option('--commit <hash>', 'Commit hash to deploy (passed by workflow)')
+  .option('--token <token>', 'GitHub token (or set GITHUB_TOKEN env var)')
+  .option('--secrets', 'Deploy secrets from Ansible Vault before deploying')
+  .option('--dry-run', 'Show deployment plan without actually deploying')
+  .action(async (options) => {
+    // Determine which environment to deploy
+    let environment = options.environment;
+    if (options.dev) environment = 'dev';
+    if (options.staging) environment = 'staging';
+    if (options.prod) environment = 'prod';
+
+    if (!environment) {
+      console.log('Please specify an environment: --dev, --staging, or --prod');
+      process.exit(1);
+    }
+
+    // Map --secrets CLI flag to deploySecrets option
+    if (options.secrets) {
+      options.deploySecrets = true;
+    }
+
+    const result = await deploy(environment, options);
+    if (!result.success) {
+      process.exit(1);
+    }
+  });
+
+// Undeploy command
+program
+  .command('undeploy')
+  .description('Remove deployment from servers')
+  .option('--dev', 'Undeploy dev environment only')
+  .option('--staging', 'Undeploy staging environment only')
+  .option('--prod', 'Undeploy production environment only')
+  .option('-e, --environment <env>', 'Environment (staging|prod|all)', 'all')
+  .action(async (options) => {
+    // Determine which environment to undeploy
+    let environment = options.environment;
+    if (options.dev) environment = 'dev';
+    if (options.staging) environment = 'staging';
+    if (options.prod) environment = 'prod';
+
+    await undeploy(environment, options);
+  });
+
+// Generate workflows command
+program
+  .command('generate-workflows')
+  .description('Generate GitHub workflow files')
+  .option('-o, --output <dir>', 'Output directory', '.github/workflows')
+  .action(async (options) => {
+    const FactiiiPipeline = require('../dist/plugins/pipelines/factiii').default;
+    await FactiiiPipeline.generateWorkflows(process.cwd());
+  });
+
+// Secrets command
+program
+  .command('secrets [action] [name]')
+  .description('Manage secrets and deploy to servers')
+  .option('--value <value>', 'Secret value (for scripting)')
+  .option('--staging', 'Target staging environment')
+  .option('--prod', 'Target production environment')
+  .option('--restart', 'Restart containers after deploying secrets')
+  .option('--dry-run', 'Show what would be deployed without deploying')
+  .option('--token <token>', 'GitHub token (or use GITHUB_TOKEN env var)')
+  .action(async (action, name, options) => {
+    // Valid actions for secrets command
+    const validActions = ['list', 'set', 'check', 'set-env', 'list-env', 'deploy', 'write-ssh-keys'];
+
+    if (!action || !validActions.includes(action)) {
+      // Show help if no valid action provided
+      console.log('');
+      console.log('Usage: npx factiii secrets <action> [name] [options]');
+      console.log('');
+      console.log('Actions:');
+      console.log('  list              List all secrets (SSH keys + env vars)');
+      console.log('  set <name>        Set a secret (STAGING_SSH, PROD_SSH, etc.)');
+      console.log('  check [name]      Check if secrets exist');
+      console.log('  set-env <name>    Set environment variable for a stage');
+      console.log('  list-env          List environment variable keys for a stage');
+      console.log('  deploy            Deploy secrets to staging/prod servers');
+      console.log('  write-ssh-keys    Write SSH keys to ~/.ssh/ (for workflows)');
+      console.log('');
+      console.log('Examples:');
+      console.log('  npx factiii secrets list');
+      console.log('  npx factiii secrets set STAGING_SSH');
+      console.log('  npx factiii secrets set-env DATABASE_URL --staging');
+      console.log('  npx factiii secrets list-env --staging');
+      console.log('  npx factiii secrets deploy --staging');
+      console.log('  npx factiii secrets deploy --all');
+      console.log('');
+      return;
+    }
+
+    await secrets(action, name, options);
+  });
+
+// Upgrade command
+program
+  .command('upgrade')
+  .description('Check for updates and regenerate configs for new version')
+  .option('--check', 'Only check for updates, do not upgrade')
+  .action(async (options) => {
+    await upgrade(options);
+  });
+
+// Dev sync command - only available in dev mode
+if (process.env.DEV_MODE === 'true') {
+  program
+    .command('dev-sync')
+    .description('Sync locally built infrastructure to servers')
+    .option('--staging', 'Sync to staging environment only')
+    .option('--prod', 'Sync to production environment only')
+    .option('--deploy', 'Deploy after syncing')
+    .action(async (options) => {
+      await devSync(options);
+    });
+}
+
+// Legacy commands (for backwards compatibility)
+program
+  .command('validate')
+  .description('[Legacy] Validate factiii.yml config file')
+  .option('-c, --config <path>', 'Path to config file', 'factiii.yml')
+  .action(async (options) => {
+    await validate(options);
+  });
+
+program
+  .command('check-config')
+  .description('[Legacy] Check and regenerate configs on servers')
+  .option('-e, --environment <env>', 'Environment (staging|prod|all)', 'all')
+  .action(async (options) => {
+    await checkConfig(options);
+  });
+
+// Register plugin commands (db, ops, backup)
+// Pipeline plugin provides these commands via static commands array
+try {
+  const FactiiiPipeline = require('../dist/plugins/pipelines/factiii').default;
+  if (FactiiiPipeline.commands && FactiiiPipeline.commands.length > 0) {
+    registerPluginCommands(program, FactiiiPipeline);
+  }
+} catch (e) {
+  // Plugin commands not available - continue without them
+}
+
+program.parse();

package/dist/cli/check-config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Check Config Command (Legacy)
+ *
+ * Checks configuration for an environment
+ */
+import type { CheckConfigOptions } from '../types/index.js';
+export declare function checkConfig(options?: CheckConfigOptions): Promise<boolean>;
+export default checkConfig;
+//# sourceMappingURL=check-config.d.ts.map

package/dist/cli/check-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-config.d.ts","sourceRoot":"","sources":["../../src/cli/check-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAS,MAAM,mBAAmB,CAAC;AAEnE,wBAAsB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpF;AAED,eAAe,WAAW,CAAC"}

package/dist/cli/check-config.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Check Config Command (Legacy)
+ *
+ * Checks configuration for an environment
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkConfig = checkConfig;
+const scan_js_1 = require("./scan.js");
+async function checkConfig(options = {}) {
+    console.log('[!] The check-config command is deprecated. Use: npx factiii scan\n');
+    const environment = options.environment ?? 'staging';
+    const stages = [environment];
+    const problems = await (0, scan_js_1.scan)({ rootDir: process.cwd(), stages });
+    const envProblems = problems[environment] ?? [];
+    return envProblems.length === 0;
+}
+exports.default = checkConfig;
+//# sourceMappingURL=check-config.js.map

package/dist/cli/check-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-config.js","sourceRoot":"","sources":["../../src/cli/check-config.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAKH,kCAUC;AAbD,uCAAiC;AAG1B,KAAK,UAAU,WAAW,CAAC,UAA8B,EAAE;IAChE,OAAO,CAAC,GAAG,CAAC,qEAAqE,CAAC,CAAC;IAEnF,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,SAAS,CAAC;IACrD,MAAM,MAAM,GAAY,CAAC,WAAoB,CAAC,CAAC;IAE/C,MAAM,QAAQ,GAAG,MAAM,IAAA,cAAI,EAAC,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAEhE,MAAM,WAAW,GAAG,QAAQ,CAAC,WAAoC,CAAC,IAAI,EAAE,CAAC;IACzE,OAAO,WAAW,CAAC,MAAM,KAAK,CAAC,CAAC;AAClC,CAAC;AAED,kBAAe,WAAW,CAAC"}

package/dist/cli/deploy-secrets.d.ts

@@ -0,0 +1,16 @@
+export interface DeploySecretsOptions {
+    rootDir?: string;
+    restart?: boolean;
+    dryRun?: boolean;
+}
+export interface DeploySecretsResult {
+    success: boolean;
+    message?: string;
+    error?: string;
+}
+/**
+ * Deploy secrets to staging and/or production servers
+ */
+export declare function deploySecrets(environment: 'staging' | 'prod' | 'all', options?: DeploySecretsOptions): Promise<DeploySecretsResult>;
+export default deploySecrets;
+//# sourceMappingURL=deploy-secrets.d.ts.map