@compforge/harness-common 0.0.1

package/README.md

@@ -0,0 +1,25 @@
+# Harness Common for TypeScript
+
+Execution-neutral client lifecycle and datasource contracts, shared by harnesses and toolbox clients.
+No database drivers, Kubernetes adapters, Doctor concepts or business configuration live here.
+
+```typescript
+import { ClientManager, type DataSource } from "@compforge/harness-common";
+
+const clients = new ClientManager();
+try {
+  const client = await clients.get(source); // source implements DataSource<Client>
+  // Borrow the initialized client; the root execution owns cleanup.
+} finally {
+  await clients.dispose();
+}
+```
+
+A DataSource key identifies the complete configuration and access policy. Equal keys share client
+initialization, not query results. Use dataSourceKey to hash configuration without exposing credentials.
+ServiceDataSource associates a consumer-owned Service model with a source without changing its key.
+
+Python's corresponding package is sdks/python/common (harness-common). Languages keep idiomatic APIs
+and independently versioned packages; they need not implement every model in lockstep.
+
+Development: bun install, make lint, make test. Published artifacts are Node-compatible ESM and declarations.

package/dist/client-manager.d.ts

@@ -0,0 +1,14 @@
+import type { Client } from "./client.js";
+import type { DataSource } from "./datasource.js";
+/** 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,61 @@
+/** @spec One root execution shares successful initialization per identity and closes clients at finalize. */
+export class ClientManager {
+    #controller = new AbortController();
+    signal;
+    #clients = new Map();
+    #ready = [];
+    #disposal;
+    constructor(signal) {
+        this.signal = signal ? AbortSignal.any([signal, this.#controller.signal]) : this.#controller.signal;
+    }
+    get(source) {
+        this.signal.throwIfAborted();
+        const existing = this.#clients.get(source.key);
+        if (existing)
+            return existing;
+        // Publish before construction so concurrent callers never dispatch a second factory.
+        const pending = Promise.resolve().then(async () => {
+            this.signal.throwIfAborted();
+            const client = source.createClient(this.signal);
+            try {
+                await client.initialize();
+                this.signal.throwIfAborted();
+                this.#ready.push(client);
+                return client;
+            }
+            catch (error) {
+                try {
+                    await client.dispose();
+                }
+                catch (cleanup) {
+                    throw new AggregateError([error, cleanup], "Client initialization and cleanup failed");
+                }
+                throw error;
+            }
+        });
+        this.#clients.set(source.key, pending);
+        void pending.catch(() => { if (this.#clients.get(source.key) === pending)
+            this.#clients.delete(source.key); });
+        return pending;
+    }
+    dispose() {
+        return this.#disposal ??= (async () => {
+            this.#controller.abort(new Error("Client manager disposed"));
+            const settled = await Promise.allSettled(this.#clients.values());
+            this.#clients.clear();
+            // Dependencies must be acquired before their consumers initialize, so reverse readiness is safe.
+            const errors = settled.flatMap(result => result.status === "rejected" && result.reason instanceof AggregateError
+                ? [result.reason] : []);
+            for (const client of this.#ready.splice(0).reverse()) {
+                try {
+                    await client.dispose();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            if (errors.length)
+                throw new AggregateError(errors, "Client cleanup failed");
+        })();
+    }
+}

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/client.js

@@ -0,0 +1 @@
+export {};

package/dist/datasource.d.ts

@@ -0,0 +1,17 @@
+import type { Client } from "./client.js";
+/** Identity includes 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;
+}
+/**
+ * @spec A Service association does not own a client or change the source identity.
+ * @why Service models belong to consumers; binding the same source must not fragment client reuse.
+ */
+export interface ServiceDataSource<Service, C extends Client> {
+    readonly service: Service;
+    readonly source: DataSource<C>;
+}
+/** 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,12 @@
+import { createHash } from "node:crypto";
+/** Stable in-memory identity; connection credentials must not appear in observable cache keys. */
+export function dataSourceKey(protocol, configuration) {
+    const canonical = (value) => {
+        if (Array.isArray(value))
+            return value.map(canonical);
+        if (value && typeof value === "object")
+            return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, canonical(item)]));
+        return value;
+    };
+    return `${protocol}:${createHash("sha256").update(JSON.stringify(canonical(configuration))).digest("hex")}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./client.js";
+export * from "./client-manager.js";
+export * from "./datasource.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./client.js";
+export * from "./client-manager.js";
+export * from "./datasource.js";

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@compforge/harness-common",
+  "version": "0.0.1",
+  "description": "Execution-neutral client lifecycle and datasource contracts for harnesses",
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "bun test"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^22",
+    "typescript": "^5.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}