@evolith/sdk 0.1.0

package/README.es.md

@@ -0,0 +1,105 @@
+# @evolith/sdk
+
+Librería cliente tipada en TypeScript para la **API REST** de Evolith Core y sus
+**herramientas MCP**. Es un envoltorio fino e inyectable por transporte: sin estado
+global, sin configuración de red implícita, y cada método está completamente tipado
+contra los contratos del servidor.
+
+> Estado: **experimental**. El paquete se publica desde este monorepo pero todavía no
+> está integrado en una aplicación de primera parte; existe para que consumidores
+> externos (repos satélite, scripts de automatización, el Tracker BFF) puedan hablar
+> con Evolith Core sin volver a derivar los DTOs a mano.
+
+## Propósito
+
+Evolith Core expone dos superficies:
+
+- una **API REST** versionada servida por `apps/core-api` (versionado por URI bajo el
+  prefijo `api/v`, por lo que las rutas reales son `/api/v1/<recurso>`);
+- un conjunto de **herramientas MCP** servidas por `packages/mcp-server` sobre
+  JSON-RPC `tools/call`.
+
+Este SDK refleja los DTOs de los controladores (`apps/core-api/src/presentation/dtos`)
+y los esquemas de entrada/salida de las herramientas MCP
+(`packages/mcp-server/src/tools/*.tools.ts`) como tipos TypeScript escritos a mano, y
+provee una clase cliente por superficie. Es el único punto de integración tipado para
+que los consumidores no dupliquen las formas de las solicitudes.
+
+## Consumidor previsto
+
+- **Repositorios satélite** que ejecutan evaluaciones de compuertas / detección de
+  drift contra una API de Evolith Core alojada.
+- **Scripts de automatización y CI** que necesitan acceso tipado a las transiciones de
+  fase.
+- **El Tracker BFF**, que custodia el `workspaceRef` opaco y media las llamadas a Core
+  en nombre de los usuarios finales.
+
+Todos los cuerpos de solicitud reciben un `workspaceRef` opaco (emitido por el Tracker
+BFF) en lugar de credenciales crudas, manteniendo el SDK solo como transporte.
+
+## Cliente REST
+
+`EvolithRestClient` es un envoltorio tipado sobre `fetch`. Cada método devuelve el
+`SuccessEnvelope<T>` completo (`{ success, data, meta }`); las respuestas no-2xx lanzan
+`EvolithApiError`.
+
+| Método | Verbo / Ruta |
+| --- | --- |
+| `evaluateGate(gateId, body)` | `POST /api/v1/gates/:gateId/evaluate` |
+| `evaluatePhaseGate(phase, body)` | resuelve fase → id de compuerta, luego `evaluateGate` |
+| `transitionPhase(body)` | `POST /api/v1/phases/transition` |
+| `listTopologies()` | `GET /api/v1/architecture/topologies` |
+| `getTopology(id)` | `GET /api/v1/architecture/topologies/:id` |
+| `validateSatellite(body)` | `POST /api/v1/architecture/validate-satellite` |
+| `detectDrift(body)` | `POST /api/v1/architecture/detect-drift` |
+| `invalidateTopologyCache()` | `POST /api/v1/architecture/cache/invalidate` |
+| `initProject(body)` | `POST /api/v1/projects/initialize` |
+| `proposeAdvance(body)` | `POST /api/v1/projects/propose-advance` |
+
+Opciones del constructor: `baseUrl` (requerido), `apiKey` (token Bearer opcional),
+`fetch` (implementación personalizada opcional), `timeoutMs` (por defecto `30_000`,
+aplicado vía `AbortController`) y `apiPrefix` (por defecto `/api`).
+
+```ts
+import { EvolithRestClient } from '@evolith/sdk';
+
+const client = new EvolithRestClient({ baseUrl: 'http://localhost:3000', apiKey: 'token' });
+const result = await client.evaluatePhaseGate('discovery', { workspaceRef: 'op_abc123' });
+console.log(result.data.passed);
+```
+
+## Cliente MCP
+
+`EvolithMcpClient` es agnóstico al transporte: provee cualquier función que envíe una
+solicitud `tools/call` y devuelva el arreglo de contenido crudo. Cada método convierte
+la respuesta parseada al tipo de salida correcto y reporta `isError`.
+
+| Método | Herramienta MCP |
+| --- | --- |
+| `evaluateGate(input)` | `evolith-gate-evaluate` |
+| `validate(input)` | `evolith-validate` |
+| `advancePhase(input)` | `evolith-phase-advance` |
+| `listTopologies(input?)` | `evolith-topology-list` |
+| `getTopology(input)` | `evolith-topology-get` |
+| `call(toolName, input)` | despacho tipado genérico |
+
+La fábrica `createJsonRpcTransport(sendRequest)` adapta cualquier emisor JSON-RPC a la
+forma de transporte requerida.
+
+```ts
+import { EvolithMcpClient, createJsonRpcTransport } from '@evolith/sdk';
+
+const mcp = new EvolithMcpClient({ transport: createJsonRpcTransport(myRpcFn) });
+const gate = await mcp.evaluateGate({ phase: 'discovery', projectPath: '/repos/my-service' });
+```
+
+## Testing
+
+Las pruebas unitarias viven en `src/__tests__/sdk.spec.ts` y nunca tocan la red: el
+cliente REST se maneja con un `fetch` simulado y el cliente MCP con un transporte
+simulado.
+
+```bash
+npm test            # ejecuta la suite de Jest
+npm run test:cov    # ejecuta con cobertura (≥85% de cobertura de funciones en los clientes)
+```

package/README.md

@@ -0,0 +1,100 @@
+# @evolith/sdk
+
+Typed TypeScript client library for the Evolith Core **REST API** and **MCP tools**.
+It is a thin, transport-injectable wrapper: no global state, no implicit network
+configuration, and every method is fully typed against the server contracts.
+
+> Status: **experimental**. The package is published from this monorepo but is not
+> yet wired into a first-party application; it exists so external consumers
+> (satellite repos, automation scripts, the Tracker BFF) can talk to Evolith Core
+> without re-deriving DTOs by hand.
+
+## Purpose
+
+Evolith Core exposes two surfaces:
+
+- a versioned **REST API** served by `apps/core-api` (URI versioning under the
+  `api/v` prefix, so live routes are `/api/v1/<resource>`);
+- a set of **MCP tools** served by `packages/mcp-server` over JSON-RPC `tools/call`.
+
+This SDK mirrors the controller DTOs (`apps/core-api/src/presentation/dtos`) and the
+MCP tool input/output schemas (`packages/mcp-server/src/tools/*.tools.ts`) as
+hand-authored TypeScript types, and provides one client class per surface. It is the
+single typed integration point so consumers do not duplicate request shapes.
+
+## Intended consumer
+
+- **Satellite repositories** running gate evaluations / drift detection against a
+  hosted Evolith Core API.
+- **Automation and CI scripts** that need typed access to phase transitions.
+- **The Tracker BFF**, which holds the opaque `workspaceRef` and brokers calls to
+  Core on behalf of end users.
+
+All request bodies take an opaque `workspaceRef` (issued by the Tracker BFF) rather
+than raw credentials, keeping the SDK transport-only.
+
+## REST client
+
+`EvolithRestClient` is a typed `fetch` wrapper. Each method returns the full
+`SuccessEnvelope<T>` (`{ success, data, meta }`); non-2xx responses throw
+`EvolithApiError`.
+
+| Method | Verb / Route |
+| --- | --- |
+| `evaluateGate(gateId, body)` | `POST /api/v1/gates/:gateId/evaluate` |
+| `evaluatePhaseGate(phase, body)` | resolves phase → gate id, then `evaluateGate` |
+| `transitionPhase(body)` | `POST /api/v1/phases/transition` |
+| `listTopologies()` | `GET /api/v1/architecture/topologies` |
+| `getTopology(id)` | `GET /api/v1/architecture/topologies/:id` |
+| `validateSatellite(body)` | `POST /api/v1/architecture/validate-satellite` |
+| `detectDrift(body)` | `POST /api/v1/architecture/detect-drift` |
+| `invalidateTopologyCache()` | `POST /api/v1/architecture/cache/invalidate` |
+| `initProject(body)` | `POST /api/v1/projects/initialize` |
+| `proposeAdvance(body)` | `POST /api/v1/projects/propose-advance` |
+
+Constructor options: `baseUrl` (required), `apiKey` (optional Bearer token),
+`fetch` (optional custom implementation), `timeoutMs` (default `30_000`, enforced
+via `AbortController`), and `apiPrefix` (default `/api`).
+
+```ts
+import { EvolithRestClient } from '@evolith/sdk';
+
+const client = new EvolithRestClient({ baseUrl: 'http://localhost:3000', apiKey: 'token' });
+const result = await client.evaluatePhaseGate('discovery', { workspaceRef: 'op_abc123' });
+console.log(result.data.passed);
+```
+
+## MCP client
+
+`EvolithMcpClient` is transport-agnostic: supply any function that sends a
+`tools/call` request and returns the raw content array. Each method casts the parsed
+response to the correct typed output and reports `isError`.
+
+| Method | MCP tool |
+| --- | --- |
+| `evaluateGate(input)` | `evolith-gate-evaluate` |
+| `validate(input)` | `evolith-validate` |
+| `advancePhase(input)` | `evolith-phase-advance` |
+| `listTopologies(input?)` | `evolith-topology-list` |
+| `getTopology(input)` | `evolith-topology-get` |
+| `call(toolName, input)` | generic typed dispatch |
+
+The `createJsonRpcTransport(sendRequest)` factory adapts any JSON-RPC sender into the
+required transport shape.
+
+```ts
+import { EvolithMcpClient, createJsonRpcTransport } from '@evolith/sdk';
+
+const mcp = new EvolithMcpClient({ transport: createJsonRpcTransport(myRpcFn) });
+const gate = await mcp.evaluateGate({ phase: 'discovery', projectPath: '/repos/my-service' });
+```
+
+## Testing
+
+Unit tests live in `src/__tests__/sdk.spec.ts` and never touch the network — the
+REST client is driven by a mock `fetch` and the MCP client by a mock transport.
+
+```bash
+npm test            # run the Jest suite
+npm run test:cov    # run with coverage (≥85% function coverage on the clients)
+```

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { EvolithRestClient, EvolithApiError } from './rest/evolith-rest-client.js';
+export type { EvolithRestClientOptions } from './rest/evolith-rest-client.js';
+export type { ApiEnvelope, GatePhase as RestGatePhase, EvaluateGateRequest, EvaluateGateResponse, GateEvidence, GateViolation as RestGateViolation, ViolationSeverity, TransitionPhaseRequest, TransitionPhaseResponse, PhaseTransitionResult, TopologyManifest as RestTopologyManifest, ListTopologiesResponse, GetTopologyResponse, ValidateSatelliteRequest, ValidateSatelliteResponse, DetectDriftRequest, DetectDriftResponse, ValidationResult, InitProjectRequest, InitProjectResponse, ProposeAdvanceRequest, ProposeAdvanceResponse, } from './rest/types.js';
+export { SatellitesClient } from './satellites.client.js';
+export type { SatelliteRecord, SatelliteStatus, SatelliteMode, SatelliteTopology, InitializeSatelliteInput, RegisterSatelliteInput, } from './satellites.client.js';
+export { EvolithMcpClient, createJsonRpcTransport } from './mcp/evolith-mcp-client.js';
+export type { EvolithMcpClientOptions, McpTransport, McpCallResult } from './mcp/evolith-mcp-client.js';
+export type { GatePhase as McpGatePhase, EvaluatorKind, EvidenceMode, ValidateFormat, GateEvaluateInput, GateEvaluateOutput, GateViolation as McpGateViolation, ValidateInput, ValidateOutput, ValidateJsonOutput, ValidationIssue, PhaseAdvanceInput, PhaseAdvanceOutput, TopologyListInput, TopologyListOutput, TopologyGetInput, TopologyGetOutput, TopologyManifest as McpTopologyManifest, McpToolName, McpToolInputMap, McpToolOutputMap, } from './mcp/types.js';

package/dist/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createJsonRpcTransport = exports.EvolithMcpClient = exports.SatellitesClient = exports.EvolithApiError = exports.EvolithRestClient = void 0;
+var evolith_rest_client_js_1 = require("./rest/evolith-rest-client.js");
+Object.defineProperty(exports, "EvolithRestClient", { enumerable: true, get: function () { return evolith_rest_client_js_1.EvolithRestClient; } });
+Object.defineProperty(exports, "EvolithApiError", { enumerable: true, get: function () { return evolith_rest_client_js_1.EvolithApiError; } });
+var satellites_client_js_1 = require("./satellites.client.js");
+Object.defineProperty(exports, "SatellitesClient", { enumerable: true, get: function () { return satellites_client_js_1.SatellitesClient; } });
+var evolith_mcp_client_js_1 = require("./mcp/evolith-mcp-client.js");
+Object.defineProperty(exports, "EvolithMcpClient", { enumerable: true, get: function () { return evolith_mcp_client_js_1.EvolithMcpClient; } });
+Object.defineProperty(exports, "createJsonRpcTransport", { enumerable: true, get: function () { return evolith_mcp_client_js_1.createJsonRpcTransport; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAqBA,wEAAmF;AAA1E,2HAAA,iBAAiB,OAAA;AAAE,yHAAA,eAAe,OAAA;AA4B3C,+DAA0D;AAAjD,wHAAA,gBAAgB,OAAA;AAWzB,qEAAuF;AAA9E,yHAAA,gBAAgB,OAAA;AAAE,+HAAA,sBAAsB,OAAA"}

package/dist/mcp/evolith-mcp-client.d.ts

@@ -0,0 +1,28 @@
+import type { McpToolName, McpToolInputMap, McpToolOutputMap, GateEvaluateInput, GateEvaluateOutput, ValidateInput, ValidateOutput, PhaseAdvanceInput, PhaseAdvanceOutput, TopologyListInput, TopologyListOutput, TopologyGetInput, TopologyGetOutput } from './types.js';
+export interface McpCallResult<T> {
+    content: Array<{
+        type: string;
+        text?: string;
+    }>;
+    parsed: T;
+    isError: boolean;
+}
+export type McpTransport = <N extends McpToolName>(toolName: N, input: McpToolInputMap[N]) => Promise<Array<{
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+}>>;
+export interface EvolithMcpClientOptions {
+    transport: McpTransport;
+}
+export declare class EvolithMcpClient {
+    private readonly transport;
+    constructor(options: EvolithMcpClientOptions);
+    evaluateGate(input: GateEvaluateInput): Promise<McpCallResult<GateEvaluateOutput>>;
+    validate(input: ValidateInput): Promise<McpCallResult<ValidateOutput>>;
+    advancePhase(input: PhaseAdvanceInput): Promise<McpCallResult<PhaseAdvanceOutput>>;
+    listTopologies(input?: TopologyListInput): Promise<McpCallResult<TopologyListOutput>>;
+    getTopology(input: TopologyGetInput): Promise<McpCallResult<TopologyGetOutput>>;
+    call<N extends McpToolName>(toolName: N, input: McpToolInputMap[N]): Promise<McpCallResult<McpToolOutputMap[N]>>;
+}
+export declare function createJsonRpcTransport(sendRequest: (method: string, params: unknown) => Promise<unknown>): McpTransport;

package/dist/mcp/evolith-mcp-client.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvolithMcpClient = void 0;
+exports.createJsonRpcTransport = createJsonRpcTransport;
+class EvolithMcpClient {
+    constructor(options) {
+        this.transport = options.transport;
+    }
+    async evaluateGate(input) {
+        return this.call('evolith-gate-evaluate', input);
+    }
+    async validate(input) {
+        return this.call('evolith-validate', input);
+    }
+    async advancePhase(input) {
+        return this.call('evolith-phase-advance', input);
+    }
+    async listTopologies(input) {
+        return this.call('evolith-topology-list', input ?? {});
+    }
+    async getTopology(input) {
+        return this.call('evolith-topology-get', input);
+    }
+    async call(toolName, input) {
+        const content = await this.transport(toolName, input);
+        const isError = content.some((c) => c.type === 'error' || c.isError === true);
+        const textContent = content.find((c) => c.type === 'text');
+        const text = textContent?.text ?? '';
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = text;
+        }
+        return { content, parsed, isError };
+    }
+}
+exports.EvolithMcpClient = EvolithMcpClient;
+function createJsonRpcTransport(sendRequest) {
+    return async (toolName, input) => {
+        const result = await sendRequest('tools/call', { name: toolName, arguments: input });
+        const r = result;
+        return r.content ?? [];
+    };
+}
+//# sourceMappingURL=evolith-mcp-client.js.map

package/dist/mcp/evolith-mcp-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evolith-mcp-client.js","sourceRoot":"","sources":["../../src/mcp/evolith-mcp-client.ts"],"names":[],"mappings":";;;AAiIA,wDAQC;AA5FD,MAAa,gBAAgB;IAG3B,YAAY,OAAgC;QAC1C,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACrC,CAAC;IAOD,KAAK,CAAC,YAAY,CAAC,KAAwB;QACzC,OAAO,IAAI,CAAC,IAAI,CAAC,uBAAuB,EAAE,KAAK,CAAC,CAAC;IACnD,CAAC;IAOD,KAAK,CAAC,QAAQ,CAAC,KAAoB;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;IAC9C,CAAC;IAOD,KAAK,CAAC,YAAY,CAAC,KAAwB;QACzC,OAAO,IAAI,CAAC,IAAI,CAAC,uBAAuB,EAAE,KAAK,CAAC,CAAC;IACnD,CAAC;IAOD,KAAK,CAAC,cAAc,CAAC,KAAyB;QAC5C,OAAO,IAAI,CAAC,IAAI,CAAC,uBAAuB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC;IAOD,KAAK,CAAC,WAAW,CAAC,KAAuB;QACvC,OAAO,IAAI,CAAC,IAAI,CAAC,sBAAsB,EAAE,KAAK,CAAC,CAAC;IAClD,CAAC;IAOD,KAAK,CAAC,IAAI,CACR,QAAW,EACX,KAAyB;QAEzB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAEtD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,IAAK,CAAS,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC;QACvF,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;QAC3D,MAAM,IAAI,GAAG,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC;QAErC,IAAI,MAA2B,CAAC;QAChC,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAwB,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,GAAG,IAAsC,CAAC;QAClD,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IACtC,CAAC;CACF;AA5ED,4CA4EC;AAQD,SAAgB,sBAAsB,CACpC,WAAkE;IAElE,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE;QAC/B,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;QACrF,MAAM,CAAC,GAAG,MAA8D,CAAC;QACzE,OAAO,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC;IACzB,CAAC,CAAC;AACJ,CAAC"}

package/dist/mcp/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './evolith-mcp-client.js';

package/dist/mcp/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./evolith-mcp-client.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,0DAAwC"}

package/dist/mcp/types.d.ts

@@ -0,0 +1,113 @@
+export type GatePhase = 'discovery' | 'design' | 'construction' | 'qa' | 'release';
+export type EvaluatorKind = 'human' | 'agent' | 'ci';
+export type EvidenceMode = 'full' | 'summary';
+export type ValidateFormat = 'json' | 'summary' | 'table';
+export interface GateEvaluateInput {
+    phase: GatePhase;
+    projectPath: string;
+    corePath?: string;
+    rulesetRef?: string;
+    evidenceMode?: EvidenceMode;
+    evaluatedBy?: EvaluatorKind;
+    initiative?: string;
+    tenant?: string;
+    webhookUrl?: string;
+}
+export interface GateViolation {
+    ruleId: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    artifact?: string;
+    remediation?: string;
+}
+export interface GateEvaluateOutput {
+    phase: GatePhase;
+    passed: boolean;
+    violations: GateViolation[];
+    evaluatedBy?: EvaluatorKind;
+    evaluatedAt?: string;
+    summary?: {
+        errors: number;
+        warnings: number;
+    };
+}
+export interface ValidateInput {
+    path: string;
+    format?: ValidateFormat;
+    ruleset?: string;
+    corePath?: string;
+    topology?: string;
+    phase?: string;
+    manifest?: string;
+}
+export interface ValidationIssue {
+    ruleId: string;
+    severity: string;
+    title: string;
+    blocking: boolean;
+    category?: string;
+}
+export interface ValidateJsonOutput {
+    status: 'passed' | 'failed';
+    rulesChecked: number;
+    issues: ValidationIssue[];
+}
+export type ValidateOutput = ValidateJsonOutput | string;
+export interface PhaseAdvanceInput {
+    fromPhase: GatePhase;
+    toPhase: GatePhase;
+    projectPath: string;
+    corePath?: string;
+    evaluatedBy?: EvaluatorKind;
+    initiative?: string;
+    tenant?: string;
+    webhookUrl?: string;
+}
+export interface PhaseAdvanceOutput {
+    fromPhase: GatePhase;
+    toPhase: GatePhase;
+    allowed: boolean;
+    gateEvidence?: GateEvaluateOutput;
+    message?: string;
+}
+export interface TopologyListInput {
+    corePath?: string;
+}
+export interface TopologyManifest {
+    id: string;
+    name: string;
+    description?: string;
+    version?: string;
+    [key: string]: unknown;
+}
+export interface TopologyListOutput {
+    tool: 'evolith-topology-list';
+    count: number;
+    topologies: TopologyManifest[];
+    timestamp: string;
+}
+export interface TopologyGetInput {
+    id: string;
+    corePath?: string;
+}
+export interface TopologyGetOutput {
+    tool: 'evolith-topology-get';
+    id: string;
+    topology: TopologyManifest;
+    timestamp: string;
+}
+export type McpToolName = 'evolith-gate-evaluate' | 'evolith-validate' | 'evolith-phase-advance' | 'evolith-topology-list' | 'evolith-topology-get';
+export interface McpToolInputMap {
+    'evolith-gate-evaluate': GateEvaluateInput;
+    'evolith-validate': ValidateInput;
+    'evolith-phase-advance': PhaseAdvanceInput;
+    'evolith-topology-list': TopologyListInput;
+    'evolith-topology-get': TopologyGetInput;
+}
+export interface McpToolOutputMap {
+    'evolith-gate-evaluate': GateEvaluateOutput;
+    'evolith-validate': ValidateOutput;
+    'evolith-phase-advance': PhaseAdvanceOutput;
+    'evolith-topology-list': TopologyListOutput;
+    'evolith-topology-get': TopologyGetOutput;
+}

package/dist/mcp/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/mcp/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/mcp/types.ts"],"names":[],"mappings":""}

package/dist/rest/agent.client.d.ts

@@ -0,0 +1,9 @@
+import type { AgentRuntimeRequestWire, AgentRuntimeResult } from '@evolith/agent-runtime';
+export declare class AgentClient {
+    private readonly baseUrl;
+    private readonly _headers;
+    constructor(baseUrl: string, apiKey?: string);
+    private get headers();
+    handle(input: AgentRuntimeRequestWire): Promise<AgentRuntimeResult>;
+    getSkills(): Promise<any>;
+}

package/dist/rest/agent.client.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentClient = void 0;
+class AgentClient {
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this._headers = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+        };
+    }
+    get headers() {
+        return this._headers;
+    }
+    async handle(input) {
+        const res = await fetch(`${this.baseUrl}/v1/agent/handle`, {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify(input),
+        });
+        if (!res.ok)
+            throw new Error(`Agent handle failed: ${res.status}`);
+        return res.json();
+    }
+    async getSkills() {
+        const res = await fetch(`${this.baseUrl}/v1/agent/skills`, {
+            headers: this.headers,
+        });
+        if (!res.ok)
+            throw new Error(`Agent list skills failed: ${res.status}`);
+        return res.json();
+    }
+}
+exports.AgentClient = AgentClient;
+//# sourceMappingURL=agent.client.js.map

package/dist/rest/agent.client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.client.js","sourceRoot":"","sources":["../../src/rest/agent.client.ts"],"names":[],"mappings":";;;AAEA,MAAa,WAAW;IAItB,YAAY,OAAe,EAAE,MAAe;QAC1C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC1C,IAAI,CAAC,QAAQ,GAAG;YACd,cAAc,EAAE,kBAAkB;YAClC,MAAM,EAAE,kBAAkB;YAC1B,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzD,CAAC;IACJ,CAAC;IAED,IAAY,OAAO;QACjB,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAMD,KAAK,CAAC,MAAM,CAAC,KAA8B;QACzC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,kBAAkB,EAAE;YACzD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;SAC5B,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACnE,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;IAMD,KAAK,CAAC,SAAS;QACb,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,kBAAkB,EAAE;YACzD,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACxE,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;CACF;AA1CD,kCA0CC"}

package/dist/rest/evolith-rest-client.d.ts

@@ -0,0 +1,45 @@
+import type { GatePhase, EvaluateGateRequest, EvaluateGateResponse, TransitionPhaseRequest, TransitionPhaseResponse, ListTopologiesResponse, GetTopologyResponse, ValidateSatelliteRequest, ValidateSatelliteResponse, DetectDriftRequest, DetectDriftResponse, InitProjectRequest, InitProjectResponse, ProposeAdvanceRequest, ProposeAdvanceResponse } from './types.js';
+import { SatellitesClient } from '../satellites.client.js';
+import { AgentClient } from './agent.client.js';
+export interface EvolithRestClientOptions {
+    baseUrl: string;
+    agentUrl?: string;
+    apiKey?: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    apiPrefix?: string;
+}
+export declare class EvolithRestClient {
+    private readonly options;
+    private readonly baseUrl;
+    private readonly apiPrefix;
+    private readonly headers;
+    private readonly fetcher;
+    private readonly timeoutMs;
+    readonly satellites: SatellitesClient;
+    readonly agent: AgentClient;
+    constructor(options: EvolithRestClientOptions);
+    evaluateGate(gateId: string, body: EvaluateGateRequest): Promise<EvaluateGateResponse>;
+    evaluatePhaseGate(phase: GatePhase, body: EvaluateGateRequest): Promise<EvaluateGateResponse>;
+    transitionPhase(body: TransitionPhaseRequest): Promise<TransitionPhaseResponse>;
+    listTopologies(): Promise<ListTopologiesResponse>;
+    getTopology(id: string): Promise<GetTopologyResponse>;
+    validateSatellite(body: ValidateSatelliteRequest): Promise<ValidateSatelliteResponse>;
+    detectDrift(body: DetectDriftRequest): Promise<DetectDriftResponse>;
+    invalidateTopologyCache(): Promise<{
+        invalidated: boolean;
+        keys: string[];
+    }>;
+    initProject(body: InitProjectRequest): Promise<InitProjectResponse>;
+    proposeAdvance(body: ProposeAdvanceRequest): Promise<ProposeAdvanceResponse>;
+    private get;
+    private post;
+    private request;
+}
+export declare class EvolithApiError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: string;
+    readonly url: string;
+    constructor(status: number, statusText: string, body: string, url: string);
+}

package/dist/rest/evolith-rest-client.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvolithApiError = exports.EvolithRestClient = void 0;
+const satellites_client_js_1 = require("../satellites.client.js");
+const agent_client_js_1 = require("./agent.client.js");
+class EvolithRestClient {
+    constructor(options) {
+        this.options = options;
+        this.baseUrl = options.baseUrl.replace(/\/$/, '');
+        let prefix = options.apiPrefix ?? '/api';
+        while (prefix.startsWith('/'))
+            prefix = prefix.slice(1);
+        while (prefix.endsWith('/'))
+            prefix = prefix.slice(0, -1);
+        this.apiPrefix = prefix ? `/${prefix}` : '';
+        this.headers = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            ...(options.apiKey ? { Authorization: `Bearer ${options.apiKey}` } : {}),
+        };
+        this.fetcher = options.fetch ?? globalThis.fetch;
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+        this.satellites = new satellites_client_js_1.SatellitesClient(this.baseUrl, options.apiKey);
+        this.agent = new agent_client_js_1.AgentClient(options.agentUrl || this.baseUrl, options.apiKey);
+    }
+    async evaluateGate(gateId, body) {
+        return this.post(`/v1/gates/${encodeURIComponent(gateId)}/evaluate`, body);
+    }
+    async evaluatePhaseGate(phase, body) {
+        const phaseToGateId = {
+            discovery: 'PG1-01',
+            design: 'PG2-01',
+            construction: 'PG3-01',
+            qa: 'PG4-01',
+            release: 'PG5-01',
+        };
+        return this.evaluateGate(phaseToGateId[phase], body);
+    }
+    async transitionPhase(body) {
+        return this.post('/v1/phases/transition', body);
+    }
+    async listTopologies() {
+        return this.get('/v1/architecture/topologies');
+    }
+    async getTopology(id) {
+        return this.get(`/v1/architecture/topologies/${encodeURIComponent(id)}`);
+    }
+    async validateSatellite(body) {
+        return this.post('/v1/architecture/validate-satellite', body);
+    }
+    async detectDrift(body) {
+        return this.post('/v1/architecture/detect-drift', body);
+    }
+    async invalidateTopologyCache() {
+        return this.post('/v1/architecture/cache/invalidate', {});
+    }
+    async initProject(body) {
+        return this.post('/v1/projects/initialize', body);
+    }
+    async proposeAdvance(body) {
+        return this.post('/v1/projects/propose-advance', body);
+    }
+    async get(path) {
+        return this.request('GET', path, undefined);
+    }
+    async post(path, body) {
+        return this.request('POST', path, body);
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${this.apiPrefix}${path}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await this.fetcher(url, {
+                method,
+                headers: this.headers,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const text = await response.text().catch(() => '');
+                throw new EvolithApiError(response.status, response.statusText, text, url);
+            }
+            return (await response.json());
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+exports.EvolithRestClient = EvolithRestClient;
+class EvolithApiError extends Error {
+    constructor(status, statusText, body, url) {
+        super(`Evolith API error ${status} (${statusText}) for ${url}: ${body}`);
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+        this.url = url;
+        this.name = 'EvolithApiError';
+    }
+}
+exports.EvolithApiError = EvolithApiError;
+//# sourceMappingURL=evolith-rest-client.js.map

package/dist/rest/evolith-rest-client.js.map

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

package/dist/rest/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './evolith-rest-client.js';
+export * from './agent.client.js';

package/dist/rest/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./evolith-rest-client.js"), exports);
+__exportStar(require("./agent.client.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/rest/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rest/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,2DAAyC;AACzC,oDAAkC"}

package/dist/rest/types.d.ts

@@ -0,0 +1,99 @@
+export interface EnvelopeMeta {
+    durationMs?: number;
+    [key: string]: unknown;
+}
+export interface SuccessEnvelope<T> {
+    success: true;
+    data: T;
+    meta: EnvelopeMeta;
+}
+export interface ErrorEnvelope {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    meta: EnvelopeMeta;
+}
+export type ApiEnvelope<T> = SuccessEnvelope<T> | ErrorEnvelope;
+export type GatePhase = 'discovery' | 'design' | 'construction' | 'qa' | 'release';
+export interface EvaluateGateRequest {
+    workspaceRef: string;
+}
+export type ViolationSeverity = 'error' | 'warning' | 'info';
+export interface GateViolation {
+    ruleId: string;
+    severity: ViolationSeverity;
+    message: string;
+    artifact?: string;
+    remediation?: string;
+}
+export interface GateEvidence {
+    phase: GatePhase;
+    passed: boolean;
+    violations: GateViolation[];
+    evaluatedBy?: string;
+    evaluatedAt?: string;
+    summary?: {
+        errors: number;
+        warnings: number;
+    };
+}
+export type EvaluateGateResponse = SuccessEnvelope<GateEvidence>;
+export interface TransitionPhaseRequest {
+    from: string;
+    to: string;
+    tools: string[];
+    workspaceRef: string;
+}
+export interface PhaseTransitionResult {
+    from: string;
+    to: string;
+    success: boolean;
+    message?: string;
+}
+export type TransitionPhaseResponse = SuccessEnvelope<PhaseTransitionResult>;
+export interface TopologyManifest {
+    id: string;
+    name: string;
+    description?: string;
+    version?: string;
+    [key: string]: unknown;
+}
+export type ListTopologiesResponse = SuccessEnvelope<TopologyManifest[]>;
+export type GetTopologyResponse = SuccessEnvelope<TopologyManifest>;
+export interface ValidateSatelliteRequest {
+    workspaceRef: string;
+}
+export interface DetectDriftRequest {
+    workspaceRef: string;
+    declaredLevel?: string;
+}
+export interface ValidationResult {
+    passed: boolean;
+    issues: Array<{
+        ruleId: string;
+        severity: string;
+        title: string;
+        blocking: boolean;
+        category?: string;
+    }>;
+    rulesChecked?: number;
+}
+export type ValidateSatelliteResponse = SuccessEnvelope<ValidationResult>;
+export type DetectDriftResponse = SuccessEnvelope<unknown>;
+export interface InitProjectRequest {
+    workspaceRef: string;
+    name: string;
+    type: string;
+    options?: Record<string, unknown>;
+}
+export interface ProposeAdvanceRequest {
+    workspaceRef: string;
+    currentPhase: string;
+    targetPhase: string;
+    triggerDeploy?: boolean;
+}
+export type InitProjectResponse = SuccessEnvelope<unknown>;
+export type ProposeAdvanceResponse = SuccessEnvelope<unknown>;

package/dist/rest/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/rest/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/rest/types.ts"],"names":[],"mappings":""}

package/dist/satellites.client.d.ts

@@ -0,0 +1,50 @@
+export type SatelliteStatus = 'provisioning' | 'active' | 'linked' | 'error' | 'archived';
+export type SatelliteMode = 'create' | 'adopt';
+export type SatelliteTopology = 'monolith' | 'modular' | 'micro' | 'distributed' | 'custom';
+export interface SatelliteRecord {
+    id: string;
+    name: string;
+    owner: string;
+    repoUrl: string;
+    cloneUrl: string;
+    sshUrl: string;
+    topology: SatelliteTopology | string;
+    phase: string;
+    status: SatelliteStatus;
+    mode: SatelliteMode;
+    coreVersion?: string;
+    parentCorePath?: string;
+    description?: string;
+    linkedAt?: string;
+    createdAt: string;
+    updatedAt: string;
+    metadata?: Record<string, unknown>;
+}
+export interface InitializeSatelliteInput {
+    mode: SatelliteMode;
+    name: string;
+    owner: string;
+    topology: string;
+    phase: string;
+    description?: string;
+    private?: boolean;
+    coreVersion?: string;
+    existingRepoUrl?: string;
+}
+export type RegisterSatelliteInput = Omit<InitializeSatelliteInput, 'mode'> & {
+    mode?: string;
+    repoUrl: string;
+    cloneUrl: string;
+    sshUrl: string;
+};
+export declare class SatellitesClient {
+    private readonly baseUrl;
+    private readonly _headers;
+    constructor(baseUrl: string, apiKey?: string);
+    private get headers();
+    register(input: RegisterSatelliteInput): Promise<SatelliteRecord>;
+    list(): Promise<SatelliteRecord[]>;
+    get(id: string): Promise<SatelliteRecord | null>;
+    update(id: string, patch: Partial<SatelliteRecord>): Promise<SatelliteRecord>;
+    link(id: string, targetSatelliteId: string): Promise<SatelliteRecord>;
+}

package/dist/satellites.client.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SatellitesClient = void 0;
+class SatellitesClient {
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this._headers = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+        };
+    }
+    get headers() {
+        return this._headers;
+    }
+    async register(input) {
+        const res = await fetch(`${this.baseUrl}/api/v1/satellites`, {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify(input),
+        });
+        if (!res.ok)
+            throw new Error(`Register satellite failed: ${res.status}`);
+        const envelope = await res.json();
+        return envelope.data.satellite;
+    }
+    async list() {
+        const res = await fetch(`${this.baseUrl}/api/v1/satellites`, {
+            headers: this.headers,
+        });
+        if (!res.ok)
+            throw new Error(`List satellites failed: ${res.status}`);
+        const envelope = await res.json();
+        return envelope.data.satellites;
+    }
+    async get(id) {
+        const res = await fetch(`${this.baseUrl}/api/v1/satellites/${encodeURIComponent(id)}`, {
+            headers: this.headers,
+        });
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new Error(`Get satellite failed: ${res.status}`);
+        const envelope = await res.json();
+        return envelope.data.satellite;
+    }
+    async update(id, patch) {
+        const res = await fetch(`${this.baseUrl}/api/v1/satellites/${encodeURIComponent(id)}`, {
+            method: 'PATCH',
+            headers: this.headers,
+            body: JSON.stringify(patch),
+        });
+        if (!res.ok)
+            throw new Error(`Update satellite failed: ${res.status}`);
+        const envelope = await res.json();
+        return envelope.data.satellite;
+    }
+    async link(id, targetSatelliteId) {
+        const res = await fetch(`${this.baseUrl}/api/v1/satellites/${encodeURIComponent(id)}/link`, {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify({ targetSatelliteId }),
+        });
+        if (!res.ok)
+            throw new Error(`Link satellite failed: ${res.status}`);
+        const envelope = await res.json();
+        return envelope.data.satellite;
+    }
+}
+exports.SatellitesClient = SatellitesClient;
+//# sourceMappingURL=satellites.client.js.map

package/dist/satellites.client.js.map

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

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@evolith/sdk",
+  "version": "0.1.0",
+  "description": "Typed client library for the Evolith Core REST API and MCP tools",
+  "author": "",
+  "license": "UNLICENSED",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:watch": "tsc -p tsconfig.json --watch",
+    "generate": "echo 'No OpenAPI spec file present — types are hand-authored from the NestJS controller DTOs'",
+    "test": "jest",
+    "test:cov": "jest --coverage",
+    "lint": "eslint \"src/**/*.ts\" --fix"
+  },
+  "devDependencies": {
+    "@evolith/agent-runtime": "*",
+    "@types/jest": "30.0.0",
+    "@types/node": "26.0.0",
+    "jest": "30.4.2",
+    "ts-jest": "29.4.11",
+    "typescript": "6.0.3"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.js$": "$1"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node"
+  },
+  "dependencies": {
+  }
+}