Metadata-Version: 2.4
Name: devforge-scaffold
Version: 0.1.0
Summary: Generate opinionated starter projects for Flutter, Django and Next.js.
Author-email: Dhinesh <dhinesh.tech2001@gmail.com>
License: MIT
Keywords: cli,scaffolding,starter,flutter,django,nextjs
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# DevForge

A CLI tool that generates opinionated starter projects for **Flutter**, **Django** and **Next.js**.

Built with [Typer](https://typer.tiangolo.com/) (CLI framework) and [Rich](https://rich.readthedocs.io/) (terminal UI).

> **Status:** all three generators — Flutter, Django and Next.js — are fully working.

## Usage

```bash
devforge version                # version + runtime info (also: devforge --version / -V)
devforge doctor                 # check required tooling and templates
devforge flutter my_app         # scaffold a Flutter project
devforge django my_site         # scaffold a Django project
devforge next my-web            # scaffold a Next.js project
devforge --help                 # help for the app or any command (-h works too)
devforge -v <command>           # enable debug logging
```

### `devforge flutter`

```bash
devforge flutter my_app \
  --org com.mycompany \          # Android/iOS bundle-id organisation (reverse-DNS)
  --app-name "My App" \          # display name (default: project name title-cased)
  --description "..." \          # pubspec description
  --api-url https://api.my.dev \ # baked into lib/core/constants/api_routes.dart
  -o ~/projects                  # parent directory (default: current directory)
```

What it does: checks the Flutter SDK → runs `flutter create` (correct platform folders
for your `--org`) → replaces `lib/`, `assets/`, `test/`, `pubspec.yaml` and
`analysis_options.yaml` with the DevForge template and substitutes its tokens → sets the
app display name across android/ios/macos/web → adds the `INTERNET` permission to the
main Android manifest (release builds need it for networking) → `flutter pub get` →
regenerates branded launcher icons and splash screens from `assets/images/logo.png`
(`flutter_launcher_icons` / `flutter_native_splash`) → `git init` + initial commit.
The generated project is `flutter analyze`-clean.

The template intentionally has **no `android/`/`ios/` folders** — platform folders
always come fresh from `flutter create`, so they never drift out of date with new
Flutter releases. See `templates/flutter_starter/TEMPLATE_REPORT.md`.

### `devforge django`

```bash
devforge django my_site \
  --app-name "My Site" \            # display name (default: project name title-cased)
  --description "..." \             # README + API docs description
  --domain my-site.com \            # production domain (ALLOWED_HOSTS examples)
  --author "Name" --email a@b.com \ # defaults: git config user.name / user.email
  --organization "Acme" \           # copyright holder (default: author)
  -o ~/projects                     # parent directory (default: current directory)
```

What it does: copies the `django_starter` template (Django 4.2 + Django Ninja + JWT,
Docker/Postgres ready, SQLite fallback for local dev) → renames the `{{PROJECT_SLUG}}/`
settings package → substitutes all tokens including a freshly generated `SECRET_KEY` →
creates `.venv` and installs `requirements.txt` → runs migrations → `git init` +
initial commit. The result passes `manage.py check` and its own test suite, and serves
API docs at `/api/v1/docs`.

### `devforge next`

```bash
devforge next my-web \
  --auth / --no-auth \               # auth module (login/signup, cookie-JWT, axios refresh queue)
  --multi-tenant / --no-multi-tenant # subdomain-per-tenant routing (proxy + [tenant] segment)
  --app-name "My Web" --domain my-web.com \
  --api-url http://127.0.0.1:8000/api/v1 \
  --cookie-prefix mw \               # default: project name initials
  --skip-install \                   # skip npm install
  -o ~/projects
```

Both features default to **no**. If the flags are omitted on a terminal, DevForge asks
two yes/no questions interactively; in scripts (no TTY) it silently uses the defaults.

What it does: copies the template per its `template.json` manifest → applies the
feature selection (disabled features have files removed and variant overlays applied,
so e.g. disabling multi-tenant relocates `app/[tenant]/dashboard` → `app/dashboard`) →
substitutes tokens → `npm install` → `git init`. All four feature combinations
produce a project that passes `npm run build`.

## Configuration

Settings resolve in precedence order: environment variables → `./devforge.json` →
`~/.config/devforge/config.json` → defaults.

| Setting | Env var | Config key | Default |
|---|---|---|---|
| Template root | `DEVFORGE_TEMPLATE_ROOT` | `template_root` | `devforge/templates/` inside the package |
| Log level | `DEVFORGE_LOG_LEVEL` | `log_level` | `WARNING` |

## Installation

Full step-by-step guide (all platforms, updating, troubleshooting):
**[docs/installation.md](docs/installation.md)**. The short version:

**With Python 3.9+** (Windows / macOS / Linux):

```bash
pipx install devforge-scaffold   # recommended (isolated); or: pip install devforge-scaffold
devforge --version
```

**Without Python** — download the standalone binary for your OS from
[GitHub Releases](https://github.com/dhineshio/DevForge/releases)
(`devforge-macos-arm64`, `devforge-windows-x86_64.exe`), put it on your `PATH` and run
it. macOS will quarantine an unsigned download: `xattr -d com.apple.quarantine devforge-macos-arm64`.

> The PyPI distribution is named `devforge-scaffold` (plain `devforge` was taken), but
> the installed command is `devforge` either way.

**For development:**

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

## Releasing

1. Bump `version` in `pyproject.toml` (and `src/devforge/__init__.py`).
2. `git tag v0.x.y && git push origin v0.x.y`
3. GitHub Actions (`.github/workflows/release.yml`) runs the tests, builds the
   macOS/Windows binaries with PyInstaller (`packaging/build_binary.py`), attaches them
   to a GitHub Release, and publishes the wheel to PyPI.

One-time setup for PyPI publishing: create the `devforge-scaffold` project as a
[trusted publisher](https://docs.pypi.org/trusted-publishers/) on pypi.org pointing at
this repo's `release.yml` workflow (environment `pypi`) — no token secrets required.

## Project layout

```
DevForge/
├── pyproject.toml          # packaging, dependencies, `devforge` entry point
├── src/devforge/           # the CLI package (src layout)
│   ├── templates/          # starter templates, shipped as package data
│   │   ├── flutter_starter/  # complete — see its TEMPLATE_REPORT.md
│   │   ├── django_starter/   # complete
│   │   └── nextjs_starter/   # placeholder, to be added
│   ├── cli.py              # Typer app assembly — registers commands, no logic
│   ├── commands/           # one module per CLI command (new, list, doctor)
│   ├── core/               # config, constants, exception hierarchy
│   ├── generators/         # one generator per framework + base interface + registry
│   ├── services/           # shared engines: template substitution, file ops, validation
│   ├── ui/                 # Rich rendering — the only package that imports rich
│   └── utils/              # small dependency-free helpers
├── tests/
│   ├── unit/               # per-module tests mirroring src/devforge
│   └── integration/        # end-to-end `devforge new` runs against real templates
└── docs/
    └── architecture.md     # detailed folder purposes and SOLID mapping
```

See [docs/architecture.md](docs/architecture.md) for what each folder is for and why.
