@stigmer/react 3.2.3 → 3.3.0

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],
   );
 

package/src/resource-creation/templates/workflow-templates.ts

@@ -122,7 +122,7 @@ spec:
               - name: extract_findings
                 kind: llm_call
                 task_config:
-                  model: "gpt-4o-mini"
+                  model: "claude-haiku-4.5"
                   system_prompt: "Extract structured key findings from the analysis."
                   prompt: >
                     Extract the key findings from this analysis as structured data:
@@ -280,7 +280,7 @@ spec:
     - name: classify_ticket
       kind: llm_call
       task_config:
-        model: "gpt-4o-mini"
+        model: "claude-haiku-4.5"
         system_prompt: >
           You are a support ticket classifier. Analyze the ticket and classify
           it by severity and category. Be conservative with critical/high
@@ -923,7 +923,7 @@ spec:
               - name: diagnose_error
                 kind: llm_call
                 task_config:
-                  model: "gpt-4o-mini"
+                  model: "claude-haiku-4.5"
                   system_prompt: >
                     You are an API integration specialist. Given an error from
                     an HTTP call, provide a brief, actionable diagnosis.
@@ -1010,7 +1010,7 @@ spec:
       description: "Comma-separated list of topics the response should cover"
       optional: true
     MODEL_UNDER_TEST:
-      description: "Model to evaluate (default: gpt-4o-mini)"
+      description: "Model to evaluate (default: claude-haiku-4.5)"
       optional: true
   budget:
     max_cost_micros: 2000000

package/src/session/useEditSessionPrep.ts

@@ -7,7 +7,7 @@ import { useStigmer } from "../hooks.js";
 import { useAgent } from "../agent/index.js";
 import { useMcpServer } from "../mcp-server/index.js";
 import { useSkill } from "../skill/index.js";
-import { serializeAgentYaml, serializeMcpServerYaml } from "../library/index.js";
+import { serializeManifest } from "@stigmer/sdk";
 import type { DraftResourceType } from "./draft.js";
 
 /** Return value of {@link useEditSessionPrep}. */
@@ -64,7 +64,7 @@ export function useEditSessionPrep(
     if (draftType === "agent" && editAgent) {
       built.current = true;
       try {
-        const yaml = serializeAgentYaml(editAgent);
+        const yaml = serializeManifest(editAgent);
         const slug = editAgent.metadata?.slug ?? "agent";
         setFiles([new File([yaml], `${slug}.yaml`, { type: "text/yaml" })]);
       } catch {
@@ -75,7 +75,7 @@ export function useEditSessionPrep(
     if (draftType === "mcp-server" && editMcpServer) {
       built.current = true;
       try {
-        const yaml = serializeMcpServerYaml(editMcpServer);
+        const yaml = serializeManifest(editMcpServer);
         const slug = editMcpServer.metadata?.slug ?? "mcp-server";
         setFiles([new File([yaml], `${slug}.yaml`, { type: "text/yaml" })]);
       } catch {

package/src/settings/__tests__/useSettingsNavGroups.test.tsx

@@ -0,0 +1,138 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { useRef, useState } from "react";
+import { SETTINGS_NAV_GROUPS, PLATFORM_SETTINGS_NAV_GROUP } from "../settings-nav";
+import { useSettingsNavGroups } from "../useSettingsNavGroups";
+
+// Drive the nav gate through the permission hook. The fail-closed
+// semantics themselves are covered by useCheckPermission's own suite —
+// here we assert the nav hook's per-item composition of the verdicts.
+// Verdicts are keyed by relation so each platform permission can be
+// granted independently.
+let verdicts: Record<string, boolean> = {};
+let checkedRelations: string[] = [];
+let lastCheckArgs: readonly unknown[] = [];
+
+vi.mock("../../iam-policy/useCheckPermission", () => ({
+  useCheckPermission: (
+    ...args: [unknown, string, { fail?: string } | undefined]
+  ) => {
+    lastCheckArgs = args;
+    checkedRelations.push(args[1]);
+    return { allowed: verdicts[args[1]] === true, isLoading: false, error: null };
+  },
+}));
+
+afterEach(() => {
+  cleanup();
+  verdicts = {};
+  checkedRelations = [];
+});
+
+function GroupsProbe() {
+  const groups = useSettingsNavGroups();
+  const platform = groups.find((g) => g.label === PLATFORM_SETTINGS_NAV_GROUP.label);
+  return (
+    <div
+      data-testid="groups"
+      data-labels={groups.map((g) => g.label).join(",")}
+      data-platform-items={platform?.items.map((i) => i.label).join(",") ?? ""}
+    />
+  );
+}
+
+const BASE_LABELS = SETTINGS_NAV_GROUPS.map((g) => g.label).join(",");
+
+describe("useSettingsNavGroups", () => {
+  it("appends the full Platform group when the operator holds every platform permission", () => {
+    verdicts = {
+      can_manage_model_pricing: true,
+      can_manage_cursor_accounts: true,
+    };
+    render(<GroupsProbe />);
+
+    const el = screen.getByTestId("groups");
+    expect(el.getAttribute("data-labels")).toBe(
+      `${BASE_LABELS},${PLATFORM_SETTINGS_NAV_GROUP.label}`,
+    );
+    expect(el.getAttribute("data-platform-items")).toBe(
+      "Pricing Governance,Cursor Accounts",
+    );
+  });
+
+  it("filters per item: pricing-only operator sees only Pricing Governance", () => {
+    verdicts = { can_manage_model_pricing: true };
+    render(<GroupsProbe />);
+
+    expect(screen.getByTestId("groups").getAttribute("data-platform-items")).toBe(
+      "Pricing Governance",
+    );
+  });
+
+  it("filters per item: cursor-accounts-only operator sees only Cursor Accounts", () => {
+    verdicts = { can_manage_cursor_accounts: true };
+    render(<GroupsProbe />);
+
+    expect(screen.getByTestId("groups").getAttribute("data-platform-items")).toBe(
+      "Cursor Accounts",
+    );
+  });
+
+  it("returns exactly the base groups when not authorized", () => {
+    function IdentityProbe() {
+      const groups = useSettingsNavGroups();
+      return (
+        <div
+          data-testid="identity"
+          data-is-base={String(groups === SETTINGS_NAV_GROUPS)}
+        />
+      );
+    }
+    render(<IdentityProbe />);
+
+    // Not just equivalent — the same array, no needless copy.
+    expect(screen.getByTestId("identity").getAttribute("data-is-base")).toBe("true");
+  });
+
+  it("checks every declared platform permission on platform:stigmer, fail-closed", () => {
+    render(<GroupsProbe />);
+
+    // Exhaustiveness guard: every requiredPermission declared on the
+    // platform group must have a corresponding hook check — a new
+    // platform surface that forgets to add its check fails here.
+    const declared = PLATFORM_SETTINGS_NAV_GROUP.items.map(
+      (item) => item.requiredPermission,
+    );
+    for (const permission of declared) {
+      expect(permission, "platform items must declare requiredPermission").toBeDefined();
+      expect(checkedRelations).toContain(permission);
+    }
+    expect(lastCheckArgs[0]).toEqual({ kind: "platform", id: "stigmer" });
+    expect(lastCheckArgs[2]).toEqual({ fail: "closed" });
+  });
+
+  it("keeps the array reference stable across re-renders", () => {
+    verdicts = {
+      can_manage_model_pricing: true,
+      can_manage_cursor_accounts: true,
+    };
+
+    function StabilityProbe() {
+      const groups = useSettingsNavGroups();
+      const first = useRef(groups);
+      const [, force] = useState(0);
+      return (
+        <button
+          data-testid="stability"
+          data-stable={String(first.current === groups)}
+          onClick={() => force((n) => n + 1)}
+        />
+      );
+    }
+
+    render(<StabilityProbe />);
+    const el = screen.getByTestId("stability");
+    fireEvent.click(el);
+    expect(el.getAttribute("data-stable")).toBe("true");
+  });
+});

package/src/settings/index.ts

@@ -1,5 +1,9 @@
-export { SETTINGS_NAV_GROUPS } from "./settings-nav.js";
+export {
+  SETTINGS_NAV_GROUPS,
+  PLATFORM_SETTINGS_NAV_GROUP,
+} from "./settings-nav.js";
 export type { SettingsNavItem, SettingsNavGroup } from "./settings-nav.js";
+export { useSettingsNavGroups } from "./useSettingsNavGroups.js";
 
 export { ApiKeysSection } from "./ApiKeysSection.js";
 export { BillingSection } from "./BillingSection.js";

package/src/settings/settings-nav.ts

@@ -8,7 +8,9 @@ import {
   KeyRound,
   Link,
   MessageSquare,
+  MousePointerClick,
   Plug,
+  Scale,
   ShieldCheck,
   Users,
 } from "lucide-react";
@@ -24,6 +26,14 @@ export interface SettingsNavItem {
     /** Optional CSS class name applied to the icon. */
     className?: string;
   }>;
+  /**
+   * Platform-level permission (on `platform:stigmer`) required for this
+   * entry to appear. Only meaningful inside
+   * {@link PLATFORM_SETTINGS_NAV_GROUP} — items in the base groups are
+   * visible to every signed-in user and leave this unset.
+   * {@link useSettingsNavGroups} checks it fail-closed.
+   */
+  readonly requiredPermission?: string;
 }
 
 /** Grouping model used to render settings navigation sections. */
@@ -82,3 +92,36 @@ export const SETTINGS_NAV_GROUPS: readonly SettingsNavGroup[] = [
     ],
   },
 ];
+
+/**
+ * Stigmer-internal platform-operator navigation group.
+ *
+ * Deliberately NOT part of {@link SETTINGS_NAV_GROUPS}: that constant
+ * means "groups every signed-in user sees", and its members must never
+ * change based on who is looking. This group is appended for platform
+ * operators only — use {@link useSettingsNavGroups} to get the
+ * permission-aware list instead of composing the two by hand.
+ *
+ * Every item here declares its `requiredPermission`; the hook filters
+ * per item (fail-closed), so an operator holding one platform permission
+ * but not another sees exactly their slice of this group.
+ */
+export const PLATFORM_SETTINGS_NAV_GROUP: SettingsNavGroup = {
+  label: "Platform",
+  description:
+    "Stigmer-internal operations. Visible to platform operators only.",
+  items: [
+    {
+      href: "/settings/pricing-governance",
+      label: "Pricing Governance",
+      icon: Scale,
+      requiredPermission: "can_manage_model_pricing",
+    },
+    {
+      href: "/settings/cursor-accounts",
+      label: "Cursor Accounts",
+      icon: MousePointerClick,
+      requiredPermission: "can_manage_cursor_accounts",
+    },
+  ],
+};

package/src/settings/useSettingsNavGroups.ts

@@ -0,0 +1,81 @@
+"use client";
+
+import { useMemo } from "react";
+import { useCheckPermission } from "../iam-policy/useCheckPermission.js";
+import {
+  PLATFORM_SETTINGS_NAV_GROUP,
+  SETTINGS_NAV_GROUPS,
+  type SettingsNavGroup,
+} from "./settings-nav.js";
+
+/**
+ * The `platform` singleton — platform-level permissions are always
+ * checked against this one resource (mirrors the server-side
+ * `resource_id = "stigmer"` RPC config).
+ */
+const PLATFORM_RESOURCE = { kind: "platform", id: "stigmer" } as const;
+
+/**
+ * Permission-aware settings navigation: {@link SETTINGS_NAV_GROUPS}
+ * for everyone, plus the {@link PLATFORM_SETTINGS_NAV_GROUP} items the
+ * caller's platform permissions unlock (per-item `requiredPermission`,
+ * checked against `platform:stigmer`). The group appears when at least
+ * one of its items is visible.
+ *
+ * The checks run fail-closed — the opposite of the `useCheckPermission`
+ * default — because navigation is *discoverability*, not *capability*:
+ * an action gate can safely fail open (the server re-checks every
+ * request), but an operator-only nav entry must not appear while the
+ * check is loading, when it errors, or on deployments where the IAM
+ * service (and the surface it points to) does not exist.
+ *
+ * Implementation note: hooks must be called unconditionally, so each
+ * distinct platform permission gets its own static check below. When a
+ * new platform surface adds a new permission, add its check to
+ * PLATFORM_PERMISSION_CHECKS' shape here — the exhaustiveness guard in
+ * the tests catches a forgotten one.
+ *
+ * @example
+ * ```tsx
+ * const groups = useSettingsNavGroups();
+ * return groups.map((group) => <NavGroup key={group.label} group={group} />);
+ * ```
+ */
+export function useSettingsNavGroups(): readonly SettingsNavGroup[] {
+  const pricing = useCheckPermission(
+    PLATFORM_RESOURCE,
+    "can_manage_model_pricing",
+    { fail: "closed" },
+  );
+  const cursorAccounts = useCheckPermission(
+    PLATFORM_RESOURCE,
+    "can_manage_cursor_accounts",
+    { fail: "closed" },
+  );
+
+  const pricingAllowed = pricing.allowed;
+  const cursorAccountsAllowed = cursorAccounts.allowed;
+
+  return useMemo(() => {
+    const verdicts: Record<string, boolean> = {
+      can_manage_model_pricing: pricingAllowed,
+      can_manage_cursor_accounts: cursorAccountsAllowed,
+    };
+
+    const visibleItems = PLATFORM_SETTINGS_NAV_GROUP.items.filter(
+      // Fail closed on both axes: an item with no declared permission or
+      // with a permission this hook does not check yet stays hidden.
+      (item) =>
+        item.requiredPermission !== undefined &&
+        verdicts[item.requiredPermission] === true,
+    );
+
+    if (visibleItems.length === 0) {
+      return SETTINGS_NAV_GROUPS;
+    }
+    return [
+      ...SETTINGS_NAV_GROUPS,
+      { ...PLATFORM_SETTINGS_NAV_GROUP, items: visibleItems },
+    ];
+  }, [pricingAllowed, cursorAccountsAllowed]);
+}