feat(mcp): Claude connector-store readiness + Better Auth OAuth

.github/workflows/checks.yml

@@ -56,8 +56,21 @@ jobs:
         run: bun scripts/lint/no-unauth-routes.ts
       - name: Check unsafe type casts
         run: bun check:casts:strict
-      - name: Check types
+      # Two type-check passes, deliberately. `bun check-types` runs a single
+      # root `tsc` over the shared React-Native/web/node program (jsx:
+      # react-native, lib DOM+ESNext). That program structurally CANNOT house
+      # packages with a different global type environment — Cloudflare Workers
+      # packages (packages/mcp: @cloudflare/workers-types, no DOM) and the
+      # @kitajs/html JSX package (packages/consent-ui: global JSX namespace) —
+      # so those, plus osm-db/osm-import/overpass, are excluded from the root
+      # tsconfig. `bun check-types:packages` (turbo) then type-checks EVERY
+      # package under its OWN tsconfig, closing that gap. Both must stay: the
+      # root pass catches cross-package program errors, the turbo pass catches
+      # per-package errors the root program can't see (e.g. MCP, #2533).
+      - name: Check types (root tsc — shared RN/web/node program)
         run: bun check-types
+      - name: Check types (per-package — turbo, each tsconfig)
+        run: bun check-types:packages
       - name: Run Expo Doctor
         run: bunx expo-doctor
         working-directory: apps/expo

.gitignore

@@ -53,4 +53,7 @@ apps/guides/public/og/
 # Git worktrees
 .worktrees/
 .worktrees
+
+# Cloudflare wrangler local state (dev/test artifacts)
+.wrangler/
 .turbo/

CLAUDE.md

@@ -158,28 +158,33 @@ Sentry.addBreadcrumb({ category: 'feature', message: 'Action started', level: 'i
 - **Better Auth errors** (plain objects with `{ message, status, code }`) are not JS Errors. Use `toAuthError` from `expo-app/features/auth/lib/authErrors` to convert them into an `AuthClientError` that carries `status` and `code`. Capture and throw that — do not create a separate synthetic error for Sentry and another for throwing.
 - Include `httpStatus` and `errorCode` in `extra` for any HTTP error so they're searchable in Sentry.
 
-**API / Cloudflare Workers** — use helpers from `@packrat/api/utils/sentry`:
+**API / Cloudflare Workers** — helpers from `@packrat/api/utils/sentry`. There are **three boundaries by where code runs** — match the tier to the situation instead of wrapping everything in try/catch:
 
-```ts
-import { apiAddBreadcrumb, captureApiException } from '@packrat/api/utils/sentry';
+1. **Route handlers → do nothing.** Elysia's global `.onError` (`src/app.ts`) is the central sink: it reports unexpected errors (skips `VALIDATION`/`PARSE`/`NOT_FOUND`), tagged by the matched **route template** + `request_id`. Let errors propagate — don't add a try/catch *just* to report. Only catch in a route to **translate** an error into a specific response (and then it's a swallow — see tier 3).
 
-// Breadcrumb before significant async steps
-apiAddBreadcrumb({ category: 'feature', message: 'Fetching external data', level: 'info' });
+2. **Sub-operations you rethrow from → wrap in `record`.** Workflow `step.do` bodies, queue/cron consumers, and services called outside an Elysia request. It opens a Sentry span (OTel-semantic, Workers-native) **and** captures-with-context **and** rethrows:
 
-// In every catch block
-} catch (error) {
-  captureApiException(error, {
-    operation: 'featureName.action',
-    userId,
-    tags: { feature: 'myFeature' },
-    extra: { relevantId },
-  });
-  throw error; // or return an error response
-}
-```
+   ```ts
+   import { record } from '@packrat/api/utils/sentry';
+
+   await record({ operation: 'etl.processLogsBatch', extra: { jobId } }, async () => {
+     await db.insert(logs).values(rows);
+   });
+   ```
+
+3. **Catches that swallow → call `captureApiException`** (object signature). Fail-closed `return false`, best-effort metrics, per-item loops that continue, route catches that return an error response:
+
+   ```ts
+   } catch (error) {
+     captureApiException({ error, operation: 'verifyAdmin', extra: { userId } });
+     return false; // swallowed — nothing to rethrow
+   }
+   ```
 
-- Use `captureApiException` (not raw `captureException`) — it wraps the call with structured operation context and also logs to console for wrangler dev output.
-- Every route `catch` block and service method that interacts with the DB or an external API must have a `captureApiException` call.
+- Capture is **idempotent + deduped** (a marker is stamped on the error), so `record`/`captureApiException` + the outer boundary (`.onError`, `withSentry`, `instrumentWorkflowWithSentry`) never double-report — enrich-and-rethrow is always safe.
+- Every event in a request shares a **`request_id`** tag (`cf-ray`, set in `.onRequest`), echoed in the `X-Request-Id` response header — pivot on it to tie an `.onError` report to the granular `record`/`captureApiException` events. Sentry's automatic `trace_id` correlates them too.
+- Don't use raw `captureException` — the wrappers add operation context + console logging. Include `httpStatus`/`errorCode` in `extra` for HTTP errors; breadcrumb significant steps with `apiAddBreadcrumb`.
+- **Not** `@elysiajs/opentelemetry`: its Node OTel SDK doesn't run on workerd (BatchSpanProcessor, AsyncHooks). `record` gives the same `record(name, fn)` ergonomics on Sentry's Workers-native tracer.
 
 ### API Client (`@packrat/api-client`)
 

apps/admin/lib/api.ts

@@ -1,5 +1,5 @@
 import { treaty } from '@elysiajs/eden';
-import type { App } from '@packrat/api';
+import type { App } from '@packrat/api-client';
 import { isObject } from '@packrat/guards';
 import type {
   ActiveUsers,

apps/admin/tsconfig.json

@@ -5,7 +5,6 @@
       "@packrat/app": ["../../packages/app/src/index.ts"],
       "@packrat/app/*": ["../../packages/app/src/*"],
       "admin-app/*": ["./*"],
-      "@packrat/api/*": ["../../packages/api/src/*"],
       "@packrat/guards": ["../../packages/guards/src"],
       "@packrat/guards/*": ["../../packages/guards/src/*"],
       "@packrat/web-ui": ["../../packages/web-ui/src"],

apps/expo/package.json

@@ -54,7 +54,6 @@
     "@gorhom/bottom-sheet": "^5.1.2",
     "@legendapp/state": "^3.0.0-beta.30",
     "@packrat-ai/nativewindui": "2.0.6",
-    "@packrat/api": "workspace:*",
     "@packrat/api-client": "workspace:*",
     "@packrat/config": "workspace:*",
     "@packrat/constants": "workspace:*",

apps/expo/tsconfig.json

@@ -7,8 +7,6 @@
     "baseUrl": ".",
     "paths": {
       "expo-app/*": ["./*"],
-      "@packrat/api": ["../../packages/api/src/index.ts"],
-      "@packrat/api/*": ["../../packages/api/src/*"],
       "@packrat/api-client": ["../../packages/api-client/src/index.ts"],
       "@packrat/api-client/*": ["../../packages/api-client/src/*"]
     }

apps/expo/vitest.types.config.ts

@@ -5,7 +5,6 @@ export default defineConfig({
   resolve: {
     alias: {
       'expo-app': resolve(__dirname, '.'),
-      '@packrat/api': resolve(__dirname, '../../packages/api/src/index.ts'),
       '@packrat/api-client': resolve(__dirname, '../../packages/api-client/src/index.ts'),
     },
   },

apps/guides/lib/enhanceGuideContent.ts

@@ -1,6 +1,6 @@
 import { openai } from '@ai-sdk/openai';
 import { treaty } from '@elysiajs/eden';
-import type { App } from '@packrat/api';
+import type { App } from '@packrat/api-client';
 import { guideEnv } from '@packrat/env/next';
 import { generateText, tool } from 'ai';
 import { z } from 'zod';

apps/guides/package.json

@@ -27,7 +27,7 @@
     "@ai-sdk/openai": "catalog:",
     "@elysiajs/eden": "catalog:",
     "@hookform/resolvers": "catalog:",
-    "@packrat/api": "workspace:*",
+    "@packrat/api-client": "workspace:*",
     "@packrat/env": "workspace:*",
     "@packrat/guards": "workspace:*",
     "@packrat/schemas": "workspace:*",

apps/landing/__tests__/legal.pages.test.ts

@@ -0,0 +1,123 @@
+/**
+ * Smoke tests for the legal pages (U12 of the MCP connector-store readiness
+ * plan).
+ *
+ * The landing app uses Next.js with `output: 'export'` and a node-environment
+ * vitest setup (see `vitest.config.ts`). React-server-component imports don't
+ * resolve cleanly in that env, so the route-level "GET returns 200 with this
+ * string" test the og-meta suite performs (against the built `out/` HTML)
+ * would be the only true smoke pattern. We don't run a full Next build inside
+ * this suite to keep it fast; instead, the assertions below operate on the
+ * source `.tsx` files for the two legal pages and on the shared
+ * `config/site.ts` block that wires them up.
+ *
+ * What we verify:
+ *   - The Terms of Service page source exists, exports the standard metadata
+ *     shape, and contains the load-bearing MCP, jurisdiction-TODO, and
+ *     hello@packratai.com strings a reviewer will scan for.
+ *   - The Privacy Policy page source contains the new MCP / connectors
+ *     addendum (heading + key bullet content).
+ *   - `siteConfig.footerLinks.legal` exposes BOTH Privacy and Terms, and
+ *     `siteConfig.support` advertises the canonical mailto.
+ *
+ * If a route smoke pattern lands later (e.g. happy-dom env + RSC eval, or
+ * a separate `vitest --config out-export.config.ts` workspace), the
+ * file-text assertions can be replaced — the reviewer-facing intent is the
+ * stable contract.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { siteConfig } from '../config/site';
+
+const APP_DIR = resolve(__dirname, '..');
+const TOS_PAGE = resolve(APP_DIR, 'app/terms-of-service/page.tsx');
+const PRIVACY_PAGE = resolve(APP_DIR, 'app/privacy-policy/page.tsx');
+
+describe('Terms of Service page (/terms-of-service)', () => {
+  it('source file exists', () => {
+    expect(existsSync(TOS_PAGE)).toBe(true);
+  });
+
+  const source = existsSync(TOS_PAGE) ? readFileSync(TOS_PAGE, 'utf8') : '';
+
+  it('exports a Next.js metadata block with title/description/robots', () => {
+    expect(source).toContain('export const metadata');
+    expect(source).toContain("title: 'Terms of Service | PackRat'");
+    expect(source).toMatch(/description:\s*'[^']+'/);
+    expect(source).toMatch(/robots:\s*\{[^}]*index:\s*true/);
+  });
+
+  it('renders the "Terms of Service" heading', () => {
+    expect(source).toContain('>Terms of Service<');
+  });
+
+  it('covers MCP connector provisions', () => {
+    // Reviewers grep for "MCP" — this section is the new content this unit
+    // ships and is what Anthropic's policy expects to find.
+    expect(source).toMatch(/MCP/);
+    expect(source).toContain('mcp.packratai.com');
+    expect(source).toMatch(/mcp:admin/);
+    expect(source).toMatch(/OAuth/);
+  });
+
+  it('includes the outdoor-safety disclaimer', () => {
+    expect(source).toMatch(/inherent risks/i);
+  });
+
+  it('surfaces the canonical support contact', () => {
+    expect(source).toContain('hello@packratai.com');
+  });
+
+  it('leaves the operator-jurisdiction TODO marker in place', () => {
+    // U12 deliberately ships with a placeholder jurisdiction (Delaware) and a
+    // TODO so the operator can replace it after legal review. The check
+    // prevents the TODO from being silently lost in a future edit.
+    expect(source).toMatch(/TODO\(operator\): set jurisdiction/);
+  });
+});
+
+describe('Privacy Policy page (/privacy-policy) — MCP addendum', () => {
+  it('source file exists', () => {
+    expect(existsSync(PRIVACY_PAGE)).toBe(true);
+  });
+
+  const source = existsSync(PRIVACY_PAGE) ? readFileSync(PRIVACY_PAGE, 'utf8') : '';
+
+  it('renders the new "MCP Connector & Third-Party Clients" section heading', () => {
+    expect(source).toContain('MCP Connector & Third-Party Clients');
+  });
+
+  it('explains OAuth token storage and rotation', () => {
+    expect(source).toMatch(/refresh token/i);
+    expect(source).toMatch(/Cloudflare KV/);
+    expect(source).toMatch(/60 minutes/);
+  });
+
+  it('clarifies what MCP clients do NOT see', () => {
+    expect(source).toMatch(/never sees your\s+PackRat password|never sees your password/i);
+    expect(source).toMatch(/conversation content/i);
+  });
+
+  it('points users at hello@packratai.com for deletion', () => {
+    expect(source).toContain('hello@packratai.com');
+  });
+});
+
+describe('siteConfig wiring (U12)', () => {
+  it('exposes BOTH Privacy and Terms in the footer legal block', () => {
+    const titles = siteConfig.footerLinks.legal.map((l) => l.title);
+    expect(titles).toContain('Privacy');
+    expect(titles).toContain('Terms');
+
+    const hrefs = siteConfig.footerLinks.legal.map((l) => l.href);
+    expect(hrefs).toContain('/privacy-policy');
+    expect(hrefs).toContain('/terms-of-service');
+  });
+
+  it('exposes the canonical support contact', () => {
+    expect(siteConfig.support).toBeDefined();
+    expect(siteConfig.support.email).toBe('hello@packratai.com');
+    expect(siteConfig.support.mailto).toBe('mailto:hello@packratai.com');
+  });
+});

apps/landing/__tests__/mcp.page.test.ts

@@ -0,0 +1,131 @@
+/**
+ * Smoke tests for the MCP public docs page (U13).
+ *
+ * Same vitest-against-source approach as `legal.pages.test.ts`: the landing
+ * app uses Next.js `output: 'export'` and a node-only vitest env, so we
+ * can't import the RSC route directly. Assertions operate on the page
+ * source plus the generated `mcp-catalog.json` to verify reviewer-facing
+ * invariants the connector-store submission will be evaluated against.
+ *
+ * What we verify:
+ *   - The page source exists, exports the standard metadata shape with
+ *     `robots.index: true` (Anthropic must be able to crawl the docs URL).
+ *   - The Quickstart / Scopes / Example prompts / Tool catalog / Resources
+ *     / Privacy & security / Reviewer test account sections all render.
+ *   - Three example prompts appear (per Software Directory Policy).
+ *   - The Claude.ai custom-connector install URL is exactly the production
+ *     MCP endpoint string.
+ *   - `mcp-catalog.json` is present and non-trivial — the page renders
+ *     from it, so a missing or empty JSON would surface as a build-time
+ *     RSC error in production.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const APP_DIR = resolve(__dirname, '..');
+const PAGE = resolve(APP_DIR, 'app/mcp/page.tsx');
+const CATALOG = resolve(APP_DIR, 'data/mcp-catalog.json');
+
+describe('MCP public docs page (/mcp)', () => {
+  it('source file exists', () => {
+    expect(existsSync(PAGE)).toBe(true);
+  });
+
+  const source = existsSync(PAGE) ? readFileSync(PAGE, 'utf8') : '';
+
+  it('exports a Next.js metadata block (indexable)', () => {
+    expect(source).toContain('export const metadata');
+    expect(source).toMatch(/title:\s*'PackRat MCP Connector \| PackRat'/);
+    expect(source).toMatch(/robots:\s*\{\s*index:\s*true/);
+  });
+
+  it('renders the hero heading', () => {
+    expect(source).toMatch(/Plan trips, build packs, check weather/);
+  });
+
+  it('exposes the production MCP endpoint URL verbatim', () => {
+    // The submission packet, the public docs page, and the worker's
+    // resourceMetadata MUST all advertise the same URL. A diff here is the
+    // canary on a drift that breaks Anthropic's audience verification.
+    expect(source).toContain('https://mcp.packratai.com/mcp');
+  });
+
+  it('lists the three OAuth scopes', () => {
+    // Sourced from the JSON dump at render time, but the header / table
+    // copy refers to them inline; the smoke test asserts both.
+    for (const scope of ['mcp:read', 'mcp:write', 'mcp:admin']) {
+      expect(source).toContain(scope);
+    }
+  });
+
+  it('uses the Anthropic "custom connector" terminology', () => {
+    expect(source).toMatch(/custom connector/i);
+  });
+
+  it('ships ≥ 3 example prompts (Software Directory Policy)', () => {
+    // Each example prompt is wrapped in a <blockquote>; count those.
+    const blockquotes = source.match(/<blockquote/g) ?? [];
+    expect(blockquotes.length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('points reviewers at the submission-packet doc for credentials', () => {
+    expect(source).toContain('docs/mcp/submission-packet.md');
+    // And explicitly states credentials are NOT on the public page.
+    expect(source).toMatch(/do not publish credentials/i);
+  });
+
+  it('links the legal / privacy / support surfaces', () => {
+    expect(source).toContain('/privacy-policy');
+    expect(source).toContain('/terms-of-service');
+    expect(source).toContain('hello@packratai.com');
+  });
+
+  it('points to the developer README and the implementation plan', () => {
+    expect(source).toContain('packages/mcp/README.md');
+    expect(source).toContain(
+      'docs/plans/2026-05-22-001-feat-mcp-connector-store-readiness-plan.md',
+    );
+    expect(source).toContain('docs/mcp/runbook.md');
+  });
+});
+
+describe('mcp-catalog.json (build-time data source for /mcp)', () => {
+  it('is present and parses as JSON', () => {
+    expect(existsSync(CATALOG)).toBe(true);
+    const raw = readFileSync(CATALOG, 'utf8');
+    // Must round-trip cleanly — the page imports it as a typed module.
+    expect(() => JSON.parse(raw)).not.toThrow();
+  });
+
+  const raw = existsSync(CATALOG) ? readFileSync(CATALOG, 'utf8') : '{}';
+  const catalog = JSON.parse(raw) as {
+    totalTools?: number;
+    counts?: { byClassification?: Record<string, number> };
+    tools?: Array<{ name: string; classification: string }>;
+    endpoint?: string;
+  };
+
+  it('contains ≥ 80 tools (sanity floor matching the U7 annotations test)', () => {
+    expect(catalog.totalTools ?? 0).toBeGreaterThanOrEqual(80);
+    expect((catalog.tools ?? []).length).toBe(catalog.totalTools ?? -1);
+  });
+
+  it('every tool name starts with the packrat_ prefix', () => {
+    for (const t of catalog.tools ?? []) {
+      expect(t.name).toMatch(/^packrat_/);
+    }
+  });
+
+  it('partitions tools into read / write / admin classifications', () => {
+    const c = catalog.counts?.byClassification ?? {};
+    expect(c.read).toBeGreaterThan(0);
+    expect(c.write).toBeGreaterThan(0);
+    expect(c.admin).toBeGreaterThan(0);
+  });
+
+  it('advertises the production endpoint URL', () => {
+    expect(catalog.endpoint).toBe('https://mcp.packratai.com/mcp');
+  });
+});