Repository navigation
fix(portability): code every export/import refusal, and stop rendering 5xx boilerplate - #6066
Conversation
6d70bef to
74f17c4
Compare
9475834 to
639768b
Compare
639768b to
ac67704
Compare
Open PR relationship auditThis is a consolidated, point-in-time code-level audit note. It compares complete merge-base diffs and current/merged code; it does not treat a shared topic as duplication or partial coverage as completion. Relationship findings
No PR, Issue, label, branch, or review state was changed by the relationship-note portion of this audit. |
c07de0b to
a270079
Compare
|
Rebased onto main Conflicts resolved (both generated baselines, took main's version and re-applied only this PR's own edit):
Gates run locally on changed files: black, isort, flake8, Please review the resolution. A maintainer push makes the maintainer the last pusher, so a second approver is needed under the repo's last-push rule. Reply if anything looks wrong. |
a270079 to
e11217b
Compare
|
Rebased onto Conflicts resolved
denied = await require_owner_dashboard_request(request, "portability.export")
if denied is not None:
return deniedBoth sides were kept: this PR's coded
One follow-on fix the rebase requiredThe owner gate reads Baseline numbers
Down 9, never up. Control: regenerating on a pristine Dropped from the branchThe four Tests and gates run
Per-file coverage of The earlier |
|
🤖 Kiro Crew — drive-to-green pass on head
|
|
🤖 Kiro Crew — drive-to-green pass on head 1. Screenshot evidence moved from committed PNGs to real GitHub attachments. Because the eight PNGs were now redundant, the commit that carried them 2. Every red on the previous head was the GitHub App installation rate limit, not a
Still open, and deliberately not pushed: the preview-fallback ruling. |
…g 5xx boilerplate
`error-code-baseline.json` listed `dashboard/handlers/portability.py` with
`missing_code: 9` — nine refusals whose only identity was an English sentence.
The file already had the pattern: its 413 answers
`{"error": "archive too large (max 2048 MB)", "code": "import_archive_too_large"}`.
The other nine now follow it — `auth_required` (the wire name from
`handlers_cloud.py`), `file_field_required`, `invalid_import_mode`,
`import_archive_invalid`, and one `<operation>_failed` per handler.
The two kinds of 4xx here are deliberately kept apart. `import_archive_invalid`
carries the archive validator's own finding ("manifest.json is missing"), which
is the whole value of that message; the 5xx bodies carry opaque boilerplate
("Export failed") that exists precisely so the cause stays private.
`PortabilityTab` renders `data.error || <localized fallback>`, so it preferred
that English boilerplate over a catalog string that says the same thing in the
reader's language. `refusalText()` inverts it for exactly one case — a refusal
that is BOTH coded and 5xx — leaving 4xx detail and uncoded refusals of any
status untouched. The export path is not moved: its fallback is
`resp.statusText`, so there is no localized string to prefer, and writing one
is new user-facing copy rather than this contract.
The two error render sites move to `ErrorNotice`. Editing those refusal
messages takes them out of `errors-use-error-notice`'s grandfather clause
(`website/AUTOSDE.yaml`, declared blocking): a diff that edits a hand-written
`text-danger` site's message migrates it. Both now use `variant="inline"`, so
the compact 12px row keeps its layout. Only the FAILURE branch of
`importStatus` moves — the success and progress lines are status, not errors,
and the rule says those must not be dressed as one. `askAgent` stays OFF on
both, each carrying the `No hand-off` comment the rule requires: the archive
under import lives in the file input and in `preview`, neither saved anywhere
durable, and the hand-off unmounts this tab where a `File` cannot be restored
programmatically.
The coverage baseline's `portability.py 17.0` exemption is pruned — the new
HTTP-level tests put the file well clear of the 80% per-file floor, so it no
longer needs one.
Drive-to-green (rebase onto current main): original work by Leon (leonlaiyc);
resolved the error-code-baseline.json conflict by taking main's counters and
regenerating with `python test/test_error_code_contract.py --update`
(the portability entry deleted, `missing_code` down by exactly nine). All
source changes kept verbatim. Squashed to one commit for the `PR Hygiene`
one-or-two-commit rule; the tree is byte-identical to the three-commit form.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Kiro Crew <noreply@kirodotdev.github.io>
|
Rebased onto main to resolve |
bolichen97
left a comment
There was a problem hiding this comment.
Approved after verified readiness: passed, PR Readiness success on this head, mergeable, no open change requests. [operator: bolichen97 batch review 2026-09-23]
Problem / Motivation
AGENTS.mdstates the rule directly: "Backend-owned strings have no catalogpath yet, so a new non-2xx JSON body MUST carry a machine-readable
codefield."
error-code-baseline.json— the worklist that ratchets the existingdebt down — listed
dashboard/handlers/portability.pywithmissing_code: 9.The file already had the answer in it. Its 413 answers:
{"error": "archive too large (max 2048 MB)", "code": "import_archive_too_large"}The other nine refusals across export, import and preview carried prose only.
Why it matters
Two different failures are indistinguishable to a client today. A 400 from
/api/portability/importis either a rejected mode or a rejected archive; a 500from any of the three endpoints is opaque by design. And
PortabilityTabrenders
data.error || <localized fallback>, so the English produced in Pythonwins over a catalog string that says the same thing in the reader's language —
in a dashboard translated into 12.
What changed (motivation → approach → change)
Backend. The nine refusals gain codes in the vocabulary already used here
and elsewhere in the tree:
auth_required(the wire name fromhandlers_cloud.py, on all three endpoints),file_field_required,invalid_import_mode,import_archive_invalid, and one<operation>_failedper handler —
export_failed,import_failed,preview_failed. Every prosestring is unchanged.
The two kinds of 4xx are deliberately kept apart, and this is the decision
the rest of the PR follows from:
import_archive_invalidcarries the archive validator's own finding —"manifest.json is missing". That prose is the value of the message."Export failed"— which is opaque onpurpose, so the cause stays private.
Frontend.
refusalText()inverts the preference for exactly one case: arefusal that is both coded and 5xx. There the localized fallback wins,
because the server's string says strictly less than the fallback already says.
A coded 4xx keeps its detail. An uncoded refusal at any status keeps its
message — it may be from a proxy or an edge rather than these handlers, and
there the prose can be all there is.
That is one predicate on
(code, status), not a hand-maintained list of codesthe frontend has to keep in sync with the backend.
The export path is deliberately not moved. Its fallback is
resp.statusText, not a catalog string, so there is nothing localized toprefer. Giving it one means authoring new user-facing copy in 12 languages,
which is a different change from this contract.
The user-visible effect is two error messages in the Portability tab: where a
failed import or preview read
Import failed/Preview failedin English, itnow reads the tab's own localized string.
Both banners also change shape, and that is a real visual delta rather than a
string swap. Each moves off its ad-hoc
<div className="text-danger">onto theshared
ErrorNoticecomponent (variant="inline"), so the icon becomesAlertTriangle size={14}where it wasAlertCircle size={12}, the icon-to-textgap goes
gap-1->gap-1.5, and the element gainsrole="alert"and adata-testid. The success and progress lines are deliberately left on the old<div>-- they are not errors and must not be dressed as one. No panel, layoutor theme token changed. The screenshots below show both banners in both trees, so
the icon and spacing change is visible rather than asserted.
Baseline
missing_code1117 -> 1108 -- exactly the nine -- and thedashboard/handlers/portability.pyentry is gone._compliantmoves2182 -> 2239, which is +57, not +9, and the asymmetry is worth stating:
missing_codeis the number the gate ratchets and it moves by exactly nine,while
_compliantis a whole-tree count, so regenerating it also absorbscompliant responses that landed on
mainafter the committed baseline was lastrefreshed.
(Read against this PR's own base,
cc0c8214e. An earlier revision of thissection claimed
missing_code1262 -> 1253 and_compliant1410 -> 1419 "exactly+9". All four numbers were wrong -- they matched neither the committed file nor
its base -- and the
_compliantdelta was never ±9.)Rebased onto current
maincc0c8214e. Thebaseline was regenerated from the live tree with the repo's own
python test/test_error_code_contract.py --update, never hand-merged: thetotals in this file are relative to this PR's base, so adding or reconciling
numbers across branches would be meaningless. Diffing the regenerated file
against
main's shows exactly one changed entry --dashboard/handlers/portability.py, removed -- and no other file added,removed, or changed.
missing_code, the number the gate enforces, moves byexactly nine.
Tests
test/test_api_portability.pyis new — the existingtest_portability.pycovers the zip logic, and nothing exercised these handlers over HTTP. It drives
them through an aiohttp
TestServerwith real multipart uploads, so the authand file-part paths are the ones a client actually hits.
test_every_endpoint_denies_anonymously_with_auth_requiredauth_requiredon all three endpointstest_export_failure_is_coded_and_stays_opaqueexport_failed, prose still generic, private path still absenttest_an_unrecognized_import_mode_is_codedinvalid_import_mode, four rejected modestest_an_upload_without_the_file_part_is_codedfile_field_requiredon both upload endpointstest_a_rejected_archive_keeps_the_validator_detailimport_archive_invalidalongside the validator's message — the case the frontend rule turns ontest_import_failure_is_coded/test_preview_failure_is_codedimport_failed/preview_failed, cause still not leakedtest_every_refusal_carries_a_codeRed before: with only the handler change stashed, all 14 cases fail.
Green after: 14 pass.
website/src/pages/overview/PortabilityTab.test.tsxcoversrefusalTextdirectly — 4 cases, including the two negative controls that define the rule's
edges: a coded 4xx keeps its detail, and an uncoded 5xx keeps its message.
Other gates:
test_portability.pyandtest_error_code_contract.pypassalongside the new module (68 passed / 3 skipped).
tsc -bandeslintclean;flake8,isort,mypyclean;scripts/check_black_formatting.pypasses onthe 5 changed files.
Coverage
The rebased head also tripped the Coverage Gate, in the good direction: this PR's new
test/test_api_portability.pytakesdashboard/handlers/portability.pyfrom 17.0% to 82.4%, above the 80% per-file floor, so the gate asked for its.github/coverage-baselines/backend.txtentry to be removed or the baseline stops shrinking. Pruned with the repo's own updater against that run's coverage artifact rather than a local run, whose rates differ and would prune the wrong entries. The refresh only deletes, so the diff is exactly one line.Manual verification
N/A — unit coverage sufficient: the backend tests exercise the real handlers
over HTTP including multipart, and the one user-visible surface is a string
chosen by
refusalText, which is asserted directly at every branch.Screenshots / video
Two surfaces change, and both change string and shape: the preview banner
(a refused archive preview) and the import banner (a refused import). Each is
shown before and after, in both locales -- eight images, uploaded as GitHub
attachments rather than committed, so the branch carries no binaries and the
links survive a force-push, a branch deletion and the merge.
The Japanese preview pair is the one that shows why this matters -- before, a
fully translated panel with a bare English sentence in it.
Preview refused --
500+code: preview_failedmain)Preview failed無効なアーカイブPreview failedInvalid archiveImport refused --
500+code: import_failedmain)Import failedインポートに失敗しましたImport failedImport failed-- unchanged textThe English import pair is stated plainly rather than dressed up: the catalog
string for
import_failedand the server's boilerplate are the same two words, sothat one pair shows no text delta at all. What it does show is the shape change --
AlertTriangleat 14px whereAlertCirclesat at 12px, and the wider gap. It isincluded because leaving it out would imply every locale gains a new string.
How these were captured, stated plainly: the real
PortabilityTab, the realsrc/index.cssand theme tokens, and the real i18n catalog, with the realfile-input
onChangedriven to run the real preview path and, for the importscenes, the real import path after a successful preview. The locale is switched
through
initI18n, not by faking strings. Only the network response is stubbed,to exactly what
dashboard/handlers/portability.pyanswers on its 5xx paths --{"ok": false, "error": "Preview failed", "code": "preview_failed"}at500forthe preview scenes,
{"ok": false, "error": "Import failed", "code": "import_failed"}at500for the import scenes (which first take a real200preview, since the Import button only enables once a preview succeeded) --
because a specific server response is precisely what this change is about. Each
scene asserts the banner's text and its icon class before a file is written, so
none of these eight can show a surface that did not reach the state its filename
claims.
What is actually in the diff, since an earlier revision of this section said
"only the four PNGs are in the diff" and that was wrong twice over. No image is in
the diff at all now -- the eight above are attachments. Six files:
src/kiro_crew/dashboard/handlers/portability.pywebsite/src/pages/overview/PortabilityTab.tsxrefusalText()and the two bannerstest/test_api_portability.pywebsite/src/pages/overview/PortabilityTab.test.tsxrefusalTextcaseserror-code-baseline.json.github/coverage-baselines/backend.txtAn earlier revision of this branch committed the eight PNGs under
temp-screenshots/portability-error-codes/. They are removed: the repo's ownevidence rule is that screenshots are uploaded with the description, not
committed, and the attachment URLs above are what the review lanes read.
The harness that drives the captures
(
website/capture/portability-error-banners.{html,tsx}andwebsite/scripts/capture-portability-error-banners.mjs) is temporary and isnot committed.
Related Issues
No issue — this is the
dashboard/handlers/portability.pyline item fromerror-code-baseline.json's own worklist ("drivemissing_codeto zero, one PRper file or per directory, moving each frontend consumer in the same PR").
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Pattern harvest
Rule candidate: review-prompt — the backend half of this class is already ratcheted by
error-code-baseline.json, so the part worth harvesting is the frontend rule: a client should prefer its own localized string over server prose exactly when the refusal is both coded and 5xx (where the server's text is deliberate boilerplate and says strictly less), expressed as one predicate on(code, status)rather than as a hand-maintained list of codes that has to stay in sync with the backend.Section appended by a maintainer to satisfy the
PR Hygienegate, which began requiring a Pattern harvest section onfix:PRs after this PR was opened. No other part of this description, and nothing on the branch, was touched.