backend-skeleton 1.0.0-beta.9 → 1.1.0

package/README.md

@@ -23,10 +23,43 @@ of just another thing to double-check by hand.
 commits behind the real default branch and never noticed. Every gate in this tool is a regression
 check for a specific failure mode found the same way — see `DECISIONS.md` for the full record.
 
-## Status: beta
-
-This is the first public release, and it's deliberately labeled a beta rather than `1.0.0`
-stable. Split by actual maturity, not by feature list:
+![bskel run against a real fixture repo: preflight, a brownfield collision scan, and a feature status gate table](https://raw.githubusercontent.com/popixoxipop-collab/backend-skeleton/main/docs/demo.gif)
+
+*A real terminal, a real `bskel` binary, a real fixture repo — not a scripted transcript. Source:
+[`docs/demo.tape`](docs/demo.tape), regenerated with [`docs/record-demo.sh`](docs/record-demo.sh).*
+
+## Contents
+
+- [Status: 1.0.0](#status-100)
+- [Quickstart](#quickstart)
+  - [Starting from nothing (greenfield)](#starting-from-nothing-greenfield)
+  - [Publishing a feature's contract as OpenAPI (optional)](#publishing-a-features-contract-as-openapi-optional)
+  - [Database schema (optional)](#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)
+- [Compatibility](#compatibility)
+- [Generated-file policy](#generated-file-policy)
+- [Security model](#security-model)
+- [Troubleshooting](#troubleshooting)
+- [What ships in the package](#what-ships-in-the-package)
+- [License](#license)
+
+## Status: 1.0.0
+
+As of `1.0.0`, this project makes an explicit API-stability promise: **`bskel`'s CLI surface --
+command/flag names and their meaning, every `--json` output shape (all schemas under `schemas/`),
+gate names and pass/fail semantics, and exit codes -- is stable.** A change that breaks any of
+those requires a major version bump, never a patch or minor release; a new command, a new optional
+flag, or a new additive field on an existing JSON shape is always minor-version-safe (every schema
+under `schemas/` is `additionalProperties: false` specifically so a genuinely new field shows up as
+a real, visible schema change rather than something an existing consumer could silently miss). See
+`D-stable-api-contract` in `DECISIONS.md` for the full policy and what's explicitly excluded from
+it.
+
+That promise is about the *interface*, not a claim that every subsystem has been proven in
+production -- which still splits the same way it always has:
 
 - **`scan`, `contract` (including `export`), and `new`** are the most exercised paths — real,
   measured verification against a real production Spring Boot repo (see `DECISIONS.md`), plus a
@@ -38,19 +71,20 @@ stable. Split by actual maturity, not by feature list:
   independently correct roles instead of silently sharing one) are both implemented -- see
   `DECISIONS.md`'s `D-handle-registry-enforcement`/`D-resolver-authorization-action-aware`. Real
   gaps remain and are explicitly still open, not closed: registry enforcement is opt-in, off by
-  default; authorization inference still only recognizes a single `@PreAuthorize(hasRole(...))`
-  shape (`hasAuthority`, role lists, ownership/tenant policy are unaddressed); and Java/Python are
-  the only providers either applies to -- TypeScript Express has no persistent handle table at
-  all. Treat `handles emit`'s output as a scaffold to finish by hand, not a production-ready
-  subsystem, until a real deployment happens.
-
-Version numbers, install instructions, and a real feedback path will firm up as this gets used
-against more real repos.
+  default; authorization inference now recognizes both `@PreAuthorize(hasRole(...))` and
+  `hasAuthority(...)` (see `DECISIONS.md`'s `D-resolver-authorization-action-aware`), but
+  `hasAnyRole`/`hasAnyAuthority` (list-shape), ownership, and tenant policy are still unaddressed.
+  All three providers (Java/Python/TypeScript) now generate a real `sbf_handle`/
+  `sbf_handle_snapshot` schema and support `--enforce-registry`/`recover()` -- TypeScript's own
+  registration mechanism is a higher-order wrapper function, not a decorator (no Java-AOP or
+  Python-decorator equivalent exists in this ecosystem the templates could safely rely on; see
+  `D-typescript-express-registry-parity` in `DECISIONS.md`). Treat `handles emit`'s output as a
+  scaffold to finish by hand, not a production-ready subsystem, until a real deployment happens.
 
 ## Quickstart
 
 ```bash
-npm install -g backend-skeleton@beta   # or: npx backend-skeleton@beta <command>
+npm install -g backend-skeleton   # or: npx backend-skeleton <command>
 cd <target-repo>                  # must be a git repository
 
 bskel doctor                      # what's on PATH, which scanner adapter detects this repo, and why
@@ -66,6 +100,9 @@ bskel scan disposition --feature 001-organization-management --mode reuse --note
 
 bskel contract emit --feature 001-organization-management
                                    # feature_id-scoped JSON Schema contract, from real source annotations
+bskel scan cross-feature-check --feature 001-organization-management
+                                   # refuses to proceed if this feature's resourceType/table/operationId
+                                   #   collides with another feature -- required before handles emit
 bskel handles plan --feature 001-organization-management
 bskel handles emit --feature 001-organization-management
                                    # UUID-addressable field handles + generated resolver code
@@ -75,6 +112,36 @@ bskel verify --feature 001-organization-management --build
                                    #   target repo's own build wrapper (gradlew/mvnw/npm), if present
 ```
 
+`bskel status`/`bskel next` are what you actually run over and over — real output, captured against
+a fixture repo partway through the flow above, not written by hand:
+
+```text
+$ bskel status --feature 001-organization-management
+# Status: 001-organization-management
+
+## Gates
+- [PASS] preflight
+- [PASS] scan
+- [(not_run)] cross_feature (required-when-present, feature-scoped)
+- [BLOCKING] contract
+- [(not_run)] dependencies (required-when-present, feature-scoped)
+- [(not_run)] handles (required-when-present, feature-scoped)
+- [(not_run)] stack (required-when-present, repo-scoped)
+- [(not_run)] patch_transactions (required-when-present, feature-scoped)
+- [(not_run)] conformance (required-when-present, feature-scoped)
+
+## Artifacts
+- [OK] contract: specs/001-organization-management/contracts/001-organization-management.schema.json
+
+## Next
+- bskel contract waive --feature 001-organization-management --code <CODE> (--subject "..."|--all) --reason "..."   # or: bskel gate force contract --feature 001-organization-management --reason "..." if intentional   # contract gate is awaiting disposition
+
+## Optional, not yet run: handles, stack
+```
+
+Every gate line is a real, disk-verified check — the `Next` line is always the exact command to
+unblock whatever's currently `BLOCKING`, so there's no separate doc to cross-reference mid-workflow.
+
 ### Starting from nothing (greenfield)
 
 Every command above assumes an existing Spring Boot or FastAPI repo. If you don't have one yet:
@@ -172,6 +239,111 @@ read from `.env`) for live, read-only Postgres introspection (`information_schem
 inside a `BEGIN TRANSACTION READ ONLY`) and a source-vs-live drift report. Both are informational
 additions to the scan report — neither blocks any gate. See `D-db-schema-plane` in `DECISIONS.md`.
 
+The same `--db`/`--database-url-env` flags, passed to `bskel scan cross-feature-check`, add a 4th
+collision signal: a real live (or migration-file-derived) Postgres foreign-key edge whose two
+tables are declared by two *different* features surfaces as a `db_foreign_key` finding, direction-
+and confidence-scored the same way the existing NAME-identity signals are. Every `fk_check` in the
+report also carries `generated_at` — when the underlying data was actually captured, so a
+`persisted`/`migrations`-mode correlation (reused from an earlier scan, not a fresh connection) can
+be judged for staleness rather than trusted blindly. See `D-cross-feature-fk-inference` in
+`DECISIONS.md`.
+
+### Applying DDL to a live database (optional)
+
+`bskel patch propose --kind ddl-apply` extends the same propose/approve/apply/rollback lifecycle
+`config_apply` uses to a second kind: hand-authored `CREATE`/`ALTER`/`DROP TABLE`/`INDEX`/`SCHEMA`
+statements, run inside a real Postgres transaction and only `COMMIT`ted once the introspected
+schema actually matches the declared postcondition — anything else `ROLLBACK`s automatically, never
+partially applies:
+
+```bash
+bskel patch propose --feature 001-organization-management --kind ddl-apply \
+  --database-url-env BSKEL_DB_URL --sql-file migrations/add_tax_rate.sql --schema public
+bskel patch approve --feature 001-organization-management --transaction <id> --reason "..."
+bskel patch apply --feature 001-organization-management --transaction <id>
+# a transaction that DROPs one or more tables requires retyping the sorted, comma-joined table
+# name(s) as --confirm instead of the transaction id -- the same "type the resource name to
+# delete" pattern GitHub uses for its own irreversible actions
+```
+
+Rollback of an *applied* `ddl-apply` transaction is refused outright by design — the only path back
+is a new, forward transaction with hand-written reverse DDL, never an automated revert. The
+allowlist structurally excludes anything that can't run inside a transaction block (e.g. `CREATE
+INDEX CONCURRENTLY`) and anything outside `TABLE`/`INDEX`/`SCHEMA` DDL. `bskel serve
+--database-url-env <NAME> [--sign-key <path>] [--require-sign-key]` exposes the same lifecycle
+through the browser UI's own propose/approve/apply routes; `--require-sign-key` refuses to start
+the DDL surface at all unless a signing key was also given. See `D-ddl-apply` in `DECISIONS.md` for
+the full design and every explicitly-deferred boundary (non-Postgres databases, connection
+pooling, production safety rails).
+
+### Declaring field-to-field dependencies (optional)
+
+When one feature's data actually depends on another feature's (e.g. a `WidgetDto.name` that's
+populated from `OrganizationDto.taxRate`), `bskel dependency declare` records that link and passes
+the `dependencies` gate for it. Declaring a dependency also warns the *source* feature next time
+someone re-runs `bskel status`/`bskel next` there, so a downstream consumer doesn't silently break:
+
+```bash
+bskel dependency declare --feature 001-widget-management --resource WidgetDto --field name \
+  --source-feature 002-organization-management --source-resource OrganizationDto --source-field taxRate \
+  --reason "widget display name mirrors the owning org's rate tier" [--memo "..."]
+bskel dependency list --feature 001-widget-management --json
+bskel dependency remove --feature 001-widget-management --resource WidgetDto --field name \
+  --source-feature 002-organization-management --source-resource OrganizationDto --source-field taxRate \
+  --reason "no longer coupled"
+```
+
+`bskel serve [--port N] [--host <addr>]` starts a small local HTTP server (loopback-only by
+default, matching this project's "safe default, explicit override" convention) that serves a
+read-only browser UI at `/` for the whole repo's dependency graph, backed by `GET /api/graph`. The
+UI's own POST/DELETE calls to `/api/features/:id/dependencies` go through the exact same
+`declareDependency`/`removeDependency` functions the CLI above uses — nothing is duplicated
+between the two — and, like every other mutating command in this project, both take a JSON body,
+not query parameters. `GET`/`HEAD` responses carry `Access-Control-Allow-Origin: *`; the mutating
+routes never do, so only same-origin requests (the bundled UI itself) can write.
+
+![bskel serve's dependency-graph UI, showing a real declared field-to-field dependency resolved as synced](https://raw.githubusercontent.com/popixoxipop-collab/backend-skeleton/main/docs/serve-ui.png)
+
+*The page's own header describes it honestly: "Not a redesign of the original Fieldwire mockup --
+this exists to prove the API actually works, nothing more." It's a minimal read-only check page, not
+a polished dashboard — every table on it comes straight from `GET /api/graph`.*
+
+### Patching a config file (optional)
+
+`bskel stack apply`'s `config_check` sometimes reports `needs-manual-patch` — a target file exists
+but isn't wired up the way the chosen stack (e.g. `ngrok`) needs. `bskel patch propose/approve/
+apply/rollback` closes that gap for the catalog entries that declare a machine-applicable fix,
+using a comment-preserving edit with a content-addressed preimage check (refuses to apply if the
+target changed since you approved it) and a real rollback:
+
+```bash
+bskel patch propose --feature 001-organization-management --choice ngrok \
+  --target src/main/resources/application.yaml
+bskel patch approve --feature 001-organization-management --transaction <id> --reason "..."
+bskel patch apply --feature 001-organization-management --transaction <id>
+# ...or, to undo: bskel patch rollback --feature 001-organization-management --transaction <id> --reason "..."
+```
+
+`bskel patch list --feature <id>` shows every transaction and its status. See
+`D-patch-transactions` in `DECISIONS.md`.
+
+### Signed gate attestations (optional)
+
+`bskel gate export` already produces a CI-independent report of every gate's current status. Add
+`--sign --key <privateKeyPath>` to detached-sign it (Ed25519, via Node's own `crypto` module — no
+new dependency), then verify it offline, on any machine, without network access or trusting
+whatever produced it:
+
+```bash
+bskel attest keygen --out ~/.bskel-keys        # writes attest-private.pem (0600) + attest-public.pem
+bskel gate export --feature 001-organization-management \
+  --sign --key ~/.bskel-keys/attest-private.pem --out attestation.json
+bskel attest verify --file attestation.json --pubkey ~/.bskel-keys/attest-public.pem
+```
+
+`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`.
+
 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.