@decohere/create 0.0.1-dev.98 → 0.0.1-dev.99

package/README.md

@@ -0,0 +1,253 @@
+# @decohere/create
+
+Scaffold a new Decohere project — built with Forge, served with Flux.
+
+Docker is required on the host. `@decohere/create` only pulls `ghcr.io/typesmiths/decohere/create` and runs `@decohere/scaffold` inside it (including the Auth0 CLI). It does not install the scaffolder libraries on the host.
+
+## Usage
+
+`npm create` already says “create”, so the first token is the kind (`webapi`), not `create` again. The launcher forwards `decohere create webapi …` into the builder image.
+
+This run prompts for database, auth, Postman, and whether to install:
+
+```bash
+npm create @decohere@dev webapi -d my-app
+# or
+npx @decohere/create@dev webapi -d my-app
+# or, once `@decohere/cli` is installed:
+decohere create webapi -d my-app
+```
+
+To skip prompts, pass every answer up front (`-y` means “install deps, don’t ask”):
+
+```bash
+npm create @decohere@dev -- webapi -d my-app --database postgres/typeorm --auth none --postman local -y
+```
+
+Target directory is `webapi`'s optional argument or `-d` (default `.`). `npm create` treats `-d` as its own loglevel flag and forwards `my-app` as a positional — that form is supported. Extra create flags still need `--` after `npm create`.
+
+The first token after the package must be a command (`webapi`); a bare directory name is an unknown command.
+
+The scaffolded Dev Container asks **y/N** (TTY only) before npm auth and optional codebase RAG MCP (semantic search). Decline or run without a TTY to skip. Credentials are written under the project `.cursor/` directory (gitignored).
+
+## Commands
+
+### `webapi`
+
+Scaffolds a full web API using Cortex (DI), Protocol (HTTP), and Scribe (logging), plus a Dev Container workspace.
+
+```bash
+npx @decohere/create webapi -d my-app
+npx @decohere/create webapi -d my-app --name billing
+npx @decohere/create webapi -d my-app --name api --name billing
+```
+
+Generated structure (default `--name api`):
+
+```
+my-app/
+  package.json          # build / start / start:<name> / dev
+  Dockerfile            # first API (PaaS default: docker build .)
+  Dockerfile.billing    # extra APIs: docker build -f Dockerfile.billing .
+  .dockerignore
+  .github/
+    actions/setup-node-pnpm/
+    workflows/
+      ci.yml            # lint ∥ test (+ build on default branch)
+      publish.yml       # forge publish (skips private); no docker push by default
+  tsconfig.json
+  biome.json
+  .env
+  config/
+    config.yaml
+    config.dev.yaml
+  .devcontainer/
+  projects/
+    api/                # or projects/<name> when --name is set
+      package.json      # private: true (app, not an npm package)
+      src/
+        main.ts
+        sample.config.ts
+        sample.service.ts
+        controllers/
+          hello.controller.ts
+```
+
+`Dockerfile.<name>` is only written for extra APIs or a custom `--name` (a single default `api` still uses root `Dockerfile` only).
+
+The app Dev Container is a thin `FROM ghcr.io/typesmiths/decohere/devcontainer:<version>` (pinned to the scaffolder version). Shared layers (bash history, pnpm, `gh`, js-debug bootloader fix) update via `docker pull` / Dev Container rebuild — Compose mounts and lifecycle scripts stay in the app repo. Rebuild with pull after upgrading `@decohere/create`.
+
+#### Scripts
+
+| Script | Command | When |
+|---|---|---|
+| `build` | `forge build --configuration release` | CI, Docker, Nixpacks |
+| `start` | `node dist/release/projects/<first>/es6/src/main.js` | Production default API (`pnpm start` / root Dockerfile) |
+| `start:<name>` | same path for that API | Deploy that API (`pnpm run start:billing`) |
+| `dev` | `flux serve --env-file-if-exists .env` (plus `--project @<app>/<first>` when named) | Local HMR for the first API; loads `.env` if present |
+| `dev:<name>` | `PORT=<3000+n> flux serve --env-file-if-exists .env --project @<app>/<name>` | Local HMR for that API |
+| `lint:check` / `typecheck` / `test` | biome / forge typecheck / vitest | CI |
+
+#### Multiple APIs / add later
+
+```bash
+decohere add api billing
+# empty machine / npm create still maps `webapi add`:
+npx @decohere/create webapi add billing -d my-app
+```
+
+Adds `projects/billing`, `start:billing` / `dev:billing`, and `Dockerfile.billing`. Does not rewrite the first API, root `Dockerfile`, or workspace files like `biome.json`.
+
+Each API is a separate deploy: point a PaaS service at `Dockerfile.<name>` with **repo-root** build context (`docker build -f Dockerfile.billing .`), or set the start command to `pnpm run start:billing`. Workspace `config/` is shared; each API still has its own named datasource and `{PREFIX}_DB_*` env (host/port default to the Compose Postgres).
+
+### `auth0`
+
+The Auth0 CLI lives in the create image. Host tokens are stored in `~/.config/auth0` (always bind-mounted). Use this after a project exists, when a token expires, or when the Postman SPA needs to be created/updated.
+
+```bash
+# Device/URL login — open the printed URL in your browser
+npx @decohere/create auth0 login
+
+# Update the Auth0 API + Postman SPA for this workspace (run from the project, or pass -d)
+npx @decohere/create auth0 configure
+npx @decohere/create auth0 configure -d my-app
+
+# Same commands once `@decohere/cli` is installed:
+decohere auth0 login
+decohere auth0 configure
+```
+
+`configure` does **not** rewrite application source. It scans `projects/*/src` for `@Authorize("action", "Subject")`, adds those permissions to the Auth0 API (keeping any already on the API), assigns them to `AUTH0_ADMIN_USER_SUB` when set, and updates Postman token `scope`.
+
+#### Keep Auth0 in sync with controllers
+
+`@Authorize("read", "Invoice")` becomes Auth0 API permission `read:Invoice`. After adding a controller:
+
+```bash
+npx @decohere/create auth0 configure
+```
+
+Then in Postman, Authorization → Get New Access Token so the token includes the new permissions.
+
+#### Deploy (Railway / Fly / Nixpacks)
+
+Hosts clone git and build themselves — they do **not** receive GitHub Actions `dist/` artifacts.
+
+1. **Dockerfile (preferred):** connect the repo; the host runs `docker build`. The scaffolded Dockerfile compiles with a full `pnpm install` + `pnpm run build`, then installs **production-only** `node_modules` (`pnpm install --prod`) into the runtime image so Forge, TypeScript, Biome, and Vitest are not shipped. `pnpm start` runs the compiled API.
+2. **Nixpacks (no Dockerfile):** same conventional `build` / `start` scripts — install → build → start.
+
+Private `@decohere/*` packages need npm auth during image build (`NODE_AUTH_TOKEN` build-arg or BuildKit secret `npm_token`). Commit `pnpm-lock.yaml` after the first install.
+
+**Registry push (optional):** CI does not run `forge docker --push` by default. For Cloud Run / K8s, add that step to `publish.yml` after configuring GHCR.
+
+**Conventions:** `"private": true` → skip npm publish; presence of a Dockerfile → dockerizable; non-private packages under `projects/` → `forge publish`.
+
+#### Database (`--database`)
+
+| Value | Effect |
+|---|---|
+| `none` | No database |
+| `postgres/typeorm` | One Compose Postgres **instance**; each API owns a named database + `{PREFIX}_DB_*` env |
+
+```bash
+npx @decohere/create webapi -d my-app --database postgres/typeorm
+npx @decohere/create webapi -d my-app --name api --name billing --database postgres/typeorm
+```
+
+`config.yaml` lists one datasource per API (`name: billing` → `withTypeOrm({ name: "billing" })`). Locally they share host `postgres` port `5432`. Point `BILLING_DB_HOST` / `BILLING_DB_PORT` at another server to split later. `webapi add billing --database postgres/typeorm` appends a datasource; TypeORM bootstrap `CREATE DATABASE`s it on first run.
+
+#### Health probes
+
+Scaffolded APIs call `.withHealth()` so these routes are available **without auth**:
+
+| Route | Purpose | Status |
+|---|---|---|
+| `GET /health` | Liveness — process is up | Always `200` `{ "status": "ok" }` |
+| `GET /ready` | Readiness — dependencies OK | `200` when checks pass; `503` when a check fails |
+
+With `--database postgres/typeorm`, readiness runs `SELECT 1` against each TypeORM datasource. Use `/ready` for load balancers and orchestrators.
+
+#### Auth (`--auth`)
+
+| Value | Effect |
+|---|---|
+| `none` | No auth |
+| `auth0` | Auth0 JWT protection; with Postgres also scaffolds a local User profile |
+
+```bash
+npx @decohere/create webapi -d my-app --auth auth0
+```
+
+With Auth0 + Postgres, customize authorization in `projects/<api>/src/auth/ability.factory.ts`:
+override `defineAbilitiesFor` for product CASL rules, and `mapPrincipal` for IdP claim mapping
+(including the `AUTH0_ADMIN_USER_SUB` admin bootstrap). Cortex’s default already maps
+`admin` → `manage`/`all` and `action:Subject` scopes.
+
+#### Postman (`--postman`)
+
+| Value | Effect |
+|---|---|
+| `none` | Skip Postman |
+| `local` | Local View collection + environment under `postman/` |
+| `api` | Create collection/environment in a Postman cloud workspace |
+
+```bash
+npx @decohere/create webapi -d my-app --postman local
+```
+
+## Options
+
+| Option | Scope | Description |
+|---|---|---|
+| `[directory]` / `-d <directory>` | `webapi` / global | Target directory (positional wins; default `.`) |
+| `--name <slug>` | `webapi` | API directory under `projects/` (repeatable; default `api`) |
+| `add api <name>` | `decohere add api` / `npx @decohere/create webapi add` | Add an API to an existing Decohere workspace |
+| `auth0 login` | `decohere auth0` / `npx @decohere/create auth0` | Device/URL login; persist tokens in `~/.config/auth0` |
+| `auth0 configure` | `decohere auth0` / `npx @decohere/create auth0` | Update Auth0 API + Postman SPA for an existing workspace |
+| `--database <provider>` | `webapi` / `add` | `none` \| `postgres/typeorm` |
+| `--auth <provider>` | `webapi` / `add` | `none` \| `auth0` |
+| `--postman <provider>` | `webapi` / `add` | `none` \| `local` \| `api` |
+| `-y, --yes` | `webapi` / `add` | Install dependencies without prompting |
+| `--install <mode>` | `webapi` / `add` | `ask` (default) \| `yes` \| `no` |
+
+## Next steps
+
+After scaffolding:
+
+```bash
+cd my-app
+code .          # open in VS Code / Dev Container
+pnpm build      # forge release build
+pnpm start      # run compiled API (production)
+pnpm dev        # Flux HMR (development)
+```
+
+## Troubleshooting
+
+### GHCR pull fails with `403 Forbidden`
+
+If scaffolding fails with an error like:
+
+```text
+failed to resolve reference "ghcr.io/typesmiths/decohere/create:<version>": ... 403 Forbidden
+```
+
+your GitHub token likely does not include the `read:packages` scope.
+
+1. Create or use a token with at least `read:packages`.
+2. If the package is private/internal, also include `repo`.
+3. Re-login to GHCR and retry.
+
+```bash
+export GH_TOKEN=YOUR_PAT_WITH_READ_PACKAGES
+echo "$GH_TOKEN" | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
+docker pull ghcr.io/typesmiths/decohere/create:<version>
+```
+
+You can verify scopes with:
+
+```bash
+gh auth status -t
+```
+
+If you still get `403` after adding `read:packages`, ask an org admin to grant your user/team access to the `typesmiths/decohere/create` package.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/create",
-  "version": "0.0.1-dev.98",
+  "version": "0.0.1-dev.99",
   "description": "Download the Decohere scaffolder image and run it (npm create @decohere)",
   "keywords": [
     "decohere",