@gobing-ai/ts-runtime 0.4.5 → 0.4.6

package/README.md

@@ -17,7 +17,7 @@ and Cloudflare Workers through a factory pattern that auto-detects the runtime.
 | Runtime factory | `RuntimeFactory` → `loadRuntimeFactory()` | `nodeBunFactory` | `cloudflareWorkersFactory` |
 | File system | `FileSystem` | `createNodeFileSystem()` (sync `node:fs`) | `createCfFileSystem()` (stub) |
 | Process execution | `ProcessExecutor` (class) | `run()` via execa, `runStreaming()` via `Bun.spawn` | throws |
-| SQL database | `createDbAdapter(config)` → `DbAdapter` | Bun SQLite via `@gobing-ai/ts-db` | throws `D1NotConfiguredError` (D1 round pending) |
+| SQL database | `createDbAdapter(config)` → `DbAdapter` | Bun SQLite via `@gobing-ai/ts-db` (optional peer) | throws `D1NotConfiguredError` (D1 round pending) |
 | Configuration | `Config` (Zod schema) | YAML + env vars | CONFIG_YAML blob + env vars |
 | Context | `RuntimeContext` | service locator | service locator |
 | Path utilities | `SEP`, `basenamePath`, `dirnamePath`, `joinPath`, `resolvePath`, `relativePath`, … | runtime-portable (zero `node:*`) | runtime-portable (zero `node:*`) |
@@ -392,11 +392,25 @@ On Cloudflare Workers, `capabilities.hasSqlDatabase` is `false` and `createDbAda
 `D1NotConfiguredError` — the method exists on the interface so consumer code is forward-compatible and
 needs no change when the D1 round ships.
 
-**Dependency note:** `@gobing-ai/ts-db` is not a static dependency of `ts-runtime` (it would create a
-cycle, since `ts-db` depends on `ts-runtime`). The factory interface uses a structural
-`RuntimeDbAdapter` type (defined locally) that a ts-db `DbAdapter` satisfies via structural subtyping;
-`nodeBunFactory.createDbAdapter` loads `ts-db` via a dynamic `import()` at runtime. Consumers that call
-`createDbAdapter` must have `@gobing-ai/ts-db` in their dependency graph.
+**Dependency note (optional peer):** `@gobing-ai/ts-db` is declared as an **optional
+`peerDependency`** of `ts-runtime` (ADR-012 addendum), not a regular dependency — a regular entry
+would create a manifest cycle (`ts-db` depends on `ts-runtime`) and force-install `ts-db` (plus its
+`drizzle-orm` peer) on every consumer, including Workers bundles and apps that never touch SQL.
+The factory interface uses a structural `RuntimeDbAdapter` type (defined locally) that a ts-db
+`DbAdapter` satisfies via structural subtyping; `nodeBunFactory.createDbAdapter` loads `ts-db` via a
+literal dynamic `import()` at runtime.
+
+**Who must install it:** only consumers that call `nodeBunFactory.createDbAdapter` on Node/Bun —
+install `@gobing-ai/ts-db` yourself (`bun add @gobing-ai/ts-db`). Workers consumers do not need it
+(`capabilities.hasSqlDatabase` is `false`; the method throws `D1NotConfiguredError`).
+
+**Bundling (`Bun --compile` / esbuild / Vite):** the literal specifier keeps `ts-db` bundler-visible,
+so `Bun --compile` can fold it into a standalone binary. If you bundle for a different runtime, mark
+`@gobing-ai/ts-db` `external` to preserve the dynamic import.
+
+**Failure mode:** if `@gobing-ai/ts-db` is absent or exports no `createDbAdapter` (incompatible
+version), `createDbAdapter` throws a typed `DbModuleNotInstalledError` (with the underlying resolution
+error chained as `cause`) instead of a raw `MODULE_NOT_FOUND`.
 
 ### 9. Graceful disposal
 

package/dist/db-errors.d.ts

@@ -11,4 +11,17 @@
 export declare class D1NotConfiguredError extends Error {
     constructor(message?: string);
 }
+/**
+ * Thrown by {@link RuntimeFactory.createDbAdapter} on `node-bun` when the
+ * optional peer `@gobing-ai/ts-db` is not installed.
+ *
+ * `ts-db` is an **optional peerDependency** of `ts-runtime` (ADR-012 addendum):
+ * it cannot be a regular dependency because `ts-db` depends on `ts-runtime`
+ * (manifest cycle). Consumers who call `nodeBunFactory.createDbAdapter` must
+ * install `@gobing-ai/ts-db` themselves. This error surfaces a missing module
+ * as an actionable, typed failure instead of a raw `MODULE_NOT_FOUND`.
+ */
+export declare class DbModuleNotInstalledError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
 //# sourceMappingURL=db-errors.d.ts.map

package/dist/db-errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db-errors.d.ts","sourceRoot":"","sources":["../src/db-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBAC/B,OAAO,SAAiE;CAIvF"}
+{"version":3,"file":"db-errors.d.ts","sourceRoot":"","sources":["../src/db-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBAC/B,OAAO,SAAiE;CAIvF;AAED;;;;;;;;;GASG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;gBAE5C,OAAO,SAAoO,EAC3O,OAAO,CAAC,EAAE,YAAY;CAK7B"}

package/dist/db-errors.js

@@ -14,3 +14,19 @@ export class D1NotConfiguredError extends Error {
         this.name = 'D1NotConfiguredError';
     }
 }
+/**
+ * Thrown by {@link RuntimeFactory.createDbAdapter} on `node-bun` when the
+ * optional peer `@gobing-ai/ts-db` is not installed.
+ *
+ * `ts-db` is an **optional peerDependency** of `ts-runtime` (ADR-012 addendum):
+ * it cannot be a regular dependency because `ts-db` depends on `ts-runtime`
+ * (manifest cycle). Consumers who call `nodeBunFactory.createDbAdapter` must
+ * install `@gobing-ai/ts-db` themselves. This error surfaces a missing module
+ * as an actionable, typed failure instead of a raw `MODULE_NOT_FOUND`.
+ */
+export class DbModuleNotInstalledError extends Error {
+    constructor(message = '@gobing-ai/ts-db is not installed. It is an optional peer of @gobing-ai/ts-runtime, required only for createDbAdapter on node-bun. Install it (`bun add @gobing-ai/ts-db`) or, when bundling, mark `@gobing-ai/ts-db` external.', options) {
+        super(message, options);
+        this.name = 'DbModuleNotInstalledError';
+    }
+}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export * from './config';
 export * from './context';
 export { createRuntimeContextFromFactory } from './context';
-export { D1NotConfiguredError } from './db-errors';
+export { D1NotConfiguredError, DbModuleNotInstalledError } from './db-errors';
 export type { FileStat, FileSystem } from './file-system';
 export { createCfFileSystem } from './file-system-cf';
 export { createNodeFileSystem, findProjectRoot } from './file-system-node';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,+BAA+B,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EACH,eAAe,EACf,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,OAAO,EACP,aAAa,GAChB,MAAM,MAAM,CAAC;AACd,cAAc,QAAQ,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACjG,YAAY,EACR,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,aAAa,EACb,UAAU,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC1E,cAAc,qBAAqB,CAAC;AACpC,cAAc,SAAS,CAAC;AAIxB,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAExG;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,YAAY,CAAC,cAAc,oBAAoB,EAAE,sBAAsB,CAAC,CAAC;AAE3G;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC,cAAc,oBAAoB,EAAE,qBAAqB,CAAC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,+BAA+B,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAC9E,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EACH,eAAe,EACf,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,OAAO,EACP,aAAa,GAChB,MAAM,MAAM,CAAC;AACd,cAAc,QAAQ,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACjG,YAAY,EACR,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,aAAa,EACb,UAAU,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC1E,cAAc,qBAAqB,CAAC;AACpC,cAAc,SAAS,CAAC;AAIxB,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAExG;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,YAAY,CAAC,cAAc,oBAAoB,EAAE,sBAAsB,CAAC,CAAC;AAE3G;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC,cAAc,oBAAoB,EAAE,qBAAqB,CAAC,CAAC"}

package/dist/index.js

@@ -1,7 +1,7 @@
 export * from './config.js';
 export * from './context.js';
 export { createRuntimeContextFromFactory } from './context.js';
-export { D1NotConfiguredError } from './db-errors.js';
+export { D1NotConfiguredError, DbModuleNotInstalledError } from './db-errors.js';
 export { createCfFileSystem } from './file-system-cf.js';
 export { createNodeFileSystem, findProjectRoot } from './file-system-node.js';
 export { atomicWriteFile, atomicWriteJson, createLogStream, ensureDirForFile, readJsonFile, walkDir, writeJsonFile, } from './fs.js';

package/dist/path.d.ts

@@ -8,6 +8,8 @@ export declare function isAbsolutePath(path: string): boolean;
 export declare function dirnamePath(path: string): string;
 /** Return the last segment of a path. Optionally strip a trailing extension. */
 export declare function basenamePath(p: string, ext?: string): string;
+/** Convert a file:// URL into the portable path format used by this package. */
+export declare function fileUrlToPath(url: string): string;
 /** Compute a platform-independent relative path from `from` to `to`. Both paths should be absolute. */
 export declare function relativePath(from: string, to: string): string;
 /** Joins path segments with `/`, normalizing separators and collapsing redundant slashes. */

package/dist/path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAIA,kGAAkG;AAClG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,oFAAoF;AACpF,eAAO,MAAM,GAAG,EAAE,MACgF,CAAC;AAEnG,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAmBD,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWhD;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAED,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAkB7D;AAED,6FAA6F;AAC7F,wBAAgB,QAAQ,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAMtD;AAED,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAqBzD;AAED,qFAAqF;AACrF,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAIA,kGAAkG;AAClG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,oFAAoF;AACpF,eAAO,MAAM,GAAG,EAAE,MACgF,CAAC;AAEnG,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAmBD,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWhD;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAkBjD;AAED,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAkB7D;AAED,6FAA6F;AAC7F,wBAAgB,QAAQ,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAMtD;AAED,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAqBzD;AAED,qFAAqF;AACrF,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}

package/dist/path.js

@@ -54,6 +54,24 @@ export function basenamePath(p, ext) {
     }
     return base;
 }
+/** Convert a file:// URL into the portable path format used by this package. */
+export function fileUrlToPath(url) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'file:') {
+        throw new Error(`Expected file URL, got "${parsed.protocol}"`);
+    }
+    // Encoded separators would decode into extra path segments (e.g. "%2F..%2F"
+    // becoming "/../"), silently changing path semantics — reject like node:url does.
+    if (/%2f|%5c/i.test(parsed.pathname)) {
+        throw new Error('File URL path must not include encoded "/" or "\\" characters');
+    }
+    const pathname = decodeURIComponent(parsed.pathname);
+    const localPath = /^\/[A-Za-z]:\//.test(pathname) ? pathname.slice(1) : pathname;
+    if (parsed.hostname.length > 0 && parsed.hostname !== 'localhost') {
+        return normalizeSeparators(`//${parsed.hostname}${localPath}`);
+    }
+    return normalizeSeparators(localPath);
+}
 /** Compute a platform-independent relative path from `from` to `to`. Both paths should be absolute. */
 export function relativePath(from, to) {
     const fromParsed = pathParts(resolvePath(from));

package/dist/runtime-node-bun.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-node-bun.d.ts","sourceRoot":"","sources":["../src/runtime-node-bun.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAUxD,oEAAoE;AACpE,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,cA8B5B,CAAC"}
+{"version":3,"file":"runtime-node-bun.d.ts","sourceRoot":"","sources":["../src/runtime-node-bun.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAUxD,oEAAoE;AACpE,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,cAwC5B,CAAC"}

package/dist/runtime-node-bun.js

@@ -1,5 +1,6 @@
 import { parse as parseYaml } from 'yaml';
 import { buildConfigFromObject, getProcessEnv } from './config.js';
+import { DbModuleNotInstalledError } from './db-errors.js';
 import { createNodeFileSystem } from './file-system-node.js';
 import { ProcessExecutor } from './process-executor.js';
 // Lazy re-initialisable singleton for test isolation.
@@ -30,14 +31,25 @@ export const nodeBunFactory = {
         return loadNodeConfig(options);
     },
     async createDbAdapter(config) {
-        // Dynamic import via a variable specifier keeps ts-db out of the
-        // static dependency graph (it depends on ts-runtime, so a static dep
-        // would cycle). The variable prevents tsc from type-resolving the
-        // module at build time (ts-db builds after ts-runtime); at runtime
-        // Bun resolves it via the workspace + tsconfig paths. Connection only
-        // — the caller owns schema/migrations.
+        // Dynamic import via a variable specifier — this prevents tsc from
+        // statically resolving @gobing-ai/ts-db at build time. ts-db builds
+        // AFTER ts-runtime (it depends on ts-runtime), so a literal specifier
+        // or `typeof import()` annotation triggers TS2307 in a clean CI
+        // checkout where no prebuilt dist/ exists yet. At runtime Bun resolves
+        // the module via the workspace symlink.
+        // ts-db is an optional peerDependency (ADR-012 addendum) — if the
+        // consumer has not installed it, surface a typed error.
         const moduleSpecifier = '@gobing-ai/ts-db';
-        const mod = (await import(moduleSpecifier));
+        let mod;
+        try {
+            mod = (await import(moduleSpecifier));
+        }
+        catch (cause) {
+            throw new DbModuleNotInstalledError(undefined, { cause });
+        }
+        if (typeof mod.createDbAdapter !== 'function') {
+            throw new DbModuleNotInstalledError('@gobing-ai/ts-db is installed but does not export createDbAdapter — the installed version may be incompatible or partial.');
+        }
         return mod.createDbAdapter({ driver: 'bun-sqlite', url: config.url });
     },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-runtime",
-    "version": "0.4.5",
+    "version": "0.4.6",
     "description": "@gobing-ai/ts-runtime — Runtime abstractions for Bun, Node, and Cloudflare Workers.",
     "keywords": [
         "typescript",
@@ -58,15 +58,23 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-runtime-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-utils": "^0.4.5",
+        "@gobing-ai/ts-utils": "^0.4.6",
         "execa": "^9.5.0",
         "yaml": "^2.7.0",
         "zod": "^4.1.0"
     },
     "devDependencies": {
-        "@gobing-ai/ts-db": "^0.4.5",
+        "@gobing-ai/ts-db": "^0.4.6",
         "@types/bun": "1.3.14"
     },
+    "peerDependencies": {
+        "@gobing-ai/ts-db": "^0.4.6"
+    },
+    "peerDependenciesMeta": {
+        "@gobing-ai/ts-db": {
+            "optional": true
+        }
+    },
     "publishConfig": {
         "access": "public"
     }

package/src/db-errors.ts

@@ -14,3 +14,23 @@ export class D1NotConfiguredError extends Error {
         this.name = 'D1NotConfiguredError';
     }
 }
+
+/**
+ * Thrown by {@link RuntimeFactory.createDbAdapter} on `node-bun` when the
+ * optional peer `@gobing-ai/ts-db` is not installed.
+ *
+ * `ts-db` is an **optional peerDependency** of `ts-runtime` (ADR-012 addendum):
+ * it cannot be a regular dependency because `ts-db` depends on `ts-runtime`
+ * (manifest cycle). Consumers who call `nodeBunFactory.createDbAdapter` must
+ * install `@gobing-ai/ts-db` themselves. This error surfaces a missing module
+ * as an actionable, typed failure instead of a raw `MODULE_NOT_FOUND`.
+ */
+export class DbModuleNotInstalledError extends Error {
+    constructor(
+        message = '@gobing-ai/ts-db is not installed. It is an optional peer of @gobing-ai/ts-runtime, required only for createDbAdapter on node-bun. Install it (`bun add @gobing-ai/ts-db`) or, when bundling, mark `@gobing-ai/ts-db` external.',
+        options?: ErrorOptions,
+    ) {
+        super(message, options);
+        this.name = 'DbModuleNotInstalledError';
+    }
+}

package/src/index.ts

@@ -1,7 +1,7 @@
 export * from './config';
 export * from './context';
 export { createRuntimeContextFromFactory } from './context';
-export { D1NotConfiguredError } from './db-errors';
+export { D1NotConfiguredError, DbModuleNotInstalledError } from './db-errors';
 export type { FileStat, FileSystem } from './file-system';
 export { createCfFileSystem } from './file-system-cf';
 export { createNodeFileSystem, findProjectRoot } from './file-system-node';

package/src/path.ts

@@ -58,6 +58,27 @@ export function basenamePath(p: string, ext?: string): string {
     return base;
 }
 
+/** Convert a file:// URL into the portable path format used by this package. */
+export function fileUrlToPath(url: string): string {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'file:') {
+        throw new Error(`Expected file URL, got "${parsed.protocol}"`);
+    }
+
+    // Encoded separators would decode into extra path segments (e.g. "%2F..%2F"
+    // becoming "/../"), silently changing path semantics — reject like node:url does.
+    if (/%2f|%5c/i.test(parsed.pathname)) {
+        throw new Error('File URL path must not include encoded "/" or "\\" characters');
+    }
+
+    const pathname = decodeURIComponent(parsed.pathname);
+    const localPath = /^\/[A-Za-z]:\//.test(pathname) ? pathname.slice(1) : pathname;
+    if (parsed.hostname.length > 0 && parsed.hostname !== 'localhost') {
+        return normalizeSeparators(`//${parsed.hostname}${localPath}`);
+    }
+    return normalizeSeparators(localPath);
+}
+
 /** Compute a platform-independent relative path from `from` to `to`. Both paths should be absolute. */
 export function relativePath(from: string, to: string): string {
     const fromParsed = pathParts(resolvePath(from));

package/src/runtime-node-bun.ts

@@ -1,6 +1,7 @@
 import { parse as parseYaml } from 'yaml';
 import type { Config } from './config';
 import { buildConfigFromObject, getProcessEnv } from './config';
+import { DbModuleNotInstalledError } from './db-errors';
 import type { FileSystem } from './file-system';
 import { createNodeFileSystem } from './file-system-node';
 import { ProcessExecutor, type ProcessExecutorConfig } from './process-executor';
@@ -40,16 +41,26 @@ export const nodeBunFactory: RuntimeFactory = {
     },
 
     async createDbAdapter(config: DatabaseConfig): Promise<RuntimeDbAdapter> {
-        // Dynamic import via a variable specifier keeps ts-db out of the
-        // static dependency graph (it depends on ts-runtime, so a static dep
-        // would cycle). The variable prevents tsc from type-resolving the
-        // module at build time (ts-db builds after ts-runtime); at runtime
-        // Bun resolves it via the workspace + tsconfig paths. Connection only
-        // — the caller owns schema/migrations.
+        // Dynamic import via a variable specifier — this prevents tsc from
+        // statically resolving @gobing-ai/ts-db at build time. ts-db builds
+        // AFTER ts-runtime (it depends on ts-runtime), so a literal specifier
+        // or `typeof import()` annotation triggers TS2307 in a clean CI
+        // checkout where no prebuilt dist/ exists yet. At runtime Bun resolves
+        // the module via the workspace symlink.
+        // ts-db is an optional peerDependency (ADR-012 addendum) — if the
+        // consumer has not installed it, surface a typed error.
         const moduleSpecifier = '@gobing-ai/ts-db';
-        const mod = (await import(moduleSpecifier)) as {
-            createDbAdapter: (config: { driver: 'bun-sqlite'; url?: string }) => RuntimeDbAdapter;
-        };
+        let mod: { createDbAdapter: (config: { driver: 'bun-sqlite'; url?: string }) => RuntimeDbAdapter };
+        try {
+            mod = (await import(moduleSpecifier)) as typeof mod;
+        } catch (cause) {
+            throw new DbModuleNotInstalledError(undefined, { cause });
+        }
+        if (typeof mod.createDbAdapter !== 'function') {
+            throw new DbModuleNotInstalledError(
+                '@gobing-ai/ts-db is installed but does not export createDbAdapter — the installed version may be incompatible or partial.',
+            );
+        }
         return mod.createDbAdapter({ driver: 'bun-sqlite', url: config.url });
     },
 };