fix(applications): explain a git deploy with no root package.json

[dawsontoth]

📦 This PR now carries #1871 too

Rebased into 7 linear, signed commits on current stage, with no merge commits:

PR	Change	Issue
#1841	explain a git deploy with no root package.json	Closes #1699
#1871	show a failed import or redeploy once, and keep a failed import beside its form	#1833 (closed)

Both were ported onto the deploy code that landed with the polling → deploy stack (rollout-job following, deployRequestBody, staged releases, resend-only-on-4xx). The ported end state of each PR is exactly what was gated before the rebase.

Also resolves #1868's open ❓: import and both redeploy paths now await mutateAsync. So an outcome that settles after the form or modal is gone, including a followed rollout that is still pending, still replaces the loading toast and gets reported. The deploy mutation sets skipGlobalErrorToast and reports to RUM once, which also removes the double toast on rollout failures.

Left out on purpose: during the port, rememberedClusterDeepLink.test.ts got a 30s timeout to get past a flaky hook. That file stays as on stage, where #1918 fixed the flake properly.

Gate on the final tree: tsc -b, oxlint, dprint check, vitest 462/462 files.

---

⊙ Problem

Importing a git repository with no package.json at its root fails with Node's raw ENOENT: no such file or directory, open '/tmp/harper-git-clone-oXPS7c/package.json', and Studio showed that verbatim everywhere a deploy failure surfaces. That covers the import and redeploy toasts, the global mutation toast, the redeploy progress panel, and Config > Deployments' error panel and Activity log. The text names a temp directory on the Harper node that is deleted moments later, and says nothing about the actual problem. #1699 measured 19 of these across 4 sessions in 30 days, with one user retrying the same import 9 times.

The root cause is in Harper. packGitReferenceWithoutScripts reads the clone's package.json without checking it exists (harper components/Application.ts:555, still the case at v5.3.1), and the same text reaches the 500 body ({ error }, operations.js:1083), the streamed error event (:1101, which the recorder also appends to event_log), and the deployment record. I filed that as HarperFast/harper#3142 (P2) and changed nothing in harper.

❓ Your call: This is a Studio-side workaround for a Harper bug. I think it is worth carrying, because Harper versions already deployed will keep sending the raw text after #3142 ships, and the workaround keys on one message and fails open (an unrecognized message renders as before). The alternative is waiting on #3142 alone, which leaves every deployed version unexplained. To remove it later, delete one module and its two call sites.

💡 Solution

A new explainDeployFailure module recognizes the failure (ENOENT plus a harper-git-clone-* directory's package.json) and substitutes guidance: "This repository has no package.json in its root folder. Harper deploys a git repository as an npm package, which needs one there, so add a package.json to the root of the repository and deploy again."

• At the source. onDeployComponentSubmit rethrows every failure through it, so each consumer of the rejection gets the guidance: the import toast, the redeploy toast and progress panel, and the global mutationErrorHandler toast that the issue's triage didn't name. Each error keeps its type and envelope. A streamed SSEOperationError stays one, because RUM redaction keys on that name, and keeps its code, phase and deployment id. A buffered AxiosError keeps its status, config and body shape: error carries the guidance and the other text fields that could carry the raw message are dropped.
• For stored records. Config > Deployments maps the deployment's error panel and its Activity log entries the same way. The log renders events as JSON, so the matcher tolerates a Windows separator doubled by that encoding.

⚖️ Alternatives

• Map the text at each render surface (the issue's suggested spot, DeployProgress and useImportApplication). Rejected: it misses the global mutation toast, which shows the same raw text a second time for every deploy failure, and it would repeat the call in four places.
• Strip only the path and keep Node's sentence. Rejected: "no such file or directory, open …/package.json" still doesn't say the repository needs a root package.json.
• Stop the deploy mutation's global toast as well. That is a behavior change with its own RUM-report wiring, so it is split out to A failed app import or redeploy shows two error toasts, and the import's only failure display fades #1833, along with [RUM] Git deploy with no root package.json shows a raw ENOENT naming a server temp path — 19 events, 4 sessions, 2 mid-onboarding #1699's third suggestion (a persistent failure panel on the import form instead of a fading toast).

🔧 Changes

• explainDeployFailure.ts (new): the matcher, the guidance, explainDeployFailureText for plain text, and explainDeployFailure for a thrown error.
• deployComponent.ts: onDeployComponentSubmit wraps the existing body (renamed deployComponent, unchanged) and rethrows through explainDeployFailure.
• DeploymentDetail.tsx: the error panel and the Activity log run their text through explainDeployFailureText.

✅ Verification

• explainDeployFailure.test.ts covers Linux, macOS and Windows clone paths, a wrapped and a multi-line message, an event serialized as JSON, and look-alikes it must leave alone (another file in the clone, a package.json elsewhere, the SSH-access failure). It checks that a streamed error keeps its type and details, that a buffered error keeps its status, config and body shape across { error }, { error, message }, Problem Details and string bodies, and that other errors pass through untouched.
• deployComponent.test.ts checks that a streamed and a buffered deploy reject with the guidance. It also drives a real QueryClient with the app's mutationErrorHandler and checks that the global toast shows the guidance.
• DeploymentDetail.test.tsx renders a failed deployment whose record and event_log carry the raw text (mirroring what Harper writes), with Linux and Windows paths, and checks that the clone path appears nowhere.
• Fails on base: against origin/stage's deployComponent.ts and DeploymentDetail.tsx, 4 tests fail showing the raw ENOENT / Request failed with status code 500 / the clone path in the DOM.
• Mutation-checked: 13 guards, each reverted turns at least one test red. They are SSE mapping, SSE type kept, the message field, title/detail, the clone-directory anchor, the Windows separator, the doubled separator, dotAll, the AxiosError envelope, the body shape, title removal, and both DeploymentDetail call sites.
• Gates: the pre-commit hook ran the full suite (397 files, 3,683 passed, 11 skipped), plus tsc -b, oxlint and dprint check, all exit 0.
• End-to-end route: not exercised against a live instance. The global-toast path runs through the real React Query mutation cache and the app's handler; the Harper message and body shapes are cited to source above.
• Cross-model review, three rounds (codex graded + gemini). Round 1 led to keeping the AxiosError envelope instead of a plain Error, reading Problem Details fields, the doubled Windows separator, dotAll, and trimmed comments. Round 2: codex found nothing and ruled round 1 resolved. Gemini's point that rebuilding the body dropped Harper's other fields was taken. Its per-render regex "major" was rejected: a linear scan over a bounded log. Round 3: no findings from either leg. The Cursor legs could not fetch (1Password SSH agent refused) and the Harper domain adjudicator failed on an expired OAuth session, so no round was adjudicated.
• gemini-code-assist feedback: fixed one, declined one. The explained Axios body now omits message/title/detail instead of setting them to undefined, and the body-shape test uses toStrictEqual, which the old code fails (0efc440). Declined adding an undefined overload to explainDeployFailureText: JSON.stringify is typed string, and an absent entry.data passes through unchanged and renders nothing, as on stage. The fix changes no consumer-visible output (describeError and JSON.stringify read both shapes identically), so no further cross-model round ran.

Related issues: HarperFast/harper#3142 (root cause), #1833 (duplicate and fading deploy-failure toasts).

Closes #1699

🤖 Generated with Claude Code

Related PRs: none found
Complexity: medium

_{Review-Coverage: authored=claude; ran=gemini,codex; blocked=cursor-composer(no-receipt),domain(auth); declined=cursor-grok,cursor-kimi,cursor-muse; rounds=3; full=1 @ 0efc440}

_{Review-Attention: read ~3m (raised: degraded review) @ 0efc440}

[gemini-code-assist]

Code Review

This pull request introduces a mechanism to intercept and explain deployment failures caused by a missing root package.json in a git repository, replacing raw Node ENOENT errors containing temporary clone paths with a user-friendly guidance message. This is integrated into the deployment detail view, event logs, and deployment submission handlers, accompanied by comprehensive tests. The review feedback suggests updating explainDeployFailureText to gracefully handle undefined inputs to prevent potential TypeScript compilation or coercion issues, and using object destructuring to omit keys rather than setting them to undefined when rewriting the Axios error response body.

[gemini-code-assist]

In DeploymentDetail.tsx, explainDeployFailureText is called with the result of JSON.stringify(entry.data), which can evaluate to undefined if entry.data is undefined. To prevent potential TypeScript compilation errors under strict null checks and avoid fragile implicit coercion of undefined to "undefined" in RegExp.prototype.test, update the function signature and implementation to handle undefined gracefully.

export function explainDeployFailureText(text: string): string;
export function explainDeployFailureText(text: undefined): undefined;
export function explainDeployFailureText(text: string | undefined): string | undefined {
	if (text === undefined) {
		return undefined;
	}
	return MISSING_ROOT_PACKAGE_JSON.test(text) ? MISSING_ROOT_PACKAGE_JSON_MESSAGE : text;
}

[dawsontoth]

Declining. TypeScript types JSON.stringify as returning string (lib.es5.d.ts:1169), so strict null checks raise no error here and tsc -b is clean. At runtime an absent entry.data stringifies to undefined; RegExp.test coerces that to "undefined", which cannot match the ENOENT … harper-git-clone-…/package.json pattern, so the value comes back unchanged and React renders nothing. That is what stage already does (DeploymentDetail.tsx:191 renders JSON.stringify(entry.data) directly). An undefined overload would only restate that pass-through.

_{🤖 Generated by Claude Code (Claude Opus 5.5); posted via @dawsontoth.}

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	72.68%	11812 / 16251
🔵	Statements	72.77%	12585 / 17293
🔵	Functions	67.32%	3138 / 4661
🔵	Branches	68.57%	9318 / 13589

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/features/instance/applications/components/DeployProgress/DeployProgress.tsx	84.21%	76.54%	83.33%	84.21%	57, 106-138, 284
src/features/instance/applications/components/NewApplication/ImportInstructions.tsx	60%	70%	42.85%	60%	37, 95-132, 166-176
src/features/instance/applications/components/NewApplication/index.tsx	67.56%	60%	83.33%	66.66%	36, 41-42, 49-53, 85-97
src/features/instance/config/deployments/components/ActivateStagedRelease.tsx	100%	78.57%	100%	100%
src/features/instance/config/deployments/components/DeploymentDetail.tsx	55.55%	52.7%	54.54%	57.14%	58-82, 87, 90, 185-206
src/integrations/api/instance/applications/deployComponent.ts	96.29%	100%	85.71%	96.29%	126-130
src/integrations/api/instance/applications/explainDeployFailure.ts	100%	100%	100%	100%

Generated in workflow #2265 for commit 7233fb0 by the Vitest Coverage Report Action