@dforge-core/dforge-cli 0.1.0-test.5 → 0.1.0

package/README.md

@@ -17,12 +17,8 @@ macOS arm64/x64, Linux x64/arm64, Windows x64/arm64.
 ## Commands
 
 ```bash
-# STATIC checks: manifest identifiers, translation completeness, menu/folder/entity
-# coverage, folder paths. DB-bound checks (FK target resolution, package-filter SQL,
-# migration safety) only surface during `module install` against a live tenant —
-# a clean `validate` does NOT guarantee a clean install.
-dforge-cli module validate ./my-module
-dforge-cli module validate ./my-module-1.0.0.dforge
+# Scaffold a new module interactively (see `Scaffolding a new module` below).
+dforge-cli init module ./my-module
 
 # Package a module directory into a .dforge archive
 dforge-cli module pack ./my-module                    # writes my-module-1.0.0.dforge in cwd
@@ -32,7 +28,10 @@ dforge-cli module pack ./my-module -o pkg.dforge      # writes ./pkg.dforge
 # Publish a .dforge to the marketplace (org-scoped)
 dforge-cli marketplace publish ./my-module-1.0.0.dforge --org acme
 
-# Install a .dforge (or source directory) to a running tenant over HTTP
+# Install a .dforge (or source directory) to a running tenant over HTTP.
+# Manifest, FK targets, package-filter SQL, and migration safety are all
+# validated server-side during install — first install of a fresh scaffold
+# is the smoke test that catches anything wrong.
 DFORGE_URL=https://app.example.com DFORGE_TOKEN=<jwt> \
 	dforge-cli module install --path ./my-module-1.0.0.dforge
 
@@ -40,6 +39,94 @@ DFORGE_URL=https://app.example.com DFORGE_TOKEN=<jwt> \
 dforge-cli dbml-import --from-dbml ./schema.dbml
 ```
 
+## Scaffolding a new module
+
+```bash
+dforge-cli init module ./my-module
+```
+
+Walks you through an interactive setup and writes a fresh module that's
+ready to `pack` and `install`.
+
+### What it asks
+
+| Prompt | Default | Notes |
+|---|---|---|
+| Module code | (none) | `^[a-z][a-z0-9_-]*$` — becomes the DB schema name and `module_cd` |
+| Display name | titlecased `code` | shown in the UI |
+| Description | (empty) | optional |
+| Author name | `git config user.name` | optional |
+| License | `MIT` | |
+| Version | `0.1.0` | semver |
+| DB schema version | `0.0.1` | bumped when you alter physical columns |
+| Dependencies | `admin`, `metadata` | toggle which system modules you depend on |
+| Preset | Minimal | see below |
+| First entity name | (none) | `^[a-z][a-z0-9_]*$` — table/entity code |
+| First entity label | titlecased name | display label |
+| Traits | `identity + audit` | see below |
+
+`moduleId` (the immutable UUID) is auto-generated with `crypto.randomUUID()` — no prompt.
+
+### Presets
+
+- **Minimal** — manifest + one entity + minimum UI (`data_views`, `folders`, `menus`, `actions`) + one admin role. ~8 files. Installs as-is; you add fields/views/roles from there.
+- **Minimal + add more entities interactively** — same as Minimal, then loops to add additional entities (name + label + traits per entity) so you don't have to re-run.
+- **Full template** — Minimal plus `settings.json`, `translations/en-US.json`, a `seed-data/01-<entity>.json` per entity, and a `logic/actions/` stub directory. Use this when you want the typical optional files scaffolded for you to fill in (or delete).
+
+### Entity traits
+
+The "traits" choice controls which built-in columns the entity gets for free — both rendered by the platform, no need to declare in `fields`:
+
+- **identity only** — primary key only. Use for lookup tables that don't need audit columns.
+- **identity + audit** (recommended) — primary key + `created_date` + `last_updated` + `created_by` + `last_updated_by`. Standard for any business entity.
+
+You can change traits later by editing the entity JSON.
+
+### After scaffold
+
+```bash
+cd ./my-module
+dforge-cli module install --path . --code <tenant>   # full validation + install
+```
+
+The first install runs the full server-side validator (manifest, FK targets, package-filter SQL, migration safety) — fix anything it flags, then re-run.
+
+### Programmatic use (subpath export)
+
+The pure-TS builders behind `init module` are also exposed as a library entry, so downstream packages can compose module file maps without shelling to the CLI. Used by [`@dforge-core/dforge-mcp`](https://www.npmjs.com/package/@dforge-core/dforge-mcp) to drive AI-authored modules.
+
+```ts
+import {
+	buildManifest,
+	buildEntity,
+	buildDataViews,
+	buildFolders,
+	buildMenus,
+	buildRoles,
+} from "@dforge-core/dforge-cli/templates";
+import type { ScaffoldOpts, EntitySpec } from "@dforge-core/dforge-cli/templates";
+import { randomUUID } from "node:crypto";
+
+const opts: ScaffoldOpts = {
+	path: "",
+	code: "smoke",
+	displayName: "Smoke",
+	description: "",
+	author: "",
+	license: "MIT",
+	version: "0.1.0",
+	dbSchemaVersion: "0.0.1",
+	dependencies: ["admin", "metadata"],
+	preset: "minimal",
+	entities: [{ name: "thing", label: "Thing", traits: "identity+audit" }],
+};
+
+const manifest = buildManifest(opts, randomUUID());
+// → plain JS object, ready for JSON.stringify
+```
+
+All builders are pure functions returning plain JS objects (no I/O). The subpath ships dual CJS + ESM + `.d.ts` types.
+
 ## Auth
 
 The remote `module install --url` and `marketplace publish` flows need a JWT
@@ -84,15 +171,106 @@ C# source lives in [`iash44/dForge-core`](https://github.com/iash44/dForge-core)
 under `server/src/dForge.Cli/`. This repo only ships the npm wrapper + 6
 platform sidecars. Release flow:
 
-1. Tag `cli-vX.Y.Z` in `dForge-core` → `.github/workflows/release-cli.yml`
-   cross-compiles 6 binaries and attaches them to a GitHub Release.
-2. Run `gh workflow run publish.yml -f source_tag=cli-vX.Y.Z -f npm_version=X.Y.Z -f npm_tag=next`
-   in this repo. `scripts/fetch-binaries.sh` pulls binaries from the source
-   release; `scripts/publish.sh` aligns versions and publishes 7 packages.
-3. After smoke-testing `npx -y @dforge-core/dforge-cli@next --version`, promote
-   with another workflow run using `-f npm_tag=latest`.
+1. **Tag the source repo.** From a clean `main` in `iash44/dForge-core`:
+   ```bash
+   git checkout main && git pull
+   git tag cli-v0.1.0                       # NOTE: prefix is cli-v, no `release/` etc.
+   git push origin cli-v0.1.0
+   ```
+   The `cli-v*` tag triggers `.github/workflows/release-cli.yml`, which
+   cross-compiles 6 binaries (3–4 min) and attaches them as assets to a
+   GitHub Release at that tag. Watch:
+   ```bash
+   gh run watch --repo iash44/dForge-core
+   gh release view cli-v0.1.0 --repo iash44/dForge-core   # should list 6 assets
+   ```
+
+2. **Publish to npm under `next`.** From anywhere (workflow runs in CI):
+   ```bash
+   gh workflow run publish.yml --repo dforge-core/dforge-cli \
+     -f source_tag=cli-v0.1.0 \
+     -f npm_version=0.1.0 \
+     -f npm_tag=next
+   ```
+   `source_tag` is the source-repo git tag (with `cli-v` prefix);
+   `npm_version` is the npm semver (no prefix). They don't have to match
+   — pre-release suffixes are fine (`cli-v0.1.0-rc.1` → `0.1.0-rc.1`).
+
+3. **Smoke test, then promote.**
+   ```bash
+   npx -y @dforge-core/dforge-cli@next --version   # exits 0, prints sha + build time
+   ```
+   If happy, promote the SAME version to `latest`:
+   ```bash
+   gh workflow run publish.yml --repo dforge-core/dforge-cli \
+     -f source_tag=cli-v0.1.0 \
+     -f npm_version=0.1.0 \
+     -f npm_tag=latest
+   ```
+   This re-publishes (idempotent for the same `npm_version`) and moves
+   the `latest` dist-tag. End users running `npm i -g @dforge-core/dforge-cli`
+   now get this version.
+
+**Choosing the version number.** `npm_version` is permanent once published
+— npm only allows unpublish within 72h and burns the version slot forever
+after. Use the `0.X.Y-rc.N` / `0.X.Y-test.N` pattern for shake-out runs
+(`npm_tag=next`), and reserve plain `0.X.Y` for what you actually want
+people to install (`npm_tag=latest`).
 
 To test a freshly-built binary without going through the publish pipeline,
 set `DFORGE_CLI_BINARY=/path/to/dforge-cli` and `node index.js` will exec
 that path directly, skipping require.resolve and the sibling-packages
 fallback.
+
+### CI auth setup (non-obvious, easy to miss)
+
+The `publish.yml` workflow uses two auth mechanisms that both have to be
+configured outside the repo:
+
+**1. npm Trusted Publisher — must be set up for ALL 7 package names**
+
+OIDC publishing is configured per-package in the npm UI, not at the org
+level. Each of these needs its own Trusted Publisher entry pointing at
+`dforge-core/dforge-cli` / `publish.yml`:
+
+- `@dforge-core/dforge-cli` (wrapper)
+- `@dforge-core/dforge-cli-darwin-arm64`
+- `@dforge-core/dforge-cli-darwin-x64`
+- `@dforge-core/dforge-cli-linux-arm64`
+- `@dforge-core/dforge-cli-linux-x64`
+- `@dforge-core/dforge-cli-win32-arm64`
+- `@dforge-core/dforge-cli-win32-x64`
+
+Visit `npmjs.com/package/<name>/access` for each, scroll to **Trusted
+Publisher**, click Add. Missing config produces a confusing **404** on
+publish (npm returns 404 instead of 401 to avoid leaking package existence).
+
+**2. `SOURCE_REPO_PAT` secret — private cross-owner read**
+
+The source repo (`iash44/dForge-core`) is private and lives under a
+different owner than this dist repo. The workflow-issued `GITHUB_TOKEN`
+can't reach it. Create a fine-grained PAT with **Contents: Read** on
+`iash44/dForge-core` and store it as a repo secret named exactly
+`SOURCE_REPO_PAT`:
+
+```bash
+gh secret set SOURCE_REPO_PAT --repo dforge-core/dforge-cli
+```
+
+Fine-grained PATs can't be renewed — when it expires, regenerate and
+re-run the `gh secret set` command.
+
+### Workflow gotchas worth knowing
+
+- **Node 24, not 22.** Node 22 ships npm 10.9.7, which doesn't support
+  Trusted Publisher OIDC. `npm install -g npm@latest` on top of npm 10
+  fails on Ubuntu runners with `Cannot find module 'promise-retry'`
+  (arborist self-upgrade bug). Node 24 ships npm 11.x natively.
+- **No `registry-url` in setup-node.** When set, it writes a `.npmrc`
+  with `_authToken=${NODE_AUTH_TOKEN}`. With no `NODE_AUTH_TOKEN` env,
+  the literal placeholder `XXXXX-XXXXX-XXXXX-XXXXX` ends up as the
+  token, and npm uses it instead of falling back to OIDC. Default
+  registry is npmjs.org anyway.
+- **`npm publish`, not `pnpm publish`.** pnpm's OIDC Trusted Publisher
+  support lags npm's. The script uses pnpm for everything else and only
+  shells to `npm publish` for the actual upload.