forge-dev-cli 1.0.5

Pip-installable wrapper for the DevForge Node.js CLI

DevForge

DevForge is an AI-powered full-stack project orchestrator CLI.

Release Notes

v1.0.0 (Stable Release)

• Promoted DevForge CLI to stable release with tested core command surface
• Added complete safe-change workflow (--dry-run, diff, journaled history, rollback)
• Added architecture/quality guardrails (analyze --compare --fail-on-regression, guard, fix-errors --verify --strict)
• Added Phase 3 refactor workflow (refactor move, extract-service, --verify --strict)
• Added Ubuntu automation (bootstrap + one-command installer) and CI gates
• Added pip/pipx distribution wrapper with runtime bootstrap and automatic Node/npm provisioning on first run

v0.2.0 (Phase 2 Complete)

• Added architecture-aware analysis with health scoring, trend snapshots, comparison, and regression gating
• Added safe dry-run + diff flow for feature generation
• Added operation journal, history, and rollback workflows
• Added quality automation commands (guard, fix-errors, fix-errors --verify, fix-errors --strict)
• Added analyze snapshot lifecycle commands (analyze-history, analyze-reset)
• Added Ubuntu workstation bootstrap path and GitHub Actions CI workflow

v0.3.0 (Phase 3 MVP Start)

• Added forge refactor command for safe module moves with automatic import rewrites
• Added dry-run + JSON support for refactor workflow
• Added rollback-compatible journaling for refactor operations

MVP Scope Implemented

• React + Express opinionated initialization flow
• Feature-level CRUD scaffolding across backend + frontend
• Basic architecture analyzer (unused files, circular imports, fat controllers)
• Environment/project diagnostics (forge doctor)
• Read-only feature planning (forge plan <feature>)
• Dry-run diff preview (forge add feature <name> --dry-run + forge diff --dry-run)
• Operation journal with history and rollback (forge history, forge rollback <operation-id>)
• Guard command for configured lint/test/build checks (forge guard)
• Safe auto-fix command for configured lint/format tasks (forge fix-errors)
• Repository bootstrap (clone + setup) automation

Install

npm (default)

npm install
npm link

Then use globally as:

forge --help

pip / pipx (Ubuntu-friendly wrapper)

DevForge is a Node CLI. The published Python package name is forge-dev-cli and it installs a forge command. The pip package is a thin Python wrapper that bootstraps and runs the bundled Node runtime.

If node/npm are missing, the wrapper attempts automatic installation on first run:

• Ubuntu/Debian: apt-get install nodejs npm (uses sudo when needed)
• macOS: brew install node
• Windows: winget install OpenJS.NodeJS.LTS

If automatic install is unavailable on your platform, install Node.js manually and rerun forge.

# inside this repo
python3 -m pip install .
# or isolated tool install
pipx install .

Install from PyPI:

python3 -m pip install --upgrade forge-dev-cli
# or
pipx install forge-dev-cli

Install from TestPyPI:

python3 -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple forge-dev-cli

One-command Ubuntu installer (checks/installs node, npm, pipx, then installs DevForge):

chmod +x scripts/install-devforge-ubuntu.sh
./scripts/install-devforge-ubuntu.sh --yes

Install directly from Git on another machine:

./scripts/install-devforge-ubuntu.sh --source git+https://github.com/<your-org>/<your-repo>.git --yes

Then run:

forge --help

Validate

npm test

Current test coverage includes Phase 2 integration flows:

• doctor/plan/dry-run/diff/add/history/rollback/guard
• setup-repo local mode journaling + rollback

Ubuntu Workstation Bootstrap

If you want a developer-focused Ubuntu setup before building a full ISO, use the bootstrap path:

cd bootstrap/ubuntu
chmod +x bootstrap.sh
./bootstrap.sh --with-node --with-docker --with-vscode --yes

Safe preview mode:

./bootstrap/ubuntu/bootstrap.sh --dry-run --profile fullstack --with-node --with-docker --with-vscode

Details and variants: docs/ubuntu-workstation.md Architecture gate policy: docs/architecture-policy.md

Release integrity helper:

cd bootstrap/ubuntu
chmod +x generate-checksums.sh
./generate-checksums.sh

Team onboarding wrapper:

chmod +x scripts/onboard-ubuntu.sh
./scripts/onboard-ubuntu.sh -- --profile fullstack --with-node --with-docker --yes

CI Example

# 1) Apply safe autofixes and ensure quick checks still pass
forge fix-errors --json --verify --strict

# 2) Run architecture gate against previous baseline snapshot
forge analyze --json --compare --fail-on-regression

# 3) Run project quality checks
forge guard --quick

Recommended first-run baseline:

forge analyze-reset
forge analyze --json

GitHub Actions workflow included: /.github/workflows/devforge-ci.yml

PyPI Release Automation

Automated publish workflow: /.github/workflows/pypi-release.yml

Tag conventions:

• v1.0.0-rc1 → publishes to TestPyPI
• v1.0.0 → publishes to PyPI

Required GitHub repository secrets:

• Not required when using Trusted Publishing (recommended)

One-time setup in PyPI/TestPyPI:

• Open the Trusted Publisher link shown in failed workflow logs
• Approve repository DaksheshGautam/devforge and workflow file pypi-release.yml

Example tag commands:

git tag v1.0.1-rc1
git push origin v1.0.1-rc1

git tag v1.0.1
git push origin v1.0.1

Install verification commands:

python3 -m pip install --upgrade forge-dev-cli
forge --version
forge --help

Commands

Show all commands with descriptions + examples:

forge help-all

Initialize project

forge init fullstack

Prompts:

• Frontend: react | next
• Backend: express | fastapi
• DB: postgresql | mongodb
• Auth: jwt | session

MVP currently scaffolds React + Express while recording your selected options.

Add feature (multi-layer scaffold)

cd <your-project-root>
forge add feature user-profile
forge add feature payments --dry-run

Generates:

• Backend model
• Backend migration SQL scaffold
• Backend validator
• Backend controller
• Backend route + routes index update
• Frontend API module
• Frontend page with loading + error UI
• Basic test placeholder

Dry-run mode:

• forge add feature <name> --dry-run stages proposed changes in .forge/cache/dry-run/latest.json
• forge diff --dry-run prints unified diff preview
• Dry-run does not write generated feature files to the project

Analyze project

cd <your-project-root>
forge analyze
forge analyze --json
forge analyze --json --no-snapshot
forge analyze --json --compare
forge analyze --json --compare --fail-on-regression

Checks:

• Unused files (reachable from frontend/backend entrypoints)
• Circular imports
• Fat controllers (line/function threshold)
• Unresolved relative imports
• High fan-out modules (coupling hotspots)
• Large files (maintainability hotspots)

Output:

• Health score (0-100) and health band (excellent|good|fair|poor)
• Module scores (frontend, backend, shared) with per-area health
• Severity-ranked findings (critical|warning|info)
• Prioritized remediation suggestions
• Trend metadata from persisted snapshots in .forge/analyze-history.json (last 50 runs)
• Optional comparison (--compare) against previous snapshot with overall/module deltas
• CI gate (--fail-on-regression) fails command when health score drops or critical findings increase

Analyze snapshot history

forge analyze-history
forge analyze-history --limit 20 --json
forge analyze-reset
forge analyze-reset --json

Behavior:

• analyze-history reads persisted snapshots from .forge/analyze-history.json
• analyze-reset clears saved snapshot history for a fresh baseline

Diagnose local/project readiness

forge doctor
forge doctor --json

Checks:

• Runtime tools (git, node, npm, python, docker when Docker files are detected)
• Required project files (forge.config.json, .env or .env.example)
• Dependency hints (lockfile presence, node_modules, local virtualenv hint)
• Port conflict check from .env (PORT)

Behavior:

• Returns exit code 0 when no critical checks fail
• Returns non-zero when at least one critical check fails

Generate implementation plan (no writes)

forge plan user-profile
forge plan payments --json

Behavior:

• Scans current project structure and detected stack
• Produces multi-layer steps (DB, backend, frontend, tests)
• Outputs deterministic JSON keys in machine mode: steps, files, risks
• Never modifies workspace files in plan mode

Preview staged dry-run diff

forge diff --dry-run

Behavior:

• Reads the latest staged dry-run changes
• Prints deterministic unified diff by file
• Shows add/update/delete summary counts

Operation history and rollback

forge history
forge history --limit 10 --json
forge rollback op_20260302_001

Behavior:

• Stores operation metadata in .forge/operations
• Keeps snapshots for rollback in .forge/snapshots
• Supports rolling back tracked file changes from an operation id

Quality gate

forge guard
forge guard --quick
forge guard --json

Behavior:

• Detects configured checks and only runs available ones
• JS/TS projects: lint, test, build, typecheck (or quick subset)
• Python projects: configured lint/test/typecheck checks when detectable
• Exits non-zero when any executed check fails

Auto-fix configured issues

forge fix-errors
forge fix-errors --json
forge fix-errors --json --verify
forge fix-errors --json --strict

Behavior:

• Runs only configured safe auto-fix tasks it can detect
• Node: known fix scripts like lint:fix, fix:lint, format, prettier:fix, eslint:fix
• Python: ruff --fix and black when configured in pyproject.toml
• Optional verify mode (--verify) runs quick quality checks after fixes
• Optional strict mode (--strict) fails when no safe fix tasks are detected
• Exits non-zero when any executed fix task fails

Refactor module (Phase 3 MVP)

forge refactor backend/src/lib/util.js --to backend/src/shared/util.js --dry-run
forge diff --dry-run
forge refactor backend/src/lib/util.js --to backend/src/shared/util.js --json
forge refactor backend/src/lib/util.js --to backend/src/shared/util.js --verify --json
forge refactor backend/src/lib/util.js --to backend/src/shared/util.js --verify --strict --json
forge refactor backend/src/controllers/account.controller.js --action extract-service --json

Behavior:

• Moves a source module to a target path
• Rewrites relative imports across project files to the new location
• extract-service action scaffolds a service module from controller exports and wires controller service calls
• Supports dry-run staging and unified diff previews
• Optional --verify runs quick guard checks and analyze regression comparison after refactor
• Optional --strict fails the command when verification detects guard failures or analyze regressions
• Records an operation for rollback with forge rollback <operation-id>

Copy/clone and setup a repo

forge setup-repo <repo-url> [target-dir]

Options:

• --skip-install: skip dependency installation and only clone + env bootstrap.
• --no-clone: treat first argument as an existing local repository path.

Behavior:

• Clones the repository
• Detects project roots via package.json, requirements.txt, pyproject.toml, Pipfile
• Installs dependencies (npm/pnpm/yarn/pip/pipenv based on manifest/lockfiles)
• Copies .env.example or .env.sample to .env when missing
• Writes FORGE_SETUP_REPORT.md in the cloned repo root
• Records Forge-managed file mutations in operation journal (.env bootstrap + setup report)

Local repo mode:

forge setup-repo ../already-cloned-repo --no-clone

Example flow

forge init fullstack
cd project
forge add feature auth
forge add feature dashboard
forge plan payments
forge add feature invoices --dry-run
forge diff --dry-run
forge analyze
forge doctor
forge guard --quick
forge fix-errors
forge history
forge setup-repo https://github.com/example/team-repo.git
forge setup-repo ../team-repo --no-clone

Phase 2 Roadmap

• Detailed implementation plan: ROADMAP_PHASE2.md
• Includes: command specs, acceptance criteria, technical foundation, and 4-week delivery sequence.