sandlot 0.1.3 → 0.2.0

package/dist/loader.d.ts

@@ -1,164 +0,0 @@
-/**
- * Module loader utilities for Sandlot bundles.
- *
- * Takes a BundleResult and turns it into usable JavaScript exports.
- * No external dependencies - just the basics for loading compiled code.
- *
- * @example
- * ```ts
- * // Capture the bundle via onBuild callback
- * let buildResult: BundleResult | null = null;
- * const unsubscribe = sandbox.onBuild((result) => {
- *   buildResult = result;
- * });
- *
- * const cmd = await sandbox.bash.exec("build /src/index.ts");
- * if (cmd.exitCode === 0 && buildResult) {
- *   // Load all exports
- *   const module = await loadModule<{ add: (a: number, b: number) => number }>(buildResult);
- *   console.log(module.add(1, 2)); // 3
- *
- *   // Load a specific export
- *   const add = await loadExport<(a: number, b: number) => number>(buildResult, "add");
- *   console.log(add(1, 2)); // 3
- * }
- * unsubscribe();
- * ```
- */
-import type { BundleResult } from "./bundler";
-/**
- * Error thrown when loading a module fails
- */
-export declare class ModuleLoadError extends Error {
-    constructor(message: string, cause?: unknown);
-}
-/**
- * Error thrown when an expected export is not found
- */
-export declare class ExportNotFoundError extends Error {
-    readonly exportName: string;
-    readonly availableExports: string[];
-    constructor(exportName: string, availableExports: string[]);
-}
-/**
- * Create a blob URL for a bundle that can be dynamically imported.
- * Remember to call `revokeModuleUrl()` when done to free memory.
- *
- * @param result - The bundle result from a successful build
- * @returns A blob URL that can be passed to `import()`
- *
- * @example
- * ```ts
- * const url = createModuleUrl(buildResult);
- * try {
- *   const module = await import(url);
- *   console.log(module.default);
- * } finally {
- *   revokeModuleUrl(url);
- * }
- * ```
- */
-export declare function createModuleUrl(result: BundleResult): string;
-/**
- * Revoke a blob URL created by `createModuleUrl()`.
- * This frees the memory associated with the blob.
- *
- * @param url - The blob URL to revoke
- */
-export declare function revokeModuleUrl(url: string): void;
-/**
- * Load all exports from a bundle result.
- *
- * @typeParam T - The expected shape of the module's exports
- * @param result - The bundle result from a successful build
- * @returns A promise that resolves to the module's exports
- * @throws {ModuleLoadError} If the module fails to load
- *
- * @example
- * ```ts
- * interface MyModule {
- *   add: (a: number, b: number) => number;
- *   multiply: (a: number, b: number) => number;
- * }
- *
- * const module = await loadModule<MyModule>(buildResult);
- * console.log(module.add(2, 3)); // 5
- * console.log(module.multiply(2, 3)); // 6
- * ```
- */
-export declare function loadModule<T = Record<string, unknown>>(result: BundleResult): Promise<T>;
-/**
- * Load a specific named export from a bundle result.
- *
- * @typeParam T - The expected type of the export
- * @param result - The bundle result from a successful build
- * @param exportName - The name of the export to retrieve (use "default" for default export)
- * @returns A promise that resolves to the export's value
- * @throws {ModuleLoadError} If the module fails to load
- * @throws {ExportNotFoundError} If the export doesn't exist
- *
- * @example
- * ```ts
- * // Load a named export
- * const add = await loadExport<(a: number, b: number) => number>(
- *   buildResult,
- *   "add"
- * );
- * console.log(add(2, 3)); // 5
- *
- * // Load the default export
- * const Calculator = await loadExport<typeof Calculator>(
- *   buildResult,
- *   "default"
- * );
- * ```
- */
-export declare function loadExport<T = unknown>(result: BundleResult, exportName?: string): Promise<T>;
-/**
- * Load the default export from a bundle result.
- * Convenience wrapper around `loadExport(result, "default")`.
- *
- * @typeParam T - The expected type of the default export
- * @param result - The bundle result from a successful build
- * @returns A promise that resolves to the default export
- * @throws {ModuleLoadError} If the module fails to load
- * @throws {ExportNotFoundError} If there is no default export
- *
- * @example
- * ```ts
- * // For a module that does: export default function add(a, b) { return a + b; }
- * const add = await loadDefault<(a: number, b: number) => number>(buildResult);
- * console.log(add(2, 3)); // 5
- * ```
- */
-export declare function loadDefault<T = unknown>(result: BundleResult): Promise<T>;
-/**
- * Get a list of export names from a bundle result.
- * Useful for introspection or debugging.
- *
- * @param result - The bundle result from a successful build
- * @returns A promise that resolves to an array of export names
- *
- * @example
- * ```ts
- * const exports = await getExportNames(buildResult);
- * console.log(exports); // ["add", "multiply", "default"]
- * ```
- */
-export declare function getExportNames(result: BundleResult): Promise<string[]>;
-/**
- * Check if a bundle has a specific export.
- *
- * @param result - The bundle result from a successful build
- * @param exportName - The name of the export to check for
- * @returns A promise that resolves to true if the export exists
- *
- * @example
- * ```ts
- * if (await hasExport(buildResult, "add")) {
- *   const add = await loadExport(buildResult, "add");
- * }
- * ```
- */
-export declare function hasExport(result: BundleResult, exportName: string): Promise<boolean>;
-//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,UAAU,EAAE,MAAM;aAClB,gBAAgB,EAAE,MAAM,EAAE;gBAD1B,UAAU,EAAE,MAAM,EAClB,gBAAgB,EAAE,MAAM,EAAE;CAQ7C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAG5D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEjD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1D,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,CAAC,CAAC,CAcZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,UAAU,CAAC,CAAC,GAAG,OAAO,EAC1C,MAAM,EAAE,YAAY,EACpB,UAAU,GAAE,MAAkB,GAC7B,OAAO,CAAC,CAAC,CAAC,CAWZ;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,CAE/E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAG5E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/dist/packages.d.ts

@@ -1,199 +0,0 @@
-/**
- * Package management for sandbox environments.
- *
- * Provides npm-like package installation using esm.sh CDN:
- * - Fetches TypeScript type definitions for editor/typecheck support
- * - Stores installed versions in package.json
- * - Resolves bare imports to CDN URLs at bundle time
- * - Supports @types/* packages (fetches package content as types)
- * - Supports subpath exports (react-dom/client, react/jsx-runtime)
- *
- * @example
- * ```ts
- * // Install a package
- * const result = await installPackage(fs, "react");
- * // result: { name: "react", version: "18.2.0", typesInstalled: true }
- *
- * // Get installed packages
- * const manifest = await getPackageManifest(fs);
- * // manifest.dependencies: { "react": "18.2.0" }
- *
- * // Resolve import to CDN URL
- * const url = resolveToEsmUrl("react", "18.2.0");
- * // url: "https://esm.sh/react@18.2.0"
- * ```
- */
-import type { IFileSystem } from "just-bash/browser";
-/**
- * Package manifest (subset of package.json)
- */
-export interface PackageManifest {
-    dependencies: Record<string, string>;
-}
-/**
- * Cache for storing fetched type definitions.
- * Used to avoid redundant network fetches when multiple sandboxes
- * install the same packages.
- */
-export interface TypesCache {
-    /**
-     * Get cached type definitions for a package version.
-     * Returns null if not cached.
-     */
-    get(name: string, version: string): Map<string, string> | null;
-    /**
-     * Store type definitions in the cache.
-     */
-    set(name: string, version: string, types: Map<string, string>): void;
-    /**
-     * Check if a package version is cached.
-     */
-    has(name: string, version: string): boolean;
-    /**
-     * Remove a package version from the cache.
-     */
-    delete(name: string, version: string): boolean;
-    /**
-     * Clear all cached entries.
-     */
-    clear(): void;
-}
-/**
- * In-memory implementation of TypesCache.
- * Suitable for sharing across multiple sandboxes within a session.
- */
-export declare class InMemoryTypesCache implements TypesCache {
-    private cache;
-    private key;
-    get(name: string, version: string): Map<string, string> | null;
-    set(name: string, version: string, types: Map<string, string>): void;
-    has(name: string, version: string): boolean;
-    delete(name: string, version: string): boolean;
-    clear(): void;
-    /**
-     * Get the number of cached packages (for diagnostics).
-     */
-    get size(): number;
-}
-/**
- * Result of installing a package
- */
-export interface InstallResult {
-    /** Package name */
-    name: string;
-    /** Resolved version */
-    version: string;
-    /** Whether type definitions were installed */
-    typesInstalled: boolean;
-    /** Number of type definition files installed */
-    typeFilesCount: number;
-    /** Error message if types failed (but package still usable) */
-    typesError?: string;
-    /** Whether types were loaded from cache */
-    fromCache?: boolean;
-}
-/**
- * Options for installing a package
- */
-export interface InstallOptions {
-    /**
-     * Cache to use for storing/retrieving type definitions.
-     * When provided, avoids redundant network fetches for packages
-     * that have already been installed in other sandboxes.
-     */
-    cache?: TypesCache;
-}
-/**
- * Parse package specifier into name and version
- * Examples:
- *   "react" -> { name: "react", version: undefined }
- *   "react@18" -> { name: "react", version: "18" }
- *   "@tanstack/react-query@5" -> { name: "@tanstack/react-query", version: "5" }
- */
-export declare function parsePackageSpec(spec: string): {
-    name: string;
-    version?: string;
-};
-/**
- * Read the package manifest from the filesystem
- */
-export declare function getPackageManifest(fs: IFileSystem): Promise<PackageManifest>;
-/**
- * Install a package from npm via esm.sh
- *
- * This fetches type definitions and stores them in the virtual filesystem,
- * then updates package.json with the installed version.
- *
- * Special handling:
- * - @types/* packages: Fetches package content directly as types
- * - Known packages (react, react-dom): Auto-fetches subpath types
- *
- * @param fs - The virtual filesystem
- * @param packageSpec - Package name with optional version (e.g., "react", "lodash@4")
- * @returns Install result with version and type info
- *
- * @example
- * ```ts
- * // Install latest version
- * await installPackage(fs, "react");
- *
- * // Install specific version
- * await installPackage(fs, "lodash@4.17.21");
- *
- * // Install scoped package
- * await installPackage(fs, "@tanstack/react-query@5");
- *
- * // Install @types package
- * await installPackage(fs, "@types/lodash");
- * ```
- */
-export declare function installPackage(fs: IFileSystem, packageSpec: string, options?: InstallOptions): Promise<InstallResult>;
-/**
- * Uninstall a package
- *
- * Removes the package from package.json and deletes type definitions.
- */
-export declare function uninstallPackage(fs: IFileSystem, packageName: string): Promise<boolean>;
-/**
- * Resolve a bare import to an esm.sh URL
- *
- * @param importPath - The import path (e.g., "react", "lodash/debounce")
- * @param installedPackages - Map of package name to version
- * @returns The CDN URL, or null if package not installed
- *
- * @example
- * ```ts
- * const packages = { "react": "18.2.0", "lodash-es": "4.17.21" };
- *
- * resolveToEsmUrl("react", packages);
- * // "https://esm.sh/react@18.2.0"
- *
- * resolveToEsmUrl("lodash-es/debounce", packages);
- * // "https://esm.sh/lodash-es@4.17.21/debounce"
- *
- * resolveToEsmUrl("unknown", packages);
- * // null
- * ```
- */
-export declare function resolveToEsmUrl(importPath: string, installedPackages: Record<string, string>): string | null;
-/**
- * Parse an import path into package name and subpath
- *
- * @example
- * parseImportPath("react") // { packageName: "react", subpath: undefined }
- * parseImportPath("lodash/debounce") // { packageName: "lodash", subpath: "debounce" }
- * parseImportPath("@tanstack/react-query") // { packageName: "@tanstack/react-query", subpath: undefined }
- * parseImportPath("@tanstack/react-query/devtools") // { packageName: "@tanstack/react-query", subpath: "devtools" }
- */
-export declare function parseImportPath(importPath: string): {
-    packageName: string;
-    subpath?: string;
-};
-/**
- * List all installed packages
- */
-export declare function listPackages(fs: IFileSystem): Promise<Array<{
-    name: string;
-    version: string;
-}>>;
-//# sourceMappingURL=packages.d.ts.map

package/dist/packages.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"packages.d.ts","sourceRoot":"","sources":["../src/packages.ts"],"names":[],"mappings":"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"}

package/dist/runner.d.ts

@@ -1,314 +0,0 @@
-/**
- * High-level runner for sandbox-based agent workflows.
- *
- * Provides simple wrappers that handle sandbox creation and build result capture,
- * letting the caller focus on their agent logic.
- */
-import { type Sandbox, type SandboxOptions } from "./sandbox";
-import type { BundleResult } from "./bundler";
-/**
- * Options for building with a sandbox (one-off usage).
- */
-export interface BuildWithSandboxOptions<T> {
-    /**
-     * Existing sandbox to use. If not provided, a new sandbox is created.
-     *
-     * Use this when you want to:
-     * - Reuse a sandbox across multiple builds
-     * - Pre-configure the sandbox with specific files or settings
-     * - Share a sandbox between different operations
-     *
-     * @example
-     * ```ts
-     * const sandbox = await createSandbox({
-     *   initialFiles: { '/src/index.ts': 'export const x = 1;' },
-     * });
-     *
-     * const result = await buildWithSandbox({
-     *   sandbox,
-     *   build: async (sb) => { ... },
-     * });
-     * ```
-     */
-    sandbox?: Sandbox;
-    /**
-     * Options for creating a new sandbox (only used if `sandbox` is not provided).
-     *
-     * @example
-     * ```ts
-     * const result = await buildWithSandbox({
-     *   sandboxOptions: {
-     *     initialFiles: { '/src/index.ts': 'export const x = 1;' },
-     *     sharedModules: ['react', 'react-dom/client'],
-     *   },
-     *   build: async (sandbox) => { ... },
-     * });
-     * ```
-     */
-    sandboxOptions?: SandboxOptions;
-    /**
-     * The function to run with the sandbox.
-     *
-     * This receives the sandbox and can do anything with it—run bash commands,
-     * write files, execute an agent loop, etc.
-     *
-     * The return value becomes `result` in the output.
-     *
-     * @example
-     * ```ts
-     * const { result, bundle } = await buildWithSandbox({
-     *   build: async (sandbox) => {
-     *     await sandbox.bash.exec('echo "hello" > /test.txt');
-     *     const buildResult = await sandbox.bash.exec('build /src/index.ts');
-     *     return { buildExitCode: buildResult.exitCode };
-     *   },
-     * });
-     * ```
-     */
-    build: (sandbox: Sandbox) => Promise<T>;
-}
-/**
- * Result of building with a sandbox.
- */
-export interface BuildResult<T> {
-    /**
-     * Whatever the `build` function returned, or `undefined` if it threw.
-     */
-    result: T | undefined;
-    /**
-     * The error thrown by the `build` function, or `null` if it succeeded.
-     *
-     * When an error occurs, the bundle and module may still be available
-     * if a build succeeded before the error was thrown.
-     */
-    error: Error | null;
-    /**
-     * The last successful build result, or null if no build succeeded.
-     *
-     * This captures the bundle from any successful `build` command executed
-     * during the run. If multiple builds succeed, this contains the last one.
-     *
-     * **Important**: This is available even if the `build` function threw an error,
-     * as long as a build succeeded before the error occurred.
-     */
-    bundle: BundleResult | null;
-    /**
-     * The loaded module exports, or null if no bundle or loading failed.
-     *
-     * When a build succeeds, the bundle is automatically loaded and the
-     * exports are available here. Use type assertions or runtime checks
-     * to access specific exports.
-     *
-     * @example
-     * ```ts
-     * const run = await buildWithSandbox({ build: myAgent });
-     *
-     * if (run.module) {
-     *   const App = run.module.App as React.ComponentType;
-     *   return <App />;
-     * }
-     * ```
-     */
-    module: Record<string, unknown> | null;
-    /**
-     * Error that occurred while loading the module, or null if loading succeeded.
-     *
-     * This is separate from `error` (agent error) to distinguish:
-     * - Agent failed → `error` is set, `module` may still be available
-     * - Agent succeeded but load failed → `moduleError` is set
-     * - No bundle produced → both `module` and `moduleError` are null
-     */
-    moduleError: Error | null;
-    /**
-     * The sandbox that was used.
-     *
-     * Useful when the wrapper created an ephemeral sandbox—you can inspect
-     * its state, save it, or reuse it for another build.
-     */
-    sandbox: Sandbox;
-}
-/**
- * Build with a sandbox, automatically capturing build results.
- *
- * This is the recommended way to use sandlot for one-off builds. It:
- * 1. Creates a sandbox (or uses one you provide)
- * 2. Sets up build result capture
- * 3. Runs your function
- * 4. Returns everything: your result, the bundle (if any), and the sandbox
- *
- * For reusable agent workflows, see `createBuilder()` which wraps this
- * function and adds prompt support.
- *
- * The caller handles their own timeout/cancellation logic—this wrapper
- * stays minimal and doesn't impose opinions on error handling.
- *
- * @example Basic usage with an agent
- * ```ts
- * import { buildWithSandbox } from 'sandlot';
- *
- * const run = await buildWithSandbox({
- *   build: async (sandbox) => {
- *     const agent = new MyAgent({
- *       tools: {
- *         bash: (command: string) => sandbox.bash.exec(command),
- *       },
- *     });
- *
- *     return agent.run('Create a React component that shows "Hello"');
- *   },
- * });
- *
- * // Module is auto-loaded if build succeeded
- * if (run.module) {
- *   const App = run.module.App as React.ComponentType;
- *   return <App />;
- * }
- * ```
- *
- * @example Handling all failure modes
- * ```ts
- * const run = await buildWithSandbox({
- *   build: async (sandbox) => myAgent.run('...'),
- * });
- *
- * // Check what happened
- * if (run.error) {
- *   console.log('Agent failed:', run.error.message);
- * }
- * if (run.moduleError) {
- *   console.log('Module failed to load:', run.moduleError.message);
- * }
- *
- * // Module available even if agent errored (if build succeeded first)
- * if (run.module) {
- *   const App = run.module.App as React.ComponentType;
- *   return <App />;
- * }
- *
- * // No module - check why
- * if (!run.bundle) {
- *   console.log('No build was produced');
- * }
- * ```
- */
-export declare function buildWithSandbox<T>(options: BuildWithSandboxOptions<T>): Promise<BuildResult<T>>;
-/**
- * Options for creating a reusable builder function.
- */
-export interface CreateBuilderOptions<T> {
-    /**
-     * Existing sandbox to reuse across all calls.
-     *
-     * When provided, the same sandbox is used for every call to the returned
-     * builder function. Files and state persist between runs—useful for
-     * iterative workflows where you want to build on previous work.
-     *
-     * @example
-     * ```ts
-     * const sandbox = await createSandbox({
-     *   initialFiles: { '/src/utils.ts': 'export const PI = 3.14;' },
-     * });
-     *
-     * const runAgent = createBuilder({
-     *   sandbox, // Reused across all calls
-     *   build: async (sb, prompt) => myAgent.run(sb, prompt),
-     * });
-     *
-     * await runAgent("Create a circle component"); // Uses existing utils.ts
-     * await runAgent("Add a square component");    // Still has circle + utils
-     * ```
-     */
-    sandbox?: Sandbox;
-    /**
-     * Options for creating fresh sandboxes (only used if `sandbox` is not provided).
-     *
-     * Each call to the returned builder function creates a new sandbox with
-     * these options. Use this when you want isolated runs.
-     *
-     * @example
-     * ```ts
-     * const runAgent = createBuilder({
-     *   sandboxOptions: {
-     *     sharedModules: ['react', 'react-dom/client'],
-     *   },
-     *   build: async (sandbox, prompt) => myAgent.run(sandbox, prompt),
-     * });
-     *
-     * // Each call gets a fresh sandbox
-     * await runAgent("Create a counter");  // Fresh sandbox
-     * await runAgent("Create a todo list"); // Another fresh sandbox
-     * ```
-     */
-    sandboxOptions?: SandboxOptions;
-    /**
-     * The function to build with the sandbox and prompt.
-     *
-     * This receives the sandbox and the prompt string, and should return
-     * whatever result your agent produces.
-     *
-     * @example
-     * ```ts
-     * const runAgent = createBuilder({
-     *   build: async (sandbox, prompt) => {
-     *     const agent = new MyAgent({
-     *       tools: { bash: sandbox.bash.exec },
-     *     });
-     *     return agent.run(prompt);
-     *   },
-     * });
-     * ```
-     */
-    build: (sandbox: Sandbox, prompt: string) => Promise<T>;
-}
-/**
- * Create a reusable builder function for running prompts in a sandbox.
- *
- * This wraps `buildWithSandbox()` to create a convenient function that
- * just takes a prompt. Define your agent logic once, then call it with
- * different prompts.
- *
- * **Sandbox behavior:**
- * - If you provide `sandbox`: The same sandbox is reused for every call
- *   (files persist, good for iteration)
- * - If you provide `sandboxOptions` (or nothing): A fresh sandbox is created
- *   for each call (isolated runs)
- *
- * @example Basic usage
- * ```ts
- * import { createBuilder } from 'sandlot';
- *
- * const runAgent = createBuilder({
- *   sandboxOptions: { sharedModules: ['react', 'react-dom/client'] },
- *   build: async (sandbox, prompt) => {
- *     const agent = new MyAgent({ tools: { bash: sandbox.bash.exec } });
- *     return agent.run(prompt);
- *   },
- * });
- *
- * // Use it multiple times with different prompts
- * const result1 = await runAgent("Create a counter component");
- * const result2 = await runAgent("Create a todo list");
- *
- * if (result1.module?.App) {
- *   const Counter = result1.module.App as React.ComponentType;
- * }
- * ```
- *
- * @example Iterative workflow with shared sandbox
- * ```ts
- * const sandbox = await createSandbox();
- *
- * const runAgent = createBuilder({
- *   sandbox, // Same sandbox for all calls
- *   build: async (sb, prompt) => myAgent.run(sb, prompt),
- * });
- *
- * // First prompt creates initial component
- * await runAgent("Create a button component");
- *
- * // Second prompt can build on the first
- * await runAgent("Add a click counter to the button");
- * ```
- */
-export declare function createBuilder<T>(options: CreateBuilderOptions<T>): (prompt: string) => Promise<BuildResult<T>>;
-//# sourceMappingURL=runner.d.ts.map

package/dist/runner.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAiB,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG9C;;GAEG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B;;OAEG;IACH,MAAM,EAAE,CAAC,GAAG,SAAS,CAAC;IAEtB;;;;;OAKG;IACH,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAEpB;;;;;;;;OAQG;IACH,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAE5B;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAEvC;;;;;;;OAOG;IACH,WAAW,EAAE,KAAK,GAAG,IAAI,CAAC;IAE1B;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAsCzB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC/B,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAW7C"}