@treeseed/sdk 0.13.0-rc.1 → 0.13.0-rc.10

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

@@ -0,0 +1,112 @@
+import type { ControlPlaneOperationBinding, ControlPlaneOperationBody, ControlPlaneOperationOutput, ControlPlaneOperationPath, ControlPlaneOperationQuery, OAuthScope } from '../../operator-contracts/control-plane-operation.js';
+import type { ApiPrincipal } from '../../operator-contracts/oauth.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[]>;
+}
+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,180 @@
+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
+  };
+}
+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) throw new ControlPlaneClientError(String(payload.error_description ?? payload.error ?? "OAuth token exchange failed."), response.status, problemFrom(payload, response.status), 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";

package/dist/knowledge/index.d.ts

@@ -1,9 +1 @@
 export * from './contracts.js';
-export * from './catalog.js';
-export * from './authoring.js';
-export * from './markdown.js';
-export * from './routes.js';
-export * from './collaboration.js';
-export * from './publication.js';
-export * from './editorial-context.js';
-export * from './editorial-review.js';

package/dist/knowledge/index.js

@@ -1,9 +1 @@
 export * from "./contracts.js";
-export * from "./catalog.js";
-export * from "./authoring.js";
-export * from "./markdown.js";
-export * from "./routes.js";
-export * from "./collaboration.js";
-export * from "./publication.js";
-export * from "./editorial-context.js";
-export * from "./editorial-review.js";

package/dist/operator-contracts/canonical-command-tree.d.ts

@@ -0,0 +1,3 @@
+import type { CommandTreeDescriptor } from './command-tree.js';
+export declare const TREESEED_COMMAND_TREE_V1: CommandTreeDescriptor;
+export declare function listCommandPaths(tree?: CommandTreeDescriptor): string[];

package/dist/operator-contracts/canonical-command-tree.js

@@ -0,0 +1,81 @@
+const planOption = { name: "--plan", description: "Return the exact proposed outcome without mutation.", type: "boolean" };
+function leaf(segment, kind = "read", argument, confirmation = "never") {
+  const value = {
+    segment,
+    description: `${segment[0].toUpperCase()}${segment.slice(1)} the selected resource.`,
+    kind,
+    arguments: argument ? [{ name: argument, description: `${argument} identity or path.`, required: true }] : void 0,
+    options: kind === "mutation" ? [planOption] : void 0,
+    authorization: kind === "mutation" ? { capability: `command.${segment}`, confirmation } : void 0,
+    resultSchemaId: `treeseed.command.${segment}/v1`
+  };
+  return { nodeType: "leaf", ...value };
+}
+function branch(segment, children) {
+  return { nodeType: "branch", segment, description: `${segment[0].toUpperCase()}${segment.slice(1)} operations.`, children };
+}
+const TREESEED_COMMAND_TREE_V1 = {
+  schemaVersion: "treeseed.command-tree/v1",
+  executable: "trsd",
+  commands: [
+    branch("auth", [leaf("login", "mutation", void 0, "credential"), leaf("logout", "mutation"), leaf("status")]),
+    branch("secrets", [leaf("list"), leaf("status"), leaf("unlock", "mutation", void 0, "credential"), leaf("lock", "mutation"), leaf("rotate", "mutation", void 0, "credential")]),
+    branch("agents", [
+      leaf("list"),
+      leaf("show", "read", "agent"),
+      leaf("validate"),
+      leaf("diff"),
+      leaf("diagnose"),
+      branch("classes", [leaf("list"), leaf("show", "read", "class")]),
+      branch("bindings", [leaf("list"), leaf("show", "read", "binding"), leaf("explain", "read", "binding")])
+    ]),
+    branch("providers", [
+      leaf("list"),
+      leaf("show", "read", "provider"),
+      leaf("status", "read", "provider"),
+      leaf("diagnose", "read", "provider"),
+      leaf("connect", "mutation", void 0, "credential"),
+      leaf("disconnect", "mutation", "connection", "destructive"),
+      branch("requests", [leaf("list"), leaf("show", "read", "request"), leaf("approve", "mutation", "request", "authority"), leaf("reject", "mutation", "request", "authority")]),
+      branch("credentials", [leaf("status", "read", "connection"), leaf("rotate", "mutation", "connection", "credential"), leaf("revoke", "mutation", "connection", "irreversible")]),
+      branch("offers", [leaf("show", "read", "connection"), leaf("validate", "read", "file"), leaf("plan", "read", "file"), leaf("apply", "mutation", "file", "authority")])
+    ]),
+    branch("capacity", [leaf("status"), leaf("explain"), leaf("usage"), leaf("ledger"), leaf("audit")]),
+    branch("plans", [leaf("list"), leaf("show", "read", "plan"), leaf("explain", "read", "plan"), { nodeType: "leaf", segment: "diff", description: "Compare two API-derived plans.", kind: "read", arguments: [{ name: "left", description: "Left plan identity.", required: true }, { name: "right", description: "Right plan identity.", required: true }], resultSchemaId: "treeseed.command.plans.diff/v1" }]),
+    branch("workdays", [
+      branch("profiles", [leaf("list"), leaf("show", "read", "profile"), leaf("validate", "read", "file")]),
+      leaf("plan"),
+      leaf("start", "mutation", void 0, "authority"),
+      leaf("list"),
+      leaf("show", "read", "workday"),
+      leaf("watch", "read", "workday"),
+      leaf("pause", "mutation", "workday", "authority"),
+      leaf("resume", "mutation", "workday", "authority"),
+      leaf("stop", "mutation", "workday", "destructive"),
+      leaf("cancel", "mutation", "workday", "destructive"),
+      branch("schedules", [leaf("list"), leaf("show", "read", "schedule"), leaf("plan"), leaf("start", "mutation", void 0, "authority"), leaf("pause", "mutation", "schedule", "authority"), leaf("resume", "mutation", "schedule", "authority"), leaf("retire", "mutation", "schedule", "destructive")])
+    ]),
+    branch("assignments", [leaf("list"), leaf("show", "read", "assignment"), leaf("explain", "read", "assignment"), leaf("watch", "read", "assignment"), leaf("retry", "mutation", "assignment", "authority"), leaf("cancel", "mutation", "assignment", "destructive"), leaf("artifacts", "read", "assignment")]),
+    leaf("save", "mutation"),
+    leaf("stage", "mutation", void 0, "authority"),
+    leaf("release", "mutation", void 0, "production"),
+    leaf("status"),
+    leaf("diagnose")
+  ]
+};
+function listCommandPaths(tree = TREESEED_COMMAND_TREE_V1) {
+  const paths = [];
+  const visit = (nodes, parent) => {
+    for (const node of nodes) {
+      const path = [...parent, node.segment];
+      if (node.nodeType === "leaf") paths.push(path.join(" "));
+      else visit(node.children, path);
+    }
+  };
+  visit(tree.commands, []);
+  return paths;
+}
+export {
+  TREESEED_COMMAND_TREE_V1,
+  listCommandPaths
+};

package/dist/operator-contracts/command-tree.d.ts

@@ -0,0 +1,79 @@
+export type CommandOperationKind = 'read' | 'mutation';
+export type CommandExecutionMode = 'execute' | 'plan';
+export type CommandErrorCategory = 'unknown_command' | 'invalid_input' | 'ambiguous_context' | 'authentication_required' | 'authorization_denied' | 'confirmation_required' | 'policy_blocked' | 'stale_preflight' | 'conflict' | 'not_found' | 'provider_unavailable' | 'rate_limited' | 'internal_error';
+export interface CommandArgumentDescriptor {
+    name: string;
+    description: string;
+    required: boolean;
+    multiple?: boolean;
+}
+export interface CommandOptionDescriptor {
+    name: `--${string}`;
+    description: string;
+    type: 'boolean' | 'string' | 'number' | 'string[]';
+    required?: boolean;
+    defaultValue?: boolean | string | number | string[];
+    sensitive?: boolean;
+}
+export interface CommandAuthorizationDescriptor {
+    capability: string;
+    confirmation: 'never' | 'destructive' | 'credential' | 'authority' | 'production' | 'irreversible';
+}
+export interface CommandLeafDescriptor {
+    segment: string;
+    description: string;
+    kind: CommandOperationKind;
+    arguments?: CommandArgumentDescriptor[];
+    options?: CommandOptionDescriptor[];
+    authorization?: CommandAuthorizationDescriptor;
+    resultSchemaId: string;
+}
+export interface CommandBranchDescriptor {
+    segment: string;
+    description: string;
+    children: CommandNodeDescriptor[];
+}
+export type CommandNodeDescriptor = ({
+    nodeType: 'branch';
+} & CommandBranchDescriptor) | ({
+    nodeType: 'leaf';
+} & CommandLeafDescriptor);
+export interface CommandTreeDescriptor {
+    schemaVersion: 'treeseed.command-tree/v1';
+    executable: 'trsd';
+    commands: CommandNodeDescriptor[];
+}
+export interface CommandBlocker {
+    code: string;
+    message: string;
+    path?: string;
+}
+export interface CommandReceiptReference {
+    kind: string;
+    id: string;
+    digest?: string;
+    uri?: string;
+}
+export interface CommandResultEnvelope<TResult = unknown> {
+    schemaVersion: 'treeseed.command-result/v1';
+    commandPath: string[];
+    mode: CommandExecutionMode;
+    ok: boolean;
+    result: TResult | null;
+    error: {
+        category: CommandErrorCategory;
+        code: string;
+        message: string;
+    } | null;
+    warnings: string[];
+    blockers: CommandBlocker[];
+    receipts: CommandReceiptReference[];
+    nextActions: string[];
+}
+export interface CommandTreeDiagnostic {
+    code: string;
+    path: string;
+    message: string;
+}
+export declare function validateCommandTree(tree: CommandTreeDescriptor): CommandTreeDiagnostic[];
+export declare function createCommandResult<TResult>(input: Omit<CommandResultEnvelope<TResult>, 'schemaVersion'>): CommandResultEnvelope<TResult>;

package/dist/operator-contracts/command-tree.js

@@ -0,0 +1,53 @@
+const SEGMENT = /^[a-z][a-z0-9]*$/;
+const FORBIDDEN_AGENT_MANAGEMENT_OPTIONS = /* @__PURE__ */ new Set([
+  "--commit",
+  "--commit-sha",
+  "--source-ref",
+  "--expected-base",
+  "--expected-commit",
+  "--branch",
+  "--checkpoint",
+  "--integration"
+]);
+function validateCommandTree(tree) {
+  const diagnostics = [];
+  if (tree.schemaVersion !== "treeseed.command-tree/v1") diagnostics.push({ code: "schema_version_invalid", path: "schemaVersion", message: "Command tree schemaVersion must be treeseed.command-tree/v1." });
+  if (tree.executable !== "trsd") diagnostics.push({ code: "executable_invalid", path: "executable", message: "trsd is the only public executable." });
+  const visit = (nodes, parent) => {
+    const segments = /* @__PURE__ */ new Set();
+    for (const [index, node] of nodes.entries()) {
+      const path = [...parent, node.segment];
+      const diagnosticPath = `commands.${path.join(".")}`;
+      if (!SEGMENT.test(node.segment)) diagnostics.push({ code: "command_segment_invalid", path: diagnosticPath, message: "Command path segments must be lowercase alphanumeric words without colons or hyphens." });
+      if (segments.has(node.segment)) diagnostics.push({ code: "command_path_duplicate", path: diagnosticPath, message: `Duplicate command segment ${node.segment}.` });
+      segments.add(node.segment);
+      const raw = node;
+      if ("alias" in raw || "aliases" in raw) diagnostics.push({ code: "command_alias_forbidden", path: diagnosticPath, message: "Public command aliases are forbidden." });
+      if (node.nodeType === "branch") {
+        if ("kind" in raw || "resultSchemaId" in raw || "options" in raw || "arguments" in raw) diagnostics.push({ code: "command_node_ambiguous", path: diagnosticPath, message: "Intermediate command nodes cannot also declare leaf behavior." });
+        if (!Array.isArray(node.children) || node.children.length === 0) diagnostics.push({ code: "command_branch_empty", path: diagnosticPath, message: "Intermediate command nodes must contain at least one child." });
+        visit(node.children ?? [], path);
+        continue;
+      }
+      if ("children" in raw) diagnostics.push({ code: "command_node_ambiguous", path: diagnosticPath, message: "Leaf command nodes cannot contain child commands." });
+      if (!node.resultSchemaId.trim()) diagnostics.push({ code: "result_schema_required", path: `${diagnosticPath}.resultSchemaId`, message: "Leaf commands require a stable result schema." });
+      const optionNames = /* @__PURE__ */ new Set();
+      for (const option of node.options ?? []) {
+        if (optionNames.has(option.name)) diagnostics.push({ code: "command_option_duplicate", path: `${diagnosticPath}.options.${index}`, message: `Duplicate option ${option.name}.` });
+        optionNames.add(option.name);
+        if (option.name === "--execute") diagnostics.push({ code: "execute_option_forbidden", path: `${diagnosticPath}.options.${option.name}`, message: "Mutations execute by default; --plan is the only dry-run switch." });
+        if (parent[0] === "agents" && FORBIDDEN_AGENT_MANAGEMENT_OPTIONS.has(option.name)) diagnostics.push({ code: "agent_internal_option_forbidden", path: `${diagnosticPath}.options.${option.name}`, message: "Agent management commands cannot expose repository integration mechanics." });
+      }
+      if (node.kind === "mutation" && !optionNames.has("--plan")) diagnostics.push({ code: "mutation_plan_option_required", path: `${diagnosticPath}.options`, message: "Every mutation must expose universal zero-mutation --plan mode." });
+    }
+  };
+  visit(tree.commands, []);
+  return diagnostics;
+}
+function createCommandResult(input) {
+  return { schemaVersion: "treeseed.command-result/v1", ...input };
+}
+export {
+  createCommandResult,
+  validateCommandTree
+};

package/dist/operator-contracts/control-plane-operation.d.ts

@@ -0,0 +1,80 @@
+import type { z } from 'zod';
+export declare const CONTROL_PLANE_OPERATION_SCHEMA_VERSION: "treeseed.control-plane-operation/v1";
+export type ControlPlaneHttpMethod = 'DELETE' | 'GET' | 'PATCH' | 'POST' | 'PUT';
+export type ControlPlaneOperationKind = 'read' | 'mutation';
+export type ControlPlaneRiskClass = 'ordinary' | 'destructive' | 'credential' | 'authority' | 'production' | 'irreversible';
+export type ControlPlaneConfirmationPolicy = 'never' | 'input_required';
+export type ControlPlaneOperationSurface = 'rest' | 'cli' | 'mcp_tool' | 'mcp_resource' | 'internal';
+export type ControlPlaneCacheScope = 'none' | 'principal' | 'team' | 'project' | 'public';
+export type ControlPlanePaginationKind = 'none' | 'cursor';
+export interface ControlPlaneRestBinding {
+    method: ControlPlaneHttpMethod;
+    path: `/v1/${string}`;
+}
+export interface ControlPlaneSchemaBinding {
+    input: string;
+    output: string;
+    parameters?: string;
+    errors: string;
+}
+export interface ControlPlaneIdempotencyContract {
+    required: boolean;
+    header: 'Idempotency-Key';
+}
+export interface ControlPlaneConcurrencyContract {
+    required: boolean;
+    readHeader: 'ETag';
+    writeHeader: 'If-Match';
+}
+export interface ControlPlaneOperationDescriptor {
+    schemaVersion: typeof CONTROL_PLANE_OPERATION_SCHEMA_VERSION;
+    operationId: `${string}.${string}`;
+    description: string;
+    rest?: ControlPlaneRestBinding;
+    schemas: ControlPlaneSchemaBinding;
+    capability: string;
+    oauthScopes: OAuthScope[];
+    kind: ControlPlaneOperationKind;
+    riskClass: ControlPlaneRiskClass;
+    confirmation: ControlPlaneConfirmationPolicy;
+    idempotency: ControlPlaneIdempotencyContract;
+    concurrency: ControlPlaneConcurrencyContract;
+    surfaces: ControlPlaneOperationSurface[];
+    cacheScope: ControlPlaneCacheScope;
+    pagination: ControlPlanePaginationKind;
+    audited: boolean;
+    receipt: boolean;
+    redactedPaths: string[];
+}
+export interface ControlPlaneOperationInput<TPath = Record<string, never>, TQuery = Record<string, never>, TBody = undefined> {
+    path: TPath;
+    query: TQuery;
+    body: TBody;
+}
+export interface ControlPlaneOperationSchemas<TPath, TQuery, TBody, TOutput> {
+    path: z.ZodType<TPath>;
+    query: z.ZodType<TQuery>;
+    body: z.ZodType<TBody>;
+    output: z.ZodType<TOutput>;
+}
+export interface ControlPlaneOperationBinding<TPath = Record<string, never>, TQuery = Record<string, never>, TBody = undefined, TOutput = unknown> {
+    descriptor: ControlPlaneOperationDescriptor;
+    schema: ControlPlaneOperationSchemas<TPath, TQuery, TBody, TOutput>;
+}
+export type ControlPlaneOperationPath<T> = T extends ControlPlaneOperationBinding<infer TPath, any, any, any> ? TPath : never;
+export type ControlPlaneOperationQuery<T> = T extends ControlPlaneOperationBinding<any, infer TQuery, any, any> ? TQuery : never;
+export type ControlPlaneOperationBody<T> = T extends ControlPlaneOperationBinding<any, any, infer TBody, any> ? TBody : never;
+export type ControlPlaneOperationOutput<T> = T extends ControlPlaneOperationBinding<any, any, any, infer TOutput> ? TOutput : never;
+export declare const TREESEED_OAUTH_SCOPES: readonly ["treeseed:read", "treeseed:knowledge:write", "treeseed:governance:write", "treeseed:projects:write", "treeseed:execution", "treeseed:admin"];
+export type OAuthScope = typeof TREESEED_OAUTH_SCOPES[number];
+export interface ControlPlaneCatalog {
+    schemaVersion: 'treeseed.control-plane-catalog/v1';
+    operations: ControlPlaneOperationDescriptor[];
+}
+export interface ControlPlaneCatalogDiagnostic {
+    code: string;
+    path: string;
+    message: string;
+}
+export declare function validateControlPlaneCatalog(catalog: ControlPlaneCatalog): ControlPlaneCatalogDiagnostic[];
+export declare function indexControlPlaneCatalog(catalog: ControlPlaneCatalog): Map<`${string}.${string}`, ControlPlaneOperationDescriptor>;