backend-skeleton 1.0.0-beta.9 → 1.0.0

package/README.md

@@ -23,10 +23,20 @@ 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
+## Status: 1.0.0
 
-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:
+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 +48,17 @@ 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;
+  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.
 
 ## 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 +74,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
@@ -172,6 +183,105 @@ 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.
+
+### 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.