fix(descriptor): prefer plain forwards — stock-CHR TLS endpoints are not dialable (#95)

[mobileskyfi]

Fixes #95.
Fixes #94.

What

Descriptor v1 (0.4.4) advertised the secure forwards for services["rest-api"] / services["native-api"]. On a stock quickchr-booted CHR both are dead:

• guest /ip/service: www-ssl:443 disabled=true → the https forward resets every connection (ECONNRESET);
• guest /certificate is [] → api-ssl is enabled but certificate-less; a standard TLS handshake fails (openssl s_client: alert 40).

Grounded on CHR 7.23.2. This also contradicted docs/centrs-interface.md's own consumer scope note ("don't add preference logic to quickchr").

The descriptor now picks the plain forwards (http/api) — the same ports restUrl has always used — falling back to https/api-ssl (with tls: true) only when the plain forward is excluded, so the excludePorts latent-bug fix is preserved.

Release CI now publishes from the committed package.json version instead of bumping package.json/CHANGELOG.md and pushing a release commit to protected main. The workflow remains a simple workflow_dispatch, but release prep is now a PR/human-owned version + changelog promotion.

This branch prepares 0.4.5 so centrs can consume the descriptor fix from npm without a local bun link.

Validation

• bun scripts/release-prep.ts --from-package --notes-out /tmp/quickchr-release-notes.md → version=0.4.5, npm-tag=latest.
• actionlint .github/workflows/release.yml.
• bun test test/unit/release-prep.test.ts: 9 pass / 0 fail.
• bun test test/unit/: 710 pass / 0 fail / 18 skip.
• bun run check.
• PR CI at 60f9ebf: green.
• Consumer chain: centrs --quickchr CHR acceptance (test/integration/quickchr-target.test.ts in tikoci/centrs, #134 Phase 5) runs green against this branch via bun link — retrieve/execute/api/transfer + fan-out + the sftp batchModes gate, on a real CHR 7.23.2.

Follow-up

Secure preference can return once boot provisioning installs a certificate and enables www-ssl; tracked implicitly in #95's discussion.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 470957ff-a948-46e2-b0c5-941a34da823a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Descriptor v1 now prefers plain forwards for rest-api and native-api, falling back to TLS forwards when plain ports are excluded. Tests, interface documentation, and the changelog reflect the updated behavior.

Changes

Descriptor endpoint selection

Layer / File(s)	Summary
Plain-first endpoint selection src/lib/quickchr.ts, test/unit/descriptor.test.ts, test/unit/cli-env-inspect.test.ts	Service construction now selects plain ports first, with tests expecting non-TLS endpoints on ports 19100 and 19103.
Descriptor behavior documentation docs/centrs-interface.md, CHANGELOG.md	Documentation records plain-first ordering, TLS fallback behavior, and the excludePorts case.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• tikoci/quickchr#84: Updates the same descriptor port-selection logic, documentation, and tests.

Suggested reviewers: copilot

Sequence Diagram(s)

sequenceDiagram
  participant descriptor
  participant buildHttpService
  participant forwardedPorts
  descriptor->>buildHttpService: construct REST and native API services
  buildHttpService->>forwardedPorts: select plain port before secure fallback
  forwardedPorts-->>buildHttpService: selected port and TLS state
  buildHttpService-->>descriptor: service endpoint definitions

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The code and tests implement #95 by preferring plain forwards and falling back to secure ports when excluded.
Out of Scope Changes check	✅ Passed	Changes stay within scope: code, docs, changelog, and tests all support the descriptor endpoint selection fix.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: descriptor now prefers plain forwards because stock CHR TLS endpoints are not dialable.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/descriptor-plain-first-95

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

This PR fixes descriptor v1’s service endpoint selection so that, on a stock quickchr-booted CHR, services["rest-api"] and services["native-api"] advertise dialable endpoints by preferring the plain forwards (http / api) and only falling back to the TLS forwards (https / api-ssl) when the plain forward is excluded/missing.

Changes:

• Switched descriptor selection order to plain-first (plain ?? secure) while preserving the excludePorts fallback behavior.
• Updated unit tests to assert the new port/url/tls expectations for REST and native API services.
• Revised interface documentation and added a changelog entry describing the behavioral correction and grounding.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/lib/quickchr.ts	Changes descriptor endpoint selection to prefer plain forwards and keeps secure as fallback.
test/unit/descriptor.test.ts	Updates expectations to validate plain-first selection and correct tls/url fields.
test/unit/cli-env-inspect.test.ts	Updates CLI JSON descriptor expectations to match the new service port/tls values.
docs/centrs-interface.md	Revises the contract note to document the plain-first behavior and rationale (#95).
CHANGELOG.md	Records the fix under Unreleased with context and consumer impact.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

scripts/release-prep.ts:17

• The top-level doc comment still says the script always gates on a non-empty CHANGELOG.md [Unreleased] section and rolls it over. In --from-package mode it no longer reads [Unreleased] at all (it extracts an existing ## [X.Y.Z] section), so the comment is now inaccurate. Clarify the two modes to avoid misleading release-process documentation.

 * release-prep — compute the next version, roll CHANGELOG.md's [Unreleased]
 * section over to it, and bump package.json for a local/manual release-prep PR.
 * The CI release workflow uses --from-package instead: it reads committed
 * package.json + CHANGELOG.md and never mutates tracked files.
 *
 * Usage: bun scripts/release-prep.ts <patch|minor|major|X.Y.Z> [--dry-run] [--notes-out <file>]
 *        bun scripts/release-prep.ts --from-package [--notes-out <file>]
 *
 * - Fails if CHANGELOG.md's [Unreleased] section is empty — a release must say
 *   what changed. (The end-of-session checklist keeps [Unreleased] current.)
 * - Inserts `## [X.Y.Z] — YYYY-MM-DD` below a fresh [Unreleased] heading.
 * - Prints machine-readable lines: `version=X.Y.Z` and `npm-tag=next|latest`
 *   (odd minor → next, even minor → latest — the repo's pre-release scheme).
 * - --notes-out writes just the released section body (the GitHub Release notes).
 * - --dry-run computes and prints everything but writes no files.