backend-skeleton 1.2.0 → 1.4.0

package/README.md

@@ -32,9 +32,13 @@ check for a specific failure mode found the same way — see `DECISIONS.md` for
 
 - [Status: 1.0.0](#status-100)
 - [Quickstart](#quickstart)
+  - [Try it in 10 seconds](#try-it-in-10-seconds)
+  - [The gated workflow](#the-gated-workflow)
   - [Starting from nothing (greenfield)](#starting-from-nothing-greenfield)
   - [Publishing a feature's contract as OpenAPI (optional)](#publishing-a-features-contract-as-openapi-optional)
+  - [A CSV table of a feature's contract (optional)](#a-csv-table-of-a-features-contract-optional)
   - [Database schema (optional)](#database-schema-optional)
+  - [An ERD of your database schema (optional)](#an-erd-of-your-database-schema-optional)
   - [Applying DDL to a live database (optional)](#applying-ddl-to-a-live-database-optional)
   - [Declaring field-to-field dependencies (optional)](#declaring-field-to-field-dependencies-optional)
   - [Patching a config file (optional)](#patching-a-config-file-optional)
@@ -84,6 +88,21 @@ production -- which still splits the same way it always has:
 
 ## Quickstart
 
+### Try it in 10 seconds
+
+```bash
+npm install -g backend-skeleton   # or: npx backend-skeleton <command>
+cd <any-existing-repo>            # must be a git repository -- that's the only requirement
+bskel scan                        # zero flags: every module/controller/entity/enum this repo's
+                                   #   adapter can see, unscored -- no preflight, no feature, no
+                                   #   files written, no gate touched
+```
+
+That's a read-only look, not the gated workflow — for real feature work (collision-checked against
+a specific idea, contract-gated, codegen), see below.
+
+### The gated workflow
+
 ```bash
 npm install -g backend-skeleton   # or: npx backend-skeleton <command>
 cd <target-repo>                  # must be a git repository
@@ -193,6 +212,27 @@ bskel new --stack fastapi --slug my-service \
 The full parameter list, the measured API-validation matrix behind that split, and the warning
 behaviour are in `D-greenfield-parameters` in `DECISIONS.md`.
 
+#### Remembering your own conventions across projects (optional)
+
+If you start several projects with the same conventions, `bskel new` can record them into a
+database **you own** -- never bskel's own state, never a shared store:
+
+```bash
+export MY_PATTERNS=postgres://localhost/my_patterns    # once: run patterns/schema.sql against it
+
+bskel new --stack spring --slug billing \
+  --java-version 21 --group-id com.acme --dependencies web,data-jpa,validation,flyway \
+  --record-pattern --pattern-database-url-env MY_PATTERNS
+
+bskel pattern suggest --stack spring --pattern-database-url-env MY_PATTERNS
+```
+
+`pattern suggest` prints what you've recorded, with per-value frequency, and a ready-to-paste
+command line at the bottom -- it never runs `bskel new` for you and `bskel new` has no flag that
+would accept a suggestion as a default. Every value in a generated project is still one you typed
+in that invocation. Omitting `--record-pattern`/`--pattern-database-url-env` leaves `bskel new`
+exactly as it is today. See `D-pattern-accrual` in `DECISIONS.md`.
+
 ### Publishing a feature's contract as OpenAPI (optional)
 
 ```bash
@@ -232,6 +272,31 @@ contract's paths don't reflect (`--allow-unprefixed` overrides), and stamps ever
 reconciling a contract against its own export would make it confirm itself. See `D-openapi-export`
 in `DECISIONS.md`.
 
+### A CSV table of a feature's contract (optional)
+
+```bash
+bskel contract export-csv --feature 001-organization-management --out organization.csv
+```
+
+One row per operation, opened by someone who will never read a JSON Schema — a PM reviewing scope,
+a lead deciding whether a partial contract is good enough to waive. Fourteen columns, always, in
+the same order: `operation_id, verb, path, path_params, path_params_unverified, body,
+request_body_required, request_body_fields, response_fields, error_fields, provenance, summary,
+tags, security`.
+
+**Every column is always present, even when every row leaves it blank** — a scan-only contract
+(no `--openapi-file`) never states `summary`/`tags`/`security`, and the blank columns *are* that
+finding, not something to hide: `export-csv` prints exactly which columns are empty for every
+operation, and why, on stderr. Dropping an empty column would make the file's own shape depend on
+its content, so it never does.
+
+**Unlike `contract export`, this command is deliberately UNGATED** — it works even when the
+`contract` gate hasn't passed yet, because its single most valuable moment is reviewing a partial
+contract to decide whether to waive it. An unreflected global path-prefix signal (the thing
+`contract export` hard-refuses on) downgrades to a stderr warning here instead. `--bom` prepends a
+UTF-8 byte-order mark for Excel-on-Windows, which otherwise mangles non-ASCII text; omit it for
+`pandas`/`csv.DictReader`/`diff`, which don't want one. See `D-contract-csv` in `DECISIONS.md`.
+
 ### Database schema (optional)
 
 `bskel scan --db` additionally scans Flyway/Liquibase migration files (local only, no network).
@@ -249,6 +314,40 @@ report also carries `generated_at` — when the underlying data was actually cap
 be judged for staleness rather than trusted blindly. See `D-cross-feature-fk-inference` in
 `DECISIONS.md`.
 
+### An ERD of your database schema (optional)
+
+```bash
+bskel db erd --database-url-env BSKEL_DB_URL --schema public --out schema.mmd
+```
+
+A Mermaid `erDiagram` of the database — paste it straight into a GitHub/GitLab/Notion/Obsidian
+markdown file (fence it in \`\`\`mermaid) or [mermaid.live](https://mermaid.live) and it renders
+with no extra tooling. Works two ways:
+
+- **With `--database-url-env`**: a real, live Postgres introspection — full column types,
+  nullability, and primary/foreign keys.
+- **Without it**: falls back to scanning Flyway/Liquibase `.sql` migration files (no network, no
+  credentials needed) — a real but **degraded** diagram, clearly marked as such in the file itself:
+  every column types as `unknown`, no `PK` badge appears anywhere, and a header block spells out
+  exactly what's missing. Useful for evaluating the tool on a repo you don't have DB credentials
+  for yet.
+
+Two things this diagram deliberately does **not** guess:
+
+- **Composite foreign keys.** Postgres's own `information_schema` doesn't retain which source
+  column pairs with which target column once a foreign key spans more than one column — the raw
+  data is a cross product that can include pairs that were never declared. Rather than draw a wrong
+  relationship line, a composite FK collapses to one line labeled with all its source columns
+  joined by `+`, with the ambiguity spelled out in a `%%` comment above it. (Composite *primary*
+  keys have no such problem and render fully.)
+- **1:1 vs 1:N.** The child side of every relationship is drawn as "zero or more," never "exactly
+  one" — telling those apart needs a UNIQUE constraint check this tool doesn't perform. The header
+  says so.
+
+Whole-schema only in this version (no `--feature`/`--tables` filtering yet) — for a very large
+schema, `db erd` prints a note above 40 entities rather than silently producing an unreadable
+diagram. See `D-db-erd` in `DECISIONS.md`.
+
 ### Applying DDL to a live database (optional)
 
 `bskel patch propose --kind ddl-apply` extends the same propose/approve/apply/rollback lifecycle
@@ -385,7 +484,7 @@ below).
 |---|---|---|
 | Node.js | `>=18` | ES2022 (`Object.hasOwn`) + ESM top-level `await` — nothing newer is used anywhere in the runtime code (verified by grep across every recent-ES-addition pattern; see `D-npm-packaging` in `DECISIONS.md`) |
 | git | required | every gate is git-state-derived |
-| [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) | required for `scan`/`handles` | every scanner adapter shells out to it directly, and throws (not degrades) if it's missing |
+| [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) | required for `scan`/`handles` | every scanner adapter shells out to it at `detect()` time behind a blanket try/catch — traced live, missing `rg` does NOT throw, it silently makes every real adapter detect nothing (degrades to the low-confidence `generic-grep` fallback). `bskel scan`'s report now carries a `rg_available: false` field plus an explicit `unknowns` warning whenever this happens, so it stays distinguishable from a genuinely-unrecognized repo — see `D-zero-config-scan` in `DECISIONS.md` |
 | `gh` (GitHub CLI) | optional | only used for `preflight`'s 3-way default-branch cross-check; already soft-guarded, never a hard requirement |
 | `python3` | optional | only needed to run this repository's own cross-language codec test — `bskel` itself never invokes `python3` |
 | a build wrapper (`gradlew`/`pom.xml`+`mvnw`/`package.json`) | optional | only `bskel verify --build` needs one; `handles emit` never compiles anything itself |