@gobing-ai/ts-runtime 0.4.8 → 0.4.9

package/README.md

@@ -8,15 +8,13 @@ and Cloudflare Workers through a factory pattern that auto-detects the runtime.
 
 ## Overview
 
-
-
 **Key abstractions:**
 
 | Concept | Interface | Bun/Node impl | Cloudflare impl |
-|---------|-----------|---------------|-----------------|
+| --------- | ----------- | --------------- | ----------------- |
 | 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 |
+| Process execution | `ProcessExecutor` (interface) | `NodeProcessExecutor` — `run()` via execa, `runStreaming()` via `Bun.spawn` | throws |
 | 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 |
@@ -88,6 +86,12 @@ classDiagram
     }
 
     class ProcessExecutor {
+        <<interface>>
+        +run(options) Promise~ProcessResult~
+        +runStreaming(options) PipeProcess
+    }
+
+    class NodeProcessExecutor {
         +run(options) Promise~ProcessResult~
         +runStreaming(options) PipeProcess
     }
@@ -133,8 +137,9 @@ classDiagram
     FileSystem <|.. createNodeFileSystem : implements
     FileSystem <|.. createCfFileSystem : implements
     ProcessExecutor --> PipeProcess : creates
+    ProcessExecutor <|.. NodeProcessExecutor : implements
     nodeBunFactory --> createNodeFileSystem : creates
-    nodeBunFactory --> ProcessExecutor : creates
+    nodeBunFactory --> NodeProcessExecutor : creates
     cloudflareWorkersFactory --> createCfFileSystem : creates
     RuntimeContext --> FileSystem : "fileSystem"
     RuntimeContext --> Config : "config"
@@ -232,7 +237,7 @@ There are three ways a config file can name its schema. **Prefer the bundled pac
 the most secure and performant default:
 
 | Style | Example | Resolution | Notes |
-|-------|---------|------------|-------|
+| ------- | --------- | ------------ | ------- |
 | **Package specifier** (recommended) | `$schema: "@gobing-ai/ts-rule-engine/schemas/rule-file.schema.json"` | Resolved through `node_modules` via the module resolver, then read from disk | No network, no path guessing; survives hoisting/pnpm/monorepo layouts. Schemas ship in each package's `schemas/` (declared in `files`). **Quote the value** — YAML treats a leading `@` as reserved. |
 | Relative path | `$schema: ./schemas/rule-file.schema.json` | Resolved against the config file's directory | Fine for repo-local schemas; brittle if the config moves. |
 | Remote URL | `$schema: https://json-schema.org/.../rule-file.schema.json` | Fetched over HTTP(S) — **off by default** | SSRF/DoS surface for third-party configs. Opt in with `{ allowRemote: true }` (5s timeout) or supply your own `fetch`. |
@@ -251,7 +256,6 @@ await loadStructuredConfig('rules.yaml', { fetch: myFetch });           // or in
 > `node_modules` keeps validation entirely local — no outbound request, no dependency on a schema host's
 > availability, and no chance for a malicious config to point validation at an internal URL.
 
-
 ### 5. Path utilities
 
 Runtime-portable path math that avoids `node:path` so the same logic works on Cloudflare Workers
@@ -284,6 +288,7 @@ The `./extension` subpath exposes a generic, domain-agnostic extension/capabilit
 with origin metadata, a trust-gated extension loader, and a path guard — without knowing anything
 about evaluators, resolvers, actions, or guards. Each engine owns its domain-specific kinds,
 schemas, error types, and override semantics.
+
 #### Capability registry
 
 ```ts
@@ -462,6 +467,7 @@ process.on('SIGTERM', async () => {
     await ctx.dispose();
     process.exit(0);
 });
+
 ```
 
 ## Usage
@@ -513,6 +519,7 @@ const config = buildConfigFromObject({
     database: { url: ':memory:' },
 });
 ```
+
 // From YAML file
 const config = buildConfigFromYaml(yamlText);
 
@@ -521,16 +528,17 @@ const config = buildConfigFromObject({
     app: { name: 'api', env: 'production', port: 3000 },
     database: { url: ':memory:' },
 });
+
 ```
 
 ### Process execution
 
-`ProcessExecutor` is a single class wrapping `execa` (buffered) and `Bun.spawn` (streaming):
+`ProcessExecutor` is the canonical interface for process execution. `NodeProcessExecutor` is the concrete implementation wrapping `execa` (buffered) and `Bun.spawn` (streaming):
 
 ```ts
-import { ProcessExecutor } from '@gobing-ai/ts-runtime';
+import { NodeProcessExecutor } from '@gobing-ai/ts-runtime';
 
-const exec = new ProcessExecutor({ defaultTimeout: 30_000 });
+const exec = new NodeProcessExecutor({ defaultTimeout: 30_000 });
 
 // Buffered — captures stdout/stderr, no throw on non-zero
 const result = await exec.run({
@@ -557,8 +565,9 @@ maxOutput, and forceBuffered.
 Cloudflare Workers do not expose process execution; check
 `factory.capabilities.hasProcessExecution` first.
 
-Old classes (`NodeProcessExecutor`, `BunSyncProcessExecutor`, `BunPipeProcessSpawner`)
-are kept as deprecated backward-compatible wrappers.
+The `ProcessExecutor` const (value alias for `NodeProcessExecutor`), `BunSyncProcessExecutor`,
+and `BunPipeProcessSpawner` are kept as deprecated backward-compatible wrappers. Prefer
+`NodeProcessExecutor` or `nodeBunFactory.createProcessExecutor()` in new code.
 
 ### SpanContext (for telemetry)
 

package/dist/context.js

@@ -1,7 +1,7 @@
 import { buildConfigFromObject } from './config.js';
 import { createNodeFileSystem } from './file-system-node.js';
 import { loadRuntimeFactory } from './platform.js';
-import { ProcessExecutor } from './process-executor.js';
+import { nodeBunFactory } from './runtime-node-bun.js';
 /** Injectable service container scoped to a runtime environment (process, request, event, or test). */
 export class RuntimeContext {
     scope;
@@ -22,7 +22,7 @@ export class RuntimeContext {
         this.register('config', (options.services?.config ?? buildConfigFromObject({})));
         this.register('fileSystem', (options.services?.fileSystem ?? createNodeFileSystem()));
         if (this.capabilities.hasProcessExecution && options.services?.processExecutor === undefined) {
-            this.register('processExecutor', new ProcessExecutor());
+            this.register('processExecutor', nodeBunFactory.createProcessExecutor());
         }
         for (const [key, value] of Object.entries(options.services ?? {})) {
             if (value !== undefined) {

package/dist/index.d.ts

@@ -9,13 +9,13 @@ export { atomicWriteFile, atomicWriteJson, createLogStream, ensureDirForFile, re
 export * from './path';
 export { _resetRuntimeFactory, isCloudflareWorkerRuntime, loadRuntimeFactory } from './platform';
 export type { OutputPolicy, PipeProcess, PipeProcessOptions, ProcessEventDetail, ProcessEventSink, ProcessEvents, ProcessExecutorConfig, ProcessExitReason, ProcessOptions, ProcessResult, ProcessSignal, TracerPort, } from './process-executor';
-export { ProcessExecutor } from './process-executor';
+export { NodeProcessExecutor, ProcessExecutor } from './process-executor';
 export { cloudflareWorkersFactory } from './runtime-cf';
 export type { RuntimeFactory } from './runtime-factory';
 export { _resetNodeFileSystem, nodeBunFactory } from './runtime-node-bun';
 export * from './schema-validation';
 export * from './types';
-export { BunPipeProcessSpawner, BunSyncProcessExecutor, NodeProcessExecutor } from './process-executor';
+export { BunPipeProcessSpawner, BunSyncProcessExecutor } from './process-executor';
 /**
  * @deprecated Use {@link ProcessExecutor} directly for async execution.
  * Use `Bun.spawnSync` or `child_process.spawnSync` for sync.

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,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"}
+{"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,mBAAmB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1E,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,MAAM,oBAAoB,CAAC;AAEnF;;;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

@@ -7,10 +7,10 @@ export { createNodeFileSystem, findProjectRoot } from './file-system-node.js';
 export { atomicWriteFile, atomicWriteJson, createLogStream, ensureDirForFile, readJsonFile, walkDir, writeJsonFile, } from './fs.js';
 export * from './path.js';
 export { _resetRuntimeFactory, isCloudflareWorkerRuntime, loadRuntimeFactory } from './platform.js';
-export { ProcessExecutor } from './process-executor.js';
+export { NodeProcessExecutor, ProcessExecutor } from './process-executor.js';
 export { cloudflareWorkersFactory } from './runtime-cf.js';
 export { _resetNodeFileSystem, nodeBunFactory } from './runtime-node-bun.js';
 export * from './schema-validation.js';
 export * from './types.js';
 // ── Deprecated re-exports (backward compatibility) ──────────────────────
-export { BunPipeProcessSpawner, BunSyncProcessExecutor, NodeProcessExecutor } from './process-executor.js';
+export { BunPipeProcessSpawner, BunSyncProcessExecutor } from './process-executor.js';

package/dist/process-executor.d.ts

@@ -87,12 +87,37 @@ export interface PipeProcess {
     kill(signal?: ProcessSignal): void;
 }
 /**
- * Runtime-agnostic process executor wrapping `execa`.
+ * Runtime-agnostic process executor contract.
  *
  * Every invocation supports timeout enforcement, output capture, and
- * configurable output policy (buffered vs streamed).
+ * configurable output policy (buffered vs streamed). Concrete implementations
+ * are obtained through `RuntimeFactory.createProcessExecutor`; the Node/Bun
+ * implementation is {@link NodeProcessExecutor}. Test doubles implement this
+ * interface structurally — no concrete subclassing required.
  */
-export declare class ProcessExecutor {
+export interface ProcessExecutor {
+    /**
+     * Run a command, buffered by default. Returns a structured {@link ProcessResult}.
+     * Does NOT throw on non-zero exit codes unless `rejectOnError` is set.
+     */
+    run(options: ProcessOptions): Promise<ProcessResult>;
+    /**
+     * Spawn a long-running interactive process with streaming I/O.
+     *
+     * Returns a {@link PipeProcess} handle with streaming stdout/stderr and
+     * stdin write support.
+     */
+    runStreaming(options: PipeProcessOptions): PipeProcess;
+}
+/**
+ * Concrete Node/Bun implementation of {@link ProcessExecutor}, wrapping `execa`
+ * for buffered execution and `Bun.spawn` for streaming pipe execution.
+ *
+ * Obtain a default instance through `RuntimeFactory.createProcessExecutor`
+ * (e.g. `nodeBunFactory.createProcessExecutor()`); construct directly only in
+ * runtime-factory wiring or concrete implementation tests.
+ */
+export declare class NodeProcessExecutor implements ProcessExecutor {
     private readonly config;
     constructor(config?: ProcessExecutorConfig);
     /**
@@ -113,11 +138,13 @@ export declare class ProcessExecutor {
     private emitProcessEvent;
 }
 /**
- * @deprecated Use {@link ProcessExecutor} directly.
- * This subclass is kept for backward compatibility.
+ * @deprecated Construct {@link NodeProcessExecutor} directly or obtain a default
+ * through `RuntimeFactory.createProcessExecutor` (e.g. `nodeBunFactory.createProcessExecutor()`).
+ * This value alias preserves source compatibility for `new ProcessExecutor(...)` callers
+ * during the interface extraction release; it will be removed in a future release.
+ * `import type { ProcessExecutor }` resolves to the canonical interface, not this alias.
  */
-export declare class NodeProcessExecutor extends ProcessExecutor {
-}
+export declare const ProcessExecutor: typeof NodeProcessExecutor;
 /**
  * @deprecated Use `Bun.spawnSync` or `child_process.spawnSync` directly.
  * Synchronous process execution is no longer recommended from ts-runtime.

package/dist/process-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-executor.d.ts","sourceRoot":"","sources":["../src/process-executor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"process-executor.d.ts","sourceRoot":"","sources":["../src/process-executor.ts"],"names":[],"mappings":"AAKA,uGAAuG;AACvG,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtF,sGAAsG;AACtG,MAAM,WAAW,qBAAqB;IAClC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;CACvB;AAED,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,+FAA+F;AAC/F,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,qDAAqD;AACrD,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAExE,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC7B,IAAI,CAAC,KAAK,EAAE,iBAAiB,GAAG,gBAAgB,EAAE,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACvF;AAED,yFAAyF;AACzF,MAAM,MAAM,aAAa,GAAG;IACxB,iBAAiB,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;IACxD,gBAAgB,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;CAC1D,CAAC;AAEF,kFAAkF;AAClF,MAAM,WAAW,UAAU;IACvB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC9E;AAED,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,iDAAiD;AACjD,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;AAElD,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEjE,6FAA6F;AAC7F,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxC,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IAC7C,QAAQ,IAAI,IAAI,CAAC;IACjB,IAAI,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;CACtC;AAID;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC5B;;;OAGG;IACH,GAAG,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAErD;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAAC;CAC1D;AAID;;;;;;;GAOG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;gBAEnC,MAAM,GAAE,qBAA0B;IAI9C;;;OAGG;IACG,GAAG,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;YAI5C,WAAW;IAkEzB;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW;YA2CxC,KAAK;IAKnB,OAAO,CAAC,oBAAoB;IA0B5B,OAAO,CAAC,gBAAgB;CAG3B;AAyGD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,4BAAsB,CAAC;AAInD;;;;GAIG;AACH,qBAAa,sBAAsB;IAC/B,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,GAAG,aAAa;CA2BnE;AAED;;;GAGG;AACH,qBAAa,qBAAqB;IAC9B,KAAK,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW;CAWlD"}

package/dist/process-executor.js

@@ -1,13 +1,15 @@
 import { isatty } from 'node:tty';
 import { execa } from 'execa';
-// ── ProcessExecutor ───────────────────────────────────────────────────────
+// ── NodeProcessExecutor (concrete Node/Bun implementation) ───────────────
 /**
- * Runtime-agnostic process executor wrapping `execa`.
+ * Concrete Node/Bun implementation of {@link ProcessExecutor}, wrapping `execa`
+ * for buffered execution and `Bun.spawn` for streaming pipe execution.
  *
- * Every invocation supports timeout enforcement, output capture, and
- * configurable output policy (buffered vs streamed).
+ * Obtain a default instance through `RuntimeFactory.createProcessExecutor`
+ * (e.g. `nodeBunFactory.createProcessExecutor()`); construct directly only in
+ * runtime-factory wiring or concrete implementation tests.
  */
-export class ProcessExecutor {
+export class NodeProcessExecutor {
     config;
     constructor(config = {}) {
         this.config = config;
@@ -224,13 +226,16 @@ class BunPipeProcess {
         this.subprocess.kill(signal);
     }
 }
-// ── Deprecated backward-compatible subclasses ─────────────────────────────
+// ── Deprecated constructible ProcessExecutor value alias ──────────────────
 /**
- * @deprecated Use {@link ProcessExecutor} directly.
- * This subclass is kept for backward compatibility.
+ * @deprecated Construct {@link NodeProcessExecutor} directly or obtain a default
+ * through `RuntimeFactory.createProcessExecutor` (e.g. `nodeBunFactory.createProcessExecutor()`).
+ * This value alias preserves source compatibility for `new ProcessExecutor(...)` callers
+ * during the interface extraction release; it will be removed in a future release.
+ * `import type { ProcessExecutor }` resolves to the canonical interface, not this alias.
  */
-export class NodeProcessExecutor extends ProcessExecutor {
-}
+export const ProcessExecutor = NodeProcessExecutor;
+// ── Deprecated backward-compatible helpers ────────────────────────────────
 /**
  * @deprecated Use `Bun.spawnSync` or `child_process.spawnSync` directly.
  * Synchronous process execution is no longer recommended from ts-runtime.

package/dist/runtime-node-bun.js

@@ -2,7 +2,7 @@ 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';
+import { NodeProcessExecutor } from './process-executor.js';
 // Lazy re-initialisable singleton for test isolation.
 let _nodeFileSystem;
 function getNodeFileSystem() {
@@ -26,7 +26,7 @@ export const nodeBunFactory = {
         hasSqlDatabase: true,
     },
     createFileSystem: () => getNodeFileSystem(),
-    createProcessExecutor: (config) => new ProcessExecutor(config),
+    createProcessExecutor: (config) => new NodeProcessExecutor(config),
     async loadConfig(options) {
         return loadNodeConfig(options);
     },

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-runtime",
-    "version": "0.4.8",
+    "version": "0.4.9",
     "description": "@gobing-ai/ts-runtime — Runtime abstractions for Bun, Node, and Cloudflare Workers.",
     "keywords": [
         "typescript",
@@ -58,17 +58,17 @@
         "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.8",
+        "@gobing-ai/ts-utils": "^0.4.9",
         "execa": "^9.5.0",
         "yaml": "^2.7.0",
         "zod": "^4.1.0"
     },
     "devDependencies": {
-        "@gobing-ai/ts-db": "^0.4.8",
+        "@gobing-ai/ts-db": "^0.4.9",
         "@types/bun": "1.3.14"
     },
     "peerDependencies": {
-        "@gobing-ai/ts-db": "^0.4.8"
+        "@gobing-ai/ts-db": "^0.4.9"
     },
     "peerDependenciesMeta": {
         "@gobing-ai/ts-db": {

package/src/context.ts

@@ -4,7 +4,7 @@ import type { FileSystem } from './file-system';
 import { createNodeFileSystem } from './file-system-node';
 import { loadRuntimeFactory } from './platform';
 import type { ProcessExecutor as ProcessExecutorService } from './process-executor';
-import { ProcessExecutor } from './process-executor';
+import { nodeBunFactory } from './runtime-node-bun';
 import type { RuntimeCapabilities, RuntimeName } from './types';
 /** Execution scope of a runtime context — determines service lifecycle and availability. */
 export type RuntimeScope = 'process' | 'server-request' | 'scheduled-event' | 'test';
@@ -50,7 +50,7 @@ export class RuntimeContext<TServices extends RuntimeServiceMap = RuntimeService
             (options.services?.fileSystem ?? createNodeFileSystem()) as TServices['fileSystem'],
         );
         if (this.capabilities.hasProcessExecution && options.services?.processExecutor === undefined) {
-            this.register('processExecutor', new ProcessExecutor() as TServices['processExecutor']);
+            this.register('processExecutor', nodeBunFactory.createProcessExecutor() as TServices['processExecutor']);
         }
 
         for (const [key, value] of Object.entries(options.services ?? {})) {

package/src/index.ts

@@ -30,7 +30,7 @@ export type {
     ProcessSignal,
     TracerPort,
 } from './process-executor';
-export { ProcessExecutor } from './process-executor';
+export { NodeProcessExecutor, ProcessExecutor } from './process-executor';
 export { cloudflareWorkersFactory } from './runtime-cf';
 export type { RuntimeFactory } from './runtime-factory';
 export { _resetNodeFileSystem, nodeBunFactory } from './runtime-node-bun';
@@ -39,7 +39,7 @@ export * from './types';
 
 // ── Deprecated re-exports (backward compatibility) ──────────────────────
 
-export { BunPipeProcessSpawner, BunSyncProcessExecutor, NodeProcessExecutor } from './process-executor';
+export { BunPipeProcessSpawner, BunSyncProcessExecutor } from './process-executor';
 
 /**
  * @deprecated Use {@link ProcessExecutor} directly for async execution.

package/src/process-executor.ts

@@ -99,15 +99,44 @@ export interface PipeProcess {
     kill(signal?: ProcessSignal): void;
 }
 
-// ── ProcessExecutor ───────────────────────────────────────────────────────
+// ── ProcessExecutor (canonical interface) ────────────────────────────────
 
 /**
- * Runtime-agnostic process executor wrapping `execa`.
+ * Runtime-agnostic process executor contract.
  *
  * Every invocation supports timeout enforcement, output capture, and
- * configurable output policy (buffered vs streamed).
+ * configurable output policy (buffered vs streamed). Concrete implementations
+ * are obtained through `RuntimeFactory.createProcessExecutor`; the Node/Bun
+ * implementation is {@link NodeProcessExecutor}. Test doubles implement this
+ * interface structurally — no concrete subclassing required.
  */
-export class ProcessExecutor {
+export interface ProcessExecutor {
+    /**
+     * Run a command, buffered by default. Returns a structured {@link ProcessResult}.
+     * Does NOT throw on non-zero exit codes unless `rejectOnError` is set.
+     */
+    run(options: ProcessOptions): Promise<ProcessResult>;
+
+    /**
+     * Spawn a long-running interactive process with streaming I/O.
+     *
+     * Returns a {@link PipeProcess} handle with streaming stdout/stderr and
+     * stdin write support.
+     */
+    runStreaming(options: PipeProcessOptions): PipeProcess;
+}
+
+// ── NodeProcessExecutor (concrete Node/Bun implementation) ───────────────
+
+/**
+ * Concrete Node/Bun implementation of {@link ProcessExecutor}, wrapping `execa`
+ * for buffered execution and `Bun.spawn` for streaming pipe execution.
+ *
+ * Obtain a default instance through `RuntimeFactory.createProcessExecutor`
+ * (e.g. `nodeBunFactory.createProcessExecutor()`); construct directly only in
+ * runtime-factory wiring or concrete implementation tests.
+ */
+export class NodeProcessExecutor implements ProcessExecutor {
     private readonly config: ProcessExecutorConfig;
 
     constructor(config: ProcessExecutorConfig = {}) {
@@ -374,13 +403,18 @@ class BunPipeProcess implements PipeProcess {
     }
 }
 
-// ── Deprecated backward-compatible subclasses ─────────────────────────────
+// ── Deprecated constructible ProcessExecutor value alias ──────────────────
 
 /**
- * @deprecated Use {@link ProcessExecutor} directly.
- * This subclass is kept for backward compatibility.
+ * @deprecated Construct {@link NodeProcessExecutor} directly or obtain a default
+ * through `RuntimeFactory.createProcessExecutor` (e.g. `nodeBunFactory.createProcessExecutor()`).
+ * This value alias preserves source compatibility for `new ProcessExecutor(...)` callers
+ * during the interface extraction release; it will be removed in a future release.
+ * `import type { ProcessExecutor }` resolves to the canonical interface, not this alias.
  */
-export class NodeProcessExecutor extends ProcessExecutor {}
+export const ProcessExecutor = NodeProcessExecutor;
+
+// ── Deprecated backward-compatible helpers ────────────────────────────────
 
 /**
  * @deprecated Use `Bun.spawnSync` or `child_process.spawnSync` directly.

package/src/runtime-node-bun.ts

@@ -4,7 +4,7 @@ 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';
+import { NodeProcessExecutor, type ProcessExecutorConfig } from './process-executor';
 import type { RuntimeFactory } from './runtime-factory';
 import type { DatabaseConfig, LoadConfigOptions, RuntimeDbAdapter } from './types';
 
@@ -34,7 +34,7 @@ export const nodeBunFactory: RuntimeFactory = {
 
     createFileSystem: () => getNodeFileSystem(),
 
-    createProcessExecutor: (config?: ProcessExecutorConfig) => new ProcessExecutor(config),
+    createProcessExecutor: (config?: ProcessExecutorConfig) => new NodeProcessExecutor(config),
 
     async loadConfig(options?: LoadConfigOptions): Promise<Config> {
         return loadNodeConfig(options);