@stigmer/react 0.0.36 → 0.0.39

package/src/library/ScopeToggle.tsx

@@ -0,0 +1,121 @@
+"use client";
+
+import { useCallback, useRef } from "react";
+import { cn } from "@stigmer/theme";
+import type { ResourceListScope } from "../search";
+
+export interface ScopeToggleProps {
+  /** The currently selected scope. */
+  readonly value: ResourceListScope;
+  /** Called when the user selects a different scope. */
+  readonly onChange: (scope: ResourceListScope) => void;
+  /** Disables all interaction. */
+  readonly disabled?: boolean;
+  /** Additional CSS classes applied to the root element. */
+  readonly className?: string;
+}
+
+const SCOPE_OPTIONS: readonly {
+  readonly value: ResourceListScope;
+  readonly label: string;
+}[] = [
+  { value: "org", label: "Org" },
+  { value: "all", label: "All" },
+];
+
+/**
+ * Segmented control for toggling resource scope between "Org"
+ * (only the current organization's resources) and "All"
+ * (including public and platform resources).
+ *
+ * Designed for use in Library list headers alongside a search input.
+ * The component is controlled — the consumer owns the `value` state
+ * and handles persistence (e.g., localStorage).
+ *
+ * Implements the WAI-ARIA Radio Group pattern with roving tabindex
+ * for keyboard navigation: Arrow Left/Right moves focus and selects,
+ * Tab enters/exits the group.
+ *
+ * All visual properties flow through `--stgm-*` tokens.
+ *
+ * @example
+ * ```tsx
+ * const [scope, setScope] = useState<ResourceListScope>("org");
+ *
+ * <ScopeToggle value={scope} onChange={setScope} />
+ * ```
+ *
+ * @see {@link ResourceListScope} for the type used by data hooks
+ * @see {@link useAgentList}, {@link useSkillList}, {@link useMcpServerList}
+ */
+export function ScopeToggle({
+  value,
+  onChange,
+  disabled = false,
+  className,
+}: ScopeToggleProps) {
+  const optionRefs = useRef<(HTMLButtonElement | null)[]>([]);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLButtonElement>, index: number) => {
+      let nextIndex: number | null = null;
+
+      if (e.key === "ArrowRight" || e.key === "ArrowDown") {
+        e.preventDefault();
+        nextIndex = (index + 1) % SCOPE_OPTIONS.length;
+      } else if (e.key === "ArrowLeft" || e.key === "ArrowUp") {
+        e.preventDefault();
+        nextIndex =
+          (index - 1 + SCOPE_OPTIONS.length) % SCOPE_OPTIONS.length;
+      }
+
+      if (nextIndex !== null) {
+        optionRefs.current[nextIndex]?.focus();
+        onChange(SCOPE_OPTIONS[nextIndex].value);
+      }
+    },
+    [onChange],
+  );
+
+  return (
+    <div
+      role="radiogroup"
+      aria-label="Resource scope"
+      aria-disabled={disabled || undefined}
+      className={cn(
+        "inline-flex rounded-md bg-muted p-0.5",
+        disabled && "pointer-events-none opacity-50",
+        className,
+      )}
+    >
+      {SCOPE_OPTIONS.map((option, index) => {
+        const isSelected = value === option.value;
+
+        return (
+          <button
+            key={option.value}
+            ref={(el) => {
+              optionRefs.current[index] = el;
+            }}
+            type="button"
+            role="radio"
+            aria-checked={isSelected}
+            tabIndex={isSelected ? 0 : -1}
+            disabled={disabled}
+            onClick={() => onChange(option.value)}
+            onKeyDown={(e) => handleKeyDown(e, index)}
+            className={cn(
+              "cursor-pointer rounded-sm px-3 py-1 text-xs font-medium transition-colors",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+              isSelected
+                ? "bg-background text-foreground shadow-sm"
+                : "text-muted-foreground hover:text-foreground",
+            )}
+          >
+            {option.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/library/detect-skill-package.ts

@@ -0,0 +1,162 @@
+import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+import { ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { parse as parseYaml } from "yaml";
+
+/**
+ * Result of detecting whether an execution artifact is a pushable skill package.
+ *
+ * Uses a discriminated union on the `detected` field — identical pattern
+ * to {@link StigmerResourceDetection} — so consumers can narrow with a
+ * simple `if (result.detected)` check.
+ *
+ * Skill detection is a **parallel** path to YAML resource detection:
+ *
+ * - **YAML detection** (`detectStigmerResource`): Agents, MCP Servers — applied via `apply()`
+ * - **Package detection** (`detectSkillPackage`): Skill packages (directory with SKILL.md) — pushed via `pushFromExecutionArtifact()`
+ */
+export type SkillPackageDetection =
+  | { readonly detected: false }
+  | {
+      /** Discriminant — always `true` when a skill package was detected. */
+      readonly detected: true;
+      /** Skill name extracted from SKILL.md YAML frontmatter. */
+      readonly skillName: string;
+      /** Optional description from SKILL.md frontmatter. */
+      readonly skillDescription: string | undefined;
+      /** Number of files in the package archive. */
+      readonly fileCount: number;
+      /** Relative file paths within the archive (from `ExecutionArtifact.entries`). */
+      readonly entries: readonly string[];
+    };
+
+const NOT_DETECTED: SkillPackageDetection = { detected: false } as const;
+
+const SKILL_MD_ENTRY = "SKILL.md";
+
+/**
+ * Checks whether an execution artifact is a skill package (directory
+ * artifact whose archive contains `SKILL.md`).
+ *
+ * This is a pure, synchronous check that requires no network call — it
+ * inspects the `entries` field populated by the agent runner at ZIP
+ * creation time.
+ *
+ * Returns `false` for:
+ * - FILE artifacts (regardless of name)
+ * - DIRECTORY artifacts without `entries` (older artifacts before this field was added)
+ * - DIRECTORY artifacts whose entries do not include `SKILL.md`
+ *
+ * @param artifact - Artifact from `execution.status.artifacts`.
+ *
+ * @example
+ * ```ts
+ * if (isSkillPackage(artifact)) {
+ *   // Show "Push Skill" CTA
+ * }
+ * ```
+ */
+export function isSkillPackage(artifact: ExecutionArtifact): boolean {
+  return (
+    artifact.kind === ExecutionArtifactKind.DIRECTORY &&
+    artifact.entries.includes(SKILL_MD_ENTRY)
+  );
+}
+
+/**
+ * Detects a skill package and extracts metadata from its SKILL.md content.
+ *
+ * Call this after fetching the SKILL.md content from the ZIP via
+ * `useArtifactContent(executionId, storageKey, "SKILL.md")`. The function
+ * parses the YAML frontmatter to extract `name` and `description`.
+ *
+ * **Resilient by design** — any parse failure, missing field, or unexpected
+ * structure returns `{ detected: false }`. This function never throws.
+ *
+ * @param artifact - The execution artifact (must be a DIRECTORY with SKILL.md in entries).
+ * @param skillMdContent - Raw text content of SKILL.md fetched from the archive.
+ * @returns A discriminated union with skill metadata when detection succeeds.
+ *
+ * @example
+ * ```ts
+ * const { content } = useArtifactContent(executionId, storageKey, "SKILL.md");
+ * const detection = detectSkillPackage(artifact, content);
+ *
+ * if (detection.detected) {
+ *   console.log(`Skill: ${detection.skillName} (${detection.fileCount} files)`);
+ * }
+ * ```
+ *
+ * @see {@link isSkillPackage} for the lightweight check (no content needed)
+ * @see {@link useDetectSkillPackage} for the React hook that automates the full flow
+ */
+export function detectSkillPackage(
+  artifact: ExecutionArtifact,
+  skillMdContent: string,
+): SkillPackageDetection {
+  if (!isSkillPackage(artifact)) {
+    return NOT_DETECTED;
+  }
+
+  const frontmatter = parseSkillFrontmatter(skillMdContent);
+  if (!frontmatter) {
+    return NOT_DETECTED;
+  }
+
+  return {
+    detected: true,
+    skillName: frontmatter.name,
+    skillDescription: frontmatter.description,
+    fileCount: artifact.entries.length,
+    entries: artifact.entries,
+  };
+}
+
+interface SkillFrontmatter {
+  readonly name: string;
+  readonly description: string | undefined;
+}
+
+/**
+ * Parses YAML frontmatter from a SKILL.md file.
+ *
+ * Expects the standard frontmatter format:
+ * ```markdown
+ * ---
+ * name: my-skill-name
+ * description: Optional description
+ * ---
+ * ```
+ *
+ * Returns `null` when the content has no valid frontmatter or the `name`
+ * field is missing/empty.
+ */
+function parseSkillFrontmatter(content: string): SkillFrontmatter | null {
+  const fenceMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fenceMatch) {
+    return null;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(fenceMatch[1]);
+  } catch {
+    return null;
+  }
+
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return null;
+  }
+
+  const obj = parsed as Record<string, unknown>;
+
+  const name = obj.name;
+  if (typeof name !== "string" || name.length === 0) {
+    return null;
+  }
+
+  const description = typeof obj.description === "string" && obj.description.length > 0
+    ? obj.description
+    : undefined;
+
+  return { name, description };
+}

package/src/library/detect-stigmer-resource.ts

@@ -0,0 +1,130 @@
+import { parse as parseYaml } from "yaml";
+
+/**
+ * Resource kinds that the YAML detection logic recognizes.
+ *
+ * These correspond to the Stigmer resource types that can appear as
+ * YAML file artifacts and be applied to an organization via `apply()`:
+ *
+ * - `"Agent"` — agent blueprint (`apiVersion: agentic.stigmer.ai/v1`, `kind: Agent`)
+ * - `"McpServer"` — MCP server definition (`kind: McpServer`)
+ *
+ * Skills are **not** included here — they are package-based (directory
+ * artifacts with SKILL.md) and use a separate detection path via
+ * {@link isSkillPackage} / {@link detectSkillPackage}.
+ */
+export type StigmerResourceKind = "Agent" | "McpServer";
+
+/**
+ * Result of detecting a Stigmer resource in a YAML content string.
+ *
+ * Uses a discriminated union on the `detected` field so consumers
+ * can narrow the type with a simple `if (result.detected)` check.
+ */
+export type StigmerResourceDetection =
+  | { readonly detected: false }
+  | {
+      /** Discriminant — always `true` when a resource was found. */
+      readonly detected: true;
+      /** The `apiVersion` field from the YAML (e.g. `"agentic.stigmer.ai/v1"`). */
+      readonly apiVersion: string;
+      /** The resource kind as it appears in the YAML. */
+      readonly kind: StigmerResourceKind;
+      /** Human-readable label for the resource kind (e.g. `"MCP Server"`). */
+      readonly displayName: string;
+      /** The `metadata.name` field from the YAML. */
+      readonly resourceName: string;
+      /** The `metadata.org` field from the YAML, if present. */
+      readonly resourceOrg: string | undefined;
+    };
+
+const NOT_DETECTED: StigmerResourceDetection = { detected: false } as const;
+
+const KIND_DISPLAY_NAMES: Record<StigmerResourceKind, string> = {
+  Agent: "Agent",
+  McpServer: "MCP Server",
+};
+
+const KNOWN_KINDS = new Set<string>(Object.keys(KIND_DISPLAY_NAMES));
+
+const STIGMER_API_VERSION_PATTERN = /^[a-z]+\.stigmer\.ai\/v\d+$/;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Detects whether a YAML content string represents a Stigmer platform resource.
+ *
+ * Performs a best-effort structural check against the Stigmer resource
+ * convention: a YAML document with `apiVersion` matching `*.stigmer.ai/*`,
+ * a recognized `kind`, and `metadata.name`.
+ *
+ * **Resilient by design** — any parse failure, missing field, or unexpected
+ * structure returns `{ detected: false }`. This function never throws.
+ *
+ * Only the first YAML document is inspected when the content contains
+ * multiple documents separated by `---`.
+ *
+ * @param content - Raw YAML content string (typically from {@link useArtifactContent}).
+ * @returns A discriminated union: `{ detected: true, kind, ... }` when a
+ *   recognized Stigmer resource is found, `{ detected: false }` otherwise.
+ *
+ * @example
+ * ```ts
+ * const result = detectStigmerResource(yamlString);
+ * if (result.detected) {
+ *   console.log(`Found ${result.displayName}: ${result.resourceName}`);
+ * }
+ * ```
+ *
+ * @see {@link useDetectStigmerResource} for the React hook wrapper
+ * @see {@link StigmerResourceKind} for recognized resource kinds
+ */
+export function detectStigmerResource(
+  content: string,
+): StigmerResourceDetection {
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(content);
+  } catch {
+    return NOT_DETECTED;
+  }
+
+  if (!isPlainObject(parsed)) {
+    return NOT_DETECTED;
+  }
+
+  const { apiVersion, kind, metadata } = parsed;
+
+  if (typeof apiVersion !== "string" || !STIGMER_API_VERSION_PATTERN.test(apiVersion)) {
+    return NOT_DETECTED;
+  }
+
+  if (typeof kind !== "string" || !KNOWN_KINDS.has(kind)) {
+    return NOT_DETECTED;
+  }
+
+  if (!isPlainObject(metadata)) {
+    return NOT_DETECTED;
+  }
+
+  const name = metadata.name;
+  if (typeof name !== "string" || name.length === 0) {
+    return NOT_DETECTED;
+  }
+
+  const resourceKind = kind as StigmerResourceKind;
+
+  return {
+    detected: true,
+    apiVersion,
+    kind: resourceKind,
+    displayName: KIND_DISPLAY_NAMES[resourceKind],
+    resourceName: name,
+    resourceOrg:
+      typeof metadata.org === "string" && metadata.org.length > 0
+        ? metadata.org
+        : undefined,
+  };
+}

package/src/library/index.ts

@@ -0,0 +1,42 @@
+export { ScopeToggle } from "./ScopeToggle";
+export type { ScopeToggleProps } from "./ScopeToggle";
+
+export { ResourceListView } from "./ResourceListView";
+export type { ResourceListViewProps } from "./ResourceListView";
+
+export { ResourceCountCard } from "./ResourceCountCard";
+export type { ResourceCountCardProps } from "./ResourceCountCard";
+
+export { detectStigmerResource } from "./detect-stigmer-resource";
+export type {
+  StigmerResourceKind,
+  StigmerResourceDetection,
+} from "./detect-stigmer-resource";
+
+export { useDetectStigmerResource } from "./useDetectStigmerResource";
+
+export {
+  isSkillPackage,
+  detectSkillPackage,
+} from "./detect-skill-package";
+export type { SkillPackageDetection } from "./detect-skill-package";
+
+export { useDetectSkillPackage } from "./useDetectSkillPackage";
+export type { UseDetectSkillPackageReturn } from "./useDetectSkillPackage";
+
+export { parseResourceYaml } from "./parse-resource-yaml";
+export type { ParsedResource } from "./parse-resource-yaml";
+
+export {
+  serializeAgentYaml,
+  serializeMcpServerYaml,
+} from "./serialize-resource-yaml";
+
+export { useApplyResource } from "./useApplyResource";
+export type {
+  UseApplyResourceReturn,
+  ApplyResourceResult,
+  PushSkillParams,
+} from "./useApplyResource";
+
+export type { ResourceListScope } from "../search";