@compforge/harness-toolbox 0.1.0

package/dist/kubernetes/service.d.ts

@@ -0,0 +1,31 @@
+import type { Executor } from "./executor";
+import type { KubernetesEndpoint } from "./endpoint";
+import { type KubernetesPod } from "./pod";
+export interface KubernetesServicePort {
+    name?: string;
+    port: number;
+    targetPort?: string | number;
+}
+export interface KubernetesService {
+    kind: "service";
+    namespace: string;
+    name: string;
+    clusterIP?: string;
+    selector: Record<string, string>;
+    ports: KubernetesServicePort[];
+}
+export declare function parseServices(raw: string, defaultNamespace: string): KubernetesService[];
+/** 只接受 Kubernetes 的稳定 Service DNS 形态，避免把普通域名误判成集群资源。 */
+export declare function serviceIdentity(host: string, defaultNamespace: string): {
+    name: string;
+    namespace: string;
+} | undefined;
+export declare function findService(services: readonly KubernetesService[], endpoint: KubernetesEndpoint, defaultNamespace: string): KubernetesService | undefined;
+/** Pod → Service 保持一对多；选择哪个 Service/port 是调用方的配置确认职责。 */
+export declare function findServicesForPod(services: readonly KubernetesService[], pod: KubernetesPod): KubernetesService[];
+/** Service → Pod 由 Kubernetes selector 决定，不让上层用 Pod 名称前缀猜测。 */
+export declare function findPodsForService(services: readonly KubernetesService[], pods: readonly KubernetesPod[], serviceName: string, namespace: string): KubernetesPod[];
+export declare function listServiceNetwork(executor: Executor, namespace: string): Promise<{
+    services: KubernetesService[];
+    pods: KubernetesPod[];
+}>;

package/dist/kubernetes/service.js

@@ -0,0 +1,17 @@
+import {
+  findPodsForService,
+  findService,
+  findServicesForPod,
+  listServiceNetwork,
+  parseServices,
+  serviceIdentity
+} from "../chunk-j46x7j7c.js";
+import"../chunk-6fnhzhdb.js";
+export {
+  serviceIdentity,
+  parseServices,
+  listServiceNetwork,
+  findServicesForPod,
+  findService,
+  findPodsForService
+};

package/dist/mysql/client.d.ts

@@ -0,0 +1,36 @@
+import type { Client } from "../client";
+import { type Connection, type ConnectionOptions } from "mysql2/promise";
+import type { Database, DatabaseTarget, DatabaseRow } from "./types";
+import type { ConnectionSource, ClientLifecycle } from "../datasource";
+import { type Transport } from "../transport";
+export interface MysqlDatabaseOptions extends ClientLifecycle {
+    connectTimeoutMs: number;
+    queryTimeoutMs: number;
+}
+type ConnectionFactory = (options: ConnectionOptions) => Promise<Connection>;
+/** SQL is executed once; only native connection establishment may advance to another transport. */
+export declare class MysqlDatabase implements Database {
+    #private;
+    private readonly transports;
+    private readonly options;
+    private readonly connect;
+    constructor(transports: readonly Transport[], options: MysqlDatabaseOptions, connect?: ConnectionFactory);
+    query(target: DatabaseTarget, sql: string, values: readonly unknown[]): Promise<DatabaseRow[]>;
+    initialize(target: DatabaseTarget): Promise<void>;
+    queryOne(target: DatabaseTarget, sql: string, values: readonly unknown[]): Promise<DatabaseRow | undefined>;
+    close(): Promise<void>;
+}
+/** A datasource-bound MySQL client; the protocol adapter still supports explicit multi-target diagnostics. */
+export declare class MysqlClient<Target extends DatabaseTarget = DatabaseTarget> implements Client {
+    #private;
+    private readonly source;
+    private readonly options;
+    readonly signal: AbortSignal;
+    constructor(source: ConnectionSource<Target>, options: MysqlDatabaseOptions);
+    initialize(): Promise<void>;
+    get database(): Database;
+    get target(): Target;
+    dispose(): Promise<void>;
+}
+export declare function openMysql<Target extends DatabaseTarget>(source: ConnectionSource<Target>, options: MysqlDatabaseOptions): Promise<MysqlClient<Target>>;
+export {};

package/dist/mysql/client.js

@@ -0,0 +1,13 @@
+import {
+  MysqlClient,
+  MysqlDatabase,
+  openMysql
+} from "../chunk-mkhyty75.js";
+import"../chunk-v3hxvnrc.js";
+import"../chunk-s06hs7a8.js";
+import"../chunk-xy4g56g4.js";
+export {
+  openMysql,
+  MysqlDatabase,
+  MysqlClient
+};

package/dist/mysql/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./target";
+export * from "./client";

package/dist/mysql/index.js

@@ -0,0 +1,18 @@
+import {
+  MysqlClient,
+  MysqlDatabase,
+  openMysql
+} from "../chunk-mkhyty75.js";
+import"../chunk-v3hxvnrc.js";
+import {
+  parseMysqlEnvTarget
+} from "../chunk-qq77x9ek.js";
+import"../chunk-pfar9cm3.js";
+import"../chunk-s06hs7a8.js";
+import"../chunk-xy4g56g4.js";
+export {
+  parseMysqlEnvTarget,
+  openMysql,
+  MysqlDatabase,
+  MysqlClient
+};

package/dist/mysql/pod.d.ts

@@ -0,0 +1,7 @@
+import type { DatabaseRow, DatabaseTarget } from "./types";
+import type { PodPythonTransport } from "../transport";
+export declare function preparePodSql(sql: string, values: readonly unknown[]): string;
+export declare function queryMysqlViaPod(transport: PodPythonTransport, target: DatabaseTarget, sql: string, values: readonly unknown[], options: {
+    connectTimeoutMs: number;
+    queryTimeoutMs: number;
+}): Promise<DatabaseRow[]>;

package/dist/mysql/pod.js

@@ -0,0 +1,8 @@
+import {
+  preparePodSql,
+  queryMysqlViaPod
+} from "../chunk-s06hs7a8.js";
+export {
+  queryMysqlViaPod,
+  preparePodSql
+};

package/dist/mysql/target.d.ts

@@ -0,0 +1,12 @@
+import type { DatabaseIdentity, DatabaseTarget } from "./types";
+export interface MysqlTarget extends DatabaseTarget {
+    credentialSource: "service-env" | "profile";
+}
+export interface DatabaseEnvTargetOptions {
+    label: string;
+    prefix: string;
+    fallback?: DatabaseIdentity;
+    defaultPort?: number;
+}
+/** Parse a database endpoint and credentials from a service environment dump. */
+export declare function parseMysqlEnvTarget(raw: string, options: DatabaseEnvTargetOptions): MysqlTarget;

package/dist/mysql/target.js

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

package/dist/mysql/types.d.ts

@@ -0,0 +1,16 @@
+export interface DatabaseIdentity {
+    user: string;
+    password: string;
+}
+export interface DatabaseTarget extends DatabaseIdentity {
+    host: string;
+    port: number;
+    database: string;
+}
+export type DatabaseRow = Record<string, unknown>;
+/** Storage-neutral operations shared by infrastructure consumers. */
+export interface Database {
+    query(target: DatabaseTarget, sql: string, values: readonly unknown[]): Promise<DatabaseRow[]>;
+    queryOne(target: DatabaseTarget, sql: string, values: readonly unknown[]): Promise<DatabaseRow | undefined>;
+    close(): Promise<void>;
+}

package/dist/mysql/types.js

@@ -0,0 +1 @@
+import"../chunk-pfar9cm3.js";

package/dist/opensearch/client.d.ts

@@ -0,0 +1,62 @@
+import type { Client as ManagedClient } from "../client";
+import type { ConnectionSource, ClientLifecycle } from "../datasource";
+import type { SearchEngine, SearchQuery, SearchResult } from "./types";
+export interface OpenSearchAuth {
+    username?: string;
+    password?: string;
+}
+export interface OpenSearchOptions {
+    node: string;
+    auth: OpenSearchAuth;
+    requestTimeoutMs?: number;
+}
+export interface OpenSearchClientApi {
+    count(params: Record<string, unknown>): Promise<{
+        body: {
+            count: number;
+        };
+    }>;
+    search(params: Record<string, unknown>): Promise<{
+        body: SearchResult;
+    }>;
+    ping(params?: Record<string, unknown>): Promise<unknown>;
+    transport?: {
+        request(params: {
+            method: string;
+            path: string;
+            querystring?: Record<string, unknown>;
+        }): Promise<{
+            body: unknown;
+        }>;
+    };
+    close(): Promise<void>;
+}
+/** OpenSearch-specific read APIs stay outside the engine-neutral SearchEngine contract. */
+export interface OpenSearchReadApi extends SearchEngine {
+    request(path: string, query?: SearchQuery): Promise<unknown>;
+}
+export declare function isOpenSearchReadApi(search: SearchEngine): search is OpenSearchReadApi;
+/** Official OpenSearch client behind the engine-neutral SearchEngine contract. */
+export declare class OpenSearchEngine implements OpenSearchReadApi {
+    private readonly client;
+    constructor(options: OpenSearchOptions, client?: OpenSearchClientApi);
+    count(index: string, query: SearchQuery): Promise<number>;
+    search(index: string, body: SearchQuery): Promise<SearchResult>;
+    request(path: string, query?: SearchQuery): Promise<unknown>;
+    ping(): Promise<unknown>;
+    close(): Promise<void>;
+}
+export declare class OpenSearchClient implements ManagedClient, OpenSearchReadApi {
+    #private;
+    private readonly source;
+    readonly signal: AbortSignal;
+    constructor(source: ConnectionSource<OpenSearchOptions>, lifecycle?: ClientLifecycle);
+    initialize(): Promise<void>;
+    count(index: string, query: SearchQuery): Promise<number>;
+    search(index: string, body: SearchQuery): Promise<SearchResult>;
+    request(path: string, query?: SearchQuery): Promise<unknown>;
+    ping(): Promise<unknown>;
+    close(): Promise<void>;
+    dispose(): Promise<void>;
+}
+export declare function openOpenSearch(source: ConnectionSource<OpenSearchOptions>, lifecycle?: ClientLifecycle): Promise<OpenSearchClient>;

package/dist/opensearch/client.js

@@ -0,0 +1,12 @@
+import {
+  OpenSearchClient,
+  OpenSearchEngine,
+  isOpenSearchReadApi,
+  openOpenSearch
+} from "../chunk-w3a4p6jm.js";
+export {
+  openOpenSearch,
+  isOpenSearchReadApi,
+  OpenSearchEngine,
+  OpenSearchClient
+};

package/dist/opensearch/endpoint.d.ts

@@ -0,0 +1,16 @@
+export interface ParsedOpenSearchEndpoint {
+    url: string;
+    safeUrl: string;
+    safeEndpoint: string;
+    host: string;
+    port: number;
+    scheme: "http" | "https";
+    schemeExplicit: boolean;
+    username?: string;
+    password?: string;
+}
+/**
+ * 连接串只在执行态保留 userinfo；任何可记录的 endpoint 必须使用 safeUrl。
+ * OPENSEARCH_ENDPOINTS 常见为逗号分隔，这里选择第一个节点作为稳定访问入口。
+ */
+export declare function parseOpenSearchEndpoint(value: string): ParsedOpenSearchEndpoint;

package/dist/opensearch/endpoint.js

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

package/dist/opensearch/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./client";
+export * from "./endpoint";
+export * from "./types";

package/dist/opensearch/index.js

@@ -0,0 +1,17 @@
+import {
+  parseOpenSearchEndpoint
+} from "../chunk-s1sjyem7.js";
+import"../chunk-djk4kmxb.js";
+import {
+  OpenSearchClient,
+  OpenSearchEngine,
+  isOpenSearchReadApi,
+  openOpenSearch
+} from "../chunk-w3a4p6jm.js";
+export {
+  parseOpenSearchEndpoint,
+  openOpenSearch,
+  isOpenSearchReadApi,
+  OpenSearchEngine,
+  OpenSearchClient
+};

package/dist/opensearch/types.d.ts

@@ -0,0 +1,8 @@
+export type SearchQuery = Record<string, unknown>;
+export type SearchResult = Record<string, unknown>;
+/** Engine-neutral operations used by collect domains. */
+export interface SearchEngine {
+    count(index: string, query: SearchQuery): Promise<number>;
+    search(index: string, body: SearchQuery): Promise<SearchResult>;
+    close?(): Promise<void>;
+}

package/dist/opensearch/types.js

@@ -0,0 +1 @@
+import"../chunk-djk4kmxb.js";

package/dist/process/index.d.ts

@@ -0,0 +1,13 @@
+export interface RuntimeProcess {
+    stdout: ReadableStream<Uint8Array>;
+    stderr: ReadableStream<Uint8Array>;
+    exited: Promise<number>;
+    kill(): void;
+}
+export interface SpawnProcessOptions {
+    stdin?: string | Uint8Array;
+    env?: NodeJS.ProcessEnv;
+}
+/** 使用 Node-compatible 子进程 API，不要求调用方使用 Bun runtime。 */
+export declare function spawnProcess(argv: string[], opts?: SpawnProcessOptions): RuntimeProcess;
+export declare function sleep(ms: number): Promise<void>;

package/dist/process/index.js

@@ -0,0 +1,8 @@
+import {
+  sleep,
+  spawnProcess
+} from "../chunk-ztenxgjv.js";
+export {
+  spawnProcess,
+  sleep
+};

package/dist/redis/client.d.ts

@@ -0,0 +1,90 @@
+import type { Client } from "../client";
+import type { ConnectionSource, ClientLifecycle } from "../datasource";
+import type { TcpTransport } from "../transport";
+import { createClient, type RedisClientType } from "@redis/client";
+export interface RedisEndpoint {
+    host: string;
+    port: number;
+}
+export interface RedisMappedEndpoint extends RedisEndpoint {
+    servername?: string;
+}
+export interface RedisCredentials {
+    username?: string;
+    password?: string;
+}
+export interface RedisConnectionConfig extends RedisCredentials {
+    database: number;
+    useSsl: boolean;
+    timeoutMs: number;
+}
+export type RedisEndpointMapper = (endpoint: RedisEndpoint) => Promise<RedisMappedEndpoint>;
+type NodeRedisClient = RedisClientType;
+type NodeRedisClientFactory = (options: Parameters<typeof createClient>[0]) => NodeRedisClient;
+export interface RedisManagedConnection extends RedisConnectionApi {
+    readonly isReady: boolean;
+    close(): void;
+}
+export type RedisConnectionFactory = (endpoint: RedisEndpoint, mapped: RedisMappedEndpoint, config: RedisConnectionConfig) => Promise<RedisManagedConnection>;
+/** Redis INFO wire 文本解析；协议适配留在 infra，领域层只接收结构化字段。 */
+export declare function parseRedisInfo(raw: string): Record<string, unknown>;
+export interface RedisConnectionApi {
+    readonly endpoint: RedisEndpoint;
+    ping(): Promise<string>;
+    info(section?: string): Promise<Record<string, unknown>>;
+    dbSize(): Promise<number>;
+    command(args: string[]): Promise<unknown>;
+    pipeline(commands: string[][]): Promise<unknown[]>;
+    scan(cursor: string, count: number): Promise<{
+        cursor: string;
+        keys: string[];
+    }>;
+}
+export interface RedisAccessApi {
+    connection(endpoint: RedisEndpoint, database: number, credentials?: RedisCredentials): Promise<RedisConnectionApi>;
+    close(): Promise<void>;
+}
+export declare class RedisConnection implements RedisManagedConnection {
+    #private;
+    readonly endpoint: RedisEndpoint;
+    private readonly client;
+    private readonly timeoutMs;
+    private readonly lastError;
+    private constructor();
+    static connect(endpoint: RedisEndpoint, mapped: RedisMappedEndpoint, config: RedisConnectionConfig, clientFactory?: NodeRedisClientFactory): Promise<RedisConnection>;
+    get isReady(): boolean;
+    ping(): Promise<string>;
+    info(section?: string): Promise<Record<string, unknown>>;
+    dbSize(): Promise<number>;
+    command(args: string[]): Promise<unknown>;
+    pipeline(commands: string[][]): Promise<unknown[]>;
+    scan(cursor: string, count: number): Promise<{
+        cursor: string;
+        keys: string[];
+    }>;
+    close(): void;
+}
+export declare class RedisAccess implements RedisAccessApi {
+    #private;
+    private readonly transport;
+    private readonly baseConfig;
+    private readonly connectionFactory;
+    constructor(transport: TcpTransport, baseConfig: Omit<RedisConnectionConfig, "database">, connectionFactory?: RedisConnectionFactory);
+    connection(endpoint: RedisEndpoint, database: number, credentials?: RedisCredentials): Promise<RedisManagedConnection>;
+    close(): Promise<void>;
+}
+export interface RedisDataSourceTarget extends RedisConnectionConfig {
+    endpoints: RedisEndpoint[];
+}
+export declare class RedisClient implements Client {
+    #private;
+    private readonly source;
+    readonly signal: AbortSignal;
+    constructor(source: ConnectionSource<RedisDataSourceTarget>, lifecycle?: ClientLifecycle);
+    initialize(): Promise<void>;
+    get access(): RedisAccess;
+    get target(): RedisDataSourceTarget;
+    dispose(): Promise<void>;
+}
+export declare function openRedis(source: ConnectionSource<RedisDataSourceTarget>, lifecycle?: ClientLifecycle): Promise<RedisClient>;
+export {};

package/dist/redis/client.js

@@ -0,0 +1,14 @@
+import {
+  RedisAccess,
+  RedisClient,
+  RedisConnection,
+  openRedis,
+  parseRedisInfo
+} from "../chunk-ajhdd4hp.js";
+export {
+  parseRedisInfo,
+  openRedis,
+  RedisConnection,
+  RedisClient,
+  RedisAccess
+};

package/dist/redis/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./client";
+export * from "./key-stats";
+export * from "./topology";

package/dist/redis/index.js

@@ -0,0 +1,24 @@
+import {
+  collectRedisKeyStats,
+  redisGroupedSampleSizes
+} from "../chunk-jr9y0ghr.js";
+import {
+  discoverRedisTopology
+} from "../chunk-c6z919qb.js";
+import {
+  RedisAccess,
+  RedisClient,
+  RedisConnection,
+  openRedis,
+  parseRedisInfo
+} from "../chunk-ajhdd4hp.js";
+export {
+  redisGroupedSampleSizes,
+  parseRedisInfo,
+  openRedis,
+  discoverRedisTopology,
+  collectRedisKeyStats,
+  RedisConnection,
+  RedisClient,
+  RedisAccess
+};

package/dist/redis/key-stats.d.ts

@@ -0,0 +1,27 @@
+import type { RedisConnectionApi } from "./client";
+export interface RedisKeyStat {
+    key: string;
+    type: string;
+    memoryBytes: number;
+    ttlMs: number;
+    length: number | null;
+}
+export interface RedisKeyStatsOptions {
+    maxKeys: number;
+    maxKeysPerSecond: number;
+    scanCount: number;
+    pipelineKeys: number;
+    memorySamples: number;
+    onSelectionProgress?: (selected: number, limit: number) => void;
+    onProgress?: (inspected: number, limit: number) => void;
+}
+export interface RedisKeyStatsResult {
+    totalKeys: number;
+    visitedKeys: number;
+    inspectedKeys: number;
+    scanComplete: boolean;
+    keys: RedisKeyStat[];
+}
+export declare function redisGroupedSampleSizes(totalKeys: number, targetSamples: number): number[];
+/** redis-cli keyStats 的受预算实现：有界选择 key，并用 pipeline 检查元数据。 */
+export declare function collectRedisKeyStats(client: RedisConnectionApi, options: RedisKeyStatsOptions): Promise<RedisKeyStatsResult>;

package/dist/redis/key-stats.js

@@ -0,0 +1,8 @@
+import {
+  collectRedisKeyStats,
+  redisGroupedSampleSizes
+} from "../chunk-jr9y0ghr.js";
+export {
+  redisGroupedSampleSizes,
+  collectRedisKeyStats
+};

package/dist/redis/topology.d.ts

@@ -0,0 +1,23 @@
+import type { RedisAccessApi, RedisCredentials, RedisEndpoint } from "./client";
+export interface RedisTopologyConfig extends RedisCredentials {
+    endpoints: RedisEndpoint[];
+    database: number;
+    clusterType: "single" | "sentinel" | "cluster";
+    sentinelHosts: RedisEndpoint[];
+    sentinelMasterName: string;
+    sentinelUsername?: string;
+    sentinelPassword?: string;
+}
+export interface RedisSlotRange {
+    start: number;
+    end: number;
+    master: RedisEndpoint;
+    replicas: RedisEndpoint[];
+}
+export interface RedisTopology {
+    clusterType: "single" | "sentinel" | "cluster";
+    masters: RedisEndpoint[];
+    replicas: RedisEndpoint[];
+    slotRanges: RedisSlotRange[];
+}
+export declare function discoverRedisTopology(access: RedisAccessApi, config: RedisTopologyConfig): Promise<RedisTopology>;

package/dist/redis/topology.js

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

package/dist/transport/index.d.ts

@@ -0,0 +1,40 @@
+export interface Endpoint {
+    host: string;
+    port: number;
+    servername?: string;
+}
+export interface TcpTransport {
+    readonly kind: "tcp";
+    readonly name: string;
+    connect(endpoint: Endpoint): Promise<Endpoint>;
+}
+export declare class DirectTransport implements TcpTransport {
+    readonly kind = "tcp";
+    readonly name = "direct";
+    connect(endpoint: Endpoint): Promise<Endpoint>;
+}
+/** The supplied forwarder owns port allocation and cleanup; external endpoints may stay direct. */
+export declare class PortForwardTransport implements TcpTransport {
+    private readonly forward;
+    readonly kind = "tcp";
+    readonly name = "port-forward";
+    constructor(forward: (endpoint: Endpoint) => Promise<Endpoint>);
+    connect(endpoint: Endpoint): Promise<Endpoint>;
+}
+export interface PodRunOptions {
+    stdin: string;
+    timeoutMs: number;
+}
+export type PodRunner = (command: readonly string[], options: PodRunOptions) => Promise<string>;
+/** A Python-capable Pod path. Protocol code supplies the script; the host enforces access. */
+export declare class PodPythonTransport {
+    private readonly exec;
+    private readonly python;
+    readonly kind = "python";
+    readonly name = "pod-python";
+    constructor(exec: PodRunner, python?: string);
+    run(script: string, input: unknown, timeoutMs: number): Promise<string>;
+}
+export type Transport = TcpTransport | PodPythonTransport;
+/** Only failure to establish a connection permits a route change; never replay protocol operations. */
+export declare function isConnectionNetworkError(error: unknown): boolean;

package/dist/transport/index.js

@@ -0,0 +1,12 @@
+import {
+  DirectTransport,
+  PodPythonTransport,
+  PortForwardTransport,
+  isConnectionNetworkError
+} from "../chunk-xy4g56g4.js";
+export {
+  isConnectionNetworkError,
+  PortForwardTransport,
+  PodPythonTransport,
+  DirectTransport
+};