# 🚀 Backlist — All-in-One Multi-Platform CLI

[![NPM Version](https://img.shields.io/npm/v/create-backlist.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/create-backlist)
[![Downloads](https://img.shields.io/npm/dt/create-backlist.svg?style=flat-square&color=green)](https://www.npmjs.com/package/create-backlist)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg?style=flat-square)](https://github.com/WAH-ISHAN/create-backlist/graphs/commit-activity)
[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-blue?style=flat-square)](#)

> **ONE tool. The entire software lifecycle: Backend Generation → QA → Docker → Kubernetes → Helm → Terraform → CI/CD → Multi-Cloud → Monitoring.**

`backlist` merges the **create-backlist** engine (AST-powered polyglot backend generation + real-browser QA) with a full **DevOps command center** (Docker, Kubernetes, Helm, Terraform, CI/CD, multi-cloud, monitoring) into a single cross-platform CLI that runs on **Windows, macOS, and Linux** with zero configuration.

---

## 📊 Why One Tool? — Feature Comparison

| Feature               | create-backlist | DevOps CLI | **backlist (All-in-One)** |
| --------------------- | :-------------: | :--------: | :-----------------------: |
| Backend Generation    | ✅              | ❌         | ✅                        |
| Docker Build          | ✅              | ✅         | ✅                        |
| Kubernetes Deploy     | ❌              | ✅         | ✅                        |
| Helm Charts           | ❌              | ✅         | ✅                        |
| Terraform IaC         | ❌              | ✅         | ✅                        |
| CI/CD Pipeline        | ✅              | ✅         | ✅                        |
| Multi-Cloud           | ❌              | ✅         | ✅                        |
| Monitoring            | ❌              | ✅         | ✅                        |
| QA Testing            | ✅              | ❌         | ✅                        |

**Before:** two separate tools — `create-backlist` for generation & QA, a DevOps CLI for deployment. Context-switching, duplicated configs, disjointed workflows.

**After:** one binary, one workflow, one config — `backlist gen` → `backlist qa` → `backlist docker build` → `backlist k8s deploy` → `backlist monitor up`. Every stage of shipping software in a single command tree.

---

## ⚡ Quick Start

```bash
# Install once — works on Windows, macOS, Linux
npm install -g create-backlist

# The whole lifecycle from one CLI
backlist gen                  # 1. Generate backend from frontend (AST, 18+ stacks)
backlist qa auto --url=http://localhost:3000   # 2. Real-browser QA
backlist docker build --tag myapp:v1           # 3. Build the image
backlist k8s deploy --namespace staging        # 4. Deploy to Kubernetes
backlist monitor up                            # 5. Watch it in production
```

Or run it inside any project without global install:

```bash
npx create-backlist@latest
```

---

## 🗂️ Command Reference

```
backlist <command> [options]

Backend & Quality:
  gen            Generate backend from frontend (AST, 18+ stacks)
  auto           🤖 Autopilot — zero prompts: auto-detect project, generate,
                 install & run the FULL system (backend + frontend)
  qa             Run QA: auto | scan | manual | history | post-gen

Build & Run:
  docker         Docker: build | up | down | ps | logs | clean | push
  dev            Start local dev environment

Deploy:
  k8s            Kubernetes: deploy | rollback | scale | status | logs | top
  helm           Helm: create | install | upgrade | list | package | template
  deploy         Full deploy workflow [--k8s|--helm|--compose] [--qa] [--production]
  rollback       Roll back the last deployment

Infrastructure:
  tf             Terraform IaC: init | plan | apply | destroy (alias: terraform, infra)

CI/CD & Automation:
  ci             Pipelines: init | run | deploy | status
  pipeline       Full pipeline: [--gen] [--qa] → test → build → deploy

Cloud & Observability:
  cloud          Multi-cloud: status | aws | azure | gcp | eks | aks | gke | login
  monitor        Observability: init | up | down | status | logs

Project:
  init           Scaffold backend + full DevOps setup
  panel          🖥️  3-Phase System Panel — overview → deps & run → all tools
  config         Show effective config · init → create .backlist.yml
  doctor         Check environment toolchain
  version        Show version information
  help           Show this help
```

### End-to-end workflows

```bash
# 🤖 AUTOPILOT — no questions asked. Run this inside ANY frontend project:
backlist auto
# → auto-detects the project (React/Vue/Next/Svelte…), AST-scans the source,
#   generates the backend (auto stack), installs deps, starts BOTH servers
#   and prints a live dashboard:  http://localhost:8000  +  http://localhost:5173
#   Ctrl+C stops everything.

backlist auto --stack=nestjs        # autopilot with a specific stack
backlist auto --no-run              # autopilot: generate only (no install/run)
backlist auto --no-frontend         # skip the frontend dev server
backlist auto --port=9000           # backend on a custom port

# From zero to deployed in one command
backlist init                       # backend + Dockerfile + compose + k8s + terraform + CI

# Ship with a QA gate
backlist deploy --k8s --qa --url=http://localhost:3000

# Full pipeline (generate → QA → test → build → deploy)
backlist pipeline --gen --qa

# One-shot cloud cluster + deploy
backlist cloud eks myapp-cluster && backlist k8s deploy

# Observability in production
backlist monitor up                 # Prometheus + Grafana stack
backlist monitor status             # scrape-target health
```

---

## 🤖 Autopilot — Zero-Prompt Full-System Run

`backlist auto` turns the whole toolchain into a **single hands-free command**. Run it inside any frontend project and it:

1. **Auto-detects the project** — finds the real root (cwd, or `frontend/`, `client/`, `web/`, …)
2. **Auto-locates frontend source** — framework-aware (`src/`, Next.js `app`/`pages`, Vue, Svelte…) via `project-detector`
3. **AST-scans** every source dir in parallel — endpoints, models, auth, forms, security
4. **Auto-picks the stack** — bun → `bun-elysia`, TS → `node-ts-express`, JS → `js-express` (or `--stack=` to override)
5. **Generates the backend** with zero-config **Prisma + SQLite** (runs instantly, no external DB)
6. **Installs dependencies** with your detected package manager (npm/bun/pnpm/yarn)
7. **Creates `.env`**, runs `prisma generate` + `prisma db push`
8. **Starts the backend** (port 8000) **and the frontend** dev server (real port detected from its output)
9. **Shows a live dashboard** with both URLs, endpoints, OpenAPI — **ready for you to try**
10. **Ctrl+C** stops both servers cleanly

No paths to type, no stack questions, no setup steps. One command → full system running.

---

## 🖥️ System Panel — the 3-Phase Command Center

`backlist panel` is the tool's main workflow in one interactive screen:

```
PHASE 1 · SYSTEM BASE        PHASE 2 · DEPENDENCIES & RUN     PHASE 3 · INTERNAL PANEL
┌─────────────────────┐     ┌──────────────────────────┐     ┌───────────────────────┐
│ Project  /my/app    │     │ ✓ Node.js  ✓ npm  ✓ Git   │     │ › 🔍 QA & Testing     │
│ Framework Vite React│     │ ⚠ Docker (optional)       │     │   🐳 Docker           │
│ Files     42        │     │ ✓ Backend generated       │     │   ☸️  Kubernetes       │
│ Endpoints 5 (AST)   │     │ ✓ Dependencies installed  │     │   ⛵ Helm Charts       │
│ Models    2         │     │ ✓ .env + Prisma sqlite    │     │   🏗️  Terraform        │
│ Stack     auto      │     │ ✓ Backend UP :8000        │     │   ⚙️  CI/CD            │
│ Tools     8/12 ✓    │     │ ✓ Frontend UP :5173       │     │   ☁️  Cloud            │
└─────────────────────┘     └──────────────────────────┘     │   📊 Monitoring       │
                                                              │   🧾 Configuration    │
                                                              │   📡 Service Logs     │
                                                              └───────────────────────┘
```

1. **Phase 1 — System Base:** shows every file, framework, AST-detected endpoints/models, stack, and the full toolchain check (Node/npm/Docker/kubectl/Helm/Terraform/cloud CLIs).
2. **Phase 2 — Dependencies & Run:** verifies all dependencies, generates/installs the backend, creates `.env`, pushes the DB schema, then **starts backend + frontend** and confirms each port is live.
3. **Phase 3 — Internal Tool Panel:** with servers running in the background, operate **every tool from one menu** — QA scans, Docker, Kubernetes, Helm, Terraform, CI/CD, Cloud, Monitoring, Config — each runs in-place, then returns to the menu. `📡 Service Logs` tails backend/frontend output; `🚪 Exit Panel` stops all services.

```bash
backlist panel              # full 3-phase interactive panel
backlist panel --overview   # phase 1 only (system base report)
backlist panel --no-menu    # phases 1-2, then keep services running (CI/scripting)
```

---

## ⚙️ Configuration (`.backlist.yml`)

The tool is fully configurable through a **unified config file** — no scattered settings.

| Source | Location | Priority |
| --- | --- | --- |
| CLI flags | `backlist auto --stack=nestjs` | 🔺 highest |
| Project config | `.backlist.yml` (searched from cwd upward) | medium |
| Global config | `~/.backlist.yml` | low |
| Built-in defaults | — | lowest |

```bash
backlist config          # show the effective merged configuration
backlist config init     # create .backlist.yml in the current project
backlist config path     # show where config files are located
```

Example `.backlist.yml`:

```yaml
project:
  backendDir: api-server        # generated backend folder name
  stack: node-ts-express        # auto | node-ts-express | js-express | nestjs | bun-elysia | …
  port: 9000                    # backend port
  database: sqlite              # sqlite | postgres | mysql | mongodb
  orm: prisma                   # prisma | mongoose
  auth: true
  seeder: true
  features: [docker, testing, swagger]

autopilot:
  install: true                 # auto-install dependencies
  runBackend: true              # start the backend server
  runFrontend: true             # start the frontend dev server
  qa: false                     # false | true | http://url — run QA after boot

qa:
  localUrl: http://localhost:3000

devops:
  kubernetes:
    namespace: default
  cloud:
    provider: aws
    region: us-west-2

ai:
  provider: together            # together | openai | anthropic
```

Everything can also be set via flags (`--stack=`, `--port=`, `--name=`, `--database=`, `--orm=`, `--no-run`, `--no-frontend`, `--no-install`) or environment variables (`BACKLIST_STACK`, `BACKLIST_PORT`). Flags always win.

> Legacy/related configs: `devops.yml` (generated by `backlist devops init` for the DevOps engine), `~/.backlist-config.json` (Pro AI API key), and `.env` (generated backend secrets).

---

## 🧠 Engine 1: AST-Powered Backend Generation (create-backlist)

The generator **Reverse Engineers** your frontend source code using an **Abstract Syntax Tree (AST) engine** — it doesn't just "read" text, it "understands" structure. It deep-scans React/Vue/vanilla code, extracts API intent, and generates a production-ready backend in **18+ stacks**: Node.js (Express/TS), NestJS, Bun+Elysia, Python (FastAPI/Django), Java Spring, Kotlin Ktor, Go (Fiber/Gin), Rust (Actix/Axum), C# (.NET 8), Deno Oak, PHP Laravel, Elixir Phoenix, and more.

```mermaid
graph LR
    subgraph Input [Stage 1: Analysis]
        A["Frontend Files"] -->|AST Parsing| B("Scanner Engine")
    end
    subgraph Core [Stage 2: Abstraction]
        B -->|Extracts Endpoints| C{"Intermediate JSON Bridge"}
    end
    subgraph Output [Stage 3: Generation]
        C -->|Transpiles| D["Node.js (Express)"]
        C -->|Transpiles| E["Python (FastAPI)"]
        C -->|Transpiles| F["Java (Spring Boot)"]
        C -->|Transpiles| G["C# (.NET Core)"]
    end
    style C fill:#ff9900,stroke:#333,stroke-width:2px,color:white
```

1. **Stage 1 (Analysis):** scans source files (prioritizing active editor context) to build an AST.
2. **Stage 2 (Abstraction):** extracted logic converts to a universal **JSON IR** — a language-agnostic "bridge".
3. **Stage 3 (Generation):** language-specific compilers write production-ready code (controllers, routes, models, Prisma schemas, Swagger, Dockerfile, docker-compose).

It also auto-generates: database schemas, JWT auth, API contracts (OpenAPI/Swagger), unit/API/E2E tests, and CI/CD workflows.

---

## 🧪 Engine 2: Real-Browser QA (backlist-qa)

Enterprise QA driven by **Playwright real browsers** — zero fake data:

- **Auto scan** — crawls routes, discovers APIs, tests real interactions
- **Security** — XSS/CSRF headers, secrets exposure, auth flows
- **Performance** — bundle, runtime, network-waterfall analysis
- **Accessibility** — axe-core WCAG checks
- **SEO & API** — metadata, sitemap, endpoint contracts
- **Continuous mode** — re-runs every 60s (watch/CI)
- **HTML + JSON reports** with AI-classified bug severity

```bash
backlist qa auto --url=http://localhost:3000          # full suite
backlist qa scan --url=http://localhost:3000          # quick scan
backlist qa manual                                    # pick scan types
backlist qa history                                   # past runs
backlist qa post-gen                                  # validate a generated backend
```

---

## 🛠️ Engine 3: DevOps Command Center

| Capability | Commands | Underlying tools |
| --- | --- | --- |
| **Docker** | `backlist docker build/up/down/ps/logs/clean` | docker, docker compose |
| **Kubernetes** | `backlist k8s deploy/rollback/scale/status/logs/top` | kubectl |
| **Helm** | `backlist helm create/install/upgrade/list/package/template` | helm |
| **Terraform** | `backlist tf init/plan/apply/destroy` | terraform |
| **CI/CD** | `backlist ci init/run/deploy/status` | GitHub Actions, GitLab CI |
| **Multi-Cloud** | `backlist cloud status/login/aws/azure/gcp/eks/aks/gke` | aws, az, gcloud, eksctl |
| **Monitoring** | `backlist monitor init/up/down/status/logs` | Prometheus + Grafana |

One command scaffolds the entire DevOps footprint for a project:

```bash
backlist devops init
# → devops.yml · Dockerfile · docker-compose.yml · kubernetes/base/*
# → charts/ · terraform/main.tf · .github/workflows/deploy.yml
```

### Multi-Cloud

```bash
backlist cloud status                          # CLIs + identities + k8s context
backlist cloud login aws                       # aws sso login
backlist cloud eks myapp-cluster               # create AWS EKS cluster
backlist cloud aks myapp-cluster               # create Azure AKS cluster
backlist cloud gke myapp-cluster               # create Google GKE cluster
```

### Monitoring

```bash
backlist monitor up        # Prometheus :9090 · Grafana :3001 · node-exporter · cAdvisor
backlist monitor status    # container health + scrape targets
backlist monitor logs      # stream observability logs
```

---

## 🔧 Architecture

```
┌───────────────────────────────────────────────────────────────┐
│                     backlist (one binary)                     │
├───────────────────────────────────────────────────────────────┤
│  gen (create-backlist) │ qa (Playwright) │ devops engine      │
├───────────────────────────────────────────────────────────────┤
│  docker │ k8s │ helm │ terraform │ ci │ cloud │ monitor       │
├───────────────────────────────────────────────────────────────┤
│  Cross-platform runner (Node ≥ 18) · Go binary when available │
└───────────────────────────────────────────────────────────────┘
```

- **Cross-platform by default:** built-in Node.js engine works on Windows/macOS/Linux with no native dependencies.
- **Native acceleration:** if the compiled Go DevOps binary is present (`bin/devops`), it is used automatically — no action needed.
- **Graceful degradation:** missing tools (kubectl, terraform, cloud CLIs…) are detected by `backlist doctor` and never block the rest of the workflow.

---

## 📦 Installation & Usage

```bash
# Global install (recommended)
npm install -g create-backlist

# The four binaries provided
backlist         # the All-in-One CLI
devops           # DevOps engine directly
create-backlist  # backend generator directly
backlist-qa      # QA engine directly

# Or via npx (no install)
npx create-backlist@latest
```

Requires **Node.js ≥ 18**. Optional tools (auto-detected): Docker, kubectl, helm, terraform, gh, aws/az/gcloud.

---

## 🗺️ Roadmap

- [x] **Phase 1: Core Engine** — AST parsing & Node.js support
- [x] **Phase 2: Polyglot Architecture** — Python, Java, C#, Go, Rust + Docker
- [x] **Phase 3: All-in-One Integration** — QA + DevOps (K8s/Helm/Terraform/CI/CD/Cloud/Monitor) in one CLI
- [ ] **Phase 4: Intelligent Data Modeling** — auto-generate Prisma/TypeORM schemas from request bodies
- [ ] **Phase 5: Security Automation** — auto-generate JWT auth and security headers
- [ ] **Phase 6: Team Edition** — shared config, org-wide pipelines, SLO dashboards

---

## 🤝 Contributing & Feedback

Open-source and built for the developer community!

* Found a bug? [Open an Issue](https://github.com/WAH-ISHAN/create-backlist/issues).
* Want to contribute? [Submit a Pull Request](https://github.com/WAH-ISHAN/create-backlist/pulls).
* Standalone modules: [devops/](devops/) (Go engine) · [backlist-devops/](backlist-devops/) (Node engine + unified CLI)

Give us a ⭐ on GitHub if this saved you time!

---

*Built with ❤️ for builders by [W.A.H. ISHAN](https://github.com/WAH-ISHAN).*