@abide/abide 0.103.0 → 0.105.0

package/src/server/appTree.ts

@@ -5,22 +5,23 @@
 // So listing a directory lists its routes.
 //
 // 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.
+// `abide build` copies and `abide dev` answers, and the refusals (23.16, 23.17, 23.18, 23.22) — each
+// file what `placeOf` says of its path, so the walk and every reader of one path agree, and ONE SKIP
+// RULE, `skipped`, for every walk of the tree.
 //
 // A WALK RATHER THAN A GLOB: a glob descends `node_modules` and the build output before a filter
 // can drop them.
 
 import { type Dirent, existsSync, readdirSync } from 'node:fs' // bun has no directory listing or sync existence check of its own
+import type { Refusals } from '#compiler/Refusals.ts'
 import { ABIDE_ADDRESS } from '#shared/ADDRESSES.ts'
 import {
-    LIB_DIRECTORY,
+    HOLDS_SERVER,
     PUBLIC_DIRECTORY,
     RESERVED_DIRECTORIES,
     SERVER_DIRECTORY,
 } from '#shared/RESERVED_DIRECTORIES.ts'
-import { DIRECTORY_FILES, routeOf, skipped } from '#shared/routePattern.ts'
+import { DIRECTORY_FILES, placeOf, routeOf, skipped } from './placement.ts'
 
 /** What one walk of the app finds, every path relative to the root. */
 type AppFiles = {
@@ -28,29 +29,19 @@ type AppFiles = {
     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. */
+    /** Every module under a `server` or a `lib` directory, in path order — read for 37.13. */
     modules: string[]
     /** Every file under a `public` directory, to the address it is answered at below the mount. */
     published: Map<string, string>
 }
 
-/** Told of each thing the tree refuses, at the path relative to the root. */
-type Refuse = (path: string, message: string) => void
-
-const THROW: Refuse = (_path, message) => {
-    throw new Error(message)
-}
-
 /**
  * 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.
+ * tree 23.16, 23.17, 23.18 or 23.22 forbids into `refusals`, each at its path below the root.
  *
  * A missing root is an app with nothing in it, not a fault.
  */
-export function appFiles(root: string, refuse: Refuse = THROW): AppFiles {
+export function appFiles(root: string, refusals: Refusals): AppFiles {
     const files: AppFiles = {
         abide: [],
         handlers: [],
@@ -60,7 +51,7 @@ export function appFiles(root: string, refuse: Refuse = THROW): AppFiles {
     // 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)
+    walk(root, '', undefined, files, refusals, packaged)
     files.abide.sort()
     files.handlers.sort()
     files.modules.sort()
@@ -68,13 +59,14 @@ export function appFiles(root: string, refuse: Refuse = THROW): AppFiles {
 }
 
 // `reserved` is the nearest reserved directory above `relative` — its path and its name — or
-// `undefined` where none is.
+// `undefined` where none is: what 23.16 refuses is the nesting of two, which is a directory's shape
+// rather than a file's place.
 function walk(
     directory: string,
     relative: string,
     reserved: { path: string; name: string } | undefined,
     files: AppFiles,
-    refuse: Refuse,
+    refusals: Refusals,
     packaged = false,
 ): void {
     let entries: Dirent[]
@@ -90,10 +82,19 @@ function walk(
         if (entry.isDirectory()) {
             let within = reserved
             if (RESERVED_DIRECTORIES.has(entry.name)) {
-                if (reserved !== undefined)
-                    refuse(
+                // 23.16 — `server` nests in the fences that hold code.
+                if (
+                    reserved !== undefined &&
+                    !(
+                        entry.name === SERVER_DIRECTORY &&
+                        HOLDS_SERVER.has(reserved.name)
+                    )
+                )
+                    refusals.at(
                         path,
-                        `abide: ${path} is a ${entry.name} directory under the ${reserved.name} directory ${reserved.path}. RULEBOOK 23.16.`,
+                        new Error(
+                            `abide: ${path} is a ${entry.name} directory under the ${reserved.name} directory ${reserved.path}. RULEBOOK 23.16.`,
+                        ),
                     )
                 within = { path, name: entry.name }
             }
@@ -102,37 +103,43 @@ function walk(
                 `${path}/`,
                 within,
                 files,
-                refuse,
+                refusals,
             )
             continue
         }
         const abide = path.endsWith('.abide')
         if (abide) files.abide.push(path)
-        if (reserved === undefined) {
+        const place = placeOf(path)
+        if (place === 'address') {
             if (!abide && !isModule(path)) {
                 if (packaged && relative === '' && !path.endsWith('.ts'))
                     continue
-                refuse(
+                refusals.at(
                     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.`,
+                    new Error(
+                        `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.
-            refuseFrameworkRoute(routeOf(path), path, refuse)
-        } else if (DIRECTORY_FILES.has(entry.name))
-            refuse(
+            const framework = frameworkRouteRefusal(routeOf(path), path)
+            if (framework !== undefined) refusals.at(path, framework)
+            continue
+        }
+        // Any other place is a fence's, and the walk passed through it.
+        const fence = reserved as { path: string; name: string }
+        if (DIRECTORY_FILES.has(entry.name))
+            refusals.at(
                 path,
-                `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.`,
+                new Error(
+                    `abide: ${path} is under the ${fence.name} directory ${fence.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)
-        )
+        else if (place === 'public')
+            files.published.set(path, publicAddress(path, fence.path))
+        else if ((place === 'server' || place === 'lib') && isModule(path))
             files.modules.push(path)
     }
 }
@@ -149,17 +156,16 @@ function isModule(path: string): boolean {
     )
 }
 
-/** Refuses `source` where `route` lies in the framework's own namespace. 23.17. */
-export function refuseFrameworkRoute(
+/** The refusal of `source` where `route` lies in the framework's own namespace, or `undefined`. 23.17. */
+export function frameworkRouteRefusal(
     route: string,
     source: string,
-    refuse: Refuse = THROW,
-): void {
-    if (route === ABIDE_ADDRESS || route.startsWith(`${ABIDE_ADDRESS}/`))
-        refuse(
-            source,
-            `abide: ${source} answers at ${route}, which is under ${ABIDE_ADDRESS}, where abide's own addresses are. RULEBOOK 23.17.`,
-        )
+): Error | undefined {
+    return route === ABIDE_ADDRESS || route.startsWith(`${ABIDE_ADDRESS}/`)
+        ? new Error(
+              `abide: ${source} answers at ${route}, which is under ${ABIDE_ADDRESS}, where abide's own addresses are. RULEBOOK 23.17.`,
+          )
+        : undefined
 }
 
 // 36.11 — the directories above `public`, then the file's own path below it.
@@ -183,19 +189,6 @@ export function publishedUnder(
     return paths
 }
 
-/**
- * Every `.abide` under `root`, relative to it, in path order — the app's own, and none a
- * dependency ships.
- *
- * Refuses nothing: the language server lists them on every check, and a tree 23.16 forbids is the
- * build's to refuse (`appFiles`).
- */
-export function abideUnder(root: string): string[] {
-    const found: string[] = []
-    for (const path of abideFilesUnder(root, '')) found.push(path)
-    return found.sort()
-}
-
 /**
  * Whether an app lies under `root`: a `.abide` anywhere or a handler file, stopping at the first.
  *
@@ -203,15 +196,13 @@ export function abideUnder(root: string): string[] {
  * is as cheap as the tree allows.
  */
 export function holdsApp(root: string): boolean {
-    return !abideFilesUnder(root, '', true).next().done
+    return !appSourcesUnder(root, '').next().done
 }
 
-// Every `.abide` under `directory` — and, where `handlers`, every handler file outside a fence.
-function* abideFilesUnder(
+// Every `.abide` under `directory`, and every handler file — a module whose place is an address.
+function* appSourcesUnder(
     directory: string,
     relative: string,
-    handlers = false,
-    fenced = false,
 ): Generator<string> {
     let entries: Dirent[]
     try {
@@ -223,15 +214,10 @@ function* abideFilesUnder(
         if (skipped(entry.name)) continue
         const path = `${relative}${entry.name}`
         if (entry.isDirectory())
-            yield* abideFilesUnder(
-                `${directory}/${entry.name}`,
-                `${path}/`,
-                handlers,
-                fenced || RESERVED_DIRECTORIES.has(entry.name),
-            )
+            yield* appSourcesUnder(`${directory}/${entry.name}`, `${path}/`)
         else if (
             path.endsWith('.abide') ||
-            (handlers && !fenced && isModule(path))
+            (isModule(path) && placeOf(path) === 'address')
         )
             yield path
     }

package/src/server/claudeApi.ts

@@ -6,7 +6,7 @@
 // Every block of an assistant turn goes back as it came — a `thinking` block with its signature
 // included, which a turn continuing after a tool call is refused without.
 
-import { framedStream, framingPrefix } from '#shared/framing.ts'
+import { framedStream } from '#shared/framing.ts'
 import { refuse } from '#shared/refuse.ts'
 import type { AssistantEvent, Provider } from './assistant.ts'
 
@@ -112,10 +112,7 @@ export function claudeApi(config: ClaudeApiConfig): Provider {
                 const partials: string[] = []
                 const called: Block[] = []
                 let stop = 'end_turn'
-                for await (const chunk of framedStream(
-                    answered.body,
-                    framingPrefix('text/event-stream') as string,
-                )) {
+                for await (const chunk of framedStream(answered.body, 'sse')) {
                     const event = chunk as ApiEvent
                     switch (event.type) {
                         case 'message_start':

package/src/server/clientBundle.ts

@@ -0,0 +1,198 @@
+// 38.5, 38.16 — THE CLIENT BUNDLE, for both lanes that build one: `abide build`, which writes it to
+// disk for `abide start`, and `abide dev`'s worker, which holds it in memory. What decides what the
+// bundle IS — its plugins and their order, whether there is a page to boot, how a stylesheet's
+// addresses are written, the manifest — is here once, so dev resolves an address the way the
+// built app does by construction; a lane picks only a `mode`. And both answer it at
+// `/__abide/client/<name>` through `bundleServer`, differing in where a byte is read from and how
+// long a browser may keep it.
+
+import { CLIENT_ADDRESS } from '#shared/ADDRESSES.ts'
+import { abideModules, type Compilation, tablePath } from './abideModules.ts'
+import { appPlugins } from './appPlugins.ts'
+import { CLIENT_ENTRY } from './CLIENT_BUILD.ts'
+import { fenceServer } from './fenceServer.ts'
+import { type Manifest, manifestOf, NO_MANIFEST } from './manifestOf.ts'
+import { type Encoding, negotiateEncoding } from './negotiateEncoding.ts'
+
+/** One file the bundle produced: its bytes — a stylesheet's already rewritten — and its kind. */
+type BundledFile = {
+    bytes: Uint8Array<ArrayBuffer>
+    type: string
+    kind: Bun.BuildArtifact['kind']
+}
+
+/** A client bundle: every file it produced, by its name below `/__abide/client`, and its manifest. */
+export type ClientBundle = {
+    files: Map<string, BundledFile>
+    manifest: Manifest
+}
+
+/**
+ * The client bundle of the app at `root`, out of `compilation`, built for `mode`.
+ *
+ * `published` is each public file's source path to its address. `'build'` is 38.5's — minified and
+ * every name hashed; `'dev'` is 38.16's — unminified, the entry named by its source, with linked
+ * maps. A bundle that fails throws, its logs the error's.
+ *
+ * AN APP OF HANDLERS ALONE has no page to boot, and is bundled as nothing with no manifest.
+ */
+export async function clientBundle(
+    root: string,
+    compilation: Compilation,
+    published: Map<string, string>,
+    mode: 'build' | 'dev',
+): Promise<ClientBundle> {
+    const bundle: ClientBundle = { files: new Map(), manifest: NO_MANIFEST }
+    // A page among what compiled: the compiler writes the entry only where there is one to boot.
+    if (compilation.tables[`${CLIENT_ENTRY}.ts`] === undefined) return bundle
+    const built = await Bun.build({
+        // The entry is a table the plugin serves (`abideModules`), below the root.
+        entrypoints: [tablePath(root, `${CLIENT_ENTRY}.ts`)],
+        // The app's own root, because `Bun.build` opens the entry's directory otherwise, and the
+        // tables' is not on disk to open.
+        root,
+        // 16.28, 16.29 — the browser's view of the server: a `<script server>` is its stand-ins and a
+        // `server/` module refuses — FENCED FIRST, before the plugin that would serve the module. 38.43
+        // — then the app's own, as `bunfig.toml` declares them.
+        plugins: [
+            fenceServer(root, compilation.mounted),
+            abideModules(root, compilation),
+            ...(await appPlugins(root)),
+        ],
+        target: 'browser',
+        format: 'esm',
+        // So a destination's markup and bindings stay in the chunk its own route loads (30.11)
+        // rather than landing in the entry every page pays for.
+        splitting: true,
+        metafile: true,
+        // 36.15 — a stylesheet's `url('/fonts/…')` is the public file's address, not a path here,
+        // and `Bun.build` reads a leading `/` as a path on this disk and fails on it not being
+        // there. The list is the files that exist rather than every `/…`: a URL naming nothing the
+        // app serves is still worth a build error.
+        external: [...published.values()],
+        throw: false,
+        ...(mode === 'build'
+            ? {
+                  // 38.5 — MINIFIED, and EVERY NAME HASHED, the entry's included: chunks and assets are
+                  // already `[name]-[hash]` by default and the entry is not, which left the one file
+                  // every page loads served for a year under a name the next deploy writes different
+                  // bytes to. The manifest is how the document learns what the entry was called.
+                  //
+                  // NAMES KEPT, because a class's name is what an error reads to say what it was
+                  // handed (`canonicalKey`), and a production error naming `a e` is one nobody can
+                  // act on. It is free where it is paid: the JS the docs app's `/values` sends is
+                  // 25 600 bytes brotli with the names and without, against 31 900 unminified.
+                  minify: {
+                      whitespace: true,
+                      syntax: true,
+                      identifiers: true,
+                      keepNames: true,
+                  },
+                  naming: { entry: '[name]-[hash].[ext]' },
+              }
+            : {
+                  // 38.97 — a debugger in the browser reads the `.abide` (`withAbideSources`).
+                  sourcemap: 'linked' as const,
+                  // 38.16 — the entry named by its source, so what a browser loads and what a stack
+                  // trace names are the module the author wrote. A dev chunk that changed has to be
+                  // fetched again, and a name that changes with it is a cache the reload cannot clear.
+                  naming: {
+                      entry: '[name].[ext]',
+                      chunk: '[name]-[hash].[ext]',
+                      asset: '[name]-[hash].[ext]',
+                  },
+              }),
+    })
+    // THROWN RATHER THAN LOGGED: a build that emitted server modules and no bundle is an app that
+    // serves every page dead — the markup right and nothing wired — which is the one failure a
+    // reader cannot see. Dev catches it (38.17); the build stops on it.
+    if (!built.success)
+        throw new AggregateError(
+            built.logs,
+            `abide ${mode}: the client bundle failed`,
+        )
+    // The outputs are independent, so they are read at once rather than one after another.
+    const read = await Promise.all(
+        built.outputs.map((output) => output.arrayBuffer()),
+    )
+    for (let index = 0; index < built.outputs.length; index += 1) {
+        const output = built.outputs[index] as Bun.BuildArtifact
+        const name = output.path.slice(output.path.lastIndexOf('/') + 1)
+        let bytes = new Uint8Array(read[index] as ArrayBuffer)
+        if (name.endsWith('.css'))
+            bytes = new TextEncoder().encode(
+                stylesheetUnderMount(new TextDecoder().decode(bytes)),
+            )
+        bundle.files.set(name, { bytes, type: output.type, kind: output.kind })
+    }
+    bundle.manifest = manifestOf(built.metafile as Bun.BuildMetafile, root)
+    return bundle
+}
+
+// From the bundle's own directory up to the app's root: `../../` below `/__abide/client`.
+const UP_TO_ROOT = '../'.repeat(CLIENT_ADDRESS.split('/').length - 1)
+
+/**
+ * A built stylesheet with every root-absolute `url()` written relative to the bundle's directory.
+ *
+ * 16.10, 36.15 — THE SAME MECHANISM AS THE HANDLER WRAPPERS: the address is written relative to
+ * where the bundle is served and the browser resolves it against the sheet, so one build serves
+ * at the root and below a mount. What survives the build as `url(/…)` is a public file's address
+ * (the `external` list above), and the browser would resolve it against the origin. `//` is
+ * another host's.
+ */
+function stylesheetUnderMount(css: string): string {
+    return css.replace(
+        /url\((["']?)\/(?!\/)/g,
+        (_whole, quote: string) => `url(${quote}${UP_TO_ROOT}`,
+    )
+}
+
+/** A bundle file as it is answered: its type, its bytes, and each precompressed copy of them. */
+export type ServedFile = {
+    type: string
+    body: () => BodyInit
+    encoded: Partial<Record<Encoding, () => BodyInit>>
+}
+
+/**
+ * Answers `/__abide/client/<name>` out of `files`, each with `cacheControl`; `undefined` for any
+ * other address, and for a name the bundle does not hold.
+ *
+ * THE BUNDLE, ENUMERATED RATHER THAN RESOLVED. A request names a file in this set or it names
+ * nothing — there is no path to normalize, so `..` is not a case that has to be got right, and what
+ * is servable is exactly what the bundle produced.
+ */
+export function bundleServer(
+    files: Map<string, ServedFile>,
+    cacheControl: string,
+): (pathname: string, request: Request) => Response | undefined {
+    // Each file's encodings listed once, rather than on every request for it.
+    const offeredOf = new Map<string, Encoding[]>()
+    for (const [name, file] of files)
+        offeredOf.set(name, Object.keys(file.encoded) as Encoding[])
+    return (pathname, request) => {
+        if (!pathname.startsWith(`${CLIENT_ADDRESS}/`)) return undefined
+        const name = pathname.slice(CLIENT_ADDRESS.length + 1)
+        const file = files.get(name)
+        if (file === undefined) return undefined
+        const headers: Record<string, string> = {
+            'cache-control': cacheControl,
+            'content-type': file.type,
+        }
+        const offered = offeredOf.get(name) as Encoding[]
+        if (offered.length === 0) return new Response(file.body(), { headers })
+        headers.vary = 'accept-encoding'
+        // 38.29 — the precompressed copy where the request takes its encoding.
+        const encoding = negotiateEncoding(
+            request.headers.get('accept-encoding'),
+            offered,
+        )
+        const encoded =
+            encoding === undefined ? undefined : file.encoded[encoding]
+        if (encoding === undefined || encoded === undefined)
+            return new Response(file.body(), { headers })
+        headers['content-encoding'] = encoding
+        return new Response(encoded(), { headers })
+    }
+}

package/src/server/coerceArgs.ts

@@ -7,8 +7,8 @@
 // has declared no types, and its args stay the text they arrived as.
 
 import { numberFromText } from '#shared/numberFromText.ts'
+import { bareName } from '#shared/queryText.ts'
 import { type Gated, gateOf } from '#shared/reactive/argsContract.ts'
-import { bareName } from '#shared/rpcRequest.ts'
 
 export type Document = {
     type?: string | string[]