[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_483":484,"_485":486},"routes/_app.x.$handle.$name",{"_97":96,"_32":44,"_105":87,"_27":52,"_13":14,"_106":-5,"_11":107,"_108":109,"_110":111,"_112":113,"_114":115,"_20":-5,"_116":-5,"_117":-5,"_118":25,"_119":120,"_121":122,"_123":-5,"_124":-5,"_125":126},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_42":43,"_32":44,"_37":45,"_46":-5,"_47":25,"_48":49,"_50":49,"_51":52,"_53":-5,"_18":54,"_55":-5,"_56":25,"_57":-5,"_58":-5,"_59":60,"_61":62,"_63":64,"_65":66,"_67":68,"_69":-5,"_70":71,"_72":71,"_73":74,"_75":74,"_76":74,"_77":71,"_78":71,"_79":80,"_81":82,"_83":84,"_85":25},"version",137,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":23,"_24":25,"_26":25,"_27":28,"_29":28},"file",{"_30":31,"_32":33,"_34":20,"_35":36,"_37":38,"_39":14,"_40":41,"_24":25},"previous",{"_30":31,"_32":33,"_34":20,"_35":36},"deleted",false,"deletedHere","path","docs/notes/building-host-scoped-integrations.md","latestPath","fileId","7b67cef6-7d69-11f1-821f-1607ee4eb77e","name","building-host-scoped-integrations.md","fileType","content","# Building host-scoped integrations: mounting, self-identification, SPAs, versioning\n\nField notes from a build session: porting a client-side React SPA onto the\nintegrations contract and probing how a mounted integration sees its host.\n\nEmpirical claims were verified against a live toy (`toy-spa-integration`)\nmounted three ways. Items tagged _(from the contract)_ were reasoned from\n`router.ts`, not exercised live.\n\n---\n\n## 1. The ways an integration can be mounted\n\nAn integration is just a `(req, ctx?) => Response` handler (a callable\n`Integration`). Two things vary independently: the **mount mechanism** — which\ndecides whether `ctx` is passed and whether prefix/redirect handling applies —\nand the **host val**, which is always whichever val Val Town executed.\n\n| Mechanism | Host val (`= VALTOWN_ENTRYPOINT`) | `ctx` | Path handler sees | Router services |\n| --------------------------------------------------------------------------------------- | --------------------------------- | -------------------- | -------------------- | --------------------------------------------------------------------- |\n| Standalone, own val — `export default factory()` in the integration's own val | the integration's own val | absent | root | none |\n| Standalone, wrapper val — another val does `import {factory}; export default factory()` | the wrapper val | absent | root | none |\n| Routed — `createRouter({ integrations:[factory()] })` | the router val | `{ user, prefix }` | prefix-stripped | prefix canonicalize, Location rewrite, directory page, OAuth gate |\n| Routed test seam — `createRouteHandler(opts, getUser)` | the val running it | `{ user, prefix }` | prefix-stripped | routing, no OAuth _(from the contract)_ |\n| Manual — host calls the handler itself, no `createRouter` | that host val | whatever host passes | whatever host strips | none — you reimplement strip + Location rewrite _(from the contract)_ |\n\nNotes:\n\n- The two standalone rows are the **same mechanism**\n (`export default\n factory()`, no `ctx`); only which val holds the export\n differs, and that is what flips the host.\n- Routed: `ctx.prefix` is `/slug` (no trailing slash), and the handler receives\n the path already stripped of it. With Hono, `ctx` arrives as `c.env`.\n- `createRouter` returns a bare handler, not an `Integration` (no\n `slug`/`name`), so routers don't nest into another router's `integrations[]`\n without re-wrapping in `defineIntegration`.\n\nTwo orthogonal axes for classifying an integration:\n\n- **Interface** — full web UI / API-only / both. (The issue tracker is already\n both.)\n- **Subject** — self-owned domain (issues, subscriptions) vs\n host-reflective/introspective (docs, version history, env). Host-reflective\n can wear any interface.\n\n---\n\n## 2. Host self-identification\n\nVal Town injects `VALTOWN_ENTRYPOINT` — the `import.meta.url` of the file it\nexecuted — into the process env. The `std/utils` file helpers default to it. So\nfrom inside a mounted integration:\n\n- `parseVal()` → `{ username, name, version, branch }` of the **host** (the\n executed val).\n- `listFiles()` → the host's full file tree. This is the multi-file answer:\n enumerate, then `readFile` each source.\n- `readFile(path)` → the host's source for one file. Use `readFile`, not\n `readFileTranspiled`, to keep JSDoc and type annotations.\n- `getValId()` → the host's UUID (rename-stable cache key).\n- `parseVal(import.meta.url)` → the integration's **own** val (overrides the\n default).\n\n**Rule:** host = the executed val; self = `import.meta.url`, always. Everything\nhost-scoped (blob, SQLite, `parseVal`, `listFiles`) keys off the host by the\nsame execution-context mechanism that scoped storage already uses.\n\nVerified with a `whoami` probe returning `{ host, self }`:\n\n- Standalone, own val → `host == self` (the toy).\n- Standalone, wrapper val → `host` = wrapper, `self` = toy.\n- Routed → `host` = router, `self` = toy; `hostFileCount` reflected the router's\n files, not the toy's.\n\nImplication for a host-reflective integration (e.g. a docs generator): default\nsubject = `parseVal()` (the host); keep any `?val=` query param as an _override_\nfor a \"document any val\" mode. Scoped blob is already per-host, so a\ngenerated-content cache auto-isolates — key entries by `parseVal().version` to\ninvalidate on redeploy. Reads use the host's scoped token, so private host\nsource is readable; expose rendered output deliberately.\n\n---\n\n## 3. A client-side SPA as an integration frontend\n\nThe router strips the prefix (the handler runs as if at root) and rewrites\n**Location headers only**, never bodies. So a SPA survives mounting when split\ninto three surfaces by who serves them:\n\n1. **HTML shell** — served by the handler at `/`. Every browser-resolved URL in\n it is **relative** (or an absolute esm.town URL), never root-absolute.\n2. **Client bundle** — referenced by an **absolute esm.town URL**\n (`https://esm.town/v/you/val/frontend/index.tsx`). Prefix-immune; the browser\n fetches it straight from esm.town, so the host only proxies shell + API.\n Requires the integration val to be public/unlisted — a private val's esm.town\n URL won't serve to the browser. Alternative: serve it through the handler\n with `staticHTTPServer(import.meta.url, app.fetch)`, passing\n `import.meta.url` explicitly (its default `VALTOWN_ENTRYPOINT` would\n otherwise serve the **host's** files as your frontend).\n3. **Host-data API** (`/api/*`) — the only genuinely host-scoped surface;\n reached by **relative** `fetch(\"api/...\")`.\n\nTwo rules make it work:\n\n- Everything the browser resolves is relative. The router canonicalizes `/slug`\n → `/slug/` (trailing slash) so relative URLs resolve inside the mount.\n- The client derives its API base once at boot:\n `const API_BASE = new URL(\".\", location.href)`, then\n `fetch(new URL(\"api/state\", API_BASE))`. No server injection; works at `/`\n standalone and `/slug/` mounted.\n\nUse **hash-based** client routing so `location.pathname` stays at the mount root\nand the derived base stays valid (path routing would need a shell catch-all plus\na base-aware router). The React component tree itself doesn't change to mount —\nonly these edges do.\n\n---\n\n## 4. Versioning: cross-val imports are lockfile-pinned\n\nWhen a host imports an integration across the esm.town boundary\n(`import { x } from \"https://esm.town/v/you/int/mod.ts\"`), the resolved version\nis written into the **host val's lockfile** and is sticky by design.\n\n- An unpinned specifier is **not** live-latest and **not** refreshed by a\n redeploy — the redeploy honors the existing lock entry. (A single edit-fused\n request can transiently resolve latest in a cold isolate, which is misleading;\n steady-state traffic keeps the locked version.)\n- Forcing an update requires **re-resolution**: reset the lockfile, or cycle the\n specifier (pin → unpin). After that, unpinned re-resolves to current and locks\n again.\n- Pin `@ver-branch` (e.g. `@8-main`) for a deterministic version you control —\n it's an immutable URL and never moves.\n\nVerified: added a route to the toy, then hit it through a wrapper that imported\nunpinned. The new route 404'd (the wrapper was locked to the pre-change version)\nwhile unchanged routes still worked. Pinning the wrapper to the old version\nreproduced the 404 deterministically; resetting the lock and unpinning brought\nthe new route back.\n\nGuidance for shipping integrations: tell consumers \"unpinned is a locked\nsnapshot you update by re-resolving; pin `@ver` for stability.\" This is also why\nthe contract ships breaking changes as a **new entrypoint** rather than mutating\n`mod.ts` — existing hosts stay locked to whatever they resolved.","createdAt",["D",1783802802386],"branchVersion","branchId","e42b787b-83d6-45c3-a695-f58ae023cdb8","id","3688ffe3-491b-42ec-b390-53d2293f502f","integrations",["D",1783715038579],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","","imageUrl","5d1042a9-7b0b-499d-8a72-3a8ac7a4e185","pinnedFileId","pinPreview","pinMigrated","screenshotVersion","likeCount",0,"orgId","5f80108f-7ca4-4327-b77b-089dbe4b5a82","tursoName","3688ffe3491b42ecb39053d2293f502f","tursoHostname","3688ffe3491b42ecb39053d2293f502f-val-town.aws-us-east-2.turso.io","tursoMeasuredAt",["D",1789525245864],"pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_97":96,"_104":100},"org",{"_97":96,"_98":-5,"_99":100,"_18":54,"_101":102,"_103":25},"branch",{"_13":86,"_32":87,"_42":41,"_88":43,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":-5,"_94":44,"_95":96},"isOwned",261,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","nbbaier","handle","displayName","avatar","https://secure.gravatar.com/avatar/0129a541b7b3574e92c4afd06c5e32da&d=identicon","tier","pro","canRestrictVals","profileImageUrl","branchName","adoptOrgId",{"_42":43,"_32":44,"_37":478,"_46":-5,"_47":25,"_48":49,"_50":49,"_51":52,"_53":-5,"_18":54,"_55":-5,"_56":25,"_57":-5,"_58":-5,"_59":60,"_61":62,"_63":64,"_65":66,"_67":479,"_69":-5,"_70":71,"_72":71,"_73":74,"_75":74,"_76":74,"_77":71,"_78":71,"_79":480,"_81":481,"_83":482,"_85":25},"tree",[240,260,264,265,266,267,268,269,270,271,272,273],"files",[240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255,256,257,258,259,260,261,262,263,264,265,266,267,268,269,270,271,272,273],"counts",{"_230":60,"_231":146,"_232":60,"_233":234,"_235":236},"contents",[127,128,129,130,131,132,133,134,135,136,137,138],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles",true,"grants","orgs","customDomains",{},{"_42":224,"_32":225,"_30":226,"_142":-5,"_40":41,"_39":227,"_144":122,"_37":228,"_13":60,"_34":222,"_35":-5,"_24":25,"_149":-5,"_27":229},{"_42":217,"_32":218,"_30":219,"_142":-5,"_40":41,"_39":220,"_144":122,"_37":221,"_13":60,"_34":222,"_35":-5,"_24":25,"_149":-5,"_27":223},{"_42":210,"_32":211,"_30":212,"_142":-5,"_40":41,"_39":213,"_144":122,"_37":214,"_13":60,"_34":20,"_35":215,"_24":25,"_149":-5,"_27":216},{"_42":203,"_32":204,"_30":205,"_142":-5,"_40":41,"_39":206,"_144":25,"_37":207,"_13":180,"_34":20,"_35":208,"_24":25,"_149":-5,"_27":209},{"_42":196,"_32":197,"_30":198,"_142":-5,"_40":41,"_39":199,"_144":25,"_37":200,"_13":180,"_34":20,"_35":201,"_24":25,"_149":-5,"_27":202},{"_42":189,"_32":190,"_30":191,"_142":-5,"_40":41,"_39":192,"_144":25,"_37":193,"_13":156,"_34":20,"_35":194,"_24":25,"_149":-5,"_27":195},{"_42":183,"_32":184,"_30":185,"_142":-5,"_40":41,"_39":156,"_144":25,"_37":186,"_13":60,"_34":20,"_35":187,"_24":25,"_149":-5,"_27":188},{"_42":175,"_32":176,"_30":177,"_142":-5,"_40":41,"_39":178,"_144":25,"_37":179,"_13":180,"_34":20,"_35":181,"_24":25,"_149":-5,"_27":182},{"_42":166,"_32":167,"_30":168,"_142":-5,"_40":41,"_39":169,"_144":25,"_37":170,"_13":171,"_34":172,"_35":173,"_24":25,"_149":-5,"_27":174},{"_42":159,"_32":160,"_30":161,"_142":-5,"_40":41,"_39":162,"_144":25,"_37":163,"_13":156,"_34":147,"_35":164,"_24":25,"_149":-5,"_27":165},{"_42":151,"_32":152,"_30":153,"_142":-5,"_40":41,"_39":154,"_144":25,"_37":155,"_13":156,"_34":147,"_35":157,"_24":25,"_149":-5,"_27":158},{"_42":139,"_32":140,"_30":141,"_142":-5,"_40":41,"_39":143,"_144":25,"_37":145,"_13":146,"_34":147,"_35":148,"_24":25,"_149":-5,"_27":150},"e82a3846-9a4b-4c4c-98cd-9618b617cea5","router_test.ts","47cd43fc-7cb8-11f1-bf06-1607ee4eb77e","parentId",71,"latest",["D",1783785020744],1,"script","import { assert, assertEquals, assertThrows } from \"@std/assert\";\nimport {\n\tcreateRouteHandler,\n\tdefineIntegration,\n\ttype IntegrationContext,\n\ttype RouterOptions,\n} from \"./router.ts\";\n\nconst anon = () => Promise.resolve(null);\nconst as = (user: string) => () => Promise.resolve(user);\n\nfunction echoIntegration(slug: string, name = slug) {\n\tlet lastCtx: IntegrationContext | undefined;\n\tconst integration = defineIntegration({\n\t\tname,\n\t\tslug,\n\t\thandler: async (req, ctx) => {\n\t\t\tlastCtx = ctx;\n\t\t\tconst url = new URL(req.url);\n\t\t\tif (req.method === \"POST\") {\n\t\t\t\treturn new Response(`echo:${await req.text()}`);\n\t\t\t}\n\t\t\tif (url.pathname === \"/redirect\") {\n\t\t\t\treturn new Response(null, {\n\t\t\t\t\tstatus: 302,\n\t\t\t\t\theaders: { Location: \"/?ok=done\" },\n\t\t\t\t});\n\t\t\t}\n\t\t\tif (url.pathname === \"/redirect-external\") {\n\t\t\t\treturn new Response(null, {\n\t\t\t\t\tstatus: 302,\n\t\t\t\t\theaders: { Location: \"https://example.com/x\" },\n\t\t\t\t});\n\t\t\t}\n\t\t\tif (url.pathname === \"/redirect-protocol-relative\") {\n\t\t\t\treturn new Response(null, {\n\t\t\t\t\tstatus: 302,\n\t\t\t\t\theaders: { Location: \"//example.com/x\" },\n\t\t\t\t});\n\t\t\t}\n\t\t\treturn new Response(`path:${url.pathname}`);\n\t\t},\n\t});\n\treturn { integration, ctx: () => lastCtx };\n}\n\nfunction router(opts: Partial, getUser = anon) {\n\treturn createRouteHandler(\n\t\t{ integrations: [], auth: false, ...opts },\n\t\tgetUser,\n\t);\n}\n\n// ---------------------------------------------------------------------------\n// Validation\n// ---------------------------------------------------------------------------\n\nDeno.test(\"defineIntegration rejects invalid slugs\", () => {\n\tfor (const slug of [\"\", \"Bad\", \"has_underscore\", \"has space\", \"café\"]) {\n\t\tassertThrows(\n\t\t\t() =>\n\t\t\t\tdefineIntegration({ name: \"x\", slug, handler: () => new Response() }),\n\t\t\tError,\n\t\t\t\"invalid\",\n\t\t);\n\t}\n});\n\nDeno.test(\"reserved slugs throw\", () => {\n\tassertThrows(\n\t\t() =>\n\t\t\tdefineIntegration({\n\t\t\t\tname: \"x\",\n\t\t\t\tslug: \"auth\",\n\t\t\t\thandler: () => new Response(),\n\t\t\t}),\n\t\tError,\n\t\t\"reserved\",\n\t);\n});\n\nDeno.test(\"duplicate slugs throw at construction\", () => {\n\tconst a = echoIntegration(\"toy\").integration;\n\tconst b = echoIntegration(\"toy\").integration;\n\tassertThrows(() => router({ integrations: [a, b] }), Error, \"Duplicate\");\n});\n\nDeno.test(\"defineIntegration returns a callable integration serving both modes\", async () => {\n\tconst integration = defineIntegration({\n\t\tname: \"Toy Thing\",\n\t\tslug: \"toy\",\n\t\thandler: (_req, ctx) => new Response(`user:${ctx?.user ?? \"none\"}`),\n\t});\n\t// Integration fields survive on the callable (incl. `name`, which must\n\t// shadow the function's own read-only name).\n\tassertEquals(integration.name, \"Toy Thing\");\n\tassertEquals(integration.slug, \"toy\");\n\t// Standalone: called as a plain HTTP handler, no ctx.\n\tconst standalone = await integration(new Request(\"https://r.test/\"));\n\tassertEquals(await standalone.text(), \"user:none\");\n\t// Routed: ctx flows through to the wrapped handler.\n\tconst routed = await integration(new Request(\"https://r.test/\"), {\n\t\tuser: \"nbbaier\",\n\t\tprefix: \"/toy\",\n\t});\n\tassertEquals(await routed.text(), \"user:nbbaier\");\n});\n\n// ---------------------------------------------------------------------------\n// Dispatch\n// ---------------------------------------------------------------------------\n\nDeno.test(\"dispatch strips the prefix and passes ctx\", async () => {\n\tconst { integration, ctx } = echoIntegration(\"toy\");\n\tconst handle = router({ integrations: [integration] });\n\tconst res = await handle(new Request(\"https://r.test/toy/deep/path?q=1\"));\n\tassertEquals(await res.text(), \"path:/deep/path\");\n\tassertEquals(ctx()?.prefix, \"/toy\");\n\tassertEquals(ctx()?.user, null);\n});\n\nDeno.test(\"bare /slug canonicalizes to /slug/ preserving the query\", async () => {\n\tconst { integration } = echoIntegration(\"toy\");\n\tconst handle = router({ integrations: [integration] });\n\tconst res = await handle(new Request(\"https://r.test/toy?q=1\"));\n\tassertEquals(res.status, 302);\n\tassertEquals(res.headers.get(\"Location\"), \"/toy/?q=1\");\n});\n\nDeno.test(\"POST bodies survive the rewrite\", async () => {\n\tconst { integration } = echoIntegration(\"toy\");\n\tconst handle = router({ integrations: [integration] });\n\tconst res = await handle(\n\t\tnew Request(\"https://r.test/toy/\", { method: \"POST\", body: \"hello\" }),\n\t);\n\tassertEquals(await res.text(), \"echo:hello\");\n});\n\nDeno.test(\"unknown paths 404; root serves the directory\", async () => {\n\tconst { integration } = echoIntegration(\"toy\", \"Toy Thing\");\n\tconst handle = router({ integrations: [integration], title: \"My Tools\" });\n\tassertEquals((await handle(new Request(\"https://r.test/nope\"))).status, 404);\n\tconst dir = await handle(new Request(\"https://r.test/\"));\n\tassertEquals(dir.status, 200);\n\tconst html = await dir.text();\n\tassert(html.includes(\"My Tools\"));\n\tassert(html.includes(\"Toy Thing\"));\n\tassert(html.includes(`href=\"toy/\"`)); // relative link, per the hygiene rule\n});\n\nDeno.test(\"directory badges missing requiredEnv\", async () => {\n\tconst integration = defineIntegration({\n\t\tname: \"Needy\",\n\t\tslug: \"needy\",\n\t\trequiredEnv: [\"DEFINITELY_NOT_SET_FOR_TESTS_XYZ\"],\n\t\thandler: () => new Response(),\n\t});\n\tconst handle = router({ integrations: [integration] });\n\tconst html = await (await handle(new Request(\"https://r.test/\"))).text();\n\tassert(html.includes(\"missing env\"));\n\tassert(html.includes(\"DEFINITELY_NOT_SET_FOR_TESTS_XYZ\"));\n});\n\n// ---------------------------------------------------------------------------\n// Location rewriting (ADR 0002)\n// ---------------------------------------------------------------------------\n\nDeno.test(\"root-absolute Location headers get the prefix prepended\", async () => {\n\tconst { integration } = echoIntegration(\"toy\");\n\tconst handle = router({ integrations: [integration] });\n\tconst res = await handle(new Request(\"https://r.test/toy/redirect\"));\n\tassertEquals(res.headers.get(\"Location\"), \"/toy/?ok=done\");\n});\n\nDeno.test(\"absolute and protocol-relative Locations pass through untouched\", async () => {\n\tconst { integration } = echoIntegration(\"toy\");\n\tconst handle = router({ integrations: [integration] });\n\tconst abs = await handle(new Request(\"https://r.test/toy/redirect-external\"));\n\tassertEquals(abs.headers.get(\"Location\"), \"https://example.com/x\");\n\tconst proto = await handle(\n\t\tnew Request(\"https://r.test/toy/redirect-protocol-relative\"),\n\t);\n\tassertEquals(proto.headers.get(\"Location\"), \"//example.com/x\");\n});\n\n// ---------------------------------------------------------------------------\n// Auth gate\n// ---------------------------------------------------------------------------\n\nDeno.test(\"auth on: anonymous GET gets the login page, non-GET bounces home\", async () => {\n\tconst { integration } = echoIntegration(\"toy\");\n\tconst handle = router({ integrations: [integration], auth: {} });\n\tconst res = await handle(new Request(\"https://r.test/toy/\"));\n\tassertEquals(res.status, 401);\n\tassert((await res.text()).includes(\"/auth/login\"));\n\tconst post = await handle(\n\t\tnew Request(\"https://r.test/toy/\", { method: \"POST\", body: \"x\" }),\n\t);\n\tassertEquals(post.status, 302);\n\tassertEquals(post.headers.get(\"Location\"), \"/\");\n});\n\nDeno.test(\"auth on: logged-in user reaches the integration with ctx.user set\", async () => {\n\tconst { integration, ctx } = echoIntegration(\"toy\");\n\tconst handle = router(\n\t\t{ integrations: [integration], auth: {} },\n\t\tas(\"nbbaier\"),\n\t);\n\tconst res = await handle(new Request(\"https://r.test/toy/\"));\n\tassertEquals(res.status, 200);\n\tassertEquals(ctx()?.user, \"nbbaier\");\n});\n\nDeno.test(\"allowlist: outsiders get 403, listed users get in\", async () => {\n\tconst { integration } = echoIntegration(\"toy\");\n\tconst opts = { integrations: [integration], auth: { users: [\"nbbaier\"] } };\n\tconst outsider = router(opts, as(\"mallory\"));\n\tassertEquals(\n\t\t(await outsider(new Request(\"https://r.test/toy/\"))).status,\n\t\t403,\n\t);\n\tconst owner = router(opts, as(\"nbbaier\"));\n\tassertEquals((await owner(new Request(\"https://r.test/toy/\"))).status, 200);\n});\n\nDeno.test(\"auth off: ctx.user is null and everything is open\", async () => {\n\tconst { integration, ctx } = echoIntegration(\"toy\");\n\tconst handle = router({ integrations: [integration], auth: false });\n\tconst res = await handle(new Request(\"https://r.test/toy/\"));\n\tassertEquals(res.status, 200);\n\tassertEquals(ctx()?.user, null);\n});\n","label",[140],"6d9c7cc6-2910-4978-adbd-ba54003f0921","router.ts","47659324-7cb8-11f1-b846-1607ee4eb77e",67,["D",1783785020715],2,"// The integrations contract and router. Public surface is re-exported from\n// mod.ts; import from there. See docs/adr/ for the dispatch architecture\n// (0001) and Location-rewriting (0002) decisions.\nimport {\n\tgetOAuthUserData,\n\toauthMiddleware,\n} from \"https://esm.town/v/std/oauth/middleware.ts\";\n\nexport interface IntegrationContext {\n\t/** Val Town username from router-owned OAuth; null when auth is off. */\n\tuser: string | null;\n\t/** Mount prefix, e.g. \"/issues\". */\n\tprefix: string;\n}\n\nexport type IntegrationHandler = (\n\treq: Request,\n\tctx?: IntegrationContext,\n) => Response | Promise;\n\nexport interface Integration {\n\tname: string;\n\tslug: string;\n\tdescription?: string;\n\t/** Env vars the integration needs; missing ones badge the directory page. */\n\trequiredEnv?: string[];\n\thandler: IntegrationHandler;\n}\n\n/**\n * An Integration that is also directly callable as an HTTP handler, so the\n * same factory return value serves both modes (ADR 0003):\n *\n * export default myIntegration({...}); // standalone val\n * createRouter({ integrations: [myIntegration({...})] }); // routed\n */\nexport type CallableIntegration = Integration & IntegrationHandler;\n\nexport type RouterAuthOptions = { users?: string | string[] } | false;\n\nexport interface RouterOptions {\n\t/** Order here is the directory page order. */\n\tintegrations: Integration[];\n\t/** Default: on, any logged-in Val Town user. `false` disables the gate. */\n\tauth?: RouterAuthOptions;\n\ttitle?: string;\n}\n\nconst SLUG_PATTERN = /^[a-z0-9-]+$/;\n// \"auth\" is std/oauth's fixed /auth/* mount; /^_/ is the router-owned\n// namespace, reserved forever so the set never needs to grow again.\nconst RESERVED_SLUGS: (string | RegExp)[] = [\"auth\", /^_/];\n\nfunction isReserved(slug: string): boolean {\n\treturn RESERVED_SLUGS.some((r) =>\n\t\ttypeof r === \"string\" ? r === slug : r.test(slug),\n\t);\n}\n\nfunction validateSlug(slug: string): void {\n\tif (!SLUG_PATTERN.test(slug)) {\n\t\tthrow new Error(\n\t\t\t`Integration slug \"${slug}\" is invalid: slugs must match ${SLUG_PATTERN}.`,\n\t\t);\n\t}\n\tif (isReserved(slug)) {\n\t\tthrow new Error(`Integration slug \"${slug}\" is reserved by the router.`);\n\t}\n}\n\nexport function defineIntegration(\n\tintegration: Integration,\n): CallableIntegration {\n\tvalidateSlug(integration.slug);\n\tconst callable = ((req: Request, ctx?: IntegrationContext) =>\n\t\tintegration.handler(req, ctx)) as CallableIntegration;\n\tfor (const [key, value] of Object.entries(integration)) {\n\t\tif (value === undefined) continue;\n\t\t// defineProperty, not assignment: a function's own `name` is read-only\n\t\t// (but configurable), and Integration.name must shadow it.\n\t\tObject.defineProperty(callable, key, {\n\t\t\tvalue,\n\t\t\tenumerable: true,\n\t\t\tconfigurable: true,\n\t\t\twritable: true,\n\t\t});\n\t}\n\treturn callable;\n}\n\n// ---------------------------------------------------------------------------\n// HTML\n// ---------------------------------------------------------------------------\n\nfunction escapeHtml(s: string): string {\n\treturn s.replace(\n\t\t/[&<>\"']/g,\n\t\t(c) =>\n\t\t\t({\n\t\t\t\t\"&\": \"&\",\n\t\t\t\t\"<\": \"<\",\n\t\t\t\t\">\": \">\",\n\t\t\t\t'\"': \""\",\n\t\t\t\t\"'\": \"'\",\n\t\t\t})[c] as string,\n\t);\n}\n\nfunction page(title: string, body: string, status = 200): Response {\n\treturn new Response(\n\t\t`\n\n${escapeHtml(title)}\n${body}`,\n\t\t{ status, headers: { \"Content-Type\": \"text/html; charset=utf-8\" } },\n\t);\n}\n\nfunction missingEnv(keys: string[] | undefined): string[] {\n\tif (!keys) return [];\n\treturn keys.filter((k) => {\n\t\ttry {\n\t\t\treturn !Deno.env.get(k);\n\t\t} catch {\n\t\t\treturn false; // no env permission — don't false-alarm\n\t\t}\n\t});\n}\n\nfunction directoryPage(\n\toptions: RouterOptions,\n\tuser: string | null,\n\tauthEnabled: boolean,\n): Response {\n\tconst title = options.title ?? \"Integrations\";\n\tconst items = options.integrations\n\t\t.map((i) => {\n\t\t\tconst missing = missingEnv(i.requiredEnv);\n\t\t\treturn `

${escapeHtml(i.name)}\n${i.description ? `

${escapeHtml(i.description)}

` : \"\"}\n${\n\tmissing.length > 0\n\t\t? `

⚠️ missing env: ${missing.map((k) => `${escapeHtml(k)}`).join(\", \")}

`\n\t\t: \"\"\n}

`;\n\t\t})\n\t\t.join(\"\\n\");\n\n\tconst who = authEnabled\n\t\t? user\n\t\t\t? `

@${escapeHtml(user)} ·\n

`\n\t\t\t: \"\"\n\t\t: \"\";\n\n\treturn page(\n\t\ttitle,\n\t\t`

${escapeHtml(title)}

${who}

\n${\n\toptions.integrations.length === 0\n\t\t? `

No integrations registered.

`\n\t\t: `

${items}`\n}`,\n\t);\n}\n\nfunction loginPage(options: RouterOptions): Response {\n\tconst title = options.title ?? \"Integrations\";\n\tconst users = allowedUsers(options.auth);\n\tconst hasKey = missingEnv([\"OAUTH_STATE_ENCRYPTION_KEY\"]).length === 0;\n\treturn page(\n\t\ttitle,\n\t\t`

${escapeHtml(title)}

${\n\t\t\tusers\n\t\t\t\t? `Access is restricted to ${users.map((u) => `@${escapeHtml(u)}`).join(\", \")}.`\n\t\t\t\t: \"Open to any logged-in Val Town account.\"\n\t\t}

\n${\n\thasKey\n\t\t? \"\"\n\t\t: `

⚠️ This val has no OAUTH_STATE_ENCRYPTION_KEY env var;\nlogin will fail until one is set (any random 32-byte hex string).

`\n}`,\n\t\t401,\n\t);\n}\n\n// ---------------------------------------------------------------------------\n// Router\n// ---------------------------------------------------------------------------\n\nfunction allowedUsers(auth: RouterAuthOptions | undefined): string[] | null {\n\tif (auth === false || auth?.users == null) return null;\n\treturn Array.isArray(auth.users) ? auth.users : [auth.users];\n}\n\n// Root-absolute (single leading slash): \"/x\" yes; \"//host/x\" and full URLs no.\nconst ROOT_ABSOLUTE = /^\\/(?!\\/)/;\n\nfunction rewriteLocation(res: Response, prefix: string): Response {\n\tconst location = res.headers.get(\"Location\");\n\tif (!location || !ROOT_ABSOLUTE.test(location)) return res;\n\tconst rewritten = new Response(res.body, res);\n\trewritten.headers.set(\"Location\", prefix + location);\n\treturn rewritten;\n}\n\ntype GetUser = (req: Request) => Promise;\n\n/**\n * The route handler minus the OAuth wrapper, with user lookup injected —\n * exported for tests. Use createRouter, which wires the real lookup.\n */\nexport function createRouteHandler(\n\toptions: RouterOptions,\n\tgetUser: GetUser,\n): (req: Request) => Promise {\n\tconst seen = new Set();\n\tfor (const i of options.integrations) {\n\t\tvalidateSlug(i.slug);\n\t\tif (seen.has(i.slug)) {\n\t\t\tthrow new Error(`Duplicate integration slug \"${i.slug}\".`);\n\t\t}\n\t\tseen.add(i.slug);\n\t}\n\n\tconst authEnabled = options.auth !== false;\n\tconst allowlist = allowedUsers(options.auth);\n\n\treturn async (req: Request): Promise => {\n\t\tconst url = new URL(req.url);\n\n\t\tlet user: string | null = null;\n\t\tif (authEnabled) {\n\t\t\tuser = await getUser(req);\n\t\t\tif (!user) {\n\t\t\t\tif (req.method !== \"GET\") {\n\t\t\t\t\treturn new Response(null, {\n\t\t\t\t\t\tstatus: 302,\n\t\t\t\t\t\theaders: { Location: \"/\" },\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\treturn loginPage(options);\n\t\t\t}\n\t\t\tif (allowlist && !allowlist.includes(user)) {\n\t\t\t\treturn page(\n\t\t\t\t\toptions.title ?? \"Integrations\",\n\t\t\t\t\t`

403

Signed in as @${escapeHtml(user)}, but access is restricted to\n${allowlist.map((u) => `@${escapeHtml(u)}`).join(\", \")}.

\n`,\n\t\t\t\t\t403,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\tfor (const i of options.integrations) {\n\t\t\tconst prefix = `/${i.slug}`;\n\t\t\t// Canonicalize /slug → /slug/ so relative URLs resolve inside the mount.\n\t\t\tif (url.pathname === prefix) {\n\t\t\t\treturn new Response(null, {\n\t\t\t\t\tstatus: 302,\n\t\t\t\t\theaders: { Location: `${prefix}/${url.search}` },\n\t\t\t\t});\n\t\t\t}\n\t\t\tif (url.pathname.startsWith(`${prefix}/`)) {\n\t\t\t\tconst childUrl = new URL(url);\n\t\t\t\tchildUrl.pathname = url.pathname.slice(prefix.length);\n\t\t\t\tconst childReq = new Request(childUrl, {\n\t\t\t\t\tmethod: req.method,\n\t\t\t\t\theaders: req.headers,\n\t\t\t\t\t// Buffered, not streamed: Request re-wrapping needs a settled body.\n\t\t\t\t\tbody:\n\t\t\t\t\t\treq.method === \"GET\" || req.method === \"HEAD\"\n\t\t\t\t\t\t\t? undefined\n\t\t\t\t\t\t\t: await req.blob(),\n\t\t\t\t});\n\t\t\t\tconst res = await i.handler(childReq, { user, prefix });\n\t\t\t\treturn rewriteLocation(res, prefix);\n\t\t\t}\n\t\t}\n\n\t\tif (url.pathname === \"/\") {\n\t\t\treturn directoryPage(options, user, authEnabled);\n\t\t}\n\n\t\treturn page(\n\t\t\t\"Not found\",\n\t\t\t`

404

← back to the directory

`,\n\t\t\t404,\n\t\t);\n\t};\n}\n\nasync function oauthUser(req: Request): Promise {\n\tconst session = await getOAuthUserData(req);\n\treturn session?.user?.username ?? null;\n}\n\nexport function createRouter(\n\toptions: RouterOptions,\n): (req: Request) => Response | Promise {\n\tconst handler = createRouteHandler(options, oauthUser);\n\treturn options.auth === false ? handler : oauthMiddleware(handler);\n}\n",[152],"431aa351-c131-419a-8700-373a1ffbc577","mod.ts","4795d00c-7cb8-11f1-a2c1-1607ee4eb77e",72,["D",1783785117512],"export {\n\ttype CallableIntegration,\n\t// The OAuth-free router core with user lookup injected — the public test\n\t// seam for integration authors to exercise routed mode without a session.\n\tcreateRouteHandler,\n\tcreateRouter,\n\tdefineIntegration,\n\ttype Integration,\n\ttype IntegrationContext,\n\ttype IntegrationHandler,\n\ttype RouterAuthOptions,\n\ttype RouterOptions,\n} from \"./router.ts\";\n",[160],"a0943a33-567d-47bb-8723-6e5dcd5c71fd","main.ts","477921dc-7cb8-11f1-94e8-1607ee4eb77e",107,["D",1783791740998],6,"http","// This val's own consumer of its router.\nimport { blobAdmin } from \"https://esm.town/v/nbbaier/scoped-blob-viewer/mod.ts\";\nimport { issueTracker } from \"https://esm.town/v/nbbaier/val-issue-tracker/mod.ts\";\nimport { helloWorld } from \"./example/hello.ts\";\nimport { createRouter } from \"./mod.ts\";\n\nexport default createRouter({\n\ttitle: \"Integrations\",\n\tauth: { users: \"nbbaier\" },\n\tintegrations: [issueTracker({}), blobAdmin({}), helloWorld()],\n});\n",[167],"7dc7ffcd-ef7c-42fc-9ed6-201654c6a901","deno.json","525df192-7c9d-11f1-a2d0-1607ee4eb77e",99,["D",1783788334915],3,"{\n\t\"compilerOptions\": {\n\t\t\"lib\": [\n\t\t\t\"dom\",\n\t\t\t\"dom.iterable\",\n\t\t\t\"dom.asynciterable\",\n\t\t\t\"deno.ns\",\n\t\t\t\"deno.unstable\"\n\t\t],\n\t\t\"noImplicitAny\": false,\n\t\t\"strict\": false,\n\t\t\"types\": [\"https://www.val.town/types/valtown.d.ts\"]\n\t},\n\t\"experimental\": {\n\t\t\"unstable-node-globals\": true,\n\t\t\"unstable-sloppy-imports\": true,\n\t\t\"unstable-temporal\": true,\n\t\t\"unstable-worker-options\": true\n\t},\n\t\"imports\": {\n\t\t\"@biomejs/biome\": \"npm:@biomejs/biome@^2.5.2\",\n\t\t\"@std/assert\": \"jsr:@std/assert@^1.0.19\"\n\t},\n\t\"lint\": {\n\t\t\"include\": [\"*.ts\", \"*.tsx\", \"example/*.ts\"],\n\t\t\"rules\": {\n\t\t\t\"exclude\": [\"no-explicit-any\", \"no-import-prefix\"]\n\t\t}\n\t},\n\t\"lock\": false,\n\t\"nodeModulesDir\": \"auto\",\n\t\"tasks\": {\n\t\t\"fmt\": \"biome check . --write\",\n\t\t\"lint\": \"deno lint\",\n\t\t\"typecheck\": \"VAL_TOWN_API_KEY=test deno check --allow-import=esm.town,www.val.town,esm.sh,jsr.io main.ts mod.ts router.ts router_test.ts example/hello.ts example/hello_test.ts\",\n\t\t\"test\": \"VAL_TOWN_API_KEY=test deno test --allow-env --allow-import=esm.town,www.val.town,esm.sh,jsr.io\",\n\t\t\"check\": \"deno task fmt && deno task lint && deno task typecheck && deno task test\"\n\t}\n}\n",[176],"572f178d-7191-48b5-953e-7ac6c0917590","biome.json","52555852-7c9d-11f1-80bb-1607ee4eb77e",["D",1783715055805],"{\n\t\"$schema\": \"https://biomejs.dev/schemas/2.5.2/schema.json\",\n\t\"vcs\": {\n\t\t\"enabled\": false,\n\t\t\"clientKind\": \"git\",\n\t\t\"useIgnoreFile\": false\n\t},\n\t\"files\": {\n\t\t\"ignoreUnknown\": false\n\t},\n\t\"formatter\": {\n\t\t\"enabled\": true,\n\t\t\"indentStyle\": \"tab\"\n\t},\n\t\"linter\": {\n\t\t\"enabled\": true,\n\t\t\"rules\": {\n\t\t\t\"preset\": \"recommended\"\n\t\t}\n\t},\n\t\"javascript\": {\n\t\t\"formatter\": {\n\t\t\t\"quoteStyle\": \"double\"\n\t\t}\n\t},\n\t\"assist\": {\n\t\t\"enabled\": true,\n\t\t\"actions\": {\n\t\t\t\"source\": {\n\t\t\t\t\"organizeImports\": \"on\"\n\t\t\t}\n\t\t}\n\t}\n}\n",[184],"7de21f57-a3c4-4b97-8670-04d3f87d0fa5","README.md","de745920-7d4f-11f1-896c-1607ee4eb77e",133,["D",1783793917943],"# integrations\n\nA contract and router for mounting reusable web apps — **integrations** — into a\nsingle Val Town val. One val, one login, one URL; many project-level tools\nserved underneath it.\n\n```\nhttps://you-integrations.web.val.run/ → directory page\n /issues/ → the issue tracker\n /blobs/ → the blob viewer\n /hello/ → your integration\n```\n\nThe router mounts each integration **in-process** and dispatches by path prefix\n(no per-integration redirects, no separate logins). It owns authentication,\nserves a directory page at `/`, and passes each integration a small context —\nthe logged-in user and its mount prefix. See [`docs/adr/`](docs/adr/) for the\narchitecture decisions behind this.\n\n## The pattern\n\nAn **integration** is a mountable sub-app over a Val Town scoped resource: a\nself-contained web app — UI, routes, and its own authorization — wrapped around\none val-scoped thing (a SQLite-backed domain, the blob store). The contract\nhere is that shape extracted from two apps that already had it\n([`val-issue-tracker`](https://www.val.town/x/nbbaier/val-issue-tracker) and\n[`scoped-blob-viewer`](https://www.val.town/x/nbbaier/scoped-blob-viewer)).\n\nWhat makes it more than a mounted sub-router is Val Town's scoping: because\nscoped SQLite/blob bind to whichever val's runtime is **executing** the code, an\nintegration operates on its **host val's** data and identity just by being\nimported — no tokens, no config. Three properties fall out of that:\n\n- **Host-scoped, not self-scoped** — drop it into any val and it points at that\n val's storage automatically.\n- **Portable / dual-mode** — the same value runs standalone (a val's HTTP\n export) or routed (mounted at `/slug/`), thanks to relative-only links and a\n callable contract.\n- **Composable** — it keeps its own authorization but lifts authentication up to\n the host or router, so many integrations stack behind one origin and one\n login.\n\nThe closest analogies are Rails engines or Hono/Express sub-apps mounted at a\nprefix — but host-scoped, so mounting also inherits the host's data and identity\nfor free.\n\nThere are two audiences below: [**mounting integrations**](#mounting-integrations)\nif you want to run a router, and [**writing an integration**](#writing-an-integration)\nif you want to build one.\n\n---\n\n## Mounting integrations\n\nImport the integrations you want and hand them to `createRouter`. Its return value\nis a plain HTTP handler — make it your val's default export.\n\n```ts\nimport { createRouter } from \"https://esm.town/v/nbbaier/integrations/mod.ts\";\nimport { issueTracker } from \"https://esm.town/v/nbbaier/val-issue-tracker/mod.ts\";\nimport { blobAdmin } from \"https://esm.town/v/nbbaier/scoped-blob-viewer/mod.ts\";\n\nexport default createRouter({\n title: \"My Tools\",\n auth: { users: \"nbbaier\" },\n integrations: [issueTracker({}), blobAdmin({})],\n});\n```\n\nEach integration is served at `//`, listed on the directory page at `/`,\nand shares the host val's scoped SQLite and blob storage. See\n[`INTEGRATIONS.md`](INTEGRATIONS.md) for the registry of known integrations and\ntheir import paths.\n\n### Auth\n\nThe router owns the OAuth gate — one login covers every integration.\n\n| `auth` value | Who gets in |\n| ----------------------------- | -------------------------------------------- |\n| _omitted_ (default) | Any logged-in Val Town account |\n| `{ users: \"alice\" }` | Only `@alice` |\n| `{ users: [\"alice\", \"bob\"] }` | Only `@alice` or `@bob` |\n| `false` | No gate — the router is open, `user` is null |\n\nWhen the gate is on, set an `OAUTH_STATE_ENCRYPTION_KEY` env var (any random\n32-byte hex string) or login will fail. The login page warns you if it's\nmissing, and the directory page badges any integration whose `requiredEnv` vars\nare unset.\n\n### Reserved paths\n\nThe router keeps `/` (the directory page) and `/auth/*` (the OAuth routes) for\nitself. Integration slugs are validated against these — see [reserved\nslugs](#reserved-slugs).\n\n---\n\n## Writing an integration\n\nAn integration is metadata plus a fetch handler. You ship an\n`(options) => Integration` **factory**; users register the factory's return\nvalue with a router, or mount it standalone as a val's HTTP export. The same\nvalue serves both modes.\n\nHere is the entire worked example ([`example/hello.ts`](example/hello.ts)) —\ncopy it to start your own. Every line is contract surface, not app logic. A\nline-by-line walkthrough lives in [`example/README.md`](example/README.md).\n\n```ts\nimport { defineIntegration } from \"https://esm.town/v/nbbaier/integrations/mod.ts\";\n\nexport interface HelloWorldOptions {\n subject?: string;\n}\n\nexport function helloWorld(options: HelloWorldOptions = {}) {\n const subject = options.subject ?? \"world\";\n return defineIntegration({\n name: \"Hello World\",\n slug: \"hello\",\n description: \"The smallest possible integration — the worked example.\",\n requiredEnv: [\"HELLO_GREETING\"],\n handler: (req, ctx) => {\n const greeting = Deno.env.get(\"HELLO_GREETING\") ?? \"Hello\";\n const who = ctx?.user ? `@${ctx.user}` : subject;\n const body =\n new URL(req.url).pathname === \"/about\"\n ? `

A toy integration.

back

`\n : `

${greeting}, ${who}!

about

`;\n return new Response(`${body}`, {\n headers: { \"Content-Type\": \"text/html; charset=utf-8\" },\n });\n },\n });\n}\n\nexport default helloWorld();\n```\n\nThe comments those lines used to carry now live in the walkthrough; the prose\nbelow covers the same ground for the contract as a whole.\n\n### The `Integration` contract\n\n`defineIntegration` takes one object:\n\n| Field | Type | Required | Meaning |\n| ------------- | -------------------- | -------- | ----------------------------------------------------------- |\n| `name` | `string` | yes | Human-readable label shown on the directory page. |\n| `slug` | `string` | yes | URL-safe id; the integration is served at `//`. |\n| `description` | `string` | no | Shown under the name on the directory page. |\n| `requiredEnv` | `string[]` | no | Env vars this integration reads; unset ones badge the page. |\n| `handler` | `IntegrationHandler` | yes | The fetch handler: `(req, ctx?) => Response \\| Promise<…>`. |\n\n### The factory convention\n\nExport a function, not a bare `Integration`. Configuration goes in the closure,\nnever on the object — that keeps the `Integration` type free of app-specific\noptions and lets users write `myFactory({ ...config })`. If your integration\nneeds no config, take an options bag anyway (`options = {}`) so the calling\nconvention stays uniform.\n\n### The handler and its context\n\n```ts\ntype IntegrationHandler = (\n req: Request,\n ctx?: IntegrationContext,\n) => Response | Promise;\n\ninterface IntegrationContext {\n user: string | null; // Val Town username from the router's OAuth; null if the gate is off.\n prefix: string; // Mount prefix, e.g. \"/hello\".\n}\n```\n\n`ctx` is **present when routed, absent when standalone** — its absence is how\nyour handler knows no router is in front of it. `ctx?.user` is the dual-mode\nidiom. If you use Hono, `ctx` arrives as `c.env`.\n\n### Dual-mode: one factory, two mounts\n\n`defineIntegration` returns a **callable integration** — the `Integration`\nobject made directly callable as an HTTP handler\n(`CallableIntegration = Integration & IntegrationHandler`). So the same return\nvalue works both ways with no branching:\n\n```ts\nexport default helloWorld(); // standalone HTTP val\ncreateRouter({ integrations: [helloWorld()] }); // routed\n```\n\nThe platform calls the standalone export with no `ctx`, which is exactly the\n\"no router\" signal the contract already defines. See\n[ADR 0003](docs/adr/0003-callable-integrations.md).\n\n### Prefix rules: keep links relative\n\nThe router mounts you under `//`. To survive that, follow one rule:\n\n- **Use relative URLs** (`href=\"about\"`, `href=\"./\"`) — never root-absolute\n (`href=\"/about\"`). Relative links resolve inside the mount prefix when routed\n and at the root when standalone, with zero branching. The router\n canonicalizes `/` → `//` so relative resolution always has a\n trailing-slash base.\n- **Redirects are handled for you.** The router rewrites root-absolute\n `Location` headers, prepending your prefix — so the redirect-after-POST idiom\n `c.redirect(\"/?ok=1\")` becomes `//?ok=1` automatically. HTML bodies are\n never rewritten; that stays your job (relative links). See\n [ADR 0002](docs/adr/0002-location-header-rewriting.md).\n- **To reach outside your mount** (the router root, a sibling), use `ctx.prefix`\n or a full absolute URL — a bare `/...` won't get there by design.\n\nTwo real integrations (`val-issue-tracker`, `scoped-blob-viewer`) migrated onto\nthis with zero contract fights. If a rule ever needs a wall of caveats in your\napp, that's a bug in the contract — open an issue rather than working around it.\n\n### `requiredEnv`\n\nList the env vars you read. The router checks them at request time and badges\nthe directory page for any that are unset — it never blocks the integration.\nRead the vars with `Deno.env.get()` **at request time**, never at import time\n(import-time reads run before the val's env is available and break standalone\nmounting).\n\n### Reserved slugs\n\n`createRouter` and `defineIntegration` reject invalid or reserved slugs by\nthrowing at construction (fail fast, not at request time):\n\n- Must match `^[a-z0-9-]+$`.\n- `auth` is reserved (std/oauth owns `/auth/*`).\n- The `_`-prefixed namespace is reserved forever for router-owned surface.\n- Slugs must be unique within a router.\n\n### Permission composition\n\nThe router **authenticates**; your integration **authorizes**. Read `ctx.user`\nand decide what that user may do:\n\n- `ctx.user` is a username when the router's gate let them in.\n- `ctx.user` is `null` when the router is ungated (`auth: false`) — meaning no\n login exists at all, so don't redirect to one; degrade to a read-only or\n public view.\n- If your integration has its own credential check (e.g. a bearer-token API),\n it stacks _behind_ the router's gate when the router has one. A headless\n client that can't hold an OAuth session should target your **standalone** or\n an ungated mount. (v1 accepts this stacking deliberately — see the map's\n out-of-scope notes.)\n\n### Testing without OAuth\n\n`createRouteHandler` is the public test seam: the router core with user lookup\ninjected, so you can exercise routed mode without a real session.\n\n```ts\nimport { createRouteHandler } from \"https://esm.town/v/nbbaier/integrations/mod.ts\";\n\nconst handler = createRouteHandler(\n { integrations: [helloWorld()], auth: false },\n () => Promise.resolve(\"alice\"), // inject the \"logged-in\" user\n);\nconst res = await handler(new Request(\"https://example.com/hello/about\"));\n```\n\nYou can also call your integration's `.handler(req, ctx)` directly with a\nhand-built `ctx` to test dispatch in isolation. See\n[`example/hello_test.ts`](example/hello_test.ts).\n\n---\n\n## API reference\n\nAll exports come from `mod.ts`:\n\n| Export | Kind | Purpose |\n| --------------------- | -------- | ------------------------------------------------------------- |\n| `createRouter` | function | Build the HTTP handler that mounts integrations (users). |\n| `defineIntegration` | function | Wrap an `Integration` into a dual-mode callable (authors). |\n| `createRouteHandler` | function | OAuth-free router core with injected user lookup (test seam). |\n| `Integration` | type | The contract object: `name`, `slug`, `handler`, … |\n| `CallableIntegration` | type | `Integration & IntegrationHandler` — the dual-mode value. |\n| `IntegrationHandler` | type | `(req, ctx?) => Response \\| Promise`. |\n| `IntegrationContext` | type | `{ user: string \\| null; prefix: string }`. |\n| `RouterOptions` | type | Argument to `createRouter`. |\n| `RouterAuthOptions` | type | The `auth` field: `{ users?: string \\| string[] } \\| false`. |\n\n## Publishing and versioning\n\nImport the contract from `mod.ts` **unpinned** for the latest v1:\n\n```ts\nimport { createRouter } from \"https://esm.town/v/nbbaier/integrations/mod.ts\";\n```\n\nPin a version with Val Town's `?v=` escape hatch if you need to\n(`…/mod.ts?v=42`). `mod.ts` is the stable v1 entrypoint — breaking changes ship\nas a **new entrypoint**, never on `mod.ts`. Post-v1, `main` is the release\nchannel: changes land through a branch with a green `deno task check`.\n\n## Development\n\n```sh\ndeno task check # fmt + lint + typecheck + test\n```\n\nBiome (tab-indented) is the canonical formatter. Tests live alongside the code\n(`router_test.ts`, `example/hello_test.ts`).\n",[190],"8193b56a-42d4-49ed-8749-149f58354be4","INTEGRATIONS.md","b16cb92a-7d51-11f1-b759-1607ee4eb77e",132,["D",1783792711200],"# Integration registry\n\nKnown integrations built on the [`integrations`](README.md) contract. Each is a\ncallable `(options) => Integration` factory — import it and register it with\n`createRouter`, or mount it standalone as a val's HTTP export.\n\n| Integration | Factory | Slug | Import |\n| ------------------- | -------------- | -------- | ------------------------------------------------------ |\n| Issue tracker | `issueTracker` | `issues` | `https://esm.town/v/nbbaier/val-issue-tracker/mod.ts` |\n| Blob viewer | `blobAdmin` | `blobs` | `https://esm.town/v/nbbaier/scoped-blob-viewer/mod.ts` |\n| Hello World example | `helloWorld` | `hello` | `./example/hello.ts` (in this repo) |\n\n```ts\nimport { createRouter } from \"https://esm.town/v/nbbaier/integrations/mod.ts\";\nimport { issueTracker } from \"https://esm.town/v/nbbaier/val-issue-tracker/mod.ts\";\nimport { blobAdmin } from \"https://esm.town/v/nbbaier/scoped-blob-viewer/mod.ts\";\n\nexport default createRouter({\n auth: { users: \"nbbaier\" },\n integrations: [issueTracker({}), blobAdmin({})],\n});\n```\n\n## Integrations\n\n### Issue tracker — `issueTracker`\n\nA lightweight GitHub-flavoured issue tracker for Val Town's scoped SQLite:\nissues, labels, assignees, blocking edges, comments, and a bearer-authenticated\nJSON API. Role model (viewer / contributor / maintainer) resolves from\n`ctx.user`.\n\n- **Repo:** [`val-issue-tracker`](https://val.town/x/nbbaier/val-issue-tracker)\n- **Env:** `OAUTH_STATE_ENCRYPTION_KEY` (when auth is on); `ISSUE_TRACKER_API_KEY`\n for JSON writes.\n\n### Blob viewer — `blobAdmin`\n\nAn admin panel for val-scoped blob storage — list, view, edit (text/JSON),\npreview images, upload, download, rename, copy, delete. Authorizes an `owner`\nfrom `ctx.user` (all-or-nothing).\n\n- **Repo:** [`scoped-blob-viewer`](https://val.town/x/nbbaier/scoped-blob-viewer)\n- **Env:** `OAUTH_STATE_ENCRYPTION_KEY` (when auth is on).\n\n### Hello World example — `helloWorld`\n\nThe smallest honest integration — the copyable worked example that ships in this\nrepo. Not a published val; copy [`example/hello.ts`](example/hello.ts) to start\nyour own. See [`example/README.md`](example/README.md) for the walkthrough.\n\n- **Env:** `HELLO_GREETING` (optional; demonstrates `requiredEnv`).\n\n## Adding an integration\n\nBuild an `(options) => Integration` factory with `defineIntegration` (see\n[Writing an integration](README.md#writing-an-integration)), publish it as a\nval, then add a row to the table above and a short entry under **Integrations**.\n",[197],"0738d1b7-4e44-4db2-a469-1e3d1c1feb28","CONTEXT.md","2744ac76-7cb1-11f1-b0e8-1607ee4eb77e",134,["D",1783793918053],"# Integrations\n\nThe contract and router for mounting reusable web apps (\"integrations\") into a\nVal Town val, so one val exposes many project-level tools through a single URL.\n\n## The pattern\n\nAn integration is a **mountable sub-app over a Val Town scoped resource** — a\nself-contained web app (UI, routes, and its own authorization) wrapped around\none val-scoped thing (a SQLite-backed domain, the blob store). The contract is\nthis shape extracted from `val-issue-tracker` and `scoped-blob-viewer`, which\nalready shared it.\n\nThe defining twist is Val Town scoping: scoped SQLite/blob bind to whichever\nval's runtime is **executing** the code, so an integration operates on its\n**host val's** data and identity just by being imported — no tokens, no config.\nFrom that follow its three properties:\n\n- **Host-scoped, not self-scoped** — it acts on the executing val's storage, so\n importing it points it at that val's data.\n- **Portable / dual-mode** — relative-only links and a callable contract let the\n same value run standalone (a val's HTTP export) or routed (mounted at\n `/slug/`).\n- **Composable** — it keeps authorization but lifts authentication to the host\n or router, so many stack behind one origin and one login.\n\nAnalogy: Rails engines or Hono/Express sub-apps mounted at a prefix, but\nhost-scoped — mounting inherits the host's data and identity for free.\n\n## Language\n\n**Integration**:\nA self-contained web app — metadata plus a fetch handler — that operates on the\nhost val's scoped storage and is registered with a router.\n_Avoid_: plugin, addon, module, app\n\n**Callable integration**:\nWhat `defineIntegration` returns — the Integration object made directly\ncallable as an HTTP handler, so one factory return value serves standalone\nmode (`export default myFactory({...})`) and routed mode alike.\n_Avoid_: hybrid, function-object\n\n**Integration factory**:\nThe `(options) => Integration` function an integration author exports; all\nconfiguration lives in its closure, never in the Integration itself.\n_Avoid_: constructor, builder, plugin function\n\n**Router**:\nThe HTTP handler `createRouter` produces. It owns auth, serves the directory\npage, and dispatches requests to registered integrations.\n_Avoid_: meta-router, gateway, hub\n\n**Host val**:\nThe val in which a router (or a standalone integration) is mounted. Its scoped\nSQLite and blob storage are what integrations read and write.\n_Avoid_: parent val, project, consumer\n\n**Integration context**:\nThe object the router passes as a handler's second argument (`user`,\n`prefix`). Absent in standalone mode — its absence is how an integration\nknows no router is present. Surfaces as `c.env` in Hono-based integrations.\n_Avoid_: env, request context, session\n\n**Reserved slugs**:\nSlugs `createRouter` rejects because the router owns those paths: `auth`\n(std/oauth's fixed routes) and the `_`-prefixed namespace (all future\nrouter-owned surface).\n\n**Slug**:\nAn integration's short, unique, URL-safe identifier within one router; it\ndetermines where the integration is served.\n_Avoid_: id, key, name (name is the human-readable label)\n\n**Directory page**:\nThe router's page at `/`: the list of registered integrations with links and\nmissing-`requiredEnv` warnings.\n_Avoid_: dashboard (the richer, out-of-scope idea), homepage, index\n\n**Reserved paths**:\nPaths the router keeps for itself (`/` and `/auth/*`); slugs must not collide\nwith them.\n\n**Standalone mode**:\nMounting an integration's handler directly as a val's HTTP export, no router\ninvolved. Every integration must keep working this way.\n_Avoid_: legacy mode, direct mode\n\n**Routed mode**:\nMounting an integration by registering it with a router via its factory.\n_Avoid_: managed mode, hosted mode\n",[204],"a9db1ec5-6e06-4624-be74-8baaa2d47729",".vtignore","52638df0-7c9d-11f1-b73f-1607ee4eb77e",4,["D",1783715055884],".git\n.vscode\n.cursor\n.claude\n.DS_Store\nnode_modules\nvendor",[211],"963ec3f1-4692-4fbf-bfed-f54fe2d276f3","example","efe83c56-7d47-11f1-9667-1607ee4eb77e",95,["D",1783788334625],"directory",[218],"a29dc277-7931-4cf4-b228-0524d69fcc23","docs","c22f6a9e-7cb3-11f1-a763-1607ee4eb77e",31,["D",1783724692393],[225],"pulls","branches","forks","envVars",{"_237":146,"_239":60},"connections",{"_237":60,"_238":60},"count","unfilledCount","emptyCount",{"_42":224,"_32":225,"_30":226,"_142":-5,"_40":41,"_39":227,"_144":122,"_37":475,"_13":60,"_34":222,"_35":-5,"_24":25,"_149":-5,"_275":476,"_27":477},{"_42":470,"_32":453,"_30":447,"_142":226,"_40":41,"_39":471,"_144":122,"_37":472,"_13":60,"_34":222,"_35":-5,"_24":25,"_149":-5,"_275":473,"_27":474},{"_42":462,"_32":463,"_30":464,"_142":447,"_40":41,"_39":465,"_144":25,"_37":466,"_13":60,"_34":20,"_35":467,"_24":25,"_149":-5,"_275":468,"_27":469},{"_42":454,"_32":455,"_30":456,"_142":447,"_40":41,"_39":457,"_144":25,"_37":458,"_13":156,"_34":20,"_35":459,"_24":25,"_149":-5,"_275":460,"_27":461},{"_42":444,"_32":445,"_30":446,"_142":447,"_40":41,"_39":448,"_144":25,"_37":449,"_13":60,"_34":20,"_35":450,"_24":25,"_149":-5,"_275":451,"_27":452},{"_42":439,"_32":438,"_30":434,"_142":226,"_40":41,"_39":440,"_144":122,"_37":441,"_13":60,"_34":222,"_35":-5,"_24":25,"_149":-5,"_275":442,"_27":443},{"_42":433,"_32":33,"_30":31,"_142":434,"_40":41,"_39":14,"_144":25,"_37":435,"_13":156,"_34":20,"_35":36,"_24":25,"_149":-5,"_275":436,"_27":437},{"_42":428,"_32":341,"_30":423,"_142":226,"_40":41,"_39":429,"_144":122,"_37":430,"_13":60,"_34":222,"_35":-5,"_24":25,"_149":-5,"_275":431,"_27":432},{"_42":422,"_32":342,"_30":334,"_142":423,"_40":41,"_39":424,"_144":122,"_37":425,"_13":60,"_34":222,"_35":-5,"_24":25,"_149":-5,"_275":426,"_27":427},{"_42":417,"_32":359,"_30":353,"_142":334,"_40":41,"_39":418,"_144":122,"_37":419,"_13":60,"_34":222,"_35":-5,"_24":25,"_149":-5,"_275":420,"_27":421},{"_42":409,"_32":410,"_30":411,"_142":353,"_40":41,"_39":412,"_144":25,"_37":413,"_13":60,"_34":20,"_35":414,"_24":25,"_149":-5,"_275":415,"_27":416},{"_42":401,"_32":402,"_30":403,"_142":353,"_40":41,"_39":404,"_144":25,"_37":405,"_13":156,"_34":20,"_35":406,"_24":25,"_149":-5,"_275":407,"_27":408},{"_42":392,"_32":393,"_30":394,"_142":353,"_40":41,"_39":395,"_144":25,"_37":396,"_13":397,"_34":20,"_35":398,"_24":25,"_149":-5,"_275":399,"_27":400},{"_42":384,"_32":385,"_30":386,"_142":353,"_40":41,"_39":387,"_144":25,"_37":388,"_13":60,"_34":20,"_35":389,"_24":25,"_149":-5,"_275":390,"_27":391},{"_42":376,"_32":377,"_30":378,"_142":353,"_40":41,"_39":379,"_144":25,"_37":380,"_13":180,"_34":20,"_35":381,"_24":25,"_149":-5,"_275":382,"_27":383},{"_42":368,"_32":369,"_30":370,"_142":353,"_40":41,"_39":371,"_144":25,"_37":372,"_13":213,"_34":20,"_35":373,"_24":25,"_149":-5,"_275":374,"_27":375},{"_42":360,"_32":361,"_30":362,"_142":353,"_40":41,"_39":363,"_144":25,"_37":364,"_13":213,"_34":20,"_35":365,"_24":25,"_149":-5,"_275":366,"_27":367},{"_42":350,"_32":351,"_30":352,"_142":353,"_40":41,"_39":354,"_144":25,"_37":355,"_13":156,"_34":20,"_35":356,"_24":25,"_149":-5,"_275":357,"_27":358},{"_42":343,"_32":190,"_30":344,"_142":334,"_40":41,"_39":345,"_144":25,"_37":346,"_13":60,"_34":20,"_35":347,"_24":25,"_149":-5,"_275":348,"_27":349},{"_42":331,"_32":332,"_30":333,"_142":334,"_40":41,"_39":335,"_144":25,"_37":336,"_13":337,"_34":20,"_35":338,"_24":25,"_149":-5,"_275":339,"_27":340},{"_42":217,"_32":218,"_30":219,"_142":-5,"_40":41,"_39":220,"_144":122,"_37":328,"_13":60,"_34":222,"_35":-5,"_24":25,"_149":-5,"_275":329,"_27":330},{"_42":321,"_32":190,"_30":322,"_142":219,"_40":41,"_39":323,"_144":122,"_37":324,"_13":146,"_34":20,"_35":325,"_24":25,"_149":-5,"_275":326,"_27":327},{"_42":313,"_32":314,"_30":315,"_142":219,"_40":41,"_39":316,"_144":25,"_37":317,"_13":146,"_34":147,"_35":318,"_24":25,"_149":-5,"_275":319,"_27":320},{"_42":305,"_32":306,"_30":307,"_142":219,"_40":41,"_39":308,"_144":25,"_37":309,"_13":60,"_34":147,"_35":310,"_24":25,"_149":-5,"_275":311,"_27":312},{"_42":210,"_32":211,"_30":212,"_142":-5,"_40":41,"_39":213,"_144":122,"_37":302,"_13":60,"_34":20,"_35":215,"_24":25,"_149":-5,"_275":303,"_27":304},{"_42":203,"_32":204,"_30":205,"_142":-5,"_40":41,"_39":206,"_144":25,"_37":299,"_13":180,"_34":20,"_35":208,"_24":25,"_149":-5,"_275":300,"_27":301},{"_42":196,"_32":197,"_30":198,"_142":-5,"_40":41,"_39":199,"_144":25,"_37":296,"_13":180,"_34":20,"_35":201,"_24":25,"_149":-5,"_275":297,"_27":298},{"_42":189,"_32":190,"_30":191,"_142":-5,"_40":41,"_39":192,"_144":25,"_37":293,"_13":156,"_34":20,"_35":194,"_24":25,"_149":-5,"_275":294,"_27":295},{"_42":183,"_32":184,"_30":185,"_142":-5,"_40":41,"_39":156,"_144":25,"_37":290,"_13":60,"_34":20,"_35":187,"_24":25,"_149":-5,"_275":291,"_27":292},{"_42":175,"_32":176,"_30":177,"_142":-5,"_40":41,"_39":178,"_144":25,"_37":287,"_13":180,"_34":20,"_35":181,"_24":25,"_149":-5,"_275":288,"_27":289},{"_42":166,"_32":167,"_30":168,"_142":-5,"_40":41,"_39":169,"_144":25,"_37":284,"_13":171,"_34":172,"_35":173,"_24":25,"_149":-5,"_275":285,"_27":286},{"_42":159,"_32":160,"_30":161,"_142":-5,"_40":41,"_39":162,"_144":25,"_37":281,"_13":156,"_34":147,"_35":164,"_24":25,"_149":-5,"_275":282,"_27":283},{"_42":151,"_32":152,"_30":153,"_142":-5,"_40":41,"_39":154,"_144":25,"_37":278,"_13":156,"_34":147,"_35":157,"_24":25,"_149":-5,"_275":279,"_27":280},{"_42":139,"_32":140,"_30":141,"_142":-5,"_40":41,"_39":143,"_144":25,"_37":274,"_13":146,"_34":147,"_35":148,"_24":25,"_149":-5,"_275":276,"_27":277},["D",1783785020744],"children",[],[140],["D",1783785020715],[],[152],["D",1783785117512],[],[160],["D",1783791740998],[],[167],["D",1783788334915],[],[176],["D",1783715055805],[],[184],["D",1783793917943],[],[190],["D",1783792711200],[],[197],["D",1783793918053],[],[204],["D",1783715055884],[],[211],"a9cb612e-1a70-4e8f-a7c6-6ba803292c96","hello_test.ts","f0100e98-7d47-11f1-af4f-1607ee4eb77e",98,["D",1783788334758],"import { assert, assertEquals } from \"@std/assert\";\nimport { createRouteHandler } from \"../router.ts\";\nimport helloStandalone, { helloWorld } from \"./hello.ts\";\n\nDeno.test(\"hello-world greets the routed user with relative links\", async () => {\n\tconst handler = createRouteHandler(\n\t\t{ integrations: [helloWorld()], auth: false },\n\t\t() => Promise.resolve(\"nbbaier\"),\n\t);\n\t// auth: false leaves ctx.user null, so inject the user via the test seam's\n\t// dispatch instead: call the integration the way the router does.\n\tconst res = await helloWorld().handler(new Request(\"https://example.com/\"), {\n\t\tuser: \"nbbaier\",\n\t\tprefix: \"/hello\",\n\t});\n\tconst body = await res.text();\n\tassert(body.includes(\"@nbbaier\"));\n\tassert(body.includes(`href=\"about\"`));\n\tassert(\n\t\t!body.includes(`href=\"/`),\n\t\t\"links must be relative, not root-absolute\",\n\t);\n\n\tconst routed = await handler(new Request(\"https://example.com/hello/about\"));\n\tassertEquals(routed.status, 200);\n\tassert((await routed.text()).includes(`href=\"./\"`));\n});\n\nDeno.test(\"hello-world works standalone with the subject fallback\", async () => {\n\tconst res = await helloStandalone(new Request(\"https://example.com/\"));\n\tassertEquals(res.status, 200);\n\tassert((await res.text()).includes(\"world\"));\n\n\tconst custom = await helloWorld({ subject: \"Val Town\" }).handler(\n\t\tnew Request(\"https://example.com/\"),\n\t);\n\tassert((await custom.text()).includes(\"Val Town\"));\n});\n",[],[218,306],"e8ff1c5e-61fc-459e-9069-7093f357ede7","hello.ts","f004bfac-7d47-11f1-9667-1607ee4eb77e",108,["D",1783791741170],"// The worked example. See ./README.md for a walkthrough; copy this file to\n// start your own integration.\nimport { defineIntegration } from \"../mod.ts\";\n\nexport interface HelloWorldOptions {\n\tsubject?: string;\n}\n\nexport function helloWorld(options: HelloWorldOptions = {}) {\n\tconst subject = options.subject ?? \"world\";\n\treturn defineIntegration({\n\t\tname: \"Hello World\",\n\t\tslug: \"hello\",\n\t\tdescription: \"The smallest possible integration — the worked example.\",\n\t\trequiredEnv: [\"HELLO_GREETING\"],\n\t\thandler: (req, ctx) => {\n\t\t\tconst greeting = Deno.env.get(\"HELLO_GREETING\") ?? \"Hello\";\n\t\t\tconst who = ctx?.user ? `@${ctx.user}` : subject;\n\t\t\tconst body =\n\t\t\t\tnew URL(req.url).pathname === \"/about\"\n\t\t\t\t\t? `

A toy integration.

back

`\n\t\t\t\t\t: `

${greeting}, ${who}!

about

`;\n\t\t\treturn new Response(`${body}`, {\n\t\t\t\theaders: { \"Content-Type\": \"text/html; charset=utf-8\" },\n\t\t\t});\n\t\t},\n\t});\n}\n\nexport default helloWorld();\n",[],[218,314],"ea1eb4f0-a41d-4a0b-83fd-89d05b2bc036","de3d453e-7d4f-11f1-a875-1607ee4eb77e",131,["D",1783792711187],"# The worked example\n\n[`hello.ts`](hello.ts) is the smallest honest integration — every line is\ncontract surface, not app logic. Copy it to start your own, and read this file\nalongside it. For the full contract, see the [top-level README](../README.md).\n\n## Walkthrough\n\n**The factory.** Authors export an `(options) => Integration` factory, not a\nbare `Integration`:\n\n```ts\nexport function helloWorld(options: HelloWorldOptions = {}) {\n```\n\nAll configuration lives in the closure (`subject` here), never on the\n`Integration` object. Take an options bag even when you need no config\n(`options = {}`) so the calling convention stays uniform across integrations.\n\n**The contract object.** `defineIntegration` takes the metadata plus a handler:\n\n```ts\nreturn defineIntegration({\n\tname: \"Hello World\",\n\tslug: \"hello\",\n\tdescription: \"…\",\n\trequiredEnv: [\"HELLO_GREETING\"],\n\thandler: (req, ctx) => { … },\n});\n```\n\n- `slug` is where the router mounts you (`/hello/`). It must match\n `^[a-z0-9-]+$` and avoid the reserved slugs; `defineIntegration` throws at\n construction if it doesn't.\n- `requiredEnv` lists the env vars you read. Unset ones badge the router's\n directory page — they never block the integration.\n\n**Read env at request time.**\n\n```ts\nconst greeting = Deno.env.get(\"HELLO_GREETING\") ?? \"Hello\";\n```\n\nRead env vars inside the handler, never at import time. Import-time reads run\nbefore the val's environment is available and break standalone mounting.\n\n**The dual-mode idiom.**\n\n```ts\nconst who = ctx?.user ? `@${ctx.user}` : subject;\n```\n\n`ctx` is present when routed, absent when standalone — its absence is how the\nhandler knows no router is in front of it. `ctx?.user` is the router-provided\nVal Town username; fall back to your own default when it's missing.\n\n**Relative links only.**\n\n```ts\n`about`; // not href=\"/about\"\n```\n\nRelative URLs resolve inside the mount prefix when routed and at the root when\nstandalone, with no branching. Root-absolute paths (`/about`) break under a\nmount — see the top-level README's prefix rules and\n[ADR 0002](../docs/adr/0002-location-header-rewriting.md).\n\n**Standalone export.**\n\n```ts\nexport default helloWorld();\n```\n\nBecause `defineIntegration` returns a _callable_ integration, the same value is\nboth an `Integration` (for `createRouter`) and an HTTP handler (as a val's\ndefault export). One factory return value, two mounting modes — see\n[ADR 0003](../docs/adr/0003-callable-integrations.md).\n\n## Testing\n\n[`hello_test.ts`](hello_test.ts) exercises both modes:\n\n- **Routed** — via `createRouteHandler`, the OAuth-free test seam, with a user\n injected. It asserts the routed user is greeted and that links stay relative.\n- **Standalone** — call the default export (and the factory with a custom\n `subject`) directly, with no `ctx`, and check the fallback subject.\n",[],[218,190],["D",1783788334625],[261,262,263],[218],"56cb78b9-88f5-4502-b5de-273be423cf19","map.md","273b54e6-7cb1-11f1-9d45-1607ee4eb77e","b0f10802-7d51-11f1-bd58-1607ee4eb77e",114,["D",1783792524257],10,"---\ntitle: Integrations v1 — contract + meta-router for Val Town project integrations\nlabels: [wayfinder:map]\nstatus: closed\n---\n\n## Destination\n\nA working v1 of the `integrations` val: a published `Integration` contract\n(`Integration` type, `defineIntegration`, `createRouter`) with\n`val-issue-tracker` and `scoped-blob-viewer` fully migrated onto it, a toy\nhello-world integration, and README contract docs for third-party authors.\n\n## Notes\n\n- **This map carries execution.** The destination is working code, so tickets\n build and migrate, not just decide.\n- Domain: Val Town platform (Deno runtime, scoped SQLite/blob, std/oauth).\n Sessions should consult the `valtown:http-endpoints`, `valtown:oauth`,\n `valtown:sqlite-storage` skills, and use `find_val_town_skills` for anything\n platform-specific.\n- Ubiquitous language lives in `CONTEXT.md` (repo root) — consult it every\n session and maintain it via `/domain-modeling`: challenge drift, sharpen new\n terms inline as they crystallise. ADRs go in `docs/adr/` (created lazily),\n offered only for hard-to-reverse, surprising, real-trade-off decisions.\n- Repos (local working dirs): `~/Code/vt-projects/integrations` (this val,\n currently an empty `main.ts`), `~/Code/vt-projects/val-issue-tracker`,\n `~/Code/vt-projects/scoped-blob-viewer`.\n- Standing preferences from the charter session (2026-07-10):\n - Astro/vite-style composition: authors ship `(options) => Integration`\n factories; users write `createRouter({ integrations: [issueTracker({...})] })`.\n Options live in each factory's closure, never in the `Integration` type.\n - The router owns auth: one OAuth gate, `/auth/*` mounted once, user passed\n down. Design intent — pending runtime verification in the prototype.\n - Router serves a minimal directory page at `/` (name, description, link per\n integration, ⚠️ badge for missing `requiredEnv`). `/` and `/auth/*` are\n reserved paths; slugs validated against them and each other.\n - Both existing integrations migrate fully AND remain standalone-mountable\n (the factory serves both modes).\n - Biome is the canonical formatter (tab-indented), not `deno fmt`.\n- Tracker conventions (local markdown): tickets live in `wayfinder/tickets/`,\n one file each, frontmatter `id`, `title`, `labels`, `status: open|closed`,\n `assignee`, `blocked-by: [ids]`. Claim = set `assignee`. Frontier = open,\n unassigned, all `blocked-by` closed. Resolutions go in a `## Resolution`\n section on the ticket.\n\n## Decisions so far\n\n\n\n- [Prototype the dispatch architecture](tickets/001-prototype-dispatch-architecture.md) —\n in-process prefix mount ([ADR 0001](../../adr/0001-dispatch-architecture.md)):\n one origin, router-owned auth verified, hygiene = \"relative URLs only\" with\n router-enforced trailing-slash canonicalization.\n- [Pin the v1 contract](tickets/002-pin-the-v1-contract.md) — `handler(req, ctx)`\n with ctx-as-Hono-env alignment; router rewrites root-absolute `Location`\n headers ([ADR 0002](../../adr/0002-location-header-rewriting.md)); slugs\n `^[a-z0-9-]+$` with `[\"auth\", /^_/]` reserved, throw at construction; auth\n is a gate (`users` allowlist), not a role system.\n- [Build integrations v1](tickets/003-build-integrations-v1.md) — shipped:\n `mod.ts`/`router.ts` implement the contract with zero deviations, 14 tests\n green, live directory at this val's `main.ts` (login-gated, empty until the\n hello-world integration lands).\n- [Decide the publishing and versioning story](tickets/008-publishing-and-versioning.md) —\n unpinned `esm.town/.../mod.ts` imports + `?v=` escape hatch; breaking\n changes ship as a new entrypoint, never on `mod.ts`; post-v1, main is the\n release channel (branch + green `deno task check` to merge); val stays\n public.\n- [Migrate val-issue-tracker onto the contract](tickets/004-migrate-val-issue-tracker.md) —\n dual-mode via callable `defineIntegration`\n ([ADR 0003](../../adr/0003-callable-integrations.md)); `ctx.user` feeds\n the tracker's role model (null → read-only viewer, no login redirects in\n routed mode); bearer-token API gates stack behind a gated router; contract\n additions: `CallableIntegration` type, `createRouteHandler` made public as\n the test seam. Live at the integrations val's `/issues/`; answered the\n permission-model fog.\n- [Migrate scoped-blob-viewer onto the contract](tickets/005-migrate-scoped-blob-viewer.md) —\n dual-mode via callable `defineIntegration`, live at the integrations val's\n `/blobs/`; the prefix-hygiene stress test **passed with zero contract fights**\n (base-threaded links + root-absolute redirects rewritten per ADR 0002, no new\n contract surface). `owner` authorizes from `ctx.user` (all-or-nothing, no\n read-only role); JSX moved to `app.tsx` with `mod.ts` a JSX-free barrel so it\n type-checks locally — a lesson for ticket 7's docs.\n- [Add the hello-world example integration](tickets/006-hello-world-example-integration.md) —\n shipped `example/hello.ts`: a dependency-free `(options) => Integration` factory\n demonstrating the full contract (dual-mode `ctx?.user`, a genuinely-read\n `requiredEnv`, relative-only links), registered live in `main.ts`, tested\n both modes; kept out of `mod.ts` — it's the copyable worked example for\n ticket 7's docs.\n- [Write the third-party author docs](tickets/007-third-party-author-docs.md) —\n shipped `README.md` (both audiences) + `example/README.md` walkthrough; the\n explainability test passed with **zero contract changes**. Review pass also\n unified factory naming (`create*` → `issueTracker`/`blobAdmin`) across all\n three repos and restructured the val-issue-tracker README to the house\n standalone/routed shape. All three repos green. **Destination reached.**\n\n## Not yet specified\n\n\n\n## Out of scope\n\n- **Remixable template val** for integration authors — good idea, explicitly\n deferred past v1; revisit as a fresh effort once the contract has survived\n two real migrations.\n- **Full dashboard** at `/` (health checks, status, per-integration state) —\n v1 ships the minimal directory page only.\n- **Auto-discovery** of sibling HTTP endpoints via `std/utils` `listFiles` —\n only interesting under the redirect architecture; not part of v1 either way.\n- **Registry/marketplace** of third-party integrations.\n- **Machine-credential pass-through** — letting bearer-token clients traverse\n a gated router without an OAuth session (surfaced by the val-issue-tracker\n migration). v1 accepts stacked gates: headless agents target a standalone\n or ungated mount. Revisit only if a real integration can't live with that.\n- **Fine-grained auth for routed integrations** _(leading candidate for the\n next effort)_ — a gated router applies one all-or-nothing login wall at the\n front door, so an integration's own finer auth model is flattened when\n routed. Example: the issue tracker standalone allows anonymous public reads\n (the `viewer` role), but behind a gated router the login wall blocks\n anonymous visitors entirely, so that public-read capability is lost. v1's\n permission model is deliberately all-or-nothing (router authenticates,\n integration authorizes from `ctx.user`); expressing per-integration or\n per-route visibility — a public-read integration, or public-read + gated-write\n routes, on an otherwise-gated router — is a richer model beyond the v1\n destination. Surfaced while writing the ticket-7 docs; revisit as a fresh\n map, not a resumption of this one.\n",[],[225,341,342,332],"wayfinder-archive","integrations-v1","6d194520-4783-4ae0-9616-d39561e89377","b17b36ee-7d51-11f1-bf82-1607ee4eb77e",122,["D",1783792524832],"# Wayfinder archive — Integrations v1\n\nA completed wayfinder effort, archived here as a historical record. The map\nreached its destination on 2026-07-11; all tickets are closed.\n\n- [`map.md`](map.md) — the map: destination, decisions-so-far (the route walked),\n and out-of-scope notes.\n- [`tickets/`](tickets/) — the eight resolved tickets, each with its `## Resolution`.\n\n**Destination reached:** a working v1 of the `integrations` val — the published\n`Integration` contract (`defineIntegration`, `createRouter`), both\n`val-issue-tracker` and `scoped-blob-viewer` migrated onto it, a hello-world\nexample, and README author docs.\n\nThis effort is done; it is not resumed. The next effort (leading candidate:\n**fine-grained auth for routed integrations**, see the map's Out of scope\nsection) is a fresh wayfinder map, started at `wayfinder/` from a clean slate.\n",[],[225,341,342,190],"d3620b53-63dc-46d0-9e4c-4209a06affb3","008-publishing-and-versioning.md","7454ac76-7cb8-11f1-9441-1607ee4eb77e","b1080eee-7d51-11f1-b73f-1607ee4eb77e",118,["D",1783792524500],"---\nid: 8\ntitle: Decide the publishing and versioning story\nlabels: [wayfinder:grilling]\nstatus: closed\nassignee: nbbaier\nblocked-by: []\n---\n\n## Question\n\nGraduated from the map's \"Publishing/versioning story\" fog once the contract\nwas built. What does \"released\" mean for the `integrations` contract?\n\n- **Canonical import URL**: `https://esm.town/v/nbbaier/integrations/mod.ts`\n presumably — confirm, and decide whether docs recommend pinning\n (esm.town `?v=` versions) or tracking latest.\n- **Breaking-change policy for third parties**: the `Integration` type and the\n router's behavioral guarantees (ctx shape, Location rewriting, reserved\n slugs, trailing-slash canonicalization) are the public API. What's the\n compatibility promise, and where is it stated? (The `/^_/` reservation\n already encodes one forever-promise.)\n- **Val privacy/discoverability**: does the val need to be public/unlisted for\n third-party imports to resolve?\n\nSmall ticket; the answers feed the README (ticket 7), which must show real\nimport URLs and state the compatibility stance.\n\nHITL: grill briefly (/grilling).\n\n## Resolution\n\nDecided 2026-07-10 by grilling. Four parts:\n\n- **Canonical import**: `https://esm.town/v/nbbaier/integrations/mod.ts`,\n recommended **unpinned** (platform culture; bugfixes flow), with esm.town's\n `?v=NN` version pinning documented as the stability escape hatch.\n- **Stability promise** (goes in a README \"Stability\" section, ticket 7): the\n public API is the exported types plus the router's behavioral guarantees\n (ctx shape / `c.env` alignment, Location rewriting, trailing-slash\n canonicalization, reserved slugs incl. the forever-`/^_/` namespace).\n Additive changes land on `mod.ts` anytime; **breaking changes never land on\n `mod.ts`** — they ship as a new entrypoint (e.g. `v2/mod.ts`) with old\n semantics preserved.\n- **Branch discipline, post-v1**: unpinned imports track the val's main tip,\n so **main is the release channel and merge = release**. Contract-touching\n work happens on a branch (`vt checkout -b`); merge only with\n `deno task check` green; don't leave `vt watch` running against main while\n editing `router.ts`/`mod.ts`. Non-code files (`wayfinder/`, `docs/`,\n `CONTEXT.md`) are exempt. Layering: `?v=` protects downstream from\n deliberate change, branch discipline from accidental breakage — unpinned-by-\n default is only honest with both.\n- **Privacy**: the val is public (verified via API) and must stay\n public/unlisted for esm.town imports to resolve.\n",[],[225,341,342,359,351],"tickets","6a448add-bc45-4bb7-8977-a2e51168f65b","007-third-party-author-docs.md","272f2194-7cb1-11f1-81a5-1607ee4eb77e",117,["D",1783792524262],"---\nid: 7\ntitle: Write the third-party author docs\nlabels: [wayfinder:task]\nstatus: closed\nassignee: nico\nblocked-by: [4, 5, 8]\n---\n\n## Question\n\nWrite the `integrations` README for the two audiences: users mounting a router\n(`createRouter` quickstart) and authors building integrations (the contract —\n`Integration` fields, the factory convention, prefix rules, what the router\nprovides vs what authors must do, `requiredEnv`, reserved slugs), with the\nhello-world integration as the worked example.\n\nBlocked on both migrations deliberately: the docs are the explainability test\nof a contract that survived two real apps. If a rule needs a wall of caveats\nto document, that's feedback for the contract, not prose to polish — surface\nit rather than shipping it.\n\nSurface added by the ticket-4 migration, to be covered too:\n\n- Callable integrations (ADR 0003): `defineIntegration` returns a value that\n is both an `Integration` and a standalone HTTP handler — the dual-mode\n story for authors.\n- `createRouteHandler` as the public, OAuth-free test seam (mount your\n integration under a real router with an injected user).\n- Permission composition: the router authenticates, the integration\n authorizes from `ctx.user`; `ctx.user: null` means an ungated router (no\n login exists); integration-level token APIs sit behind the router's gate\n when it has one.\n\nAFK draft, HITL review pass.\n\n## Resolution\n\nShipped `README.md` for both audiences — *Mounting integrations* (`createRouter`\nquickstart, the `auth` table, reserved paths) and *Writing an integration* (the\n`Integration` contract, factory convention, handler + `IntegrationContext`,\n`requiredEnv`, reserved slugs), with `example/hello.ts` as the worked example.\nThe ticket-4 surface is all covered: callable dual-mode integrations (ADR 0003),\n`createRouteHandler` as the OAuth-free test seam, and permission composition\n(`ctx.user` null → ungated → don't redirect; token APIs stack behind the gate).\n\n**The explainability test passed** — every contract rule stated in a clean\nparagraph, no wall of caveats, so no contract changes fell out of writing the\ndocs. Two migrations having landed \"zero contract fights\" held up under prose.\n\nRefinements made during the HITL review pass:\n\n- **Naming convention unified** to the `helloWorld` style: `createIssueTracker`\n → `issueTracker`, `createBlobAdmin` → `blobAdmin`, renamed across all three\n repos (closed tickets left as the migration audit record). `*Options` types\n already matched the `HelloWorldOptions` style and were left.\n- **Example docs extracted**: `example/hello.ts` stripped of teaching comments;\n a line-by-line walkthrough moved to new `example/README.md`.\n- **val-issue-tracker README restructured** onto scoped-blob-viewer's\n standalone/routed shape (the house style for integration READMEs).\n\nAll three repos green (`deno task check`): integrations 17 tests, val-issue-tracker\n23, scoped-blob-viewer 5. The two migrated vals were republished so the\nintegrations val's remote imports resolve against the new names.\n\nSurfaced but ruled out of scope: **fine-grained auth for routed integrations**\n(a gated router's all-or-nothing login wall flattens an integration's own finer\nauth model — e.g. the tracker's anonymous public reads vanish behind a gated\nrouter). Beyond v1's settled all-or-nothing gate; filed as the leading candidate\nfor the next effort.\n",[],[225,341,342,359,361],"1690e329-2e8e-4562-a408-fd923f6021c2","006-hello-world-example-integration.md","27198942-7cb1-11f1-bf6f-1607ee4eb77e",116,["D",1783792524281],"---\nid: 6\ntitle: Add the hello-world example integration\nlabels: [wayfinder:task]\nstatus: closed\nassignee: nbbaier\nblocked-by: [3]\n---\n\n## Question\n\nWrite the toy integration (~30 lines) that lives in the `integrations` repo,\ndoubles as the docs' worked example, and demonstrates the whole contract\nsurface honestly: `defineIntegration`, an `(options) => Integration` factory,\nreading the router-provided user, one `requiredEnv` declaration, and\nprefix-correct links per the ticket-2 rules.\n\nMount it in this val's own `main.ts` so the live directory page always shows a\nworking example. Keep it genuinely trivial — its job is to be copied by\nthird-party authors, so every line should be contract, not app.\n\nAFK.\n\n## Resolution\n\nShipped 2026-07-11. [`hello.ts`](../../../../example/hello.ts) — ~40 lines, deployed live.\n\n- **The whole contract surface, honestly:** an `(options) => Integration`\n factory (`helloWorld({ subject? })`, config in the closure), built with\n `defineIntegration`, reading `ctx?.user` via the dual-mode idiom (greets\n `@user` when routed+logged-in, the `subject` option standalone), one\n `requiredEnv: [\"HELLO_GREETING\"]` it genuinely reads at request time\n (falls back to \"Hello\"; unset = the directory's ⚠️ badge, deliberately\n demonstrating the feature), and relative-only links (`about`, `./`) per the\n ticket-2 prefix rules. `export default helloWorld()` at the bottom shows\n standalone mode on the same callable.\n- **Plain `(req, ctx)` handler, no Hono** — the toy stays dependency-free so\n every line is contract; the Hono idiom is val-issue-tracker's job to show.\n- **Registered in `main.ts`** after the issue tracker; pushed via `vt push`\n and verified live (401 login gate serving correctly; directory is\n owner-gated by design).\n- Tests: [`hello_test.ts`](../../../../example/hello_test.ts) — routed greeting + relative\n links, standalone fallback, both modes through the real dispatch. 17/17\n green under `deno task check`.\n- Not exported from `mod.ts`: the example is a copyable file, not contract\n surface. Ticket 7's docs should link/inline it as the worked example.\n",[],[225,341,342,359,369],"45fbb922-76e0-45ca-8495-322306c43e62","005-migrate-scoped-blob-viewer.md","2721832c-7cb1-11f1-adf5-1607ee4eb77e",115,["D",1783792524281],"---\nid: 5\ntitle: Migrate scoped-blob-viewer onto the contract\nlabels: [wayfinder:task]\nstatus: closed\nassignee: nbbaier\nblocked-by: [3]\n---\n\n## Question\n\nMigrate `~/Code/vt-projects/scoped-blob-viewer` to be a conforming integration\nwhile keeping standalone mounting working (`export default\ncreateBlobAdmin({...})` stays valid).\n\nThis is the deliberate stress test for prefix hygiene: `mod.ts` is one file of\nlink-heavy server-rendered HTML — absolute `href`s (`/view?key=...`,\n`/raw?key=...`), form `action`s (`/create`, `/delete`, `/rename`), and\nredirect targets (`c.redirect(\"/?ok=...\")`) all break under a mount prefix\nunless the ticket-2 rules handle them. If the migration fights the contract,\nthat's signal, not something to hack around — feed it back.\n\nAlso: it currently wraps `oauthMiddleware` itself with an `owner` allowlist;\nthat gate moves to the router, and its `LoginPage` setup-check for\n`OAUTH_STATE_ENCRYPTION_KEY` becomes a `requiredEnv` declaration.\n\nAFK.\n\n## Resolution\n\nMigrated 2026-07-11; both modes live and green, and the stress test passed —\n**the prefix-hygiene rules held without a single contract fight.**\n\n- `createBlobAdmin` now returns a callable Integration built with\n `defineIntegration` from the published contract\n (`https://esm.town/v/nbbaier/integrations/mod.ts`). `export default\n createBlobAdmin({ owner: \"nbbaier\" })` stays a valid standalone HTTP export,\n and the same value registers with `createRouter`. Standalone wraps this val's\n own `oauthMiddleware`; routed mode never does\n (`handler: (req, ctx) => ctx ? app.fetch(req, ctx) : standalone(req)`).\n- **Prefix hygiene (the point of the ticket):** every link/form action in the\n link-heavy HTML threads `base = ctx.prefix ?? \"\"` (via a `base` Hono var set\n in the auth middleware); redirects stay root-absolute (`/?ok=`, `/view?...`)\n and get router-rewritten per ADR 0002; `/auth/*` links stay origin-level in\n both modes. `blob.*` calls unchanged — scoped storage needs no prefix\n handling. **No contract additions were needed** — unlike the tracker\n migration, this one consumed the contract exactly as ticket 4 left it\n (callable integrations, `createRouteHandler` seam, Location rewriting).\n- **Permission composition:** `owner` stays this panel's own authorization\n layer, now checked against `ctx.user` when routed and the OAuth session when\n standalone. Unlike the tracker there is no read-only role — an admin panel is\n all-or-nothing — so a non-owner (including the `null` user of an ungated\n router, which can't satisfy an allowlist) gets 403, not a downgraded view.\n `auth: false` is fully open in both modes, as before. `OAUTH_STATE_ENCRYPTION_KEY`\n is declared as `requiredEnv` so a router's directory badges it when unset.\n- **File layout — reusable lesson for the docs ticket (7):** JSX in a `.ts`\n file runs on Val Town but can't be type-checked by plain `deno check`. So,\n mirroring the tracker, the JSX moved to `app.tsx` and `mod.ts` became a\n JSX-free re-export barrel — keeping the stable\n `.../scoped-blob-viewer/mod.ts` import path AND making the module locally\n checkable. Authors shipping JSX integrations should do the same.\n- Added a `deno task check` (fmt/lint/typecheck/test) the val never had, plus\n `mod_test.ts`: 5 tests via an injected in-memory `BlobStore` seam covering\n contract metadata, routed prefix-threading, the owner gate (owner/non-owner/\n null), root-absolute redirects, and end-to-end composition under the real\n router (`createRouteHandler`). All green in both repos.\n- Live: pushed both vals. `createBlobAdmin({})` registered in the integrations\n val's `main.ts`, mounted at `/blobs/` (401-gated as configured — the router\n serving 401 rather than 500 confirms it accepted the value as an Integration\n at construction). Standalone blob-viewer val serves its own data unchanged.\n- Same gotcha as ticket 4: the viewer imports the contract unpinned and Deno\n caches remote modules — after pushing scoped-blob-viewer, run `deno cache\n --reload=https://esm.town/v/nbbaier/scoped-blob-viewer/mod.ts` in the\n integrations val before its `deno task check`.\n",[],[225,341,342,359,377],"fd8d4653-aa84-4bf2-bb70-0e0a9c128b47","004-migrate-val-issue-tracker.md","04d622d6-7d52-11f1-8ed3-1607ee4eb77e",128,["D",1783792664697],"---\nid: 4\ntitle: Migrate val-issue-tracker onto the contract\nlabels: [wayfinder:task]\nstatus: closed\nassignee: nbbaier\nblocked-by: [3]\n---\n\n## Question\n\nMigrate `~/Code/vt-projects/val-issue-tracker` to be a conforming integration\nwhile keeping standalone mounting working (charter constraint: the factory\nserves both modes — `export default createIssueTracker({...})` stays valid).\n\nKnown hard parts:\n\n- It self-manages OAuth **and** a role model (maintainer/contributor/viewer)\n **and** a bearer-token JSON API under `/api`. Router-owned auth replaces the\n OAuth gate; how the router-provided user feeds the role model, and what\n happens to bearer-token writes behind the router, is the map's\n \"permission-model composition\" fog — resolving this ticket should graduate\n or answer it.\n- Prefix hygiene per the ticket-2 rules if architecture (A) won: absolute\n links/form actions throughout `app.tsx` / `components.tsx` / `ui.tsx`, and\n the `/source` redirect.\n- Its test suite (`deno task check`) must stay green in both modes.\n\nAFK mostly; flag anything that contradicts the contract rather than working\naround it.\n\n## Resolution\n\nMigrated 2026-07-11; both modes live and green.\n\n- `createIssueTracker` now returns a callable Integration built with\n `defineIntegration` from the published contract\n (`https://esm.town/v/nbbaier/integrations/mod.ts`): `export default\n createIssueTracker({})` stays a valid standalone HTTP export, and the same\n value registers with `createRouter`. Standalone wraps the tracker's own\n `oauthMiddleware`; routed mode never does.\n- **Permission composition (answers the map's fog):** the router owns\n authentication; the tracker's maintainer/contributor/viewer model stays its\n own authorization layer, fed by `ctx.user` — maintainer if in the\n `maintainers` set, else `defaultRole`; `ctx.user: null` (ungated router) is\n a read-only viewer with login UI hidden, since no login flow exists there.\n Tracker `auth: false` still means \"everyone is maintainer\" in both modes.\n Routed mode never redirects to `/auth/login` (Location rewriting would turn\n it into a 404 under the prefix) — viewers get a 403 page instead.\n- **Bearer-token `/api`:** unchanged at the integration layer; gates stack.\n Behind a gated router the JSON API additionally requires the router's OAuth\n session, so headless agents target a standalone or ungated mount.\n Machine-credential pass-through ruled out of scope for v1 (map updated).\n- **Prefix hygiene:** every HTML link/form action threads\n `base = ctx.prefix ?? \"\"` (Layout + all pages); redirects stay root-absolute\n and get router-rewritten per ADR 0002; `/auth/*` links stay origin-level\n (correct in both modes); Referer-based redirects pass through as full URLs.\n- **Contract feedback — implemented as additive changes, not workarounds:**\n (1) `defineIntegration` returns a callable Integration\n ([ADR 0003](../../../adr/0003-callable-integrations.md); new\n `CallableIntegration` / `IntegrationHandler` types) — without it the two\n mounting styles needed different factory return values; (2)\n `createRouteHandler` promoted to `mod.ts` as the public OAuth-free test\n seam — the tracker's routed tests mount under the real router with an\n injected user.\n- Tests: val-issue-tracker 23 green (2 new: routed roles + prefixed links;\n end-to-end under the real router), integrations 15 green — `deno task\n check` in both repos. Live: tracker mounted at the integrations val\n (`/issues/`, 401-gated as configured); the standalone tracker val serves\n its existing data unchanged.\n- Gotcha for later tickets: the tracker imports the contract unpinned, and\n Deno caches remote modules — after pushing integrations, run `deno cache\n --reload=https://esm.town/v/nbbaier/integrations/mod.ts` in dependents\n before `deno task check`.\n",[],[225,341,342,359,385],"ca063689-322a-4702-8446-8daf48aae580","003-build-integrations-v1.md","27129ee8-7cb1-11f1-9ee9-1607ee4eb77e",121,["D",1783792524489],5,"---\nid: 3\ntitle: Build integrations v1 — contract exports, router, directory page\nlabels: [wayfinder:task]\nstatus: closed\nassignee: nbbaier\nblocked-by: [2]\n---\n\n## Question\n\nImplement the pinned contract in the `integrations` val\n(`~/Code/vt-projects/integrations`, currently an empty `main.ts`):\n\n- `mod.ts` exporting `Integration`, `defineIntegration`, `createRouter`.\n- The router per the ticket-1 architecture and ticket-2 API: dispatch,\n router-owned OAuth gate, user passed to integrations.\n- The directory page at `/`: name, description, link per registered\n integration; ⚠️ badge when a `requiredEnv` var is unset\n (`Deno.env.get(...)`).\n- Slug/reserved-path validation with clear construction-time errors.\n- `main.ts` as this val's own consumer (mirroring how `val-issue-tracker`'s\n `main.ts` consumes its `mod.ts`) — it can mount the hello-world integration\n once ticket 6 exists.\n- Tests where the repo's siblings set precedent (`deno task check` style:\n biome fmt, lint, typecheck, test).\n\nAFK: buildable solo once the contract is pinned; resolution records what\nshipped and any contract deviations discovered while building (feed those back\ninto the map).\n\n## Resolution\n\nBuilt and deployed 2026-07-10. What shipped:\n\n- `router.ts` — the implementation: `Integration` / `IntegrationContext` /\n `RouterOptions` types, `defineIntegration` (charset + reserved validation),\n `createRouteHandler(options, getUser)` (the OAuth-free core, user lookup\n injected — this is the test seam), and `createRouter` (wires\n `getOAuthUserData` + wraps with `oauthMiddleware` unless `auth: false`).\n- `mod.ts` — public re-exports only; third parties import this.\n- `router_test.ts` — 14 tests, all green via `deno task check` (fmt, lint,\n typecheck, test — tasks added to `deno.json` mirroring val-issue-tracker):\n validation throws, prefix strip + ctx, trailing-slash canonicalization\n preserving query, buffered POST bodies, 404/directory, requiredEnv badge,\n Location rewriting incl. protocol-relative (`//host`) and absolute\n pass-through, and the full auth matrix (anon GET→401 login page, anon\n non-GET→302 home, allowlist 403/200, `auth: false`→`ctx.user` null).\n- `main.ts` (HTTP) — this val's consumer: `createRouter({ title:\n \"Integrations\", auth: { users: \"nbbaier\" }, integrations: [] })`. Live at\n https://nbbaier--477921dc7cb811f194e81607ee4eb77e.web.val.run — verified\n serving the login page (401, allowlist named, no env warning). The\n hello-world integration (ticket 6) registers here.\n- Housekeeping: fixed the template's Deno-2-deprecated `lint.files` config.\n\nContract deviations discovered while building: **none** — the pinned API\nimplemented cleanly. One addition the contract didn't specify: anonymous\nnon-GET requests bounce 302 home rather than rendering the login page\n(precedent from scoped-blob-viewer; a stale form POST shouldn't render HTML\ninto a POST response).\n",[],[225,341,342,359,393],"5eb8c63d-bcdd-417a-890e-bdc9e5c5b828","002-pin-the-v1-contract.md","274f5dce-7cb1-11f1-ab0f-1607ee4eb77e",119,["D",1783792524595],"---\nid: 2\ntitle: Pin the v1 contract — Integration type, defineIntegration, createRouter API\nlabels: [wayfinder:grilling]\nstatus: closed\nassignee: nbbaier\nblocked-by: [1]\n---\n\n## Question\n\nFinalize the exact public API of `integrations/mod.ts`. The charter settled\nthe shape; this ticket pins the details the architecture decision unlocks.\n\nSettled by the charter (do not relitigate):\n\n```ts\ninterface Integration {\n name: string; // \"Issue Tracker\"\n slug: string; // \"issues\" → mount prefix\n description?: string;\n requiredEnv?: string[]; // e.g. [\"OAUTH_STATE_ENCRYPTION_KEY\"] → ⚠️ on the directory page\n handler: (req: Request) => Response | Promise;\n}\n```\n\nAuthors export `(options) => Integration` factories built with\n`defineIntegration`; users write\n`createRouter({ integrations: [issueTracker({...})], auth: {...} })`.\n\nTo pin here:\n\n- **Handler signature**: how does the router pass the authenticated user (and\n anything else, e.g. the mount prefix) to the integration? Extra context arg\n (`(req, ctx)`), request header, or a richer handler type? Depends on the\n ticket-1 architecture.\n- **Prefix rules**: if (A) won, the exact contract for links/forms/assets under\n a mount prefix — what the router guarantees (e.g. strips the prefix? passes\n it in ctx?) and what authors must do. If this takes three paragraphs of\n caveats, that is a design smell to feed back.\n- **Slug validation**: charset, uniqueness, reserved names (`auth`, plus the\n root). When does `createRouter` reject — construction time, with what error?\n- **`createRouter` options**: `auth` shape (`owner`/allowed users, off switch),\n `title` for the directory page, anything else v1 actually needs. Keep\n minimal.\n- **What `defineIntegration` actually does** beyond identity/typing —\n validation? defaults?\n\nHITL: grill through these one at a time (/grilling, /domain-modeling).\n\n## Resolution\n\nDecided 2026-07-10 by grilling. The v1 public API of `integrations/mod.ts`:\n\n```ts\ninterface IntegrationContext {\n\tuser: string | null; // Val Town username via router-owned OAuth\n\tprefix: string; // mount prefix, e.g. \"/issues\"\n}\n\ninterface Integration {\n\tname: string;\n\tslug: string;\n\tdescription?: string;\n\trequiredEnv?: string[];\n\thandler: (req: Request, ctx?: IntegrationContext) => Response | Promise;\n}\n\ninterface RouterOptions {\n\tintegrations: Integration[]; // order = directory order\n\tauth?: { users?: string | string[] } | false; // default ON, any logged-in user\n\ttitle?: string; // directory header, default \"Integrations\"\n}\n```\n\n- **Context as second argument, nothing in headers.** `handler(req, ctx)`.\n Aligns with Hono: an integration exporting `app.fetch` reads `c.env.user` /\n `c.env.prefix` directly (`Hono<{ Bindings: IntegrationContext }>` for\n typing) — same object reference, no adapter. Standalone mode passes no ctx,\n so `c.env?.user` is the dual-mode idiom. No identity headers = no spoofing\n surface.\n- **Response rewriting: root-absolute `Location` headers get the prefix\n prepended** by the router ([ADR 0002](../../../adr/0002-location-header-rewriting.md)).\n HTML is never rewritten — authors use relative URLs or `ctx.prefix`. Result:\n `c.redirect(\"/?ok=...\")` and the whole redirect-after-POST idiom work\n unmodified in BOTH modes with zero branching.\n- **Slugs:** `^[a-z0-9-]+$`, unique per router, checked against\n `RESERVED_SLUGS: (string | RegExp)[] = [\"auth\", /^_/]` — `auth` because\n std/oauth hardcodes `/auth/*`; `/^_/` publishes the underscore namespace as\n router-owned forever (unspellable under the charset today; guards a future\n loosening). Violations **throw at construction** with the offending slug\n named, so bad config fails the deploy, never serves silently broken routes.\n- **Auth is a gate, not a role system.** `auth.users` is an allowlist of who\n may enter; what they may DO stays integration-domain logic fed by\n `ctx.user` (issue tracker keeps maintainer/contributor — that seam belongs\n to its migration ticket). `auth: false` opts out; `ctx.user` is then null.\n- **Nothing else in v1**: no per-integration auth overrides, no hooks, no\n custom directory renderer — v2-shaped until a migration proves a need.\n",[],[225,341,342,359,402],"4a4e470c-45b1-4258-972d-511378f28d4e","001-prototype-dispatch-architecture.md","04f1644c-7d52-11f1-acde-1607ee4eb77e",130,["D",1783792664698],"---\nid: 1\ntitle: Prototype the dispatch architecture — in-process mount (A) vs sibling-endpoint redirect (B′)\nlabels: [wayfinder:prototype]\nstatus: closed\nassignee: nbbaier\nblocked-by: []\n---\n\n## Question\n\nWhich dispatch architecture does `createRouter` use? Build cheap stubs of both\non Val Town and decide from the evidence. This is the load-bearing mechanical\nunknown; nearly every other ticket blocks on it.\n\n**(A) In-process mount.** One HTTP endpoint; the router holds `Integration`\nhandlers and dispatches by path prefix (`/issues/*` → issue tracker's fetch\nhandler with a rewritten path). One origin: a true single URL, one OAuth\nsession. Costs to verify:\n\n- **Prefix hygiene**: both existing integrations emit absolute paths\n (`/view?key=...`, form `action=\"/delete\"`, `/auth/login`) that break under a\n `/blobs` prefix. How painful is making a real app prefix-correct — does Hono\n `basePath`/route-mounting get most of the way, or is it a caveat-laden\n contract on every author?\n- **OAuth composition**: can the router wrap `oauthMiddleware` once at the top,\n mount `/auth/*` once, and pass the authenticated user down to integrations\n (the \"router owns auth\" design intent)? Verify `getOAuthUserData` works from\n inside a prefix-mounted child handler.\n\n**(B′) Sibling endpoint files + redirecting directory.** Each integration is\nits own HTTP file in the host val (own URL, but scoped SQLite/blob is\nval-scoped, so storage is still shared — confirmed platform fact). The router\nendpoint is a launcher that 302s `/issues` to the sibling's URL. Existing\nintegrations work unmodified today. Costs to verify:\n\n- Separate origins → separate cookie jars → per-integration OAuth logins. How\n bad does that feel in practice?\n- \"Mounting\" = creating a file per integration + telling the router about it;\n the astro-style `createRouter({ integrations: [...] })` API can't hold the\n handlers, only metadata/URLs.\n\n**Thumb on the scale**: the charter's astro/vite composition model\n(`createRouter` receives integration instances) presupposes (A). (B′) wins\nonly if prefix hygiene or OAuth composition turns out genuinely nasty.\n\nPlatform notes: `Response.redirect` is broken on Val Town — use Hono\n`c.redirect` or a manual 302. Each HTTP file's URL comes from `links.endpoint`\nvia `list_files` / `create_file`; never construct it by hand.\n\nHITL: build the stubs, then react to them together before recording the\ndecision.\n\nThe decision meets all three ADR criteria (hard to reverse, surprising without\ncontext, real trade-off): record it as the repo's first ADR at\n`docs/adr/0001-dispatch-architecture.md` in addition to the resolution comment.\n\n## Resolution\n\n**Architecture (A) — in-process prefix mount.** Decided 2026-07-10 after both\nstubs ran live; recorded as [ADR 0001](../../../adr/0001-dispatch-architecture.md).\nThe prototype (`proto/`, since deleted) established:\n\n- **Dispatch works.** The router matches `/slug` prefixes, rewrites the URL\n (child sees `/`), and passes `x-mount-prefix`. POSTs survive with a buffered\n body (`await req.blob()` — streams need re-wrapping care).\n- **Prefix hygiene is a one-line rule, not a wall of caveats.** With the\n router canonicalizing `/slug` → `/slug/` (302, reverse-proxy convention),\n plain relative links AND relative form actions resolve correctly. Only\n root-absolute paths (`/two`, `action=\"/add\"`) break. Contract rule: use\n relative URLs or the provided prefix; never root-absolute.\n- **Router-owned auth verified.** `oauthMiddleware` wrapped once at the\n router; after one login, children saw the user both via a router-set header\n (`x-router-user`) and by calling `getOAuthUserData` directly on the\n rewritten request — cookies flow through. Integrations need no OAuth code.\n- **Scoped SQLite is shared across all mount styles** (val-scoped, verified\n in both directions), so (B′) held no storage advantage.\n- **(B′) rejected**: split origins mean per-integration logins and a\n launcher-only \"single URL\", and the astro-style\n `createRouter({ integrations: [...] })` API can't exist — mounting would\n mean creating a file per integration instead of just importing a factory\n (a real UX loss).\n",[],[225,341,342,359,410],"72785ed1-e6af-4eb2-a126-35d7610911ca",113,["D",1783792524099],[250,251,252,253,254,255,256,257],[225,341,342,359],"4943a8e8-7e18-4b5e-9cf5-01f32b53ffb3","b0de7188-7d51-11f1-b8b2-1607ee4eb77e",112,["D",1783792523949],[249,258,259],[225,341,342],"159d8575-7826-4301-a89a-db8a19f128a9",111,["D",1783792523821],[248],[225,341],"12e1c021-01bc-47fc-816f-20241cf27fae","2428d405-c9ba-409c-80a1-535778f75f37",["D",1783802802386],[],[225,438,33],"notes","652c10c5-892e-45b9-8646-fc241d0be5f7",135,["D",1783802742029],[246],[225,438],"e6888750-1cd9-420f-922a-381b22a205ad","0003-callable-integrations.md","38b33f42-7d40-11f1-9235-1607ee4eb77e","c2500b00-7cb3-11f1-accf-1607ee4eb77e",68,["D",1783785020716],"# defineIntegration returns a callable Integration\n\n`defineIntegration` returns the `Integration` object made directly callable\nas an HTTP handler (`CallableIntegration = Integration & IntegrationHandler`;\ncalling it with no ctx is standalone mode). The charter requires every\nintegration factory to serve both modes — `export default myFactory({...})`\nas a standalone HTTP val AND `createRouter({ integrations: [myFactory({...})] })`\n— and an `Integration` is a plain object, not a function, so without this the\ntwo mounting styles would need different factory return values (`.handler` in\none place, the object in the other). Making the contract helper produce the\nhybrid gives every author dual-mode support for free; the val-issue-tracker\nmigration proved the need.\n\n## Consequences\n\n- `export default myFactory({...})` is a valid HTTP val export; the platform\n calls it with no ctx, which is exactly the standalone signal the contract\n already defined (`ctx` absent).\n- Integration fields are attached with `Object.defineProperty` because a\n function's own `name` is read-only-but-configurable and `Integration.name`\n must shadow it.\n- The router still calls `.handler(req, ctx)`; plain object literals that\n merely satisfy the `Integration` type keep working when registered, they\n just aren't standalone-mountable.\n",[],[225,453,445],"adr","37dcf046-3898-4ff2-80a4-b684d1d7852d","0002-location-header-rewriting.md","cf4fd38c-7cb6-11f1-b356-1607ee4eb77e",50,["D",1783726398517],"# The router rewrites root-absolute Location headers, and only those\n\nWhen a mounted integration responds with a `Location` header starting with\n`/`, the router prepends the mount prefix (`Location: /?ok=x` →\n`/issues/?ok=x`); HTML bodies are never rewritten. We chose this asymmetry —\nover rewriting nothing (strict authoring rule) or rewriting everything (full\nreverse-proxy) — because HTML links have the document base URL as a safety\nnet, so relative links are natural to write, while redirects are generated\nfar from any notion of \"where am I mounted\"; covering `Location` makes the\nubiquitous redirect-after-POST idiom (`c.redirect(\"/?ok=...\")`) work\nunmodified in both routed and standalone modes with zero branching, exactly\nlike nginx's `proxy_redirect`.\n\n## Consequences\n\n- An integration cannot reach the router root or a sibling integration via a\n bare `/...` redirect; it uses `ctx.prefix` or a full absolute URL. Rare and\n deliberate by design.\n- Body rewriting stays the author's responsibility: relative URLs, or\n `ctx.prefix` when an absolute path is unavoidable.\n",[],[225,453,455],"ccb529f3-9e06-4ec0-808e-d7e4b8093b08","0001-dispatch-architecture.md","c2a2a518-7cb3-11f1-af02-1607ee4eb77e",38,["D",1783724692803],"# In-process prefix dispatch, not sibling-endpoint redirects\n\nThe router (`createRouter`) mounts integrations **in-process**: one HTTP\nendpoint holds every registered integration's fetch handler and dispatches by\npath prefix (`/issues/*` → issue tracker), rewriting the request URL and\npassing mount context along. We prototyped both this and the alternative —\neach integration as its own sibling HTTP file in the host val, with a\ndirectory endpoint 302-ing out — and chose in-process (2026-07-10, prototype\nsince deleted; evidence recorded on wayfinder ticket 1).\n\n## Considered Options\n\n**Sibling endpoints + redirecting directory** was rejected. Its one real\nadvantage — existing integrations work unmodified — evaporated when the\nprototype showed the in-process authoring burden collapses to a one-line rule:\nwith the router canonicalizing `/slug` → `/slug/`, plain relative URLs just\nwork, and only root-absolute paths break. What it could never offer: each\nsibling file is its own origin, so users log in separately per integration,\nthe single URL is only a launcher, and `createRouter({ integrations: [...] })`\ncan't exist — mounting means creating a file per integration instead of\nimporting a factory.\n\n## Consequences\n\n- One origin: one OAuth login for every integration. Verified: the router\n wraps `oauthMiddleware` once, and `getOAuthUserData` works both in the\n router and inside a prefix-mounted child (session cookies survive the\n request rewrite).\n- Integration authors must use relative URLs (or the provided mount prefix)\n and never root-absolute paths; the router guarantees trailing-slash\n canonicalization of the mount root.\n- Scoped SQLite/blob need no special handling — storage is val-scoped, so\n in-process children naturally share the host val's data (verified; true of\n the rejected option too).\n- Request bodies are re-wrapped during URL rewriting; the router buffers them\n rather than streaming.\n",[],[225,453,463],"b8d5d5fd-e95b-4cdc-831d-08861e689a73",32,["D",1783724692595],[242,243,244],[225,453],["D",1783724692393],[241,245,247],[225],["D",1783715038579],["D",1789525245864],{"_97":96,"_104":100},{"_97":96,"_98":-5,"_99":100,"_18":54,"_101":102,"_103":25},{"_13":86,"_32":87,"_42":41,"_88":43,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":-5,"_94":44,"_95":96},"ctx",{"_79":-5,"_124":516,"_517":518,"_519":520,"_521":25,"_522":25,"_523":25,"_524":122,"_525":-5,"_526":-7,"_527":-7,"_528":60,"_529":25,"_530":25,"_531":-5,"_532":25,"_533":25,"_534":25,"_535":-5},"ENV",{"_487":488,"_489":490,"_491":87,"_492":493,"_494":495,"_496":497,"_498":499,"_500":501,"_502":503,"_504":505,"_506":507,"_508":509,"_510":511,"_512":513,"_514":515},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","811aa22498c9b0b5a47e8d778de579cdb990f332","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Diff · v137