@stigmer/cli 3.0.8

package/src/resources/apply/declarative.ts

@@ -0,0 +1,474 @@
+// Declarative apply (`stigmer apply` inside a stigmer.yaml project directory).
+//
+// The project is a lightweight membership tracker: it stores only references
+// (org/kind/slug) to its members and the server reconciles by set-difference
+// against the previous member list. The CLI's job is to discover the resources
+// that live beside stigmer.yaml, apply each one, collect references to the
+// member-eligible ones, then apply the project with that member set. Pruning of
+// orphans is therefore entirely server-side — see the note on `--prune` in
+// commands/apply.ts (S1).
+//
+// Two project layouts are supported, mirroring the Go CLI:
+//   flat:      project/agent.yaml, project/my-skill/SKILL.md
+//   organized: project/agents/*.yaml, project/skills/my-skill/SKILL.md
+// Scanning is top-level plus one level of subdirectories — deep trees are not
+// walked, matching Go (this keeps membership predictable and fast).
+
+import { existsSync, mkdtempSync, readdirSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { create, fromJson, type Message } from "@bufbuild/protobuf";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import {
+  type ApiResourceReference,
+  ApiResourceReferenceSchema,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import {
+  type ApiResourceMetadata,
+  ApiResourceMetadataSchema,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { type Project, ProjectSchema } from "@stigmer/protos/ai/stigmer/tenancy/project/v1/api_pb";
+import { ProjectCommandController } from "@stigmer/protos/ai/stigmer/tenancy/project/v1/command_pb";
+import { ProjectSpecSchema } from "@stigmer/protos/ai/stigmer/tenancy/project/v1/spec_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { UsageError } from "../../errors/index.js";
+import { CommandResult } from "../../output/index.js";
+import { loadDocuments } from "../documents.js";
+import { cloneRepository } from "../git.js";
+import { hasSkillFile, type PushResult, pushSkill, pushSkillFromClone } from "../skill.js";
+import { type ApplyItem, applyMessage, marshalItem, resolveHandlerForKind, resourceMetadata, sortApplyItems } from "./apply.js";
+import { discoverAppliedMcpServers } from "./discovery.js";
+import type { ApplyHandler, ControllerFn } from "./handlers.js";
+
+const CONFIG_FILE_NAME = "stigmer.yaml";
+const DEFAULT_MAX_DEPTH = 10;
+
+/** The detected CLI operation mode (mirrors Go's project.Track). */
+export type Track = "atomic" | "declarative" | "project";
+
+export interface DetectResult {
+  readonly track: Track;
+  /** Absolute path to stigmer.yaml; undefined for the atomic track. */
+  readonly configPath?: string;
+  /** Directory containing stigmer.yaml; undefined for the atomic track. */
+  readonly configDir?: string;
+  /** Parsed Project; undefined for the atomic track. */
+  readonly project?: Project;
+}
+
+/**
+ * Walk up from `startDir` (max 10 levels, matching Go) looking for stigmer.yaml.
+ * Absent → atomic track. Present-but-invalid → a hard error (the user clearly
+ * intended a project; help them fix it rather than silently falling back).
+ * Present with an entry_point → the SDK "project" track (synthesis), which this
+ * wave does not implement.
+ */
+export function detectTrack(startDir: string, maxDepth = DEFAULT_MAX_DEPTH): DetectResult {
+  let dir = resolve(startDir);
+  for (let depth = 0; depth < maxDepth; depth++) {
+    const candidate = join(dir, CONFIG_FILE_NAME);
+    if (existsSync(candidate) && statSync(candidate).isFile()) {
+      const project = loadProject(candidate);
+      const track: Track = project.spec?.entryPoint ? "project" : "declarative";
+      return { track, configPath: candidate, configDir: dirname(candidate), project };
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return { track: "atomic" };
+}
+
+// Strict parse of stigmer.yaml into a Project (proto carries apiVersion/kind as
+// real fields, so the discriminator is accepted, not rejected). Unknown fields
+// are an error — a typo in stigmer.yaml should fail loudly.
+function loadProject(configPath: string): Project {
+  const docs = loadDocuments(configPath, { strict: true });
+  if (docs.length === 0) throw new UsageError(`${configPath} contains no document`);
+  const doc = docs[0];
+  if (doc.kind !== "Project") {
+    throw new UsageError(`${configPath} must declare 'kind: Project' (found '${doc.kind}')`);
+  }
+  try {
+    return fromJson(ProjectSchema, doc.document, { ignoreUnknownFields: false });
+  } catch (err) {
+    throw new UsageError(
+      `invalid project configuration in ${configPath}: ${(err as Error).message}\n\n` +
+        "Fix the issues above or remove the file to use file mode (stigmer apply -f).",
+    );
+  }
+}
+
+// =============================================================================
+// Directory scanning
+// =============================================================================
+
+/**
+ * YAML resource files beside stigmer.yaml: top-level files plus files in
+ * immediate subdirectories. stigmer.yaml itself is excluded, as are skill
+ * directories (handled separately) and grouping dirs that hold skills.
+ */
+export function scanResourceFiles(projectDir: string): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(projectDir, { withFileTypes: true })) {
+    const full = join(projectDir, entry.name);
+    if (entry.isDirectory()) {
+      if (isSkillDirectory(full) || containsSkillDirectories(full)) continue;
+      for (const sub of readdirSync(full, { withFileTypes: true })) {
+        if (!sub.isDirectory() && isYaml(sub.name)) files.push(join(full, sub.name));
+      }
+      continue;
+    }
+    if (isYaml(entry.name) && entry.name.toLowerCase() !== CONFIG_FILE_NAME) {
+      files.push(full);
+    }
+  }
+  return files.sort();
+}
+
+/**
+ * Skill directories beside stigmer.yaml: immediate children that contain a
+ * SKILL.md (flat layout), plus grandchildren under a grouping dir like skills/
+ * (organized layout). Scanning stops one level deep, matching Go.
+ */
+export function scanSkillDirectories(projectDir: string): string[] {
+  const skillDirs: string[] = [];
+  for (const entry of readdirSync(projectDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const full = join(projectDir, entry.name);
+    if (isSkillDirectory(full)) {
+      skillDirs.push(full);
+      continue;
+    }
+    for (const sub of readdirSync(full, { withFileTypes: true })) {
+      const nested = join(full, sub.name);
+      if (sub.isDirectory() && isSkillDirectory(nested)) skillDirs.push(nested);
+    }
+  }
+  return skillDirs.sort();
+}
+
+function containsSkillDirectories(dir: string): boolean {
+  try {
+    return readdirSync(dir, { withFileTypes: true }).some((e) => e.isDirectory() && isSkillDirectory(join(dir, e.name)));
+  } catch {
+    return false;
+  }
+}
+
+function isSkillDirectory(dir: string): boolean {
+  return hasSkillFile(dir);
+}
+
+function isYaml(name: string): boolean {
+  const ext = extname(name).toLowerCase();
+  return ext === ".yaml" || ext === ".yml";
+}
+
+// =============================================================================
+// Item building
+// =============================================================================
+
+/**
+ * Build ordered apply items from scanned resource files. Project documents are
+ * skipped (stigmer.yaml is already loaded) and Organization documents are
+ * skipped with a warning — an organization sits above a project in the resource
+ * hierarchy and must be applied independently with file mode.
+ */
+export function buildDeclarativeItems(files: readonly string[], warn: (line: string) => void): ApplyItem[] {
+  const items: ApplyItem[] = [];
+  for (const file of files) {
+    for (const doc of loadDocuments(file, { strict: true })) {
+      if (doc.kind === "Project") continue;
+      if (doc.kind === "Organization") {
+        warn(`Skipping ${file}: Organization is not a project resource. Use 'stigmer apply -f' to manage organizations.`);
+        continue;
+      }
+      items.push({ filePath: file, handler: resolveHandlerForKind(doc.kind, file), document: doc.document });
+    }
+  }
+  return sortApplyItems(items);
+}
+
+// Member-eligible kinds participate in project membership and reconciliation.
+// Mirrors Go's types.IsProjectMemberKind.
+const MEMBER_KINDS: ReadonlySet<ApiResourceKind> = new Set([
+  ApiResourceKind.agent,
+  ApiResourceKind.workflow,
+  ApiResourceKind.mcp_server,
+  ApiResourceKind.skill,
+]);
+
+// =============================================================================
+// Orchestration
+// =============================================================================
+
+export interface DeclarativeDeps {
+  /** Raw command-controller accessor (full-proto apply, preserves metadata.id). */
+  readonly controller: ControllerFn;
+  /** High-level client for skill push + post-apply MCP discovery. */
+  readonly stigmer: Stigmer;
+  /** Resolved organization (already validated non-empty by the caller). */
+  readonly org: string;
+  /** Human progress lines (stderr; not a parity surface). */
+  readonly info: (line: string) => void;
+  /** Warnings (stderr). */
+  readonly warn: (line: string) => void;
+}
+
+/**
+ * Apply a declarative project: scan the directory for YAML resources and skill
+ * directories, marshal each resource, then hand everything to the shared
+ * reconciler. This adapter's only job is "filesystem → resources + skill
+ * sources"; the synthesis track has its own adapter ("SDK → resources + skill
+ * sources") and both converge on {@link reconcileProjectMembers} (DD-009 §6).
+ */
+export async function applyDeclarative(detect: DetectResult, deps: DeclarativeDeps): Promise<CommandResult> {
+  const { project, configDir } = detect;
+  if (project === undefined || configDir === undefined) {
+    throw new UsageError("declarative apply requires a stigmer.yaml project");
+  }
+
+  const resourceFiles = scanResourceFiles(configDir);
+  const skillDirs = scanSkillDirectories(configDir);
+  if (resourceFiles.length === 0 && skillDirs.length === 0) {
+    return buildNoResourcesResult(configDir);
+  }
+
+  const items = buildDeclarativeItems(resourceFiles, deps.warn);
+  deps.info(`Found ${items.length} resource(s) in ${resourceFiles.length} file(s), ${skillDirs.length} skill(s)`);
+
+  const resources: ReconcileResource[] = items.map((item) => ({ handler: item.handler, message: marshalItem(item) }));
+  const skillSources: SkillSource[] = skillDirs.map((dir) => ({ kind: "local", dir, tag: "latest" }));
+
+  return reconcileProjectMembers(project, resources, skillSources, deps);
+}
+
+// =============================================================================
+// Shared reconciler (used by BOTH the declarative and the synthesis tracks)
+// =============================================================================
+
+/** A resource ready to apply: its handler plus the fully-marshalled message. */
+export interface ReconcileResource {
+  readonly handler: ApplyHandler;
+  readonly message: Message;
+}
+
+/**
+ * A skill to push as a project member. `local` is a directory beside the
+ * project (declarative) or resolved from a SkillSynth local path (synthesis);
+ * `git` is a remote repo cloned on demand (synthesis only — SkillSynth git).
+ */
+export type SkillSource =
+  | { readonly kind: "local"; readonly dir: string; readonly tag: string }
+  | {
+      readonly kind: "git";
+      readonly url: string;
+      readonly ref: string;
+      readonly subdir: string;
+      readonly tag: string;
+    };
+
+// Both tracks treat skill artifacts the same way; the default ignore policy
+// mirrors the declarative push (respect .gitignore, no extra patterns).
+const DEFAULT_IGNORE_OPTIONS = { respectGitignore: true, extraIgnore: [] as string[], extraInclude: [] as string[] };
+
+/**
+ * Reconcile a project's membership: push skills first (agents may reference
+ * them), apply each resource through the shared apply core, collect references
+ * to the member-eligible ones, run post-apply MCP discovery, then apply the
+ * project with that exact member set so the server can reconcile by
+ * set-difference (orphan pruning is server-side; see S1 in commands/apply.ts).
+ */
+export async function reconcileProjectMembers(
+  project: Project,
+  resources: readonly ReconcileResource[],
+  skillSources: readonly SkillSource[],
+  deps: DeclarativeDeps,
+): Promise<CommandResult> {
+  const members: ApiResourceReference[] = [];
+
+  // Skills first — agents may reference them.
+  for (const src of skillSources) {
+    const pushed = await pushSkillSource(deps.stigmer, src, deps.org, deps.info);
+    members.push(reference(deps.org, ApiResourceKind.skill, pushed.slug));
+  }
+
+  // Then each resource, collecting member references from the APPLIED result so
+  // membership carries the server's authoritative slug. (This is the unified
+  // policy: the declarative track used to read the pre-apply YAML slug, the Go
+  // synthesis track read the applied result — converging on the applied result
+  // is correct for both and matches what the backend actually stored.)
+  const appliedMcpServers: McpServer[] = [];
+  for (const res of resources) {
+    const outcome = await applyMessage(deps.controller, res.handler, res.message, deps.org, false);
+    if (outcome.warning !== undefined) deps.warn(outcome.warning);
+    if (outcome.appliedMcpServer !== undefined) appliedMcpServers.push(outcome.appliedMcpServer);
+    if (MEMBER_KINDS.has(res.handler.kind) && outcome.applied !== undefined) {
+      const slug = memberSlugOf(outcome.applied);
+      if (slug) members.push(reference(deps.org, res.handler.kind, slug));
+    }
+  }
+
+  await discoverAppliedMcpServers(deps.stigmer, appliedMcpServers, deps.info);
+
+  injectOrg(project, deps.org);
+  if (project.spec === undefined) project.spec = create(ProjectSpecSchema, {});
+  project.spec.members = members;
+  const created = (project.metadata?.id ?? "") === "";
+  const applied = await deps.controller(ProjectCommandController).apply(project);
+
+  return buildDeclarativeResult(applied, members, created);
+}
+
+/**
+ * Push one skill source and return the result. Local sources push directly;
+ * git sources clone to a temp dir, push from the subdir, then clean up
+ * (mirrors `commands/push.ts` --git-url and Go's `pushSkillSynth`).
+ */
+export async function pushSkillSource(
+  client: Stigmer,
+  src: SkillSource,
+  org: string,
+  info: (line: string) => void,
+): Promise<PushResult> {
+  if (src.kind === "local") {
+    info(`Pushing skill from ${basename(src.dir)}...`);
+    return pushSkill(client, src.dir, org, src.tag, "", DEFAULT_IGNORE_OPTIONS);
+  }
+
+  info(`Pushing skill from ${src.url}...`);
+  const tempDir = mkdtempSync(join(tmpdir(), "stigmer-skill-"));
+  try {
+    cloneRepository(src.url, src.ref, tempDir);
+    const skillDir = src.subdir !== "" ? join(tempDir, src.subdir) : tempDir;
+    return await pushSkillFromClone(client, skillDir, {
+      gitUrl: src.url,
+      gitRef: src.ref,
+      subdir: src.subdir,
+      org,
+      tag: src.tag,
+      message: "",
+      options: DEFAULT_IGNORE_OPTIONS,
+    });
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+// Member slug from an applied resource: prefer the server's slug, fall back to
+// the name (mirrors Go's buildResourceReference / reader name-fallback).
+function memberSlugOf(message: Message): string {
+  const meta = resourceMetadata(message);
+  return meta?.slug || meta?.name || "";
+}
+
+/** Dry-run: validate every resource without touching the backend. */
+export function previewDeclarative(detect: DetectResult, deps: Pick<DeclarativeDeps, "controller" | "warn">): {
+  results: CommandResult[];
+  summary: CommandResult;
+} {
+  const { configDir } = detect;
+  if (configDir === undefined) throw new UsageError("declarative apply requires a stigmer.yaml project");
+  const items = buildDeclarativeItems(scanResourceFiles(configDir), deps.warn);
+  const results = items.map((item) => buildDryRunPreview(item));
+  const summary = CommandResult.success(`Dry run complete: ${items.length} resource(s) validated`);
+  summary.hint("Remove --dry-run to apply resources to the backend");
+  return { results, summary };
+}
+
+function buildDryRunPreview(item: ApplyItem): CommandResult {
+  const meta = metaOf(item);
+  const result = CommandResult.success(`Dry run: ${meta?.name ?? item.handler.displayName} is valid`);
+  const section = result.addSection(`${item.handler.displayName} Preview`);
+  if (meta?.name) section.field("Name", meta.name);
+  if (meta?.slug) section.field("Slug", meta.slug);
+  return result;
+}
+
+// The document is YAML-shaped JSON; read metadata fields for membership/preview
+// without marshalling (the apply itself marshals strictly).
+function metaOf(item: ApplyItem): { name?: string; slug?: string } | undefined {
+  const meta = (item.document as { metadata?: { name?: unknown; slug?: unknown } }).metadata;
+  if (meta === undefined) return undefined;
+  return {
+    name: typeof meta.name === "string" ? meta.name : undefined,
+    slug: typeof meta.slug === "string" ? meta.slug : undefined,
+  };
+}
+
+function reference(org: string, kind: ApiResourceKind, slug: string): ApiResourceReference {
+  return create(ApiResourceReferenceSchema, { org, kind, slug });
+}
+
+function injectOrg(project: Project, org: string): void {
+  if (org === "") return;
+  const holder = project as unknown as { metadata?: ApiResourceMetadata };
+  if (holder.metadata === undefined) {
+    holder.metadata = create(ApiResourceMetadataSchema, { org });
+  } else if (holder.metadata.org === "") {
+    holder.metadata.org = org;
+  }
+}
+
+// =============================================================================
+// Result builders
+// =============================================================================
+
+function buildNoResourcesResult(projectDir: string): CommandResult {
+  const result = CommandResult.warning("No resource files found in project directory");
+  result
+    .addSection("")
+    .field("Directory", projectDir)
+    .item(
+      "Add YAML resource files (Agent, Workflow, McpServer) or skill directories (with SKILL.md) next to stigmer.yaml",
+    );
+  result.hint("Example: create agent.yaml with kind: Agent, then run 'stigmer apply'");
+  return result;
+}
+
+function buildDeclarativeResult(
+  project: Project,
+  members: readonly ApiResourceReference[],
+  created: boolean,
+): CommandResult {
+  const name = project.metadata?.name ?? "project";
+  const result = CommandResult.success(`Project ${name} successfully (${created ? "created" : "updated"})`);
+
+  const section = result.addSection("Project");
+  if (project.metadata?.name) section.field("Name", project.metadata.name);
+  if (project.metadata?.slug) section.field("Slug", project.metadata.slug);
+  if (project.metadata?.id) section.field("ID", project.metadata.id);
+
+  const counts = countByKind(members);
+  if (counts.size > 0) {
+    const memberSection = result.addSection("Members Applied");
+    for (const kind of [
+      ApiResourceKind.agent,
+      ApiResourceKind.workflow,
+      ApiResourceKind.mcp_server,
+      ApiResourceKind.skill,
+    ]) {
+      const count = counts.get(kind);
+      if (count !== undefined) memberSection.field(ApiResourceKind[kind], String(count));
+    }
+  }
+
+  const recon = project.status?.lastReconciliation;
+  if (recon !== undefined && (recon.created.length > 0 || recon.updated.length > 0 || recon.deleted.length > 0)) {
+    const reconSection = result.addSection("Reconciliation");
+    if (recon.created.length > 0) reconSection.field("Created", String(recon.created.length));
+    if (recon.updated.length > 0) reconSection.field("Updated", String(recon.updated.length));
+    if (recon.deleted.length > 0) reconSection.field("Pruned", String(recon.deleted.length));
+  }
+
+  if (project.metadata?.slug) result.hint(`View project: stigmer get project ${project.metadata.slug}`);
+  return result;
+}
+
+function countByKind(members: readonly ApiResourceReference[]): Map<ApiResourceKind, number> {
+  const counts = new Map<ApiResourceKind, number>();
+  for (const member of members) counts.set(member.kind, (counts.get(member.kind) ?? 0) + 1);
+  return counts;
+}

package/src/resources/apply/discovery.ts

@@ -0,0 +1,60 @@
+// Post-apply MCP capability discovery.
+//
+// After a file apply, each newly-applied stdio MCP server is connected so its
+// tools become available immediately (no daemon restart). This is best-effort:
+// HTTP servers are skipped (the backend discovers those lazily), servers with
+// unset secret env vars are skipped with a hint, and connect failures warn
+// rather than fail the apply. Mirrors Go's discoverAppliedMcpServers + ConnectOne.
+
+import { create } from "@bufbuild/protobuf";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { ConnectInputSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { buildRuntimeEnv } from "../mcp/runtime-env.js";
+
+/** A sink for human progress/warning lines (discovery output is not parity). */
+export type DiscoverySink = (line: string) => void;
+
+/** Connect each applied stdio MCP server to trigger capability discovery. */
+export async function discoverAppliedMcpServers(
+  client: Stigmer,
+  servers: readonly McpServer[],
+  sink?: DiscoverySink,
+): Promise<void> {
+  if (servers.length === 0) return;
+  sink?.(`Discovering capabilities for ${servers.length} applied MCP server(s)...`);
+
+  for (const server of servers) {
+    const name = server.metadata?.name ?? "(unnamed)";
+
+    // Only stdio servers are auto-connected here; HTTP servers are skipped.
+    if (server.spec?.serverType?.case !== "stdio") continue;
+
+    const missing = missingSecretEnvVars(server);
+    if (missing.length > 0) {
+      sink?.(`Skipping discovery for ${name}: missing secret env var(s): ${missing.join(", ")}`);
+      continue;
+    }
+
+    try {
+      await client.mcpServer.connect(
+        create(ConnectInputSchema, {
+          mcpServerId: server.metadata?.id ?? "",
+          runtimeEnv: buildRuntimeEnv(server),
+        }),
+      );
+      sink?.(`Discovered capabilities for ${name}`);
+    } catch (err) {
+      sink?.(`Discovery failed for ${name}: ${(err as Error).message}`);
+    }
+  }
+}
+
+function missingSecretEnvVars(server: McpServer): string[] {
+  const env = server.spec?.env ?? {};
+  const missing: string[] = [];
+  for (const [name, decl] of Object.entries(env)) {
+    if (decl.isSecret && (process.env[name] ?? "") === "") missing.push(name);
+  }
+  return missing;
+}

package/src/resources/apply/handlers.ts

@@ -0,0 +1,145 @@
+// Explicit apply-handler registry for `apply -f` (file mode).
+//
+// Each handler binds an ApiResourceKind to its proto schema (for strict
+// YAML→proto marshalling) and the raw command-controller `apply` RPC. We drive
+// the *generated controllers* directly — not the high-level SDK `apply(input)`
+// methods — because the SDK's `*Input` wrappers are lossy (they drop
+// `metadata.id`, so an update would be misrouted as a create). The `apply` RPC
+// takes the full resource message, preserving every field round-tripped from
+// YAML. This is the keystone decision for Wave 2e.
+//
+// Registration is explicit (no init magic), mirroring Go's
+// newApplyHandlerRegistry — to add a kind, add a line here.
+
+import type { Client } from "@connectrpc/connect";
+import type { DescMessage, DescService, Message } from "@bufbuild/protobuf";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { type Agent, AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
+import { type AgentInstance, AgentInstanceSchema } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+import { AgentInstanceCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/command_pb";
+import { type Environment, EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { EnvironmentCommandController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/command_pb";
+import { type McpServer, McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
+import { type Session, SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { SessionCommandController } from "@stigmer/protos/ai/stigmer/agentic/session/v1/command_pb";
+import { type Workflow, WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/command_pb";
+import {
+  type WorkflowInstance,
+  WorkflowInstanceSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
+import { WorkflowInstanceCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/command_pb";
+import { type IdentityProvider, IdentityProviderSchema } from "@stigmer/protos/ai/stigmer/iam/identityprovider/v1/api_pb";
+import { IdentityProviderCommandController } from "@stigmer/protos/ai/stigmer/iam/identityprovider/v1/command_pb";
+import { type OAuthApp, OAuthAppSchema } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/api_pb";
+import { OAuthAppCommandController } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/command_pb";
+import { type Organization, OrganizationSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
+import { OrganizationCommandController } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/command_pb";
+
+/** Accessor for a raw Connect client over a generated service controller. */
+export type ControllerFn = <Desc extends DescService>(service: Desc) => Client<Desc>;
+
+export interface ApplyHandler {
+  readonly kind: ApiResourceKind;
+  readonly displayName: string;
+  /** Proto schema for strict YAML→proto marshalling. */
+  readonly schema: DescMessage;
+  /** Drive the controller's `apply` RPC with the full resource message. */
+  apply(controller: ControllerFn, message: Message): Promise<Message>;
+}
+
+export const APPLY_HANDLERS: ReadonlyMap<ApiResourceKind, ApplyHandler> = new Map<ApiResourceKind, ApplyHandler>([
+  [
+    ApiResourceKind.organization,
+    {
+      kind: ApiResourceKind.organization,
+      displayName: "Organization",
+      schema: OrganizationSchema,
+      apply: (c, m) => c(OrganizationCommandController).apply(m as Organization),
+    },
+  ],
+  [
+    ApiResourceKind.mcp_server,
+    {
+      kind: ApiResourceKind.mcp_server,
+      displayName: "MCP Server",
+      schema: McpServerSchema,
+      apply: (c, m) => c(McpServerCommandController).apply(m as McpServer),
+    },
+  ],
+  [
+    ApiResourceKind.agent,
+    {
+      kind: ApiResourceKind.agent,
+      displayName: "Agent",
+      schema: AgentSchema,
+      apply: (c, m) => c(AgentCommandController).apply(m as Agent),
+    },
+  ],
+  [
+    ApiResourceKind.workflow,
+    {
+      kind: ApiResourceKind.workflow,
+      displayName: "Workflow",
+      schema: WorkflowSchema,
+      apply: (c, m) => c(WorkflowCommandController).apply(m as Workflow),
+    },
+  ],
+  [
+    ApiResourceKind.environment,
+    {
+      kind: ApiResourceKind.environment,
+      displayName: "Environment",
+      schema: EnvironmentSchema,
+      apply: (c, m) => c(EnvironmentCommandController).apply(m as Environment),
+    },
+  ],
+  [
+    ApiResourceKind.identity_provider,
+    {
+      kind: ApiResourceKind.identity_provider,
+      displayName: "Identity Provider",
+      schema: IdentityProviderSchema,
+      apply: (c, m) => c(IdentityProviderCommandController).apply(m as IdentityProvider),
+    },
+  ],
+  [
+    ApiResourceKind.oauth_app,
+    {
+      kind: ApiResourceKind.oauth_app,
+      displayName: "OAuth App",
+      schema: OAuthAppSchema,
+      apply: (c, m) => c(OAuthAppCommandController).apply(m as OAuthApp),
+    },
+  ],
+  [
+    ApiResourceKind.agent_instance,
+    {
+      kind: ApiResourceKind.agent_instance,
+      displayName: "Agent Instance",
+      schema: AgentInstanceSchema,
+      apply: (c, m) => c(AgentInstanceCommandController).apply(m as AgentInstance),
+    },
+  ],
+  [
+    ApiResourceKind.workflow_instance,
+    {
+      kind: ApiResourceKind.workflow_instance,
+      displayName: "Workflow Instance",
+      schema: WorkflowInstanceSchema,
+      apply: (c, m) => c(WorkflowInstanceCommandController).apply(m as WorkflowInstance),
+    },
+  ],
+  [
+    ApiResourceKind.session,
+    {
+      kind: ApiResourceKind.session,
+      displayName: "Session",
+      schema: SessionSchema,
+      apply: (c, m) => c(SessionCommandController).apply(m as Session),
+    },
+  ],
+]);