octoflow-core 1.0.0

package/dist/environments/local.js

@@ -0,0 +1,104 @@
+import { spawn } from "node:child_process";
+import { EXECUTION_ENVIRONMENT_CONTRACT_VERSION } from "octoflow-protocols";
+import {
+  ENVIRONMENT_DEFAULTS,
+  isEnvironmentTimeoutError,
+  runWithTimeout,
+  timedOutExecResult,
+  truncateOutput
+} from "./shared.js";
+const LOCAL_CAPABILITIES = [
+  "process-backed",
+  "long-lived"
+];
+function createLocalEnvironment(opts = {}) {
+  const defaultTimeoutMs = opts.defaultTimeoutMs ?? ENVIRONMENT_DEFAULTS.timeoutMs;
+  const outputByteLimit = opts.outputByteLimit ?? ENVIRONMENT_DEFAULTS.outputByteLimit;
+  const shell = opts.shell !== false;
+  return {
+    contractVersion: EXECUTION_ENVIRONMENT_CONTRACT_VERSION,
+    name: "local",
+    capabilities: LOCAL_CAPABILITIES,
+    async exec(input) {
+      const start = Date.now();
+      const timeoutMs = input.timeoutMs ?? defaultTimeoutMs;
+      const cwd = input.cwd ?? opts.cwd;
+      const mergedEnv = { ...process.env, ...opts.env, ...input.env };
+      let value;
+      let timedOut;
+      try {
+        ({ value, timedOut } = await runWithTimeout(
+          (signal) => execOnce({ input, cwd, env: mergedEnv, shell, signal }),
+          timeoutMs,
+          input.signal
+        ));
+      } catch (error) {
+        if (isEnvironmentTimeoutError(error)) {
+          return timedOutExecResult(error, start);
+        }
+        throw error;
+      }
+      const stdoutTrunc = truncateOutput(value.stdout, outputByteLimit);
+      const stderrTrunc = truncateOutput(value.stderr, outputByteLimit);
+      return {
+        stdout: stdoutTrunc.text,
+        stderr: stderrTrunc.text,
+        exitCode: value.exitCode,
+        truncated: stdoutTrunc.truncated || stderrTrunc.truncated,
+        timedOut,
+        durationMs: Date.now() - start
+      };
+    },
+    cleanup() {
+      return Promise.resolve();
+    }
+  };
+}
+function execOnce(args) {
+  return new Promise((resolve) => {
+    const child = spawn(args.input.command, [], {
+      cwd: args.cwd,
+      env: args.env,
+      shell: args.shell,
+      signal: args.signal,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    child.stdout?.on("data", (chunk) => stdoutChunks.push(chunk));
+    child.stderr?.on("data", (chunk) => stderrChunks.push(chunk));
+    if (child.stdin) {
+      child.stdin.end(args.input.stdin);
+    }
+    child.on("error", (err) => {
+      stderrChunks.push(Buffer.from(`
+${err.message}
+`, "utf8"));
+      resolve({
+        stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+        stderr: Buffer.concat(stderrChunks).toString("utf8"),
+        exitCode: typeof err.errno === "number" ? err.errno : 1
+      });
+    });
+    child.on("close", (code, signal) => {
+      const exitCode = code ?? (signal ? 128 + signalNumber(signal) : 1);
+      resolve({
+        stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+        stderr: Buffer.concat(stderrChunks).toString("utf8"),
+        exitCode
+      });
+    });
+  });
+}
+function signalNumber(signal) {
+  const signals = {
+    SIGINT: 2,
+    SIGKILL: 9,
+    SIGTERM: 15
+  };
+  return signals[signal] ?? 1;
+}
+export {
+  createLocalEnvironment
+};
+//# sourceMappingURL=local.js.map

package/dist/environments/local.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/environments/local.ts"],
+  "sourcesContent": ["import { spawn } from 'node:child_process';\n\nimport type {\n  EnvCapability,\n  ExecInput,\n  ExecResult,\n  ExecutionEnvironment,\n} from 'octoflow-protocols';\nimport { EXECUTION_ENVIRONMENT_CONTRACT_VERSION } from 'octoflow-protocols';\n\nimport {\n  ENVIRONMENT_DEFAULTS,\n  isEnvironmentTimeoutError,\n  runWithTimeout,\n  timedOutExecResult,\n  truncateOutput,\n} from './shared.js';\n\nexport interface LocalEnvironmentOptions {\n  /** Default working directory used when an `ExecInput` does not supply one. */\n  cwd?: string;\n  /** Extra environment variables merged on top of `process.env`. */\n  env?: Record<string, string>;\n  /** Default timeout in ms when an `ExecInput` does not supply one. */\n  defaultTimeoutMs?: number;\n  /** Maximum bytes of stdout/stderr returned. Excess is head+tail truncated. */\n  outputByteLimit?: number;\n  /** Run under a shell (`/bin/sh -c <command>`). Default `true`. */\n  shell?: boolean;\n}\n\nconst LOCAL_CAPABILITIES: readonly EnvCapability[] = [\n  'process-backed',\n  'long-lived',\n];\n\nexport function createLocalEnvironment(\n  opts: LocalEnvironmentOptions = {}\n): ExecutionEnvironment {\n  const defaultTimeoutMs =\n    opts.defaultTimeoutMs ?? ENVIRONMENT_DEFAULTS.timeoutMs;\n  const outputByteLimit =\n    opts.outputByteLimit ?? ENVIRONMENT_DEFAULTS.outputByteLimit;\n  const shell = opts.shell !== false;\n\n  return {\n    contractVersion: EXECUTION_ENVIRONMENT_CONTRACT_VERSION,\n    name: 'local',\n    capabilities: LOCAL_CAPABILITIES,\n\n    async exec(input: ExecInput): Promise<ExecResult> {\n      const start = Date.now();\n      const timeoutMs = input.timeoutMs ?? defaultTimeoutMs;\n      const cwd = input.cwd ?? opts.cwd;\n      const mergedEnv = { ...process.env, ...opts.env, ...input.env };\n\n      let value: ExecOnceResult;\n      let timedOut: boolean;\n      try {\n        ({ value, timedOut } = await runWithTimeout(\n          (signal) => execOnce({ input, cwd, env: mergedEnv, shell, signal }),\n          timeoutMs,\n          input.signal\n        ));\n      } catch (error) {\n        if (isEnvironmentTimeoutError(error)) {\n          return timedOutExecResult(error, start);\n        }\n        throw error;\n      }\n\n      const stdoutTrunc = truncateOutput(value.stdout, outputByteLimit);\n      const stderrTrunc = truncateOutput(value.stderr, outputByteLimit);\n\n      return {\n        stdout: stdoutTrunc.text,\n        stderr: stderrTrunc.text,\n        exitCode: value.exitCode,\n        truncated: stdoutTrunc.truncated || stderrTrunc.truncated,\n        timedOut,\n        durationMs: Date.now() - start,\n      };\n    },\n\n    cleanup(): Promise<void> {\n      return Promise.resolve();\n    },\n  };\n}\n\ninterface ExecOnceArgs {\n  input: ExecInput;\n  cwd?: string;\n  env: NodeJS.ProcessEnv;\n  shell: boolean;\n  signal: AbortSignal;\n}\n\ninterface ExecOnceResult {\n  stdout: string;\n  stderr: string;\n  exitCode: number;\n}\n\nfunction execOnce(args: ExecOnceArgs): Promise<ExecOnceResult> {\n  return new Promise((resolve) => {\n    const child = spawn(args.input.command, [], {\n      cwd: args.cwd,\n      env: args.env,\n      shell: args.shell,\n      signal: args.signal,\n      stdio: ['pipe', 'pipe', 'pipe'],\n    });\n\n    const stdoutChunks: Buffer[] = [];\n    const stderrChunks: Buffer[] = [];\n\n    child.stdout?.on('data', (chunk: Buffer) => stdoutChunks.push(chunk));\n    child.stderr?.on('data', (chunk: Buffer) => stderrChunks.push(chunk));\n\n    if (child.stdin) {\n      child.stdin.end(args.input.stdin);\n    }\n\n    child.on('error', (err) => {\n      stderrChunks.push(Buffer.from(`\\n${err.message}\\n`, 'utf8'));\n      resolve({\n        stdout: Buffer.concat(stdoutChunks).toString('utf8'),\n        stderr: Buffer.concat(stderrChunks).toString('utf8'),\n        exitCode:\n          typeof (err as NodeJS.ErrnoException).errno === 'number'\n            ? (err as NodeJS.ErrnoException).errno!\n            : 1,\n      });\n    });\n\n    child.on('close', (code, signal) => {\n      const exitCode = code ?? (signal ? 128 + signalNumber(signal) : 1);\n      resolve({\n        stdout: Buffer.concat(stdoutChunks).toString('utf8'),\n        stderr: Buffer.concat(stderrChunks).toString('utf8'),\n        exitCode,\n      });\n    });\n  });\n}\n\nfunction signalNumber(signal: NodeJS.Signals): number {\n  const signals: Record<string, number> = {\n    SIGINT: 2,\n    SIGKILL: 9,\n    SIGTERM: 15,\n  };\n  return signals[signal] ?? 1;\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/environments/plugin.d.ts

@@ -0,0 +1,22 @@
+import type { ExecutionEnvironment } from 'octoflow-protocols';
+import type { BridgePlugin } from '../runtime/bridge/plugins.js';
+import type { EnvironmentsRegistry } from './registry.js';
+export interface EnvironmentsPluginOptions {
+    environments: Readonly<Record<string, ExecutionEnvironment>>;
+    defaultName?: string;
+    /** Maps pack-worker names → environment names for per-worker pinning. */
+    perPackWorker?: Readonly<Record<string, string>>;
+    /**
+     * When true, register an `envBackedBashAction` against the default environment
+     * so the plugin's first registered action overrides any built-in `bash`.
+     * Default `true`.
+     */
+    installBashAction?: boolean;
+    /** Override the action name registered when `installBashAction` is true. */
+    bashActionName?: string;
+}
+export type EnvironmentsBridgePlugin = BridgePlugin & {
+    readonly environments: EnvironmentsRegistry;
+};
+export declare function createEnvironmentsPlugin(opts: EnvironmentsPluginOptions): EnvironmentsBridgePlugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/environments/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/environments/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAG/D,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,8BAA8B,CAAC;AAEhF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAG1D,MAAM,WAAW,yBAAyB;IACxC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,wBAAwB,GAAG,YAAY,GAAG;IACpD,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;CAC7C,CAAC;AAEF,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,yBAAyB,GAC9B,wBAAwB,CAkB1B"}

package/dist/environments/plugin.js

@@ -0,0 +1,20 @@
+import { envBackedBashAction } from "./bash-action.js";
+import { createEnvironmentsRegistry } from "./registry.js";
+function createEnvironmentsPlugin(opts) {
+  const registry = createEnvironmentsRegistry(opts);
+  const installBash = opts.installBashAction !== false;
+  const actions = installBash ? [envBackedBashAction(registry.get(), { name: opts.bashActionName })] : [];
+  return {
+    name: "octoflow-environments",
+    version: "0.1.0",
+    actions,
+    environments: registry,
+    async teardown(_ctx) {
+      await registry.cleanupAll();
+    }
+  };
+}
+export {
+  createEnvironmentsPlugin
+};
+//# sourceMappingURL=plugin.js.map

package/dist/environments/plugin.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/environments/plugin.ts"],
+  "sourcesContent": ["import type { ExecutionEnvironment } from 'octoflow-protocols';\n\nimport type { ActionDefinition } from '../actions/types.js';\nimport type { BridgePlugin, PluginContext } from '../runtime/bridge/plugins.js';\nimport { envBackedBashAction } from './bash-action.js';\nimport type { EnvironmentsRegistry } from './registry.js';\nimport { createEnvironmentsRegistry } from './registry.js';\n\nexport interface EnvironmentsPluginOptions {\n  environments: Readonly<Record<string, ExecutionEnvironment>>;\n  defaultName?: string;\n  /** Maps pack-worker names \u2192 environment names for per-worker pinning. */\n  perPackWorker?: Readonly<Record<string, string>>;\n  /**\n   * When true, register an `envBackedBashAction` against the default environment\n   * so the plugin's first registered action overrides any built-in `bash`.\n   * Default `true`.\n   */\n  installBashAction?: boolean;\n  /** Override the action name registered when `installBashAction` is true. */\n  bashActionName?: string;\n}\n\nexport type EnvironmentsBridgePlugin = BridgePlugin & {\n  readonly environments: EnvironmentsRegistry;\n};\n\nexport function createEnvironmentsPlugin(\n  opts: EnvironmentsPluginOptions\n): EnvironmentsBridgePlugin {\n  const registry = createEnvironmentsRegistry(opts);\n  const installBash = opts.installBashAction !== false;\n\n  const actions: ActionDefinition[] = installBash\n    ? [envBackedBashAction(registry.get(), { name: opts.bashActionName })]\n    : [];\n\n  return {\n    name: 'octoflow-environments',\n    version: '0.1.0',\n    actions,\n    environments: registry,\n\n    async teardown(_ctx: PluginContext): Promise<void> {\n      await registry.cleanupAll();\n    },\n  };\n}\n"],
+  "mappings": "AAIA,SAAS,2BAA2B;AAEpC,SAAS,kCAAkC;AAqBpC,SAAS,yBACd,MAC0B;AAC1B,QAAM,WAAW,2BAA2B,IAAI;AAChD,QAAM,cAAc,KAAK,sBAAsB;AAE/C,QAAM,UAA8B,cAChC,CAAC,oBAAoB,SAAS,IAAI,GAAG,EAAE,MAAM,KAAK,eAAe,CAAC,CAAC,IACnE,CAAC;AAEL,SAAO;AAAA,IACL,MAAM;AAAA,IACN,SAAS;AAAA,IACT;AAAA,IACA,cAAc;AAAA,IAEd,MAAM,SAAS,MAAoC;AACjD,YAAM,SAAS,WAAW;AAAA,IAC5B;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/environments/registry.d.ts

@@ -0,0 +1,19 @@
+import type { ExecutionEnvironment } from 'octoflow-protocols';
+export interface EnvironmentsRegistry {
+    /** Default environment used when no per-pack-worker pin is configured. */
+    readonly defaultName: string;
+    list(): readonly string[];
+    get(name?: string): ExecutionEnvironment;
+    has(name: string): boolean;
+    /** Look up the environment pinned for a given pack worker (falls back to default). */
+    forWorker(workerName: string): ExecutionEnvironment;
+    cleanupAll(): Promise<void>;
+}
+export interface EnvironmentsRegistryOptions {
+    environments: Readonly<Record<string, ExecutionEnvironment>>;
+    defaultName?: string;
+    /** Maps pack-worker names → environment names for per-worker pinning. */
+    perPackWorker?: Readonly<Record<string, string>>;
+}
+export declare function createEnvironmentsRegistry(opts: EnvironmentsRegistryOptions): EnvironmentsRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/environments/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/environments/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,IAAI,IAAI,SAAS,MAAM,EAAE,CAAC;IAC1B,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,oBAAoB,CAAC;IACzC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,sFAAsF;IACtF,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,oBAAoB,CAAC;IACpD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,2BAA2B;IAC1C,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,2BAA2B,GAChC,oBAAoB,CAmDtB"}

package/dist/environments/registry.js

@@ -0,0 +1,61 @@
+function createEnvironmentsRegistry(opts) {
+  const names = Object.keys(opts.environments);
+  if (names.length === 0) {
+    throw new Error(
+      "[octoflow-core/environments] registry requires at least one environment"
+    );
+  }
+  const defaultName = resolveDefaultName(opts);
+  if (!opts.environments[defaultName]) {
+    throw new Error(
+      `[octoflow-core/environments] default environment '${defaultName}' is not in the registry`
+    );
+  }
+  for (const [worker, target] of Object.entries(opts.perPackWorker ?? {})) {
+    if (!opts.environments[target]) {
+      throw new Error(
+        `[octoflow-core/environments] perPackWorker['${worker}'] points at unknown environment '${target}'`
+      );
+    }
+  }
+  return {
+    defaultName,
+    list() {
+      return Object.freeze([...names]);
+    },
+    has(name) {
+      return Object.prototype.hasOwnProperty.call(opts.environments, name);
+    },
+    get(name) {
+      const target = name ?? defaultName;
+      const env = opts.environments[target];
+      if (!env) {
+        throw new Error(
+          `[octoflow-core/environments] unknown environment '${target}'`
+        );
+      }
+      return env;
+    },
+    forWorker(workerName) {
+      const pinned = opts.perPackWorker?.[workerName];
+      return this.get(pinned ?? defaultName);
+    },
+    async cleanupAll() {
+      await Promise.allSettled(
+        Object.values(opts.environments).map((env) => env.cleanup())
+      );
+    }
+  };
+}
+function resolveDefaultName(opts) {
+  if (opts.defaultName) return opts.defaultName;
+  const names = Object.keys(opts.environments);
+  if (names.length === 1) return names[0];
+  throw new Error(
+    `[octoflow-core/environments] more than one environment registered (${names.join(", ")}); set 'defaultName' explicitly`
+  );
+}
+export {
+  createEnvironmentsRegistry
+};
+//# sourceMappingURL=registry.js.map

package/dist/environments/registry.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/environments/registry.ts"],
+  "sourcesContent": ["import type { ExecutionEnvironment } from 'octoflow-protocols';\n\nexport interface EnvironmentsRegistry {\n  /** Default environment used when no per-pack-worker pin is configured. */\n  readonly defaultName: string;\n  list(): readonly string[];\n  get(name?: string): ExecutionEnvironment;\n  has(name: string): boolean;\n  /** Look up the environment pinned for a given pack worker (falls back to default). */\n  forWorker(workerName: string): ExecutionEnvironment;\n  cleanupAll(): Promise<void>;\n}\n\nexport interface EnvironmentsRegistryOptions {\n  environments: Readonly<Record<string, ExecutionEnvironment>>;\n  defaultName?: string;\n  /** Maps pack-worker names \u2192 environment names for per-worker pinning. */\n  perPackWorker?: Readonly<Record<string, string>>;\n}\n\nexport function createEnvironmentsRegistry(\n  opts: EnvironmentsRegistryOptions\n): EnvironmentsRegistry {\n  const names = Object.keys(opts.environments);\n  if (names.length === 0) {\n    throw new Error(\n      '[octoflow-core/environments] registry requires at least one environment'\n    );\n  }\n\n  const defaultName = resolveDefaultName(opts);\n  if (!opts.environments[defaultName]) {\n    throw new Error(\n      `[octoflow-core/environments] default environment '${defaultName}' is not in the registry`\n    );\n  }\n\n  for (const [worker, target] of Object.entries(opts.perPackWorker ?? {})) {\n    if (!opts.environments[target]) {\n      throw new Error(\n        `[octoflow-core/environments] perPackWorker['${worker}'] points at unknown environment '${target}'`\n      );\n    }\n  }\n\n  return {\n    defaultName,\n    list() {\n      return Object.freeze([...names]);\n    },\n    has(name) {\n      return Object.prototype.hasOwnProperty.call(opts.environments, name);\n    },\n    get(name) {\n      const target = name ?? defaultName;\n      const env = opts.environments[target];\n      if (!env) {\n        throw new Error(\n          `[octoflow-core/environments] unknown environment '${target}'`\n        );\n      }\n      return env;\n    },\n    forWorker(workerName) {\n      const pinned = opts.perPackWorker?.[workerName];\n      return this.get(pinned ?? defaultName);\n    },\n    async cleanupAll() {\n      await Promise.allSettled(\n        Object.values(opts.environments).map((env) => env.cleanup())\n      );\n    },\n  };\n}\n\nfunction resolveDefaultName(opts: EnvironmentsRegistryOptions): string {\n  if (opts.defaultName) return opts.defaultName;\n  const names = Object.keys(opts.environments);\n  if (names.length === 1) return names[0]!;\n  throw new Error(\n    `[octoflow-core/environments] more than one environment registered (${names.join(', ')}); set 'defaultName' explicitly`\n  );\n}\n"],
+  "mappings": "AAoBO,SAAS,2BACd,MACsB;AACtB,QAAM,QAAQ,OAAO,KAAK,KAAK,YAAY;AAC3C,MAAI,MAAM,WAAW,GAAG;AACtB,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,QAAM,cAAc,mBAAmB,IAAI;AAC3C,MAAI,CAAC,KAAK,aAAa,WAAW,GAAG;AACnC,UAAM,IAAI;AAAA,MACR,qDAAqD,WAAW;AAAA,IAClE;AAAA,EACF;AAEA,aAAW,CAAC,QAAQ,MAAM,KAAK,OAAO,QAAQ,KAAK,iBAAiB,CAAC,CAAC,GAAG;AACvE,QAAI,CAAC,KAAK,aAAa,MAAM,GAAG;AAC9B,YAAM,IAAI;AAAA,QACR,+CAA+C,MAAM,qCAAqC,MAAM;AAAA,MAClG;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AAAA,IACL;AAAA,IACA,OAAO;AACL,aAAO,OAAO,OAAO,CAAC,GAAG,KAAK,CAAC;AAAA,IACjC;AAAA,IACA,IAAI,MAAM;AACR,aAAO,OAAO,UAAU,eAAe,KAAK,KAAK,cAAc,IAAI;AAAA,IACrE;AAAA,IACA,IAAI,MAAM;AACR,YAAM,SAAS,QAAQ;AACvB,YAAM,MAAM,KAAK,aAAa,MAAM;AACpC,UAAI,CAAC,KAAK;AACR,cAAM,IAAI;AAAA,UACR,qDAAqD,MAAM;AAAA,QAC7D;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA,IACA,UAAU,YAAY;AACpB,YAAM,SAAS,KAAK,gBAAgB,UAAU;AAC9C,aAAO,KAAK,IAAI,UAAU,WAAW;AAAA,IACvC;AAAA,IACA,MAAM,aAAa;AACjB,YAAM,QAAQ;AAAA,QACZ,OAAO,OAAO,KAAK,YAAY,EAAE,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC;AAAA,MAC7D;AAAA,IACF;AAAA,EACF;AACF;AAEA,SAAS,mBAAmB,MAA2C;AACrE,MAAI,KAAK,YAAa,QAAO,KAAK;AAClC,QAAM,QAAQ,OAAO,KAAK,KAAK,YAAY;AAC3C,MAAI,MAAM,WAAW,EAAG,QAAO,MAAM,CAAC;AACtC,QAAM,IAAI;AAAA,IACR,sEAAsE,MAAM,KAAK,IAAI,CAAC;AAAA,EACxF;AACF;",
+  "names": []
+}

package/dist/environments/shared.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared helpers used by every concrete environment factory.
+ */
+import type { ExecInput, ExecResult } from 'octoflow-protocols';
+export declare const ENVIRONMENT_DEFAULTS: {
+    readonly timeoutMs: 120000;
+    readonly outputByteLimit: 1048576;
+};
+export interface TruncationResult {
+    text: string;
+    truncated: boolean;
+}
+/**
+ * Truncate a UTF-8 string to a byte budget, preserving the head and a small
+ * tail so error context is visible.
+ */
+export declare function truncateOutput(text: string, byteLimit: number): TruncationResult;
+/**
+ * Race `op` against the caller's `signal` and an internally-managed timeout.
+ * The returned tuple gives the operation result plus whether the timeout
+ * fired (so the caller can set `timedOut` on `ExecResult`).
+ */
+export interface TimedRunResult<T> {
+    value: T;
+    timedOut: boolean;
+}
+export declare class EnvironmentTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+export declare function runWithTimeout<T>(op: (signal: AbortSignal) => Promise<T>, timeoutMs: number, outerSignal?: AbortSignal): Promise<TimedRunResult<T>>;
+export declare function isEnvironmentTimeoutError(error: unknown): error is EnvironmentTimeoutError;
+export declare function timedOutExecResult(error: EnvironmentTimeoutError, startedAtMs: number): ExecResult;
+export declare function assertSafeEnvKey(key: string): void;
+/**
+ * Single-quote a shell argument, escaping any embedded single-quotes.
+ * Safe for POSIX-compatible shells (bash, sh, dash).
+ *
+ * @example shellQuote("it's alive") → "'it'\\''s alive'"
+ */
+export declare function shellQuote(value: string): string;
+/**
+ * Shared exec body for environment implementations: runs an executor under a
+ * timeout, truncates output, and returns a normalized ExecResult. Callers are
+ * responsible for resolving the environment-specific resource (container,
+ * SSH client, etc.) before passing the executor.
+ */
+export declare function runExecBody(input: ExecInput, defaultTimeoutMs: number, outputByteLimit: number, executor: () => Promise<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}>): Promise<ExecResult>;
+/**
+ * Best-effort dynamic import for an optional peer SDK. Throws a developer-
+ * facing error message naming the missing package so the user knows what to
+ * install.
+ */
+export declare function loadOptionalPeer<T>(packageName: string): Promise<T>;
+//# sourceMappingURL=shared.d.ts.map

package/dist/environments/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/environments/shared.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAMhE,eAAO,MAAM,oBAAoB;;;CAGvB,CAAC;AAEX,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAalB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,uBAAwB,SAAQ,KAAK;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM;gBAAjB,SAAS,EAAE,MAAM;CAIvC;AAED,wBAAsB,cAAc,CAAC,CAAC,EACpC,EAAE,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EACvC,SAAS,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CA8B5B;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,uBAAuB,CAElC;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,uBAAuB,EAC9B,WAAW,EAAE,MAAM,GAClB,UAAU,CASZ;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAIlD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAgBD;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,SAAS,EAChB,gBAAgB,EAAE,MAAM,EACxB,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,MAAM,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,GAC5E,OAAO,CAAC,UAAU,CAAC,CA2BrB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CASzE"}

package/dist/environments/shared.js

@@ -0,0 +1,142 @@
+const DEFAULT_TIMEOUT_MS = 12e4;
+const DEFAULT_OUTPUT_BYTE_LIMIT = 1048576;
+const SAFE_ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ENVIRONMENT_DEFAULTS = {
+  timeoutMs: DEFAULT_TIMEOUT_MS,
+  outputByteLimit: DEFAULT_OUTPUT_BYTE_LIMIT
+};
+function truncateOutput(text, byteLimit) {
+  const buffer = Buffer.from(text, "utf8");
+  if (buffer.byteLength <= byteLimit) {
+    return { text, truncated: false };
+  }
+  const tailBytes = Math.min(2048, Math.floor(byteLimit / 8));
+  const headBytes = byteLimit - tailBytes;
+  const head = buffer.subarray(0, headBytes).toString("utf8");
+  const tail = buffer.subarray(buffer.byteLength - tailBytes).toString("utf8");
+  return {
+    text: `${head}
+... [truncated ${buffer.byteLength - byteLimit} bytes] ...
+${tail}`,
+    truncated: true
+  };
+}
+class EnvironmentTimeoutError extends Error {
+  constructor(timeoutMs) {
+    super(`Environment exec timed out after ${timeoutMs}ms`);
+    this.timeoutMs = timeoutMs;
+    this.name = "EnvironmentTimeoutError";
+  }
+  timeoutMs;
+}
+async function runWithTimeout(op, timeoutMs, outerSignal) {
+  if (outerSignal?.aborted) {
+    throw abortReasonToError(outerSignal.reason);
+  }
+  const controller = new AbortController();
+  let rejectAbort = () => {
+  };
+  const abortPromise = new Promise((_resolve, reject) => {
+    rejectAbort = reject;
+  });
+  const abortWith = (error) => {
+    rejectAbort(error);
+    controller.abort(error);
+  };
+  const onAbort = () => abortWith(abortReasonToError(outerSignal?.reason));
+  outerSignal?.addEventListener("abort", onAbort, { once: true });
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    abortWith(new EnvironmentTimeoutError(timeoutMs));
+  }, timeoutMs);
+  try {
+    const value = await Promise.race([op(controller.signal), abortPromise]);
+    return { value, timedOut };
+  } finally {
+    clearTimeout(timer);
+    outerSignal?.removeEventListener("abort", onAbort);
+  }
+}
+function isEnvironmentTimeoutError(error) {
+  return error instanceof EnvironmentTimeoutError;
+}
+function timedOutExecResult(error, startedAtMs) {
+  return {
+    stdout: "",
+    stderr: `${error.message}
+`,
+    exitCode: 124,
+    truncated: false,
+    timedOut: true,
+    durationMs: Date.now() - startedAtMs
+  };
+}
+function assertSafeEnvKey(key) {
+  if (!SAFE_ENV_KEY_RE.test(key)) {
+    throw new Error(`Unsafe environment variable name: ${key}`);
+  }
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function abortReasonToError(reason) {
+  if (reason instanceof Error) return reason;
+  if (reason == null) return new Error("Environment exec aborted");
+  if (typeof reason === "string") return new Error(reason);
+  if (typeof reason === "number" || typeof reason === "boolean" || typeof reason === "bigint") {
+    return new Error(String(reason));
+  }
+  return new Error("Environment exec aborted");
+}
+async function runExecBody(input, defaultTimeoutMs, outputByteLimit, executor) {
+  const start = Date.now();
+  const timeoutMs = input.timeoutMs ?? defaultTimeoutMs;
+  let value;
+  let timedOut;
+  try {
+    ({ value, timedOut } = await runWithTimeout(
+      async () => executor(),
+      timeoutMs,
+      input.signal
+    ));
+  } catch (error) {
+    if (isEnvironmentTimeoutError(error)) {
+      return timedOutExecResult(error, start);
+    }
+    throw error;
+  }
+  const stdoutTrunc = truncateOutput(value.stdout, outputByteLimit);
+  const stderrTrunc = truncateOutput(value.stderr, outputByteLimit);
+  return {
+    stdout: stdoutTrunc.text,
+    stderr: stderrTrunc.text,
+    exitCode: value.exitCode,
+    truncated: stdoutTrunc.truncated || stderrTrunc.truncated,
+    timedOut,
+    durationMs: Date.now() - start
+  };
+}
+async function loadOptionalPeer(packageName) {
+  try {
+    return await import(packageName);
+  } catch (error) {
+    const cause = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `[octoflow-core/environments] missing optional peer '${packageName}'. Install it first: \`yarn add ${packageName}\`. Original error: ${cause}`
+    );
+  }
+}
+export {
+  ENVIRONMENT_DEFAULTS,
+  EnvironmentTimeoutError,
+  assertSafeEnvKey,
+  isEnvironmentTimeoutError,
+  loadOptionalPeer,
+  runExecBody,
+  runWithTimeout,
+  shellQuote,
+  timedOutExecResult,
+  truncateOutput
+};
+//# sourceMappingURL=shared.js.map

package/dist/environments/shared.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/environments/shared.ts"],
+  "sourcesContent": ["/**\n * Shared helpers used by every concrete environment factory.\n */\n\nimport type { ExecInput, ExecResult } from 'octoflow-protocols';\n\nconst DEFAULT_TIMEOUT_MS = 120_000;\nconst DEFAULT_OUTPUT_BYTE_LIMIT = 1_048_576;\nconst SAFE_ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;\n\nexport const ENVIRONMENT_DEFAULTS = {\n  timeoutMs: DEFAULT_TIMEOUT_MS,\n  outputByteLimit: DEFAULT_OUTPUT_BYTE_LIMIT,\n} as const;\n\nexport interface TruncationResult {\n  text: string;\n  truncated: boolean;\n}\n\n/**\n * Truncate a UTF-8 string to a byte budget, preserving the head and a small\n * tail so error context is visible.\n */\nexport function truncateOutput(\n  text: string,\n  byteLimit: number\n): TruncationResult {\n  const buffer = Buffer.from(text, 'utf8');\n  if (buffer.byteLength <= byteLimit) {\n    return { text, truncated: false };\n  }\n  const tailBytes = Math.min(2_048, Math.floor(byteLimit / 8));\n  const headBytes = byteLimit - tailBytes;\n  const head = buffer.subarray(0, headBytes).toString('utf8');\n  const tail = buffer.subarray(buffer.byteLength - tailBytes).toString('utf8');\n  return {\n    text: `${head}\\n... [truncated ${buffer.byteLength - byteLimit} bytes] ...\\n${tail}`,\n    truncated: true,\n  };\n}\n\n/**\n * Race `op` against the caller's `signal` and an internally-managed timeout.\n * The returned tuple gives the operation result plus whether the timeout\n * fired (so the caller can set `timedOut` on `ExecResult`).\n */\nexport interface TimedRunResult<T> {\n  value: T;\n  timedOut: boolean;\n}\n\nexport class EnvironmentTimeoutError extends Error {\n  constructor(readonly timeoutMs: number) {\n    super(`Environment exec timed out after ${timeoutMs}ms`);\n    this.name = 'EnvironmentTimeoutError';\n  }\n}\n\nexport async function runWithTimeout<T>(\n  op: (signal: AbortSignal) => Promise<T>,\n  timeoutMs: number,\n  outerSignal?: AbortSignal\n): Promise<TimedRunResult<T>> {\n  if (outerSignal?.aborted) {\n    throw abortReasonToError(outerSignal.reason);\n  }\n\n  const controller = new AbortController();\n  let rejectAbort: (error: Error) => void = () => {};\n  const abortPromise = new Promise<never>((_resolve, reject) => {\n    rejectAbort = reject;\n  });\n  const abortWith = (error: Error) => {\n    rejectAbort(error);\n    controller.abort(error);\n  };\n  const onAbort = () => abortWith(abortReasonToError(outerSignal?.reason));\n  outerSignal?.addEventListener('abort', onAbort, { once: true });\n\n  let timedOut = false;\n  const timer = setTimeout(() => {\n    timedOut = true;\n    abortWith(new EnvironmentTimeoutError(timeoutMs));\n  }, timeoutMs);\n\n  try {\n    const value = await Promise.race([op(controller.signal), abortPromise]);\n    return { value, timedOut };\n  } finally {\n    clearTimeout(timer);\n    outerSignal?.removeEventListener('abort', onAbort);\n  }\n}\n\nexport function isEnvironmentTimeoutError(\n  error: unknown\n): error is EnvironmentTimeoutError {\n  return error instanceof EnvironmentTimeoutError;\n}\n\nexport function timedOutExecResult(\n  error: EnvironmentTimeoutError,\n  startedAtMs: number\n): ExecResult {\n  return {\n    stdout: '',\n    stderr: `${error.message}\\n`,\n    exitCode: 124,\n    truncated: false,\n    timedOut: true,\n    durationMs: Date.now() - startedAtMs,\n  };\n}\n\nexport function assertSafeEnvKey(key: string): void {\n  if (!SAFE_ENV_KEY_RE.test(key)) {\n    throw new Error(`Unsafe environment variable name: ${key}`);\n  }\n}\n\n/**\n * Single-quote a shell argument, escaping any embedded single-quotes.\n * Safe for POSIX-compatible shells (bash, sh, dash).\n *\n * @example shellQuote(\"it's alive\") \u2192 \"'it'\\\\''s alive'\"\n */\nexport function shellQuote(value: string): string {\n  return `'${value.replace(/'/g, `'\\\\''`)}'`;\n}\n\nfunction abortReasonToError(reason: unknown): Error {\n  if (reason instanceof Error) return reason;\n  if (reason == null) return new Error('Environment exec aborted');\n  if (typeof reason === 'string') return new Error(reason);\n  if (\n    typeof reason === 'number' ||\n    typeof reason === 'boolean' ||\n    typeof reason === 'bigint'\n  ) {\n    return new Error(String(reason));\n  }\n  return new Error('Environment exec aborted');\n}\n\n/**\n * Shared exec body for environment implementations: runs an executor under a\n * timeout, truncates output, and returns a normalized ExecResult. Callers are\n * responsible for resolving the environment-specific resource (container,\n * SSH client, etc.) before passing the executor.\n */\nexport async function runExecBody(\n  input: ExecInput,\n  defaultTimeoutMs: number,\n  outputByteLimit: number,\n  executor: () => Promise<{ stdout: string; stderr: string; exitCode: number }>\n): Promise<ExecResult> {\n  const start = Date.now();\n  const timeoutMs = input.timeoutMs ?? defaultTimeoutMs;\n  let value: { stdout: string; stderr: string; exitCode: number };\n  let timedOut: boolean;\n  try {\n    ({ value, timedOut } = await runWithTimeout(\n      async () => executor(),\n      timeoutMs,\n      input.signal\n    ));\n  } catch (error) {\n    if (isEnvironmentTimeoutError(error)) {\n      return timedOutExecResult(error, start);\n    }\n    throw error;\n  }\n  const stdoutTrunc = truncateOutput(value.stdout, outputByteLimit);\n  const stderrTrunc = truncateOutput(value.stderr, outputByteLimit);\n  return {\n    stdout: stdoutTrunc.text,\n    stderr: stderrTrunc.text,\n    exitCode: value.exitCode,\n    truncated: stdoutTrunc.truncated || stderrTrunc.truncated,\n    timedOut,\n    durationMs: Date.now() - start,\n  };\n}\n\n/**\n * Best-effort dynamic import for an optional peer SDK. Throws a developer-\n * facing error message naming the missing package so the user knows what to\n * install.\n */\nexport async function loadOptionalPeer<T>(packageName: string): Promise<T> {\n  try {\n    return (await import(packageName)) as T;\n  } catch (error) {\n    const cause = error instanceof Error ? error.message : String(error);\n    throw new Error(\n      `[octoflow-core/environments] missing optional peer '${packageName}'. Install it first: \\`yarn add ${packageName}\\`. Original error: ${cause}`\n    );\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/environments/ssh.d.ts

@@ -0,0 +1,33 @@
+import type { ExecutionEnvironment } from 'octoflow-protocols';
+export interface SshEnvironmentOptions {
+    host: string;
+    port?: number;
+    username: string;
+    password?: string;
+    privateKey?: string | Buffer;
+    passphrase?: string;
+    /** Pass-through for advanced ssh2 options. */
+    connectOptions?: Record<string, unknown>;
+    defaultTimeoutMs?: number;
+    outputByteLimit?: number;
+    /** Inject a pre-built `ssh2.Client` (used by tests). */
+    client?: SshClientLike;
+}
+export interface SshClientLike {
+    connect(opts: Record<string, unknown>): unknown;
+    end(): unknown;
+    exec(command: string, options: Record<string, unknown>, cb: (err: Error | undefined, channel: SshChannelLike) => void): unknown;
+    on(event: 'ready', listener: () => void): unknown;
+    on(event: 'error', listener: (err: Error) => void): unknown;
+    once(event: 'ready', listener: () => void): unknown;
+    once(event: 'error', listener: (err: Error) => void): unknown;
+}
+export interface SshChannelLike extends NodeJS.ReadableStream {
+    stderr: NodeJS.ReadableStream;
+    end(stdin?: string): unknown;
+    on(event: 'close', listener: (code: number | null, signal?: string) => void): this;
+    on(event: 'data', listener: (chunk: Buffer) => void): this;
+    on(event: 'error', listener: (err: Error) => void): this;
+}
+export declare function createSshEnvironment(opts: SshEnvironmentOptions): ExecutionEnvironment;
+//# sourceMappingURL=ssh.d.ts.map

package/dist/environments/ssh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssh.d.ts","sourceRoot":"","sources":["../../src/environments/ssh.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAIV,oBAAoB,EACrB,MAAM,oBAAoB,CAAC;AAW5B,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;IAChD,GAAG,IAAI,OAAO,CAAC;IACf,IAAI,CACF,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,EAAE,EAAE,CAAC,GAAG,EAAE,KAAK,GAAG,SAAS,EAAE,OAAO,EAAE,cAAc,KAAK,IAAI,GAC5D,OAAO,CAAC;IACX,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IAClD,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC;IAC5D,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IACpD,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC;CAC/D;AAED,MAAM,WAAW,cAAe,SAAQ,MAAM,CAAC,cAAc;IAC3D,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,EAAE,CACA,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,GACvD,IAAI,CAAC;IACR,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAC3D,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;CAC1D;AAWD,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,qBAAqB,GAC1B,oBAAoB,CAoCtB"}