pgserve 2.6.0 → 2.6.4

package/CHANGELOG.md

@@ -14,6 +14,187 @@ All notable changes to `pgserve` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.6.4] - 2026-05-12
+
+**Final v2.x maintenance release** — the last `pgserve`-named npm publish.
+Cut from the `release/v2.6.x` maintenance branch (off `1489d7d`, pre-V3
+cutover) so consumers like `@withone/cli` (and any other `pgserve: ^2.x`
+dependent) continue to receive backward-compatible updates without the
+V3 rename, V3-1 verb cutover, or npm-publish drop. **Future development
+moves to the `autopg` package starting at v3.0.0** (see
+`distribution-exodus` wish in main).
+
+### Added (since 2.6.1)
+
+- **Signed-app delivery pipeline** — `pgserve create-app <slug>` writes a
+  per-consumer manifest with cosign locked trust roots; `pgserve verify
+  --slug <slug>` differentiates lock-vs-live identities and exit-codes
+  per outcome.
+- **Cosign keyless OIDC signing** for release tarballs — Sigstore bundles
+  + SLSA L3 provenance + GitHub Attestations API attestation per
+  platform tarball. Verifiable via `cosign verify-blob`, `slsa-verifier
+  verify-artifact`, or `gh attestation verify`.
+- **Trust-list hardcoded roots** — `automagik-genie-release`,
+  `automagik-omni-release`, and `automagik-pgserve-release` entries in
+  `src/cosign/trust-list.js`. All three anchor on `sign-attest.yml@`
+  (the canonical Fulcio SAN URI shape across Namastex automagik
+  signed apps).
+- **`pgserve gc`** — orphan-DB sweep + per-day rotating audit log under
+  `~/.pgserve/audit/` (90-day retention, current-day boundary guard).
+- **Console + docs** — operator-facing migration guide
+  (`docs/migrations/v2.6-from-v2.5.md`), cosign trust reference
+  (`docs/security/cosign-trust.md`), schema docs (`pgserve_meta`,
+  trust-store, signed-app delivery).
+- **Integration test scaffolds** — `tests/integration/gc-provision.test.sh`,
+  `tests/integration/verify-slug-rotation.test.sh`,
+  `tests/integration/wave-a-e2e.test.sh`,
+  `tests/integration/v2.6-cohort-smoke.sh`.
+- **Postinstall guardrail** — soft-fails on git-worktree dev installs
+  with a stderr warning, preventing accidental `~/.pgserve` mutation
+  during package development.
+
+### Fixed (since 2.6.1)
+
+- **CV-1**: `pgserve provision` / `pgserve gc` no longer auth-fail on
+  fresh installs (hot-fix from PR #101).
+- **B5/B6/B7 trio** — audit-log rotation boundary, dual-mode keyless
+  verify, JSON-escape OIDC issuer in aggregate manifest.
+- **CV-VERIFY-BUNDLE-NAMING** — consumer-side bundle resolve falls
+  through `.bundle` → `.sig` + `.cert` detached pair when the bundle
+  filename doesn't match, so older signing artifacts continue to verify.
+- **Wave B bundle-format** — `pgserve verify` accepts both sigstore
+  bundle (`.bundle`) and detached cosign (`<tarball>.sig` +
+  `<tarball>.cert`) artifact shapes.
+
+### Preserved (intentional — for backward compatibility)
+
+- **`pgserve` CLI bin** — both `pgserve` and `autopg` bins remain
+  declared in package.json. `pgserve <verb>` works the same as it did
+  in v2.6.1.
+- **`pgserve upgrade` verb** — V3-1's clean cutover to `pgserve update`
+  was reverted on this maintenance branch (V3-1 is a v3.0.0 breaking
+  change, not safe for a patch release). Operators continue to use
+  `pgserve upgrade` on v2.x.
+- **npm publish workflow** — V3-2 dropped npm publishing from main's
+  release path; reverted on this maintenance branch so v2.6.4 publishes
+  to npm normally via the existing OIDC trusted publisher entry.
+- **Default port 8432** — unchanged from v2.6.1.
+
+### Removed
+
+(none — additive release)
+
+### Notes for `@withone/cli` + other npm dependents
+
+- `pgserve: ^2.2.3` satisfies — semver range resolves to 2.6.4.
+- No code changes required on the consumer side.
+- The next major (`autopg@v3.0.0`) ships from the new
+  `automagik-dev/autopg` repo + drops npm; if/when you migrate, switch
+  to `install.sh` + GitHub Releases per the autopg distribution model.
+
+## [2.6.0] / [2.6.1] - 2026-05-09
+
+The 2.6 cohort closes the singleton-G3 sprint and the
+`autopg-distribution-cutover-finalize` Wave 1+2 work. v2.6.0 cut the singleton
+verbs to npm; v2.6.1 followed with the B2/B3/B4 CLI fix trio.
+
+### Added
+
+- **`pgserve doctor`** — read-only health probe for postmaster, pm2 supervision,
+  on-disk roots, and trust store. JSON output via `--json`. See
+  [`docs/migrations/v2.6-from-v2.5.md`](docs/migrations/v2.6-from-v2.5.md).
+- **`pgserve trust add | list | remove`** — manage the user-extensible cosign
+  trust store at `~/.pgserve/trust/identities.json`. Layered on top of the
+  hardcoded `TRUSTED_IDENTITIES` (frozen at build time). See
+  [`docs/trust-store.md`](docs/trust-store.md).
+- **`pgserve gc [--dry-run | --apply]`** — sweep orphan databases (rows in
+  `pgserve_meta` whose `source_path` no longer exists). One-line-per-event audit
+  log at `~/.pgserve/audit/gc-<YYYY-MM-DD>.log`. Rotates files >90 days old at
+  start of each run. See [`docs/pgserve-meta.md`](docs/pgserve-meta.md) for the
+  underlying schema.
+- **`pgserve provision <fingerprint>`** — idempotent DB + role provisioning for
+  an app fingerprint. Concurrency-safe via `pg_advisory_lock` keyed on
+  fingerprint hash; `42P04` ("database already exists") accepted as success.
+- **`pgserve create-app <slug>`** — per-consumer app registration with manifest
+  LOCK 1 cosign verifier. Writes `~/.autopg/<slug>/admin.json` + sibling
+  `manifest.json`, registers in `autopg_meta`, freezes `TRUSTED_IDENTITIES` for
+  this consumer at create time. `pgserve verify --slug <slug>` consults the
+  frozen snapshot.
+- **`pgserve verify --slug <slug>`** — verify a binary against an app's locked
+  roots (instead of the live `TRUSTED_IDENTITIES`). Allows trust rotation
+  without invalidating already-registered consumers.
+- **`pgserve_meta` schema** — base table for `provision`/`gc`. Cosign verification
+  columns (`verified_at`, `verified_identity`, `verified_tier`) layered on top
+  via additive ALTER TABLE migration. Schema reference at
+  [`docs/pgserve-meta.md`](docs/pgserve-meta.md).
+- **`autopg_meta` schema** — separate table keyed on `slug` for `create-app`
+  registrations. Frozen `locked_roots` JSONB. Idempotent re-runs preserve
+  `locked_roots` and only touch `last_updated`.
+- **GitHub Releases as the canonical distribution channel** — `install.sh`
+  fetches per-platform binaries from
+  `github.com/namastexlabs/pgserve/releases/download/v<version>/`. Cosign
+  attestations live in Sigstore Rekor; verification via `gh attestation verify`
+  (no custom verifier server). See
+  [`.github/workflows/release-publish.yml`](.github/workflows/release-publish.yml).
+- **Hardcoded blocklist** — `pgserve install` refuses to start against known-bad
+  versions with exit code `EBLOCKEDVERSION`.
+
+### Changed
+
+- **`pgserve install`** now runs port pre-flight (IPv4 + IPv6 connect probe on
+  5432) and refuses to start on collision. Closes the silent-failure mode
+  where pm2 reported `online` while postgres had crashed.
+- **`pgserve install --help`** respects `--help` / `-h` and exits 0 without
+  performing the install.
+- **Unknown verbs** (`pgserve foo`) exit non-zero with an "unknown verb" error
+  instead of printing top-level help and exiting 0.
+- **`pgserve doctor`** surfaces a missing `pgaudit` extension as a non-PASS
+  finding (was silently fall-through).
+- **`pgserve config --help`** exits 0 with a usage block instead of running the
+  config logic against `--help` as if it were a key.
+- **`install.sh`** replaced in-place with the ≤80-line GitHub Releases path.
+  No legacy or shim companions; the npm + pm2 install path is preserved via
+  `pgserve install` (`npm install -g pgserve && pgserve install`).
+
+### Fixed
+
+- **`fix(pg-query)`** — default `PGPASSWORD` to `'postgres'` on fresh install
+  (CV-1 release blocker).
+- **`fix(cosign)`** — correct trust-list github org refs (omni →
+  `automagik-dev`, pgserve → `namastexlabs`).
+- **`fix(cosign)`** — correct `publisher` field for pgserve + reconcile
+  `SHARED-DESIGN.md` org refs.
+- **`fix(postinstall)`** — worktree guard + non-CI pre-warning + dev-setup
+  docs. Closes the bug where every `bun install` in a pgserve worktree
+  triggered `autopg upgrade` against the real `~/.autopg/data/`.
+- **`fix(verify-binary)`** — `resolveBundlePath` fall-through to
+  `provenance.intoto.jsonl` and sibling provenance.
+- **`fix(verify-binary)`** — support detached `<tarball>.sig` +
+  `<tarball>.cert` cosign format alongside `<tarball>.bundle`.
+- **`fix(cli-install)`** — use `process.exitCode + throw` to avoid stdio-pipe
+  race on `process.exit(1)` against piped stdout.
+- **`fix(doctor)`** — timeout supervisor probes + `pgserve upgrade` hint when
+  pm2 is missing.
+- **`fix(install)`** — drop npm references in `install.sh`; canonical path is
+  the GitHub Releases curl-pipe.
+
+### Notes
+
+- The 2.6 cohort lands as **additive** changes — existing `pgserve` invocations
+  continue to work unchanged. See
+  [`docs/migrations/v2.6-from-v2.5.md`](docs/migrations/v2.6-from-v2.5.md) for
+  the operator action checklist.
+- **Signing artifacts on GitHub Releases are NOT yet shipping** as of v2.6.1.
+  The release workflow's `sign-attest.yml` produces cosign signatures + SLSA
+  L3 provenance, but the `release-publish.yml` upload step does not yet wire
+  those artifacts into the published release. Tracked as Wave A in
+  `agents/genie-pgserve/SIGNED-APPS-MISSION-STATE.md`. Will land in a follow-up
+  patch release.
+- **Connectivity fanout test** — `tests/integration/consumer-fanout.sh`
+  (verifying brain / omni / rlmx / hapvida-eugenia / email all reach the
+  postmaster) is owned by `pgserve-singleton-no-proxy` Group 9 and ships in a
+  separate cohort.
+
 ## [2.2.3] - 2026-05-03
 
 ### Changed

package/README.md

@@ -141,6 +141,26 @@ autopg restart                         # pm2-aware: pm2 restart pgserve, else SI
 autopg ui [--port N] [--no-open]       # local web console on 127.0.0.1
 ```
 
+### v2.6 cohort verbs
+
+The 2.6 release adds five operator-facing verbs for health probing, trust-store
+management, orphan-database GC, fingerprint provisioning, and per-consumer app
+registration:
+
+```
+pgserve doctor [--json]                # read-only health probe
+pgserve trust <list|add|remove> [...]  # manage ~/.pgserve/trust/identities.json
+pgserve gc [--dry-run|--apply]         # sweep orphan databases (audit log)
+pgserve provision <fingerprint>        # idempotent DB + role provisioning
+pgserve create-app <slug>              # per-consumer manifest LOCK 1
+pgserve verify [--slug <slug>] <bin>   # cosign verify against trust list or locked roots
+```
+
+Full reference:
+[`docs/migrations/v2.6-from-v2.5.md`](docs/migrations/v2.6-from-v2.5.md) ·
+[`docs/pgserve-meta.md`](docs/pgserve-meta.md) ·
+[`docs/trust-store.md`](docs/trust-store.md).
+
 Foreground options accepted by `autopg` / `pgserve` (no subcommand):
 
 ```

package/bin/pgserve-wrapper.cjs

@@ -66,6 +66,15 @@ const __installSubcommands = new Set([
   // src/commands/provision.js header for why). Pure node + child_process,
   // must skip bun probe.
   'provision',
+  // autopg-distribution-cutover-finalize (v2.6) — wish Group 3.
+  // `create-app` registers a consumer slug in autopg_meta + writes the
+  // per-consumer admin.json + manifest.json under ~/.autopg/<slug>/,
+  // freezing TRUSTED_IDENTITIES into locked_roots at create time. Pure
+  // node + psql shellout — must skip bun probe like the rest of the G3
+  // verbs. Adding here makes BOTH `pgserve create-app` and
+  // `autopg create-app` work via the same dispatcher (autopg-wrapper.cjs
+  // delegates to pgserve-wrapper.cjs per Decision #7).
+  'create-app',
 ]);
 if (__subcommand && __installSubcommands.has(__subcommand)) {
   const cli = require(path.join(__dirname, '..', 'src', 'cli-install.cjs'));
@@ -79,8 +88,24 @@ if (__subcommand && __installSubcommands.has(__subcommand)) {
     result.then(
       (code) => process.exit(typeof code === 'number' ? code : 0),
       (err) => {
-        process.stderr.write(`pgserve: ${err?.message ?? err}\n`);
-        process.exit(1);
+        // CV103-2 (v2.6.2): the cli-install.cjs EADDRINUSE catch handler
+        // already wrote the message to stderr AND set process.exitCode = 1
+        // before throwing. If we ALSO write here we'd double-print, AND
+        // if we call process.exit(1) we re-introduce the stdio-pipe race
+        // the catch handler avoided by switching to exitCode + throw.
+        //
+        // Suppress the duplicate stderr write for already-handled error
+        // codes. Don't call process.exit() — Node will exit naturally
+        // once the event loop drains, using process.exitCode (which the
+        // throwing handler already set) so stderr flushes cleanly even
+        // under the piped-stdout / inherited-stderr shape that exposed
+        // the race (qa repro R6: `pgserve install | cat`).
+        if (err && err.code !== 'EADDRINUSE') {
+          process.stderr.write(`pgserve: ${err?.message ?? err}\n`);
+        }
+        if (process.exitCode === undefined || process.exitCode === 0) {
+          process.exitCode = 1;
+        }
       },
     );
     return;
@@ -95,6 +120,35 @@ if (__subcommand === 'serve') {
   process.argv[2] = 'postmaster';
 }
 
+// B4 (v2.6.1): unknown-verb guard. Prior behavior fell through to the
+// bun probe + postgres-server.js which prints help and exits 0 on any
+// argv shape it didn't understand — that masked typos as silent
+// successes (`pgserve doctorr` → exits 0 with help banner; the operator
+// thinks doctor ran). Now we emit a clear `unknown verb` error and
+// exit EX_USAGE (64 per sysexits.h).
+//
+// Allowed shapes that MUST still flow through:
+//   - empty argv (no subcommand) → top-level help via postgres-server.js
+//   - flags starting with `-` (e.g. `--help`, `--version`) → top-level
+//     handlers in postgres-server.js
+//   - `postmaster` (canonical long-running entry) + `serve` (alias,
+//     already rewritten above)
+//   - allowlisted install-subcommands (already dispatched above; if
+//     control reaches here with one in __subcommand it means the
+//     dispatch path returned without exiting — keep the fallthrough).
+if (
+  __subcommand &&
+  !__subcommand.startsWith('-') &&
+  __subcommand !== 'postmaster' &&
+  __subcommand !== 'serve' &&
+  !__installSubcommands.has(__subcommand)
+) {
+  process.stderr.write(
+    `pgserve: unknown verb "${__subcommand}". Run \`pgserve --help\` for the supported verb list.\n`,
+  );
+  process.exit(64); // EX_USAGE per sysexits.h
+}
+
 // Detect platform
 const isWindows = process.platform === 'win32';
 const bunBin = isWindows ? 'bun.exe' : 'bun';