@stigmer/react 0.4.8 → 0.5.1

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

@@ -0,0 +1,160 @@
+import type { AgentWizardData } from "../../agent/steps/types";
+import type { ResourceTemplate } from "./types";
+
+/**
+ * Built-in agent templates shipped with the SDK.
+ *
+ * Each template pre-fills the agent creation wizard with a curated
+ * set of instructions, name, and description. Users can customize
+ * every field after selection — templates are starting points, not
+ * constraints.
+ *
+ * Platform builders can pass their own template arrays to the
+ * gallery; these built-in templates are a convenience default.
+ */
+export const AGENT_TEMPLATES: readonly ResourceTemplate<AgentWizardData>[] = [
+  {
+    id: "customer-support",
+    name: "Customer Support Agent",
+    description:
+      "A support agent that handles customer inquiries with empathy, follows escalation procedures, and maintains a professional tone.",
+    category: "customer-support",
+    tags: ["support", "helpdesk", "tickets", "customer"],
+    data: {
+      name: "Customer Support Agent",
+      description:
+        "Handles customer inquiries, troubleshoots issues, and escalates when necessary.",
+      instructions: `You are a customer support agent. Your role is to help customers resolve their issues efficiently and empathetically.
+
+## Guidelines
+
+- **Tone:** Professional, friendly, and patient. Acknowledge the customer's frustration before troubleshooting.
+- **Scope:** Answer questions about the product, troubleshoot common issues, and guide customers through solutions step by step.
+- **Escalation:** If you cannot resolve the issue within your capabilities, clearly explain what you've tried and escalate to a human agent with a summary of the conversation.
+- **Privacy:** Never ask for or store sensitive information like passwords or payment details. Direct customers to secure channels for sensitive operations.
+
+## Response Format
+
+1. Acknowledge the customer's issue
+2. Ask clarifying questions if needed
+3. Provide a step-by-step solution
+4. Confirm the issue is resolved or escalate`,
+    },
+  },
+  {
+    id: "code-review",
+    name: "Code Review Agent",
+    description:
+      "Reviews pull requests and code changes with a focus on correctness, maintainability, and adherence to coding standards.",
+    category: "code-review",
+    tags: ["code", "review", "pull-request", "engineering"],
+    data: {
+      name: "Code Review Agent",
+      description:
+        "Reviews code changes for correctness, maintainability, and style consistency.",
+      instructions: `You are a code reviewer. Your role is to review code changes and provide constructive, actionable feedback.
+
+## Review Priorities (in order)
+
+1. **Correctness** — Does the code do what it claims? Are there edge cases, off-by-one errors, or logic flaws?
+2. **Security** — Are there injection vulnerabilities, auth bypasses, or data leaks?
+3. **Maintainability** — Is the code readable? Would a new team member understand it in under 5 minutes?
+4. **Performance** — Are there obvious performance issues (N+1 queries, unnecessary allocations, blocking calls)?
+5. **Style** — Does it follow the project's conventions?
+
+## Feedback Format
+
+- Be specific: reference line numbers and variable names.
+- Explain *why* something is a problem, not just *what* to change.
+- Distinguish between blockers (must fix), suggestions (should consider), and nits (optional polish).
+- Acknowledge what the author did well.`,
+    },
+  },
+  {
+    id: "data-analysis",
+    name: "Data Analysis Agent",
+    description:
+      "Analyzes datasets, generates insights, and presents findings with clear explanations and visualizations.",
+    category: "data-analysis",
+    tags: ["data", "analytics", "insights", "reporting"],
+    data: {
+      name: "Data Analysis Agent",
+      description:
+        "Analyzes data, identifies patterns, and presents actionable insights.",
+      instructions: `You are a data analysis agent. Your role is to help users understand their data by identifying patterns, anomalies, and actionable insights.
+
+## Guidelines
+
+- **Clarity over complexity:** Explain findings in plain language before diving into technical details. Not every user is a data scientist.
+- **Statistical rigor:** When making claims about trends or correlations, state the confidence level and sample size. Distinguish correlation from causation.
+- **Visualization:** When appropriate, suggest or generate charts and tables that make the data story clear. Choose the right chart type for the data relationship being shown.
+- **Assumptions:** State your assumptions explicitly. If the data is incomplete or ambiguous, say so rather than guessing.
+
+## Response Structure
+
+1. Summary of the key finding (one sentence)
+2. Supporting evidence with specific numbers
+3. Recommended next steps or questions to investigate further`,
+    },
+  },
+  {
+    id: "content-writer",
+    name: "Content Writer Agent",
+    description:
+      "Writes and edits content with consistent style, tone, and formatting across different content types.",
+    category: "content",
+    tags: ["writing", "content", "copywriting", "editing"],
+    data: {
+      name: "Content Writer Agent",
+      description:
+        "Creates and edits written content with consistent style and tone.",
+      instructions: `You are a content writing agent. Your role is to produce clear, engaging, and well-structured written content.
+
+## Writing Principles
+
+- **Audience-first:** Adapt vocabulary, depth, and tone to the target audience. Technical docs for developers differ from blog posts for general readers.
+- **Structure:** Use headings, short paragraphs, and bullet points for scannability. Front-load the most important information.
+- **Voice:** Active voice by default. Concise sentences. Avoid filler words and unnecessary qualifiers.
+- **Accuracy:** Do not invent facts, statistics, or quotes. If you are uncertain, say so.
+
+## Content Types
+
+- Blog posts: informative, engaging, SEO-aware structure
+- Documentation: precise, task-oriented, with code examples where relevant
+- Marketing copy: benefit-focused, clear call-to-action
+- Internal communications: concise, action-oriented
+
+## Editing Mode
+
+When editing existing content, preserve the author's voice while improving clarity and flow. Explain your changes.`,
+    },
+  },
+  {
+    id: "devops-assistant",
+    name: "DevOps Assistant Agent",
+    description:
+      "Assists with infrastructure operations, incident response, and deployment workflows.",
+    category: "devops",
+    tags: ["devops", "infrastructure", "deployment", "incident", "sre"],
+    data: {
+      name: "DevOps Assistant Agent",
+      description:
+        "Assists with infrastructure operations, incident triage, and deployment workflows.",
+      instructions: `You are a DevOps assistant agent. Your role is to help engineering teams with infrastructure operations, incident response, and deployment workflows.
+
+## Capabilities
+
+- **Incident triage:** Analyze alerts, logs, and metrics to identify the likely root cause. Prioritize by blast radius and customer impact.
+- **Runbook execution:** Follow documented runbooks step by step. If a step fails or produces unexpected output, pause and report rather than improvising.
+- **Deployment support:** Guide users through deployment checklists, validate configurations, and monitor rollout health.
+- **Infrastructure queries:** Answer questions about resource configurations, service dependencies, and architecture topology.
+
+## Safety Rules
+
+- **Never execute destructive operations** (delete, force-push, scale-to-zero) without explicit human confirmation.
+- **Always verify the target environment** (staging vs production) before any operation.
+- **Prefer read-only operations** when gathering information. Only suggest write operations when the user requests a change.
+- **Escalate uncertainty:** If you are not confident in a diagnosis or action, say so and recommend involving a human operator.`,
+    },
+  },
+];

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

@@ -0,0 +1,7 @@
+// Types
+export type { ResourceTemplate, TemplateCategory } from "./types";
+export { TEMPLATE_CATEGORY_LABELS } from "./types";
+
+// Static template data
+export { AGENT_TEMPLATES } from "./agent-templates";
+export { MCP_SERVER_TEMPLATES } from "./mcp-server-templates";

package/src/resource-creation/templates/mcp-server-templates.ts

@@ -0,0 +1,106 @@
+import type { McpServerWizardData } from "../../mcp-server/steps/types";
+import type { ResourceTemplate } from "./types";
+
+/**
+ * Built-in MCP server templates shipped with the SDK.
+ *
+ * Each template pre-fills the MCP server creation wizard with a
+ * curated transport configuration, environment variable declarations,
+ * and descriptive metadata. Users can customize every field after
+ * selection.
+ *
+ * Platform builders can pass their own template arrays to the
+ * gallery; these built-in templates are a convenience default.
+ */
+export const MCP_SERVER_TEMPLATES: readonly ResourceTemplate<McpServerWizardData>[] =
+  [
+    {
+      id: "github",
+      name: "GitHub",
+      description:
+        "Connect to the GitHub API for repository management, issue tracking, pull requests, and code search.",
+      category: "integration",
+      tags: ["github", "git", "repository", "api", "code"],
+      data: {
+        name: "GitHub",
+        description:
+          "GitHub API integration for repository management, issues, pull requests, and code search.",
+        transportType: "http",
+        httpUrl: "https://api.githubcopilot.com",
+        env: [
+          {
+            key: "GITHUB_TOKEN",
+            description:
+              "GitHub personal access token with appropriate scopes.",
+            isSecret: true,
+            optional: false,
+          },
+        ],
+      },
+    },
+    {
+      id: "slack",
+      name: "Slack",
+      description:
+        "Connect to the Slack API for sending messages, managing channels, and reading conversation history.",
+      category: "integration",
+      tags: ["slack", "messaging", "chat", "communication"],
+      data: {
+        name: "Slack",
+        description:
+          "Slack API integration for messaging, channel management, and conversation history.",
+        transportType: "http",
+        httpUrl: "https://slack.com/api/mcp",
+        env: [
+          {
+            key: "SLACK_BOT_TOKEN",
+            description: "Slack Bot User OAuth token (xoxb-...).",
+            isSecret: true,
+            optional: false,
+          },
+        ],
+      },
+    },
+    {
+      id: "postgresql",
+      name: "PostgreSQL",
+      description:
+        "Connect to a PostgreSQL database for querying, schema inspection, and data management.",
+      category: "integration",
+      tags: ["postgres", "postgresql", "database", "sql", "data"],
+      data: {
+        name: "PostgreSQL",
+        description:
+          "PostgreSQL database connection for querying, schema inspection, and data management.",
+        transportType: "stdio",
+        stdioCommand: "npx",
+        stdioArgs: "-y @modelcontextprotocol/server-postgres",
+        env: [
+          {
+            key: "DATABASE_URL",
+            description:
+              "PostgreSQL connection string (e.g. postgresql://user:pass@host:5432/db).",
+            isSecret: true,
+            optional: false,
+          },
+        ],
+      },
+    },
+    {
+      id: "filesystem",
+      name: "Filesystem",
+      description:
+        "Provide read and write access to a local directory for file management and content operations.",
+      category: "general",
+      tags: ["filesystem", "files", "local", "directory"],
+      data: {
+        name: "Filesystem",
+        description:
+          "Local filesystem access for reading, writing, and managing files within a directory.",
+        transportType: "stdio",
+        stdioCommand: "npx",
+        stdioArgs:
+          "-y @modelcontextprotocol/server-filesystem /path/to/directory",
+      },
+    },
+  ];

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

@@ -0,0 +1,64 @@
+/**
+ * Template categories for grouping resource templates in the gallery.
+ *
+ * Each category maps to a common use-case domain. The gallery renders
+ * these as filterable tabs. Platform builders can use the same
+ * categories or extend with custom values if they define their own
+ * template arrays.
+ */
+export type TemplateCategory =
+  | "customer-support"
+  | "code-review"
+  | "data-analysis"
+  | "devops"
+  | "content"
+  | "integration"
+  | "general";
+
+/**
+ * Human-readable labels for template categories.
+ *
+ * Used by the gallery UI for tab labels and screen readers.
+ * Exported so platform builders can reuse or extend them.
+ */
+export const TEMPLATE_CATEGORY_LABELS: Record<TemplateCategory, string> = {
+  "customer-support": "Customer Support",
+  "code-review": "Code Review",
+  "data-analysis": "Data Analysis",
+  devops: "DevOps",
+  content: "Content",
+  integration: "Integration",
+  general: "General",
+};
+
+/**
+ * A pre-built resource configuration that seeds a creation wizard.
+ *
+ * Generic over `TData` — the wizard's accumulated form state type.
+ * For agents, `TData` is `AgentWizardData`; for MCP servers,
+ * `TData` is `McpServerWizardData`.
+ *
+ * `data` is `Partial<TData>`: only the fields the template wants to
+ * pre-fill. The wizard merges this with its default empty state via
+ * `{ ...createInitialWizardData(), ...template.data }`.
+ *
+ * @typeParam TData - The wizard's accumulated form data shape.
+ */
+export interface ResourceTemplate<TData> {
+  /** Stable template identifier (unique within a resource kind). */
+  readonly id: string;
+  /** Human-readable template name displayed in the gallery card. */
+  readonly name: string;
+  /** Short description of what this template sets up. */
+  readonly description: string;
+  /** Category for gallery filtering. */
+  readonly category: TemplateCategory;
+  /** Searchable tags for the gallery's text search. */
+  readonly tags?: readonly string[];
+  /**
+   * Partial wizard data to merge with defaults when the user
+   * selects this template. Only fields that the template wants
+   * to pre-fill are included.
+   */
+  readonly data: Partial<TData>;
+}

package/src/resource-creation/types.ts

@@ -0,0 +1,105 @@
+import type { ReactNode } from "react";
+
+// ---------------------------------------------------------------------------
+// Shared form entry types — reusable across all resource creation wizards
+// ---------------------------------------------------------------------------
+
+/** A single env var declaration entry in a wizard form. */
+export interface EnvVarEntry {
+  /** Environment variable name (e.g. GITHUB_TOKEN). */
+  readonly key: string;
+  /** Human-readable description. */
+  readonly description: string;
+  /** Whether this variable holds a secret value. */
+  readonly isSecret: boolean;
+  /** Whether the variable is optional. */
+  readonly optional: boolean;
+}
+
+/** A generic key-value pair entry for wizard forms (e.g. HTTP headers). */
+export interface KeyValueEntry {
+  /** The key (e.g. header name). */
+  readonly key: string;
+  /** The value (e.g. header value). */
+  readonly value: string;
+}
+
+// ---------------------------------------------------------------------------
+// Wizard step definition — describes a single step in the wizard
+// ---------------------------------------------------------------------------
+
+/**
+ * Defines a wizard step's metadata and validation logic.
+ *
+ * Generic over `TData` — the accumulated form state type that flows
+ * through all steps. Each step's `validate` function receives the full
+ * accumulated state and returns an error message or `null` if valid.
+ *
+ * @typeParam TData - Shape of the wizard's accumulated form data.
+ */
+export interface WizardStepDef<TData> {
+  /** Stable step identifier (used as key and for navigation). */
+  readonly id: string;
+  /** Human-readable step label displayed in the step indicator. */
+  readonly label: string;
+  /**
+   * Validates the current data before allowing navigation to the next step.
+   * Returns a descriptive error string if invalid, or `null` if the step
+   * passes validation.
+   *
+   * When omitted, the step is always considered valid.
+   */
+  readonly validate?: (data: TData) => string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Wizard state — the internal state managed by useWizardState
+// ---------------------------------------------------------------------------
+
+/** Internal state shape for the wizard reducer. */
+export interface WizardState<TData> {
+  /** Zero-based index of the currently active step. */
+  readonly currentStepIndex: number;
+  /** Accumulated form data across all steps. */
+  readonly data: TData;
+  /** Validation error for the current step, or `null` when valid. */
+  readonly validationError: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// WizardShell props — the reusable wizard layout component
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for {@link WizardShell} — the resource-agnostic wizard layout.
+ *
+ * Renders a step indicator, content area, and navigation footer.
+ * The content for each step is provided via `children` — the wizard
+ * shell does not know about step-specific rendering.
+ */
+export interface WizardShellProps {
+  /** Step definitions for the progress indicator (only `id` and `label` are used for rendering). */
+  readonly steps: readonly { readonly id: string; readonly label: string }[];
+  /** Zero-based index of the currently active step. */
+  readonly currentStepIndex: number;
+  /** Content to render in the main area (the active step's UI). */
+  readonly children: ReactNode;
+  /** Label for the final step's action button (e.g. "Create agent"). */
+  readonly submitLabel: string;
+  /** Whether the submit action is currently in progress. */
+  readonly isSubmitting?: boolean;
+  /** Whether the "Next" / submit button should be disabled. */
+  readonly canGoNext?: boolean;
+  /** Whether the "Back" button should be shown. */
+  readonly canGoBack?: boolean;
+  /** Called when the user clicks "Next" or the submit button. */
+  readonly onNext: () => void;
+  /** Called when the user clicks "Back". */
+  readonly onBack: () => void;
+  /** Called when a completed step is clicked in the indicator (backward jump). */
+  readonly onGoToStep?: (index: number) => void;
+  /** Called when the user cancels the wizard entirely. */
+  readonly onCancel?: () => void;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}

package/src/resource-creation/useTemplateFilter.ts

@@ -0,0 +1,117 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import type { ResourceTemplate, TemplateCategory } from "./templates/types";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** Options for {@link useTemplateFilter}. */
+export interface UseTemplateFilterOptions<TData> {
+  /** The full set of templates to filter. */
+  readonly templates: readonly ResourceTemplate<TData>[];
+}
+
+/** Return value of {@link useTemplateFilter}. */
+export interface UseTemplateFilterReturn<TData> {
+  /** Templates matching the current search query and active category. */
+  readonly filtered: readonly ResourceTemplate<TData>[];
+  /** Current search query string. */
+  readonly query: string;
+  /** Update the search query. */
+  readonly setQuery: (query: string) => void;
+  /** Currently active category filter, or `null` for "All". */
+  readonly activeCategory: TemplateCategory | null;
+  /** Set the active category filter. Pass `null` to show all. */
+  readonly setActiveCategory: (category: TemplateCategory | null) => void;
+  /** Deduplicated, sorted list of categories present in the template set. */
+  readonly availableCategories: readonly TemplateCategory[];
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Headless hook for filtering and searching a set of resource templates.
+ *
+ * Provides category tab state, text search across name/description/tags,
+ * and the filtered result set. Fully memoized — only recalculates when
+ * inputs change.
+ *
+ * Platform builders can use this hook with their own rendering; the
+ * styled `TemplateGallery` component uses it internally.
+ *
+ * @typeParam TData - The wizard data shape (e.g. `AgentWizardData`).
+ *
+ * @example
+ * ```tsx
+ * const { filtered, query, setQuery, activeCategory, setActiveCategory, availableCategories } =
+ *   useTemplateFilter({ templates: AGENT_TEMPLATES });
+ *
+ * // Render your own gallery UI using `filtered`
+ * ```
+ */
+export function useTemplateFilter<TData>(
+  options: UseTemplateFilterOptions<TData>,
+): UseTemplateFilterReturn<TData> {
+  const { templates } = options;
+
+  const [query, setQueryRaw] = useState("");
+  const [activeCategory, setActiveCategory] = useState<TemplateCategory | null>(
+    null,
+  );
+
+  const setQuery = useCallback((q: string) => {
+    setQueryRaw(q);
+  }, []);
+
+  const availableCategories = useMemo(() => {
+    const seen = new Set<TemplateCategory>();
+    for (const t of templates) {
+      seen.add(t.category);
+    }
+    const sorted = [...seen].sort();
+    return sorted;
+  }, [templates]);
+
+  const filtered = useMemo(() => {
+    let result: readonly ResourceTemplate<TData>[] = templates;
+
+    if (activeCategory) {
+      result = result.filter((t) => t.category === activeCategory);
+    }
+
+    const trimmed = query.trim().toLowerCase();
+    if (trimmed) {
+      result = result.filter((t) => {
+        const haystack = [t.name, t.description, ...(t.tags ?? [])]
+          .join(" ")
+          .toLowerCase();
+        return haystack.includes(trimmed);
+      });
+    }
+
+    return result;
+  }, [templates, activeCategory, query]);
+
+  return useMemo(
+    () => ({
+      filtered,
+      query,
+      setQuery,
+      activeCategory,
+      setActiveCategory,
+      availableCategories,
+    }),
+    [
+      filtered,
+      query,
+      setQuery,
+      activeCategory,
+      setActiveCategory,
+      availableCategories,
+    ],
+  );
+}