Repository navigation
feat(desktop): accept kirocrew://apps/detail/<name> deep links - #26281
Conversation
Design Review (Opus 5.5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the change adds one allowlisted deep-link shape that rebuilds the route from a validated name, and it relies on the existing router-state-only Notes
[DESIGN-REVIEWED] 30b7fbe Description read[DESCRIPTION-READ] b491641489afb89edb1d7e6e877c88bcb924ee858f0d8312414ddc2267c3e00a That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
UX Review (Opus 5.5, fork) — ✅ PASSUX-level review of UX-Verdict: PASS No new control, label or string; the link opens the existing app detail page and reuses the session link's pane switch and leave prompt. Notes
[UX-REVIEWED] 30b7fbe Description read[DESCRIPTION-READ] b1b02803f481dc9eb8dd09dc5bb1c6e48fbca51413e25bb21cf7bc241e4aca4b That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed |
First Principles Review (Opus 5.5, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. The PR adds one deep-link shape next to the existing ones and changes no default. Every item fixes a nameable problem with nothing else already doing that job. The What this change shipsInventory (6 items) — 6 justifiedIntent: let a companion program on the same machine send the user straight to one app's detail page in the desktop app, for example to grant a dashboard-only consent. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 30b7fbe Description read[DESCRIPTION-READ] f98d4e618639c6db6f6cdcd9225d3649d0fab93d4ed179de70bf75c6222f6cee That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review (fork) — ✅ no blocking findings (all downgraded on adjudication)Reviewed Opus 5.5 adjudication downgraded every blocking finding. Downgraded: the remedy each one needs is disproportionate to the harm it prevents. Adjudication downgraded all 1 blocking finding(s): the remedy each one requires is disproportionate to the harm it prevents. Review detailsBLOCKING -- website/src/shell/appShell.tsx:855 -- Commit the local-pane switch before invoking its leave guard
Adjudication (Opus 5.5) — is blocking on each finding proportionate?F1: LOW harm. The failure needs two things: a Remote Crew pane is active and the local pane has an unsaved draft (diff |
f4e5605 to
6752170
Compare
1fe3767 to
7e73d06
Compare
7e73d06 to
12d4c22
Compare
12d4c22 to
c73b790
Compare
c73b790 to
dbcfe04
Compare
510ab82 to
7396367
Compare
bolichen97
left a comment
There was a problem hiding this comment.
Thanks for the update. Re-checked at 7396367. The deep-link name check is still plain logic, and the shared app-name-samples.json fixture keeps the two sides in step.
One small thing, under our no-new-regex rule: this head adds a new regex in test/test_cli_open.py:
match = re.search(r"const APP_NAME_MAX_LENGTH = (\d+);", source)It parses JS source text to find the constant. An exact string check does the same job with no pattern:
expected = f"const APP_NAME_MAX_LENGTH = {manifest_names.APP_NAME_MAX_LENGTH};"
assert expected in source, "deep-link.js APP_NAME_MAX_LENGTH differs from the manifest cap"Another option is to put the cap in app-name-samples.json and have both test suites read it from there.
With that swapped, I'll approve once CI is green.
|
Correction to my last review: the I'll approve once the remaining checks on 7396367 are green. |
|
Thanks for re-checking, and for the quick correction on the test-file regex. No change made there. Everything on What changed since your first review:
Ready for your approval when you have a moment. |
ca4f1aa to
eafaff8
Compare
|
Backend Tests (3.12, 2) and (3.12, 4) are red at
|
The kirocrew:// scheme accepts two shapes: a bare link that raises the window, and chat?sid=<key> that opens one session. A companion program whose app needs the user's attention on its own detail page (to review it, or to grant a permissions.sessionApproval consent that only the dashboard can grant) has no link to send them there, so it falls back to raising the window and describing the clicks through the store. Add a third allowlisted shape, kirocrew://apps/detail/<name>, resolving to /apps/detail/<name>. The name is checked against the manifest's own app-name grammar (KEBAB_RE in manifest_names.py) with a length bound, the route is rebuilt from the validated name rather than copied, and a query parameter, a fragment, an extra segment or any other apps/ path (the store pages, the app's own page) is still refused. The detail page takes its install, update and enable trigger from router state only, so a link can show the page and nothing more: the click stays the user's. The handler, main.js, the preload and the renderer are unchanged: the route travels the same hold-until-navigate-ready path and the same guarded navigate as a native menu entry. kirocrew open gets no flag for it; a program that wants the link opens the URL itself. Docs move in the same commit: the Electron README names the three shapes, the cli.md row that owns the resolver's grammar names this one, and the apps and manifest-reference docs tell users and app authors.
eafaff8 to
30b7fbe
Compare
bolichen97
left a comment
There was a problem hiding this comment.
Approving 30b7fbe as maintainer. All 95 checks pass. This replaces my change request on 7396367.
That review asked about a re.search in test/test_cli_open.py. Our no-new-regex rule covers product code only, so a pattern in a test is not a blocker. I'm withdrawing that point, and you don't need to change it.
What I checked in the product code:
resolveDeepLinkaccepts exactly one new shape,kirocrew://apps/detail/<name>: two path segments, the firstdetail, no query parameters. Anything else is refused with a reason. The route is rebuilt from the parsed name, never copied from the input.isAppNamechecks the manifest's kebab grammar with plain logic: dash-separated non-empty parts ofa-zand0-9, length capped at the manifest'sAPP_NAME_MAX_LENGTH(128). So a percent-encoded segment is refused, not decoded, and the sharedapp-name-samples.jsonfixture keeps both sides in step.- The link only shows the detail page. Install, update and enable stay router-state triggers, so the click stays the user's.
- Over a Remote Crew pane,
appShellbrings the local Crew forward first, as a session link does.
|
Problem / Motivation
Goal: A program on the same machine can send the user to one app's detail page in the desktop app with
kirocrew://apps/detail/<name>, instead of raising the window and describing the clicks.The
kirocrew://scheme accepts two shapes: barekirocrew://raises the window, andkirocrew://chat?sid=<key>opens one session. Nothing points at an app. An app driven by a companion program outside the dashboard (Keeb Control and itskeeb-crewapp are the case at hand) sometimes needs the user on the app's own detail page: to grant apermissions.sessionApprovalconsent that only the dashboard can grant (kirocrew app enablerefuses it from the CLI and prints the page's link), to review a pending update, or to see what the app is. Today the program can only bring the window forward and then explain, in its own UI, where to click: Apps, Library, the tile, Details.Why it matters
The consent case is the sharp one. An app's
sessionApprovalgrant is deliberately a dashboard-only click, so a program that needs it can do nothing but describe a route through the store, and a user following a described route through an unfamiliar page is the one most likely to click the wrong thing. A link that lands on the page, and does nothing else, keeps the click where the design put it and removes the walkthrough. For app authors the scheme becomes usable for the one page that describes their app; for users the dashboard opens where they were sent. Every companion program for a path-installed app pays this on every release that changes a permission.Not a goal
AppDetailPage'sautoAction), never from a URL, because a URL-driven trigger would be reachable by a cross-site navigation with the session cookie riding along; this PR leaves that unchanged and relies on it.apps/target: not/apps(Discover),/apps/library,/apps/-/updates,/apps/migrate/<name>, and not/apps/<name>, the app's own page, where the app's code runs. The detail page is the one page that merely describes an app.settings/<tab>,artifacts/<slug>or any other dashboard route. The allowlist grows by exactly one shape; the pins that refuse those stay.--app NAMEflag onkirocrew open. A program that wants the link opens the URL itself (open,xdg-open,start).deep-link-handler.js,main.jsandpreload.jsare untouched. The renderer changes only so an app detail link is visible over a Remote Crew pane.What changed (motivation → approach → change)
A companion program can now open one app's detail page with
kirocrew://apps/detail/<name>. The link only navigates: it never installs, updates or enables anything.The approach:
website/electron/deep-link.jsalready decides which URLs may drive navigation, as a deny-by-default allowlist that rebuilds each route from validated pieces. The new shape lives there and nowhere else. Two alternatives were rejected: accepting any/apps/...path (the store pages act on apps, and/apps/<name>runs the app's code) and a flag onkirocrew open(the URL is one line in the calling program).deep-link.js)appswith exactlydetail/<name>, no query, no fragment.<name>is checked byisAppNamewith plain logic, no regex: at most 200 characters, split on-into non-empty parts made only ofa-zand0-9. That is the manifest's kebab-case grammar (KEBAB_RE). A percent-encoded name is refused, not decoded. The chat shape resolves exactly as before.website/src/shell/appShell.tsx,website/src/utils/navIntent.ts)website/electron/README.md, thekirocrew openrow indocs/system-specs/modules/cli.md, the Detail row insrc/kiro_crew/docs/apps.md, and thesessionApprovalnote indocs/app-kit/manifest-reference.mddescribe the link.As for a session link, the handler holds the link until the dashboard reports
navigate-ready.Not a product-shape change: no default changes and nothing user-facing is removed or replaced, so no RFC is cited.
Backwards compatibility
Compatible: both existing shapes resolve exactly as before, and the pre-existing resolver and handler tests pass unchanged apart from one
describetitle.refuse()'s reasons are only logged. The renderer change applies only to/apps/detail/<name>paths, which no native sender produced before this PR.Removes nothing: the diff adds one accepted shape, its renderer handling, tests and docs; no route, key, record or function is hidden, removed, renamed or tightened.
Tests
website/electron/test/deep-link.test.jsanddeep-link-handler.test.js(65 cases undernode --test):apps/detail/<name>resolves to/apps/detail/<name>with no session; a trailing slash and an upper-case host are normalised as for chat._, leading, trailing or double hyphens,.,%2Dand 201 characters are refused; 200 characters are admitted.apps,apps/library,apps/-/updates,apps/<name>,apps/migrate/<name>,apps/detail,apps/detail/<name>/settings,?autoAction=install,?sid=x,#enable, a port, and dot-segment traversals.navigate-readyand delivered once, like a session link.website/src/test/App.navLeaveGuard.test.tsx:activeIdand lands on/apps/detail/demo-app.website/src/test/popoutNavForwarding.test.ts:isAppDetailPathaccepts/apps/detail/<name>and rejects/apps/detail/,/apps,/settings/aboutand a chat path that carriesapps/detailin its query.website/electron/test/fixtures/app-name-samples.jsonlists valid and invalid app names.deep-link.test.jsruns each one throughisAppNameandtest/test_cli_open.pyruns each one through the manifest'sKEBAB_RE, so the two grammars cannot drift apart.test_cli_open.pyalso checks thatdeep-link.jshas noAPP_NAME_RE.Proof: not provable -- frontend test (prove.py runs Python only). By hand: with the
appShell.tsxswitch removed, bothApp.navLeaveGuardapp detail tests fail (expected 'remote-1' to be null) and pass with it restored.Results on macOS: vitest 110 passed across
App.navLeaveGuard,popoutNavForwarding,App.shell.ownersandAppRootCoverage;test/test_cli_open.py20 passed; the two Electron deep-link suites 65 passed; eslint and flake8 clean.Manual verification
Still required. The shape needs a packaged build: a dev run (
process.defaultApp) deliberately registers no scheme, and an installed build predates this branch.npx electron-builder --mac --dir, then copy the bundle to/Applications), with at least one app installed. From a terminal:open "kirocrew://apps/detail/<name>"(macOS;xdg-open/startelsewhere). Expect the window to come forward on that app's detail page and nothing else to happen: no install, update or enable starts.navigate-ready).open "kirocrew://apps/detail/<name>?autoAction=install", thenopen "kirocrew://apps/library". Expect no navigation, and the desktop launch log to carrydeep link refused (unknown query parameter)anddeep link refused (unknown route)with the URL's length, never its text.Screenshots / video
Why no screenshot: No component, layout or string changes; the link opens the existing
/apps/detail/:namepage as a sidebar click does, and over a Remote Crew pane it selects the existing local Crew pane first.Related Issues
Related: #23197 (shipped the
kirocrew://scheme asda4eb1c32a; its stated scope stopped at two shapes and framed any further route as a deliberate allowlist change, which this PR is) and #23195 (its originating issue). No issue is linked.Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributed under the project's Apache-2.0 license, per the Licensing section of CONTRIBUTING.md.