@compforge/harness-toolbox 0.1.0

package/dist/chunk-xy4g56g4.js

@@ -0,0 +1,50 @@
+// src/transport/index.ts
+class DirectTransport {
+  kind = "tcp";
+  name = "direct";
+  async connect(endpoint) {
+    return endpoint;
+  }
+}
+
+class PortForwardTransport {
+  forward;
+  kind = "tcp";
+  name = "port-forward";
+  constructor(forward) {
+    this.forward = forward;
+  }
+  connect(endpoint) {
+    return this.forward(endpoint);
+  }
+}
+
+class PodPythonTransport {
+  exec;
+  python;
+  kind = "python";
+  name = "pod-python";
+  constructor(exec, python = "python") {
+    this.exec = exec;
+    this.python = python;
+  }
+  run(script, input, timeoutMs) {
+    return this.exec([this.python, "-c", script], { stdin: JSON.stringify(input), timeoutMs });
+  }
+}
+function isConnectionNetworkError(error) {
+  if (!error || typeof error !== "object" || !("code" in error))
+    return false;
+  return [
+    "ECONNREFUSED",
+    "ETIMEDOUT",
+    "ECONNRESET",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "EADDRNOTAVAIL",
+    "ENOTFOUND",
+    "EAI_AGAIN"
+  ].includes(String(error.code));
+}
+
+export { DirectTransport, PortForwardTransport, PodPythonTransport, isConnectionNetworkError };

package/dist/chunk-ztenxgjv.js

@@ -0,0 +1,27 @@
+// src/process/index.ts
+import { spawn } from "node:child_process";
+import { Readable } from "node:stream";
+function spawnProcess(argv, opts) {
+  if (!argv.length)
+    throw new Error("command argv cannot be empty");
+  const child = spawn(argv[0], argv.slice(1), {
+    stdio: "pipe",
+    env: opts?.env
+  });
+  child.stdin.end(opts?.stdin);
+  const exited = new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("close", (code) => resolve(code ?? 1));
+  });
+  return {
+    stdout: Readable.toWeb(child.stdout),
+    stderr: Readable.toWeb(child.stderr),
+    exited,
+    kill: () => child.kill()
+  };
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export { spawnProcess, sleep };

package/dist/client-manager.d.ts

@@ -0,0 +1,14 @@
+import type { Client } from "./client";
+import type { DataSource } from "./datasource";
+/** Consumers borrow clients; only the root owner receives the disposal capability. */
+export interface ClientProvider {
+    get<C extends Client>(source: DataSource<C>): Promise<C>;
+}
+/** @spec One root execution shares successful initialization per identity and closes clients at finalize. */
+export declare class ClientManager implements ClientProvider {
+    #private;
+    readonly signal: AbortSignal;
+    constructor(signal?: AbortSignal);
+    get<C extends Client>(source: DataSource<C>): Promise<C>;
+    dispose(): Promise<void>;
+}

package/dist/client-manager.js

@@ -0,0 +1,6 @@
+import {
+  ClientManager
+} from "./chunk-3dt25p98.js";
+export {
+  ClientManager
+};

package/dist/client.d.ts

@@ -0,0 +1,5 @@
+/** A protocol client owns its initialization and idempotent cleanup, including partial initialization. */
+export interface Client {
+    initialize(): Promise<void>;
+    dispose(): Promise<void>;
+}

package/dist/concurrency.d.ts

@@ -0,0 +1,7 @@
+/** FIFO slots shared by callers; queued cancellation never starts external work. */
+export declare class ConcurrencyPool {
+    #private;
+    readonly concurrency: number;
+    constructor(concurrency: number);
+    run<T>(work: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+}

package/dist/concurrency.js

@@ -0,0 +1,6 @@
+import {
+  ConcurrencyPool
+} from "./chunk-v3hxvnrc.js";
+export {
+  ConcurrencyPool
+};

package/dist/datasource.d.ts

@@ -0,0 +1,26 @@
+export type { Client } from "./client";
+export { ClientManager, type ClientProvider } from "./client-manager";
+import type { Client } from "./client";
+import type { Transport } from "./transport";
+/** Identity must include protocol, target, configuration and credentials; never an object address. */
+export interface DataSource<C extends Client> {
+    readonly key: string;
+    /** Construct only; Client.initialize owns external work. */
+    createClient(signal: AbortSignal): C;
+}
+/** Resolution owns configuration semantics; transports preserve the resolved target and identity. */
+export interface ConnectionSource<Target> {
+    resolve(): Promise<Target>;
+    readonly transports: readonly Transport[];
+}
+export interface ClientLifecycle {
+    signal?: AbortSignal;
+    onDispose?: (dispose: () => Promise<void>) => void;
+    /** Safe route facts only: no credentials, SQL or protocol payloads. */
+    onRoute?: (route: {
+        transport: string;
+        reason?: string;
+    }) => void;
+}
+/** Stable in-memory identity; connection credentials must not appear in observable cache keys. */
+export declare function dataSourceKey(protocol: string, configuration: unknown): string;

package/dist/datasource.js

@@ -0,0 +1,10 @@
+import {
+  dataSourceKey
+} from "./chunk-hqx7j9xe.js";
+import {
+  ClientManager
+} from "./chunk-3dt25p98.js";
+export {
+  dataSourceKey,
+  ClientManager
+};

package/dist/kubernetes/client-node-pod-log.d.ts

@@ -0,0 +1,31 @@
+import type { RequestInfo, RequestInit, Response } from "node-fetch";
+import type { ExecResult } from "./executor";
+import type { KubernetesPodLogAccess, PodLogRequest, PodLogResult, ServicePodListResult } from "./pod-log";
+export interface ClientNodeLogPolicy {
+    idleTimeoutMs: number;
+    hardTimeoutMs: number;
+    maxAttempts: number;
+}
+export type ClientNodeFetch = (url: RequestInfo, init?: RequestInit) => Promise<Response>;
+export declare const DEFAULT_CLIENT_NODE_LOG_POLICY: ClientNodeLogPolicy;
+export interface ClientNodePodLogOptions {
+    namespace: string;
+    signal?: AbortSignal;
+    kubeconfig?: string;
+    context?: string;
+    policy?: Partial<ClientNodeLogPolicy>;
+    /** Transport seam for deterministic tests; production uses node-fetch. */
+    fetchImpl?: ClientNodeFetch;
+}
+/**
+ * 迁移期组合：Service/Pod 发现仍走既有 access，只有高体量 Pod Log transport 改为 API 流。
+ * 调用侧不需要知道两种 transport；后续发现层 API 化时可直接替换 delegate。
+ */
+export declare class ClientNodePodLogAccess implements KubernetesPodLogAccess {
+    private readonly discovery;
+    private readonly transport;
+    constructor(discovery: KubernetesPodLogAccess, options: ClientNodePodLogOptions);
+    clientVersion(): Promise<ExecResult>;
+    listServicePods(services: readonly string[]): Promise<ServicePodListResult>;
+    collectPodLogs(request: PodLogRequest): Promise<PodLogResult>;
+}

package/dist/kubernetes/client-node-pod-log.js

@@ -0,0 +1,425 @@
+import {
+  logTimestampNanos
+} from "../chunk-mp88s7r7.js";
+
+// src/kubernetes/client-node-pod-log.ts
+import { closeSync, openSync, writeSync } from "node:fs";
+import { KubeConfig } from "@kubernetes/client-node";
+import fetch from "node-fetch/lib/index.js";
+var DEFAULT_CLIENT_NODE_LOG_POLICY = {
+  idleTimeoutMs: 15000,
+  hardTimeoutMs: 120000,
+  maxAttempts: 2
+};
+var RFC3339_LINE = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2}))(?:\s|$)/;
+var RECENT_LINE_LIMIT = 256;
+function parseSinceSeconds(value) {
+  const input = value.trim();
+  if (!input)
+    return;
+  const units = {
+    ns: 0.000000001,
+    us: 0.000001,
+    "µs": 0.000001,
+    ms: 0.001,
+    s: 1,
+    m: 60,
+    h: 3600
+  };
+  let seconds = 0;
+  let cursor = 0;
+  const segment = /(\d+(?:\.\d+)?)(ns|us|µs|ms|s|m|h)/gy;
+  while (cursor < input.length) {
+    segment.lastIndex = cursor;
+    const match = segment.exec(input);
+    if (!match)
+      return;
+    seconds += Number(match[1]) * units[match[2]];
+    cursor = segment.lastIndex;
+  }
+  return Math.max(1, Math.ceil(seconds));
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function logCommand(namespace, request) {
+  const command = [
+    "kubernetes-api",
+    "logs",
+    "-n",
+    namespace,
+    request.pod
+  ];
+  if (request.container)
+    command.push("-c", request.container);
+  if (request.previous)
+    command.push("--previous");
+  if (request.tail !== undefined)
+    command.push(`--tail=${request.tail}`);
+  if (request.limitBytes !== undefined)
+    command.push(`--limit-bytes=${request.limitBytes}`);
+  if (request.sinceTime)
+    command.push(`--since-time=${request.sinceTime}`);
+  else if (request.since)
+    command.push(`--since=${request.since}`);
+  if (request.untilTime)
+    command.push(`--until-time=${request.untilTime}`);
+  return command;
+}
+
+class ClientNodeLogTransport {
+  options;
+  kubeConfig = new KubeConfig;
+  policy;
+  initializationError;
+  constructor(options) {
+    this.options = options;
+    this.policy = { ...DEFAULT_CLIENT_NODE_LOG_POLICY, ...options.policy };
+    try {
+      if (this.policy.idleTimeoutMs < 1 || this.policy.hardTimeoutMs < 1) {
+        throw new Error("Pod Log timeout 必须为正数");
+      }
+      if (!Number.isInteger(this.policy.maxAttempts) || this.policy.maxAttempts < 1) {
+        throw new Error("Pod Log maxAttempts 必须是正整数");
+      }
+      if (options.kubeconfig)
+        this.kubeConfig.loadFromFile(options.kubeconfig);
+      else
+        this.kubeConfig.loadFromDefault();
+      if (options.context)
+        this.kubeConfig.setCurrentContext(options.context);
+      const cluster = this.kubeConfig.getCurrentCluster();
+      if (!cluster) {
+        throw new Error(`kubeconfig context '${this.kubeConfig.getCurrentContext()}' 没有关联 cluster`);
+      }
+      if (new URL(cluster.server).protocol === "http:") {
+        this.kubeConfig.clusters = this.kubeConfig.clusters.map((item) => item === cluster ? { ...item, skipTLSVerify: true } : item);
+      }
+    } catch (error) {
+      this.initializationError = errorMessage(error);
+    }
+  }
+  async capture(request) {
+    this.options.signal?.throwIfAborted();
+    const command = logCommand(this.options.namespace, request);
+    const startedAt = Date.now();
+    if (this.initializationError) {
+      return this.unavailable(command, startedAt, `kubeconfig 初始化失败：${this.initializationError}`);
+    }
+    if (!request.container) {
+      return this.unavailable(command, startedAt, "Kubernetes Pod Log API 要求指定 container");
+    }
+    const sinceSeconds = request.since && !request.sinceTime ? parseSinceSeconds(request.since) : undefined;
+    if (request.since && !request.sinceTime && sinceSeconds === undefined) {
+      return this.unavailable(command, startedAt, `无法解析日志时间窗口：${request.since}`);
+    }
+    const untilNanos = request.untilTime === undefined ? undefined : logTimestampNanos(request.untilTime);
+    if (request.untilTime !== undefined && untilNanos === undefined) {
+      return this.unavailable(command, startedAt, "untilTime 必须是 RFC3339 时间戳");
+    }
+    const fd = request.rawFilePath ? openSync(request.rawFilePath, "w", 384) : undefined;
+    const output = [];
+    let rawChunks = [];
+    let rawBytes = 0;
+    const flushRaw = () => {
+      if (fd !== undefined && rawChunks.length)
+        writeSync(fd, rawChunks.join(""));
+      rawChunks = [];
+      rawBytes = 0;
+    };
+    const recentLines = [];
+    const recentLineSet = new Set;
+    const errors = [];
+    let attempts = 0;
+    let totalBytesRead = 0;
+    let resumeSinceTime = request.sinceTime;
+    let timedOut = false;
+    let finalStatusCode;
+    const hardDeadline = startedAt + this.policy.hardTimeoutMs;
+    const emitLine = (line, deduplicate) => {
+      if (deduplicate && recentLineSet.has(line))
+        return;
+      const prefix = request.prefix ? `[pod/${request.pod}/${request.container}] ` : "";
+      const rendered = `${prefix}${line}`;
+      request.onLine?.(rendered);
+      if (fd !== undefined) {
+        const chunk = `${rendered}
+`;
+        rawChunks.push(chunk);
+        rawBytes += Buffer.byteLength(chunk);
+        if (rawBytes >= 64 * 1024)
+          flushRaw();
+      } else if (request.collectStdout !== false)
+        output.push(rendered);
+      recentLines.push(line);
+      recentLineSet.add(line);
+      if (recentLines.length > RECENT_LINE_LIMIT) {
+        recentLineSet.delete(recentLines.shift());
+      }
+    };
+    try {
+      while (attempts < this.policy.maxAttempts) {
+        if (this.options.signal?.aborted)
+          break;
+        const remainingHardTimeoutMs = hardDeadline - Date.now();
+        if (remainingHardTimeoutMs <= 0) {
+          timedOut = true;
+          errors.push(`hard_timeout（hard=${this.policy.hardTimeoutMs}ms）`);
+          break;
+        }
+        const remainingBytes = request.limitBytes === undefined ? undefined : Math.max(0, request.limitBytes - totalBytesRead);
+        if (remainingBytes === 0)
+          break;
+        attempts += 1;
+        const attempt = await this.captureAttempt({
+          request: remainingBytes === undefined ? request : { ...request, limitBytes: remainingBytes },
+          sinceSeconds,
+          untilNanos,
+          sinceTime: resumeSinceTime,
+          hardTimeoutMs: remainingHardTimeoutMs,
+          deduplicate: attempts > 1,
+          emitLine
+        });
+        totalBytesRead += attempt.bytesRead;
+        timedOut ||= attempt.timedOut;
+        finalStatusCode = attempt.statusCode;
+        if (attempt.lastTimestamp)
+          resumeSinceTime = attempt.lastTimestamp;
+        if (attempt.ok) {
+          const limited = !attempt.windowComplete && request.limitBytes !== undefined && totalBytesRead >= request.limitBytes;
+          return {
+            ok: !limited,
+            exitCode: limited ? null : 0,
+            stdout: output.length ? `${output.join(`
+`)}
+` : "",
+            stderr: limited ? `日志达到单次字节上限 ${request.limitBytes}` : "",
+            durationMs: Date.now() - startedAt,
+            timedOut,
+            command,
+            captureStatus: limited ? "partial" : "complete",
+            reason: limited ? "byte_limit" : undefined,
+            bytesRead: totalBytesRead,
+            attempts
+          };
+        }
+        errors.push(attempt.error ?? "Kubernetes Pod Log API 请求失败");
+        if (this.options.signal?.aborted || !attempt.retryable || attempts >= this.policy.maxAttempts)
+          break;
+      }
+    } finally {
+      try {
+        flushRaw();
+      } finally {
+        if (fd !== undefined)
+          closeSync(fd);
+      }
+    }
+    const captureStatus = totalBytesRead > 0 ? "partial" : "unavailable";
+    const byteLimitReached = request.limitBytes !== undefined && totalBytesRead >= request.limitBytes;
+    if (byteLimitReached)
+      errors.push(`日志达到单次字节上限 ${request.limitBytes}`);
+    return {
+      ok: false,
+      exitCode: finalStatusCode ?? null,
+      stdout: output.length ? `${output.join(`
+`)}
+` : "",
+      stderr: errors.join(`
+`),
+      durationMs: Date.now() - startedAt,
+      timedOut,
+      command,
+      captureStatus,
+      reason: this.options.signal?.aborted ? "cancelled" : byteLimitReached ? "byte_limit" : timedOut ? "timeout" : "transport_error",
+      bytesRead: totalBytesRead,
+      attempts
+    };
+  }
+  unavailable(command, startedAt, reason) {
+    return {
+      ok: false,
+      exitCode: null,
+      stdout: "",
+      stderr: reason,
+      durationMs: Date.now() - startedAt,
+      timedOut: false,
+      command,
+      captureStatus: "unavailable",
+      reason,
+      bytesRead: 0,
+      attempts: 0
+    };
+  }
+  async captureAttempt(input) {
+    const cluster = this.kubeConfig.getCurrentCluster();
+    const path = `/api/v1/namespaces/${encodeURIComponent(this.options.namespace)}` + `/pods/${encodeURIComponent(input.request.pod)}/log`;
+    const url = new URL(path, cluster.server.endsWith("/") ? cluster.server : `${cluster.server}/`);
+    url.searchParams.set("container", input.request.container);
+    url.searchParams.set("follow", "false");
+    url.searchParams.set("timestamps", "true");
+    if (input.request.previous)
+      url.searchParams.set("previous", "true");
+    if (input.request.tail !== undefined)
+      url.searchParams.set("tailLines", String(input.request.tail));
+    if (input.request.limitBytes !== undefined) {
+      url.searchParams.set("limitBytes", String(input.request.limitBytes));
+    }
+    if (input.sinceTime)
+      url.searchParams.set("sinceTime", input.sinceTime);
+    else if (input.sinceSeconds !== undefined) {
+      url.searchParams.set("sinceSeconds", String(input.sinceSeconds));
+    }
+    const controller = new AbortController;
+    const commandSignal = this.options.signal;
+    const abort = () => controller.abort(commandSignal?.reason);
+    commandSignal?.addEventListener("abort", abort, { once: true });
+    if (commandSignal?.aborted)
+      abort();
+    let abortReason;
+    let idleTimer;
+    const resetIdleTimer = () => {
+      clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => {
+        abortReason = "idle_timeout";
+        controller.abort();
+      }, this.policy.idleTimeoutMs);
+    };
+    resetIdleTimer();
+    const hardTimer = setTimeout(() => {
+      abortReason = "hard_timeout";
+      controller.abort();
+    }, input.hardTimeoutMs);
+    const decoder = new TextDecoder;
+    let pending = "";
+    let bytesRead = 0;
+    let lastTimestamp;
+    let windowComplete = false;
+    const emit = (line) => {
+      const timestamp = line.match(RFC3339_LINE)?.[1];
+      const nanos = timestamp && input.untilNanos !== undefined ? logTimestampNanos(timestamp) : undefined;
+      if (nanos !== undefined && input.untilNanos !== undefined && nanos > input.untilNanos) {
+        windowComplete = true;
+        return;
+      }
+      if (timestamp)
+        lastTimestamp = timestamp;
+      input.emitLine(line, input.deduplicate);
+    };
+    const consume = (text) => {
+      pending += text;
+      const lines = pending.split(/\r?\n/);
+      pending = lines.pop() ?? "";
+      for (const line of lines) {
+        emit(line);
+        if (windowComplete)
+          break;
+      }
+    };
+    try {
+      const init = await this.kubeConfig.applyToFetchOptions({});
+      const response = await (this.options.fetchImpl ?? fetch)(url, {
+        ...init,
+        method: "GET",
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const body = (await response.text()).trim().slice(0, 2000);
+        return {
+          ok: false,
+          retryable: response.status === 408 || response.status === 429 || response.status >= 500,
+          timedOut: false,
+          error: `Kubernetes Pod Log API HTTP ${response.status}${body ? `: ${body}` : ""}`,
+          statusCode: response.status,
+          bytesRead
+        };
+      }
+      if (!response.body) {
+        return {
+          ok: false,
+          retryable: true,
+          timedOut: false,
+          error: "Kubernetes Pod Log API 返回空响应流",
+          statusCode: response.status,
+          bytesRead
+        };
+      }
+      response.body.on("error", () => {
+        return;
+      });
+      for await (const raw of response.body) {
+        const chunk = raw instanceof Uint8Array ? raw : Buffer.from(raw);
+        bytesRead += chunk.byteLength;
+        resetIdleTimer();
+        consume(decoder.decode(chunk, { stream: true }));
+        if (windowComplete) {
+          controller.abort();
+          return { ok: true, retryable: false, timedOut: false, bytesRead, lastTimestamp, windowComplete: true };
+        }
+      }
+      commandSignal?.throwIfAborted();
+      consume(decoder.decode());
+      if (pending && !windowComplete)
+        emit(pending);
+      if (abortReason) {
+        return {
+          ok: false,
+          retryable: true,
+          timedOut: true,
+          error: `${abortReason}（idle=${this.policy.idleTimeoutMs}ms, hard=${this.policy.hardTimeoutMs}ms）`,
+          statusCode: response.status,
+          bytesRead,
+          lastTimestamp
+        };
+      }
+      return {
+        ok: true,
+        retryable: false,
+        timedOut: false,
+        statusCode: response.status,
+        bytesRead,
+        lastTimestamp,
+        windowComplete
+      };
+    } catch (error) {
+      if (windowComplete && !commandSignal?.aborted) {
+        return { ok: true, retryable: false, timedOut: false, bytesRead, lastTimestamp, windowComplete: true };
+      }
+      const timedOut = abortReason !== undefined;
+      return {
+        ok: false,
+        retryable: true,
+        timedOut,
+        error: timedOut ? `${abortReason}（idle=${this.policy.idleTimeoutMs}ms, hard=${this.policy.hardTimeoutMs}ms）` : errorMessage(error),
+        bytesRead,
+        lastTimestamp
+      };
+    } finally {
+      commandSignal?.removeEventListener("abort", abort);
+      clearTimeout(idleTimer);
+      clearTimeout(hardTimer);
+    }
+  }
+}
+
+class ClientNodePodLogAccess {
+  discovery;
+  transport;
+  constructor(discovery, options) {
+    this.discovery = discovery;
+    this.transport = new ClientNodeLogTransport(options);
+  }
+  clientVersion() {
+    return this.discovery.clientVersion();
+  }
+  listServicePods(services) {
+    return this.discovery.listServicePods(services);
+  }
+  collectPodLogs(request) {
+    return this.transport.capture(request);
+  }
+}
+export {
+  DEFAULT_CLIENT_NODE_LOG_POLICY,
+  ClientNodePodLogAccess
+};

package/dist/kubernetes/client.d.ts

@@ -0,0 +1,17 @@
+import type { Client } from "../client";
+import { type Executor, type KubectlOptions, type ExecTarget, type RunOptions } from "./executor";
+import type { KubernetesEndpoint } from "./endpoint";
+/** Owns cluster transports; protocol callers borrow this client without closing it. */
+export declare class KubernetesClient implements Client {
+    #private;
+    private readonly kube;
+    readonly signal: AbortSignal;
+    constructor(kube: KubectlOptions & {
+        namespace: string;
+    }, signal?: AbortSignal, executor?: Executor);
+    initialize(): Promise<void>;
+    run(namespace: string, command: string[], options?: RunOptions): Promise<import("./executor").ExecResult>;
+    exec(namespace: string, target: ExecTarget, command: string[], options?: RunOptions): Promise<import("./executor").ExecResult>;
+    forward(namespace: string, target: KubernetesEndpoint): Promise<import("./service-port-forward").ForwardedEndpoint>;
+    dispose(): Promise<void>;
+}