backend-skeleton 1.1.1 → 1.3.0

package/README.md

@@ -32,13 +32,18 @@ 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)
   - [Signed gate attestations (optional)](#signed-gate-attestations-optional)
+  - [Signed observe receipts (optional)](#signed-observe-receipts-optional)
 - [Compatibility](#compatibility)
 - [Generated-file policy](#generated-file-policy)
 - [Security model](#security-model)
@@ -83,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
@@ -192,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
@@ -231,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).
@@ -248,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
@@ -344,6 +444,32 @@ bskel attest verify --file attestation.json --pubkey ~/.bskel-keys/attest-public
 `attest verify`'s exit code reflects signature validity only — whether the gates inside actually
 passed is a separate, printed summary. See `D-gate-attestation-signing` in `DECISIONS.md`.
 
+### Signed observe receipts (optional)
+
+`bskel observe emit` generates opt-in runtime middleware that checks real traffic against a
+feature's contract and logs a verdict-only receipt per call (JSON Pointer + constraint kind, never
+an observed value); `bskel observe import --receipts <path>` turns a stream of those receipts into
+a committed report backing the `conformance` gate. By default a receipts file is trusted at face
+value once it's structurally valid — a human could hand-fabricate one. Add `--pubkey <path>` to
+`observe import` to verify each receipt's optional signature instead, reusing the same
+`bskel attest keygen`-generated keypair signed gate attestations use:
+
+```bash
+bskel attest keygen --out ~/.bskel-keys        # same command as above -- one keypair, multiple uses
+# then, per deployed app (one-time, at the app's own startup):
+#   TypeScript: import { setSigningKey } from './observe/receiptSign'; setSigningKey(pem);
+#   Java:       set the bskel.observe.signing-key-pem Spring property (e.g. an env var)
+#   Python:     receipt_sign.configure(os.environ.get("BSKEL_OBSERVE_SIGNING_KEY_PEM"))
+bskel observe import --feature 001-organization-management --receipts receipts.jsonl \
+  --pubkey ~/.bskel-keys/attest-public.pem [--require-signature]
+```
+
+Unset/no key configured means every receipt stays unsigned — fully backward compatible with every
+app already using this feature. `--pubkey` alone verifies signatures where present and tolerates
+unsigned receipts (excluding them from the report's `matched` counts, with a printed warning);
+`--require-signature` makes any unsigned or invalid receipt abort the whole import. See the
+"cryptographic receipt attestation" update in `D-runtime-conformance-receipts` in `DECISIONS.md`.
+
 Every command is read-only until you explicitly run one of the mutating steps above — `bskel
 status`/`bskel next` (no arguments needed) tell you which gate is next and print the exact
 copy-pasteable command for it, without touching anything.
@@ -358,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 |