@abide/abide 0.102.0 → 0.103.0

package/src/server/abideModules.ts

@@ -7,8 +7,8 @@
 // WHICH FACE AN IMPORT GETS IS SPELLED ON ITS SPECIFIER (`MODULE_QUERIES`), because bun hands a plugin
 // no import attributes: a compiled module asks for `?component`, a browser module for its own
 // `?style`, a text import for `?text`. A `.abide` named bare is a module abide did not compile
-// asking — on a server that is the bound face 34.16 states, beside every name the module exports,
-// and in a browser the component module itself.
+// asking — on a server that is the bound face 34.16 states, and in a browser the component module
+// itself.
 //
 // THE TABLES — the route, error and handler tables, and in a browser the router's table and the
 // entry — are the build's own modules, served from `__abide` below the root, where no app writes.
@@ -17,13 +17,16 @@
 // that registered one, so a second app booted in the same process — a test's — adds its compilation
 // to this one rather than registering a plugin nobody asks.
 
-import { dirname, resolve } from 'node:path' // bun exposes no path helpers of its own
+import { basename, dirname, resolve } from 'node:path' // bun exposes no path helpers of its own
+import { SERVER_SPECIFIER } from '#shared/SPECIFIERS.ts'
 import type { ServerTable } from './answerRequest.ts'
 import type { MountRow } from './answerRpc.ts'
 import { installSourceMaps, type SourceMaps } from './installSourceMaps.ts'
 import {
     CLIENT_QUERY,
     COMPONENT_QUERY,
+    HANDLER_FACE,
+    HANDLER_SUFFIX,
     STYLE_QUERY,
     TEXT_QUERY,
 } from './MODULE_QUERIES.ts'
@@ -51,8 +54,18 @@ export type CompiledFile = {
 export type Compilation = {
     /** Every `.abide` compiled, by its path below the root. */
     files: Record<string, CompiledFile>
+    /**
+     * Every handler file, by its path below the root: the route its hooks are filed at (37.1), and
+     * the module a browser is handed in its place (16.74), `''` where the browser is handed none.
+     */
+    handlers: Record<string, HandlerFace>
     /** The build's own modules, by name below `__abide`. */
     tables: Record<string, string>
+    /**
+     * 23.19 — every directory a file mounts, by its path below the root, to the position its files
+     * take: what the browser's fence reads a mounted file's place by (16.29).
+     */
+    mounted: Record<string, string>
 }
 
 // A VIRTUAL FACE'S PATH: its file's, with a suffix that is not a query. Both registries key a module
@@ -68,29 +81,40 @@ export const COMPONENT_NAMESPACE = 'abide-component'
 /** The namespaces a file's text and a component's stylesheet are loaded in. */
 export const TEXT_NAMESPACE = 'abide-text'
 export const STYLE_NAMESPACE = 'abide-style'
+const RELATIVE_OR_SUBPATH = /^(?:\.\.?\/|#)/
 
-/** What the plugin answers from: a compiled file or a table by absolute path. */
-type Served = {
-    file: (path: string) => CompiledFile | undefined
-    table: (path: string) => string | undefined
-}
+/** One handler file, as `Compilation.handlers` holds it. */
+type HandlerFace = { scope: string; client: string }
 
 /** The plugin serving `compilation`'s files and tables, for one bundle. */
 export function abideModules(
     root: string,
     compilation: Compilation,
 ): Bun.BunPlugin {
-    const files = new Map<string, CompiledFile>()
-    const tables = new Map<string, string>()
-    addCompilation(realOrAsGiven(root), compilation, files, tables)
-    return modulesPlugin({
-        file: (path) => files.get(path),
-        table: (path) => tables.get(path),
-    })
+    const held: Held = {
+        files: new Map(),
+        handlers: new Map(),
+        tables: new Map(),
+    }
+    addCompilation(realOrAsGiven(root), compilation, held)
+    return modulesPlugin(held)
+}
+
+/**
+ * A compilation as the plugin keys it, and answers from: a compiled file, a handler file or a table
+ * by absolute path.
+ */
+type Held = {
+    files: Map<string, CompiledFile>
+    handlers: Map<string, HandlerFace>
+    tables: Map<string, string>
 }
 
-const RUNTIME_FILES = new Map<string, CompiledFile>()
-const RUNTIME_TABLES = new Map<string, string>()
+const RUNTIME: Held = {
+    files: new Map(),
+    handlers: new Map(),
+    tables: new Map(),
+}
 let registered = false
 
 /**
@@ -99,16 +123,11 @@ let registered = false
  */
 export function serveCompilation(root: string, compilation: Compilation): void {
     const real = realOrAsGiven(root)
-    addCompilation(real, compilation, RUNTIME_FILES, RUNTIME_TABLES)
+    addCompilation(real, compilation, RUNTIME)
     installSourceMaps(serverMapsOf(compilation, real), real)
     if (registered) return
     registered = true
-    Bun.plugin(
-        modulesPlugin({
-            file: (path) => RUNTIME_FILES.get(path),
-            table: (path) => RUNTIME_TABLES.get(path),
-        }),
-    )
+    Bun.plugin(modulesPlugin(RUNTIME))
 }
 
 /** What the server's table exports: its routes and error pages, server blocks and handlers. */
@@ -146,14 +165,15 @@ export function serverMapsOf(
 function addCompilation(
     root: string,
     compilation: Compilation,
-    files: Map<string, CompiledFile>,
-    tables: Map<string, string>,
+    held: Held,
 ): void {
     // RESOLVED, not joined: a dependency's file is keyed above the root (`../node_modules/…`).
     for (const [relative, compiled] of Object.entries(compilation.files))
-        files.set(resolve(root, relative), compiled)
+        held.files.set(resolve(root, relative), compiled)
+    for (const [relative, face] of Object.entries(compilation.handlers))
+        held.handlers.set(resolve(root, relative), face)
     for (const [name, text] of Object.entries(compilation.tables))
-        tables.set(`${root}/${VIRTUAL_DIRECTORY}/${name}`, text)
+        held.tables.set(`${root}/${VIRTUAL_DIRECTORY}/${name}`, text)
 }
 
 // `Bun.resolveSync` asks EVERY abide plugin's `onResolve` again — this one's, and the runtime's, which
@@ -178,7 +198,7 @@ export function resolvedFile(specifier: string, from: string): string {
     }
 }
 
-function modulesPlugin(served: Served): Bun.BunPlugin {
+function modulesPlugin(served: Held): Bun.BunPlugin {
     return {
         name: 'abide-modules',
         setup(build) {
@@ -264,12 +284,55 @@ function modulesPlugin(served: Served): Bun.BunPlugin {
                         dirname(pathOf(args.importer)),
                         args.path,
                     )
-                    return served.table(path) === undefined
+                    return served.tables.get(path) === undefined
                         ? undefined
                         : { path, namespace: 'abide-table' }
                 },
             )
 
+            // A HANDLER FILE IS FOUND BY WHERE ITS IMPORT RESOLVES, however the import spells it, and
+            // only from the app's own modules: a package's never names one, and asking bun again for
+            // each of a package's relative imports is a resolve per module of the bundle. IN A BUNDLE
+            // THE FILTER IS THE HANDLER FILES' NAMES: a hook matching every relative import costs the
+            // bundle abide's own `sideEffects`, and the barrel's rest — the validator, the csp — moved
+            // into the chunk every page loads (38.94). The runtime is told of each compilation after
+            // it registered, so it matches every relative or `#` import and asks.
+            // Each handler file's name without `.ts` — what an import of one ends in.
+            let stems: string[] | undefined
+            if (bundling) {
+                const names = new Set<string>()
+                for (const path of served.handlers.keys())
+                    names.add(basename(path, '.ts'))
+                stems = [...names]
+            }
+            const handlerImport =
+                stems === undefined
+                    ? RELATIVE_OR_SUBPATH
+                    : new RegExp(
+                          `(?:^|/)(?:${stems.map(RegExp.escape).join('|')})(?:\\.ts)?$`,
+                      )
+            if (stems?.length !== 0)
+                build.onResolve({ filter: handlerImport }, (args) => {
+                    if (resolving || !RELATIVE_OR_SUBPATH.test(args.path))
+                        return undefined
+                    const importer = pathOf(args.importer)
+                    if (importer.includes('/node_modules/')) return undefined
+                    let path: string
+                    try {
+                        path = resolved(args.path, args.importer)
+                    } catch {
+                        return undefined
+                    }
+                    const face = served.handlers.get(path)
+                    if (face === undefined) return undefined
+                    // 20.4 — a handler the browser is handed no wrapper for is no import of its.
+                    if (inBrowser(args.importer) && face.client === '')
+                        throw new Error(
+                            `abide: ${pathOf(args.importer)} imports ${args.path}, whose handler withholds itself from the browser (\`clients: { ui: false }\`). Call it from a <script server>, or let the browser have it. RULEBOOK 20.4.`,
+                        )
+                    return { path: `${path}${HANDLER_SUFFIX}` }
+                })
+
             // A RELATIVE SPECIFIER A FACE IMPORTS AT RUN TIME is resolved from the file the face
             // stands for: bun's runtime reads one from an importer in a namespace as no path at
             // all. A bare one it resolves itself. Registered after every face, so a `.abide` is
@@ -294,6 +357,22 @@ function modulesPlugin(served: Served): Bun.BunPlugin {
                     }
                 },
             )
+            // 16.74, 37.1 — A HANDLER FILE: the browser's is its wrapper, and the server's is the file
+            // as written, between the two calls that file its hooks at its route — on its first
+            // line, so every line of the file stays where its frames name it. ITS FACE is its path
+            // with a suffix, in bun's own namespace — so what it imports, relative, `#` or bare,
+            // resolves from its directory as the file's own imports do. A namespace of abide's own
+            // had bun resolve a bare one from the working directory: a second abide, run from `/`.
+            build.onLoad({ filter: HANDLER_FACE }, async (args) => {
+                const path = args.path.slice(0, -HANDLER_SUFFIX.length)
+                const face = served.handlers.get(path) as HandlerFace
+                if (browser) return { contents: face.client, loader: 'js' }
+                const text = await Bun.file(path).text()
+                return {
+                    contents: `import { fileRoute as __fileRoute } from '${SERVER_SPECIFIER}';__fileRoute(${JSON.stringify(face.scope)});${text}\n;__fileRoute(undefined)\n`,
+                    loader: 'ts',
+                }
+            })
             build.onLoad(
                 { filter: /.*/, namespace: 'abide-client' },
                 (args) => ({
@@ -307,10 +386,7 @@ function modulesPlugin(served: Served): Bun.BunPlugin {
             build.onLoad({ filter: /.*/, namespace: 'abide-bound' }, (args) => {
                 const path = args.path.slice(0, -BOUND.length)
                 return {
-                    contents: boundModule(
-                        path,
-                        compiledAt(served, path).server,
-                    ),
+                    contents: boundModule(path),
                     loader: 'js',
                 }
             })
@@ -339,7 +415,7 @@ function modulesPlugin(served: Served): Bun.BunPlugin {
             build.onLoad(
                 { filter: /.*/, namespace: 'abide-table' },
                 (args) => ({
-                    contents: served.table(args.path) ?? '',
+                    contents: served.tables.get(args.path) ?? '',
                     loader: 'ts',
                 }),
             )
@@ -355,8 +431,8 @@ function pathOf(importer: string): string {
 
 // THE PATH BUN NAMES A FILE BY HAS ITS LINKS RESOLVED, and so has the root a compilation is served
 // under (`serveCompilation`).
-function compiledAt(served: Served, path: string): CompiledFile {
-    const compiled = served.file(path)
+function compiledAt(served: Held, path: string): CompiledFile {
+    const compiled = served.files.get(path)
     if (compiled === undefined)
         throw new Error(
             `abide: ${path} is imported, and no compile of this app reached it.`,
@@ -364,22 +440,12 @@ function compiledAt(served: Served, path: string): CompiledFile {
     return compiled
 }
 
-const SCANNER = new Bun.Transpiler({ loader: 'ts' })
-
 // 34.16 — BOUND, NOT RAW. The compiled module is a function of accessors answering its markup (33.4);
 // what an app's own module calls is a function of plain props answering a `Component` (35.4), which
-// `render` invokes with nothing. Every name the module exports rides beside it: a `<script module>`'s,
-// and the handlers a `<script server>` declares (34.23).
-//
-// NAMED RATHER THAN `export *`: the server blocks load side by side at boot, and a star export
-// through a module still loading found none of its names.
-function boundModule(path: string, server: string): string {
-    const specifier = JSON.stringify(path)
-    const names: string[] = []
-    for (const name of SCANNER.scan(server).exports)
-        if (name !== 'default') names.push(name)
-    return `import component from ${specifier}
-${names.length === 0 ? '' : `export { ${names.join(', ')} } from ${specifier}\n`}export default (props = {}) => {
+// `render` invokes with nothing. The component is the module's one export (34.17).
+function boundModule(path: string): string {
+    return `import component from ${JSON.stringify(path)}
+export default (props = {}) => {
     const accessors = {}
     for (const key in props) {
         const value = props[key]

package/src/server/answerRequest.ts

@@ -13,6 +13,7 @@ import {
     HEALTH_ADDRESS,
     MCP_ADDRESS,
     OPENAPI_ADDRESS,
+    PRIVATE_HANDLERS_ADDRESS,
 } from '#shared/ADDRESSES.ts'
 import { APP_META } from '#shared/APP_META.ts'
 import { DEBUG_META } from '#shared/DEBUG_META.ts'
@@ -102,7 +103,7 @@ type Ranked = RankedError & {
 /**
  * One route of the app: the page at it, and the handler answering each method there.
  *
- * 19.1 — one file per method per route, so a route is a row and a method is a column, and 19.21's
+ * 19.1 — one file per method per route, so a route is a row and a method is a column, and 19.20's
  * "the most specific route answering the method" is a walk down the rows asking each column.
  */
 type RouteRow = {
@@ -196,7 +197,11 @@ export async function answerRequest(
     // 37.3 — THE MUX'S UPGRADE PASSES THE APP LANE as every request does (`muxUpgrade`).
     const admitted = muxAdmission(asked, request, app)
     if (admitted !== undefined) return admitted
-    if (asked.startsWith(`${ABIDE_ADDRESS}/`)) {
+    // 16.70 — a private handler is answered by the route table, below abide's own namespace.
+    if (
+        asked.startsWith(`${ABIDE_ADDRESS}/`) &&
+        !asked.startsWith(`${PRIVATE_HANDLERS_ADDRESS}/`)
+    ) {
         const answer = app.framework(asked, request)
         if (answer === undefined) return notFound()
         return readsOnly(request) ? answer : methodRefused(app, asked, READS)
@@ -222,7 +227,7 @@ export async function answerRequest(
             refuse(400, 'The address is not a valid path.'),
         )
 
-    // 19.21 — THE MOST SPECIFIC ROUTE ANSWERING THE METHOD, an `OPTIONS` asking about the method
+    // 19.20 — THE MOST SPECIFIC ROUTE ANSWERING THE METHOD, an `OPTIONS` asking about the method
     // its preflight names (16.24). A route that matches and answers some other method is held, so
     // an address nothing answers the method at is a 405 naming what is answered there (15.17).
     const preflight = request.method === 'OPTIONS'
@@ -271,7 +276,7 @@ export async function answerRequest(
     // above it, the root's having run already, and an error in it reaches that route's `onError`.
     const scope = currentRequestScope() as RequestScope
     scope.route =
-        found.handler === undefined ? found.route.pattern : found.handler.route
+        found.handler === undefined ? found.route.pattern : found.handler.scope
     scope.params = found.params
     const answer = found.route.answers.get(
         found.handler ?? (found.route.page as Ranked),

package/src/server/answerRpc.ts

@@ -16,7 +16,6 @@ import type { Gated } from '#shared/reactive/argsContract.ts'
 import { deadlineOf, heldGenerationOf } from '#shared/reactive/index.ts'
 import type { Defaults } from '#shared/reactive/parameterDefaults.ts'
 import { notFound, refuse } from '#shared/refuse.ts'
-import { routeOf } from '#shared/routePattern.ts'
 import type { Method, Rpc } from '#shared/rpc.ts'
 import { argsInURL } from '#shared/rpcRequest.ts'
 import { VERSION_HEADER } from '#shared/VERSION_HEADER.ts'
@@ -66,7 +65,14 @@ export type Mount = {
     address: string
     method: Method
     source: string
+    /** The handler file's name, or the private handler's binding. */
     name: string
+    /** What the source's module exports it as: `default` for a handler file. */
+    export: string
+    /** The route its hooks are filed at, which its rungs are read over (37.1, 16.72). */
+    scope: string
+    /** Whether it is a private handler, listed nowhere (16.71). */
+    private: boolean
     /** Whether a browser is handed a wrapper for it. 20.4. */
     ui: boolean
     /** Whether the command line lists it — the shell's listing and completion, never whether `call` reaches it. 20.3, 38.62. */
@@ -97,18 +103,15 @@ export type Mount = {
 
 /**
  * A row of the table the build wrote, with the import of the module its handler is declared in —
- * the file's server module, the one the route table loads too, so a page and a call reach one
- * handler.
+ * the handler file itself, or a private handler's `.abide` server module, the one the route table
+ * loads too, so a page and a call reach one handler.
  */
 export type MountRow = Mount & { load: () => Promise<Record<string, unknown>> }
 
 /** A handler's row, mounted: the handler imported and its args schema probed. */
 export type Mounted = Mount & {
-    method: Method
-    /** The route of the file declaring it, which its hooks are filed at (37.1, 37.2). */
-    route: string
     /**
-     * The rungs filed over `route`, read once at mount (16.14) — what an http call and a socket
+     * The rungs filed over `scope`, read once at mount (16.14) — what an http call and a socket
      * subscription to it both pass through (37.2, 18.26).
      */
     rungs: AppRung[]
@@ -148,12 +151,14 @@ export function mountedOwn(
         {
             address,
             method: 'GET',
-            route: '/',
             // The root's rungs run before routing (37.3), and nothing is filed below a route
             // of abide's own.
             rungs: [],
             source: '',
             name,
+            export: name,
+            scope: '/',
+            private: false,
             ui: false,
             cli: false,
             mcp: false,
@@ -188,20 +193,17 @@ export async function mountHandlers(
     const handlers = new Map<string, Mounted>()
     for (let at = 0; at < table.length; at += 1) {
         const mount = table[at] as Mount
-        const exported = (modules[at] as Record<string, unknown>)[mount.name]
+        const exported = (modules[at] as Record<string, unknown>)[mount.export]
         const handler = exported as Rpc<unknown, unknown> & Gated<unknown>
         const declared = argsDocumentOf(handler)
         // 16.9, 16.10 — the address `rpc.url` and `rpc.raw` build on, under the mount — and what a
         // page's render turns a call it made into the browser's request by (41.20).
         handler.address = underMount(mount.address)
-        // 23.19 — the route its address answers below, which is its mount's for a package's file,
-        // never the file's place on disk.
-        const route = routeOf(mount.address)
         handlers.set(handlerKey(mount.method, mount.address), {
             ...mount,
-            method: mount.method,
-            route,
-            rungs: rungsOver(route),
+            // 37.1, 16.72 — the route its file's hooks are filed at, which the build read off
+            // where the file answers (23.19's mount for a package's), never its place on disk.
+            rungs: rungsOver(mount.scope),
             handler,
             argsDocument: declared ?? (mount.args as Document | undefined),
             wireArgs: declared === undefined ? mount.args : undefined,
@@ -219,7 +221,7 @@ export function handlerKey(method: string, address: string): string {
  * The `Response` to a call of `found` made over http, `params` being what its route matched.
  *
  * `found` answers the request's method — or, for an `OPTIONS`, the method its preflight asks
- * about: which handler a request reaches is the route table's to say (19.21).
+ * about: which handler a request reaches is the route table's to say (19.20).
  */
 export async function answerRpc(
     found: Mounted,

package/src/server/appTree.ts

@@ -1,28 +1,35 @@
-// 23.14 — WHERE AN APP'S ADDRESSES ARE, read off the tree in one walk. Every directory below the root
-// is a segment of an address, and a `page.abide`, `layout.abide` or `error.abide` in it answers there;
-// a `server` or `public` directory is never one (23.15) — the first fences a graph and the second
-// holds files answered as authored, at the path of the directories above it. So an app is organized
-// by subject (`media/[id]/page.abide`, `media/server`) and the addresses follow.
+// 23.14 — WHERE AN APP'S ADDRESSES ARE, read off the tree in one walk. A file directly in a directory
+// below the root is an address — a page, a layout, an error page or a handler file — and nothing
+// else is there (23.22); a fence is never one (23.15): `server` fences a graph, `public` holds files
+// answered as authored at the path of the directories above it, and `lib` and `tests` hold the rest.
+// So listing a directory lists its routes.
 //
-// ONE WALK for the sources and the public files `abide build` copies and `abide dev` answers, and
-// the refusals (23.16, 23.17, 23.18) — and ONE SKIP RULE, `skipped`, for every walk of the tree,
-// beside `placeOf`, which answers the same question of one path.
+// ONE WALK for the sources, the handler files, the server and lib modules, and the public files
+// `abide build` copies and `abide dev` answers, and the refusals (23.16, 23.17, 23.18, 23.22) — and
+// ONE SKIP RULE, `skipped`, for every walk of the tree, beside `placeOf`, which answers the same
+// question of one path.
 //
 // A WALK RATHER THAN A GLOB: a glob descends `node_modules` and the build output before a filter
 // can drop them.
 
-import { type Dirent, readdirSync } from 'node:fs' // bun has no directory listing of its own
+import { type Dirent, existsSync, readdirSync } from 'node:fs' // bun has no directory listing or sync existence check of its own
 import { ABIDE_ADDRESS } from '#shared/ADDRESSES.ts'
 import {
+    LIB_DIRECTORY,
     PUBLIC_DIRECTORY,
     RESERVED_DIRECTORIES,
+    SERVER_DIRECTORY,
 } from '#shared/RESERVED_DIRECTORIES.ts'
-import { fileKind, routeOf, skipped } from '#shared/routePattern.ts'
+import { DIRECTORY_FILES, routeOf, skipped } from '#shared/routePattern.ts'
 
 /** What one walk of the app finds, every path relative to the root. */
-export type AppFiles = {
+type AppFiles = {
     /** Every `.abide`, in path order. */
     abide: string[]
+    /** Every handler file, in path order. */
+    handlers: string[]
+    /** Every module under a `server` or a `lib` directory, in path order — run as it is imported. */
+    modules: string[]
     /** Every file under a `public` directory, to the address it is answered at below the mount. */
     published: Map<string, string>
 }
@@ -35,7 +42,8 @@ const THROW: Refuse = (_path, message) => {
 }
 
 /**
- * The app's `.abide` sources and public files, refusing a tree 23.16, 23.17 or 23.18 forbids.
+ * The app's `.abide` sources, handler files, server and lib modules and public files, refusing a
+ * tree 23.16, 23.17, 23.18 or 23.22 forbids.
  *
  * `refuse` throws by default, which is the build's answer; `abide check` collects instead (38.33),
  * and the checker's route table ignores them, since a refused tree is the build's to report.
@@ -43,9 +51,19 @@ const THROW: Refuse = (_path, message) => {
  * A missing root is an app with nothing in it, not a fault.
  */
 export function appFiles(root: string, refuse: Refuse = THROW): AppFiles {
-    const files: AppFiles = { abide: [], published: new Map() }
-    walk(root, '', undefined, files, refuse)
+    const files: AppFiles = {
+        abide: [],
+        handlers: [],
+        modules: [],
+        published: new Map(),
+    }
+    // 23.22, 38.25 — a root that is its package's directory holds the package's own files beside its
+    // pages.
+    const packaged = existsSync(`${root}/package.json`)
+    walk(root, '', undefined, files, refuse, packaged)
     files.abide.sort()
+    files.handlers.sort()
+    files.modules.sort()
     return files
 }
 
@@ -57,6 +75,7 @@ function walk(
     reserved: { path: string; name: string } | undefined,
     files: AppFiles,
     refuse: Refuse,
+    packaged = false,
 ): void {
     let entries: Dirent[]
     try {
@@ -87,21 +106,49 @@ function walk(
             )
             continue
         }
-        if (path.endsWith('.abide')) files.abide.push(path)
+        const abide = path.endsWith('.abide')
+        if (abide) files.abide.push(path)
         if (reserved === undefined) {
+            if (!abide && !isModule(path)) {
+                if (packaged && relative === '' && !path.endsWith('.ts'))
+                    continue
+                refuse(
+                    path,
+                    `abide: ${path} is directly in an address directory, which holds pages, layouts, error pages and handler files alone. Move it into a lib directory beside it. RULEBOOK 23.22.`,
+                )
+                continue
+            }
+            if (!abide) files.handlers.push(path)
             // 23.17 — anything that could answer here would answer in abide's own namespace.
-            if (path.endsWith('.abide'))
-                refuseFrameworkRoute(routeOf(path), path, refuse)
-        } else if (fileKind(entry.name) !== 'component')
+            refuseFrameworkRoute(routeOf(path), path, refuse)
+        } else if (DIRECTORY_FILES.has(entry.name))
             refuse(
                 path,
-                `abide: ${path} is a ${entry.name} under the ${reserved.name} directory ${reserved.path}, where nothing has an address. RULEBOOK 23.18.`,
+                `abide: ${path} is under the ${reserved.name} directory ${reserved.path}, where nothing has an address, and ${entry.name} is a route's name. RULEBOOK 23.18.`,
             )
         else if (reserved.name === PUBLIC_DIRECTORY)
             files.published.set(path, publicAddress(path, reserved.path))
+        else if (
+            (reserved.name === SERVER_DIRECTORY ||
+                reserved.name === LIB_DIRECTORY) &&
+            isModule(path)
+        )
+            files.modules.push(path)
     }
 }
 
+/**
+ * Whether `path` names a module the app runs — neither a declaration nor a test: directly in an
+ * address directory, a handler file rather than a stray.
+ */
+function isModule(path: string): boolean {
+    return (
+        path.endsWith('.ts') &&
+        !path.endsWith('.d.ts') &&
+        !path.endsWith('.test.ts')
+    )
+}
+
 /** Refuses `source` where `route` lies in the framework's own namespace. 23.17. */
 export function refuseFrameworkRoute(
     route: string,
@@ -150,18 +197,21 @@ export function abideUnder(root: string): string[] {
 }
 
 /**
- * Whether a `.abide` lies anywhere under `root` — stopping at the first.
+ * Whether an app lies under `root`: a `.abide` anywhere or a handler file, stopping at the first.
  *
  * 38.26's question, asked of a root before anything is built from it, so asking it of a large tree
  * is as cheap as the tree allows.
  */
-export function holdsAbide(root: string): boolean {
-    return !abideFilesUnder(root, '').next().done
+export function holdsApp(root: string): boolean {
+    return !abideFilesUnder(root, '', true).next().done
 }
 
+// Every `.abide` under `directory` — and, where `handlers`, every handler file outside a fence.
 function* abideFilesUnder(
     directory: string,
     relative: string,
+    handlers = false,
+    fenced = false,
 ): Generator<string> {
     let entries: Dirent[]
     try {
@@ -173,7 +223,16 @@ function* abideFilesUnder(
         if (skipped(entry.name)) continue
         const path = `${relative}${entry.name}`
         if (entry.isDirectory())
-            yield* abideFilesUnder(`${directory}/${entry.name}`, `${path}/`)
-        else if (path.endsWith('.abide')) yield path
+            yield* abideFilesUnder(
+                `${directory}/${entry.name}`,
+                `${path}/`,
+                handlers,
+                fenced || RESERVED_DIRECTORIES.has(entry.name),
+            )
+        else if (
+            path.endsWith('.abide') ||
+            (handlers && !fenced && isModule(path))
+        )
+            yield path
     }
 }

package/src/server/commands.ts

@@ -33,7 +33,7 @@ type SourceCommands = Record<
     | 'dev'
     | 'build'
     | 'check'
-    | 'sync'
+    | 'routes'
     | 'compile'
     | 'bundle'
     | 'lsp',
@@ -151,9 +151,9 @@ function commandsOf(host: Host): Row[] {
             'check',
         ),
         fromSource(
-            'sync',
-            'write the types a .ts reads a .abide by, into .abide/types',
-            'sync',
+            'routes [--json]',
+            'every address the app answers, its file, and where each hook is filed',
+            'routes',
         ),
         fromSource(
             'compile',
@@ -227,6 +227,7 @@ function parsed(argv: string[]) {
             method: { type: 'string' },
             target: { type: 'string' },
             platforms: { type: 'string' },
+            json: { type: 'boolean' },
             help: { type: 'boolean', short: 'h' },
         },
         allowPositionals: true,

package/src/server/componentModules.d.ts

@@ -1,8 +1,7 @@
 // 35.4 — what a `.ts` holds where it imports a `.abide`: the component, called with its props to
 // bind them, answering the `Component` `render` takes (`abideModules`). A wildcard, so the props
 // are not checked here; a declaration in a module would be an augmentation, which takes no wildcard.
-// The names a `.abide` exports are typed by what 34.24 writes, which an app's tsconfig reaches
-// before this.
+// The component is all a `.abide` exports (34.17).
 declare module '*.abide' {
     const component: (
         props?: Record<string, unknown>,