[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_387":388,"_389":390},"routes/_app.x.$handle.$name",{"_96":95,"_31":43,"_104":86,"_26":51,"_13":14,"_105":-5,"_11":106,"_107":108,"_109":110,"_111":112,"_113":114,"_20":-5,"_115":-5,"_116":-5,"_117":24,"_118":119,"_120":121,"_122":-5,"_123":-5,"_124":125},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_41":42,"_31":43,"_36":44,"_45":-5,"_46":24,"_47":48,"_49":48,"_50":51,"_52":-5,"_18":53,"_54":-5,"_55":24,"_56":-5,"_57":-5,"_58":59,"_60":61,"_62":63,"_64":65,"_66":67,"_68":-5,"_69":70,"_71":70,"_72":73,"_74":73,"_75":73,"_76":70,"_77":70,"_78":79,"_80":81,"_82":83,"_84":24},"version",68,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":-7,"_23":24,"_25":24,"_26":27,"_28":27},"file",{"_29":30,"_31":32,"_33":20,"_34":35,"_36":37,"_38":14,"_39":40,"_23":24},"previous","deleted",false,"deletedHere","path","docs/adr/0003-callable-integrations.md","latestPath","fileId","38b33f42-7d40-11f1-9235-1607ee4eb77e","name","0003-callable-integrations.md","fileType","content","# 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","createdAt",["D",1783785020716],"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",{"_96":95,"_103":99},"org",{"_96":95,"_97":-5,"_98":99,"_18":53,"_100":101,"_102":24},"branch",{"_13":85,"_31":86,"_41":40,"_87":42,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":43,"_94":95},"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",{"_41":42,"_31":43,"_36":382,"_45":-5,"_46":24,"_47":48,"_49":48,"_50":51,"_52":-5,"_18":53,"_54":-5,"_55":24,"_56":-5,"_57":-5,"_58":59,"_60":61,"_62":63,"_64":65,"_66":383,"_68":-5,"_69":70,"_71":70,"_72":73,"_74":73,"_75":73,"_76":70,"_77":70,"_78":384,"_80":385,"_82":386,"_84":24},"tree",[221,226,237,238,239,240,241,242,243,244],"files",[221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,240,241,242,243,244],"counts",{"_211":59,"_212":167,"_213":59,"_214":215,"_216":217},"contents",[126,127,128,129,130,131,132,133,134,135],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles",true,"grants","orgs","customDomains",{},{"_41":205,"_31":206,"_29":207,"_139":-5,"_39":40,"_38":208,"_141":121,"_36":209,"_13":59,"_33":203,"_34":-5,"_23":24,"_145":-5,"_26":210},{"_41":198,"_31":199,"_29":200,"_139":-5,"_39":40,"_38":201,"_141":24,"_36":202,"_13":59,"_33":203,"_34":-5,"_23":24,"_145":-5,"_26":204},{"_41":191,"_31":192,"_29":193,"_139":-5,"_39":40,"_38":194,"_141":121,"_36":195,"_13":59,"_33":20,"_34":196,"_23":24,"_145":-5,"_26":197},{"_41":184,"_31":185,"_29":186,"_139":-5,"_39":40,"_38":187,"_141":24,"_36":188,"_13":167,"_33":20,"_34":189,"_23":24,"_145":-5,"_26":190},{"_41":178,"_31":179,"_29":180,"_139":-5,"_39":40,"_38":152,"_141":24,"_36":181,"_13":59,"_33":20,"_34":182,"_23":24,"_145":-5,"_26":183},{"_41":171,"_31":172,"_29":173,"_139":-5,"_39":40,"_38":174,"_141":24,"_36":175,"_13":167,"_33":20,"_34":176,"_23":24,"_145":-5,"_26":177},{"_41":162,"_31":163,"_29":164,"_139":-5,"_39":40,"_38":165,"_141":24,"_36":166,"_13":167,"_33":168,"_34":169,"_23":24,"_145":-5,"_26":170},{"_41":155,"_31":156,"_29":157,"_139":-5,"_39":40,"_38":158,"_141":24,"_36":159,"_13":59,"_33":143,"_34":160,"_23":24,"_145":-5,"_26":161},{"_41":147,"_31":148,"_29":149,"_139":-5,"_39":40,"_38":150,"_141":24,"_36":151,"_13":152,"_33":143,"_34":153,"_23":24,"_145":-5,"_26":154},{"_41":136,"_31":137,"_29":138,"_139":-5,"_39":40,"_38":140,"_141":24,"_36":142,"_13":59,"_33":143,"_34":144,"_23":24,"_145":-5,"_26":146},"e86a249f-37e7-4318-a0ba-e93b98dd0a44","router_test.ts","47cd43fc-7cb8-11f1-bf06-1607ee4eb77e","parentId",57,"latest",["D",1783726633902],"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\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",[137],"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",[148],"ef74b2ee-1f08-4937-b6f9-838c0b5b94a3","mod.ts","4795d00c-7cb8-11f1-a2c1-1607ee4eb77e",56,["D",1783726633925],"export {\n\tcreateRouter,\n\tdefineIntegration,\n\ttype Integration,\n\ttype IntegrationContext,\n\ttype RouterAuthOptions,\n\ttype RouterOptions,\n} from \"./router.ts\";\n",[156],"04a19bf5-4974-4327-8dcf-59f4f2db1d86","main.ts","477921dc-7cb8-11f1-94e8-1607ee4eb77e",58,["D",1783726645160],1,"http","// This val's own consumer of its router. The hello-world example integration\n// (wayfinder ticket 6) registers here once it exists.\nimport { createRouter } from \"./mod.ts\";\n\nexport default createRouter({\n\ttitle: \"Integrations\",\n\tauth: { users: \"nbbaier\" },\n\tintegrations: [],\n});\n",[163],"11f920bc-d884-40b7-9387-6aa34a524b72","deno.json","525df192-7c9d-11f1-a2d0-1607ee4eb77e",55,["D",1783726634031],"{\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\"],\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\",\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",[172],"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",[179],"b2ec6ce4-9ded-46ef-93c4-6351201295bd","CONTEXT.md","2744ac76-7cb1-11f1-b0e8-1607ee4eb77e",45,["D",1783726002919],"# 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## 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**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",[185],"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",[192],"81dd5a6f-8a25-49a7-9752-cf573ba54bc8","wayfinder","26e8811c-7cb1-11f1-81a5-1607ee4eb77e",5,["D",1783723572890],"directory",[199],"a29dc277-7931-4cf4-b228-0524d69fcc23","docs","c22f6a9e-7cb3-11f1-a763-1607ee4eb77e",31,["D",1783724692393],[206],"pulls","branches","forks","envVars",{"_218":167,"_220":59},"connections",{"_218":59,"_219":59},"count","unfilledCount","emptyCount",{"_41":205,"_31":206,"_29":207,"_139":-5,"_39":40,"_38":208,"_141":121,"_36":379,"_13":59,"_33":203,"_34":-5,"_23":24,"_145":-5,"_246":380,"_26":381},{"_41":374,"_31":357,"_29":353,"_139":207,"_39":40,"_38":375,"_141":121,"_36":376,"_13":59,"_33":203,"_34":-5,"_23":24,"_145":-5,"_246":377,"_26":378},{"_41":366,"_31":367,"_29":368,"_139":353,"_39":40,"_38":369,"_141":24,"_36":370,"_13":59,"_33":20,"_34":371,"_23":24,"_145":-5,"_246":372,"_26":373},{"_41":358,"_31":359,"_29":360,"_139":353,"_39":40,"_38":361,"_141":24,"_36":362,"_13":152,"_33":20,"_34":363,"_23":24,"_145":-5,"_246":364,"_26":365},{"_41":352,"_31":32,"_29":30,"_139":353,"_39":40,"_38":14,"_141":24,"_36":354,"_13":59,"_33":20,"_34":35,"_23":24,"_145":-5,"_246":355,"_26":356},{"_41":198,"_31":199,"_29":200,"_139":-5,"_39":40,"_38":201,"_141":24,"_36":349,"_13":59,"_33":203,"_34":-5,"_23":24,"_145":-5,"_246":350,"_26":351},{"_41":344,"_31":287,"_29":281,"_139":200,"_39":40,"_38":345,"_141":24,"_36":346,"_13":59,"_33":203,"_34":-5,"_23":24,"_145":-5,"_246":347,"_26":348},{"_41":336,"_31":337,"_29":338,"_139":281,"_39":40,"_38":339,"_141":24,"_36":340,"_13":152,"_33":20,"_34":341,"_23":24,"_145":-5,"_246":342,"_26":343},{"_41":328,"_31":329,"_29":330,"_139":281,"_39":40,"_38":331,"_141":24,"_36":332,"_13":167,"_33":20,"_34":333,"_23":24,"_145":-5,"_246":334,"_26":335},{"_41":320,"_31":321,"_29":322,"_139":281,"_39":40,"_38":323,"_141":24,"_36":324,"_13":194,"_33":20,"_34":325,"_23":24,"_145":-5,"_246":326,"_26":327},{"_41":312,"_31":313,"_29":314,"_139":281,"_39":40,"_38":315,"_141":24,"_36":316,"_13":167,"_33":20,"_34":317,"_23":24,"_145":-5,"_246":318,"_26":319},{"_41":304,"_31":305,"_29":306,"_139":281,"_39":40,"_38":307,"_141":24,"_36":308,"_13":59,"_33":20,"_34":309,"_23":24,"_145":-5,"_246":310,"_26":311},{"_41":296,"_31":297,"_29":298,"_139":281,"_39":40,"_38":299,"_141":24,"_36":300,"_13":59,"_33":20,"_34":301,"_23":24,"_145":-5,"_246":302,"_26":303},{"_41":288,"_31":289,"_29":290,"_139":281,"_39":40,"_38":291,"_141":24,"_36":292,"_13":167,"_33":20,"_34":293,"_23":24,"_145":-5,"_246":294,"_26":295},{"_41":278,"_31":279,"_29":280,"_139":281,"_39":40,"_38":282,"_141":24,"_36":283,"_13":167,"_33":20,"_34":284,"_23":24,"_145":-5,"_246":285,"_26":286},{"_41":270,"_31":271,"_29":272,"_139":200,"_39":40,"_38":273,"_141":24,"_36":274,"_13":194,"_33":20,"_34":275,"_23":24,"_145":-5,"_246":276,"_26":277},{"_41":191,"_31":192,"_29":193,"_139":-5,"_39":40,"_38":194,"_141":121,"_36":267,"_13":59,"_33":20,"_34":196,"_23":24,"_145":-5,"_246":268,"_26":269},{"_41":184,"_31":185,"_29":186,"_139":-5,"_39":40,"_38":187,"_141":24,"_36":264,"_13":167,"_33":20,"_34":189,"_23":24,"_145":-5,"_246":265,"_26":266},{"_41":178,"_31":179,"_29":180,"_139":-5,"_39":40,"_38":152,"_141":24,"_36":261,"_13":59,"_33":20,"_34":182,"_23":24,"_145":-5,"_246":262,"_26":263},{"_41":171,"_31":172,"_29":173,"_139":-5,"_39":40,"_38":174,"_141":24,"_36":258,"_13":167,"_33":20,"_34":176,"_23":24,"_145":-5,"_246":259,"_26":260},{"_41":162,"_31":163,"_29":164,"_139":-5,"_39":40,"_38":165,"_141":24,"_36":255,"_13":167,"_33":168,"_34":169,"_23":24,"_145":-5,"_246":256,"_26":257},{"_41":155,"_31":156,"_29":157,"_139":-5,"_39":40,"_38":158,"_141":24,"_36":252,"_13":59,"_33":143,"_34":160,"_23":24,"_145":-5,"_246":253,"_26":254},{"_41":147,"_31":148,"_29":149,"_139":-5,"_39":40,"_38":150,"_141":24,"_36":249,"_13":152,"_33":143,"_34":153,"_23":24,"_145":-5,"_246":250,"_26":251},{"_41":136,"_31":137,"_29":138,"_139":-5,"_39":40,"_38":140,"_141":24,"_36":245,"_13":59,"_33":143,"_34":144,"_23":24,"_145":-5,"_246":247,"_26":248},["D",1783726633902],"children",[],[137],["D",1783785020715],[],[148],["D",1783726633925],[],[156],["D",1783726645160],[],[163],["D",1783726634031],[],[172],["D",1783715055805],[],[179],["D",1783726002919],[],[185],["D",1783715055884],[],[192],"97b484f5-4493-4a6f-ad99-c7ee52a31a2f","map.md","273b54e6-7cb1-11f1-9d45-1607ee4eb77e",64,["D",1783730308298],"---\ntitle: Integrations v1 — contract + meta-router for Val Town project integrations\nlabels: [wayfinder:map]\nstatus: open\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](../docs/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](../docs/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\n## Not yet specified\n\n- **Permission-model composition**: how router-provided identity meets each\n integration's internal roles (issue tracker's maintainer/contributor/viewer)\n and its bearer-token JSON API. Sharpens once the prototype settles the auth\n mechanics.\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",[],[199,271],"a39c0f93-d05f-419e-a88b-86580cba1d34","008-publishing-and-versioning.md","7454ac76-7cb8-11f1-9441-1607ee4eb77e","26fcc42e-7cb1-11f1-9ee9-1607ee4eb77e",63,["D",1783730308292],"---\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",[],[199,287,279],"tickets","a0b304fc-54ec-4cd9-91ca-e25bf6c234de","007-third-party-author-docs.md","272f2194-7cb1-11f1-81a5-1607ee4eb77e",61,["D",1783726709272],"---\nid: 7\ntitle: Write the third-party author docs\nlabels: [wayfinder:task]\nstatus: open\nassignee:\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\nAFK draft, HITL review pass.\n",[],[199,287,289],"b51a8910-f845-41fd-afdf-1a2909abf5f5","006-hello-world-example-integration.md","27198942-7cb1-11f1-bf6f-1607ee4eb77e",8,["D",1783723573189],"---\nid: 6\ntitle: Add the hello-world example integration\nlabels: [wayfinder:task]\nstatus: open\nassignee:\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",[],[199,287,297],"c699725f-8a92-4e84-9a52-2333c1e760ab","005-migrate-scoped-blob-viewer.md","2721832c-7cb1-11f1-adf5-1607ee4eb77e",9,["D",1783723573217],"---\nid: 5\ntitle: Migrate scoped-blob-viewer onto the contract\nlabels: [wayfinder:task]\nstatus: open\nassignee:\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",[],[199,287,305],"8f693d2f-ba7c-4079-8cb3-45c7d7c00863","004-migrate-val-issue-tracker.md","273401aa-7cb1-11f1-bf6f-1607ee4eb77e",66,["D",1783784517596],"---\nid: 4\ntitle: Migrate val-issue-tracker onto the contract\nlabels: [wayfinder:task]\nstatus: open\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",[],[199,287,313],"c1ad9d44-e7b5-4eeb-9b0c-ca5acbc7cf85","003-build-integrations-v1.md","27129ee8-7cb1-11f1-9ee9-1607ee4eb77e",60,["D",1783726709289],"---\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",[],[199,287,321],"aea93b26-7b55-4815-9cdb-76f9bcd1b2d0","002-pin-the-v1-contract.md","274f5dce-7cb1-11f1-ab0f-1607ee4eb77e",47,["D",1783726002919],"---\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](../../docs/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",[],[199,287,329],"d90e2f8c-7f34-4ed7-ac11-33f61a821343","001-prototype-dispatch-architecture.md","27274514-7cb1-11f1-9ee9-1607ee4eb77e",34,["D",1783724692820],"---\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](../../docs/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",[],[199,287,337],"b04bf3db-6ece-438b-a26b-9b7e28940ee2",6,["D",1783723573021],[228,229,230,231,232,233,234,235],[199,287],["D",1783723572890],[227,236],[199],"e6888750-1cd9-420f-922a-381b22a205ad","c2500b00-7cb3-11f1-accf-1607ee4eb77e",["D",1783785020716],[],[206,357,32],"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",[],[206,357,359],"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",[],[206,357,367],"b8d5d5fd-e95b-4cdc-831d-08861e689a73",32,["D",1783724692595],[223,224,225],[206,357],["D",1783724692393],[222],[206],["D",1783715038579],["D",1789525245864],{"_96":95,"_103":99},{"_96":95,"_97":-5,"_98":99,"_18":53,"_100":101,"_102":24},{"_13":85,"_31":86,"_41":40,"_87":42,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":43,"_94":95},"ctx",{"_78":-5,"_123":420,"_421":422,"_423":424,"_425":24,"_426":24,"_427":24,"_428":121,"_429":-5,"_430":-7,"_431":-7,"_432":59,"_433":24,"_434":24,"_435":-5,"_436":24,"_437":24,"_438":24,"_439":-5},"ENV",{"_391":392,"_393":394,"_395":86,"_396":397,"_398":399,"_400":401,"_402":403,"_404":405,"_406":407,"_408":409,"_410":411,"_412":413,"_414":415,"_416":417,"_418":419},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","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 · v68