@stigmer/react 0.0.36 → 0.0.40

package/src/library/parse-resource-yaml.ts

@@ -0,0 +1,611 @@
+import { parse as parseYaml } from "yaml";
+import type {
+  AgentInput,
+  McpServerInput,
+  McpServerUsageInput,
+  ToolApprovalOverrideInput,
+  SubAgentInput,
+  McpAccessInput,
+  StdioServerConfigInput,
+  HttpServerConfigInput,
+  ToolApprovalPolicyInput,
+  EnvSpecInput,
+  EnvVarInput,
+  ResourceRef,
+} from "@stigmer/sdk";
+import type { StigmerResourceKind } from "./detect-stigmer-resource";
+
+/**
+ * Result of parsing a Stigmer resource YAML into an SDK input type.
+ *
+ * Discriminated on `kind` so consumers can narrow to the specific input:
+ *
+ * ```ts
+ * const parsed = parseResourceYaml(content, "my-org");
+ * if (parsed.kind === "Agent") {
+ *   // parsed.input is AgentInput
+ * }
+ * ```
+ */
+export type ParsedResource =
+  | { readonly kind: "Agent"; readonly input: AgentInput }
+  | { readonly kind: "McpServer"; readonly input: McpServerInput };
+
+/**
+ * Parses a Stigmer resource YAML string into the corresponding SDK input
+ * type for use with `stigmer.agent.apply()` or `stigmer.mcpServer.apply()`.
+ *
+ * Handles the conversion from proto-style snake_case YAML field names to
+ * the camelCase TypeScript SDK input types, including nested structures
+ * like `mcp_server_usages`, `sub_agents`, and `env_spec`.
+ *
+ * The `org` parameter **always overrides** `metadata.org` in the YAML.
+ * This matches the UX intent of "Apply to [my-org]" — the user explicitly
+ * chooses the target organization.
+ *
+ * **Throws** with descriptive, user-facing error messages when the YAML
+ * is malformed or missing required fields. These messages are designed
+ * for display in error UI components.
+ *
+ * @param content - Raw YAML content string (typically from {@link useArtifactContent}).
+ * @param org - Target organization slug. Overrides `metadata.org` in the YAML.
+ * @returns A discriminated union with the parsed SDK input.
+ * @throws {Error} When the content is not valid YAML, not a recognized
+ *   Stigmer resource, or is missing required fields.
+ *
+ * @example
+ * ```ts
+ * import { parseResourceYaml } from "@stigmer/react";
+ *
+ * const parsed = parseResourceYaml(yamlContent, "my-org");
+ * if (parsed.kind === "Agent") {
+ *   await stigmer.agent.apply(parsed.input);
+ * } else {
+ *   await stigmer.mcpServer.apply(parsed.input);
+ * }
+ * ```
+ *
+ * @see {@link useApplyResource} for the React hook that wraps this function
+ * @see {@link detectStigmerResource} for lightweight detection without full parsing
+ */
+export function parseResourceYaml(
+  content: string,
+  org: string,
+): ParsedResource {
+  const doc = parseYamlDocument(content);
+  const { kind, metadata, spec } = validateResourceStructure(doc);
+
+  const name = extractRequiredString(metadata, "name", "metadata.name");
+  const slug = extractOptionalString(metadata, "slug");
+  const labels = extractOptionalStringRecord(metadata, "labels");
+
+  switch (kind) {
+    case "Agent":
+      return {
+        kind: "Agent",
+        input: buildAgentInput(name, slug, org, labels, spec),
+      };
+    case "McpServer":
+      return {
+        kind: "McpServer",
+        input: buildMcpServerInput(name, slug, org, labels, spec),
+      };
+    default:
+      throw new Error(
+        `Unsupported resource kind: "${kind}". ` +
+          "Only Agent and McpServer can be applied from artifacts.",
+      );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// YAML parsing
+// ---------------------------------------------------------------------------
+
+function parseYamlDocument(content: string): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(content);
+  } catch {
+    throw new Error("Failed to parse artifact content as YAML.");
+  }
+
+  if (!isPlainObject(parsed)) {
+    throw new Error(
+      "Failed to parse artifact content as YAML: expected a mapping document.",
+    );
+  }
+
+  return parsed;
+}
+
+// ---------------------------------------------------------------------------
+// Structure validation
+// ---------------------------------------------------------------------------
+
+interface ValidatedStructure {
+  readonly kind: string;
+  readonly metadata: Record<string, unknown>;
+  readonly spec: Record<string, unknown>;
+}
+
+const STIGMER_API_VERSION_PATTERN = /^[a-z]+\.stigmer\.ai\/v\d+$/;
+
+const APPLICABLE_KINDS: ReadonlySet<string> = new Set<StigmerResourceKind>([
+  "Agent",
+  "McpServer",
+]);
+
+function validateResourceStructure(
+  doc: Record<string, unknown>,
+): ValidatedStructure {
+  const apiVersion = doc.apiVersion ?? doc.api_version;
+  if (
+    typeof apiVersion !== "string" ||
+    !STIGMER_API_VERSION_PATTERN.test(apiVersion)
+  ) {
+    throw new Error(
+      "Resource YAML is missing required field: apiVersion " +
+        "(expected pattern: *.stigmer.ai/v*).",
+    );
+  }
+
+  const kind = doc.kind;
+  if (typeof kind !== "string" || kind.length === 0) {
+    throw new Error("Resource YAML is missing required field: kind.");
+  }
+
+  if (!APPLICABLE_KINDS.has(kind)) {
+    throw new Error(
+      `Unsupported resource kind: "${kind}". ` +
+        "Only Agent and McpServer can be applied from artifacts.",
+    );
+  }
+
+  const metadata = doc.metadata;
+  if (!isPlainObject(metadata)) {
+    throw new Error("Resource YAML is missing required field: metadata.");
+  }
+
+  const spec = doc.spec;
+  if (!isPlainObject(spec)) {
+    throw new Error("Resource YAML is missing required field: spec.");
+  }
+
+  return { kind, metadata, spec };
+}
+
+// ---------------------------------------------------------------------------
+// Agent conversion
+// ---------------------------------------------------------------------------
+
+function buildAgentInput(
+  name: string,
+  slug: string | undefined,
+  org: string,
+  labels: Record<string, string> | undefined,
+  spec: Record<string, unknown>,
+): AgentInput {
+  return {
+    name,
+    org,
+    ...(slug !== undefined && { slug }),
+    ...(labels !== undefined && { labels }),
+    ...optionalString(spec, "description", "description"),
+    ...optionalSnakeToCamel(spec, "icon_url", "iconUrl"),
+    ...optionalString(spec, "instructions", "instructions"),
+    ...optionalField("mcpServerUsages", extractMcpServerUsages(spec)),
+    ...optionalField("skillRefs", extractResourceRefs(spec, "skill_refs")),
+    ...optionalField("subAgents", extractSubAgents(spec)),
+    ...optionalField("envSpec", extractEnvSpec(spec)),
+  };
+}
+
+function extractMcpServerUsages(
+  spec: Record<string, unknown>,
+): McpServerUsageInput[] | undefined {
+  const raw = spec.mcp_server_usages ?? spec.mcpServerUsages;
+  if (!Array.isArray(raw) || raw.length === 0) return undefined;
+
+  return raw.filter(isPlainObject).map(
+    (entry): McpServerUsageInput => {
+      const refObj = entry.mcp_server_ref ?? entry.mcpServerRef;
+      if (!isPlainObject(refObj)) {
+        throw new Error(
+          "Agent YAML: each mcp_server_usages entry must have a mcp_server_ref.",
+        );
+      }
+
+      return {
+        mcpServerRef: extractResourceRef(refObj),
+        ...optionalStringArray(entry, "enabled_tools", "enabledTools"),
+        ...optionalMappedArray(
+          entry,
+          "tool_approval_overrides",
+          "toolApprovalOverrides",
+          extractToolApprovalOverride,
+        ),
+      };
+    },
+  );
+}
+
+function extractToolApprovalOverride(
+  raw: Record<string, unknown>,
+): ToolApprovalOverrideInput {
+  return {
+    ...optionalSnakeToCamel(raw, "tool_name", "toolName"),
+    ...optionalSnakeToCamelBool(raw, "requires_approval", "requiresApproval"),
+    ...optionalString(raw, "message", "message"),
+  };
+}
+
+function extractSubAgents(
+  spec: Record<string, unknown>,
+): SubAgentInput[] | undefined {
+  const raw = spec.sub_agents ?? spec.subAgents;
+  if (!Array.isArray(raw) || raw.length === 0) return undefined;
+
+  return raw.filter(isPlainObject).map((entry): SubAgentInput => {
+    const entryName = entry.name;
+    if (typeof entryName !== "string" || entryName.length === 0) {
+      throw new Error(
+        "Agent YAML: each sub_agents entry must have a non-empty name.",
+      );
+    }
+
+    return {
+      name: entryName,
+      ...optionalString(entry, "description", "description"),
+      ...optionalString(entry, "instructions", "instructions"),
+      ...optionalSnakeToCamel(entry, "model_override", "modelOverride"),
+      ...optionalMappedArray(
+        entry,
+        "mcp_access",
+        "mcpAccess",
+        extractMcpAccess,
+      ),
+      ...optionalField(
+        "skillRefs",
+        extractResourceRefs(entry as Record<string, unknown>, "skill_refs"),
+      ),
+    };
+  });
+}
+
+function extractMcpAccess(raw: Record<string, unknown>): McpAccessInput {
+  const mcpServer = raw.mcp_server ?? raw.mcpServer;
+  if (typeof mcpServer !== "string" || mcpServer.length === 0) {
+    throw new Error(
+      "Agent YAML: each mcp_access entry must have a non-empty mcp_server.",
+    );
+  }
+
+  return {
+    mcpServer,
+    ...optionalStringArray(raw, "enabled_tools", "enabledTools"),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// McpServer conversion
+// ---------------------------------------------------------------------------
+
+function buildMcpServerInput(
+  name: string,
+  slug: string | undefined,
+  org: string,
+  labels: Record<string, string> | undefined,
+  spec: Record<string, unknown>,
+): McpServerInput {
+  const stdio = extractStdioConfig(spec);
+  const http = extractHttpConfig(spec);
+
+  if (!stdio && !http) {
+    throw new Error(
+      "McpServer YAML must specify either spec.stdio or spec.http.",
+    );
+  }
+
+  return {
+    name,
+    org,
+    ...(slug !== undefined && { slug }),
+    ...(labels !== undefined && { labels }),
+    ...optionalString(spec, "description", "description"),
+    ...optionalSnakeToCamel(spec, "icon_url", "iconUrl"),
+    ...optionalField("stdio", stdio),
+    ...optionalField("http", http),
+    ...optionalStringArrayFromSnake(spec, "default_enabled_tools", "defaultEnabledTools"),
+    ...optionalMappedArray(
+      spec,
+      "default_tool_approvals",
+      "defaultToolApprovals",
+      extractToolApprovalPolicy,
+    ),
+    ...optionalField("envSpec", extractEnvSpec(spec)),
+  };
+}
+
+function extractStdioConfig(
+  spec: Record<string, unknown>,
+): StdioServerConfigInput | undefined {
+  const raw = spec.stdio;
+  if (!isPlainObject(raw)) return undefined;
+
+  const command = raw.command;
+  if (typeof command !== "string" || command.length === 0) {
+    throw new Error(
+      "McpServer YAML: spec.stdio must have a non-empty command.",
+    );
+  }
+
+  return {
+    command,
+    ...optionalStringArray(raw, "args", "args"),
+    ...optionalSnakeToCamel(raw, "working_dir", "workingDir"),
+  };
+}
+
+function extractHttpConfig(
+  spec: Record<string, unknown>,
+): HttpServerConfigInput | undefined {
+  const raw = spec.http;
+  if (!isPlainObject(raw)) return undefined;
+
+  const url = raw.url;
+  if (typeof url !== "string" || url.length === 0) {
+    throw new Error("McpServer YAML: spec.http must have a non-empty url.");
+  }
+
+  return {
+    url,
+    ...optionalStringRecord(raw, "headers", "headers"),
+    ...optionalStringRecordSnake(raw, "query_params", "queryParams"),
+    ...optionalSnakeToCamelNumber(raw, "timeout_seconds", "timeoutSeconds"),
+  };
+}
+
+function extractToolApprovalPolicy(
+  raw: Record<string, unknown>,
+): ToolApprovalPolicyInput {
+  return {
+    ...optionalSnakeToCamel(raw, "tool_name", "toolName"),
+    ...optionalString(raw, "message", "message"),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Shared extractors
+// ---------------------------------------------------------------------------
+
+function extractEnvSpec(
+  spec: Record<string, unknown>,
+): EnvSpecInput | undefined {
+  const envSpecRaw = spec.env_spec ?? spec.envSpec;
+  if (!isPlainObject(envSpecRaw)) return undefined;
+
+  // Proto uses `data` as the map field name; SDK uses `variables`.
+  const data = envSpecRaw.data ?? envSpecRaw.variables;
+  if (!isPlainObject(data)) return undefined;
+
+  const variables: Record<string, EnvVarInput> = {};
+  let hasEntries = false;
+
+  for (const [key, val] of Object.entries(data)) {
+    if (!isPlainObject(val)) continue;
+
+    const value = typeof val.value === "string" ? val.value : "";
+    const isSecret = val.is_secret ?? val.isSecret;
+    const description = val.description;
+
+    variables[key] = {
+      value,
+      ...(typeof isSecret === "boolean" && { isSecret }),
+      ...(typeof description === "string" && { description }),
+    };
+    hasEntries = true;
+  }
+
+  return hasEntries ? { variables } : undefined;
+}
+
+function extractResourceRef(raw: Record<string, unknown>): ResourceRef {
+  const org = raw.org;
+  const slug = raw.slug;
+
+  if (typeof org !== "string" || org.length === 0) {
+    throw new Error("Resource reference must have a non-empty org.");
+  }
+  if (typeof slug !== "string" || slug.length === 0) {
+    throw new Error("Resource reference must have a non-empty slug.");
+  }
+
+  return {
+    org,
+    slug,
+    ...(typeof raw.version === "string" &&
+      raw.version.length > 0 && { version: raw.version }),
+    ...(typeof raw.kind === "number" && { kind: raw.kind }),
+  };
+}
+
+function extractResourceRefs(
+  container: Record<string, unknown>,
+  snakeKey: string,
+): ResourceRef[] | undefined {
+  const camelKey = snakeToCamel(snakeKey);
+  const raw = container[snakeKey] ?? container[camelKey];
+  if (!Array.isArray(raw) || raw.length === 0) return undefined;
+
+  return raw.filter(isPlainObject).map(extractResourceRef);
+}
+
+// ---------------------------------------------------------------------------
+// Field extraction helpers — return spreadable partials
+// ---------------------------------------------------------------------------
+
+function optionalField<K extends string, V>(
+  key: K,
+  value: V | undefined,
+): { [P in K]: V } | undefined {
+  if (value === undefined) return undefined;
+  return { [key]: value } as { [P in K]: V };
+}
+
+function optionalString<K extends string>(
+  obj: Record<string, unknown>,
+  sourceKey: string,
+  targetKey: K,
+): { [P in K]: string } | undefined {
+  const val = obj[sourceKey];
+  if (typeof val !== "string") return undefined;
+  return { [targetKey]: val } as { [P in K]: string };
+}
+
+function optionalSnakeToCamel<K extends string>(
+  obj: Record<string, unknown>,
+  snakeKey: string,
+  camelKey: K,
+): { [P in K]: string } | undefined {
+  const val = obj[snakeKey] ?? obj[camelKey];
+  if (typeof val !== "string") return undefined;
+  return { [camelKey]: val } as { [P in K]: string };
+}
+
+function optionalSnakeToCamelBool<K extends string>(
+  obj: Record<string, unknown>,
+  snakeKey: string,
+  camelKey: K,
+): { [P in K]: boolean } | undefined {
+  const val = obj[snakeKey] ?? obj[camelKey];
+  if (typeof val !== "boolean") return undefined;
+  return { [camelKey]: val } as { [P in K]: boolean };
+}
+
+function optionalSnakeToCamelNumber<K extends string>(
+  obj: Record<string, unknown>,
+  snakeKey: string,
+  camelKey: K,
+): { [P in K]: number } | undefined {
+  const val = obj[snakeKey] ?? obj[camelKey];
+  if (typeof val !== "number" || !Number.isFinite(val)) return undefined;
+  return { [camelKey]: val } as { [P in K]: number };
+}
+
+function optionalStringArray<K extends string>(
+  obj: Record<string, unknown>,
+  sourceKey: string,
+  targetKey: K,
+): { [P in K]: string[] } | undefined {
+  const val = obj[sourceKey] ?? obj[targetKey];
+  if (!Array.isArray(val)) return undefined;
+  const filtered = val.filter((v): v is string => typeof v === "string");
+  if (filtered.length === 0) return undefined;
+  return { [targetKey]: filtered } as { [P in K]: string[] };
+}
+
+function optionalStringArrayFromSnake<K extends string>(
+  obj: Record<string, unknown>,
+  snakeKey: string,
+  camelKey: K,
+): { [P in K]: string[] } | undefined {
+  const val = obj[snakeKey] ?? obj[camelKey];
+  if (!Array.isArray(val)) return undefined;
+  const filtered = val.filter((v): v is string => typeof v === "string");
+  if (filtered.length === 0) return undefined;
+  return { [camelKey]: filtered } as { [P in K]: string[] };
+}
+
+function optionalStringRecord<K extends string>(
+  obj: Record<string, unknown>,
+  sourceKey: string,
+  targetKey: K,
+): { [P in K]: Record<string, string> } | undefined {
+  const val = obj[sourceKey];
+  if (!isPlainObject(val)) return undefined;
+  return { [targetKey]: toStringRecord(val) } as {
+    [P in K]: Record<string, string>;
+  };
+}
+
+function optionalStringRecordSnake<K extends string>(
+  obj: Record<string, unknown>,
+  snakeKey: string,
+  camelKey: K,
+): { [P in K]: Record<string, string> } | undefined {
+  const val = obj[snakeKey] ?? obj[camelKey];
+  if (!isPlainObject(val)) return undefined;
+  return { [camelKey]: toStringRecord(val) } as {
+    [P in K]: Record<string, string>;
+  };
+}
+
+function optionalMappedArray<K extends string, T>(
+  obj: Record<string, unknown>,
+  snakeKey: string,
+  camelKey: K,
+  mapper: (item: Record<string, unknown>) => T,
+): { [P in K]: T[] } | undefined {
+  const raw = obj[snakeKey] ?? obj[camelKey];
+  if (!Array.isArray(raw) || raw.length === 0) return undefined;
+  const mapped = raw.filter(isPlainObject).map(mapper);
+  if (mapped.length === 0) return undefined;
+  return { [camelKey]: mapped } as { [P in K]: T[] };
+}
+
+// ---------------------------------------------------------------------------
+// Primitive helpers
+// ---------------------------------------------------------------------------
+
+function extractRequiredString(
+  obj: Record<string, unknown>,
+  key: string,
+  displayPath: string,
+): string {
+  const val = obj[key];
+  if (typeof val !== "string" || val.length === 0) {
+    throw new Error(
+      `Resource YAML is missing required field: ${displayPath}.`,
+    );
+  }
+  return val;
+}
+
+function extractOptionalString(
+  obj: Record<string, unknown>,
+  key: string,
+): string | undefined {
+  const val = obj[key];
+  return typeof val === "string" && val.length > 0 ? val : undefined;
+}
+
+function extractOptionalStringRecord(
+  obj: Record<string, unknown>,
+  key: string,
+): Record<string, string> | undefined {
+  const val = obj[key];
+  if (!isPlainObject(val)) return undefined;
+  return toStringRecord(val);
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function toStringRecord(obj: Record<string, unknown>): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (typeof v === "string") result[k] = v;
+    else if (v !== null && v !== undefined) result[k] = String(v);
+  }
+  return result;
+}
+
+function snakeToCamel(key: string): string {
+  return key.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
+}