@stigmer/cli 3.0.8

package/src/registry/registry.ts

@@ -0,0 +1,101 @@
+// The type registry: the single source of truth that maps user-facing resource
+// identifiers (aliases, YAML kinds) to proto kinds and their supported verbs.
+// Built once from the declarative kind-metadata table with aliases derived
+// algorithmically — a structural mirror of Go's types.Registry.
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { generateAliases, normalizeAlias } from "./aliases.js";
+import { CLI_RELEVANT_KINDS, KIND_META } from "./metadata.js";
+import { Verb } from "./verbs.js";
+import { verbsForKind } from "./verb-support.js";
+
+/** CLI metadata for a single resource type. */
+export interface TypeInfo {
+  /** Proto enum value this type maps to. */
+  readonly kind: ApiResourceKind;
+  /** Kind name (also the YAML `kind` value), e.g. "McpServer". */
+  readonly name: string;
+  /** Human-readable name, e.g. "MCP Server". */
+  readonly displayName: string;
+  /** ID prefix, e.g. "mcp". */
+  readonly idPrefix: string;
+  /** Canonical singular form (lowercase name), e.g. "mcpserver". */
+  readonly singular: string;
+  /** Plural form for list commands, e.g. "mcpservers". */
+  readonly plural: string;
+  /** All accepted input spellings (case-insensitive on lookup). */
+  readonly aliases: readonly string[];
+  /** Verbs this type supports. */
+  readonly supportedVerbs: ReadonlySet<Verb>;
+}
+
+export function supportsVerb(info: TypeInfo, verb: Verb): boolean {
+  return info.supportedVerbs.has(verb);
+}
+
+export interface Registry {
+  /** Look up a type by its proto kind. */
+  getByKind(kind: ApiResourceKind): TypeInfo | undefined;
+  /** Look up a type by any alias (case-insensitive). */
+  getByAlias(input: string): TypeInfo | undefined;
+  /** Look up a type by its exact YAML kind string. */
+  getByYamlKind(yamlKind: string): TypeInfo | undefined;
+  /** All registered CLI-relevant types, in declaration order. */
+  all(): readonly TypeInfo[];
+  /** Whether a kind supports a verb. */
+  supportsVerb(kind: ApiResourceKind, verb: Verb): boolean;
+  /** All types supporting a given verb, in declaration order. */
+  typesForVerb(verb: Verb): readonly TypeInfo[];
+}
+
+function buildTypeInfo(kind: ApiResourceKind): TypeInfo | undefined {
+  const meta = KIND_META.get(kind);
+  if (meta === undefined) return undefined;
+
+  const singular = meta.name.toLowerCase();
+  return {
+    kind,
+    name: meta.name,
+    displayName: meta.displayName,
+    idPrefix: meta.idPrefix,
+    singular,
+    plural: singular.endsWith("s") ? singular : `${singular}s`,
+    aliases: generateAliases(meta.name, meta.displayName, meta.idPrefix),
+    supportedVerbs: verbsForKind(kind),
+  };
+}
+
+function buildRegistry(): Registry {
+  const byKind = new Map<ApiResourceKind, TypeInfo>();
+  const byAlias = new Map<string, TypeInfo>();
+  const byYamlKind = new Map<string, TypeInfo>();
+  const all: TypeInfo[] = [];
+
+  for (const kind of CLI_RELEVANT_KINDS) {
+    const info = buildTypeInfo(kind);
+    if (info === undefined) continue;
+    byKind.set(kind, info);
+    byYamlKind.set(info.name, info);
+    all.push(info);
+    for (const alias of info.aliases) {
+      byAlias.set(normalizeAlias(alias), info);
+    }
+  }
+
+  return {
+    getByKind: (kind) => byKind.get(kind),
+    getByAlias: (input) => byAlias.get(normalizeAlias(input)),
+    getByYamlKind: (yamlKind) => byYamlKind.get(yamlKind),
+    all: () => all,
+    supportsVerb: (kind, verb) => byKind.get(kind)?.supportedVerbs.has(verb) ?? false,
+    typesForVerb: (verb) => all.filter((info) => info.supportedVerbs.has(verb)),
+  };
+}
+
+let cached: Registry | undefined;
+
+/** The process-wide registry singleton, built lazily on first use. */
+export function defaultRegistry(): Registry {
+  if (cached === undefined) cached = buildRegistry();
+  return cached;
+}

package/src/registry/verb-support.ts

@@ -0,0 +1,50 @@
+// Verb-support matrix — which verbs each resource kind supports.
+//
+// This is CLI-specific policy (not stored in proto), ported verbatim from Go's
+// types.verbSupport so both CLIs expose the same surface. Keep in lockstep.
+//
+//   | Kind         | apply | validate | get | list | delete | run | push | search | download |
+//   |--------------|-------|----------|-----|------|--------|-----|------|--------|----------|
+//   | Organization | Y     | -        | Y   | Y    | Y      | -   | -    | -      | -        |
+//   | Agent        | Y     | Y        | Y   | Y    | Y      | Y   | -    | Y      | -        |
+//   | Workflow     | Y     | Y        | Y   | Y    | Y      | Y   | -    | Y      | -        |
+//   | Skill        | -     | -        | Y   | Y    | Y      | -   | Y    | -      | -        |
+//   | McpServer    | Y     | Y        | Y   | Y    | Y      | -   | -    | -      | -        |
+//   | Project      | Y*    | Y        | Y   | Y    | Y      | -   | -    | -      | -        |
+//   | Execution    | -     | -        | Y   | Y    | Y**    | -   | -    | -      | Y        |
+//
+//   *  Project "apply" triggers SDK synthesis mode.
+//   ** Execution "delete" maps to a cancel operation.
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { Verb } from "./verbs.js";
+
+export const VERB_SUPPORT: ReadonlyMap<ApiResourceKind, ReadonlySet<Verb>> = new Map([
+  [ApiResourceKind.organization, new Set<Verb>([Verb.Apply, Verb.Get, Verb.List, Verb.Delete])],
+  [
+    ApiResourceKind.agent,
+    new Set<Verb>([Verb.Apply, Verb.Validate, Verb.Get, Verb.List, Verb.Delete, Verb.Run, Verb.Search]),
+  ],
+  [
+    ApiResourceKind.workflow,
+    new Set<Verb>([Verb.Apply, Verb.Validate, Verb.Get, Verb.List, Verb.Delete, Verb.Run, Verb.Search]),
+  ],
+  [ApiResourceKind.skill, new Set<Verb>([Verb.Get, Verb.List, Verb.Delete, Verb.Push])],
+  [ApiResourceKind.mcp_server, new Set<Verb>([Verb.Apply, Verb.Validate, Verb.Get, Verb.List, Verb.Delete])],
+  [ApiResourceKind.project, new Set<Verb>([Verb.Apply, Verb.Validate, Verb.Get, Verb.List, Verb.Delete])],
+  [ApiResourceKind.api_key, new Set<Verb>([Verb.Get, Verb.List, Verb.Delete])],
+  // agent_execution is special — uses dedicated AgentExecutionQueryController
+  // RPCs, not the unified SearchService. delete maps to cancel.
+  [ApiResourceKind.agent_execution, new Set<Verb>([Verb.Get, Verb.List, Verb.Delete, Verb.Download])],
+  [ApiResourceKind.identity_provider, new Set<Verb>([Verb.Apply, Verb.Get, Verb.List, Verb.Delete])],
+  [ApiResourceKind.oauth_app, new Set<Verb>([Verb.Apply, Verb.Get, Verb.List, Verb.Delete])],
+  [ApiResourceKind.environment, new Set<Verb>([Verb.Apply, Verb.Get, Verb.List, Verb.Delete])],
+  [ApiResourceKind.agent_instance, new Set<Verb>([Verb.Apply, Verb.Get, Verb.List, Verb.Delete])],
+  // No list: proto exposes getByWorkflow (requires workflow_id), not a generic list.
+  [ApiResourceKind.workflow_instance, new Set<Verb>([Verb.Apply, Verb.Get, Verb.Delete])],
+  [ApiResourceKind.session, new Set<Verb>([Verb.Apply, Verb.Get, Verb.List, Verb.Delete])],
+]);
+
+export function verbsForKind(kind: ApiResourceKind): ReadonlySet<Verb> {
+  return VERB_SUPPORT.get(kind) ?? new Set<Verb>();
+}

package/src/registry/verbs.ts

@@ -0,0 +1,43 @@
+// CLI verbs — operations that can be performed on a resource.
+// Mirrors the Go types.Verb set so the two CLIs stay behaviorally identical.
+
+export const Verb = {
+  Apply: "apply",
+  Validate: "validate",
+  Get: "get",
+  List: "list",
+  Delete: "delete",
+  Run: "run",
+  Push: "push",
+  Search: "search",
+  Download: "download",
+} as const;
+
+export type Verb = (typeof Verb)[keyof typeof Verb];
+
+// Declaration order is the canonical display order (help text, parity tables).
+export const ALL_VERBS: readonly Verb[] = [
+  Verb.Apply,
+  Verb.Validate,
+  Verb.Get,
+  Verb.List,
+  Verb.Delete,
+  Verb.Run,
+  Verb.Push,
+  Verb.Search,
+  Verb.Download,
+];
+
+export function isFileBasedVerb(verb: Verb): boolean {
+  return verb === Verb.Apply || verb === Verb.Validate;
+}
+
+export function isReferenceBasedVerb(verb: Verb): boolean {
+  return (
+    verb === Verb.Get ||
+    verb === Verb.Delete ||
+    verb === Verb.Run ||
+    verb === Verb.Search ||
+    verb === Verb.Download
+  );
+}

package/src/resources/apply/apply.integration.test.ts

@@ -0,0 +1,207 @@
+// In-process integration test for file-mode apply.
+//
+// The keystone assertion (the reason this wave drives the raw command
+// controllers instead of the high-level SDK `apply(input)`): a resource carrying
+// fields the SDK's lossy `*Input` would drop — notably `metadata.id`, which
+// distinguishes an update from a create — must reach the backend intact. We
+// apply an Agent YAML with an id set plus spec fields and assert the server
+// received every one. Also covers dependency ordering, org injection, dry-run,
+// and the created-vs-updated signal.
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { createServer as createHttp2Server, type Http2Server, type ServerHttp2Session } from "node:http2";
+import type { AddressInfo } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type ConnectRouter, createClient } from "@connectrpc/connect";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
+import { createNodeTransport, normalizeEndpoint } from "@stigmer/sdk/node";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { applyItem, requiresOrgContext, resolveApplyItems } from "./apply.js";
+import type { ControllerFn } from "./handlers.js";
+
+let backend: Http2Server;
+let controllerFn: ControllerFn;
+const openSessions = new Set<ServerHttp2Session>();
+
+let appliedAgents: Agent[] = [];
+let appliedMcps: McpServer[] = [];
+
+beforeEach(() => {
+  appliedAgents = [];
+  appliedMcps = [];
+});
+
+function writeYaml(dir: string, name: string, body: string): string {
+  const path = join(dir, name);
+  writeFileSync(path, body);
+  return path;
+}
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(AgentCommandController, {
+      apply: (req) => {
+        appliedAgents.push(req);
+        return req; // echo back the full proto the server received
+      },
+    });
+    router.service(McpServerCommandController, {
+      apply: (req) => {
+        appliedMcps.push(req);
+        return req;
+      },
+    });
+  };
+
+  backend = createHttp2Server(connectNodeAdapter({ routes }));
+  backend.on("session", (session) => {
+    openSessions.add(session);
+    session.on("close", () => openSessions.delete(session));
+  });
+  await new Promise<void>((resolve) => backend.listen(0, "127.0.0.1", resolve));
+  const port = (backend.address() as AddressInfo).port;
+  const transport = createNodeTransport({ baseUrl: normalizeEndpoint(`127.0.0.1:${port}`) });
+  controllerFn = (service) => createClient(service, transport);
+});
+
+afterAll(async () => {
+  for (const session of openSessions) session.destroy();
+  await new Promise<void>((resolve) => backend.close(() => resolve()));
+});
+
+const AGENT_WITH_ID = [
+  "apiVersion: agentic.stigmer.ai/v1",
+  "kind: Agent",
+  "metadata:",
+  "  id: agt_existing",
+  "  name: Reviewer",
+  "  slug: reviewer",
+  "  org: acme",
+  "spec:",
+  "  description: A code reviewer",
+  "  instructions: Review pull requests carefully",
+  "",
+].join("\n");
+
+describe("file-mode apply — fidelity (raw controller preserves full proto)", () => {
+  it("preserves metadata.id and spec fields the SDK input would drop", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "apply-it-"));
+    try {
+      writeYaml(dir, "agent.yaml", AGENT_WITH_ID);
+      const items = resolveApplyItems(dir);
+      expect(items).toHaveLength(1);
+
+      const outcome = await applyItem(controllerFn, items[0], "acme", false);
+
+      // The keystone: id (lossy in AgentInput) and spec round-trip intact.
+      expect(appliedAgents).toHaveLength(1);
+      expect(appliedAgents[0].metadata?.id).toBe("agt_existing");
+      expect(appliedAgents[0].metadata?.slug).toBe("reviewer");
+      expect(appliedAgents[0].spec?.description).toBe("A code reviewer");
+      expect(appliedAgents[0].spec?.instructions).toBe("Review pull requests carefully");
+
+      // id present → treated as an update.
+      expect(outcome.result.status).toBe("success");
+      expect(outcome.result.message).toBe("Agent updated successfully");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("treats a resource without metadata.id as a create", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "apply-it-"));
+    try {
+      writeYaml(
+        dir,
+        "agent.yaml",
+        ["kind: Agent", "metadata:", "  name: New", "  slug: new", "spec:", "  description: d", ""].join("\n"),
+      );
+      const items = resolveApplyItems(dir);
+      const outcome = await applyItem(controllerFn, items[0], "acme", false);
+      expect(outcome.result.message).toBe("Agent created successfully");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("injects the resolved org when the document omits it", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "apply-it-"));
+    try {
+      writeYaml(
+        dir,
+        "agent.yaml",
+        ["kind: Agent", "metadata:", "  name: NoOrg", "  slug: no-org", "spec:", "  description: d", ""].join("\n"),
+      );
+      const items = resolveApplyItems(dir);
+      await applyItem(controllerFn, items[0], "acme", false);
+      expect(appliedAgents[0].metadata?.org).toBe("acme");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("file-mode apply — orchestration", () => {
+  it("sorts items into dependency order (mcp_server before agent)", () => {
+    const dir = mkdtempSync(join(tmpdir(), "apply-it-"));
+    try {
+      writeYaml(dir, "agent.yaml", AGENT_WITH_ID);
+      writeYaml(
+        dir,
+        "mcp.yaml",
+        ["kind: McpServer", "metadata:", "  name: fs", "  slug: fs", "spec:", "  stdio:", "    command: node", ""].join(
+          "\n",
+        ),
+      );
+      const items = resolveApplyItems(dir);
+      expect(items.map((i) => i.handler.displayName)).toEqual(["MCP Server", "Agent"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("requiresOrgContext is false for an Organization-only set", () => {
+    const dir = mkdtempSync(join(tmpdir(), "apply-it-"));
+    try {
+      writeYaml(dir, "org.yaml", ["kind: Organization", "metadata:", "  name: Acme", "  slug: acme", ""].join("\n"));
+      const items = resolveApplyItems(dir);
+      expect(requiresOrgContext(items)).toBe(false);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("dry-run previews without touching the backend", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "apply-it-"));
+    try {
+      writeYaml(dir, "agent.yaml", AGENT_WITH_ID);
+      const items = resolveApplyItems(dir);
+      const before = appliedAgents.length;
+      const outcome = await applyItem(controllerFn, items[0], "acme", true);
+      expect(outcome.result.message).toBe("Dry run: Reviewer is valid");
+      expect(appliedAgents.length).toBe(before);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("rejects unknown YAML fields under strict marshalling", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "apply-it-"));
+    try {
+      writeYaml(
+        dir,
+        "agent.yaml",
+        ["kind: Agent", "metadata:", "  name: Bad", "spec:", "  bogus_field: nope", ""].join("\n"),
+      );
+      const items = resolveApplyItems(dir);
+      await expect(applyItem(controllerFn, items[0], "acme", false)).rejects.toThrow(/invalid Agent/);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/resources/apply/apply.ts

@@ -0,0 +1,202 @@
+// File-mode apply orchestration (`apply -f <file|dir>`).
+//
+// Pipeline per document: strict YAML→proto marshal (S-strict) → inject the
+// resolved org when absent → dry-run preview OR drive the raw command
+// controller's `apply` RPC with the full proto → build a CommandResult. Items
+// across all files are sorted into dependency order before applying so parents
+// (org → mcp_server → agent → workflow → …) land before their dependents.
+
+import { create, fromJson, type JsonValue, type Message } from "@bufbuild/protobuf";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_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 { UsageError } from "../../errors/index.js";
+import { CommandResult } from "../../output/index.js";
+import { defaultRegistry, Verb } from "../../registry/index.js";
+import { loadDocuments, resolveYamlFiles } from "../documents.js";
+import { type ApplyHandler, APPLY_HANDLERS, type ControllerFn } from "./handlers.js";
+
+export interface ApplyItem {
+  readonly filePath: string;
+  readonly handler: ApplyHandler;
+  readonly document: JsonValue;
+}
+
+export interface ApplyOutcome {
+  readonly result: CommandResult;
+  /** Set for successfully applied MCP servers, to drive post-apply discovery. */
+  readonly appliedMcpServer?: McpServer;
+  /** Optional org-mismatch warning to surface on stderr. */
+  readonly warning?: string;
+  /**
+   * The applied resource message (absent in dry-run). Carries the server's
+   * authoritative metadata (id/slug) — the reconciler reads this to register
+   * project membership, so membership matches what the backend stored.
+   */
+  readonly applied?: Message;
+}
+
+// Dependency apply order (ascending priority); kinds absent get 99 (applied
+// last). Mirrors Go's applier.DefaultApplyOrder.
+const APPLY_ORDER: ReadonlyMap<ApiResourceKind, number> = new Map([
+  [ApiResourceKind.organization, 0],
+  [ApiResourceKind.mcp_server, 1],
+  [ApiResourceKind.agent, 2],
+  [ApiResourceKind.workflow, 3],
+  [ApiResourceKind.environment, 4],
+  [ApiResourceKind.identity_provider, 5],
+  [ApiResourceKind.oauth_app, 6],
+  [ApiResourceKind.agent_instance, 7],
+  [ApiResourceKind.workflow_instance, 8],
+  [ApiResourceKind.session, 9],
+]);
+
+/** Expand a path into ordered, kind-resolved apply items (strict YAML parse). */
+export function resolveApplyItems(path: string): ApplyItem[] {
+  const files = resolveYamlFiles(path);
+  if (files.length === 0) throw new UsageError("no YAML files found");
+
+  const items: ApplyItem[] = [];
+  for (const file of files) {
+    for (const doc of loadDocuments(file, { strict: true })) {
+      items.push({ filePath: file, handler: resolveHandlerForKind(doc.kind, file), document: doc.document });
+    }
+  }
+  if (items.length === 0) throw new UsageError("no valid resources found in files");
+  return sortApplyItems(items);
+}
+
+/**
+ * Resolve a YAML `kind` to its apply handler, enforcing the verb-support gate.
+ * Shared by file mode and declarative mode so the lookup + error wording lives
+ * in exactly one place. `where` is woven into errors for a precise location.
+ */
+export function resolveHandlerForKind(kind: string, where: string): ApplyHandler {
+  const info = defaultRegistry().getByYamlKind(kind);
+  if (info === undefined) throw new UsageError(`unknown resource kind '${kind}' in ${where}`);
+  if (!info.supportedVerbs.has(Verb.Apply)) throw new UsageError(`${info.displayName} does not support 'apply'`);
+  const handler = APPLY_HANDLERS.get(info.kind);
+  if (handler === undefined) throw new UsageError(`apply not implemented for ${info.displayName}`);
+  return handler;
+}
+
+/** Stable sort by dependency priority (Array.prototype.sort is stable in V8). */
+export function sortApplyItems(items: ApplyItem[]): ApplyItem[] {
+  items.sort((a, b) => priorityOf(a.handler.kind) - priorityOf(b.handler.kind));
+  return items;
+}
+
+/** True when any item needs org context (everything except Organization). */
+export function requiresOrgContext(items: readonly ApplyItem[]): boolean {
+  return items.some((item) => item.handler.kind !== ApiResourceKind.organization);
+}
+
+/** Apply a single YAML item: strict-marshal to a proto, then apply the message. */
+export async function applyItem(
+  controller: ControllerFn,
+  item: ApplyItem,
+  org: string,
+  dryRun: boolean,
+): Promise<ApplyOutcome> {
+  return applyMessage(controller, item.handler, marshalItem(item), org, dryRun);
+}
+
+/**
+ * Strict YAML→proto marshal for one item, with a precise location in the error.
+ * Split out from {@link applyItem} so the declarative reconciler can marshal
+ * without immediately applying (it batches messages, then reconciles).
+ */
+export function marshalItem(item: ApplyItem): Message {
+  try {
+    return fromJson(item.handler.schema, item.document, { ignoreUnknownFields: false });
+  } catch (err) {
+    throw new UsageError(`invalid ${item.handler.displayName} in ${item.filePath}: ${(err as Error).message}`);
+  }
+}
+
+/**
+ * Apply a fully-marshalled resource message: inject org, then dry-run preview or
+ * drive the controller's `apply` RPC. This is the single apply core shared by
+ * both tracks — the declarative/file track feeds messages marshalled from YAML
+ * (`marshalItem`), the synthesis track feeds messages decoded from `.pb`
+ * (`fromBinary`). One core means one place where org injection, create/update
+ * detection, and result shaping live (DD-009 §6).
+ */
+export async function applyMessage(
+  controller: ControllerFn,
+  handler: ApplyHandler,
+  message: Message,
+  org: string,
+  dryRun: boolean,
+): Promise<ApplyOutcome> {
+  const warning = injectOrg(message, org);
+  const created = (metaOf(message)?.id ?? "") === "";
+
+  if (dryRun) {
+    return { result: buildDryRunResult(handler, message), warning };
+  }
+
+  const applied = await handler.apply(controller, message);
+  const result = buildApplyResult(handler, applied, created);
+  if (handler.kind === ApiResourceKind.mcp_server) {
+    return { result, appliedMcpServer: applied as McpServer, warning, applied };
+  }
+  return { result, warning, applied };
+}
+
+/** Read a resource message's metadata (id/name/slug/org), if present. */
+export function resourceMetadata(message: Message): ApiResourceMetadata | undefined {
+  return metaOf(message);
+}
+
+function metaOf(message: Message): ApiResourceMetadata | undefined {
+  return (message as unknown as { metadata?: ApiResourceMetadata }).metadata;
+}
+
+// Inject the resolved org into metadata.org when the document omitted it. When
+// the document specifies a *different* org, return a warning (Go warns but
+// honors the document's value — we do the same).
+function injectOrg(message: Message, org: string): string | undefined {
+  if (org === "") return undefined;
+  const holder = message as unknown as { metadata?: ApiResourceMetadata };
+  if (holder.metadata === undefined) {
+    holder.metadata = create(ApiResourceMetadataSchema, { org });
+    return undefined;
+  }
+  if (holder.metadata.org === "") {
+    holder.metadata.org = org;
+    return undefined;
+  }
+  if (holder.metadata.org !== org) {
+    return `resource org '${holder.metadata.org}' differs from target org '${org}'; using '${holder.metadata.org}'`;
+  }
+  return undefined;
+}
+
+function buildApplyResult(handler: ApplyHandler, applied: Message, created: boolean): CommandResult {
+  const meta = metaOf(applied);
+  const result = CommandResult.success(`${handler.displayName} ${created ? "created" : "updated"} successfully`);
+  const section = result.addSection("Resource Details");
+  if (meta?.id) section.field("ID", meta.id);
+  if (meta?.name) section.field("Name", meta.name);
+  if (meta?.slug) section.field("Slug", meta.slug);
+  return result;
+}
+
+function buildDryRunResult(handler: ApplyHandler, message: Message): CommandResult {
+  const meta = metaOf(message);
+  const name = meta?.name ?? handler.displayName;
+  const result = CommandResult.success(`Dry run: ${name} is valid`);
+  const section = result.addSection(`${handler.displayName} Preview`);
+  if (meta?.name) section.field("Name", meta.name);
+  if (meta?.slug) section.field("Slug", meta.slug);
+  if (meta?.org) section.field("Org", meta.org);
+  return result;
+}
+
+function priorityOf(kind: ApiResourceKind): number {
+  return APPLY_ORDER.get(kind) ?? 99;
+}