fix: tighten ztd starter prepublish UX proof

[mk3008]

Summary

• Fix the generated ztd starter smoke boundary so the scaffold typechecks without hand edits.
• Wrap starter Postgres connection failures, including AggregateError cases, with concise recovery steps that name Docker, .env, and ZTD_DB_PORT.
• Extend the published-package verification script so the pre-release tarball proof runs starter typecheck, DB-free smoke tests, and ztd-config before npm publication.

Verification

• pnpm --filter @rawsql-ts/ztd-cli test -- ztdVerifier.unit.test.ts init.command.test.ts publishWorkflow.unit.test.ts
• pnpm --filter @rawsql-ts/ztd-cli test -- ztdVerifier.unit.test.ts publishWorkflow.unit.test.ts
• pnpm --filter @rawsql-ts/ztd-cli exec tsc -p tsconfig.json --noEmit
• git diff --check
• node scripts/verify-published-package-mode.mjs
• Manual generated tarball starter DB-missing UX check: pnpm exec vitest run src/features/smoke/queries/smoke/tests/smoke.boundary.ztd.test.ts now reports the target URL and recovery steps instead of a raw AggregateError. DB-backed success was not run locally because Docker reports all predefined address pools have been fully subnetted in this environment.

Merge Readiness

• No baseline exception requested.
• Baseline exception requested and linked below.

Tracking issue:
Scoped checks run:
Why full baseline is not required:

Self Review

Self-review workflow: Ran the self-review skill over starter first-run UX, prepublish proof coverage, error recovery, and claim wording.
Self-review result: No merge blockers remain; the only unconfirmed path is DB-backed success in this local Docker environment due Docker network pool exhaustion, and the generated error text now points at that recovery case.
Concept-review workflow: Checked the ztd-cli package concept/runtime-free boundary in docs/ztd-cli-docs.md against the changed starter templates and publish verification flow.
Concept-review result: No concept or package-boundary violation found; generated production code remains runtime-free and the DB/testkit pieces stay in dev/test verification paths.

CLI Surface Migration

• No migration packet required for this CLI change.
• CLI/user-facing surface change and migration packet completed.

No-migration rationale:
Upgrade note: Newly generated starters now typecheck without editing the smoke query params, and DB connection failures include direct recovery steps for Docker and ZTD_DB_PORT.
Deprecation/removal plan or issue: No deprecation or removal is introduced.
Docs/help/examples updated: Starter template behavior and published-package verification were updated; the existing starter README remains the user-facing setup guide.
Release/changeset wording: .changeset/quiet-starter-proof.md describes the ztd-cli patch release.

Scaffold Contract Proof

• No scaffold contract proof required for this PR.
• Scaffold contract proof completed.

No-proof rationale:
Non-edit assertion: Newly generated starter smoke params are valid TypeScript without hand edits; this is asserted by init.command.test.ts and the tarball starter typecheck in verify-published-package-mode.mjs.
Fail-fast input-contract proof: ztdVerifier.unit.test.ts covers AggregateError-style Postgres connection failures and asserts the starter recovery message includes the target and next steps.
Generated-output viability proof: node scripts/verify-published-package-mode.mjs now proves the generated tarball starter by running pnpm exec tsc --noEmit -p tsconfig.json, DB-free smoke tests, and ztd-config after dependency rebinding.

Summary by CodeRabbit

Release Notes

• Bug Fixes

  • Improved error handling for Postgres aggregate connection failures with concise recovery instructions.
  • Better error message aggregation from nested error structures.

• New Features

  • Extended publish-time artifact verification to include starter type-checking, smoke tests, and configuration validation before release.

• Tests

  • Added comprehensive test coverage for database connection failure scenarios.
  • Enhanced test assertions for starter initialization flow.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: fe7b3f69-251f-4570-9142-717247de1cf6

📥 Commits

Reviewing files that changed from the base of the PR and between 1e8f4c1 and ab62ac5.

📒 Files selected for processing (7)

• .changeset/quiet-starter-proof.md
• packages/ztd-cli/templates/src/features/smoke/queries/smoke/boundary.ts
• packages/ztd-cli/templates/tests/support/ztd/verifier.ts
• packages/ztd-cli/tests/init.command.test.ts
• packages/ztd-cli/tests/publishWorkflow.unit.test.ts
• packages/ztd-cli/tests/ztdVerifier.unit.test.ts
• scripts/verify-published-package-mode.mjs

---

📝 Walkthrough

Walkthrough

This PR tightens the starter first-run flow by broadening the smoke-query parameter type contract to allow additional properties, improving Postgres connection-failure error diagnostics with recursive detection and aggregated recovery guidance, and extending publish-time verification to include TypeScript compilation and targeted smoke tests.

Changes

Starter Quality and Recovery

Layer / File(s)	Summary
Query parameter type broadening packages/ztd-cli/templates/src/features/smoke/queries/smoke/boundary.ts, packages/ztd-cli/tests/init.command.test.ts	SmokeQueryParams interface now extends Record<string, unknown> to explicitly allow additional key-value pairs alongside user_id: number. Init test verifies the broadened interface contract.
Postgres connection-failure recovery wrapping packages/ztd-cli/templates/tests/support/ztd/verifier.ts, packages/ztd-cli/tests/ztdVerifier.unit.test.ts	Verifier assertion patterns changed to directly await and assert results. New describeStarterDbOriginalError helper extracts aggregated error messages from nested errors arrays or fallback to Error.message. isStarterDbConnectionFailure detects failures recursively via errors arrays and cause chains. Wrapped error messaging includes concise docker compose and ZTD_DB_PORT recovery instructions. Unit test verifies AggregateError with nested ECONNREFUSED failures triggers recovery guidance.
Publish-time starter verification extension scripts/verify-published-package-mode.mjs, packages/ztd-cli/tests/publishWorkflow.unit.test.ts	verifyPnpmStarterPath adds TypeScript compilation (tsc --noEmit) and runs Vitest for two smoke test files after scaffold install, then continues with ztd-config validation. publishWorkflow.unit.test.ts asserts these checks appear in starter section and refines exec-pattern assertions.
Release notes and versioning .changeset/quiet-starter-proof.md	Changeset documents patch release bump for @rawsql-ts/ztd-cli covering starter typecheckability, improved Postgres aggregate error wrapping, and expanded publish-time verification.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• mk3008/rawsql-ts#845: Both PRs directly modify the ZTD verifier's starter Postgres connection-failure handling in packages/ztd-cli/templates/tests/support/ztd/verifier.ts, improving how errors (including unreachable/connection failures) are detected and wrapped with recovery guidance.
• mk3008/rawsql-ts#817: Both PRs modify scripts/verify-published-package-mode.mjs's verifyPnpmStarterPath by extending starter scaffold smoke/typecheck validation steps.
• mk3008/rawsql-ts#763: Both PRs change publish-time verification logic in scripts/verify-published-package-mode.mjs and corresponding publishWorkflow.unit.test.ts expectations for starter artifact validation.

Poem

🐰 A starter blooms with broader bounds,
QueryParams now knows unknown grounds,
Connection woes get kind recovery,
Docker's just a hop away, you see,
TypeScript proves the smoke rings true!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: tightening the ztd starter's prepublish UX proof.
Description check	✅ Passed	The description is comprehensive and well-structured, covering all required sections with detailed verification steps, merge readiness, CLI migration, and scaffold contract proof.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/prepublish-ztd-starter-ux

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

packages/ztd-cli/templates/src/features/smoke/queries/smoke/boundary.ts

Parsing error: "parserOptions.project" has been provided for @typescript-eslint/parser.
The file was not found in any of the provided project(s): packages/ztd-cli/templates/src/features/smoke/queries/smoke/boundary.ts

---

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 and usage tips.}