astro-dev-edit 0.11.0

package/src/server/page-source-routes.ts

@@ -0,0 +1,71 @@
+import type { AstroIntegrationLogger } from 'astro';
+import type { PageSourceRequest, PageSourceResponse } from '../shared/protocol.ts';
+import type { OptionsResolver } from './options.ts';
+import type { RouteManifest } from './route-manifest.ts';
+import type { Route } from './router.ts';
+
+/**
+ * The page-source route group (/page-source) — "which file is the page I am
+ * looking at written in?", for the admin bar's *Open page source*.
+ *
+ * Its own module rather than a core route because the core table is the
+ * loc-based editing flow: every route there takes a `SourceLoc` or an asset,
+ * while this one takes a **pathname** and carries its own injected capability
+ * (`route-manifest.ts`). The shape is `/inspect/open`'s — one route, one
+ * feature, sharing the `openInEditor` gate.
+ *
+ * **Resolve-only: it opens nothing.** `/open` stays the single editor-launch
+ * path behind `validateEditablePath`, which keeps the matching algorithm
+ * testable in vitest instead of spawning the developer's editor on every
+ * assertion. Read-only — no writes ever pass through here.
+ */
+
+export interface PageSourceRouteDeps {
+  logger: AstroIntegrationLogger;
+  /** Live options — `openInEditor` gates the group and can change without a
+   *  dev-server restart. */
+  optionsResolver: OptionsResolver;
+  /** Astro's route manifest, or null when there is none (a test, or an Astro
+   *  that never fired the routes hook) — answered as a refusal, not a guess. */
+  routeManifest: RouteManifest | null;
+}
+
+export function createPageSourceRoutes(deps: PageSourceRouteDeps): Route[] {
+  const { logger, optionsResolver, routeManifest } = deps;
+
+  return [
+    // Resolve a browser pathname to the source file of the route serving it.
+    {
+      method: 'POST',
+      path: '/page-source',
+      maxBytes: 64 * 1024,
+      label: 'page-source',
+      handler: async (body) => {
+        const { options } = await optionsResolver.resolve();
+        if (!options.openInEditor) {
+          return { status: 403, body: { error: 'open-in-editor is disabled by configuration' } };
+        }
+        const { pathname } = body as PageSourceRequest;
+        if (typeof pathname !== 'string' || pathname === '') {
+          throw new Error('pathname is required');
+        }
+
+        const hit = routeManifest?.forPathname(pathname) ?? {
+          ok: false as const,
+          refusal: 'no-routes' as const,
+        };
+        if (!hit.ok) {
+          // The one diagnostic anyone wants when this misfires. debug, not
+          // info: a menu click should not print to the dev server log.
+          logger.debug(`page-source: ${pathname} → ${hit.refusal}`);
+          const miss: PageSourceResponse = { file: null, pattern: null, refusal: hit.refusal };
+          // A miss is an answer, not an error — the panel says why nothing
+          // opened, the same way /classify reports a non-editable element.
+          return { status: 200, body: miss };
+        }
+        const found: PageSourceResponse = { file: hit.file, pattern: hit.pattern, refusal: null };
+        return { status: 200, body: found };
+      },
+    },
+  ];
+}

package/src/server/paths.ts

@@ -0,0 +1,219 @@
+import { chmod, realpath, rename, writeFile } from 'node:fs/promises';
+import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path';
+
+/**
+ * Path confinement and mapping helpers — the single home for every "may this
+ * path be touched?" rule. (spec §8)
+ */
+
+/** True when `abs` lies inside `root` (string-space; no symlink resolution). */
+export function insideRoot(root: string, abs: string): boolean {
+  const rel = relative(root, abs);
+  return !rel.startsWith('..') && !rel.startsWith(sep);
+}
+
+/**
+ * Resolve a client-requested upload directory, or fall back.
+ *
+ * Uploads may only land in directories the integration already treats as asset
+ * locations — otherwise a client-supplied `targetDir` would be a general
+ * "write a file anywhere under the project root" capability. Anything outside
+ * them (or escaping the root) returns `fallback` rather than throwing, so a
+ * stale or hostile request writes somewhere safe instead of failing the upload.
+ * Pure string-space, like the rest of this module. (spec §8)
+ */
+export function resolveUploadDir(
+  root: string,
+  allowedDirs: string[],
+  fallback: string,
+  requested?: string,
+): string {
+  if (!requested) return fallback;
+  const abs = resolve(root, requested);
+  if (!insideRoot(root, abs)) return fallback;
+  const allowed = allowedDirs.some((dir) => {
+    const dirAbs = resolve(root, dir);
+    return insideRoot(root, dirAbs) && insideRoot(dirAbs, abs);
+  });
+  return allowed ? requested : fallback;
+}
+
+/**
+ * Where an asset write should land — the shared rule behind `/upload` and
+ * `/unsplash/import`.
+ *
+ * Two decisions in one place. An `assetRef: 'relative'` field's asset is
+ * imported by Astro rather than served verbatim, so it falls back to the
+ * src-side dir instead of the web-servable one; and a client-supplied
+ * `targetDir` is honoured only when {@link resolveUploadDir} finds it inside a
+ * configured asset directory. Extracted rather than duplicated because a drift
+ * between two copies of this is a path-confinement bug — the exact class this
+ * module exists to centralise.
+ *
+ * `redirected` is true when a requested `targetDir` was refused, so the caller
+ * can log it: the rule lives here, the logger does not.
+ */
+export function resolveAssetTarget(
+  root: string,
+  dirs: { uploadDir: string; imageUploadDir: string; allowedDirs: string[] },
+  req: { assetRef?: 'relative'; targetDir?: string },
+): { dir: string; redirected: boolean } {
+  const fallback = req.assetRef === 'relative' ? dirs.imageUploadDir : dirs.uploadDir;
+  const dir = resolveUploadDir(root, dirs.allowedDirs, fallback, req.targetDir);
+  return { dir, redirected: Boolean(req.targetDir) && dir !== req.targetDir };
+}
+
+/** Root-relative path of a file, in posix form regardless of platform. */
+function relPosix(root: string, absFile: string): string {
+  return relative(root, absFile).split(sep).join('/');
+}
+
+/**
+ * The project's public directory as a root-relative posix prefix, with no
+ * trailing slash. Astro's `publicDir` is configurable (and reaches us as a
+ * resolved fs path), so every rule below is written against this rather than a
+ * literal `public/` — a project on `publicDir: 'static'` is otherwise told its
+ * served files live at a URL the site does not have.
+ */
+function publicPrefix(root: string, publicDir: string): string {
+  return relPosix(root, resolve(root, publicDir)).replace(/\/+$/, '');
+}
+
+/**
+ * Whether the **built** site will serve `absFile` at its {@link toWebPath} URL.
+ *
+ * Only the public directory is copied verbatim into the output. Everything else
+ * under the project root — `src/assets` above all — is served by Vite in dev and
+ * simply absent from a build, so a path pointing at it is a dev-only URL. That
+ * distinction is a property of the file, not something each call site can be
+ * trusted to re-derive; it travels to the client on `AssetInfo.servable`.
+ */
+export function isServableAsset(root: string, absFile: string, publicDir = 'public'): boolean {
+  const rel = relPosix(root, absFile);
+  if (rel.startsWith('../') || rel === '..') return false;
+  const prefix = publicPrefix(root, publicDir);
+  // A publicDir that *is* the root makes everything under it public; one that
+  // escapes the root can serve nothing.
+  if (prefix === '') return true;
+  if (prefix.startsWith('../')) return false;
+  return rel.startsWith(prefix + '/');
+}
+
+/** Map an absolute file under the project root to the path it is served at:
+ *  the public directory maps to the site root; everything else keeps its
+ *  project path (truthful in dev, and {@link isServableAsset} is what says so). */
+export function toWebPath(root: string, absFile: string, publicDir = 'public'): string {
+  const rel = relPosix(root, absFile);
+  const prefix = publicPrefix(root, publicDir);
+  return '/' + (prefix && rel.startsWith(prefix + '/') ? rel.slice(prefix.length + 1) : rel);
+}
+
+/** Why a path was refused. `outside-roots` is a *normal answer* for read-only
+ *  callers — the element belongs to a package or a non-content file, which is
+ *  information, not a fault. The others are anomalies worth surfacing. */
+export type PathRefusal = 'missing' | 'escapes-root' | 'outside-roots' | 'bad-extension';
+
+export type PathCheck =
+  | { ok: true; abs: string }
+  /** `abs` is present whenever the path resolved at all (absent only for
+   *  `missing`), so callers can tailor a message from where it landed. */
+  | { ok: false; code: PathRefusal; reason: string; abs?: string };
+
+/** True when the path lives inside an installed package. Such files are real
+ *  and readable but are never the user's own source — `astro:assets` renders
+ *  every `<Image>` through `node_modules/astro/components/Image.astro`, and
+ *  that is the path the source annotation carries. */
+export function isPackageOwned(abs: string): boolean {
+  return abs.split(sep).includes('node_modules');
+}
+
+/**
+ * Resolve and check a client-supplied source path, *without* throwing. The
+ * real path (symlinks resolved) must live inside the project root AND inside
+ * one of the configured content roots, with an allowed extension.
+ *
+ * This is the single implementation of the gate; `validateEditablePath` is the
+ * throwing wrapper over it. Read-only callers that want to answer "not
+ * editable" instead of erroring use this directly. (spec §8)
+ */
+export async function checkEditablePath(
+  root: string,
+  contentRoots: string[],
+  editableExtensions: string[],
+  file: string,
+): Promise<PathCheck> {
+  let abs: string;
+  try {
+    abs = await realpath(resolve(root, file));
+  } catch {
+    return { ok: false, code: 'missing', reason: `no such file: ${file}` };
+  }
+  const rootReal = await realpath(root);
+  const rel = relative(rootReal, abs);
+  if (!rel || rel.startsWith('..') || rel.startsWith(sep)) {
+    return { ok: false, code: 'escapes-root', reason: 'path escapes the project root', abs };
+  }
+  const inContentRoot = contentRoots.some(
+    (cr) => rel === cr || rel.startsWith(cr.endsWith(sep) ? cr : cr + sep),
+  );
+  if (!inContentRoot) {
+    return {
+      ok: false,
+      code: 'outside-roots',
+      reason: 'path is outside the editable content roots',
+      abs,
+    };
+  }
+  if (!editableExtensions.includes(extname(abs).toLowerCase())) {
+    return {
+      ok: false,
+      code: 'bad-extension',
+      reason: `files of type ${extname(abs) || '(none)'} are not editable`,
+      abs,
+    };
+  }
+  return { ok: true, abs };
+}
+
+/**
+ * Throwing form of {@link checkEditablePath} — the gate every *writing* or
+ * file-launching route passes through. Unchanged in behavior: any refusal is
+ * an Error. (spec §8)
+ */
+export async function validateEditablePath(
+  root: string,
+  contentRoots: string[],
+  editableExtensions: string[],
+  file: string,
+): Promise<string> {
+  const check = await checkEditablePath(root, contentRoots, editableExtensions, file);
+  if (!check.ok) throw new Error(check.reason);
+  return check.abs;
+}
+
+/** Owner-only. The mode for any file holding the Unsplash access key. */
+export const SECRET_MODE = 0o600;
+
+/**
+ * Write atomically: temp file in the same directory, then rename. (spec §10)
+ *
+ * `mode` rides the **temp file**, not the finished one. Chmod-ing after the
+ * rename leaves a window in which the content — for a secret-bearing file, the
+ * access key — sits on disk at the process umask, typically world-readable.
+ * `rename` then carries the temp inode's mode onto the target, so a
+ * pre-existing loose file is tightened rather than left as it was. The chmod is
+ * belt-and-braces over `writeFile`'s `mode`, which is honoured only on create:
+ * a crashed run can leave a temp file behind for this one to reuse.
+ */
+export async function atomicWrite(target: string, content: string, mode?: number): Promise<void> {
+  const tmp = join(dirname(target), `.${basename(target)}.dev-edit-tmp-${process.pid}`);
+  await writeFile(tmp, content, mode === undefined ? 'utf8' : { encoding: 'utf8', mode });
+  if (mode !== undefined) {
+    try {
+      await chmod(tmp, mode);
+    } catch {
+      // Non-POSIX filesystem; the content is written either way.
+    }
+  }
+  await rename(tmp, target);
+}

package/src/server/private-files.ts

@@ -0,0 +1,116 @@
+import type { Connect, Plugin as VitePlugin } from 'vite';
+
+/**
+ * Files this integration writes into the project root that the dev server must
+ * never hand back over HTTP.
+ *
+ * Vite serves the project root, so `.astro-dev-edit.json` — the option and
+ * field-override document `settings.ts` writes — is reachable at
+ * `GET /.astro-dev-edit.json` and at `/@fs/<root>/.astro-dev-edit.json`. None of
+ * this integration's own defences see those requests: `middleware.ts` is mounted
+ * from `astro:server:setup` with `server.middlewares.use()`, which appends
+ * *after* Vite's static and `@fs` handlers, and it only inspects URLs under
+ * `/__dev-edit` before calling `next()`. So `isLocalRequest` and
+ * `validateEditablePath` are both bypassed. (spec §8)
+ *
+ * **Why not `server.fs.deny`.** That is the obvious lever and it is a trap.
+ * Vite resolves server options with `mergeWithDefaultsRecursively`, where an
+ * array in user config *replaces* the default rather than extending it — so
+ * adding one entry would silently drop Vite's own protection for `.env`,
+ * `.env.*`, `*.{crt,pem,key,…}`, `.npmrc`, `.yarnrc.yml` and every `.git`
+ * directory. Nor can the list be extended after the fact: `fsDenyGlob` is compiled during
+ * `resolveConfig`, before any `configResolved` hook could push to it.
+ *
+ * **The seam.** A Vite plugin's `configureServer` *body* runs before Vite
+ * installs its own middlewares; only the function it returns is a post hook. So
+ * registering here — and only here — puts this guard ahead of the static and
+ * `@fs` handlers, on every Vite version Astro 5–7 pins.
+ */
+
+/** Fixed filenames, never client-supplied. Add a file here to make it unservable. */
+const PRIVATE_FILES: readonly string[] = ['.astro-dev-edit.json'];
+
+/**
+ * `atomicWrite`'s mid-write sibling, `.<basename>.dev-edit-tmp-<pid>`
+ * (`paths.ts`). It is covered for two reasons: the sibling of a secret-bearing
+ * file briefly holds that secret, and for a dotfile target the doubled leading
+ * dot (`..env.local.dev-edit-tmp-1234`) falls outside Vite's own `.env.*` deny.
+ */
+const TMP_SEGMENT_RE = /^\..+\.dev-edit-tmp-\d+$/;
+
+/**
+ * Whether a request URL names a private file, in any form the dev server would
+ * resolve: a plain root path, a `base`-prefixed one (this runs before Vite's
+ * `baseMiddleware`, so the base is still attached), `/@fs/<abs>`, with a query
+ * (`?raw`, `?import`, `?t=…`) or a fragment, and percent-encoded.
+ *
+ * Segment equality rather than path resolution: it needs no filesystem access
+ * and no knowledge of the project root or the configured base, and one rule
+ * covers every form above. Three details are load-bearing:
+ *
+ * - Split on backslash too, or a Windows `/@fs/C:\proj\…` path is one segment.
+ * - Test the raw *and* decoded spelling. Decode once, matching what Vite does:
+ *   decoding further would only over-refuse, since `%252e` reaches the
+ *   filesystem as a literal `%2e` filename. A URL that cannot be decoded is
+ *   still tested raw — Vite bails on those too, so it is not a bypass.
+ * - Compare case-insensitively, as Vite's own deny globs do: macOS and Windows
+ *   will happily serve `/.ASTRO-DEV-EDIT.JSON`.
+ */
+export function isPrivateFileRequest(url: string): boolean {
+  const path = url.split('#')[0].split('?')[0];
+
+  let decoded = path;
+  try {
+    decoded = decodeURIComponent(path);
+  } catch {
+    // Malformed escape — test the raw spelling only.
+  }
+
+  for (const candidate of decoded === path ? [path] : [path, decoded]) {
+    for (const raw of candidate.split(/[\\/]/)) {
+      const segment = raw.toLowerCase();
+      if (PRIVATE_FILES.includes(segment) || TMP_SEGMENT_RE.test(segment)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Refuse with 403 rather than 404: the filename is documented publicly, so
+ * there is no existence to conceal, and a legible refusal is worth more to a
+ * developer whose `fetch` just failed. The body never echoes the path.
+ */
+function refuse(res: Parameters<Connect.NextHandleFunction>[1]): void {
+  res.statusCode = 403;
+  res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+  res.setHeader('Cache-Control', 'no-store');
+  res.setHeader('X-Content-Type-Options', 'nosniff');
+  res.end('astro-dev-edit: this file is not served by the dev server.\n');
+}
+
+/**
+ * The guard plugin. Registered unconditionally from `astro:config:setup` — a
+ * project that disabled the editor still has the file on disk, and a protection
+ * that only appeared on some Astro versions would be a hole.
+ */
+export function createPrivateFilesPlugin(): VitePlugin {
+  return {
+    name: 'astro-dev-edit:private-files',
+    // Never part of a build; `enforce: 'pre'` sorts this configureServer ahead
+    // of other plugins', so none of them can install a file server in front.
+    apply: 'serve',
+    enforce: 'pre',
+    configureServer(server) {
+      // Registered in the hook body, NOT in a returned function: the body runs
+      // before Vite installs its static and @fs middlewares, a returned
+      // function runs after them. That ordering is the whole fix.
+      server.middlewares.use((req, res, next) => {
+        if (isPrivateFileRequest(req.url ?? '')) {
+          refuse(res);
+          return;
+        }
+        next();
+      });
+    },
+  };
+}

package/src/server/route-manifest.ts

@@ -0,0 +1,200 @@
+import { existsSync } from 'node:fs';
+import { relative, resolve, sep } from 'node:path';
+import type { PageSourceRefusal } from '../shared/protocol.ts';
+import { insideRoot, isPackageOwned } from './paths.ts';
+
+/**
+ * "Which file is this URL's page written in?" — answered from Astro's own route
+ * manifest, captured by the `astro:routes:resolved` hook in `src/index.ts`.
+ *
+ * The DOM cannot answer this. Component tags are never annotated
+ * (`annotate.ts`), so counting `data-astro-source-file` values makes a
+ * markup-dense `Nav.astro` outrank a page that merely composes components —
+ * which is exactly how *Open page source* used to pick the wrong file. Astro
+ * already knows the answer, so we ask it.
+ *
+ * Impure only in `existsSync` (injected, so tests stay pure), and injected into
+ * the middleware the way `content-config.ts` is: **every failure path is a
+ * refusal, never a throw and never a guess.** A caller handed `ok: false` tells
+ * the user why nothing opened.
+ *
+ * Three things about the matching are load-bearing, all verified against
+ * Astro's own `dist/core/routing/`:
+ *
+ *   1. **`patternRegex` matches the base-*stripped* pathname.** `getPattern`
+ *      takes `base` but only consumes it on a branch its own guard makes
+ *      unreachable; Astro strips the base before matching. So we strip it here.
+ *      `config.base` is not normalized by Astro's schema, so `docs`, `/docs`
+ *      and `/docs/` all have to work.
+ *   2. **`trailingSlash` is already baked into the regex** (`\/$`, `$`, `\/?$`)
+ *      and Astro redirects to the canonical form, so we read no config for it —
+ *      we try the pathname as given, then the slash-flipped form.
+ *   3. **Astro sorts routes by priority before the hook fires,** and its own
+ *      `matchRoute` takes the first pattern hit. We iterate in array order and
+ *      the first `page` hit wins, so an index route beats the catch-all that
+ *      also matches it.
+ */
+
+/**
+ * The four fields of Astro's `IntegrationResolvedRoute` this module reads,
+ * declared structurally rather than imported.
+ *
+ * Deliberate: `astro` is a peer over `>=5.0.0 <8`, and importing the real type
+ * would turn any field rename in any of those majors into a `typecheck` failure
+ * for a module that reads four fields. `type` is widened to `string` so Astro's
+ * own `RouteType` union can grow without breaking the hook's assignability.
+ */
+export interface ResolvedRouteLike {
+  /** The route pattern, e.g. "/articles/[...slug]". Reported, never parsed. */
+  pattern: string;
+  /** The regex Astro itself matches a base-stripped pathname with. */
+  patternRegex: RegExp;
+  /** Root-relative, forward-slashed component path, e.g. "src/pages/index.astro". */
+  entrypoint: string;
+  /** "page" | "endpoint" | "redirect" | "fallback", widened. */
+  type: string;
+}
+
+export type RouteLookup =
+  | { ok: true; file: string; pattern: string }
+  | { ok: false; refusal: PageSourceRefusal };
+
+/** A page route that renders one thing per URL. */
+export interface DynamicPage {
+  /** The route pattern, e.g. "/articles/[...slug]". */
+  pattern: string;
+  /** Root-relative, forward-slashed entrypoint. */
+  file: string;
+}
+
+export interface RouteManifest {
+  /** The file the given browser pathname's page is written in, or a refusal. */
+  forPathname(pathname: string): RouteLookup;
+  /**
+   * Every **dynamic** page route whose entrypoint is a file in this project.
+   *
+   * "Dynamic" is read off the pattern rather than the regex: a bracketed
+   * segment is how Astro spells "this route renders one of a set", and it is
+   * the only routes worth asking which collection they render. Static pages are
+   * left out because a listing route has no single backing entry, and openable
+   * is filtered the same way {@link forPathname} filters it — a package-owned or
+   * absent entrypoint is nothing a caller can read.
+   */
+  dynamicPages(): DynamicPage[];
+}
+
+export interface RouteManifestConfig {
+  /** Project root (fsPath). */
+  root: string;
+  /** `config.base`, verbatim — unnormalized, as Astro's schema leaves it. */
+  base: string;
+  /**
+   * The routes, as a **thunk**. Astro re-fires `astro:routes:resolved` on every
+   * add/unlink/change under `srcDir`, so a captured array would go stale the
+   * first time a page is added — the same reason the schema provider takes its
+   * options as a thunk rather than a value.
+   */
+  routes: () => readonly ResolvedRouteLike[];
+  /** Seam for tests; defaults to `existsSync`. */
+  exists?: (abs: string) => boolean;
+}
+
+export function createRouteManifest(cfg: RouteManifestConfig): RouteManifest {
+  const exists = cfg.exists ?? existsSync;
+
+  // "/" → "", and `docs` / `/docs` / `/docs/` all → "/docs".
+  const trimmed = cfg.base.replace(/\/+$/, '');
+  const basePrefix =
+    trimmed === '' ? '' : trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+
+  /** Browser pathname → the form Astro's own pattern regexes expect. */
+  function normalize(pathname: string): string | null {
+    let p = pathname;
+    // Defence only: location.pathname carries neither.
+    const cut = p.search(/[?#]/);
+    if (cut !== -1) p = p.slice(0, cut);
+    // Astro's dev handler decodes, and getPattern normalizes its literal
+    // segments — without both, a non-ASCII route never matches.
+    try {
+      p = decodeURI(p);
+    } catch {
+      /* keep the raw form; a malformed escape simply won't match */
+    }
+    p = p.normalize().replace(/\/{2,}/g, '/');
+    if (basePrefix) {
+      if (p === basePrefix) p = '/';
+      else if (p.startsWith(`${basePrefix}/`)) p = p.slice(basePrefix.length);
+      // Outside the configured base — not a route of this site at all.
+      else return null;
+    }
+    return p.startsWith('/') ? p : `/${p}`;
+  }
+
+  /** Root-relative, forward-slashed, or null when it is not a file we may read. */
+  function openable(entrypoint: string): string | null {
+    const abs = resolve(cfg.root, entrypoint.split('/').join(sep));
+    if (!insideRoot(cfg.root, abs) || isPackageOwned(abs)) return null;
+    if (!exists(abs)) return null;
+    return relative(cfg.root, abs).split(sep).join('/');
+  }
+
+  return {
+    dynamicPages() {
+      const out: DynamicPage[] = [];
+      const seen = new Set<string>();
+      for (const route of cfg.routes()) {
+        if (route.type !== 'page') continue;
+        if (!route.pattern.includes('[')) continue;
+        const file = openable(route.entrypoint);
+        if (file === null || seen.has(route.pattern)) continue;
+        seen.add(route.pattern);
+        out.push({ pattern: route.pattern, file });
+      }
+      return out;
+    },
+
+    forPathname(pathname) {
+      const routes = cfg.routes();
+      if (routes.length === 0) return { ok: false, refusal: 'no-routes' };
+      if (typeof pathname !== 'string' || pathname === '') {
+        return { ok: false, refusal: 'no-match' };
+      }
+      const norm = normalize(pathname);
+      if (norm === null) return { ok: false, refusal: 'no-match' };
+
+      // Variants outer, routes inner: an exact hit on the canonical pathname
+      // must beat a slash-flipped hit on a lower-priority route.
+      const variants =
+        norm === '/' ? [norm] : [norm, norm.endsWith('/') ? norm.slice(0, -1) : `${norm}/`];
+
+      for (const variant of variants) {
+        for (const route of routes) {
+          // Only pages have a template you would open. Endpoints, redirects and
+          // fallbacks are skipped rather than refused — a later route may match.
+          if (route.type !== 'page') continue;
+          // We don't own these regexes, and `.test` on a g/y one is stateful.
+          if (route.patternRegex.global || route.patternRegex.sticky) {
+            route.patternRegex.lastIndex = 0;
+          }
+          if (!route.patternRegex.test(variant)) continue;
+
+          // First hit wins, mirroring Astro's own matchRoute — so when it is not
+          // openable we say which way it failed rather than scanning on and
+          // opening some other route's file.
+          const abs = resolve(cfg.root, route.entrypoint.split('/').join(sep));
+          if (!insideRoot(cfg.root, abs) || isPackageOwned(abs)) {
+            return { ok: false, refusal: 'not-in-project' };
+          }
+          // Astro injects a default 404 page that has no file on disk.
+          if (!exists(abs)) return { ok: false, refusal: 'missing' };
+          return {
+            ok: true,
+            file: relative(cfg.root, abs).split(sep).join('/'),
+            pattern: route.pattern,
+          };
+        }
+      }
+      return { ok: false, refusal: 'no-match' };
+    },
+  };
+}