Serve deeplinks from /_ instead of the deeplink literal

Escape the underscore in the route filename so it stays a literal URL
segment: a flat-route segment beginning with `_` is a pathless layout, so
`_.$` would have mounted the route at `/*`. `createRoutePath` skips a
segment only when its cooked and raw spellings both start with `_`, and
the raw spelling of `[_]` does not, so `[_].$` serves `/_/*`.

The prefix comparison no longer folds case. It existed because React
Router matches routes case-insensitively and `/Deeplink/apikeys` really
did reach the loader, but `_` has no case, so the fold is dead. Page-name
folding stays, since `/_/APIKeys` still has a route to agree with.

Drops `/deeplink/*` rather than keeping it as an alias; the route has not
shipped, so nothing links to it yet.

Author: claude

.server-changes/deeplink-routes.md

@@ -3,4 +3,4 @@ area: webapp
 type: feature
 ---
 
-Short links like /deeplink/apikeys now take you straight to that page in your current project and environment, so you no longer need the full URL with your org, project and environment in it.
+Short links like /_/apikeys now take you straight to that page in your current project and environment, so you no longer need the full URL with your org, project and environment in it.

apps/webapp/app/routes/deeplink.$.ts apps/webapp/app/routes/[_].$.tsapps/webapp/app/routes/deeplink.$.ts renamed to apps/webapp/app/routes/[_].$.ts

@@ -12,10 +12,12 @@ import {
 } from "~/utils/pathBuilder";
 
 /**
- * Stable links that don't name an org, project or environment: /deeplink/apikeys redirects to
+ * Stable links that don't name an org, project or environment: /_/apikeys redirects to
  * /orgs/{org}/projects/{project}/env/{env}/apikeys for whoever is signed in. Only the pages in
  * ENV_PAGE_TARGETS are followed, so an unrecognised path can never become the redirect target —
  * it lands on the resolved environment instead.
+ *
+ * The filename escapes the underscore for a reason — see DEEPLINK_PATH_PREFIX.
  */
 export const loader = async ({ request }: LoaderFunctionArgs) => {
   const user = await requireUser(request);

apps/webapp/app/utils/deeplinkPages.test.ts

@@ -105,7 +105,7 @@ describe("deeplink targets", () => {
   });
 
   it("every deep path lands on a real route", () => {
-    // The invariant a bare segment list could not express: /deeplink/waitpoints/{id} has to reach
+    // The invariant a bare segment list could not express: /_/waitpoints/{id} has to reach
     // waitpoints/tokens/{id}, not waitpoints/{id}. Driven off the real child routes rather than one
     // synthetic segment, so names whose children are all literal (settings/general) count too.
     const broken: string[] = [];
@@ -272,54 +272,60 @@ describe("resolveDeeplinkPage", () => {
 
 describe("deeplinkSuffix", () => {
   it("strips the route's own prefix", () => {
-    expect(deeplinkSuffix("/deeplink/tasks")).toBe("tasks");
-    expect(deeplinkSuffix("/deeplink/runs/run_123")).toBe("runs/run_123");
+    expect(deeplinkSuffix("/_/tasks")).toBe("tasks");
+    expect(deeplinkSuffix("/_/runs/run_123")).toBe("runs/run_123");
   });
 
   it("keeps an escaped slash intact, unlike the decoded splat param", () => {
-    expect(deeplinkSuffix("/deeplink/tasks/standard/group%2Fmy-task")).toBe(
+    expect(deeplinkSuffix("/_/tasks/standard/group%2Fmy-task")).toBe(
       "tasks/standard/group%2Fmy-task"
     );
   });
 
-  it("strips the prefix whatever its case, and only the prefix", () => {
-    expect(deeplinkSuffix("/Deeplink/apikeys")).toBe("apikeys");
-    expect(deeplinkSuffix("/DEEPLINK/runs/run_ABC123")).toBe("runs/run_ABC123");
-    // The remainder comes back as it was written, capitals and all.
-    expect(deeplinkSuffix("/DeepLink/tasks/standard/My-Task")).toBe("tasks/standard/My-Task");
-    expect(deeplinkSuffix("/Deeplink")).toBe("");
-    expect(deeplinkSuffix("/Deeplink/")).toBe("");
+  it("strips only the prefix, leaving the remainder's case alone", () => {
+    // The prefix has no case to fold — `_` is the same character either way — so unlike the page
+    // name there is no case-insensitive comparison here. What still matters is that the remainder
+    // comes back exactly as written, capitals and all, because ids are case-sensitive.
+    expect(deeplinkSuffix("/_/runs/run_ABC123")).toBe("runs/run_ABC123");
+    expect(deeplinkSuffix("/_/tasks/standard/My-Task")).toBe("tasks/standard/My-Task");
   });
 
-  it("folds case because the route it is mounted on does", () => {
-    // The assertion the test above rests on: React Router compiles a route path with the `i` flag
-    // unless it opts into `caseSensitive`, so a capitalised prefix really does reach this loader
-    // instead of 404ing before it. If that ever changed, the folding would be dead weight.
+  it("is mounted where the route filename says it is", () => {
+    // `[_].$` is an escaped literal, not a pathless layout: Remix's `createRoutePath` drops a
+    // segment only when the cooked and the raw spelling both start with `_`, and the raw spelling
+    // is `[_]`. A plain `_.$` would compile to `/*` and swallow the site, so this pins the prefix
+    // the loader strips to the URL the router actually serves.
     const route = `${DEEPLINK_PATH_PREFIX}/*`;
-    expect(matchPath(route, "/deeplink/apikeys")?.params["*"]).toBe("apikeys");
-    expect(matchPath(route, "/Deeplink/apikeys")?.params["*"]).toBe("apikeys");
-    // And the splat keeps the case it was given, which is why only the first segment is folded.
-    expect(matchPath(route, "/DEEPLINK/APIKeys")?.params["*"]).toBe("APIKeys");
+    expect(route).toBe("/_/*");
+    expect(matchPath(route, "/_/apikeys")?.params["*"]).toBe("apikeys");
+    expect(matchPath(route, "/_/runs/run_123")?.params["*"]).toBe("runs/run_123");
+    // The splat keeps the case it was given, which is why the loader folds only the page name.
+    expect(matchPath(route, "/_/APIKeys")?.params["*"]).toBe("APIKeys");
+    // And it is a literal segment, so it matches nothing else.
+    expect(matchPath(route, "/deeplink/apikeys")).toBeNull();
+    expect(matchPath(route, "/apikeys")).toBeNull();
   });
 
   it("treats a bare prefix, a trailing slash and anything outside it as no suffix", () => {
-    expect(deeplinkSuffix("/deeplink")).toBe("");
-    expect(deeplinkSuffix("/deeplink/")).toBe("");
+    expect(deeplinkSuffix("/_")).toBe("");
+    expect(deeplinkSuffix("/_/")).toBe("");
     // What `new URL` leaves behind once it has normalised and resolved `%2e%2e` itself.
     expect(deeplinkSuffix("/etc")).toBe("");
+    // A prefix that merely starts with the same character is not this route.
+    expect(deeplinkSuffix("/_app/orgs")).toBe("");
   });
 
   it("matches what the URL parser actually produces", () => {
     // The behaviour above is only correct if `new URL` really does keep %2F and really does
     // resolve %2e%2e, so assert that rather than assuming it.
-    const encodedSlash = new URL("http://x/deeplink/tasks/standard/group%2Fmy-task");
+    const encodedSlash = new URL("http://x/_/tasks/standard/group%2Fmy-task");
     expect(deeplinkSuffix(encodedSlash.pathname)).toBe("tasks/standard/group%2Fmy-task");
     expect(resolveDeeplinkPage(deeplinkSuffix(encodedSlash.pathname))).toBe(
       "tasks/standard/group%2Fmy-task"
     );
 
     // `%2e%2e` is normalised to `..` and resolved by the parser, leaving the prefix behind.
-    const traversal = new URL("http://x/deeplink/runs/%2e%2e/%2e%2e/etc");
+    const traversal = new URL("http://x/_/runs/%2e%2e/%2e%2e/etc");
     expect(traversal.pathname).toBe("/etc");
     expect(resolveDeeplinkPage(deeplinkSuffix(traversal.pathname))).toBeUndefined();
   });

apps/webapp/app/utils/deeplinkPages.ts

@@ -1,8 +1,8 @@
 /**
- * Where each /deeplink/<name> goes, relative to the resolved environment.
+ * Where each /_/<name> goes, relative to the resolved environment.
  *
  * Two pieces, because a name's own page and the things underneath it are not always in the same
- * place. `landing` is used for a bare `/deeplink/<name>`; `prefix` is what deeper segments hang off.
+ * place. `landing` is used for a bare `/_/<name>`; `prefix` is what deeper segments hang off.
  * They differ only where a segment is not a page in its own right:
  *
  * - `tasks` has no bare route, and the task list is the environment root — but task detail pages do
@@ -16,9 +16,9 @@
  * route files and fails if a page is missing or a target stops resolving.
  */
 export type DeeplinkTarget = {
-  /** Path for a bare `/deeplink/<name>`. "" is the environment root. */
+  /** Path for a bare `/_/<name>`. "" is the environment root. */
   landing: string;
-  /** Deeper segments are appended to this: `/deeplink/<name>/a/b` -> `<prefix>/a/b`. */
+  /** Deeper segments are appended to this: `/_/<name>/a/b` -> `<prefix>/a/b`. */
   prefix: string;
 };
 
@@ -57,27 +57,35 @@ export const ENV_PAGE_TARGETS: ReadonlyMap<string, DeeplinkTarget> = new Map([
   ["waitpoints", { landing: "waitpoints/tokens", prefix: "waitpoints/tokens" }],
 ]);
 
-/** Where this route is mounted. Matches the `deeplink.$` route filename. */
-export const DEEPLINK_PATH_PREFIX = "/deeplink";
+/**
+ * Where this route is mounted. Matches the `[_].$` route filename.
+ *
+ * The brackets are Remix's escape, and they are load-bearing rather than decorative: a flat-route
+ * segment that starts with `_` is a pathless layout and contributes nothing to the URL, so a plain
+ * `_.$` would mount this at `/*` and swallow the whole site. Escaping the underscore makes it a
+ * literal segment — `createRoutePath` skips a segment only when the cooked *and* the raw spelling
+ * both start with `_`, and the raw spelling here is `[_]`, so `[_].$` really does serve `/_/*`.
+ */
+export const DEEPLINK_PATH_PREFIX = "/_";
 
 /**
- * The still-encoded suffix after /deeplink, taken from the request's pathname rather than the
- * splat param. React Router decodes the splat, which turns an id containing an escaped slash
+ * The still-encoded suffix after /_, taken from the request's pathname rather than the splat param.
+ * React Router decodes the splat, which turns an id containing an escaped slash
  * (`group%2Fmy-task`, as the dashboard's own link builder writes it) into two segments that match
  * no route. The pathname keeps `%2F` intact.
  *
  * Returns "" for anything that is not under the prefix. That includes a pathname the URL parser has
  * already rewritten: it normalises `%2e%2e` to `..` and resolves it, so a traversal attempt can
  * leave the prefix entirely before this ever sees it.
  *
- * The prefix is matched case-insensitively because React Router's route matching is: it compiles
- * every path with the `i` flag unless the route opts into `caseSensitive`, so `/Deeplink/apikeys`
- * reaches this loader too. Only the prefix is folded — the remainder is returned as it was written,
- * since the ids after the first segment are case-sensitive.
+ * The comparison is exact, unlike the page name's. React Router still matches the route
+ * case-insensitively, but `_` has no case for it to differ in, so there is nothing to fold.
+ * The remainder is returned as it was written, since the ids after the first segment are
+ * case-sensitive.
  */
 export function deeplinkSuffix(pathname: string): string {
   const withSlash = `${DEEPLINK_PATH_PREFIX}/`;
-  if (!pathname.toLowerCase().startsWith(withSlash)) return "";
+  if (!pathname.startsWith(withSlash)) return "";
 
   return pathname.slice(withSlash.length);
 }
@@ -103,20 +111,21 @@ function isUsableSegment(segment: string): boolean {
  * first segment names no page. Returns "" for a target that is the environment root itself.
  *
  * A bare name uses its landing path. Deeper segments are grafted onto the prefix, so
- * `/deeplink/waitpoints/waitpoint_123` reaches the token that actually lives at
+ * `/_/waitpoints/waitpoint_123` reaches the token that actually lives at
  * `/waitpoints/tokens/waitpoint_123`. A suffix that already spells out a path under the prefix is
- * kept as it was written, so both `/deeplink/waitpoints/waitpoint_123` and the longhand
- * `/deeplink/waitpoints/tokens/waitpoint_123` arrive at the same place.
+ * kept as it was written, so both `/_/waitpoints/waitpoint_123` and the longhand
+ * `/_/waitpoints/tokens/waitpoint_123` arrive at the same place.
  *
  * `suffix` is expected already encoded (see `deeplinkSuffix`) and is passed through untouched — an
  * `encodeURIComponent` pass here would double-encode every id that contains an escape.
  *
- * The name is matched case-insensitively, to the same end as the prefix in `deeplinkSuffix`:
- * `/env/{env}/APIKeys` would have matched its route, so `/deeplink/APIKeys` should reach it rather
- * than falling through to the environment root. So is the written-out prefix, which is why the
- * comparison is against the lowercased path rather than the path itself — a prefix can be more than
- * one segment (`waitpoints/tokens`), and reading only `Tokens` as a segment of its own would graft
- * the prefix on top of it and produce `waitpoints/tokens/Tokens/{id}`.
+ * The name is matched case-insensitively because React Router's route matching is: it compiles
+ * every path with the `i` flag unless the route opts into `caseSensitive`, so `/env/{env}/APIKeys`
+ * would have matched its route, and `/_/APIKeys` should reach it rather than falling through to the
+ * environment root. So is the written-out prefix, which is why the comparison is against the
+ * lowercased path rather than the path itself — a prefix can be more than one segment
+ * (`waitpoints/tokens`), and reading only `Tokens` as a segment of its own would graft the prefix
+ * on top of it and produce `waitpoints/tokens/Tokens/{id}`.
  *
  * The prefix comes back in the map's own spelling and everything past it exactly as written, since
  * folding the case of a task or run id would break the link far more thoroughly than the miss this