@factiii/stack

@factiii/stack

Infrastructure management CLI. Scan, fix, and deploy Node.js apps to AWS with Docker, Nginx, and GitHub Actions.

Install

npm install @factiii/stack

Quick Start

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:

• dev / secrets → always runs locally
• 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

• npx stack — bootstrap (installs deps, detects frameworks, generates config)
• npx stack init — create vault, store secrets
• npx stack fix --staging — provision infrastructure, push workflows
• 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.

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