@stigmer/react 0.4.7 → 0.5.0

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

@@ -1,4 +1,13 @@
 import { stringify as stringifyYaml } from "yaml";
+import type {
+  AgentInput,
+  McpServerInput,
+  McpServerUsageInput,
+  SubAgentInput,
+  McpAccessInput,
+  ToolApprovalOverrideInput,
+  ResourceRef,
+} from "@stigmer/sdk";
 import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import type {
   AgentSpec,
@@ -398,3 +407,350 @@ function hasEntries(obj: Record<string, unknown> | undefined): boolean {
   if (!obj) return false;
   return Object.keys(obj).length > 0;
 }
+
+// ===========================================================================
+// AgentInput serialization (from SDK input type, not proto)
+// ===========================================================================
+
+/**
+ * Serializes an {@link AgentInput} (SDK input type) into the canonical
+ * Stigmer YAML format.
+ *
+ * Unlike {@link serializeAgentYaml} which takes a proto `Agent`, this
+ * function works from the SDK input type — the same shape used by
+ * `stigmer.agent.apply()`. This is used by the creation wizard to
+ * preview the YAML before submission.
+ *
+ * The output is round-trip compatible with {@link parseResourceYaml}.
+ *
+ * @param input - The SDK `AgentInput` to serialize.
+ * @returns A YAML string in the canonical Stigmer resource format.
+ *
+ * @example
+ * ```ts
+ * import { serializeAgentInputYaml } from "@stigmer/react";
+ *
+ * const yaml = serializeAgentInputYaml({
+ *   name: "my-agent",
+ *   org: "acme",
+ *   instructions: "You are a helpful assistant.",
+ * });
+ * ```
+ */
+export function serializeAgentInputYaml(input: AgentInput): string {
+  const doc: Record<string, unknown> = {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "Agent",
+    metadata: buildInputMetadata(input),
+    spec: buildAgentInputSpec(input),
+  };
+
+  return stringifyYaml(doc, { lineWidth: 0, blockQuote: "literal" });
+}
+
+function buildInputMetadata(input: AgentInput): Record<string, unknown> {
+  const result: Record<string, unknown> = {
+    name: input.name,
+  };
+
+  if (input.org) {
+    result.org = input.org;
+  }
+
+  if (input.slug && input.slug !== input.name) {
+    result.slug = input.slug;
+  }
+
+  if (input.labels && Object.keys(input.labels).length > 0) {
+    result.labels = { ...input.labels };
+  }
+
+  return result;
+}
+
+function buildAgentInputSpec(input: AgentInput): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  if (input.description) {
+    result.description = input.description;
+  }
+
+  if (input.iconUrl) {
+    result.icon_url = input.iconUrl;
+  }
+
+  if (input.instructions) {
+    result.instructions = input.instructions;
+  }
+
+  if (input.mcpServerUsages && input.mcpServerUsages.length > 0) {
+    result.mcp_server_usages = input.mcpServerUsages.map(serializeInputMcpUsage);
+  }
+
+  if (input.skillRefs && input.skillRefs.length > 0) {
+    result.skill_refs = input.skillRefs.map(serializeInputRef);
+  }
+
+  if (input.subAgents && input.subAgents.length > 0) {
+    result.sub_agents = input.subAgents.map(serializeInputSubAgent);
+  }
+
+  if (input.env && Object.keys(input.env).length > 0) {
+    result.env = serializeInputEnv(input.env);
+  }
+
+  return result;
+}
+
+function serializeInputMcpUsage(
+  usage: McpServerUsageInput,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {
+    mcp_server_ref: serializeInputRef(usage.mcpServerRef),
+  };
+
+  if (usage.enabledTools && usage.enabledTools.length > 0) {
+    result.enabled_tools = [...usage.enabledTools];
+  }
+
+  if (usage.toolApprovalOverrides && usage.toolApprovalOverrides.length > 0) {
+    result.tool_approval_overrides =
+      usage.toolApprovalOverrides.map(serializeInputApprovalOverride);
+  }
+
+  return result;
+}
+
+function serializeInputApprovalOverride(
+  override: ToolApprovalOverrideInput,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  if (override.toolName) {
+    result.tool_name = override.toolName;
+  }
+  if (override.requiresApproval != null) {
+    result.requires_approval = override.requiresApproval;
+  }
+  if (override.message) {
+    result.message = override.message;
+  }
+
+  return result;
+}
+
+function serializeInputSubAgent(sub: SubAgentInput): Record<string, unknown> {
+  const result: Record<string, unknown> = {
+    name: sub.name,
+  };
+
+  if (sub.description) {
+    result.description = sub.description;
+  }
+  if (sub.instructions) {
+    result.instructions = sub.instructions;
+  }
+  if (sub.modelOverride) {
+    result.model_override = sub.modelOverride;
+  }
+  if (sub.mcpAccess && sub.mcpAccess.length > 0) {
+    result.mcp_access = sub.mcpAccess.map(serializeInputMcpAccess);
+  }
+  if (sub.skillRefs && sub.skillRefs.length > 0) {
+    result.skill_refs = sub.skillRefs.map(serializeInputRef);
+  }
+
+  return result;
+}
+
+function serializeInputMcpAccess(
+  access: McpAccessInput,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {
+    mcp_server: access.mcpServer,
+  };
+
+  if (access.enabledTools && access.enabledTools.length > 0) {
+    result.enabled_tools = [...access.enabledTools];
+  }
+
+  return result;
+}
+
+function serializeInputRef(ref: ResourceRef): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  if (ref.org) {
+    result.org = ref.org;
+  }
+  result.slug = ref.slug;
+
+  if (ref.version) {
+    result.version = ref.version;
+  }
+
+  return result;
+}
+
+function serializeInputEnv(
+  env: NonNullable<AgentInput["env"]>,
+): Record<string, Record<string, unknown>> {
+  const result: Record<string, Record<string, unknown>> = {};
+
+  for (const [key, val] of Object.entries(env)) {
+    const entry: Record<string, unknown> = {};
+
+    if (val.isSecret) {
+      entry.is_secret = val.isSecret;
+    }
+    if (val.description) {
+      entry.description = val.description;
+    }
+    if (val.optional) {
+      entry.optional = val.optional;
+    }
+
+    result[key] = entry;
+  }
+
+  return result;
+}
+
+// ===========================================================================
+// McpServerInput serialization (from SDK input type, not proto)
+// ===========================================================================
+
+/**
+ * Serializes a {@link McpServerInput} (SDK input type) into the canonical
+ * Stigmer YAML format.
+ *
+ * Unlike {@link serializeMcpServerYaml} which takes a proto `McpServer`,
+ * this function works from the SDK input type — the same shape used by
+ * `stigmer.mcpServer.apply()`. This is used by the creation wizard to
+ * preview the YAML before submission.
+ *
+ * The output is round-trip compatible with {@link parseResourceYaml}.
+ *
+ * @param input - The SDK `McpServerInput` to serialize.
+ * @returns A YAML string in the canonical Stigmer resource format.
+ *
+ * @example
+ * ```ts
+ * import { serializeMcpServerInputYaml } from "@stigmer/react";
+ *
+ * const yaml = serializeMcpServerInputYaml({
+ *   name: "github",
+ *   org: "acme",
+ *   http: { url: "https://mcp.github.com/sse" },
+ * });
+ * ```
+ */
+export function serializeMcpServerInputYaml(input: McpServerInput): string {
+  const doc: Record<string, unknown> = {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "McpServer",
+    metadata: buildMcpServerInputMetadata(input),
+    spec: buildMcpServerInputSpec(input),
+  };
+
+  return stringifyYaml(doc, { lineWidth: 0, blockQuote: "literal" });
+}
+
+function buildMcpServerInputMetadata(
+  input: McpServerInput,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {
+    name: input.name,
+  };
+
+  if (input.org) {
+    result.org = input.org;
+  }
+
+  if (input.slug && input.slug !== input.name) {
+    result.slug = input.slug;
+  }
+
+  if (input.labels && Object.keys(input.labels).length > 0) {
+    result.labels = { ...input.labels };
+  }
+
+  return result;
+}
+
+function buildMcpServerInputSpec(
+  input: McpServerInput,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  if (input.description) {
+    result.description = input.description;
+  }
+
+  if (input.iconUrl) {
+    result.icon_url = input.iconUrl;
+  }
+
+  if (input.stdio) {
+    const stdio: Record<string, unknown> = {
+      command: input.stdio.command,
+    };
+    if (input.stdio.args && input.stdio.args.length > 0) {
+      stdio.args = [...input.stdio.args];
+    }
+    if (input.stdio.workingDir) {
+      stdio.working_dir = input.stdio.workingDir;
+    }
+    result.stdio = stdio;
+  }
+
+  if (input.http) {
+    const http: Record<string, unknown> = {
+      url: input.http.url,
+    };
+    if (input.http.headers && Object.keys(input.http.headers).length > 0) {
+      http.headers = { ...input.http.headers };
+    }
+    if (input.http.queryParams && Object.keys(input.http.queryParams).length > 0) {
+      http.query_params = { ...input.http.queryParams };
+    }
+    if (input.http.timeoutSeconds && input.http.timeoutSeconds > 0) {
+      http.timeout_seconds = input.http.timeoutSeconds;
+    }
+    result.http = http;
+  }
+
+  if (input.env && Object.keys(input.env).length > 0) {
+    result.env = serializeInputEnv(input.env);
+  }
+
+  if (input.auth) {
+    result.auth = serializeInputMcpServerAuth(input.auth);
+  }
+
+  return result;
+}
+
+function serializeInputMcpServerAuth(
+  auth: NonNullable<McpServerInput["auth"]>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  if (auth.oauthAppRef) {
+    result.oauth_app_ref = serializeInputRef(auth.oauthAppRef);
+  }
+  if (auth.targetEnvVar) {
+    result.target_env_var = auth.targetEnvVar;
+  }
+  if (auth.tokenLifetimeHint) {
+    result.token_lifetime_hint = auth.tokenLifetimeHint;
+  }
+  if (auth.scopeHints && auth.scopeHints.length > 0) {
+    result.scope_hints = [...auth.scopeHints];
+  }
+  if (auth.discoveryUrl) {
+    result.discovery_url = auth.discoveryUrl;
+  }
+
+  return result;
+}

package/src/library/useExportResource.ts

@@ -0,0 +1,183 @@
+"use client";
+
+import { useCallback, useMemo } from "react";
+import { parse as parseYaml } from "yaml";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { toast } from "../feedback/toast";
+import { serializeAgentYaml, serializeMcpServerYaml } from "./serialize-resource-yaml";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Options for {@link useExportResource}. */
+export interface UseExportResourceOptions {
+  /** The resource kind — determines which serializer is used. */
+  readonly kind: "Agent" | "McpServer";
+  /** The proto resource to export, or `null` when not yet loaded. */
+  readonly resource: Agent | McpServer | null;
+}
+
+/** Return value of {@link useExportResource}. */
+export interface UseExportResourceReturn {
+  /** Copy the resource as YAML to the clipboard (with toast feedback). */
+  readonly copyYaml: () => Promise<void>;
+  /** Copy the resource as JSON to the clipboard (with toast feedback). */
+  readonly copyJson: () => Promise<void>;
+  /** Download the resource as a `.yaml` file. */
+  readonly downloadYaml: () => void;
+  /** Download the resource as a `.json` file. */
+  readonly downloadJson: () => void;
+  /** The serialized YAML string, or `null` when the resource is not loaded. */
+  readonly yaml: string | null;
+  /** The serialized JSON string, or `null` when the resource is not loaded. */
+  readonly json: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Headless export hook for Stigmer resources (Agent, McpServer).
+ *
+ * Serializes the resource into YAML and JSON formats and provides
+ * stable callbacks for copying to clipboard or triggering a file
+ * download. All operations are client-side — no additional API calls.
+ *
+ * The serialized output uses the canonical Stigmer resource format
+ * (`apiVersion`, `kind`, `metadata`, `spec`) with snake_case field
+ * names, identical to what the CLI produces and what `parseResourceYaml`
+ * accepts — ensuring full round-trip compatibility.
+ *
+ * @param options - Resource kind and the proto resource object.
+ * @returns Stable callbacks and memoized serialized strings.
+ *
+ * @example
+ * ```tsx
+ * const { agent } = useAgent(org, slug);
+ * const { copyYaml, downloadYaml } = useExportResource({
+ *   kind: "Agent",
+ *   resource: agent,
+ * });
+ *
+ * <ActionMenu.Item onSelect={copyYaml}>Export YAML</ActionMenu.Item>
+ * <ActionMenu.Item onSelect={downloadYaml}>Download YAML</ActionMenu.Item>
+ * ```
+ *
+ * @see {@link serializeAgentYaml} for the underlying Agent serializer
+ * @see {@link serializeMcpServerYaml} for the underlying McpServer serializer
+ */
+export function useExportResource({
+  kind,
+  resource,
+}: UseExportResourceOptions): UseExportResourceReturn {
+  const yaml = useMemo<string | null>(() => {
+    if (!resource) return null;
+    if (kind === "Agent") return serializeAgentYaml(resource as Agent);
+    return serializeMcpServerYaml(resource as McpServer);
+  }, [kind, resource]);
+
+  const json = useMemo<string | null>(() => {
+    if (!resource) return null;
+    if (kind === "Agent") return serializeResourceJson(resource as Agent, "Agent");
+    return serializeResourceJson(resource as McpServer, "McpServer");
+  }, [kind, resource]);
+
+  const slug = useMemo<string>(() => {
+    if (!resource) return "resource";
+    return resource.metadata?.slug || resource.metadata?.name || "resource";
+  }, [resource]);
+
+  const copyYaml = useCallback(async () => {
+    if (!yaml) return;
+    await copyToClipboard(yaml);
+    toast.success("YAML copied to clipboard");
+  }, [yaml]);
+
+  const copyJson = useCallback(async () => {
+    if (!json) return;
+    await copyToClipboard(json);
+    toast.success("JSON copied to clipboard");
+  }, [json]);
+
+  const downloadYaml = useCallback(() => {
+    if (!yaml) return;
+    downloadFile(yaml, `${slug}.yaml`, "text/yaml");
+  }, [yaml, slug]);
+
+  const downloadJson = useCallback(() => {
+    if (!json) return;
+    downloadFile(json, `${slug}.json`, "application/json");
+  }, [json, slug]);
+
+  return useMemo(
+    () => ({ copyYaml, copyJson, downloadYaml, downloadJson, yaml, json }),
+    [copyYaml, copyJson, downloadYaml, downloadJson, yaml, json],
+  );
+}
+
+// ---------------------------------------------------------------------------
+// JSON serialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Produces a JSON representation of the resource using the same canonical
+ * structure as the YAML export (apiVersion, kind, metadata, spec).
+ *
+ * Internally parses the YAML output to get a clean plain object, then
+ * re-stringifies as JSON. This guarantees the JSON structure is identical
+ * to the YAML structure (snake_case fields, no status).
+ */
+function serializeResourceJson(
+  resource: Agent | McpServer,
+  kind: "Agent" | "McpServer",
+): string {
+  const yamlStr = kind === "Agent"
+    ? serializeAgentYaml(resource as Agent)
+    : serializeMcpServerYaml(resource as McpServer);
+
+  const doc = parseYaml(yamlStr);
+  return JSON.stringify(doc, null, 2);
+}
+
+// ---------------------------------------------------------------------------
+// Clipboard
+// ---------------------------------------------------------------------------
+
+async function copyToClipboard(text: string): Promise<void> {
+  try {
+    await navigator.clipboard.writeText(text);
+  } catch {
+    fallbackCopy(text);
+  }
+}
+
+function fallbackCopy(text: string): void {
+  const textarea = document.createElement("textarea");
+  textarea.value = text;
+  textarea.style.position = "fixed";
+  textarea.style.opacity = "0";
+  document.body.appendChild(textarea);
+  textarea.select();
+  document.execCommand("copy");
+  document.body.removeChild(textarea);
+}
+
+// ---------------------------------------------------------------------------
+// File download
+// ---------------------------------------------------------------------------
+
+function downloadFile(content: string, filename: string, mimeType: string): void {
+  const blob = new Blob([content], { type: `${mimeType};charset=utf-8;` });
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = filename;
+  link.style.display = "none";
+  document.body.appendChild(link);
+  link.click();
+  document.body.removeChild(link);
+  URL.revokeObjectURL(url);
+}