@vesk/adapter 0.2.67 → 0.2.69

package/dist/server-only-plugin.js

@@ -0,0 +1,233 @@
+/**
+ * esbuild plugin that keeps server-only packages out of a browser bundle.
+ *
+ * Why a plugin and not a filter on the chunk's own import list: by the time the
+ * bundler runs, the chunk's direct imports have already been merged, and the
+ * offender is almost never one of them. The shape that actually leaks is
+ * `page.vsk → app/db.ts → slintorm → pg`, and only the bundler's transitive
+ * resolution sees `pg` at all. Filtering the import list would have caught
+ * nothing.
+ *
+ * A resolved server-only package is replaced with a generated module whose
+ * every export is a Proxy that throws. A stub and not a deletion, because the
+ * binding is referenced by code that survives into the chunk: dropping it would
+ * produce `X is not defined` at hydration, pointing nowhere near the import that
+ * caused it. The export names come from the importing statement, read off the
+ * importer's own source, so the generated module declares exactly what the
+ * importer asked for and nothing is silently undefined.
+ *
+ * TCP drivers are NOT stubbed. A browser bundle cannot contain one under any
+ * circumstances, so a stub would ship a page that looks fine and fails at the
+ * first query; they are reported and left for esbuild to reject.
+ */
+import { readFileSync } from 'node:fs';
+import { parse } from '@vesk/compiler/src/parser';
+import { classifySpecifier } from '@vesk/adapter/src/server-only';
+const STUB_NAMESPACE = 'vesk-server-only';
+let stubCounter = 0;
+/**
+ * The export names one file asks for from `specifier`.
+ *
+ * Read from the importer's own source rather than guessed: a stub declaring the
+ * wrong set of names is either an unresolvable-import build failure or, worse,
+ * a silently undefined binding.
+ */
+export function importedNamesFor(code, specifier) {
+    let ast;
+    try {
+        ast = parse(code);
+    }
+    catch {
+        return [];
+    }
+    const names = [];
+    // The vsk parser flattens a module specifier to a bare string, while the TS
+    // parser keeps it as `{ value }`. Both shapes occur in practice.
+    const sourceOf = (node) => {
+        const src = node.source;
+        if (typeof src === 'string')
+            return src;
+        const v = src?.value;
+        return typeof v === 'string' ? v : null;
+    };
+    for (const node of ast.body ?? []) {
+        if (node?.type === 'ImportDeclaration') {
+            if (sourceOf(node) !== specifier)
+                continue;
+            for (const spec of node.specifiers ?? []) {
+                // `import * as x` has no names to declare — the namespace is made of
+                // whatever the importer reaches for, and each of those reads is what
+                // throws. Declaring guesses would be worse than declaring none.
+                if (spec.type === 'ImportNamespaceSpecifier')
+                    continue;
+                const local = spec.local?.name;
+                if (typeof local === 'string' && !names.includes(local))
+                    names.push(local);
+            }
+            continue;
+        }
+        if (node?.type === 'ExportAllDeclaration' || node?.type === 'ExportNamedDeclaration') {
+            if (sourceOf(node) !== specifier)
+                continue;
+            // `export * from 'pg'` names nothing at all, and `export { Client } from
+            // 'pg'` names only what this barrel happens to forward. Either way the
+            // honest stub declares what is written here.
+            for (const spec of node.specifiers ?? []) {
+                const imported = spec.imported?.name ?? spec.imported?.value ?? spec.local?.name;
+                if (typeof imported === 'string' && !names.includes(imported))
+                    names.push(imported);
+            }
+        }
+    }
+    return names;
+}
+/** The shared throwing-proxy factory, emitted once per stubbed package. */
+export function stubFactorySource(specifier) {
+    const template = '"$1" comes from "$0", which is server-only. It reached the browser bundle because a ' +
+        'component (or a module one imports) imported it — component code runs in the browser, ' +
+        'where this module cannot work. Move the server-only work into an API route ' +
+        '(app/api/**/route.ts) or a server action and call it over HTTP, or import the ' +
+        'edge/browser-safe entry if the package ships one.';
+    return [
+        'function __vesk_stub(binding) {',
+        '  var message = ' + JSON.stringify(template) + ';',
+        '  message = message.replace("$0", ' + JSON.stringify(specifier) + ').replace("$1", String(binding));',
+        '  var thrower = function () { throw Object.assign(new Error(message), { __veskServerOnly: ' + JSON.stringify(specifier) + ' }); };',
+        '  return new Proxy(function () {}, {',
+        '    get: thrower,',
+        '    apply: thrower,',
+        '    construct: thrower',
+        '  });',
+        '}',
+    ].join('\n');
+}
+/**
+ * Is `name` used at module-evaluation position — i.e. NOT inside a function?
+ *
+ * This is the difference between a stub that is fine and one that is a trap.
+ *
+ *   export function allRows() { return orm.getAll(); }   // never runs in the
+ *                                                      // browser → stub is fine
+ *   export const orm = createORM({});                   // runs the moment the
+ *                                                      // chunk evaluates
+ *
+ * The second form cannot be rescued by any amount of stubbing: the browser
+ * evaluates it while loading the chunk, so the page dies before a single
+ * component exists. A build error is the honest answer there, and it is
+ * decidable from the source alone — no types, no dataflow.
+ *
+ * Non-computed member keys (`obj.orm`) and object/class property keys are not
+ * references, for the same reason the reactivity diagnostics skip them.
+ */
+export function referencedAtTopLevel(code, name) {
+    let ast;
+    try {
+        ast = parse(code);
+    }
+    catch {
+        // Cannot prove it either way; assume the dangerous case so the build is
+        // never softened by an unparseable file.
+        return true;
+    }
+    let found = false;
+    const FUNCTION_TYPES = new Set([
+        'FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression',
+        'ClassMethod', 'ObjectMethod', 'ClassDeclaration', 'ClassExpression',
+    ]);
+    /** Never carries a reference: AST bookkeeping and source offsets. */
+    const SKIP_KEYS = new Set(['type', 'start', 'end', 'loc', 'range', 'raw', 'regex']);
+    /** A re-export's module specifier and specifier list name bindings, not use them. */
+    const SKIP_EXPORT_NAMED_KEYS = new Set([...SKIP_KEYS, 'source', 'specifiers', 'exportKind', 'attributes']);
+    const visit = (node, parentKey, fnDepth) => {
+        if (found || node === null || typeof node !== 'object')
+            return;
+        if (Array.isArray(node)) {
+            for (const child of node)
+                visit(child, parentKey, fnDepth);
+            return;
+        }
+        const n = node;
+        if (n.type === 'MemberExpression' || n.type === 'Property' || n.type === 'PropertyDefinition' || n.type === 'MethodDefinition') {
+            const prop = (n.property ?? n.key);
+            // `obj.orm` and `{ orm: 1 }` name a field, not the binding. `[orm]` does.
+            if (prop && typeof prop === 'object' && prop.name === name && n.computed !== true)
+                return;
+        }
+        // An import NAMES the binding without USING it. Walking into the specifiers
+        // made every imported name look top-level-referenced, which would have
+        // turned every server-only import into a build error.
+        if (n.type === 'ImportDeclaration' || n.type === 'ExportAllDeclaration' || n.type === 'ImportExpression')
+            return;
+        if (n.type === 'Identifier' && n.name === name) {
+            if (parentKey === 'local' || parentKey === 'id' || parentKey === 'params' || parentKey === 'key')
+                return;
+            if (fnDepth === 0)
+                found = true;
+            return;
+        }
+        // `export const orm = createORM({})` carries its USE inside the export
+        // declaration, so only the specifier list and module specifier are skipped.
+        const skip = n.type === 'ExportNamedDeclaration' ? SKIP_EXPORT_NAMED_KEYS : SKIP_KEYS;
+        const nextDepth = FUNCTION_TYPES.has(String(n.type)) ? fnDepth + 1 : fnDepth;
+        for (const [key, value] of Object.entries(n)) {
+            if (skip.has(key))
+                continue;
+            visit(value, key, nextDepth);
+        }
+    };
+    visit(ast.body, undefined, 0);
+    return found;
+}
+export function serverOnlyPlugin(options = {}) {
+    /** Generated stub id -> module source. */
+    const stubs = new Map();
+    return {
+        name: 'vesk-server-only',
+        setup(build) {
+            build.onResolve({ filter: /.*/ }, args => {
+                const kind = classifySpecifier(args.path);
+                if (!kind)
+                    return null;
+                if (kind === 'tcp-driver') {
+                    options.onDriver?.({ specifier: args.path, importer: args.importer });
+                    // Returning null lets esbuild resolve it normally, which in a browser
+                    // bundle fails with its own "Could not resolve" error. Substituting a
+                    // stub here would ship a page that looks fine and dies on first use.
+                    return null;
+                }
+                let names = [];
+                let importerCode = '';
+                try {
+                    importerCode = readFileSync(args.importer, 'utf-8');
+                    names = importedNamesFor(importerCode, args.path);
+                }
+                catch {
+                    /* importer unreadable — emit a default-only stub rather than crash */
+                }
+                // A stub only works if the browser never reaches the binding. A
+                // module-evaluation-position use means the browser reaches it while
+                // loading the chunk, before any component exists, so no stub can help
+                // and the build has to say so rather than ship a page that dies on load.
+                const eager = names.filter(n => referencedAtTopLevel(importerCode, n));
+                if (eager.length > 0) {
+                    options.onEager?.({ specifier: args.path, bindings: eager, importer: args.importer });
+                    return null;
+                }
+                const id = `vesk-stub-${stubCounter++}`;
+                stubs.set(id, [
+                    stubFactorySource(args.path),
+                    'export default __vesk_stub("default");',
+                    ...names.map(n => `export const ${n} = __vesk_stub(${JSON.stringify(n)});`),
+                ].join('\n'));
+                for (const binding of names) {
+                    options.onStub?.({ specifier: args.path, binding, importer: args.importer });
+                }
+                return { path: id, namespace: STUB_NAMESPACE };
+            });
+            build.onLoad({ filter: /.*/, namespace: STUB_NAMESPACE }, args => ({
+                contents: stubs.get(args.path) ?? stubFactorySource('unknown'),
+                loader: 'js',
+            }));
+        },
+    };
+}

package/dist/server-only.d.ts

@@ -0,0 +1,99 @@
+/**
+ * What may not cross the server/client line, and what may not be deployed to a
+ * socketless runtime.
+ *
+ * Vesk splits a `.vsk` file into two graphs without being told which side a
+ * given import belongs to: a page is *also* a client component, so the module
+ * a page imports for its `load()` ends up in the browser chunk closure. When
+ * that module reaches for a database driver, the browser bundler dutifully
+ * inlines the driver's Node implementation — `node:net`, `node:tls`,
+ * `node:stream` — and the client bundle grows by hundreds of kilobytes of code
+ * that cannot run and is never called.
+ *
+ * So the separation has to be enforced by the build rather than inferred from
+ * usage. Two distinct rules, because the failure modes are different:
+ *
+ * - **Server-only packages** (`slintorm`, `@vesk/adapter`) may legitimately be
+ *   imported by a page that only touches them during SSR. The import is removed
+ *   from the browser chunk and every binding it declared becomes a throwing
+ *   stub, so a build stays possible but a real client-side use fails loudly and
+ *   names itself. `--strict` turns the warning into a build failure.
+ * - **TCP-only drivers** (`pg`, `mysql2`, `mongodb`, `node:sqlite`) cannot run
+ *   anywhere a socket cannot be opened — not in a browser, and not on any edge
+ *   runtime. In an edge-targeted build that is not a degradation, it is a
+ *   guaranteed crash at the first query, so it is a hard build error with no
+ *   opt-out: the alternative is discovering it in a deployment log.
+ *
+ * AST-only throughout. No text scanning — see the module rules.
+ */
+export type ServerOnlyKind = 'server-only-package' | 'tcp-driver';
+/**
+ * Classify a bare import specifier. Returns null for anything that is fine on
+ * the client — including a subpath of a listed package that is itself a
+ * browser entry.
+ */
+export declare function classifySpecifier(spec: string): ServerOnlyKind | null;
+export declare function isServerOnlySpecifier(spec: string): boolean;
+export declare function isTcpDriverSpecifier(spec: string): boolean;
+/**
+ * Throwing stand-ins for the bindings a server-only import declared.
+ *
+ * A stub, not a removal: the binding is referenced by code that survives into
+ * the chunk, so dropping it would produce `X is not defined` at hydration — a
+ * ReferenceError pointing nowhere near the import that caused it. A Proxy that
+ * throws on any use keeps `typeof` truthful (so a feature check does not blow
+ * up during module evaluation) while failing at the exact call site with a
+ * message that names the package, the binding and the fix.
+ */
+export declare function serverOnlyStubs(notes: Array<{
+    specifier: string;
+    binding: string;
+}>): string;
+/**
+ * Same stubs, discovered by scanning source rather than from a recorded list —
+ * used by the edge gate, which sees `.vsk` sources before anything is compiled.
+ */
+export declare function serverOnlyImportStubs(code: string, classify?: (spec: string) => ServerOnlyKind | null): string;
+export interface ServerOnlyViolation {
+    kind: ServerOnlyKind;
+    specifier: string;
+    /** Absolute path of the file the import was written in. */
+    file: string;
+    /** 1-based line number when it could be determined. */
+    line: number | null;
+    /** What to do about it. */
+    remedy: string;
+}
+/**
+ * Every server-only / TCP-only import written across a set of files.
+ *
+ * Walks the whole set rather than a module graph, because the file that names
+ * the driver is rarely the file that matters: `app/db.ts` importing `slintorm`
+ * is the normal shape, and it is the *component* that transitively pulls it in.
+ * Callers pair this with their own reachability information.
+ */
+export declare function scanServerOnlyImports(files: Array<{
+    path: string;
+    code: string;
+}>): ServerOnlyViolation[];
+/**
+ * The build-time error for an edge-targeted build that imports a TCP driver.
+ *
+ * No opt-out by design: there is no configuration of an edge target under which
+ * a TCP driver works, so the only question is whether the author finds out here
+ * or from a production log.
+ */
+export declare function edgeDriverBuildError(violations: ServerOnlyViolation[]): Error;
+export declare function isSocketlessTarget(platform: string | null | undefined, target: string | null | undefined): boolean;
+/** Every app source file under `dir`, recursively. */
+export declare function collectAppSources(dir: string, out?: string[]): string[];
+/**
+ * TCP-driver imports anywhere under the app directory.
+ *
+ * Scans the whole tree rather than the client chunk closure: the driver is named
+ * in `app/db.ts`, which is correct, and what is wrong is that anything under it
+ * is reachable from a socketless runtime. Either way the build has to stop, and
+ * it has to stop before minutes of bundling have been spent.
+ */
+export declare function tcpDriverViolations(appDir: string): ServerOnlyViolation[];
+//# sourceMappingURL=server-only.d.ts.map

package/dist/server-only.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-only.d.ts","sourceRoot":"","sources":["../src/server-only.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAsCH,MAAM,MAAM,cAAc,GAAG,qBAAqB,GAAG,YAAY,CAAC;AAElE;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAMrE;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,MAAM,CAkB5F;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,cAAc,GAAG,IAAwB,GAAG,MAAM,CAoBjI;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB;AAWD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAC3C,mBAAmB,EAAE,CA8BvB;AAYD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,mBAAmB,EAAE,GAAG,KAAK,CAU7E;AAYD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAGlH;AAMD,sDAAsD;AACtD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CAwB3E;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAUzE"}

package/dist/server-only.js

@@ -0,0 +1,283 @@
+/**
+ * What may not cross the server/client line, and what may not be deployed to a
+ * socketless runtime.
+ *
+ * Vesk splits a `.vsk` file into two graphs without being told which side a
+ * given import belongs to: a page is *also* a client component, so the module
+ * a page imports for its `load()` ends up in the browser chunk closure. When
+ * that module reaches for a database driver, the browser bundler dutifully
+ * inlines the driver's Node implementation — `node:net`, `node:tls`,
+ * `node:stream` — and the client bundle grows by hundreds of kilobytes of code
+ * that cannot run and is never called.
+ *
+ * So the separation has to be enforced by the build rather than inferred from
+ * usage. Two distinct rules, because the failure modes are different:
+ *
+ * - **Server-only packages** (`slintorm`, `@vesk/adapter`) may legitimately be
+ *   imported by a page that only touches them during SSR. The import is removed
+ *   from the browser chunk and every binding it declared becomes a throwing
+ *   stub, so a build stays possible but a real client-side use fails loudly and
+ *   names itself. `--strict` turns the warning into a build failure.
+ * - **TCP-only drivers** (`pg`, `mysql2`, `mongodb`, `node:sqlite`) cannot run
+ *   anywhere a socket cannot be opened — not in a browser, and not on any edge
+ *   runtime. In an edge-targeted build that is not a degradation, it is a
+ *   guaranteed crash at the first query, so it is a hard build error with no
+ *   opt-out: the alternative is discovering it in a deployment log.
+ *
+ * AST-only throughout. No text scanning — see the module rules.
+ */
+import { parse } from '@vesk/compiler/src/parser';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Packages that are server-side by construction.
+ *
+ * `slintorm` is here for a specific reason, and it is not a slur on the ORM:
+ * `slintorm` ships an edge-safe entry (`slintorm/edge` and `slintorm/browser`,
+ * which resolve to a bundle with no Node built-ins anywhere in its graph), and
+ * that entry is deliberately NOT matched. Only the bare `slintorm` specifier is
+ * server-only, because only that one pulls in the driver dispatch and the
+ * `node:fs` schema generator.
+ */
+const SERVER_ONLY_EXACT = new Set([
+    'slintorm',
+    '@vesk/adapter',
+]);
+/**
+ * Drivers that need a real socket. Anything here is a hard error in an
+ * edge-targeted build.
+ *
+ * `node:sqlite` is a Node built-in that appears only as an import specifier, so
+ * it is listed here alongside the packages for uniformity; it cannot appear in
+ * a browser chunk because the bundler already fails on it.
+ */
+const TCP_DRIVERS = new Set([
+    'pg',
+    'mysql2',
+    'mongodb',
+    'node:sqlite',
+    'node:net',
+    'node:tls',
+]);
+/**
+ * Classify a bare import specifier. Returns null for anything that is fine on
+ * the client — including a subpath of a listed package that is itself a
+ * browser entry.
+ */
+export function classifySpecifier(spec) {
+    if (typeof spec !== 'string' || spec.length === 0)
+        return null;
+    if (TCP_DRIVERS.has(spec))
+        return 'tcp-driver';
+    if (spec.startsWith('node:'))
+        return 'tcp-driver';
+    if (SERVER_ONLY_EXACT.has(spec))
+        return 'server-only-package';
+    return null;
+}
+export function isServerOnlySpecifier(spec) {
+    return classifySpecifier(spec) === 'server-only-package';
+}
+export function isTcpDriverSpecifier(spec) {
+    return classifySpecifier(spec) === 'tcp-driver';
+}
+/**
+ * Throwing stand-ins for the bindings a server-only import declared.
+ *
+ * A stub, not a removal: the binding is referenced by code that survives into
+ * the chunk, so dropping it would produce `X is not defined` at hydration — a
+ * ReferenceError pointing nowhere near the import that caused it. A Proxy that
+ * throws on any use keeps `typeof` truthful (so a feature check does not blow
+ * up during module evaluation) while failing at the exact call site with a
+ * message that names the package, the binding and the fix.
+ */
+export function serverOnlyStubs(notes) {
+    if (notes.length === 0)
+        return '';
+    const lines = notes.map(({ binding, specifier }) => {
+        const message = `"${binding}" comes from "${specifier}", which is server-only. It reached the client bundle ` +
+            'because a component (or a module one imports) imported it — component code runs in the ' +
+            'browser, where this module cannot work. Move the server-only work into an API route ' +
+            '(app/api/**/route.ts) or a server action and call it over HTTP, or import the ' +
+            'edge/browser-safe entry if the package ships one.';
+        const thrower = `throw Object.assign(new Error(${JSON.stringify(message)}), { __veskServerOnly: ${JSON.stringify(specifier)} })`;
+        return (`const ${binding} = new Proxy(function () {}, { ` +
+            `get: function () { ${thrower}; }, ` +
+            `apply: function () { ${thrower}; }, ` +
+            `construct: function () { ${thrower}; } });`);
+    });
+    return lines.join('\n') + '\n\n';
+}
+/**
+ * Same stubs, discovered by scanning source rather than from a recorded list —
+ * used by the edge gate, which sees `.vsk` sources before anything is compiled.
+ */
+export function serverOnlyImportStubs(code, classify = classifySpecifier) {
+    let ast;
+    try {
+        ast = parse(code);
+    }
+    catch {
+        return '';
+    }
+    const notes = [];
+    for (const node of ast.body ?? []) {
+        // Only ImportDeclaration here, unlike the scanner above: a re-export binds
+        // no local name, so there is nothing to replace — the scan still reports it.
+        if (node?.type !== 'ImportDeclaration')
+            continue;
+        const src = node.source?.value;
+        if (typeof src !== 'string' || classify(src) !== 'server-only-package')
+            continue;
+        for (const spec of node.specifiers ?? []) {
+            const local = spec?.local?.name;
+            if (typeof local === 'string')
+                notes.push({ specifier: src, binding: local });
+        }
+    }
+    return serverOnlyStubs(notes);
+}
+const REMEDY = {
+    'server-only-package': 'import it from an API route (app/api/**/route.ts) or a server action instead of a component, ' +
+        'or use the package\'s browser/edge entry point if it ships one.',
+    'tcp-driver': 'this driver opens a TCP socket, which no edge runtime provides. Use the driver\'s HTTP/HTTPS ' +
+        'transport (for SlintORM: `driver: "postgrest"`), or build for a Node target.',
+};
+/**
+ * Every server-only / TCP-only import written across a set of files.
+ *
+ * Walks the whole set rather than a module graph, because the file that names
+ * the driver is rarely the file that matters: `app/db.ts` importing `slintorm`
+ * is the normal shape, and it is the *component* that transitively pulls it in.
+ * Callers pair this with their own reachability information.
+ */
+export function scanServerOnlyImports(files) {
+    const out = [];
+    for (const file of files) {
+        let ast;
+        try {
+            ast = parse(file.code);
+        }
+        catch {
+            continue;
+        }
+        for (const node of ast.body ?? []) {
+            // Re-exports count. `export { Client } from 'pg'` is how a barrel file
+            // forwards a driver, and it is exactly the shape that slips past a scan
+            // looking only at imports.
+            if (node?.type !== 'ImportDeclaration'
+                && node?.type !== 'ExportNamedDeclaration'
+                && node?.type !== 'ExportAllDeclaration')
+                continue;
+            const spec = node.source?.value;
+            if (typeof spec !== 'string')
+                continue;
+            const kind = classifySpecifier(spec);
+            if (!kind)
+                continue;
+            out.push({
+                kind,
+                specifier: spec,
+                file: file.path,
+                line: lineOf(file.code, node.start),
+                remedy: REMEDY[kind],
+            });
+        }
+    }
+    return out;
+}
+/** 1-based line of a character offset. */
+function lineOf(code, offset) {
+    if (typeof offset !== 'number' || offset < 0 || offset > code.length)
+        return null;
+    let line = 1;
+    for (let i = 0; i < offset; i++) {
+        if (code.charCodeAt(i) === 10)
+            line++;
+    }
+    return line;
+}
+/**
+ * The build-time error for an edge-targeted build that imports a TCP driver.
+ *
+ * No opt-out by design: there is no configuration of an edge target under which
+ * a TCP driver works, so the only question is whether the author finds out here
+ * or from a production log.
+ */
+export function edgeDriverBuildError(violations) {
+    const detail = violations
+        .map(v => `  ${v.file}${v.line ? `:${v.line}` : ''} — import "${v.specifier}"\n    ${v.remedy}`)
+        .join('\n');
+    return new Error(`[vesk] edge-targeted build cannot include a TCP-only driver (${violations.length} found).\n` +
+        `${detail}\n\n` +
+        'This was a build error rather than a runtime one because an edge runtime has no socket: ' +
+        'the deployed function would fail on its first query.');
+}
+/**
+ * Platforms whose deployed functions have no socket.
+ *
+ * Derived from `platform-deploy.ts`'s `nodeBuiltins: false` shells — those are
+ * exactly the ones bundled with empty-Node-builtin stubs, which is the same
+ * reason they cannot open a TCP connection. `vercel`/`netlify`/`aws` run Node
+ * functions and are deliberately absent.
+ */
+const SOCKETLESS_PLATFORMS = new Set(['edge', 'cloudflare', 'deno', 'coxmos']);
+export function isSocketlessTarget(platform, target) {
+    if (target === 'edge')
+        return true;
+    return typeof platform === 'string' && SOCKETLESS_PLATFORMS.has(platform);
+}
+const SOURCE_EXTENSIONS = ['.vsk', '.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
+const SKIPPED_DIRS = new Set(['node_modules', '.vesk', '.git', 'dist', '.next', '.output', 'coverage']);
+/** Every app source file under `dir`, recursively. */
+export function collectAppSources(dir, out = []) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        if (SKIPPED_DIRS.has(entry) || entry.startsWith('.'))
+            continue;
+        const full = join(dir, entry);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory())
+            collectAppSources(full, out);
+        else if (st.isFile()) {
+            const dot = entry.lastIndexOf('.');
+            if (dot === -1)
+                continue;
+            if (SOURCE_EXTENSIONS.includes(entry.slice(dot).toLowerCase()))
+                out.push(full);
+        }
+    }
+    return out;
+}
+/**
+ * TCP-driver imports anywhere under the app directory.
+ *
+ * Scans the whole tree rather than the client chunk closure: the driver is named
+ * in `app/db.ts`, which is correct, and what is wrong is that anything under it
+ * is reachable from a socketless runtime. Either way the build has to stop, and
+ * it has to stop before minutes of bundling have been spent.
+ */
+export function tcpDriverViolations(appDir) {
+    const files = [];
+    for (const path of collectAppSources(appDir)) {
+        try {
+            files.push({ path, code: readFileSync(path, 'utf-8') });
+        }
+        catch {
+            /* unreadable file — not a build blocker */
+        }
+    }
+    return scanServerOnlyImports(files).filter(v => v.kind === 'tcp-driver');
+}

package/dist/types.d.ts

@@ -1,2 +1,2 @@
-export type { RouteNode, ApiRouteNode, VeskPlugin, ServerEventContext, VeskEventHandlers, VeskSecurity, VeskCors, VeskRateLimit, VeskSecurityPreset, SecurityConfig, MiddlewareChainItem, MiddlewareExtractResult, AncestorLayout, BuildOptions, DevServerOptions, ProdServerOptions, SsrFunctionOptions, ApiFunctionOptions, ClientBundleOptions, ClientBundleFileEntry, ClientBundleChunkSpec, ClientBundleCache, ChunkEntry, ClientBundleResult, MonolithicBundleParts, Manifest, ManifestRouteEntry, ManifestActionEntry, ManifestPrerenderedEntry, SsgRouteResult, BuildResult, ImageRef, ImageResult, SeoCheckIssue, SeoAuditResult, CombinedPageInfo, Tracked, Resource, UseFetchOptions, UseFetchStreamOptions, VeskRequest, VeskResponse, SetCookieOptions, CookieStore, ServerRequest, SsrDataSink, MdProps, MdConfig, MdHtmlMode, MarkdownOptions, MdHtmlWarning, VeskLeafComponent, VeskPrimitiveComponent, VeskTaggedLeafComponent, VeskComponentRegistry, VeskScope, } from '@vesk/types';
+export type { RouteNode, ApiRouteNode, VeskPlugin, ServerEventContext, VeskEventHandlers, VeskSecurity, VeskCors, VeskRateLimit, VeskSecurityPreset, SecurityConfig, MiddlewareChainItem, MiddlewareExtractResult, AncestorLayout, BuildOptions, DevServerOptions, ProdServerOptions, SsrFunctionOptions, ApiFunctionOptions, ClientBundleOptions, ClientBundleFileEntry, ClientBundleChunkSpec, ClientBundleCache, ChunkEntry, ClientBundleResult, MonolithicBundleParts, Manifest, ManifestRouteEntry, ManifestActionEntry, ManifestPrerenderedEntry, SsgRouteResult, BuildResult, ImageRef, ImageResult, SeoCheckIssue, SeoAuditResult, CombinedPageInfo, Tracked, Resource, UseFetchOptions, UseFetchStreamOptions, VeskRequest, VeskResponse, SetCookieOptions, CookieStore, ServerRequest, SsrDataSink, MdProps, MdConfig, MdHtmlMode, MarkdownOptions, CompressionConfig, MdHtmlWarning, VeskLeafComponent, VeskPrimitiveComponent, VeskTaggedLeafComponent, VeskComponentRegistry, VeskScope, } from '@vesk/types';
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,SAAS,EACT,YAAY,EACZ,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,UAAU,EACV,kBAAkB,EAClB,qBAAqB,EACrB,QAAQ,EACR,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,cAAc,EACd,WAAW,EACX,QAAQ,EACR,WAAW,EACX,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,OAAO,EACP,QAAQ,EACR,eAAe,EACf,qBAAqB,EACrB,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,WAAW,EACX,OAAO,EACP,QAAQ,EACR,UAAU,EACV,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,SAAS,GACV,MAAM,aAAa,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,SAAS,EACT,YAAY,EACZ,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,UAAU,EACV,kBAAkB,EAClB,qBAAqB,EACrB,QAAQ,EACR,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,cAAc,EACd,WAAW,EACX,QAAQ,EACR,WAAW,EACX,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,OAAO,EACP,QAAQ,EACR,eAAe,EACf,qBAAqB,EACrB,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,WAAW,EACX,OAAO,EACP,QAAQ,EACR,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,SAAS,GACV,MAAM,aAAa,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vesk/adapter",
-  "version": "0.2.67",
+  "version": "0.2.69",
   "type": "module",
   "description": "Vesk adapter — builds deployable .vesk/ output for Deno and Node serverless",
   "main": "./dist/index.js",
@@ -23,9 +23,9 @@
     "sharp": "^0.35.3"
   },
   "dependencies": {
-    "@vesk/compiler": "^0.2.67",
-    "@vesk/runtime": "^0.2.67",
-    "@vesk/types": "^0.2.67"
+    "@vesk/compiler": "^0.2.69",
+    "@vesk/runtime": "^0.2.69",
+    "@vesk/types": "^0.2.69"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1",