@gobing-ai/ts-runtime 0.3.0 → 0.3.2

package/src/fs.ts

@@ -1,6 +1,8 @@
 import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { findProjectRoot } from './file-system-node';
 import { dirnamePath, getProcessCwd, joinPath, resolvePath } from './path';
 
+/** Portable file stat interface — mirrors the subset of `node:fs.Stats` used by the runtime. */
 export interface FileStat {
     isFile(): boolean;
     isDirectory(): boolean;
@@ -8,11 +10,13 @@ export interface FileStat {
     mtimeMs: number;
 }
 
+/** Write-only append stream for log output. */
 export interface LogStream {
     write(chunk: string): void;
     end(): void;
 }
 
+/** @deprecated Use {@link import('./file-system').FileSystem} instead — the new interface has union return types and does not require a separate SyncFileSystem. */
 export interface FileSystem {
     readFile(path: string): Promise<string>;
     writeFile(path: string, content: string): Promise<void>;
@@ -28,6 +32,7 @@ export interface FileSystem {
     createLogStream(path: string): LogStream;
 }
 
+/** @deprecated Use {@link import('./file-system').FileSystem} instead — its union return types make a separate sync interface unnecessary. */
 export interface SyncFileSystem {
     readFile(path: string): string;
     writeFile(path: string, content: string): void;
@@ -54,6 +59,8 @@ function nodeFs(): Promise<NodeFs> {
     return fsModule;
 }
 
+/** {@link FileSystem} backed by `node:fs/promises`. Lazy-loads the module to avoid top-level import cost. */
+/** @deprecated Use createNodeFileSystem() from './file-system-node' instead. */
 export class NodeFileSystem implements FileSystem {
     async readFile(path: string): Promise<string> {
         const { readFile } = await nodeFsPromises();
@@ -132,6 +139,8 @@ export class NodeFileSystem implements FileSystem {
     }
 }
 
+/** {@link SyncFileSystem} backed by `node:fs` synchronous APIs. */
+/** @deprecated Use createNodeFileSystem() from './file-system-node' instead — its FileSystem interface has union return types, eliminating the need for a separate sync implementation. */
 export class NodeSyncFileSystem implements SyncFileSystem {
     readFile(path: string): string {
         return readFileSync(path, 'utf-8');
@@ -214,6 +223,8 @@ class LazyNodeLogStream implements LogStream {
 
 const CLOUDFLARE_FS_ERROR = 'FileSystem is not available on Cloudflare Workers. Use D1, KV, or R2.';
 
+/** {@link FileSystem} stub for Cloudflare Workers — all file operations throw. Use D1, KV, or R2 instead. */
+/** @deprecated Use createCfFileSystem() from './file-system-cf' instead. */
 export class CloudflareFileSystem implements FileSystem {
     async readFile(path: string): Promise<string> {
         throw unsupportedCloudflareFs('readFile', path);
@@ -270,6 +281,8 @@ function unsupportedCloudflareFs(operation: string, path: string): Error {
 
 let activeFileSystem: FileSystem = new NodeFileSystem();
 
+/** Swaps the active global file system, returning a restore function for the previous instance. */
+/** @deprecated Use RuntimeFactory.createFileSystem() or ctx.require('fileSystem') instead. The global swap is replaced by factory-based DI. */
 export function setFileSystem(fileSystem: FileSystem): () => void {
     const previous = activeFileSystem;
     activeFileSystem = fileSystem;
@@ -278,18 +291,24 @@ export function setFileSystem(fileSystem: FileSystem): () => void {
     };
 }
 
+/** Returns the currently active global {@link FileSystem} instance. */
+/** @deprecated Use RuntimeFactory.createFileSystem() or ctx.require('fileSystem') instead. */
 export function getFs(): FileSystem {
     return activeFileSystem;
 }
 
+/** Creates parent directories for a file path before writing. */
 export async function ensureDirForFile(path: string, fs = getFs()): Promise<void> {
     await fs.mkdir(dirnamePath(path));
 }
 
+/** Synchronous variant of {@link ensureDirForFile}. */
+/** @deprecated The new createNodeFileSystem() handles parent-directory creation internally. */
 export function ensureDirForFileSync(path: string, fs: SyncFileSystem): void {
     fs.mkdir(dirnamePath(path));
 }
 
+/** Atomically writes a file by writing to a temp path then renaming, avoiding partial writes on crash. */
 export async function atomicWriteFile(path: string, content: string, fs = getFs()): Promise<void> {
     await ensureDirForFile(path, fs);
     const tempPath = `${path}.${getProcessPid()}.${uniqueToken()}.tmp`;
@@ -297,26 +316,31 @@ export async function atomicWriteFile(path: string, content: string, fs = getFs(
     await fs.rename(tempPath, path);
 }
 
+/** Atomically writes a value as JSON with trailing newline. */
 export async function atomicWriteJson(path: string, value: unknown, fs = getFs()): Promise<void> {
     await atomicWriteFile(path, `${JSON.stringify(value, null, 2)}\n`, fs);
 }
 
+/** Reads and parses a JSON file. */
 export async function readJsonFile<T = unknown>(path: string, fs = getFs()): Promise<T> {
     return JSON.parse(await fs.readFile(path)) as T;
 }
 
+/** Writes a value as JSON with 2-space indentation and trailing newline. */
 export async function writeJsonFile(path: string, value: unknown, fs = getFs()): Promise<void> {
     await fs.writeFile(path, `${JSON.stringify(value, null, 2)}\n`);
 }
 
-export async function walkDir(path: string, fs = getFs()): Promise<string[]> {
+/** Recursively walks a directory, returning sorted paths to all files, optionally excluding entries by name. */
+export async function walkDir(path: string, fs = getFs(), exclude?: Set<string>): Promise<string[]> {
     const entries = (await fs.readDir(path)).sort();
     const result: string[] = [];
     for (const entry of entries) {
+        if (exclude?.has(entry)) continue;
         const fullPath = joinPath(path, entry);
         const entryStat = await fs.stat(fullPath);
         if (entryStat?.isDirectory()) {
-            result.push(...(await walkDir(fullPath, fs)));
+            result.push(...(await walkDir(fullPath, fs, exclude)));
         } else if (entryStat?.isFile()) {
             result.push(fullPath);
         }
@@ -324,33 +348,26 @@ export async function walkDir(path: string, fs = getFs()): Promise<string[]> {
     return result;
 }
 
+/**
+ * Walks up from `startDir` looking for a `package.json` or `bun.lock` to locate the project root.
+ *
+ * @deprecated Use {@link import('./file-system-node').findProjectRoot} (or `createNodeFileSystem().getProjectRoot()`).
+ * This delegates to the single shared implementation.
+ */
 export function getProjectRoot(startDir = getProcessCwd()): string {
-    let current = resolvePath(startDir);
-    for (let i = 0; i < 12; i++) {
-        if (hasBunFile(joinPath(current, 'bun.lock')) || hasBunFile(joinPath(current, 'package.json'))) {
-            return current;
-        }
-        const parent = dirnamePath(current);
-        if (parent === current) return startDir;
-        current = parent;
-    }
-    return startDir;
+    return findProjectRoot(startDir);
 }
 
+/** Resolves path segments relative to the project root. */
 export function resolveProjectPath(...segments: string[]): string {
     return resolvePath(getProjectRoot(), ...segments);
 }
 
+/** Creates a {@link LogStream} at the given path using the active file system. */
 export function createLogStream(path: string, fs = getFs()): LogStream {
     return fs.createLogStream(path);
 }
 
-function hasBunFile(path: string): boolean {
-    const bun = (globalThis as { Bun?: { file: (path: string) => { size: number } } }).Bun;
-    if (bun === undefined) return false;
-    return bun.file(path).size !== 0;
-}
-
 function getProcessPid(): number {
     return (globalThis as { process?: { pid?: number } }).process?.pid ?? 0;
 }

package/src/index.ts

@@ -1,7 +1,62 @@
 export * from './config';
 export * from './context';
-export * from './fs';
+export { createRuntimeContextFromFactory } from './context';
+export type { FileStat, FileSystem } from './file-system';
+export { createCfFileSystem } from './file-system-cf';
+export { createNodeFileSystem, findProjectRoot } from './file-system-node';
+export {
+    atomicWriteFile,
+    atomicWriteJson,
+    CloudflareFileSystem,
+    createLogStream,
+    ensureDirForFile,
+    ensureDirForFileSync,
+    type FileSystem as LegacyFileSystem,
+    getFs,
+    getProjectRoot,
+    NodeFileSystem,
+    NodeSyncFileSystem,
+    readJsonFile,
+    resolveProjectPath,
+    type SyncFileSystem,
+    setFileSystem,
+    walkDir,
+    writeJsonFile,
+} from './fs';
 export * from './path';
-export * from './process-executor';
+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 { cloudflareWorkersFactory } from './runtime-cf';
+export type { RuntimeFactory } from './runtime-factory';
+export { _resetNodeFileSystem, nodeBunFactory } from './runtime-node-bun';
 export * from './schema-validation';
 export * from './types';
+
+// ── Deprecated re-exports (backward compatibility) ──────────────────────
+
+export { BunPipeProcessSpawner, BunSyncProcessExecutor, NodeProcessExecutor } from './process-executor';
+
+/**
+ * @deprecated Use {@link ProcessExecutor} directly for async execution.
+ * Use `Bun.spawnSync` or `child_process.spawnSync` for sync.
+ */
+export type SyncProcessExecutor = InstanceType<typeof import('./process-executor').BunSyncProcessExecutor>;
+
+/**
+ * @deprecated Use {@link ProcessExecutor.runStreaming} instead.
+ */
+export type PipeProcessSpawner = InstanceType<typeof import('./process-executor').BunPipeProcessSpawner>;

package/src/path.ts

@@ -2,16 +2,42 @@
 // `cloudflare-workers` (no `node:*`) as on node-bun (ADR-008). POSIX-style separators throughout;
 // Windows drive paths (`C:/...`) are normalized and treated as absolute.
 
+/** Replaces Windows backslashes with forward slashes for consistent POSIX-style path handling. */
 export function normalizeSeparators(path: string): string {
     return path.replaceAll('\\', '/');
 }
 
+/** Platform-specific path segment separator (`'/'` on POSIX, `'\\'` on Windows). */
+export const SEP: string =
+    (globalThis as { process?: { platform?: string } }).process?.platform === 'win32' ? '\\' : '/';
+
+/** Returns `true` for POSIX absolute paths and Windows drive paths (`C:/…`). */
 export function isAbsolutePath(path: string): boolean {
     return path.startsWith('/') || /^[A-Za-z]:\//.test(normalizeSeparators(path));
 }
 
+function splitRoot(path: string): { root: string; rest: string } {
+    const normalized = normalizeSeparators(path);
+    const drive = normalized.match(/^([A-Za-z]:)(?:\/|$)/);
+    if (drive) {
+        return { root: drive[1] ?? '', rest: normalized.slice((drive[1] ?? '').length).replace(/^\/+/, '') };
+    }
+    if (normalized.startsWith('/')) {
+        return { root: '/', rest: normalized.replace(/^\/+/, '') };
+    }
+    return { root: '', rest: normalized };
+}
+
+function pathParts(path: string): { root: string; parts: string[] } {
+    const { root, rest } = splitRoot(path);
+    return { root, parts: rest.split('/').filter(Boolean) };
+}
+
+/** Returns the parent directory of a path. Platform-independent — avoids `node:path`. */
 export function dirnamePath(path: string): string {
     const input = normalizeSeparators(path);
+    const { root } = splitRoot(input);
+    if (root !== '' && input.replace(/\/+$/, '') === root) return root === '/' ? '/' : `${root}/`;
     if (/^\/+$/.test(input)) return '/';
     const normalized = input.replace(/\/+$/, '');
     if (normalized === '' || normalized === '/') return normalized || '.';
@@ -21,6 +47,39 @@ export function dirnamePath(path: string): string {
     return normalized.slice(0, index);
 }
 
+/** Return the last segment of a path. Optionally strip a trailing extension. */
+export function basenamePath(p: string, ext?: string): string {
+    const normalized = normalizeSeparators(p).replace(/\/+$/, '');
+    const index = normalized.lastIndexOf('/');
+    let base = index < 0 ? normalized : normalized.slice(index + 1);
+    if (ext !== undefined && base !== ext && base.endsWith(ext)) {
+        base = base.slice(0, -ext.length);
+    }
+    return base;
+}
+
+/** 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));
+    const toParsed = pathParts(resolvePath(to));
+    if (fromParsed.root.toLowerCase() !== toParsed.root.toLowerCase()) {
+        return resolvePath(to);
+    }
+    const fromParts = fromParsed.parts;
+    const toParts = toParsed.parts;
+
+    // Strip common prefix.
+    let i = 0;
+    const minLen = Math.min(fromParts.length, toParts.length);
+    while (i < minLen && fromParts[i] === toParts[i]) i++;
+
+    const up = fromParts.slice(i).map(() => '..');
+    const down = toParts.slice(i);
+    const result = [...up, ...down].join('/');
+    return result || '.';
+}
+
+/** Joins path segments with `/`, normalizing separators and collapsing redundant slashes. */
 export function joinPath(...segments: string[]): string {
     const filtered = segments.filter((segment) => segment.length > 0).map(normalizeSeparators);
     if (filtered.length === 0) return '.';
@@ -29,6 +88,7 @@ export function joinPath(...segments: string[]): string {
     return absolute ? joined : joined.replace(/^\//, '');
 }
 
+/** Resolves a sequence of path segments to an absolute path, collapsing `..` and `.`. */
 export function resolvePath(...segments: string[]): string {
     const candidates = segments.length === 0 ? [getProcessCwd()] : segments;
     let resolved = '';
@@ -36,19 +96,23 @@ export function resolvePath(...segments: string[]): string {
         if (segment.length === 0) continue;
         resolved = isAbsolutePath(segment) ? segment : joinPath(resolved || getProcessCwd(), segment);
     }
+    const { root, rest } = splitRoot(resolved);
     const parts: string[] = [];
-    const absolute = isAbsolutePath(resolved);
-    for (const part of resolved.split('/')) {
+    const absolute = root !== '';
+    for (const part of rest.split('/')) {
         if (part === '' || part === '.') continue;
         if (part === '..') {
-            parts.pop();
+            if (parts.length > 0) parts.pop();
             continue;
         }
         parts.push(part);
     }
-    return `${absolute ? '/' : ''}${parts.join('/')}` || (absolute ? '/' : '.');
+    if (!absolute) return parts.join('/') || '.';
+    if (root === '/') return `/${parts.join('/')}` || '/';
+    return parts.length > 0 ? `${root}/${parts.join('/')}` : `${root}/`;
 }
 
+/** Returns `process.cwd()` if available, or `/` as fallback (Cloudflare Workers). */
 export function getProcessCwd(): string {
     return (globalThis as { process?: { cwd?: () => string } }).process?.cwd?.() ?? '/';
 }

package/src/platform.ts

@@ -0,0 +1,47 @@
+import type { RuntimeFactory } from './runtime-factory';
+import type { RuntimeName } from './types';
+
+// Single authoritative source for runtime detection.
+// All other code MUST consume RuntimeFactory via loadRuntimeFactory().
+// Probe-once contract: each primitive is invoked at most once per process and
+// the result is cached in `_factory` / `_runtimeName`.
+
+/** True when running in a Cloudflare Worker (server-tier only). */
+export function isCloudflareWorkerRuntime(): boolean {
+    return globalThis.navigator?.userAgent?.startsWith('Cloudflare-Workers') ?? false;
+}
+
+let _factory: RuntimeFactory | undefined;
+let _runtimeName: RuntimeName | undefined;
+
+/**
+ * Lazy-load and cache the appropriate {@link RuntimeFactory} based on environment detection.
+ */
+export async function loadRuntimeFactory(): Promise<RuntimeFactory> {
+    if (_factory) return _factory;
+
+    let factory: RuntimeFactory;
+    if (getRuntimeName() === 'cloudflare-workers') {
+        const { cloudflareWorkersFactory } = await import('./runtime-cf');
+        factory = cloudflareWorkersFactory;
+    } else {
+        const { nodeBunFactory } = await import('./runtime-node-bun');
+        factory = nodeBunFactory;
+    }
+    _factory = factory;
+    return factory;
+}
+
+function getRuntimeName(): RuntimeName {
+    if (_runtimeName) return _runtimeName;
+    _runtimeName = isCloudflareWorkerRuntime() ? 'cloudflare-workers' : 'node-bun';
+    return _runtimeName;
+}
+
+/**
+ * Reset the cached runtime factory and name (for test isolation).
+ */
+export function _resetRuntimeFactory(): void {
+    _factory = undefined;
+    _runtimeName = undefined;
+}

package/src/plugin/capability-registry.ts

@@ -0,0 +1,58 @@
+/** Registry origin for a host capability. */
+export type CapabilityOrigin = 'builtin' | 'extension';
+
+/** Registry entry metadata. */
+export interface CapabilityEntry<TCapability> {
+    /** Capability implementation. */
+    capability: TCapability;
+    /** Registration origin. */
+    origin: CapabilityOrigin;
+}
+
+/**
+ * Generic, domain-agnostic capability registry shared by engine hosts.
+ *
+ * Stores named capabilities of an opaque type `TCapability` with replace-by-name
+ * semantics and `origin` metadata. It knows nothing about what a capability *is* —
+ * each engine supplies its own type and owns its own error types and override
+ * semantics (the registry only reports what it stores).
+ */
+export class CapabilityRegistry<TCapability> {
+    private readonly capabilities = new Map<string, CapabilityEntry<TCapability>>();
+
+    constructor(private readonly kind: string) {}
+
+    /** Register or replace a capability. */
+    register(name: string, capability: TCapability, origin: CapabilityOrigin = 'extension'): void {
+        this.capabilities.set(name, { capability, origin });
+    }
+
+    /** Return true when a capability exists. */
+    has(name: string): boolean {
+        return this.capabilities.has(name);
+    }
+
+    /** Get a registered capability or throw a clear error. */
+    get(name: string): TCapability {
+        const entry = this.capabilities.get(name);
+        if (entry === undefined) {
+            throw new Error(`Unknown ${this.kind}: ${name}`);
+        }
+        return entry.capability;
+    }
+
+    /** Get a registered entry (capability plus origin) without throwing. */
+    getEntry(name: string): CapabilityEntry<TCapability> | undefined {
+        return this.capabilities.get(name);
+    }
+
+    /** List registered capability names in insertion order. */
+    list(): string[] {
+        return [...this.capabilities.keys()];
+    }
+
+    /** List registered entries (name + capability + origin) in insertion order. */
+    entries(): Array<readonly [string, CapabilityEntry<TCapability>]> {
+        return [...this.capabilities.entries()];
+    }
+}

package/src/plugin/extension-loader.ts

@@ -0,0 +1,105 @@
+import { isAbsolute, resolve } from 'node:path';
+import { assertRelativeExtensionPath } from './extension-path';
+
+/**
+ * A single extension module reference.
+ *
+ * `kind` is an engine-defined tag the registration callback uses to route the
+ * module to the right registry — the loader itself never interprets it. `path` is
+ * the relative path as authored; the loader **derives** the import target by
+ * resolving `path` against `baseDir` *after* validating it, so the trust guard
+ * always governs the actual module that gets imported. `sourceName` identifies the
+ * declaring config for diagnostics.
+ */
+export interface ExtensionRef<TExtensionKind extends string = string> {
+    /** Engine-defined capability tag, used only by the registration callback. */
+    readonly kind: TExtensionKind;
+    /** Relative path as authored, enforced by {@link assertRelativeExtensionPath}. */
+    readonly path: string;
+    /** Absolute directory the authored `path` is resolved against. */
+    readonly baseDir: string;
+    /** Name of the config (preset, workflow, …) that declared this ref. */
+    readonly sourceName: string;
+}
+
+/** Options controlling extension-module loading. */
+export interface LoadExtensionsOptions {
+    /**
+     * Whether to actually import extension modules. Defaults to `false`: loading
+     * arbitrary code is a trust decision the caller must make explicitly. When refs
+     * exist and this is not `true`, loading throws **before any import**.
+     */
+    readonly allowExtensions?: boolean;
+    /** Optional sink for non-fatal warnings (e.g. capability overrides). */
+    readonly logger?: { warn: (message: string) => void };
+    /**
+     * Required module loader. The generic core never performs a dynamic `import`
+     * itself — the embedder supplies the import policy (typically
+     * `(absPath) => import(absPath)`), and tests pass a stub. Keeping this explicit
+     * means the shared core has no ambient code-loading capability of its own.
+     */
+    readonly moduleLoader: (absPath: string) => Promise<Record<string, unknown>>;
+}
+
+/** A validated extension module export: an object carrying at least a string `name`. */
+export interface LoadedExtension {
+    /** Stable name of the contributed capability bundle. */
+    readonly name: string;
+    /** Engine-specific contribution payload (actions, evaluators, …). */
+    readonly [key: string]: unknown;
+}
+
+/**
+ * Import each extension module behind an explicit trust gate, validate its export,
+ * then hand it to an engine-provided registration callback.
+ *
+ * The loader is domain-agnostic: it does not know which registry a module belongs to.
+ * It enforces the trust boundary (gate + relative-path guard), validates the
+ * default/named-`extension` export shape, and delegates routing to `register`.
+ *
+ * Security invariants:
+ * - No refs → no-op.
+ * - Refs present but `allowExtensions !== true` → throws **before** any `import` or
+ *   `moduleLoader` call, so a declared extension is never silently dropped.
+ * - Every ref's authored path is re-validated by {@link assertRelativeExtensionPath}.
+ *
+ * @throws When extensions are present but `allowExtensions` is not `true`, when a path
+ *   fails the trust guard, or when a module lacks a valid `name`.
+ */
+export async function loadExtensionModules<TExtensionKind extends string>(
+    refs: readonly ExtensionRef<TExtensionKind>[],
+    options: LoadExtensionsOptions,
+    register: (ref: ExtensionRef<TExtensionKind>, extension: LoadedExtension) => void | Promise<void>,
+): Promise<void> {
+    if (refs.length === 0) return;
+
+    // Fail closed before importing anything: a declared extension under a disabled gate
+    // is a hard error, never a silent drop.
+    if (options.allowExtensions !== true) {
+        const first = refs[0] as ExtensionRef<TExtensionKind>;
+        throw new Error(
+            `"${first.sourceName}" declares ${first.kind} extension "${first.path}", but extensions are disabled — pass allowExtensions: true to load extension modules`,
+        );
+    }
+
+    for (const ref of refs) {
+        if (!isAbsolute(ref.baseDir)) {
+            throw new Error(`"${ref.sourceName}" extension baseDir "${ref.baseDir}" must be an absolute directory`);
+        }
+        // Validate the authored path, then derive the import target from it so the
+        // trust guard always governs the module actually imported — the loader never
+        // imports a caller-supplied absolute path it did not resolve itself.
+        assertRelativeExtensionPath(ref.path, { sourceName: ref.sourceName });
+        const absPath = resolve(ref.baseDir, ref.path);
+        const moduleExports = await options.moduleLoader(absPath);
+        const candidate = moduleExports.default ?? moduleExports.extension;
+        if (
+            candidate === null ||
+            typeof candidate !== 'object' ||
+            typeof (candidate as { name?: unknown }).name !== 'string'
+        ) {
+            throw new Error(`"${ref.sourceName}" extension "${ref.path}" must export an object with a string "name"`);
+        }
+        await register(ref, candidate as LoadedExtension);
+    }
+}

package/src/plugin/extension-path.ts

@@ -0,0 +1,20 @@
+/**
+ * Assert that an extension module path is relative and does not escape its
+ * declaring directory.
+ *
+ * Extension declarations are data, and a path that is absolute or escapes via `..`
+ * is a trust-boundary violation even when extension loading is explicitly allowed.
+ * This is a standalone validator (not a schema refinement) so the loader can enforce
+ * it at load time, independent of any engine's config schema — defense in depth.
+ *
+ * @throws When the path is absolute or contains a `..` traversal segment.
+ */
+export function assertRelativeExtensionPath(path: string, options: { sourceName?: string } = {}): void {
+    const where = options.sourceName !== undefined ? ` declared by "${options.sourceName}"` : '';
+    if (/^([/\\]|[A-Za-z]:[/\\])/.test(path)) {
+        throw new Error(`extension path "${path}"${where} must be relative (no absolute paths)`);
+    }
+    if (path.split(/[/\\]/).includes('..')) {
+        throw new Error(`extension path "${path}"${where} must not contain ".." traversal`);
+    }
+}

package/src/plugin/index.ts

@@ -0,0 +1,3 @@
+export * from './capability-registry';
+export * from './extension-loader';
+export * from './extension-path';

package/src/plugin.ts

@@ -0,0 +1 @@
+export * from './plugin/index';