@treeseed/sdk 0.13.0-rc.3 → 0.13.0-rc.30

package/dist/deployment/schemas.js

@@ -0,0 +1,274 @@
+import { z } from "zod";
+const identifier = z.string().regex(/^[a-z][a-z0-9.-]{1,63}$/u);
+const digest = z.string().regex(/^sha256:[a-f0-9]{64}$/u);
+const gitCommit = z.string().regex(/^[a-f0-9]{40}$/u);
+const packageVersion = z.string().min(1).regex(/^[0-9][0-9A-Za-z.+:~-]*$/u);
+const localAlias = z.string().regex(
+  /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*\.localhost$/u,
+  "Host aliases must use the .localhost namespace."
+);
+const binding = z.string().regex(/^(?:\[[0-9a-f:]+\]|[^:]+):[1-9][0-9]{0,4}$/iu);
+const httpsUrl = z.string().url().refine((value) => new URL(value).protocol === "https:", "Remote TreeSeed connections require HTTPS.");
+const deploymentTrackSchema = z.enum(["stable", "development"]);
+const hostRoleSchema = z.union([
+  z.enum(["integrated", "capacity-provider", "control-plane", "knowledge", "ai-gpu", "edge"]),
+  identifier
+]);
+const connectionHealthGateSchema = z.object({
+  protocol: z.enum(["http", "https", "tcp"]),
+  path: z.string().startsWith("/").optional(),
+  timeoutSeconds: z.number().int().positive().max(600)
+}).strict();
+const remoteTlsSchema = z.object({
+  trust: z.enum(["system", "secret", "spki"]),
+  serverName: z.string().min(1).optional(),
+  caSecretRef: identifier.optional(),
+  spkiSha256: digest.optional()
+}).strict().superRefine((tls, context) => {
+  if (tls.trust === "secret" && !tls.caSecretRef) context.addIssue({ code: z.ZodIssueCode.custom, path: ["caSecretRef"], message: "Secret TLS trust requires a CA secret reference." });
+  if (tls.trust === "spki" && !tls.spkiSha256) context.addIssue({ code: z.ZodIssueCode.custom, path: ["spkiSha256"], message: "SPKI TLS trust requires an exact SHA-256 pin." });
+});
+const hostConnectionBindingSchema = z.union([
+  z.object({
+    kind: z.literal("local"),
+    componentId: identifier,
+    serviceId: identifier,
+    endpointId: identifier
+  }).strict(),
+  z.object({
+    kind: z.literal("remote"),
+    url: httpsUrl,
+    audience: z.string().min(1),
+    tls: remoteTlsSchema,
+    authentication: z.object({ mode: z.enum(["none", "application", "bearer", "mtls"]), secretRef: identifier.optional() }).strict(),
+    healthGate: connectionHealthGateSchema
+  }).strict()
+]).superRefine((connection, context) => {
+  if (connection.kind === "remote" && connection.authentication.mode !== "none" && !connection.authentication.secretRef) context.addIssue({ code: z.ZodIssueCode.custom, path: ["authentication", "secretRef"], message: "Authenticated remote connections require a secret reference." });
+});
+const hostComponentSchema = z.object({
+  enabled: z.boolean(),
+  track: deploymentTrackSchema,
+  profile: identifier.optional(),
+  aliases: z.record(z.string().min(1), localAlias).default({}),
+  configuration: z.record(z.unknown()).default({}),
+  resources: z.object({
+    cpuCores: z.number().positive().optional(),
+    memoryBytes: z.number().int().positive().optional(),
+    storageBytes: z.number().int().positive().optional(),
+    gpuDevices: z.array(z.string().min(1)).default([])
+  }).strict().default({ gpuDevices: [] }),
+  connections: z.record(identifier, hostConnectionBindingSchema).default({})
+}).strict();
+const hostConfigurationSchema = z.object({
+  schemaVersion: z.literal("treeseed.host/v1"),
+  configurationId: identifier,
+  generation: z.number().int().positive(),
+  host: z.object({
+    id: identifier,
+    role: hostRoleSchema,
+    architecture: z.literal("amd64")
+  }).strict(),
+  runtime: z.object({ management: z.enum(["managed", "external"]) }).strict(),
+  updates: z.object({
+    defaultTrack: deploymentTrackSchema,
+    stable: z.object({
+      metadataPollSeconds: z.number().int().min(3600),
+      maintenanceWindow: z.object({
+        weekday: z.enum(["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"]),
+        localTime: z.string().regex(/^(?:[01][0-9]|2[0-3]):[0-5][0-9]$/u),
+        jitterMinutes: z.number().int().min(0).max(30)
+      }).strict()
+    }).strict(),
+    development: z.object({ pollSeconds: z.literal(60) }).strict()
+  }).strict(),
+  components: z.record(identifier, hostComponentSchema),
+  network: z.object({
+    manager: z.object({ binding, aliases: z.array(localAlias).default([]), sans: z.array(z.string().min(1)).default([]), trustedLanCidrs: z.array(z.string().min(1)).default([]) }).strict()
+  }).strict(),
+  fleet: z.object({
+    rolloutGroup: identifier,
+    receiptReporting: z.object({
+      enabled: z.boolean(),
+      connection: hostConnectionBindingSchema.optional(),
+      intervalSeconds: z.number().int().min(60).max(86400)
+    }).strict()
+  }).strict().superRefine((fleet, context) => {
+    if (fleet.receiptReporting.enabled && fleet.receiptReporting.connection?.kind !== "remote") context.addIssue({ code: z.ZodIssueCode.custom, path: ["receiptReporting", "connection"], message: "Enabled fleet receipt reporting requires an explicit remote connection." });
+  }),
+  secrets: z.record(identifier, z.object({
+    provider: z.enum(["file", "systemd-credential", "vault", "aws-secrets-manager"]),
+    reference: z.string().min(1)
+  }).strict())
+}).strict();
+const packageEndpointSchema = z.object({
+  id: identifier,
+  protocol: z.enum(["http", "https", "tcp"]),
+  port: z.number().int().min(1).max(65535),
+  visibility: z.enum(["private", "host"]),
+  defaultAlias: localAlias.optional(),
+  aliasOverride: z.boolean().default(true),
+  tls: z.enum(["edge", "passthrough", "none"]),
+  authentication: z.enum(["none", "application", "mtls"]),
+  healthGate: z.object({ protocol: z.enum(["http", "https", "tcp"]), path: z.string().startsWith("/").optional(), timeoutSeconds: z.number().int().positive().max(600) }).strict().optional()
+}).strict().superRefine((endpoint, context) => {
+  if (endpoint.visibility === "host" && !endpoint.defaultAlias) context.addIssue({ code: z.ZodIssueCode.custom, path: ["defaultAlias"], message: "Host-visible endpoints require a .localhost alias." });
+  if (endpoint.visibility === "host" && !endpoint.healthGate) context.addIssue({ code: z.ZodIssueCode.custom, path: ["healthGate"], message: "Host-visible endpoints require a health gate." });
+  if (endpoint.visibility === "private" && endpoint.defaultAlias) context.addIssue({ code: z.ZodIssueCode.custom, path: ["defaultAlias"], message: "Private endpoints cannot declare host aliases." });
+});
+const packageRuntimeSchema = z.object({
+  schemaVersion: z.literal("treeseed.package-runtime/v1"),
+  componentId: identifier,
+  version: packageVersion,
+  compose: z.object({
+    projectName: identifier,
+    files: z.array(z.object({ path: z.string().min(1), digest }).strict()).min(1)
+  }).strict(),
+  services: z.array(z.object({ id: identifier, composeService: identifier, endpoints: z.array(packageEndpointSchema) }).strict()).min(1),
+  stateVolumes: z.array(z.object({ id: identifier, volume: z.string().min(1), backup: z.enum(["required", "optional", "none"]) }).strict()),
+  migrations: z.array(z.object({ id: identifier, order: z.number().int().nonnegative(), backupRequired: z.boolean() }).strict()),
+  requiredCapabilities: z.array(identifier),
+  dependencies: z.array(z.object({
+    id: identifier,
+    capability: identifier,
+    locality: z.enum(["local", "remote", "either"]),
+    optional: z.boolean().default(false)
+  }).strict()).default([])
+}).strict().superRefine((runtime, context) => {
+  const endpointIds = runtime.services.flatMap((service) => service.endpoints.map((endpoint) => `${service.id}.${endpoint.id}`));
+  if (new Set(endpointIds).size !== endpointIds.length) context.addIssue({ code: z.ZodIssueCode.custom, path: ["services"], message: "Endpoint identities must be unique within a component." });
+});
+const catalogPackageSchema = z.object({ name: z.string().regex(/^treeseed(?:-[a-z0-9-]+)?$/u), version: packageVersion, architecture: z.enum(["amd64", "all"]), origin: z.literal("TreeSeed Deployment"), order: z.number().int().nonnegative() }).strict();
+const catalogImageSchema = z.object({ role: identifier, repository: z.string().regex(/^treeseed\/[a-z0-9-]+$/u), digest, platforms: z.array(z.enum(["linux/amd64", "linux/arm64"])).min(1), consumers: z.array(identifier).min(1) }).strict();
+const componentReleaseSchema = z.object({
+  schemaVersion: z.literal("treeseed.component-release/v1"),
+  componentId: identifier,
+  release: packageVersion,
+  applicationVersion: packageVersion,
+  revision: z.number().int().positive(),
+  track: deploymentTrackSchema,
+  source: z.object({ repository: z.string().regex(/^treeseed-ai\/[a-z0-9-]+$/u), commit: gitCommit }).strict(),
+  stableBase: z.object({ releaseRange: z.string().min(1), compatibilityId: identifier, catalogDigest: digest.nullable() }).strict().nullable(),
+  packages: z.array(catalogPackageSchema).min(1),
+  images: z.array(catalogImageSchema),
+  runtime: packageRuntimeSchema,
+  runtimeDigest: digest,
+  rollback: z.object({ compatible: z.boolean(), requiresBackup: z.boolean() }).strict(),
+  evidence: z.object({ provenance: z.array(z.string().url()), sboms: z.array(z.string().url()), vulnerabilities: z.array(z.string().url()) }).strict()
+}).strict().superRefine((release, context) => {
+  if (release.runtime.componentId !== release.componentId || release.runtime.version !== release.release) context.addIssue({ code: z.ZodIssueCode.custom, path: ["runtime"], message: "Runtime identity must match its component release." });
+  if (release.track === "development" && !release.stableBase) context.addIssue({ code: z.ZodIssueCode.custom, path: ["stableBase"], message: "Development releases require an exact stable-base binding." });
+  if (release.track === "stable" && release.stableBase) context.addIssue({ code: z.ZodIssueCode.custom, path: ["stableBase"], message: "Stable releases cannot be overlays." });
+});
+const lockedArtifactSchema = z.object({ url: z.string().url(), sha256: z.string().regex(/^[a-f0-9]{64}$/u) }).strict();
+const integrationReleaseSchema = z.object({
+  schemaVersion: z.literal("treeseed.integration-release/v1"),
+  release: packageVersion,
+  generation: z.number().int().positive(),
+  track: deploymentTrackSchema,
+  compatibilityId: identifier,
+  platform: z.object({ repository: z.literal("treeseed-ai/platform"), commit: gitCommit }).strict(),
+  deployment: z.object({ repository: z.literal("treeseed-ai/deployment"), commit: gitCommit, tag: z.string().min(1) }).strict(),
+  hostPayloads: z.array(z.object({ id: identifier, packageName: z.string().min(1), version: packageVersion, artifact: lockedArtifactSchema }).strict()),
+  components: z.array(z.object({
+    componentId: identifier,
+    release: packageVersion,
+    manifest: lockedArtifactSchema,
+    files: z.array(z.object({ path: z.string().min(1), artifact: lockedArtifactSchema }).strict()).min(1)
+  }).strict()).min(1),
+  createdAt: z.string().datetime()
+}).strict().superRefine((release, context) => {
+  const components = release.components.map((component) => component.componentId);
+  if (new Set(components).size !== components.length) context.addIssue({ code: z.ZodIssueCode.custom, path: ["components"], message: "Integration releases cannot select a component more than once." });
+});
+const releaseCatalogSchema = z.object({
+  schemaVersion: z.literal("treeseed.release-catalog/v1"),
+  release: packageVersion,
+  generation: z.number().int().positive(),
+  track: deploymentTrackSchema,
+  compatibilityId: identifier,
+  catalogDigest: digest,
+  stableBase: z.object({ release: packageVersion, catalogDigest: digest }).strict().nullable(),
+  components: z.array(componentReleaseSchema).min(1),
+  createdAt: z.string().datetime()
+}).strict().superRefine((catalog, context) => {
+  if (catalog.track === "development" && !catalog.stableBase) context.addIssue({ code: z.ZodIssueCode.custom, path: ["stableBase"], message: "Development catalogs require an exact stable base." });
+  if (catalog.track === "stable" && catalog.stableBase) context.addIssue({ code: z.ZodIssueCode.custom, path: ["stableBase"], message: "Stable catalogs cannot bind another stable base." });
+  if (catalog.track === "development" && catalog.stableBase) for (const [index, component] of catalog.components.entries()) {
+    if (component.track !== "development" || component.stableBase?.catalogDigest !== catalog.stableBase.catalogDigest) context.addIssue({ code: z.ZodIssueCode.custom, path: ["components", index, "stableBase", "catalogDigest"], message: "Catalog ingestion must bind every development component to the exact selected stable base." });
+  }
+});
+const hostPlanSchema = z.object({ schemaVersion: z.literal("treeseed.host-plan/v1"), planId: identifier, configurationDigest: digest, catalogDigest: digest, changes: z.array(z.object({ componentId: identifier, action: z.enum(["install", "upgrade", "reconfigure", "remove", "noop"]), from: packageVersion.nullable(), to: packageVersion.nullable() }).strict()), blockers: z.array(z.object({ code: identifier, message: z.string().min(1) }).strict()) }).strict();
+const hostBootstrapSchema = z.object({
+  schemaVersion: z.literal("treeseed.host-bootstrap/v1"),
+  bootstrapId: identifier,
+  configurationDigest: digest,
+  apt: z.object({ origin: z.literal("TreeSeed Deployment"), suite: deploymentTrackSchema, repository: z.string().url(), keyFingerprint: z.string().regex(/^[A-F0-9]{40}$/u) }).strict(),
+  packages: z.array(catalogPackageSchema).min(1),
+  credentialPolicy: z.object({ noStoreResponse: z.literal(true), redactedLogging: z.literal(true), ephemeralGeneration: z.literal(true), deleteAfterInstall: z.literal(true) }).strict(),
+  createdAt: z.string().datetime()
+}).strict();
+const hostUpdateSchema = z.object({
+  schemaVersion: z.literal("treeseed.host-update/v1"),
+  updateId: identifier,
+  track: deploymentTrackSchema,
+  fromCatalogDigest: digest,
+  toCatalogDigest: digest,
+  components: z.array(z.object({ componentId: identifier, from: packageVersion.nullable(), to: packageVersion, imageDigests: z.array(digest) }).strict()).min(1),
+  activation: z.object({ policy: z.enum(["maintenance-window", "continuous"]), eligibleAt: z.string().datetime(), jitterSeconds: z.number().int().nonnegative() }).strict(),
+  state: z.enum(["planned", "draining", "applying", "healthy", "failed", "rolled-back"])
+}).strict();
+const hostReceiptSchema = z.object({ schemaVersion: z.literal("treeseed.host-receipt/v1"), receiptId: identifier, planId: identifier, state: z.enum(["known-good", "degraded", "rolled-back"]), hostId: identifier, role: hostRoleSchema, rolloutGroup: identifier, configurationDigest: digest, catalogDigest: digest, packages: z.array(catalogPackageSchema), images: z.array(catalogImageSchema), runtimes: z.array(z.object({ componentId: identifier, release: packageVersion, runtimeDigest: digest }).strict()), completedAt: z.string().datetime() }).strict();
+const hostBackupSchema = z.object({
+  schemaVersion: z.literal("treeseed.host-backup/v1"),
+  backupId: identifier,
+  componentId: identifier,
+  generation: z.number().int().positive(),
+  state: z.enum(["pending", "complete", "failed", "verified"]),
+  artifacts: z.array(z.object({ volumeId: identifier, location: z.string().min(1), digest, encrypted: z.boolean() }).strict()),
+  createdAt: z.string().datetime(),
+  verifiedAt: z.string().datetime().nullable()
+}).strict();
+const hostMigrationSchema = z.object({
+  schemaVersion: z.literal("treeseed.host-migration/v1"),
+  migrationId: identifier,
+  componentId: identifier,
+  operation: identifier,
+  fromGeneration: z.number().int().nonnegative(),
+  toGeneration: z.number().int().positive(),
+  backupId: identifier.nullable(),
+  state: z.enum(["pending", "quiesced", "copied", "verified", "activated", "failed", "rolled-back"]),
+  sourceWritersStopped: z.boolean(),
+  completedAt: z.string().datetime().nullable()
+}).strict();
+const hostRecoverySchema = z.object({
+  schemaVersion: z.literal("treeseed.host-recovery/v1"),
+  recoveryId: identifier,
+  receiptId: identifier,
+  componentId: identifier.nullable(),
+  trigger: z.enum(["health-gate", "operator", "boot", "interrupted-update"]),
+  action: z.enum(["retry", "rollback", "restore"]),
+  targetGeneration: z.number().int().positive(),
+  state: z.enum(["pending", "running", "healthy", "failed"]),
+  backupId: identifier.nullable(),
+  completedAt: z.string().datetime().nullable()
+}).strict();
+export {
+  componentReleaseSchema,
+  deploymentTrackSchema,
+  hostBackupSchema,
+  hostBootstrapSchema,
+  hostComponentSchema,
+  hostConfigurationSchema,
+  hostConnectionBindingSchema,
+  hostMigrationSchema,
+  hostPlanSchema,
+  hostReceiptSchema,
+  hostRecoverySchema,
+  hostRoleSchema,
+  hostUpdateSchema,
+  integrationReleaseSchema,
+  packageEndpointSchema,
+  packageRuntimeSchema,
+  releaseCatalogSchema
+};

package/dist/deployment/topology.d.ts

@@ -0,0 +1,9 @@
+import type { ComponentRelease, HostConfiguration } from './schemas.js';
+export interface TopologyBlocker {
+    code: 'missing-connection' | 'invalid-locality' | 'missing-local-component' | 'missing-local-endpoint';
+    componentId: string;
+    dependencyId: string;
+    message: string;
+}
+export declare function collectTopologyBlockers(host: HostConfiguration, releases: ComponentRelease[]): TopologyBlocker[];
+export declare function hostNeedsEdge(host: HostConfiguration, releases: ComponentRelease[]): boolean;

package/dist/deployment/topology.js

@@ -0,0 +1,35 @@
+function collectTopologyBlockers(host, releases) {
+  const selected = new Map(releases.map((release) => [release.componentId, release]));
+  const blockers = [];
+  for (const release of releases) {
+    const selection = host.components[release.componentId];
+    if (!selection?.enabled) continue;
+    for (const dependency of release.runtime.dependencies) {
+      const connection = selection.connections[dependency.id];
+      if (!connection) {
+        if (!dependency.optional) blockers.push({ code: "missing-connection", componentId: release.componentId, dependencyId: dependency.id, message: `${release.componentId} requires an explicit ${dependency.id} connection.` });
+        continue;
+      }
+      if (dependency.locality !== "either" && connection.kind !== dependency.locality) {
+        blockers.push({ code: "invalid-locality", componentId: release.componentId, dependencyId: dependency.id, message: `${release.componentId}.${dependency.id} requires a ${dependency.locality} connection.` });
+        continue;
+      }
+      if (connection.kind !== "local") continue;
+      const target = selected.get(connection.componentId);
+      if (!target || !host.components[connection.componentId]?.enabled) {
+        blockers.push({ code: "missing-local-component", componentId: release.componentId, dependencyId: dependency.id, message: `${release.componentId}.${dependency.id} references disabled or unselected component ${connection.componentId}.` });
+        continue;
+      }
+      const service = target.runtime.services.find((candidate) => candidate.id === connection.serviceId);
+      if (!service?.endpoints.some((endpoint) => endpoint.id === connection.endpointId)) blockers.push({ code: "missing-local-endpoint", componentId: release.componentId, dependencyId: dependency.id, message: `${release.componentId}.${dependency.id} references unknown endpoint ${connection.componentId}.${connection.serviceId}.${connection.endpointId}.` });
+    }
+  }
+  return blockers.sort((left, right) => `${left.componentId}.${left.dependencyId}`.localeCompare(`${right.componentId}.${right.dependencyId}`));
+}
+function hostNeedsEdge(host, releases) {
+  return releases.some((release) => host.components[release.componentId]?.enabled && release.runtime.services.some((service) => service.endpoints.some((endpoint) => endpoint.visibility === "host")));
+}
+export {
+  collectTopologyBlockers,
+  hostNeedsEdge
+};

package/dist/entrypoints/clients/control-plane-client.d.ts

@@ -0,0 +1,114 @@
+import type { ControlPlaneOperationBinding, ControlPlaneOperationBody, ControlPlaneOperationOutput, ControlPlaneOperationPath, ControlPlaneOperationQuery, OAuthScope } from '../../operator-contracts/control-plane-operation.js';
+import type { ApiPrincipal } from '../../operator-contracts/oauth.js';
+import type { InputRequired } from '../../operator-contracts/mcp.js';
+export declare const DEFAULT_CONTROL_PLANE_BASE_URL = "http://127.0.0.1:3002";
+export declare const CONTROL_PLANE_BASE_URL_ENV = "TREESEED_API_BASE_URL";
+export interface ControlPlaneServerProfile {
+    serverId: string;
+    label: string;
+    baseUrl: string;
+}
+export interface ControlPlaneServerSession {
+    serverId: string;
+    audience: string;
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: string;
+    principal?: ApiPrincipal | null;
+}
+export interface ControlPlaneServerRegistry {
+    version: 1;
+    activeServerId: string;
+    servers: ControlPlaneServerProfile[];
+}
+export interface OAuthDeviceAuthorizationReceipt {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete?: string;
+    expiresIn: number;
+    interval: number;
+}
+export interface OAuthTokenReceipt {
+    tokenType: 'Bearer';
+    accessToken: string;
+    expiresIn: number;
+    refreshToken?: string;
+    scope: OAuthScope[];
+    audience: string;
+    principal?: ApiPrincipal | null;
+}
+export interface ControlPlaneClientOptions {
+    profile: ControlPlaneServerProfile;
+    accessToken?: string | null;
+    fetchImpl?: typeof fetch;
+    userAgent?: string;
+}
+export interface ControlPlaneResponseEnvelope<T> {
+    data: T;
+    meta?: Record<string, unknown>;
+    links?: Record<string, string>;
+}
+export interface ProblemDetails {
+    type: string;
+    title: string;
+    status: number;
+    detail?: string;
+    instance?: string;
+    code: string;
+    requestId?: string;
+    traceId?: string;
+    fields?: Record<string, string[]>;
+    inputRequired?: InputRequired;
+}
+export interface ControlPlaneCallOptions {
+    method?: 'DELETE' | 'GET' | 'PATCH' | 'POST' | 'PUT';
+    path: `/v1/${string}` | '/openapi.json';
+    input?: unknown;
+    headers?: Record<string, string>;
+    idempotencyKey?: string;
+    ifMatch?: string;
+    authorization?: string | null;
+    signal?: AbortSignal;
+}
+export interface ControlPlaneOperationCallOptions {
+    headers?: Record<string, string>;
+    idempotencyKey?: string;
+    ifMatch?: string;
+    authorization?: string | null;
+    signal?: AbortSignal;
+}
+export interface ControlPlaneInvocation<TPath, TQuery, TBody> {
+    path: TPath;
+    query: TQuery;
+    body: TBody;
+}
+export declare class ControlPlaneClientError extends Error {
+    readonly status: number;
+    readonly problem: ProblemDetails;
+    readonly responseHeaders: Headers;
+    constructor(message: string, status: number, problem: ProblemDetails, responseHeaders: Headers);
+}
+export declare function normalizeControlPlaneBaseUrl(value: string): string;
+export declare function defaultLocalControlPlaneServer(env?: Record<string, string | undefined>): ControlPlaneServerProfile;
+export declare function normalizeControlPlaneServerRegistry(state: ControlPlaneServerRegistry): {
+    version: 1;
+    activeServerId: string;
+    servers: ControlPlaneServerProfile[];
+};
+export declare function resolveControlPlaneServer(selector: string | null | undefined, registry: ControlPlaneServerRegistry): ControlPlaneServerProfile;
+export declare class ControlPlaneClient {
+    readonly options: ControlPlaneClientOptions;
+    readonly baseUrl: string;
+    readonly accessToken: string | null;
+    readonly fetchImpl: typeof fetch;
+    readonly userAgent?: string;
+    constructor(options: ControlPlaneClientOptions);
+    invoke<TOperation extends ControlPlaneOperationBinding<any, any, any, any>>(binding: TOperation, input: ControlPlaneInvocation<ControlPlaneOperationPath<TOperation>, ControlPlaneOperationQuery<TOperation>, ControlPlaneOperationBody<TOperation>>, options?: ControlPlaneOperationCallOptions): Promise<ControlPlaneResponseEnvelope<ControlPlaneOperationOutput<TOperation>>>;
+    authorizeDevice(clientId: string, scope: OAuthScope[], signal?: AbortSignal): Promise<OAuthDeviceAuthorizationReceipt>;
+    exchangeDeviceCode(clientId: string, deviceCode: string, signal?: AbortSignal): Promise<OAuthTokenReceipt>;
+    refreshAccessToken(clientId: string, refreshToken: string, signal?: AbortSignal): Promise<OAuthTokenReceipt>;
+    revokeToken(clientId: string, token: string, signal?: AbortSignal): Promise<void>;
+    private exchangeOAuthToken;
+    private request;
+}

package/dist/entrypoints/clients/control-plane-client.js

@@ -0,0 +1,186 @@
+import { controlPlaneOperation } from "../../operator-contracts/control-plane-operations.js";
+const DEFAULT_CONTROL_PLANE_BASE_URL = "http://127.0.0.1:3002";
+const CONTROL_PLANE_BASE_URL_ENV = "TREESEED_API_BASE_URL";
+class ControlPlaneClientError extends Error {
+  constructor(message, status, problem, responseHeaders) {
+    super(message);
+    this.status = status;
+    this.problem = problem;
+    this.responseHeaders = responseHeaders;
+    this.name = "ControlPlaneClientError";
+  }
+  status;
+  problem;
+  responseHeaders;
+}
+function normalizeControlPlaneBaseUrl(value) {
+  const normalized = value.trim().replace(/\/+$/u, "");
+  if (!/^https?:\/\//u.test(normalized)) throw new Error("Control-plane server URLs must use HTTP or HTTPS.");
+  return normalized;
+}
+function defaultLocalControlPlaneServer(env = process.env) {
+  return {
+    serverId: "local",
+    label: "Local TreeSeed control plane",
+    baseUrl: normalizeControlPlaneBaseUrl(env[CONTROL_PLANE_BASE_URL_ENV] ?? DEFAULT_CONTROL_PLANE_BASE_URL)
+  };
+}
+function normalizeServer(profile) {
+  const serverId = profile.serverId.trim();
+  if (!serverId) throw new Error("Control-plane server IDs cannot be empty.");
+  return { serverId, label: profile.label.trim() || serverId, baseUrl: normalizeControlPlaneBaseUrl(profile.baseUrl) };
+}
+function normalizeControlPlaneServerRegistry(state) {
+  const servers = [...new Map(state.servers.map((entry) => {
+    const normalized = normalizeServer(entry);
+    return [normalized.serverId, normalized];
+  })).values()].sort((left, right) => left.serverId.localeCompare(right.serverId));
+  if (servers.length === 0) throw new Error("A control-plane server registry requires at least one server.");
+  const activeServerId = servers.some((entry) => entry.serverId === state.activeServerId) ? state.activeServerId : servers[0].serverId;
+  return { version: 1, activeServerId, servers };
+}
+function resolveControlPlaneServer(selector, registry) {
+  const value = selector?.trim();
+  if (value && /^https?:\/\//iu.test(value)) {
+    return normalizeServer({ serverId: value.replace(/^https?:\/\//iu, "").replace(/[^a-z0-9._-]+/giu, "-"), label: value, baseUrl: value });
+  }
+  const normalized = normalizeControlPlaneServerRegistry(registry);
+  const serverId = value || normalized.activeServerId;
+  const profile = normalized.servers.find((entry) => entry.serverId === serverId);
+  if (!profile) throw new Error(`Unknown control-plane server "${serverId}".`);
+  return profile;
+}
+async function responsePayload(response) {
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.includes("json")) return response.json();
+  const text = await response.text();
+  return text.length > 0 ? text : null;
+}
+function problemFrom(payload, status) {
+  const source = payload && typeof payload === "object" ? payload : {};
+  return {
+    type: typeof source.type === "string" ? source.type : "about:blank",
+    title: typeof source.title === "string" ? source.title : "Control-plane request failed",
+    status,
+    detail: typeof source.detail === "string" ? source.detail : void 0,
+    instance: typeof source.instance === "string" ? source.instance : void 0,
+    code: typeof source.code === "string" ? source.code : "control_plane_request_failed",
+    requestId: typeof source.requestId === "string" ? source.requestId : void 0,
+    traceId: typeof source.traceId === "string" ? source.traceId : void 0,
+    fields: source.fields && typeof source.fields === "object" ? source.fields : void 0,
+    inputRequired: source.inputRequired && typeof source.inputRequired === "object" ? source.inputRequired : void 0
+  };
+}
+class ControlPlaneClient {
+  constructor(options) {
+    this.options = options;
+    this.baseUrl = normalizeControlPlaneBaseUrl(options.profile.baseUrl);
+    this.accessToken = options.accessToken ?? null;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+    this.userAgent = options.userAgent;
+  }
+  options;
+  baseUrl;
+  accessToken;
+  fetchImpl;
+  userAgent;
+  async invoke(binding, input, options = {}) {
+    if (controlPlaneOperation(binding.descriptor.operationId) !== binding) {
+      throw new Error(`Operation ${binding.descriptor.operationId} is not the authoritative catalog binding.`);
+    }
+    const rest = binding.descriptor.rest;
+    if (!rest) throw new Error(`Operation ${binding.descriptor.operationId} has no REST binding.`);
+    const pathInput = binding.schema.path.parse(input.path);
+    const queryInput = binding.schema.query.parse(input.query);
+    const bodyInput = binding.schema.body.parse(input.body);
+    let path = rest.path;
+    path = path.replace(/\{([A-Za-z][A-Za-z0-9]*)\}/gu, (_match, name) => {
+      const value = pathInput[name];
+      if (typeof value !== "string" && typeof value !== "number") throw new Error(`Operation ${binding.descriptor.operationId} requires path parameter ${name}.`);
+      return encodeURIComponent(String(value));
+    });
+    if (path.includes("{")) throw new Error(`Operation ${binding.descriptor.operationId} has unresolved path parameters.`);
+    const query = new URLSearchParams();
+    for (const [name, value] of Object.entries(queryInput)) {
+      if (value === void 0 || value === null) continue;
+      for (const item of Array.isArray(value) ? value : [value]) query.append(name, String(item));
+    }
+    const queryString = query.toString();
+    const response = await this.request({
+      method: rest.method,
+      path: `${path}${queryString ? `?${queryString}` : ""}`,
+      input: rest.method === "GET" ? void 0 : bodyInput,
+      ...options
+    });
+    return { ...response, data: binding.schema.output.parse(response.data) };
+  }
+  async authorizeDevice(clientId, scope, signal) {
+    const response = await this.fetchImpl(`${this.baseUrl}/oauth/device_authorization`, { method: "POST", headers: { accept: "application/json", "content-type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ client_id: clientId, scope: scope.join(" ") }), signal });
+    const payload = await responsePayload(response);
+    if (!response.ok) throw new ControlPlaneClientError(String(payload.error_description ?? payload.error ?? "Device authorization failed."), response.status, problemFrom(payload, response.status), response.headers);
+    return { deviceCode: String(payload.device_code), userCode: String(payload.user_code), verificationUri: String(payload.verification_uri), verificationUriComplete: typeof payload.verification_uri_complete === "string" ? payload.verification_uri_complete : void 0, expiresIn: Number(payload.expires_in), interval: Number(payload.interval) };
+  }
+  async exchangeDeviceCode(clientId, deviceCode, signal) {
+    return this.exchangeOAuthToken({ client_id: clientId, grant_type: "urn:ietf:params:oauth:grant-type:device_code", device_code: deviceCode }, signal);
+  }
+  async refreshAccessToken(clientId, refreshToken, signal) {
+    return this.exchangeOAuthToken({ client_id: clientId, grant_type: "refresh_token", refresh_token: refreshToken }, signal);
+  }
+  async revokeToken(clientId, token, signal) {
+    const response = await this.fetchImpl(`${this.baseUrl}/oauth/revoke`, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ client_id: clientId, token }), signal });
+    if (!response.ok) throw new ControlPlaneClientError("Token revocation failed.", response.status, problemFrom(await responsePayload(response), response.status), response.headers);
+  }
+  async exchangeOAuthToken(values, signal) {
+    const response = await this.fetchImpl(`${this.baseUrl}/oauth/token`, { method: "POST", headers: { accept: "application/json", "content-type": "application/x-www-form-urlencoded" }, body: new URLSearchParams(values), signal });
+    const payload = await responsePayload(response);
+    if (!response.ok) {
+      const problem = problemFrom(payload, response.status);
+      problem.code = typeof payload.error === "string" ? payload.error : problem.code;
+      problem.detail = typeof payload.error_description === "string" ? payload.error_description : problem.detail;
+      throw new ControlPlaneClientError(problem.detail ?? problem.code, response.status, problem, response.headers);
+    }
+    return { tokenType: "Bearer", accessToken: String(payload.access_token), refreshToken: typeof payload.refresh_token === "string" ? payload.refresh_token : void 0, expiresIn: Number(payload.expires_in), scope: String(payload.scope ?? "").split(/\s+/u).filter(Boolean), audience: String(payload.audience ?? this.baseUrl), principal: payload.principal && typeof payload.principal === "object" ? payload.principal : void 0 };
+  }
+  async request(options) {
+    const headers = new Headers(options.headers);
+    headers.set("accept", "application/json, application/problem+json");
+    if (options.authorization !== null) {
+      const authorization = options.authorization ?? (this.accessToken ? `Bearer ${this.accessToken}` : null);
+      if (authorization) headers.set("authorization", authorization);
+    }
+    if (this.userAgent) headers.set("user-agent", this.userAgent);
+    if (options.idempotencyKey) headers.set("idempotency-key", options.idempotencyKey);
+    if (options.ifMatch) headers.set("if-match", options.ifMatch);
+    if (options.input !== void 0) headers.set("content-type", "application/json");
+    const response = await this.fetchImpl(`${this.baseUrl}${options.path}`, {
+      method: options.method ?? "GET",
+      headers,
+      body: options.input === void 0 ? void 0 : JSON.stringify(options.input),
+      signal: options.signal
+    });
+    const payload = await responsePayload(response);
+    if (!response.ok) {
+      const problem = problemFrom(payload, response.status);
+      throw new ControlPlaneClientError(problem.detail ?? problem.title, response.status, problem, response.headers);
+    }
+    if (!payload || typeof payload !== "object" || !("data" in payload)) {
+      throw new ControlPlaneClientError("The control plane returned an invalid success envelope.", 502, {
+        type: "https://treeseed.dev/problems/invalid-upstream-response",
+        title: "Invalid control-plane response",
+        status: 502,
+        code: "control_plane_response_invalid"
+      }, response.headers);
+    }
+    return payload;
+  }
+}
+export {
+  CONTROL_PLANE_BASE_URL_ENV,
+  ControlPlaneClient,
+  ControlPlaneClientError,
+  DEFAULT_CONTROL_PLANE_BASE_URL,
+  defaultLocalControlPlaneServer,
+  normalizeControlPlaneBaseUrl,
+  normalizeControlPlaneServerRegistry,
+  resolveControlPlaneServer
+};

package/dist/entrypoints/models/sdk-types.d.ts

@@ -1,10 +1,3 @@
-export * from '../../sdk-types/commerce/capacity/commerce-capacity-listing-input.js';
-export * from '../../sdk-types/commerce/catalog/upsert-catalog-item-request.js';
-export * from '../../sdk-types/commerce/governance/commerce-governance-states.js';
-export * from '../../sdk-types/commerce/payments/commerce-entitlement.js';
-export * from '../../sdk-types/commerce/payments/commerce-subscription-statuses.js';
-export * from '../../sdk-types/commerce/services/commerce-service-contract.js';
-export * from '../../sdk-types/commerce/vendors/commerce-stripe-onboarding-request-input.js';
 export * from '../../sdk-types/configuration/sdk-dispatch-credential-source.js';
 export * from '../../sdk-types/governance/commons/commons-question-input.js';
 export * from '../../sdk-types/support/planning-policy.js';
@@ -14,3 +7,4 @@ export * from '../../sdk-types/support/sdk-model-names.js';
 export * from '../../sdk-types/support/sdk-search-request.js';
 export * from '../../sdk-types/treedx/graph/sdk-graph-query-request.js';
 export * from '../../projects/projects-core/project-workflow.js';
+export * from '../../sdk-types/control-plane/resource-requests.js';

package/dist/entrypoints/models/sdk-types.js

@@ -1,10 +1,3 @@
-export * from "../../sdk-types/commerce/capacity/commerce-capacity-listing-input.js";
-export * from "../../sdk-types/commerce/catalog/upsert-catalog-item-request.js";
-export * from "../../sdk-types/commerce/governance/commerce-governance-states.js";
-export * from "../../sdk-types/commerce/payments/commerce-entitlement.js";
-export * from "../../sdk-types/commerce/payments/commerce-subscription-statuses.js";
-export * from "../../sdk-types/commerce/services/commerce-service-contract.js";
-export * from "../../sdk-types/commerce/vendors/commerce-stripe-onboarding-request-input.js";
 export * from "../../sdk-types/configuration/sdk-dispatch-credential-source.js";
 export * from "../../sdk-types/governance/commons/commons-question-input.js";
 export * from "../../sdk-types/support/planning-policy.js";
@@ -14,3 +7,4 @@ export * from "../../sdk-types/support/sdk-model-names.js";
 export * from "../../sdk-types/support/sdk-search-request.js";
 export * from "../../sdk-types/treedx/graph/sdk-graph-query-request.js";
 export * from "../../projects/projects-core/project-workflow.js";
+export * from "../../sdk-types/control-plane/resource-requests.js";