⚒ Boltforge

A CLI that scaffolds a production-ready Node.js / Express / MongoDB backend — then keeps generating fully-wired features, one command at a time.

Boltforge is a code generator, not a framework. It writes real Express + Mongoose JavaScript to disk — files you own and edit like any hand-written project — and then keeps adding complete, consistent features on demand. There is no runtime dependency on Boltforge: uninstall the CLI and your project still runs, tests, and deploys exactly the same.

📖 Read the full documentation →

Features

• Generic generator engine — every generator is discovered from disk at startup. Adding one is a new folder, not a CLI edit.
• Nothing unused — choose OTP and no password code is generated at all; skip sockets and no socket server exists anywhere.
• Never rewrites your files — routes and permissions are discovered at startup, so no generator edits a shared file to "register" anything.
• All-or-nothing writes — files are staged in a temp directory and committed with one atomic move. A failed generation leaves nothing behind.
• Two auth strategies — password or passwordless OTP, over email, phone, or both.
• Roles + fine-grained permissions — with a single AccessResolver that decides every access question.
• Feature-first admin area — extensible via boltforge-cli generate admin <name>.
• Batteries included — FCM notifications, Socket.io via a domain event bus, Swagger, Jest + in-memory MongoDB, structured errors, security middleware.

Installation

npm install -g boltforge-cli

Requires Node.js 18 or newer. Verify with boltforge-cli version.

Quick Start

boltforge-cli create my-api          # answer six prompts
cd my-api
npm install
cp .env.example .env           # then set MONGO_URI and JWT_ACCESS_SECRET
npm run dev

Add your first feature — it's live at /offers on the next restart, with no file edited to register it:

boltforge-cli generate offer

CLI examples

# non-interactive, for CI
boltforge-cli create my-api --auth otp --identifier email --db mongodb --pm npm --yes

# generate a whole feature (shortcut for: generate feature offer)
boltforge-cli generate offer

# generate one file
boltforge-cli generate controller users

# full CRUD
boltforge-cli generate crud product

# an admin sub-feature, permission-guarded, at /admin/reports
boltforge-cli generate admin reports

# optional add-ons, any time
boltforge-cli add socket
boltforge-cli add swagger

# preview without writing anything
boltforge-cli generate crud invoice --dry-run

# health check (non-zero exit on errors)
boltforge-cli doctor

| Command | Purpose | |---|---| | boltforge-cli create <project-name> | Scaffold a new base project | | boltforge-cli generate <name> | Generate a full feature (shortcut) | | boltforge-cli generate <type> <name> | Generate a specific type | | boltforge-cli add <addon> | Add socket or swagger | | boltforge-cli doctor [--repair] | Diagnose the current project | | boltforge-cli version | Print the installed version | | boltforge-cli help [command] | Show help |

Generator types: feature, crud, admin, controller, service, model, validator, middleware

Common flags: --auth --identifier --db --notifications --socket --swagger --pm --dry-run --yes --force --no-model --no-tests --repair

Architecture overview

Four pieces drive every command:

| Piece | Role | |---|---| | Registry | Scans src/generators/* at startup; registers anything exporting a type and a plan() | | Template engine | Handlebars, deliberately logic-less — decisions are resolved in the generator, not the template | | File plan | plan() is pure: returns { targetPath, content }[] and performs no I/O | | File writer | Detects conflicts, stages every file, commits with one atomic move |

Blueprints (feature, crud, admin) compose existing generators rather than duplicating file-writing logic, so a whole feature commits as a single unit — there is never a state where the controller landed but the model did not.

validate → plan → conflict detection → [--dry-run stops here]
   → write to temp staging          # project untouched so far
   → atomic move                    # ← the single commit point
   → update boltforge.config.json → install deps → format → lint

Generated project structure

my-api/
├── src/
│   ├── config/            # env validation (fail-fast), database, firebase
│   ├── constants/         # roles, permissions (self-assembling catalog), http status
│   ├── authorization/     # access-resolver.js — the one place roles+permissions combine
│   ├── middlewares/       # auth, authorize, validate, rate-limit, error
│   ├── errors/            # AppError hierarchy + classify-error.js
│   ├── delivery/          # email/sms providers behind VerificationService
│   ├── modules/           # feature-first
│   │   ├── auth/          # + tokens/ (OneTimeTokenStore, RefreshTokenStore)
│   │   ├── user/
│   │   ├── admin/         # admins/, users/, + generated admin features
│   │   ├── notification/  # --notifications only
│   │   └── offer/         # ← boltforge-cli generate offer
│   ├── sockets/           # --socket only
│   ├── docs/              # --swagger only
│   ├── routes/            # recursive discovery loader — never hand-edited
│   ├── app.js
│   └── server.js
├── tests/{unit,integration,e2e}/
├── boltforge.config.json    # CLI state only — never runtime config, never secrets
├── postman/<project>.postman_collection.json   # auto-synced, never hand-edit
├── .env / .env.example
└── package.json

Documentation

Full documentation — installation, every command and flag, authentication flows, roles and permissions, the generator engine, an interactive project explorer, troubleshooting and FAQ — lives in docs/index.html and is published at:

https://\alihossainhabib.github.io/boltforge-cli/

It is a single static page: no build step, no backend, no external requests. Open docs/index.html directly in a browser to read it offline.

Testing

Boltforge's own test suite runs with plain Node — no test framework required:

node test/auth-template-extensions.test.js

Generated projects ship a Jest harness backed by mongodb-memory-server, so tests need no running database:

cd my-api
npm test
npm run test:watch

Contributing

Contributions are welcome. The most valuable contribution is usually a new generator, and the architecture is designed to make that a single file:

// src/generators/<type>/generator.js
module.exports = {
  type: 'repository',
  describe: 'Generates a repository layer for a feature',
  plan(name, options, ctx) {
    return [{ targetPath, content }];   // pure — no I/O
  }
};

Drop the folder in and the registry discovers it at startup. No CLI file, argument parser, or command needs editing.

Guidelines:

1. Keep plan() pure — all I/O belongs to the file writer.
2. Resolve decisions in the generator; keep templates logic-less.
3. Never edit a shared file to register something — prefer discovery.
4. Run the syntax sweep and tests before opening a PR.

Releases

See CHANGELOG.md. Maintainers publishing to npm should follow the checklist in PUBLISHING.md — npm publish runs those checks automatically via prepublishOnly.

License

MIT

Author

Created and maintained by Ali Hossain Habib.