create-projx 1.1.2 → 1.3.0

package/README.md

@@ -1,5 +1,9 @@
 # Projx
 
+[![npm version](https://img.shields.io/npm/v/create-projx)](https://www.npmjs.com/package/create-projx)
+[![CI](https://github.com/ukanhaupa/projx/actions/workflows/ci.yml/badge.svg)](https://github.com/ukanhaupa/projx/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
 Production-grade project scaffolder. Pick your stack, get a fully wired project with auth, database, CI/CD, and E2E tests — ready to deploy.
 
 ## The Problem
@@ -54,32 +58,58 @@ Interactive prompt lets you pick components. Or specify them directly:
 npx create-projx my-app --components fastapi,fastify,frontend,mobile,e2e,infra
 ```
 
-### Add Components Later
+### Adopt an Existing Project
+
+Already have a project? Initialize projx to get the scaffolding (CI, hooks, docker-compose) without overwriting your code:
+
+```bash
+cd my-existing-app
+npx create-projx init
+```
+
+Auto-detects components by scanning for `fastapi` in pyproject.toml, `react`/`fastify` in package.json, `flutter` in pubspec.yaml, and `.tf` files. Confirms each mapping, creates a `projx/baseline` branch with the template, and merges it — preserving all your existing code while establishing the ancestry link that makes future updates work.
 
-Already have a project? Add more components anytime:
+### Add Components Later
 
 ```bash
 cd my-app
 npx create-projx add frontend mobile
 ```
 
-This copies the new component directories, regenerates shared files (docker-compose, CI, pre-commit hooks) to include them, and installs dependencies.
+Copies the new component directories, regenerates shared files (docker-compose, CI, pre-commit hooks) to include them, and installs dependencies.
 
 ### Update Scaffolding
 
-When we improve templates, update your project's scaffolding without touching your code:
+When templates improve, update your project:
 
 ```bash
 cd my-app
 npx create-projx@latest update
 ```
 
-This updates template files (base models, middleware, configs, Dockerfiles, CI) tracked in `.projx` manifest. Files you created (new entities, pages, features) are never touched.
+Uses a `projx/baseline` branch that tracks the raw template state. When you update, the baseline advances to the new template version and merges into your branch using git's three-way merge:
+
+- **Files only the template changed** — auto-merged, no action needed
+- **Files only you changed** — preserved, untouched
+- **Files both sides changed** — git conflict, you resolve
+
+```bash
+# If conflicts occur:
+git status                    # see conflicted files
+# resolve conflicts in your editor
+git add . && git commit       # finish the merge
+
+# Or abort:
+git merge --abort
+```
+
+Your custom files (controllers, pages, middleware) are never deleted. Files you created that don't exist in the template are always preserved.
 
 ## Options
 
 ```
 npx create-projx <name> [options]
+npx create-projx init
 npx create-projx add <components...>
 npx create-projx update
 
@@ -90,19 +120,34 @@ npx create-projx update
 -h, --help             Show help
 ```
 
+## Rename Component Directories
+
+Rename `fastapi/` to `backend/`? Just rename the folder — the `.projx-component` marker file moves with it. The `update` command auto-discovers where each component lives by scanning for these markers. No config changes needed.
+
+```
+backend/.projx-component  →  { "components": ["fastapi"] }
+web/.projx-component      →  { "components": ["frontend"] }
+```
+
+CI, setup.sh, pre-commit hooks, and docker-compose are all regenerated with your custom directory names.
+
 ## What a Scaffolded Project Looks Like
 
 ```
 my-app/
-├── fastapi/              # Auto-entity CRUD backend
-├── frontend/             # Auto-entity UI from /_meta
-├── e2e/                  # Playwright E2E tests
-├── docker-compose.yml    # Production (backend + frontend + SSL)
-├── docker-compose.dev.yml # Development (PostgreSQL + hot reload)
-├── .github/workflows/    # CI per component
-├── .githooks/pre-commit  # Format + lint on commit
-├── setup.sh              # Install all deps
-└── .projx                # Manifest (tracks template files for updates)
+├── fastapi/                # Auto-entity CRUD backend
+│   └── .projx-component    # Identifies this as the fastapi component
+├── frontend/               # Auto-entity UI from /_meta
+│   └── .projx-component
+├── e2e/                    # Playwright E2E tests
+│   └── .projx-component
+├── docker-compose.yml      # Production (backend + frontend + SSL)
+├── docker-compose.dev.yml  # Development (PostgreSQL + hot reload)
+├── .github/workflows/      # CI per component (runs only on changes)
+├── .githooks/pre-commit    # Format + lint on commit
+├── .vscode/                # Editor settings + recommended extensions
+├── setup.sh                # Install all deps
+└── .projx                  # Components list + version
 ```
 
 Only the components you selected appear. Shared files (docker-compose, CI, hooks) are generated to match your selection.
@@ -121,9 +166,10 @@ The core idea: define a data model, get everything else for free.
 
 - JWT auth with Keycloak (pluggable providers)
 - Docker Compose for dev and prod
-- GitHub Actions CI per component
+- GitHub Actions CI per component (path-filtered — only runs when that component changes)
 - Pre-commit hooks (format + lint + typecheck)
 - Secret detection in pre-commit
+- VS Code settings + recommended extensions
 - 80% test coverage enforced
 - Auto-entity discovery across all stacks
 
@@ -139,6 +185,20 @@ cd projx
 
 The CLI lives in `cli/`. Templates are the root-level component directories (`fastapi/`, `frontend/`, etc.).
 
+```bash
+cd cli
+npm test        # run tests
+npm run build   # build CLI
+```
+
+## Badge
+
+Add this to your project's README:
+
+```md
+[![Built with Projx](https://img.shields.io/badge/Built%20with-Projx-blue)](https://github.com/ukanhaupa/projx)
+```
+
 ## License
 
 MIT