installer: report progress and reconcile ambiguous writes

[Kzoeps]

Summary

• Report per-asset install progress while keeping the JSON summary on stdout.
• Treat successful admin write statuses as success without parsing unused response bodies.
• After a write error, read the asset back and continue only if it matches the bundle; otherwise preserve the partial-failure report.
• Document the recovery behavior and include patch Changesets.

Validation

• pnpm check
• pnpm changeset status
• git diff --check

No live HappyView installation was run; the write recovery test uses a local HTTP server.

Summary by CodeRabbit

• Improvements
  • The API installer now verifies an asset after a write error and continues if the installed asset matches the expected bundle.
  • Successful writes no longer fail because of an interrupted, unused response body.
  • The installer displays concise progress updates for asset checks and installs on stderr, while keeping the final JSON summary on stdout.
• Documentation
  • Updated installer guidance to describe write verification and progress output.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
api-endpoints	Ready	Preview	Oct 6, 2026 4:58pm UTC

[changeset-bot]

🦋 Changeset detected

Latest commit: e5847ae

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@hypercerts-org/hypercerts-api	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 3029f4f5-377d-495c-917e-95caa5232389

📥 Commits

Reviewing files that changed from the base of the PR and between d3df6f5 and e5847ae.

📒 Files selected for processing (7)

• .changeset/installer-ambiguous-write-verification.md
• .changeset/installer-progress-lines.md
• CONTRIBUTING.md
• api/README.md
• api/tests/unit/tooling/installer-cli.test.js
• api/tests/unit/tooling/installer-core.test.js
• api/tooling/installer.js

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The installer now reports indexed asset-check and install progress to stderr while keeping its JSON summary on stdout. It skips parsing unused successful write responses and checks installed asset state after write errors. Tests cover progress output, read-back recovery, and interrupted response bodies.

Changes

Installer behavior

Layer / File(s)	Summary
Successful write response handling api/tooling/installer.js, api/tests/unit/tooling/installer-core.test.js	Successful asset writes and script-variable creation skip parsing unused response bodies. Cancellation errors are ignored, and tests cover an interrupted unused response body.
Failed-write verification api/tooling/installer.js, api/tests/unit/tooling/installer-core.test.js, CONTRIBUTING.md, .changeset/installer-ambiguous-write-verification.md	After a write error, the installer reads the asset back. It records the asset as changed and continues when the read-back matches the bundle; otherwise, it reports verification details with the partial-failure information.
Progress reporting and CLI output api/tooling/installer.js, api/tests/unit/tooling/installer-core.test.js, api/tests/unit/tooling/installer-cli.test.js, api/README.md, .changeset/installer-progress-lines.md	The installer reports indexed checks and installs through a callback. The CLI writes progress to stderr and retains the JSON summary on stdout. Tests verify the progress lines and parseable JSON output.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to e5847

The installer’s write-recovery behavior matches its declared-asset comparison. No merge-blocking issue was identified.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main changes: reporting installer progress and reconciling ambiguous asset writes.
Docstring Coverage	✅ Passed	Docstring coverage is 87.50% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 functions across 3 files. (4 skipped: 4 u…
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.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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.}

[sonarqubecloud]

❌ The last analysis has failed.

See analysis details on SonarQube Cloud

[Kzoeps]

Regarding SonarCloud’s analysis comment:

(reply generated by OpenAI Codex)

Fixed in e5847ae: extracted the read-back verification from writeAssets and renamed the catch binding. The current-head annotation inventory is 1/1; only the intentional sequential read-back await remains. It must finish before the installer advances to the next ordered asset. API validation/build and HTTP tests pass. SonarCloud still marks the analysis failed/cancelled, and its linked issue details are unavailable through the access here.