@uppercut-labs/agent-native 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Devin Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,165 @@
-# Temporary Holding Version
+# Uppercut Agent Native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Uppercut Agent Native defines typed capability contracts once and serves them on local,
+HTTP, CLI, MCP, Node/Hono, browser, and Astro static/on-demand surfaces. It is distributed as
+`@uppercut-labs/agent-native` under the MIT license. See [installation](docs/installation.md)
+for the first programmatic capability.
+
+To expose a real operation from a working app, start with [adopt an existing site](docs/adopt-existing-site.md).
+For a coding assistant, use [the portable skill or standalone prompt](docs/for-agents.md).
+Node.js 22+ is required. Eleven entry points are stable under SemVer; browser, framework, init
+and harness integrations are experimental. See [stability](docs/stability.md). The package
+ships importable capability APIs and an app-owned CLI runner. The development branch adds an experimental [site publication CLI](docs/site-publication.md).
+
+## 1.1.0 candidate
+
+This branch builds a candidate archive for `@uppercut-labs/agent-native@1.1.0`. Install the archive from the passing production-fixture workflow run to try it before registry publication. [Site publication CLI](docs/site-publication.md) · [Eight native examples](docs/readability-frameworks.md).
+
+## Current scope
+
+UAN-001 established the strict TypeScript baseline, Zod adapter, JSON Schema projection checks,
+and stable diagnostic observations. UAN-002 adds immutable capability definitions, explicit
+runtime bindings, a checked registry, per-invocation authorization, and shared input/output
+validation. E01 exercises shared album lookup and a static Astro site integration; E12 is a
+shared unit-converter example; E05 covers local and HTTP execution through the CLI. UAN-008 adds E04, a locally verified Worker sidecar for the same E01 contract while the Astro site remains static.
+
+UAN-009 adds a programmatic, plan-first retrofit for a narrowly recognized existing Astro static
+site. It tracks owned files, rechecks the plan before applying, and protects human edits during
+restoration. The E01 check installs a local tarball into a copied site and builds the retrofit.
+See the [experimental init guide](docs/getting-started.md) for its limits; no package-level init
+command exists.
+
+UAN-010 adds trusted principal and durable grant contracts. E07 demonstrates a local persistent
+grant store with the official MCP SDK bearer gate, two fixture tenants, repeated protected edits,
+separate delete permission, restart persistence and revocation. See
+[permissions and discovery](docs/permissions-and-discovery.md). The E07 identities and store are
+test-only and refuse production mode.
+
+UAN-017 adds independent major-version composition and reviewed migration policy. V1 and v2 can
+coexist and be selected by exact identity; aliases always target one canonical major. Structural
+reports cover represented schema/risk/access changes, while semantic review and lifecycle state are
+explicit. See [composition and versioning](docs/composition-and-versioning.md) and the E08 fixture.
+
+Run `npm run example:e01`, `npm run example:e08`, `npm run example:e12`, or `npm run example:e05` to build and pack the
+package, install it independently into each example, and run its tests and runnable surface. E05
+uses one registry in a pinned Node/Hono host for generated HTTP and MCP plus local/remote CLI. E01
+also verifies a pre-existing multi-page static Astro fixture before and after integration. E04 checks a local workerd HTTP/OpenAPI roundtrip and official MCP client exchange; it does not deploy or configure DNS.
+
+E02 verifies Astro 7.3.5 on-demand routes with the official Node standalone adapter. It keeps the
+human catalog and unrelated pages prerendered while serving authenticated Agent Native HTTP and MCP
+routes from one shared contract, binding, authorization policy, and executor path.
+
+The root, `./contracts`, `./registry`, and `./executor` entrypoints use only portable core modules.
+They do not import Zod, Node, DOM, framework, provider, or server modules. Optional peers are
+installed by the host only for the adapters it imports; see [installation](docs/installation.md). `npm run check` compiles
+and scans browser output against a fake server-secret sentinel. This is a boundary regression
+check, not proof of compatibility with any real browser, client, or host.
+
+Every execution requires an `AuthorizationPort`; there is no implicit allow-all path. The executor
+checks input, authorization, handler, and output in that order. Runtime matching is exact, and
+multiple matching bindings require a `bindingId`. Durable grants are available through the
+application-owned `GrantStorePort`; production identity, persistence and resource policy remain
+host responsibilities. See [the capability and binding guide](docs/capabilities-and-bindings.md)
+for the frozen signatures and limitations.
+
+## Programmatic harness contracts
+
+The isolated `@uppercut-labs/agent-native/harness` export defines provider-neutral
+sessions, turns, feature negotiation, bounded normalized events, and stable failures.
+Harness control is a sibling of capability execution and preserves its authorization
+boundary. The Node-only `/harness/mcp-bridge` export serves an application-supplied
+MCP handler on loopback with managed cleanup. The isolated `/harness/codex` adapter
+controls an installed Codex app-server using managed ChatGPT sign-in; its local
+Luna two-turn/resume proof passed. Cursor adapters remain future work. See
+[harness contracts](docs/programmatic-harness.md) and [Codex lifecycle](docs/harness-codex.md).
+
+## HTTP and OpenAPI
+
+The separate `@uppercut-labs/agent-native/http` entrypoint provides a framework-neutral Web
+Request/Response handler. It exposes deterministic invocation routes for explicit public read
+capabilities, including validated GET overrides, generates OpenAPI 3.1 from those contracts, and serves protocol health evidence.
+Protected capability schemas and routes are omitted from this initial HTTP projection. See
+[the HTTP guide](docs/http.md) for response mappings, body/deadline limits, and integration boundaries.
+
+## Browser tools
+
+The isolated `@uppercut-labs/agent-native/browser` entrypoint feature-detects the current WebMCP
+document.modelContext API and owns registrations with an AbortSignal. It projects only definitions
+with browser bindings; public reads are exposed by default, while protected tools require an explicit
+projection policy and are still authorized on every call. Unit and example fixtures use a simulated
+API. E01 and E06 also passed against native WebMCP in Chrome 155 with its opt-in `WebMCP` feature; no
+shipping browser agent is claimed. See [the browser guide](docs/browser.md) and the
+[native Chrome evidence](docs/evidence/UAN-023-native-webmcp-chrome.md).
+
+## Astro sites
+
+The isolated `@uppercut-labs/agent-native/astro` integration injects an application-owned browser
+entry with Astro's page-script hook and validates the selected static or on-demand mode. It never
+installs a server adapter. E01 remains wholly static; E02 uses application-owned Astro endpoints and
+the official Node standalone adapter while retaining prerendered pages and navigation. See
+[static-site guidance](docs/static-sites.md), [framework support](docs/frameworks.md), and
+[UAN-007 evidence](docs/evidence/UAN-007-astro.md).
+
+## Next.js App Router
+
+The isolated `next` entrypoint adapts the existing HTTP and official MCP handlers to Next 16.3.8
+Node-runtime route exports without importing Next into core or Astro consumers. Browser bootstrap
+code lives at `next/browser` and resyncs explicitly from `usePathname()` while preserving a normal
+browser fallback. E03 retains its pre-integration fixture and verifies a generated, locked
+after-state. See [Next.js App Router](docs/next.md) and
+[UAN-014 evidence](docs/evidence/UAN-014-next.md).
+
+## Remote MCP
+
+The isolated `@uppercut-labs/agent-native/mcp` entrypoint uses the official MCP server SDK over
+Streamable HTTP. It exposes explicitly public read capabilities by default and can discover
+protected capabilities only with an explicit callback and verified auth integration. It filters
+discovery per request and reauthorizes every call through the shared executor. Results place the
+canonical value under `structuredContent.result`. See [the MCP guide](docs/mcp.md) and
+[fixture-tested compatibility](docs/compatibility.md). The fixture covers the official SDK client
+and server packages at version 2.3.0 and the negotiated protocol version 2025-11-25; this is not a
+claim that every commercial client or deployment host is supported.
+
+## Generated CLI
+
+The separate `@uppercut-labs/agent-native/cli` runner entrypoint builds help and typed field flags from registry schemas. Calls select `--mode local|remote` explicitly; remote calls also select a configured credential profile and use a bounded HTTP request. Invocations write one `uan.cli-result/v1` JSON envelope to stdout and redacted target/failure diagnostics to stderr. No package-level `bin` command ships yet; applications expose the runner with their own registry. See [the CLI guide](docs/cli.md) and the installed E05/E12 examples.
+
+## Diagnostics
+
+The `./doctor` entrypoint builds versioned findings, required-check profiles, read-only registry
+inspection, and policy-filtered capability lists. E11 packs the package into a fault/repair lab;
+its local profile reports only local evidence, and the default full profile remains incomplete
+without an explicit loopback probe. See [doctor and troubleshooting](docs/doctor-and-troubleshooting.md).
+
+## Development
+
+Requires Node.js 22 or newer and npm.
+
+```sh
+npm ci
+npm run format
+npm run format:check
+npm run lint
+npm run typecheck
+npm test
+npm run build
+npm run example:e01
+npm run example:e02
+npm run example:e12
+npm run example:e05
+npm run example:e07
+npm run check:portability
+npm run check
+```
+
+The schema spike checks album lookup and unit conversion input/output shapes with Zod 4, then
+validates exported draft-2020-12 schemas independently with Ajv. JSON Schema projection throws for
+transforms that cannot be represented faithfully. The official MCP server SDK is an optional peer required by the isolated MCP adapter; the
+official MCP client SDK is pinned for the local protocol fixture only. See [UAN-008 sidecar evidence](docs/evidence/UAN-008-worker-sidecar.md) for host/origin controls, revision matching, and local-only limits.
+
+## Status
+
+Version `1.0.1` is released under MIT. Stable entry points follow semantic versioning; see [stability](docs/stability.md) and [upgrading from 0.1.x](docs/upgrading-to-1.0.md). UAN-002 local acceptance and limitations are in
+[UAN-002 evidence](https://github.com/uppercut-labs/agent-native/blob/main/evidence/UAN-002.md); pinned tool versions and upstream references are in [VERSION-EVIDENCE.md](https://github.com/uppercut-labs/agent-native/blob/main/VERSION-EVIDENCE.md).
+The current init acceptance and limits are in [UAN-009 evidence](docs/evidence/UAN-009-init.md).
+The local trusted-auth and grant acceptance is in [UAN-010 evidence](docs/evidence/UAN-010-auth.md).

package/agent/agent-prompt-short.md

@@ -0,0 +1 @@
+Read https://docs.uppercut-labs.com/agent-native/adopt-existing-site/ and expose one existing website operation to agents in this repository.

package/agent/agent-prompt.md

@@ -0,0 +1,26 @@
+# Agent Native — website integration agent prompt
+
+**Use:** Paste the text below into your preferred coding agent alongside access to your website repository. Replace the bracketed task only if you have a specific operation in mind. The prompt works without a skill plugin or private Uppercut materials.
+
+---
+
+I want to make **this existing website genuinely agent-native** using the published MIT-licensed `@uppercut-labs/agent-native` TypeScript library, not replace the website with a chatbot and not merely build a synthetic demo. Your task is to add a real, typed, permission-checked agent-callable capability built on an existing function or application operation.
+
+My target operation, if specified: **[Describe one real operation; otherwise identify and implement the most useful existing public read.]**
+
+Read the repository instructions, package manifest, lockfile, framework, routes, current human workflows, authentication boundaries and relevant source code before changing anything. Use the Agent Native integration skill if installed; if not, rely on official public docs: https://github.com/uppercut-labs/agent-native/blob/main/docs/installation.md and the existing-function retrofit at https://github.com/uppercut-labs/agent-native/tree/main/examples/e10-existing-functions-retrofit. Check the installed npm package's exports before assuming option names. The inspected candidate is `1.1.0` and requires Node.js 22+; do not silently upgrade the app's framework or optional peers.
+
+Choose a minimal implementation that respects the site's actual architecture. Start with an **existing public read** unless my request specifically authorizes authenticated actions. Define a versioned capability with real input/output schemas, honest risk/access metadata, an explicit runtime binding to the existing domain function, and a checked registry. Use an application-owned authorization port on **every invocation**. Preserve current human UI, working APIs, records, routes and auth.
+
+Identity namespace and name use lower-case slug segments separated by dots or hyphens,
+such as `{ namespace: 'blog', name: 'list-posts', majorVersion: 1 }`.
+
+Expose an actual useful agent surface, not just a local registry. If this website has a server, prefer HTTP/OpenAPI for public reads and, where useful, official MCP Streamable HTTP. If it is static, retain its static output and use a separately hosted server/Worker sidecar for remote tool calls, or explain precisely why a server cannot be provided within this work scope. If Next App Router, use its documented Node route adapter; if Astro, use its supported mode deliberately. Browser WebMCP is optional/experimental and requires normal UI fallback. There is **no** global `agent-native init` CLI, no automatic discovery of business operations, and no built-in production identity/grant service.
+
+Never turn protected customer data, user-specific operations, writes or destructive actions into public tools. For protected MCP functionality, use the host's real verified identity, current scopes, application-persisted grants and per-record authorization; do not use a fixture store or unconditional allow-all. Don't place tokens or server-only SDKs in client bundles. Don't create paid services, change DNS, deploy, publish a package, change external permissions, or modify production records unless separately authorized.
+
+**Execute the implementation and its local tests**, not just a plan. First write a short source-grounded integration outline. Then make minimal focused changes. Prove one real successful call on the chosen surface, at least one invalid-input rejection **before handler execution**, at least one denied/hidden path, and one existing human website flow still works. For MCP, use an actual compatible MCP client and inspect `structuredContent.result`; for HTTP, test the actual mounted route and method/schema. If a deployment or commercial host wasn't tested, label it *unverified*, not complete. Avoid fake green tests, invented commands and unused scaffolding.
+
+Finish with the implemented capability name/version, real function reused, risk/access policy, chosen runtime and surface, file diffs, install/test commands, observed positive and negative outputs, known limits, needed owner-owned deployment/auth steps, and a rollback plan. If important access or an authorized external action is missing, complete independent safe work and precisely identify what remains blocked.
+
+---

package/bin/agent-native-site.mjs

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, mkdir, readFile, realpath, rename, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { planPublication, safePublicationPath } from '@uppercut-labs/agent-native/publication';
+import { discoverRoutes } from './discover-routes.mjs';
+import { verifyProtocol, verifyPublication } from './verify-publication.mjs';
+
+const help =
+  'agent-native-site discover --framework NAME --project DIR [--routes TABLE.json]  |  agent-native-site <preview|apply|restore-preview|restore|verify> --manifest FILE [--out EXISTING_DIR --state EXISTING_PRIVATE_DIR] [--approve DIGEST]';
+const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const fail = (code, detail) => {
+  throw Object.assign(new Error(code), { diagnostic: code, detail });
+};
+
+async function optional(read) {
+  try {
+    return await read();
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function within(root, target) {
+  const relative = path.relative(root, target);
+  return (
+    relative === '' ||
+    (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
+  );
+}
+
+// Reject symlinks in existing components, including a symlink at the leaf.
+// The caller supplies a canonical root and relative names produced by the engine.
+async function inspect(root, name) {
+  if (!safePublicationPath(name)) fail('unsafe-path', name);
+  const segments = name.split('/');
+  let location = root;
+  for (const [i, segment] of segments.entries()) {
+    location = path.join(location, segment);
+    const stat = await optional(() => lstat(location));
+    if (!stat) return null;
+    if (stat.isSymbolicLink() || (i === segments.length - 1 ? !stat.isFile() : !stat.isDirectory()))
+      fail('unsafe-path', name);
+  }
+  return readFile(location);
+}
+
+async function readJournal(file, out) {
+  const stat = await optional(() => lstat(file));
+  if (!stat) return {};
+  if (!stat.isFile() || stat.isSymbolicLink()) fail('invalid-journal');
+  const record = JSON.parse(await readFile(file, 'utf8'));
+  if (
+    record.version !== 1 ||
+    record.out !== out ||
+    !record.files ||
+    Array.isArray(record.files) ||
+    typeof record.files !== 'object'
+  )
+    fail('invalid-journal');
+  for (const [name, digest] of Object.entries(record.files)) {
+    if (!safePublicationPath(name) || !/^[a-f0-9]{64}$/.test(digest)) fail('invalid-journal');
+  }
+  return record.files;
+}
+
+async function snapshot(out, state, plan, restore) {
+  const journal = await readJournal(path.join(state, 'ownership.json'), out);
+  const assets = new Map((restore ? [] : plan.assets).map((a) => [a.path, a]));
+  const changes = [],
+    conflicts = [],
+    backup = new Map();
+  for (const name of [...new Set([...Object.keys(journal), ...assets.keys()])].sort()) {
+    const bytes = await inspect(out, name);
+    const before = bytes === null ? null : hash(bytes);
+    const owned = Object.hasOwn(journal, name);
+    if (owned ? before !== journal[name] : before !== null) {
+      conflicts.push(name);
+      continue;
+    }
+    const after = assets.get(name)?.digest ?? null;
+    if (after === before) continue;
+    backup.set(name, bytes);
+    changes.push({ path: name, before, after });
+  }
+  const digest = hash(
+    JSON.stringify([
+      restore ? 'restore' : 'apply',
+      plan.digest,
+      out,
+      state,
+      journal,
+      changes,
+      conflicts,
+    ]),
+  );
+  return { digest, changes, conflicts, backup, assets };
+}
+
+async function main(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      manifest: { type: 'string' },
+      framework: { type: 'string' },
+      project: { type: 'string' },
+      routes: { type: 'string' },
+      out: { type: 'string' },
+      state: { type: 'string' },
+      approve: { type: 'string' },
+      help: { type: 'boolean', short: 'h' },
+    },
+  });
+  if (values.help || argv.length === 0) return { usage: help };
+  const [command] = positionals;
+  if (command === 'discover' && positionals.length === 1 && values.framework && values.project) {
+    return discoverRoutes(values.framework, values.project, values.routes);
+  }
+  if (
+    positionals.length !== 1 ||
+    !['preview', 'apply', 'restore-preview', 'restore', 'verify'].includes(command) ||
+    !values.manifest
+  )
+    fail('invalid-usage', help);
+  const manifestFile = await realpath(values.manifest);
+  const input = JSON.parse(await readFile(manifestFile, 'utf8'));
+  const restore = command === 'restore' || command === 'restore-preview';
+  const plan = await planPublication(input.config, input.candidates, { verifyProtocol });
+  if (!restore && plan.diagnostics.some((d) => d.severity === 'error'))
+    fail('invalid-publication', plan.diagnostics);
+  if (command === 'verify')
+    return verifyPublication(plan, input.config, input.verify, input.candidates);
+  if (!values.out || !values.state) fail('invalid-usage', help);
+  const [out, state] = await Promise.all([realpath(values.out), realpath(values.state)]);
+  if (
+    !(await lstat(out)).isDirectory() ||
+    !(await lstat(state)).isDirectory() ||
+    within(out, state) ||
+    within(state, out) ||
+    within(out, manifestFile)
+  )
+    fail('invalid-roots');
+  const preview = command === 'preview' || command === 'restore-preview';
+  if (preview) {
+    const { digest, changes, conflicts } = await snapshot(out, state, plan, restore);
+    return {
+      status: conflicts.length ? 'conflict' : 'preview',
+      digest,
+      changes,
+      conflicts,
+      manifest: plan.manifest,
+      diagnostics: plan.diagnostics,
+    };
+  }
+  if (!values.approve) fail('approval-required');
+  const lock = path.join(state, 'publication.lock');
+  try {
+    await writeFile(lock, String(process.pid), { flag: 'wx', mode: 0o600 });
+  } catch (error) {
+    if (error.code === 'EEXIST') fail('publication-locked');
+    throw error;
+  }
+  let releaseLock = true;
+  try {
+    const { digest, changes, conflicts, backup, assets } = await snapshot(
+      out,
+      state,
+      plan,
+      restore,
+    );
+    if (conflicts.length) fail('ownership-conflict', conflicts);
+    if (digest !== values.approve) fail('stale-approval');
+    if (!changes.length) return { status: 'no-op', digest };
+    const pending = path.join(state, 'pending.json');
+    const priorFiles = await readJournal(path.join(state, 'ownership.json'), out);
+    try {
+      await writeFile(
+        pending,
+        JSON.stringify({
+          version: 1,
+          out,
+          digest,
+          priorFiles,
+          changes: changes.map((change) => ({
+            ...change,
+            original: backup.get(change.path)?.toString('base64') ?? null,
+          })),
+        }),
+        { flag: 'wx', mode: 0o600, flush: true },
+      );
+    } catch (error) {
+      if (error.code === 'EEXIST') fail('recovery-required');
+      throw error;
+    }
+    const applied = [];
+    const journal = path.join(state, 'ownership.json');
+    const tempJournal = path.join(state, `${randomUUID()}.tmp`);
+    try {
+      for (const change of changes) {
+        const dest = path.join(out, change.path);
+        const prior = await inspect(out, change.path);
+        if ((prior === null ? null : hash(prior)) !== change.before)
+          fail('stale-file', change.path);
+        const next = assets.get(change.path);
+        if (prior !== null) await unlink(dest);
+        applied.push(change);
+        if (next) {
+          await mkdir(path.dirname(dest), { recursive: true });
+          await writeFile(dest, next.content, { flag: 'wx' });
+        }
+      }
+      const files = Object.fromEntries(
+        [...assets]
+          .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+          .map(([name, asset]) => [name, asset.digest]),
+      );
+      await writeFile(
+        tempJournal,
+        JSON.stringify({ version: 1, out, files, transaction: digest }),
+        {
+          flag: 'wx',
+          mode: 0o600,
+        },
+      );
+      await rename(tempJournal, journal);
+    } catch (error) {
+      await optional(() => unlink(tempJournal));
+      for (const change of applied.reverse()) {
+        try {
+          const current = await inspect(out, change.path);
+          if (current !== null) {
+            if (hash(current) !== change.after) fail('rollback-conflict', change.path);
+            await unlink(path.join(out, change.path));
+          }
+          const original = backup.get(change.path);
+          if (original !== null)
+            await writeFile(path.join(out, change.path), original, { flag: 'wx' });
+        } catch (recoveryError) {
+          releaseLock = false;
+          throw recoveryError;
+        }
+      }
+      await unlink(pending);
+      throw error;
+    }
+    await unlink(pending);
+    return { status: restore ? 'restored' : 'applied', digest, changes };
+  } finally {
+    if (releaseLock) await unlink(lock);
+  }
+}
+
+try {
+  const result = await main(process.argv.slice(2));
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'conflict' || result.status === 'failed') process.exitCode = 1;
+} catch (error) {
+  process.stdout.write(
+    `${JSON.stringify({
+      status: 'failed',
+      code: error.diagnostic ?? error.code ?? 'invalid-input',
+      detail: error.detail,
+    })}\n`,
+  );
+  process.exitCode = 1;
+}

package/bin/discover-routes.mjs

@@ -0,0 +1,162 @@
+import { lstat, readdir, readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+const filesystem = {
+  astro: { roots: ['src/pages'], page: /\.(astro|md|mdx|html)$/ },
+  next: { roots: ['app', 'src/app'], page: /^page\.[cm]?[jt]sx?$/ },
+  sveltekit: { roots: ['src/routes'], page: /^\+page(?:@[\w-]*)?\.svelte$/ },
+  nuxt: { roots: ['app/pages', 'pages'], page: /\.vue$/ },
+};
+const tableRouters = new Set(['angular', 'react-router', 'react-vite', 'vue-vite']);
+const safeName = /^[\p{L}\p{M}\p{N}_.~\-\[\]()+@=:*]+$/u;
+
+// Return private review candidates only. Never parse module code, run loaders or read page bodies.
+export async function discoverRoutes(framework, project, tableFile) {
+  if (!Object.hasOwn(filesystem, framework) && !tableRouters.has(framework))
+    throw Error('unknown-framework');
+  const root = await realpath(project);
+  const routes = [],
+    diagnostics = [];
+  let visited = 0;
+  function record(raw, source) {
+    if (
+      typeof raw !== 'string' ||
+      raw.split('/').some((segment) => segment === '..' || segment === '.') ||
+      raw.includes('\\') ||
+      !raw.startsWith('/')
+    )
+      throw Error('invalid-route-record');
+    if (++visited > 20000) throw Error('route-limit');
+    const route = raw.replace(/\/+$/, '') || '/';
+    const id =
+      'route-' +
+      createHash('sha256')
+        .update(JSON.stringify([framework, source, route]))
+        .digest('hex')
+        .slice(0, 24);
+    routes.push({
+      id,
+      route,
+      source,
+      visibility: 'unknown',
+      requiresParameters: /[\[\]:*$?]/.test(route),
+    });
+  }
+  async function safeDir(rel) {
+    const dir = path.join(root, rel);
+    try {
+      if (!(await lstat(dir)).isDirectory() || (await realpath(dir)) !== dir) return false;
+    } catch (error) {
+      if (error.code === 'ENOENT') return false;
+      throw error;
+    }
+    return true;
+  }
+  const rule = filesystem[framework];
+  if (rule) {
+    for (const prefix of rule.roots) {
+      if (!(await safeDir(prefix))) continue;
+      async function visit(folder) {
+        for (const entry of await readdir(path.join(root, prefix, folder), {
+          withFileTypes: true,
+        })) {
+          const name = entry.name;
+          if (
+            !safeName.test(name) ||
+            name.startsWith('.') ||
+            name.startsWith('_') ||
+            name.startsWith('@') ||
+            entry.isSymbolicLink()
+          )
+            continue;
+          const rel = path.posix.join(folder, name);
+          if (entry.isDirectory()) {
+            if (rel.split('/').length > 40) throw Error('route-depth-limit');
+            await visit(rel);
+          } else if (entry.isFile() && rule.page.test(name)) {
+            let parts = rel.split('/');
+            if (framework === 'next' || framework === 'sveltekit') parts.pop();
+            else {
+              parts[parts.length - 1] = name.replace(/\.[^.]+$/, '');
+              if (parts.at(-1) === 'index') parts.pop();
+            }
+            if (framework === 'next' || framework === 'sveltekit')
+              parts = parts.filter((part) => !/^\([^()]+\)$/.test(part));
+            record('/' + parts.join('/'), prefix + '/' + rel);
+          }
+        }
+      }
+      await visit('');
+      if (framework === 'next' || framework === 'nuxt') break;
+    }
+  }
+  let table = tableFile;
+  if (!table && framework === 'angular' && (await safeDir('dist'))) {
+    try {
+      if ((await lstat(path.join(root, 'dist/prerendered-routes.json'))).isFile())
+        table = 'dist/prerendered-routes.json';
+    } catch (e) {
+      if (e.code !== 'ENOENT') throw e;
+    }
+  }
+  if (table) {
+    const absolute = path.resolve(root, table),
+      relative = path.relative(root, absolute);
+    if (
+      relative.startsWith('..' + path.sep) ||
+      relative === '..' ||
+      path.isAbsolute(relative) ||
+      absolute !== (await realpath(absolute))
+    )
+      throw Error('unsafe-route-table');
+    const stat = await lstat(absolute);
+    if (!stat.isFile() || stat.size > 2 * 1024 * 1024) throw Error('invalid-route-table');
+    const value = JSON.parse(await readFile(absolute, 'utf8'));
+    const source = relative.split(path.sep).join('/');
+    if (Array.isArray(value)) {
+      const add = (row, parent, depth) => {
+        if (depth > 40) throw Error('route-depth-limit');
+        if (typeof row === 'string') {
+          record(row.startsWith('/') ? row : parent + '/' + row, source);
+          return;
+        }
+        if (
+          !row ||
+          typeof row !== 'object' ||
+          (row.path !== undefined && typeof row.path !== 'string')
+        )
+          throw Error('invalid-route-record');
+        const route = row.path?.startsWith('/')
+          ? row.path
+          : [parent, row.path].filter(Boolean).join('/').replace(/^\/?/, '/');
+        if (row.path || row.index) record(route || '/', source);
+        if (row.children !== undefined) {
+          if (!Array.isArray(row.children)) throw Error('invalid-route-record');
+          for (const child of row.children) add(child, route === '/' ? '' : route, depth + 1);
+        }
+      };
+      for (const row of value) add(row, '', 0);
+    } else if (
+      framework === 'angular' &&
+      value?.routes &&
+      typeof value.routes === 'object' &&
+      !Array.isArray(value.routes)
+    ) {
+      for (const key of Object.keys(value.routes)) record(key, source);
+    } else throw Error('invalid-route-table');
+  }
+  if (!routes.length)
+    diagnostics.push(
+      tableRouters.has(framework) ? 'supply-exported-route-table' : 'no-conventional-pages',
+    );
+  const unique = new Map(routes.map((r) => [r.id, r]));
+  return {
+    status: 'discovered',
+    framework,
+    routes: [...unique.values()].sort((a, b) =>
+      a.route < b.route ? -1 : a.route > b.route ? 1 : a.id.localeCompare(b.id),
+    ),
+    diagnostics,
+  };
+}