@stigmer/react 3.2.3 → 3.4.0

package/src/manifest/useApplyManifest.ts

@@ -0,0 +1,270 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  containsRedactedSecrets,
+  parseManifest,
+  type AppliedManifest,
+  type ManifestDocument,
+} from "@stigmer/sdk";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/** Per-document apply lifecycle within one manifest. */
+export type ManifestEntryStatus =
+  | "pending"
+  | "applying"
+  | "applied"
+  | "failed"
+  /** A prior document failed; this one was not attempted. */
+  | "skipped";
+
+/** One document of the manifest, with its preview and apply state. */
+export interface ManifestPreviewEntry {
+  /** The parsed document (kind handler, message, name/slug/org). */
+  readonly document: ManifestDocument;
+  /** What applying will do, resolved against live server state. */
+  readonly action: "create" | "update" | "unknown";
+  /** Apply lifecycle status. */
+  readonly status: ManifestEntryStatus;
+  /** The applied resource, present when `status` is `"applied"`. */
+  readonly result?: AppliedManifest;
+  /** User-facing failure message, present when `status` is `"failed"`. */
+  readonly errorMessage?: string;
+}
+
+/** Return value of {@link useApplyManifest}. */
+export interface UseApplyManifestReturn {
+  /** Current manifest text (paste target). */
+  readonly content: string;
+  /** Update the manifest text. Re-validates (debounced). */
+  readonly setContent: (value: string) => void;
+  /** Read a `.yaml`/`.yml`/`.json` file into `content`. */
+  readonly readFile: (file: File) => Promise<void>;
+  /**
+   * Validated per-document preview in dependency apply order, or `null`
+   * while the content is empty or invalid.
+   */
+  readonly entries: readonly ManifestPreviewEntry[] | null;
+  /** Validation error for the current content, or `null` when valid. */
+  readonly validationError: string | null;
+  /** `true` while the (debounced) validation + existence checks run. */
+  readonly isValidating: boolean;
+  /** `true` when the content contains `***REDACTED***` secret markers. */
+  readonly hasRedactedSecrets: boolean;
+  /**
+   * Apply all documents sequentially in dependency order. Entries update
+   * live. Stops at the first failure (later entries become `"skipped"`).
+   * Resolves `true` when every document applied.
+   */
+  readonly applyAll: () => Promise<boolean>;
+  /** `true` while applies are in flight. */
+  readonly isApplying: boolean;
+  /** Clear all state (content, preview, errors). */
+  readonly reset: () => void;
+}
+
+// Validation parses + resolves existence server-side; wait for a typing pause.
+const VALIDATE_DEBOUNCE_MS = 500;
+
+/**
+ * Headless "apply a YAML manifest" flow for any registry-supported kind —
+ * the console counterpart of `stigmer apply -f`.
+ *
+ * Orchestrates: paste or upload → strict parse against generated proto
+ * schemas ({@link parseManifest}) → per-document create-vs-update preview
+ * (server existence check) → sequential apply in dependency order with
+ * live per-document status.
+ *
+ * Accepts multi-document manifests (`---` separators) and JSON content
+ * (YAML is a superset). The target `org` is injected into documents that
+ * omit `metadata.org`; documents naming a *different* org are honored and
+ * apply there (matching `stigmer apply` semantics — the org-mismatch
+ * warning surfaces on the parsed document).
+ *
+ * @param org - Target organization slug for `metadata.org` injection.
+ *
+ * @example
+ * ```tsx
+ * const manifest = useApplyManifest(activeOrg);
+ *
+ * <textarea value={manifest.content}
+ *           onChange={(e) => manifest.setContent(e.target.value)} />
+ * {manifest.entries?.map((e) => (
+ *   <PreviewRow key={e.document.slug} entry={e} />
+ * ))}
+ * <button onClick={manifest.applyAll} disabled={!manifest.entries}>Apply</button>
+ * ```
+ *
+ * @see {@link ApplyManifestDialog} for the styled component composing this hook
+ * @see {@link useEditResourceYaml} for the edit-in-place counterpart
+ */
+export function useApplyManifest(org: string): UseApplyManifestReturn {
+  const stigmer = useStigmer();
+
+  const [content, setContentState] = useState("");
+  const [entries, setEntries] = useState<readonly ManifestPreviewEntry[] | null>(null);
+  const [validationError, setValidationError] = useState<string | null>(null);
+  const [isValidating, setIsValidating] = useState(false);
+  const [isApplying, setIsApplying] = useState(false);
+
+  const orgRef = useRef(org);
+  orgRef.current = org;
+
+  const setContent = useCallback((value: string) => {
+    setContentState(value);
+  }, []);
+
+  const readFile = useCallback(async (file: File) => {
+    let text: string;
+    try {
+      text = await file.text();
+    } catch {
+      setContentState("");
+      setEntries(null);
+      setValidationError(`Failed to read ${file.name}.`);
+      return;
+    }
+    setContentState(text);
+  }, []);
+
+  const reset = useCallback(() => {
+    setContentState("");
+    setEntries(null);
+    setValidationError(null);
+    setIsValidating(false);
+    setIsApplying(false);
+  }, []);
+
+  // Debounced validation + existence resolution, cancellation-safe. Applies
+  // freeze the preview: entries carry live statuses the validator must not
+  // clobber mid-run.
+  const validateSeq = useRef(0);
+  useEffect(() => {
+    if (isApplying) return;
+
+    const seq = ++validateSeq.current;
+
+    if (!content.trim()) {
+      setEntries(null);
+      setValidationError(null);
+      setIsValidating(false);
+      return;
+    }
+
+    setIsValidating(true);
+
+    const timer = setTimeout(async () => {
+      let documents: ManifestDocument[];
+      try {
+        documents = parseManifest(content, { org: orgRef.current });
+      } catch (err) {
+        if (validateSeq.current === seq) {
+          setEntries(null);
+          setValidationError(toError(err).message);
+          setIsValidating(false);
+        }
+        return;
+      }
+
+      const resolved = await Promise.all(
+        documents.map(async (document): Promise<ManifestPreviewEntry> => {
+          let action: ManifestPreviewEntry["action"];
+          try {
+            const existing = await stigmer.manifest.getByReference(
+              document.handler.yamlKind,
+              document.org,
+              document.slug,
+            );
+            action = existing !== null ? "update" : "create";
+          } catch {
+            action = "unknown";
+          }
+          return { document, action, status: "pending" };
+        }),
+      );
+
+      if (validateSeq.current === seq) {
+        setEntries(resolved);
+        setValidationError(null);
+        setIsValidating(false);
+      }
+    }, VALIDATE_DEBOUNCE_MS);
+
+    return () => clearTimeout(timer);
+  }, [content, stigmer, isApplying]);
+
+  const applyAll = useCallback(async (): Promise<boolean> => {
+    if (!entries || entries.length === 0) return false;
+
+    // Invalidate any in-flight validation so it cannot clobber apply statuses.
+    validateSeq.current++;
+    setIsApplying(true);
+
+    // Local working copy — React state is updated per transition so the
+    // dialog renders progress live.
+    const working = entries.map((entry): ManifestPreviewEntry => ({ ...entry, status: "pending" }));
+    const commit = () => setEntries([...working]);
+
+    let allApplied = true;
+
+    for (let i = 0; i < working.length; i++) {
+      if (!allApplied) {
+        working[i] = { ...working[i], status: "skipped" };
+        continue;
+      }
+
+      working[i] = { ...working[i], status: "applying" };
+      commit();
+
+      try {
+        const result = await stigmer.manifest.apply(working[i].document);
+        working[i] = { ...working[i], status: "applied", result };
+      } catch (err) {
+        working[i] = {
+          ...working[i],
+          status: "failed",
+          errorMessage: toError(err).message,
+        };
+        allApplied = false;
+      }
+      commit();
+    }
+
+    commit();
+    setIsApplying(false);
+    return allApplied;
+  }, [entries, stigmer]);
+
+  const hasRedactedSecrets = useMemo(
+    () => containsRedactedSecrets(content),
+    [content],
+  );
+
+  return useMemo(
+    () => ({
+      content,
+      setContent,
+      readFile,
+      entries,
+      validationError,
+      isValidating,
+      hasRedactedSecrets,
+      applyAll,
+      isApplying,
+      reset,
+    }),
+    [
+      content,
+      setContent,
+      readFile,
+      entries,
+      validationError,
+      isValidating,
+      hasRedactedSecrets,
+      applyAll,
+      isApplying,
+      reset,
+    ],
+  );
+}

package/src/manifest/useEditResourceYaml.ts

@@ -0,0 +1,273 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { Message } from "@bufbuild/protobuf";
+import {
+  containsRedactedSecrets,
+  parseManifest,
+  serializeManifest,
+  type AppliedManifest,
+  type ManifestDocument,
+} from "@stigmer/sdk";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/**
+ * Result of validating the edited YAML against the source resource.
+ *
+ * Discriminated on `status` so consumers can render exactly one of:
+ * a disabled state (`empty`), an inline error (`invalid`), or the
+ * apply affordance (`valid`).
+ */
+export type EditYamlValidation =
+  | { readonly status: "empty" }
+  | { readonly status: "invalid"; readonly message: string }
+  | { readonly status: "valid"; readonly document: ManifestDocument };
+
+/**
+ * What applying the current content will do — resolved against live
+ * server state so renames surface as "create" before the user commits.
+ */
+export type EditYamlTarget =
+  | { readonly action: "update"; readonly slug: string }
+  | { readonly action: "create"; readonly slug: string }
+  /** Existence lookup failed (offline, permissions) — wording degrades. */
+  | { readonly action: "unknown"; readonly slug: string };
+
+/** Options for {@link useEditResourceYaml}. */
+export interface UseEditResourceYamlOptions {
+  /**
+   * The resource to edit, as returned by the server (e.g. from `useAgent`
+   * or a list panel row). `null` while the resource is loading — the hook
+   * seeds the editor when it arrives.
+   */
+  readonly resource: Message | null;
+}
+
+/** Return value of {@link useEditResourceYaml}. */
+export interface UseEditResourceYamlReturn {
+  /** Current editor content. */
+  readonly yaml: string;
+  /** Update the editor content (wire to the YAML editor's `onChange`). */
+  readonly setYaml: (value: string) => void;
+  /** `true` when the content differs from the seeded serialization. */
+  readonly isDirty: boolean;
+  /** Live validation of the current content. */
+  readonly validation: EditYamlValidation;
+  /**
+   * Create-vs-update preview for the current content, or `null` while
+   * validation fails or the existence check is in flight.
+   */
+  readonly target: EditYamlTarget | null;
+  /** `true` when the content contains `***REDACTED***` secret markers. */
+  readonly hasRedactedSecrets: boolean;
+  /**
+   * Apply the edited YAML. Resolves with the applied resource, or `null`
+   * when the content is not currently valid (check `validation`).
+   */
+  readonly apply: () => Promise<AppliedManifest | null>;
+  /** `true` while the apply RPC is in flight. */
+  readonly isApplying: boolean;
+  /** Error from the last failed apply, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Clear the apply error (e.g. when the user edits again). */
+  readonly clearError: () => void;
+  /** Discard edits and reseed from the resource. */
+  readonly reset: () => void;
+}
+
+// Existence checks run against live server state; wait for a typing pause.
+const TARGET_CHECK_DEBOUNCE_MS = 400;
+
+/**
+ * Behavior hook for editing an existing resource as YAML and applying the
+ * result — the console's kind-agnostic "Edit YAML" flow.
+ *
+ * Seeds the editor from {@link serializeManifest} (full fidelity minus
+ * system-managed state), validates every edit against the kind's generated
+ * proto schema via {@link parseManifest} (strict — unknown fields fail
+ * loudly), previews create-vs-update by resolving the edited document's
+ * reference against the server, and applies through
+ * `stigmer.manifest.apply()`.
+ *
+ * Guardrails beyond the raw engine:
+ * - the edited document must stay the same kind as the source resource
+ *   (pasting an Environment into an Agent editor is an error, not an apply)
+ * - the edited manifest must contain exactly one document
+ *
+ * @example
+ * ```tsx
+ * const edit = useEditResourceYaml({ resource: agent });
+ *
+ * <YamlEditor value={edit.yaml} onChange={edit.setYaml} />
+ * {edit.validation.status === "invalid" && <p>{edit.validation.message}</p>}
+ * <button disabled={edit.validation.status !== "valid"} onClick={edit.apply}>
+ *   {edit.target?.action === "create" ? "Create" : "Apply changes"}
+ * </button>
+ * ```
+ *
+ * @see {@link EditResourceYamlDialog} for the styled component composing this hook
+ * @see {@link useApplyManifest} for the paste/upload counterpart
+ */
+export function useEditResourceYaml({
+  resource,
+}: UseEditResourceYamlOptions): UseEditResourceYamlReturn {
+  const stigmer = useStigmer();
+
+  // The serialized source of truth. Recomputed when the resource changes;
+  // only reseeds the editor while the user hasn't started editing.
+  const seeded = useMemo(
+    () => (resource ? serializeManifest(resource) : ""),
+    [resource],
+  );
+
+  const [yaml, setYamlState] = useState(seeded);
+  const [isDirty, setIsDirty] = useState(false);
+  const [isApplying, setIsApplying] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [target, setTarget] = useState<EditYamlTarget | null>(null);
+
+  useEffect(() => {
+    if (!isDirty) setYamlState(seeded);
+  }, [seeded, isDirty]);
+
+  const setYaml = useCallback(
+    (value: string) => {
+      setYamlState(value);
+      setIsDirty(value !== seeded);
+    },
+    [seeded],
+  );
+
+  const reset = useCallback(() => {
+    setYamlState(seeded);
+    setIsDirty(false);
+    setError(null);
+  }, [seeded]);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const sourceKind = useMemo(() => {
+    if (!resource) return null;
+    // The seeded YAML's kind is authoritative for the source resource; a
+    // parse of our own serialization cannot fail.
+    return seeded ? parseManifest(seeded)[0].handler.yamlKind : null;
+  }, [resource, seeded]);
+
+  const validation = useMemo<EditYamlValidation>(() => {
+    if (!yaml.trim()) return { status: "empty" };
+
+    let documents: ManifestDocument[];
+    try {
+      documents = parseManifest(yaml);
+    } catch (err) {
+      return { status: "invalid", message: toError(err).message };
+    }
+
+    if (documents.length > 1) {
+      return {
+        status: "invalid",
+        message:
+          "This editor applies a single resource. Remove the extra " +
+          "documents, or use Apply YAML in the Library for multi-document manifests.",
+      };
+    }
+
+    const document = documents[0];
+    if (sourceKind !== null && document.handler.yamlKind !== sourceKind) {
+      return {
+        status: "invalid",
+        message:
+          `The document's kind changed from ${sourceKind} to ` +
+          `${document.handler.yamlKind}. To apply a different resource kind, ` +
+          "use Apply YAML in the Library instead.",
+      };
+    }
+
+    return { status: "valid", document };
+  }, [yaml, sourceKind]);
+
+  // Resolve create-vs-update against live state whenever the content
+  // becomes valid, debounced across keystrokes and cancellation-safe.
+  const checkSeq = useRef(0);
+  useEffect(() => {
+    if (validation.status !== "valid") {
+      setTarget(null);
+      return;
+    }
+
+    const { document } = validation;
+    const seq = ++checkSeq.current;
+    setTarget(null);
+
+    const timer = setTimeout(async () => {
+      let action: EditYamlTarget["action"];
+      try {
+        const existing = await stigmer.manifest.getByReference(
+          document.handler.yamlKind,
+          document.org,
+          document.slug,
+        );
+        action = existing !== null ? "update" : "create";
+      } catch {
+        action = "unknown";
+      }
+      if (checkSeq.current === seq) {
+        setTarget({ action, slug: document.slug });
+      }
+    }, TARGET_CHECK_DEBOUNCE_MS);
+
+    return () => clearTimeout(timer);
+  }, [validation, stigmer]);
+
+  const apply = useCallback(async (): Promise<AppliedManifest | null> => {
+    if (validation.status !== "valid") return null;
+
+    setIsApplying(true);
+    setError(null);
+    try {
+      const applied = await stigmer.manifest.apply(validation.document);
+      setIsDirty(false);
+      return applied;
+    } catch (err) {
+      setError(toError(err));
+      throw err;
+    } finally {
+      setIsApplying(false);
+    }
+  }, [validation, stigmer]);
+
+  const hasRedactedSecrets = useMemo(
+    () => containsRedactedSecrets(yaml),
+    [yaml],
+  );
+
+  return useMemo(
+    () => ({
+      yaml,
+      setYaml,
+      isDirty,
+      validation,
+      target,
+      hasRedactedSecrets,
+      apply,
+      isApplying,
+      error,
+      clearError,
+      reset,
+    }),
+    [
+      yaml,
+      setYaml,
+      isDirty,
+      validation,
+      target,
+      hasRedactedSecrets,
+      apply,
+      isApplying,
+      error,
+      clearError,
+      reset,
+    ],
+  );
+}

package/src/mcp-server/steps/ReviewStep.tsx

@@ -2,9 +2,8 @@
 
 import { useMemo } from "react";
 import { cn } from "@stigmer/theme";
-import { getUserMessage } from "@stigmer/sdk";
+import { buildMcpServerProto, getUserMessage, serializeManifest } from "@stigmer/sdk";
 import type { McpServerInput } from "@stigmer/sdk";
-import { serializeMcpServerInputYaml } from "../../library/serialize-resource-yaml.js";
 import type { McpServerWizardData } from "./types.js";
 
 /** Props for {@link ReviewStep}. */
@@ -33,7 +32,7 @@ export function ReviewStep({
     [org, data],
   );
   const yamlPreview = useMemo(
-    () => serializeMcpServerInputYaml(mcpServerInput),
+    () => serializeManifest(buildMcpServerProto(mcpServerInput)),
     [mcpServerInput],
   );