@stigmer/react 0.0.36 → 0.0.40

package/src/error/ErrorMessage.tsx

@@ -0,0 +1,225 @@
+"use client";
+
+import { useState } from "react";
+import {
+  classifyError,
+  getUserMessage,
+  getRpcMetadata,
+  isRetryableError,
+  type ErrorCategory,
+} from "@stigmer/sdk";
+import { cn } from "@stigmer/theme";
+
+export interface ErrorMessageProps {
+  /** The error to display. Renders nothing when `null`. */
+  readonly error: Error | null;
+  /** Override the default title derived from the error category. */
+  readonly title?: string;
+  /**
+   * Callback to retry the failed operation.
+   * Shows a "Retry" button when provided **and** the error is retryable
+   * (server or unavailable category).
+   */
+  readonly retry?: () => void;
+  readonly className?: string;
+}
+
+const CATEGORY_TITLES: Record<ErrorCategory, string> = {
+  auth: "Authentication required",
+  permission: "Access denied",
+  "not-found": "Not found",
+  validation: "Invalid request",
+  server: "Server error",
+  unavailable: "Service unavailable",
+  cancelled: "Request cancelled",
+  unknown: "Something went wrong",
+};
+
+/**
+ * Inline error display that classifies errors and renders a
+ * category-appropriate message with optional retry and expandable
+ * technical details (RPC method and path).
+ *
+ * Uses `classifyError()`, `getUserMessage()`, `getRpcMetadata()`, and
+ * `isRetryableError()` from `@stigmer/sdk` to provide structured,
+ * user-friendly error rendering.
+ *
+ * All visual properties flow through `--stgm-*` design tokens. No
+ * Console-specific dependencies — safe for platform builder embedding.
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, error, refetch } = useAgent(id);
+ * if (error) return <ErrorMessage error={error} retry={refetch} />;
+ * ```
+ */
+export function ErrorMessage({
+  error,
+  title,
+  retry,
+  className,
+}: ErrorMessageProps) {
+  const [detailsOpen, setDetailsOpen] = useState(false);
+
+  if (!error) return null;
+
+  const category = classifyError(error);
+  const message = getUserMessage(error);
+  const metadata = getRpcMetadata(error);
+  const retryable = isRetryableError(error);
+  const isShield = category === "auth" || category === "permission";
+
+  return (
+    <div
+      role="alert"
+      className={cn(
+        "bg-destructive/5 border-destructive/20 text-destructive rounded-lg border p-4",
+        className,
+      )}
+    >
+      <div className="flex items-start gap-3">
+        {isShield ? (
+          <ShieldXIcon className="mt-0.5 size-4 shrink-0" />
+        ) : (
+          <AlertTriangleIcon className="mt-0.5 size-4 shrink-0" />
+        )}
+
+        <div className="min-w-0 flex-1 space-y-1">
+          <p className="text-sm font-medium">
+            {title ?? CATEGORY_TITLES[category]}
+          </p>
+          <p className="text-destructive/80 text-sm">{message}</p>
+
+          {metadata && (
+            <div className="pt-1">
+              <button
+                type="button"
+                onClick={() => setDetailsOpen((prev) => !prev)}
+                className="text-destructive/60 hover:text-destructive/80 inline-flex items-center gap-1 text-xs transition-colors"
+              >
+                <ChevronDownIcon
+                  className={cn(
+                    "size-3 transition-transform",
+                    detailsOpen && "rotate-180",
+                  )}
+                />
+                Technical details
+              </button>
+              {detailsOpen && (
+                <dl className="text-destructive/60 mt-1.5 space-y-0.5 font-mono text-xs">
+                  <div className="flex gap-2">
+                    <dt className="shrink-0">Method:</dt>
+                    <dd className="truncate">{metadata.method}</dd>
+                  </div>
+                  <div className="flex gap-2">
+                    <dt className="shrink-0">Path:</dt>
+                    <dd className="truncate">{metadata.path}</dd>
+                  </div>
+                </dl>
+              )}
+            </div>
+          )}
+        </div>
+
+        {retry && retryable && (
+          <button
+            type="button"
+            onClick={retry}
+            className={cn(
+              "inline-flex shrink-0 items-center gap-1.5 rounded-md border px-2.5 py-1.5 text-xs font-medium",
+              "border-destructive/20 text-destructive hover:bg-destructive/10",
+              "transition-colors",
+            )}
+          >
+            <RotateCcwIcon className="size-3" />
+            Retry
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Icons (inline SVGs — SDK components avoid icon library dependencies)
+// ---------------------------------------------------------------------------
+
+function AlertTriangleIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={className}
+      aria-hidden="true"
+    >
+      <path d="M7.13 2.5a1 1 0 0 1 1.74 0l5.5 9.5A1 1 0 0 1 13.5 13.5h-11a1 1 0 0 1-.87-1.5l5.5-9.5z" />
+      <path d="M8 6v3" />
+      <circle cx="8" cy="11" r="0.5" fill="currentColor" stroke="none" />
+    </svg>
+  );
+}
+
+function ShieldXIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={className}
+      aria-hidden="true"
+    >
+      <path d="M8 1.5l5 2v4c0 3.5-2.5 5.5-5 6.5-2.5-1-5-3-5-6.5v-4l5-2z" />
+      <path d="M6 6.5l4 4M10 6.5l-4 4" />
+    </svg>
+  );
+}
+
+function ChevronDownIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={className}
+      aria-hidden="true"
+    >
+      <path d="M4 6l4 4 4-4" />
+    </svg>
+  );
+}
+
+function RotateCcwIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={className}
+      aria-hidden="true"
+    >
+      <path d="M2 6.5h4v-4" />
+      <path d="M3.5 11.5a5.5 5.5 0 1 0 .5-6l-2 1" />
+    </svg>
+  );
+}

package/src/error/SecretFlowErrorGuide.tsx

@@ -0,0 +1,189 @@
+"use client";
+
+import { useMemo } from "react";
+import { StigmerError, getUserMessage } from "@stigmer/sdk";
+import { cn } from "@stigmer/theme";
+
+export interface SecretFlowErrorGuideProps {
+  /**
+   * The error to inspect. Renders nothing when `null` or when the error
+   * does not match a recognized secret-flow failure pattern.
+   */
+  readonly error: Error | null;
+  readonly className?: string;
+}
+
+interface MissingVariable {
+  readonly serverName: string;
+  readonly variableName: string;
+}
+
+const MISSING_ENV_VAR_PATTERN =
+  /MCP server '([^']+)' requires environment variable '([^']+)'/g;
+
+/**
+ * Parse a `FAILED_PRECONDITION` error message for missing environment
+ * variable declarations. Returns an empty array when the pattern does
+ * not match.
+ */
+function parseMissingVariables(message: string): MissingVariable[] {
+  const results: MissingVariable[] = [];
+  let match: RegExpExecArray | null;
+  while ((match = MISSING_ENV_VAR_PATTERN.exec(message)) !== null) {
+    results.push({ serverName: match[1], variableName: match[2] });
+  }
+  MISSING_ENV_VAR_PATTERN.lastIndex = 0;
+  return results;
+}
+
+function isFailedPreconditionError(error: Error): boolean {
+  return error instanceof StigmerError && error.code === "failed-precondition";
+}
+
+/**
+ * Contextual recovery guidance for secret-flow errors.
+ *
+ * Detects `FAILED_PRECONDITION` errors from execution creation that
+ * indicate missing MCP server environment variables, and renders
+ * actionable guidance alongside the technical error message.
+ *
+ * When the error does not match a secret-flow pattern, renders nothing.
+ * This makes the component composable: try `SecretFlowErrorGuide`
+ * first, fall through to {@link ErrorMessage} for everything else.
+ *
+ * No Console-specific dependencies (no routing, no app-shell imports).
+ * Platform builders embedding Stigmer components get the same guidance.
+ *
+ * @example
+ * ```tsx
+ * {error && (
+ *   <SecretFlowErrorGuide error={error} />
+ *   ?? <ErrorMessage error={error} />
+ * )}
+ *
+ * // Or in a single expression:
+ * <SecretFlowErrorGuide error={error} />
+ * {error && !isSecretFlowError(error) && <ErrorMessage error={error} />}
+ * ```
+ */
+export function SecretFlowErrorGuide({
+  error,
+  className,
+}: SecretFlowErrorGuideProps) {
+  const parsed = useMemo(() => {
+    if (!error || !isFailedPreconditionError(error)) return null;
+    const variables = parseMissingVariables(error.message);
+    if (variables.length === 0) return null;
+    return variables;
+  }, [error]);
+
+  if (!parsed) return null;
+
+  const grouped = useMemo(() => {
+    const map = new Map<string, string[]>();
+    for (const { serverName, variableName } of parsed) {
+      const list = map.get(serverName) ?? [];
+      list.push(variableName);
+      map.set(serverName, list);
+    }
+    return map;
+  }, [parsed]);
+
+  return (
+    <div
+      role="alert"
+      className={cn(
+        "rounded-lg border border-amber-500/30 bg-amber-500/5 p-4",
+        className,
+      )}
+    >
+      <div className="flex items-start gap-3">
+        <KeyIcon className="mt-0.5 size-4 shrink-0 text-amber-600 dark:text-amber-400" />
+
+        <div className="min-w-0 flex-1 space-y-2">
+          <p className="text-sm font-medium text-amber-800 dark:text-amber-200">
+            Missing environment variables
+          </p>
+
+          <div className="space-y-1.5">
+            {Array.from(grouped).map(([server, vars]) => (
+              <div key={server}>
+                <p className="text-xs text-amber-700 dark:text-amber-300">
+                  <span className="font-medium">{server}</span> requires:
+                </p>
+                <ul className="mt-0.5 space-y-0.5">
+                  {vars.map((v) => (
+                    <li
+                      key={v}
+                      className="text-xs font-mono text-amber-800/80 dark:text-amber-200/80 pl-3"
+                    >
+                      {v}
+                    </li>
+                  ))}
+                </ul>
+              </div>
+            ))}
+          </div>
+
+          <div className="border-t border-amber-500/20 pt-2">
+            <p className="text-xs text-amber-700/90 dark:text-amber-300/90">
+              You can provide these values in two ways:
+            </p>
+            <ul className="mt-1 space-y-0.5 text-xs text-amber-700/80 dark:text-amber-300/80">
+              <li className="flex items-start gap-1.5">
+                <span className="mt-px shrink-0">•</span>
+                <span>
+                  Add them to your{" "}
+                  <strong className="font-medium">personal environment</strong>{" "}
+                  in Settings for automatic reuse across sessions.
+                </span>
+              </li>
+              <li className="flex items-start gap-1.5">
+                <span className="mt-px shrink-0">•</span>
+                <span>
+                  Provide them as{" "}
+                  <strong className="font-medium">session variables</strong>{" "}
+                  when sending a message.
+                </span>
+              </li>
+            </ul>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Check whether an error matches the secret-flow missing variable pattern.
+ * Useful for conditional rendering alongside `ErrorMessage`.
+ */
+export function isSecretFlowError(error: Error | null): boolean {
+  if (!error || !isFailedPreconditionError(error)) return false;
+  return parseMissingVariables(error.message).length > 0;
+}
+
+// ---------------------------------------------------------------------------
+// Icons
+// ---------------------------------------------------------------------------
+
+function KeyIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={className}
+      aria-hidden="true"
+    >
+      <circle cx="10.5" cy="5.5" r="3" />
+      <path d="M8.5 7.5L3 13l1.5 1.5" />
+      <path d="M5.5 11l1.5 1.5" />
+    </svg>
+  );
+}

package/src/error/index.ts

@@ -0,0 +1,5 @@
+export { ErrorMessage } from "./ErrorMessage";
+export type { ErrorMessageProps } from "./ErrorMessage";
+
+export { SecretFlowErrorGuide, isSecretFlowError } from "./SecretFlowErrorGuide";
+export type { SecretFlowErrorGuideProps } from "./SecretFlowErrorGuide";