Add /deeplink/* redirect route

[claude]

Requested by Chris Arderne · Slack thread

Before: there's no stable URL you can put in docs, an email or a Slack message that lands someone on their own project's API keys page — every dashboard URL contains the org, project and environment slugs, so you have to tell people to navigate there by hand.

After: /deeplink/apikeys resolves the signed-in user's current organization, project and environment and redirects to /orgs/{org}/projects/{project}/env/{env}/apikeys. Deeper segments are preserved (/deeplink/runs/run_abc123) and the query string is passed through. If you're not signed in, login happens first and you land on the deeplink afterwards. The preserved suffix drops . and .. segments in both their plain and escaped spellings, so a crafted URL can't escape the resolved environment path.

How

New loader-only route apps/webapp/app/routes/deeplink.$.ts, modelled on the existing redirect-only routes (orgs.$organizationSlug.projects.$projectParam.apikeys.ts, orgs.$organizationSlug.projects.v3.$.ts):

• requireUser (app/services/session.server.ts) — already redirects to /login?redirectTo=…, so the deeplink survives login.
• SelectBestEnvironmentPresenter.call({ user }) resolves org + project + environment from dashboard preferences, falling back to the most recently updated project and the user's dev/prod environment.
• The suffix is resolved by resolveDeeplinkPage against ENV_PAGE_TARGETS in app/utils/deeplinkPages.ts, which mirrors the environment layout's routes (_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.*).
• An unrecognised first segment redirects to the environment root — a user-supplied path is never used as the redirect target. The query string survives either way, so /deeplink, /deeplink/nonsense and /deeplink/tasks all behave alike.
• A user with pending invites goes to invitesPath() first, mirroring _app._index/route.tsx — a deeplink is exactly the URL a new invitee is sent, and without this they were offered organization creation while their invite sat unaccepted.
• If the user has no projects the presenter throws, and we branch to newProjectPath / newOrganizationPath exactly like _app._index/route.tsx does.
• The suffix is read from new URL(request.url).pathname rather than the splat param, which React Router decodes. The dashboard writes a task id containing a slash as group%2Fmy-task, and the decoded param split that into two segments that matched no route. Segments are passed through as they arrived — re-encoding would turn %2F into %252F.

Why the map has two paths per entry

Most names are a page in their own right. Three segments under the environment layout are not — they exist only as the parent of param or child routes, so a bare URL matches no route and would 404:

name	bare URL resolves	landing	prefix for deeper segments
tasks	no (only tasks.dashboard, tasks.{standard,scheduled}.$taskParam, tasks.stream)	the environment root	tasks
waitpoints	no (only waitpoints.tokens[.$waitpointParam])	waitpoints/tokens	waitpoints/tokens
metrics	no (only metrics.$dashboardKey, metrics.custom.$dashboardId)	— dropped	—

So each entry carries a landing used for a bare /deeplink/<name> and a prefix that deeper segments hang off; for an ordinary page both are just the name. The two differ only where the page and the things underneath it live in different places: the task list is the environment root (that route is the env _index, titled "Tasks") while task detail pages are under /tasks. A single "prefix the target" rule would fix waitpoints and break tasks. metrics is left out entirely — it's only a legacy 301 shim to dashboards with no page of its own, so it falls back to the environment root rather than being given an invented target. A suffix that already spells out a path under the prefix is kept as written, so the shorthand /deeplink/waitpoints/waitpoint_123 and the longhand /deeplink/waitpoints/tokens/waitpoint_123 agree.

ENV_PAGE_META in app/components/navigation/favoritePages.tsx looked like the natural source for this list, but it only lists segments that need an icon and a label — tasks, agents and settings get theirs from special cases when resolving page metadata — and it says nothing about whether a segment resolves on its own. The route files answer both questions, so they are the source of truth.

No /_/ alias. No route file in apps/webapp/app/routes uses Remix's […] character escaping, so there's no in-repo precedent confirming that a literal underscore segment ([_].$.ts) behaves as intended on Remix 2.17.4 — a bare _ prefix means "pathless" in the flat-route convention. Rather than guess, the alias is left out; it can be added later if we verify the escaping.

No project-picker fallback page. The presenter always resolves something for a user with at least one project, and the zero-project case already has a well-defined destination (create project / create org), so an intermediate "which project did you mean?" page would never be shown in practice.

✅ Checklist

• I have followed every step in the contributing guide
• The PR title follows the convention.
• I ran and tested the code works

---

Testing

pnpm run format, pnpm run lint:fix and pnpm run typecheck --filter webapp are clean. Not yet exercised against a running dashboard — worth clicking through /deeplink/apikeys, /deeplink/tasks, /deeplink/waitpoints, /deeplink/runs?statuses=COMPLETED_SUCCESSFULLY, /deeplink/runs/run_…, /deeplink/nonsense and /deeplink while signed out and signed in.

app/utils/deeplinkPages.test.ts reads the environment layout's route files and enforces the invariants that keep the map honest:

• every landing page resolves to a real route — a leaf route or an _index child, since a param route like metrics.$dashboardKey isn't somewhere you can arrive without the param;
• every deep link that can actually be made resolves, walking the real child routes under each prefix rather than probing one synthetic segment (names whose children are all literal, like settings/general and alerts/new, need that);
• every segment that resolves on its own has a deeplink name, so a new page can't be quietly forgotten.

Deliberate exclusions are named in the test: _index (the environment root, which tasks already points at) and queues_ (Remix's layout-opt-out spelling of queues, not a distinct URL). Failures name the offending entry.

Traversal is covered in both spellings, because the two escapes behave differently and it's worth knowing which layer stops each. %2F survives in pathname, so an escaped slash inside an id stays one segment. %2e%2e does not: WHATWG normalises it to .. and resolves it, so /deeplink/runs/%2e%2e/%2e%2e/etc reaches the loader as /etc — outside the prefix, and treated as no suffix. Individually, a segment is dropped when it is ./.., when it decodes to one, or when it isn't decodable. Both parser behaviours are asserted rather than assumed. The redirect loader itself is still untested: there is no existing pattern for testing a redirect-only Remix loader in this repo.

---

Changelog

Short links like /deeplink/apikeys now take you straight to that page in your current project and environment (.server-changes/deeplink-routes.md).

---

Generated by Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6b2e0f9

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[claude]

@coderabbitai review

---

Generated by Claude Code

[github-actions]

Observability map

As of c72f501.

18/100 over 413 measured of 429 entry points (base 18, no change)

What this PR changed

route	base	head	now failing
/deeplink/:	new	0	error-classification, request-context

FIX FIRST

• /api/v1/projects/:projectRef/envvars (sensitive) - auth-boundary, request-context
• /auth/sso (sensitive) - auth-boundary, request-context
• /_app/orgs/:organizationSlug/settings/team (sensitive) - error-classification, auth-scope, request-context

AUDIT 3 of 50 sensitive mutations record an actor. 47 without one.
CONTEXT 11 of 413 entry points name a tenant on a failure path. 325 appear only here, 39 of them sensitive, in the JSON rather than the fix list.

What the score is made of

CHECKS
  error-classification  168 applicable,  94 pass,   0 sole, global without it 10
  auth-boundary          62 applicable,  57 pass,   0 sole, global without it 15
  auth-scope             19 applicable,  17 pass,   0 sole, global without it 18
  request-context       413 applicable,  11 pass, 223 sole, global without it 64
  audit-trail            50 applicable,   3 pass,   0 sole, not in the score

The score and findings here are report-only and never gate the merge. Separately, a required test suite keeps this tool's symbol and route lists in sync with the code they name, and can fail a pull request that renames or removes a symbol they reference, or that adds the first route with a segment they anticipate. Each failure names the list to edit. The rules and their reasons: internal-packages/observability-map/README.md.