@stigmer/react 0.0.36 → 0.0.39

package/library/ScopeToggle.d.ts

@@ -0,0 +1,38 @@
+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;
+}
+/**
+ * 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 declare function ScopeToggle({ value, onChange, disabled, className, }: ScopeToggleProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=ScopeToggle.d.ts.map

package/library/ScopeToggle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScopeToggle.d.ts","sourceRoot":"","sources":["../../src/library/ScopeToggle.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACtD,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAUD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,QAAQ,EACR,QAAgB,EAChB,SAAS,GACV,EAAE,gBAAgB,2CAiElB"}

package/library/ScopeToggle.js

@@ -0,0 +1,61 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useRef } from "react";
+import { cn } from "@stigmer/theme";
+const SCOPE_OPTIONS = [
+    { 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, }) {
+    const optionRefs = useRef([]);
+    const handleKeyDown = useCallback((e, index) => {
+        let nextIndex = 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 (_jsx("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), children: SCOPE_OPTIONS.map((option, index) => {
+            const isSelected = value === option.value;
+            return (_jsx("button", { 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"), children: option.label }, option.value));
+        }) }));
+}
+//# sourceMappingURL=ScopeToggle.js.map

package/library/ScopeToggle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScopeToggle.js","sourceRoot":"","sources":["../../src/library/ScopeToggle.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AAcpC,MAAM,aAAa,GAGb;IACJ,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE;IAC9B,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE;CAC/B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,WAAW,CAAC,EAC1B,KAAK,EACL,QAAQ,EACR,QAAQ,GAAG,KAAK,EAChB,SAAS,GACQ;IACjB,MAAM,UAAU,GAAG,MAAM,CAA+B,EAAE,CAAC,CAAC;IAE5D,MAAM,aAAa,GAAG,WAAW,CAC/B,CAAC,CAAyC,EAAE,KAAa,EAAE,EAAE;QAC3D,IAAI,SAAS,GAAkB,IAAI,CAAC;QAEpC,IAAI,CAAC,CAAC,GAAG,KAAK,YAAY,IAAI,CAAC,CAAC,GAAG,KAAK,WAAW,EAAE,CAAC;YACpD,CAAC,CAAC,cAAc,EAAE,CAAC;YACnB,SAAS,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC;QACjD,CAAC;aAAM,IAAI,CAAC,CAAC,GAAG,KAAK,WAAW,IAAI,CAAC,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;YACxD,CAAC,CAAC,cAAc,EAAE,CAAC;YACnB,SAAS;gBACP,CAAC,KAAK,GAAG,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC;QAC9D,CAAC;QAED,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACvB,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC;YACvC,QAAQ,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC,EACD,CAAC,QAAQ,CAAC,CACX,CAAC;IAEF,OAAO,CACL,cACE,IAAI,EAAC,YAAY,gBACN,gBAAgB,mBACZ,QAAQ,IAAI,SAAS,EACpC,SAAS,EAAE,EAAE,CACX,uCAAuC,EACvC,QAAQ,IAAI,gCAAgC,EAC5C,SAAS,CACV,YAEA,aAAa,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;YACnC,MAAM,UAAU,GAAG,KAAK,KAAK,MAAM,CAAC,KAAK,CAAC;YAE1C,OAAO,CACL,iBAEE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE;oBACV,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;gBACjC,CAAC,EACD,IAAI,EAAC,QAAQ,EACb,IAAI,EAAC,OAAO,kBACE,UAAU,EACxB,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAC7B,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,EACrC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,EAAE,KAAK,CAAC,EACzC,SAAS,EAAE,EAAE,CACX,2EAA2E,EAC3E,yEAAyE,EACzE,UAAU;oBACR,CAAC,CAAC,yCAAyC;oBAC3C,CAAC,CAAC,6CAA6C,CAClD,YAEA,MAAM,CAAC,KAAK,IAnBR,MAAM,CAAC,KAAK,CAoBV,CACV,CAAC;QACJ,CAAC,CAAC,GACE,CACP,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,79 @@
+import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+/**
+ * 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[];
+};
+/**
+ * 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 declare function isSkillPackage(artifact: ExecutionArtifact): boolean;
+/**
+ * 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 declare function detectSkillPackage(artifact: ExecutionArtifact, skillMdContent: string): SkillPackageDetection;
+//# sourceMappingURL=detect-skill-package.d.ts.map

package/library/detect-skill-package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-skill-package.d.ts","sourceRoot":"","sources":["../../src/library/detect-skill-package.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kEAAkE,CAAC;AAI1G;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAA;CAAE,GAC5B;IACE,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC,CAAC;AAMN;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAKnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,iBAAiB,EAC3B,cAAc,EAAE,MAAM,GACrB,qBAAqB,CAiBvB"}

package/library/detect-skill-package.js

@@ -0,0 +1,113 @@
+import { ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { parse as parseYaml } from "yaml";
+const NOT_DETECTED = { detected: false };
+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) {
+    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, skillMdContent) {
+    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,
+    };
+}
+/**
+ * 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) {
+    const fenceMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!fenceMatch) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(fenceMatch[1]);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    const obj = parsed;
+    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 };
+}
+//# sourceMappingURL=detect-skill-package.js.map

package/library/detect-skill-package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-skill-package.js","sourceRoot":"","sources":["../../src/library/detect-skill-package.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,8DAA8D,CAAC;AACrG,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AA6B1C,MAAM,YAAY,GAA0B,EAAE,QAAQ,EAAE,KAAK,EAAW,CAAC;AAEzE,MAAM,cAAc,GAAG,UAAU,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,cAAc,CAAC,QAA2B;IACxD,OAAO,CACL,QAAQ,CAAC,IAAI,KAAK,qBAAqB,CAAC,SAAS;QACjD,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAC1C,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAA2B,EAC3B,cAAsB;IAEtB,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9B,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,MAAM,WAAW,GAAG,qBAAqB,CAAC,cAAc,CAAC,CAAC;IAC1D,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,IAAI;QACd,SAAS,EAAE,WAAW,CAAC,IAAI;QAC3B,gBAAgB,EAAE,WAAW,CAAC,WAAW;QACzC,SAAS,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM;QAClC,OAAO,EAAE,QAAQ,CAAC,OAAO;KAC1B,CAAC;AACJ,CAAC;AAOD;;;;;;;;;;;;;GAaG;AACH,SAAS,qBAAqB,CAAC,OAAe;IAC5C,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;IAChE,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,GAAG,GAAG,MAAiC,CAAC;IAE9C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,WAAW,GAAG,OAAO,GAAG,CAAC,WAAW,KAAK,QAAQ,IAAI,GAAG,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;QACnF,CAAC,CAAC,GAAG,CAAC,WAAW;QACjB,CAAC,CAAC,SAAS,CAAC;IAEd,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;AAC/B,CAAC"}

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

@@ -0,0 +1,66 @@
+/**
+ * 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;
+};
+/**
+ * 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 declare function detectStigmerResource(content: string): StigmerResourceDetection;
+//# sourceMappingURL=detect-stigmer-resource.d.ts.map

package/library/detect-stigmer-resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-stigmer-resource.d.ts","sourceRoot":"","sources":["../../src/library/detect-stigmer-resource.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,WAAW,CAAC;AAExD;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAA;CAAE,GAC5B;IACE,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C,CAAC;AAiBN;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,GACd,wBAAwB,CA4C1B"}

package/library/detect-stigmer-resource.js

@@ -0,0 +1,77 @@
+import { parse as parseYaml } from "yaml";
+const NOT_DETECTED = { detected: false };
+const KIND_DISPLAY_NAMES = {
+    Agent: "Agent",
+    McpServer: "MCP Server",
+};
+const KNOWN_KINDS = new Set(Object.keys(KIND_DISPLAY_NAMES));
+const STIGMER_API_VERSION_PATTERN = /^[a-z]+\.stigmer\.ai\/v\d+$/;
+function isPlainObject(value) {
+    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) {
+    let parsed;
+    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;
+    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,
+    };
+}
+//# sourceMappingURL=detect-stigmer-resource.js.map

package/library/detect-stigmer-resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-stigmer-resource.js","sourceRoot":"","sources":["../../src/library/detect-stigmer-resource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAwC1C,MAAM,YAAY,GAA6B,EAAE,QAAQ,EAAE,KAAK,EAAW,CAAC;AAE5E,MAAM,kBAAkB,GAAwC;IAC9D,KAAK,EAAE,OAAO;IACd,SAAS,EAAE,YAAY;CACxB,CAAC;AAEF,MAAM,WAAW,GAAG,IAAI,GAAG,CAAS,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAErE,MAAM,2BAA2B,GAAG,6BAA6B,CAAC;AAElE,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAe;IAEf,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IAE9C,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,CAAC,2BAA2B,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QACpF,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACvD,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;IAC3B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,MAAM,YAAY,GAAG,IAA2B,CAAC;IAEjD,OAAO;QACL,QAAQ,EAAE,IAAI;QACd,UAAU;QACV,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE,kBAAkB,CAAC,YAAY,CAAC;QAC7C,YAAY,EAAE,IAAI;QAClB,WAAW,EACT,OAAO,QAAQ,CAAC,GAAG,KAAK,QAAQ,IAAI,QAAQ,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC;YACzD,CAAC,CAAC,QAAQ,CAAC,GAAG;YACd,CAAC,CAAC,SAAS;KAChB,CAAC;AACJ,CAAC"}

package/library/index.d.ts

@@ -0,0 +1,20 @@
+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";
+//# sourceMappingURL=index.d.ts.map

package/library/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/library/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAElE,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,YAAY,EACV,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAEtE,OAAO,EACL,cAAc,EACd,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,YAAY,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAE3E,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,YAAY,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EACL,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EACV,sBAAsB,EACtB,mBAAmB,EACnB,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC"}

package/library/index.js

@@ -0,0 +1,11 @@
+export { ScopeToggle } from "./ScopeToggle";
+export { ResourceListView } from "./ResourceListView";
+export { ResourceCountCard } from "./ResourceCountCard";
+export { detectStigmerResource } from "./detect-stigmer-resource";
+export { useDetectStigmerResource } from "./useDetectStigmerResource";
+export { isSkillPackage, detectSkillPackage, } from "./detect-skill-package";
+export { useDetectSkillPackage } from "./useDetectSkillPackage";
+export { parseResourceYaml } from "./parse-resource-yaml";
+export { serializeAgentYaml, serializeMcpServerYaml, } from "./serialize-resource-yaml";
+export { useApplyResource } from "./useApplyResource";
+//# sourceMappingURL=index.js.map

package/library/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/library/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAMlE,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAEtE,OAAO,EACL,cAAc,EACd,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAGhE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG1D,OAAO,EACL,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}

package/library/parse-resource-yaml.d.ts

@@ -0,0 +1,59 @@
+import type { AgentInput, McpServerInput } from "@stigmer/sdk";
+/**
+ * Result of parsing a Stigmer resource YAML into an SDK input type.
+ *
+ * Discriminated on `kind` so consumers can narrow to the specific input:
+ *
+ * ```ts
+ * const parsed = parseResourceYaml(content, "my-org");
+ * if (parsed.kind === "Agent") {
+ *   // parsed.input is AgentInput
+ * }
+ * ```
+ */
+export type ParsedResource = {
+    readonly kind: "Agent";
+    readonly input: AgentInput;
+} | {
+    readonly kind: "McpServer";
+    readonly input: McpServerInput;
+};
+/**
+ * Parses a Stigmer resource YAML string into the corresponding SDK input
+ * type for use with `stigmer.agent.apply()` or `stigmer.mcpServer.apply()`.
+ *
+ * Handles the conversion from proto-style snake_case YAML field names to
+ * the camelCase TypeScript SDK input types, including nested structures
+ * like `mcp_server_usages`, `sub_agents`, and `env_spec`.
+ *
+ * The `org` parameter **always overrides** `metadata.org` in the YAML.
+ * This matches the UX intent of "Apply to [my-org]" — the user explicitly
+ * chooses the target organization.
+ *
+ * **Throws** with descriptive, user-facing error messages when the YAML
+ * is malformed or missing required fields. These messages are designed
+ * for display in error UI components.
+ *
+ * @param content - Raw YAML content string (typically from {@link useArtifactContent}).
+ * @param org - Target organization slug. Overrides `metadata.org` in the YAML.
+ * @returns A discriminated union with the parsed SDK input.
+ * @throws {Error} When the content is not valid YAML, not a recognized
+ *   Stigmer resource, or is missing required fields.
+ *
+ * @example
+ * ```ts
+ * import { parseResourceYaml } from "@stigmer/react";
+ *
+ * const parsed = parseResourceYaml(yamlContent, "my-org");
+ * if (parsed.kind === "Agent") {
+ *   await stigmer.agent.apply(parsed.input);
+ * } else {
+ *   await stigmer.mcpServer.apply(parsed.input);
+ * }
+ * ```
+ *
+ * @see {@link useApplyResource} for the React hook that wraps this function
+ * @see {@link detectStigmerResource} for lightweight detection without full parsing
+ */
+export declare function parseResourceYaml(content: string, org: string): ParsedResource;
+//# sourceMappingURL=parse-resource-yaml.d.ts.map

package/library/parse-resource-yaml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-resource-yaml.d.ts","sourceRoot":"","sources":["../../src/library/parse-resource-yaml.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EAWf,MAAM,cAAc,CAAC;AAGtB;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,GACV,cAAc,CAyBhB"}