Metadata-Version: 2.4
Name: forge-dev-cli
Version: 1.0.5
Summary: Pip-installable wrapper for the DevForge Node.js CLI
Author: DevForge
License: MIT
Project-URL: Homepage, https://github.com/example/devforge
Keywords: cli,devforge,orchestrator
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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)

```bash
npm install
npm link
```

Then use globally as:

```bash
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`.

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

Install from PyPI:

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

Install from TestPyPI:

```bash
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):

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

Install directly from Git on another machine:

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

Then run:

```bash
forge --help
```

## Validate

```bash
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:

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

Safe preview mode:

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

Details and variants: [docs/ubuntu-workstation.md](docs/ubuntu-workstation.md)
Architecture gate policy: [docs/architecture-policy.md](docs/architecture-policy.md)

Release integrity helper:

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

Team onboarding wrapper:

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

## CI Example

```bash
# 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:

```bash
forge analyze-reset
forge analyze --json
```

GitHub Actions workflow included: [/.github/workflows/devforge-ci.yml](.github/workflows/devforge-ci.yml)

## PyPI Release Automation

Automated publish workflow: [/.github/workflows/pypi-release.yml](.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:

```bash
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:

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

## Commands

Show all commands with descriptions + examples:

```bash
forge help-all
```

### Initialize project

```bash
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)

```bash
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

```bash
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

```bash
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

```bash
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)

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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)

```bash
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

```bash
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:

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

## Example flow

```bash
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](ROADMAP_PHASE2.md)
- Includes: command specs, acceptance criteria, technical foundation, and 4-week delivery sequence.
