@stigmer/react 0.4.8 → 0.5.0

package/src/skill/useSkillArtifact.ts

@@ -0,0 +1,107 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+import type { SkillFileEntry } from "./useSkillUpload";
+import { fetchAndUnpackArtifact } from "./internal/fetchAndUnpackArtifact";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** Return value of {@link useSkillArtifact}. */
+export interface UseSkillArtifactReturn {
+  /** File entries in the skill package, or `null` while loading/on error. */
+  readonly files: SkillFileEntry[] | null;
+  /** `true` while the artifact is being fetched and unpacked. */
+  readonly isLoading: boolean;
+  /** Error from the fetch/unpack, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Get the text content of a file by path, or `null` if not available. */
+  readonly getFileContent: (path: string) => string | null;
+  /** Re-fetch the artifact from the server. */
+  readonly refetch: () => void;
+}
+
+// ---------------------------------------------------------------------------
+// Hook implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Data hook that fetches and unpacks a skill's ZIP artifact for browsing.
+ *
+ * Uses `stigmer.skill.getArtifact()` with the skill's storage key,
+ * then decompresses the ZIP using `fflate` to expose a file listing
+ * and content retrieval.
+ *
+ * Pass `null` for `artifactStorageKey` to skip fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { skill } = useSkill(org, slug);
+ * const { files, getFileContent, isLoading } = useSkillArtifact(
+ *   skill?.status?.artifactStorageKey ?? null
+ * );
+ *
+ * if (files) {
+ *   const readme = getFileContent("SKILL.md");
+ * }
+ * ```
+ */
+export function useSkillArtifact(
+  artifactStorageKey: string | null,
+): UseSkillArtifactReturn {
+  const stigmer = useStigmer();
+  const [files, setFiles] = useState<SkillFileEntry[] | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const contentMapRef = useRef<Map<string, string>>(new Map());
+  const fetchIdRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    if (!artifactStorageKey) {
+      setFiles(null);
+      setError(null);
+      return;
+    }
+
+    const fetchId = ++fetchIdRef.current;
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const result = await fetchAndUnpackArtifact(stigmer, artifactStorageKey);
+
+      if (fetchIdRef.current !== fetchId) return;
+
+      contentMapRef.current = new Map(result.contentMap);
+      setFiles(result.files);
+    } catch (err) {
+      if (fetchIdRef.current !== fetchId) return;
+      setError(toError(err));
+      setFiles(null);
+    } finally {
+      if (fetchIdRef.current === fetchId) {
+        setIsLoading(false);
+      }
+    }
+  }, [artifactStorageKey, stigmer]);
+
+  useEffect(() => {
+    doFetch();
+  }, [doFetch]);
+
+  const getFileContent = useCallback((path: string): string | null => {
+    return contentMapRef.current.get(path) ?? null;
+  }, []);
+
+  const refetch = useCallback(() => {
+    doFetch();
+  }, [doFetch]);
+
+  return useMemo(
+    () => ({ files, isLoading, error, getFileContent, refetch }),
+    [files, isLoading, error, getFileContent, refetch],
+  );
+}

package/src/skill/useSkillDiff.ts

@@ -0,0 +1,128 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+import { fetchAndUnpackArtifact } from "./internal/fetchAndUnpackArtifact";
+import { computeMultiFileDiff } from "../version-history/computeMultiFileDiff";
+import type { MultiFileDiffResult } from "../version-history/types";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** Return value of {@link useSkillDiff}. */
+export interface UseSkillDiffReturn {
+  /** Multi-file diff result, or `null` while loading / on error / when disabled. */
+  readonly diff: MultiFileDiffResult | null;
+  /** `true` while both artifacts are being fetched, unpacked, and diffed. */
+  readonly isLoading: boolean;
+  /** Error from the fetch/unpack/diff, or `null` when healthy. */
+  readonly error: Error | null;
+}
+
+/** Maximum artifact size (10 MB) to prevent excessive memory usage. */
+const MAX_ARTIFACT_BYTES = 10 * 1024 * 1024;
+
+// ---------------------------------------------------------------------------
+// Hook implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Data hook that fetches two skill version artifacts and computes a
+ * multi-file diff between them.
+ *
+ * Takes two artifact storage keys (obtained from `useSkillVersions.getArtifactKey()`).
+ * Fetches both ZIPs in parallel, unpacks them, and runs `computeMultiFileDiff`
+ * on the extracted text file maps.
+ *
+ * Pass `null` for either key to disable fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { getArtifactKey } = useSkillVersions(org, slug);
+ * const { diff, isLoading } = useSkillDiff(
+ *   getArtifactKey(fromHash),
+ *   getArtifactKey(toHash),
+ * );
+ * ```
+ */
+export function useSkillDiff(
+  fromArtifactKey: string | null,
+  toArtifactKey: string | null,
+): UseSkillDiffReturn {
+  const stigmer = useStigmer();
+  const [diff, setDiff] = useState<MultiFileDiffResult | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const fetchIdRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    if (!fromArtifactKey || !toArtifactKey) {
+      setDiff(null);
+      setError(null);
+      return;
+    }
+
+    const fetchId = ++fetchIdRef.current;
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const [fromResult, toResult] = await Promise.all([
+        fetchAndUnpackArtifact(stigmer, fromArtifactKey),
+        fetchAndUnpackArtifact(stigmer, toArtifactKey),
+      ]);
+
+      if (fetchIdRef.current !== fetchId) return;
+
+      const totalBytes = estimateMapSize(fromResult.contentMap) + estimateMapSize(toResult.contentMap);
+      if (totalBytes > MAX_ARTIFACT_BYTES) {
+        throw new Error(
+          `Combined artifact size (${formatBytes(totalBytes)}) exceeds the ${formatBytes(MAX_ARTIFACT_BYTES)} limit. ` +
+          "Try comparing smaller skill packages.",
+        );
+      }
+
+      const result = computeMultiFileDiff(fromResult.contentMap, toResult.contentMap);
+
+      if (fetchIdRef.current !== fetchId) return;
+      setDiff(result);
+    } catch (err) {
+      if (fetchIdRef.current !== fetchId) return;
+      setError(toError(err));
+      setDiff(null);
+    } finally {
+      if (fetchIdRef.current === fetchId) {
+        setIsLoading(false);
+      }
+    }
+  }, [fromArtifactKey, toArtifactKey, stigmer]);
+
+  useEffect(() => {
+    doFetch();
+  }, [doFetch]);
+
+  return useMemo(
+    () => ({ diff, isLoading, error }),
+    [diff, isLoading, error],
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+function estimateMapSize(map: ReadonlyMap<string, string>): number {
+  let total = 0;
+  for (const value of map.values()) {
+    total += value.length * 2;
+  }
+  return total;
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}

package/src/skill/useSkillDuplicateCheck.ts

@@ -0,0 +1,92 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+import { useStigmer } from "../hooks";
+import { computeArtifactHash } from "./internal/computeArtifactHash";
+
+/** Return value of {@link useSkillDuplicateCheck}. */
+export interface UseSkillDuplicateCheckReturn {
+  /** Whether the uploaded artifact is identical to the current version. */
+  readonly isDuplicate: boolean;
+  /** `true` while the check is in progress. */
+  readonly isChecking: boolean;
+  /**
+   * Run the duplicate check for the given artifact.
+   *
+   * Computes a client-side SHA-256 hash of `artifactBytes`, fetches
+   * the existing skill by `(org, slug)`, and compares against
+   * `status.versionHash`. If they match, sets `isDuplicate` to `true`.
+   *
+   * Returns `true` if the content is a duplicate.
+   */
+  readonly check: (params: {
+    org: string;
+    slug: string;
+    artifactBytes: Uint8Array;
+  }) => Promise<boolean>;
+  /** Reset the check state. */
+  readonly reset: () => void;
+}
+
+/**
+ * Behavior hook that checks whether a skill package's content is
+ * identical to the currently deployed version.
+ *
+ * Uses Web Crypto SHA-256 on the client side and compares against
+ * `SkillStatus.versionHash` from a `getByReference` RPC call.
+ * If the skill doesn't exist yet (NOT_FOUND), the check passes
+ * (not a duplicate).
+ */
+export function useSkillDuplicateCheck(): UseSkillDuplicateCheckReturn {
+  const stigmer = useStigmer();
+  const [isDuplicate, setIsDuplicate] = useState(false);
+  const [isChecking, setIsChecking] = useState(false);
+  const callIdRef = useRef(0);
+
+  const reset = useCallback(() => {
+    callIdRef.current++;
+    setIsDuplicate(false);
+    setIsChecking(false);
+  }, []);
+
+  const check = useCallback(
+    async (params: {
+      org: string;
+      slug: string;
+      artifactBytes: Uint8Array;
+    }): Promise<boolean> => {
+      const callId = ++callIdRef.current;
+      setIsChecking(true);
+      setIsDuplicate(false);
+
+      try {
+        const [clientHash, existingSkill] = await Promise.all([
+          computeArtifactHash(params.artifactBytes),
+          stigmer.skill
+            .getByReference({ org: params.org, slug: params.slug })
+            .catch(() => null),
+        ]);
+
+        if (callIdRef.current !== callId) return false;
+
+        if (!existingSkill) {
+          setIsDuplicate(false);
+          return false;
+        }
+
+        const serverHash = existingSkill.status?.versionHash ?? "";
+        const match = serverHash !== "" && serverHash === clientHash;
+        setIsDuplicate(match);
+        return match;
+      } catch {
+        if (callIdRef.current === callId) setIsDuplicate(false);
+        return false;
+      } finally {
+        if (callIdRef.current === callId) setIsChecking(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { isDuplicate, isChecking, check, reset };
+}

package/src/skill/useSkillUpload.ts

@@ -0,0 +1,231 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+import { parse as parseYaml } from "yaml";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** A single file entry within a skill ZIP package. */
+export interface SkillFileEntry {
+  /** Relative path within the ZIP (e.g. "SKILL.md", "scripts/validate.py"). */
+  readonly path: string;
+  /** Uncompressed file size in bytes. */
+  readonly size: number;
+  /** Whether this entry represents a directory. */
+  readonly isDirectory: boolean;
+}
+
+/** Preview metadata extracted from a validated skill package. */
+export interface SkillUploadPreview {
+  /** Skill name extracted from SKILL.md YAML frontmatter. */
+  readonly name: string;
+  /** Skill description extracted from SKILL.md YAML frontmatter. */
+  readonly description: string;
+  /** All files contained in the ZIP package. */
+  readonly files: SkillFileEntry[];
+  /** Raw SKILL.md content (frontmatter + body). */
+  readonly skillMdContent: string;
+  /** Total uncompressed size of all files in bytes. */
+  readonly totalSize: number;
+}
+
+/** Return value of {@link useSkillUpload}. */
+export interface UseSkillUploadReturn {
+  /** Validated preview of the uploaded package, or `null` before upload. */
+  readonly preview: SkillUploadPreview | null;
+  /** Validation error message, or `null` if valid/not yet uploaded. */
+  readonly validationError: string | null;
+  /** `true` while the file is being read and validated. */
+  readonly isProcessing: boolean;
+  /** Process a file selected by the user (triggers validation). */
+  readonly processFile: (file: File) => Promise<void>;
+  /** Reset to initial state (clear preview and errors). */
+  readonly reset: () => void;
+  /** Raw ZIP bytes ready for push, or `null` before successful validation. */
+  readonly artifact: Uint8Array | null;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const ZIP_MAGIC_BYTES = [0x50, 0x4b, 0x03, 0x04];
+const NAME_MAX_LENGTH = 64;
+const NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+// ---------------------------------------------------------------------------
+// Hook implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Behavior hook for the skill upload workflow.
+ *
+ * Handles file reading, ZIP unpacking, structure validation, and
+ * metadata extraction. Produces a {@link SkillUploadPreview} that
+ * the UI can render, and exposes the raw artifact bytes for pushing.
+ *
+ * Validation rules (Anthropic Agent Skills spec):
+ * - File must be a valid ZIP archive (checked via magic bytes)
+ * - ZIP must contain `SKILL.md` at the root level
+ * - SKILL.md must have YAML frontmatter with a valid `name` field
+ * - Name must be lowercase letters/numbers/hyphens, max 64 chars
+ *
+ * @example
+ * ```tsx
+ * const upload = useSkillUpload();
+ *
+ * const handleDrop = (file: File) => upload.processFile(file);
+ *
+ * if (upload.preview) {
+ *   // Show preview UI
+ *   console.log(upload.preview.name, upload.preview.files);
+ * }
+ *
+ * if (upload.artifact) {
+ *   // Ready to push
+ *   await push({ org: "acme", artifact: upload.artifact });
+ * }
+ * ```
+ */
+export function useSkillUpload(): UseSkillUploadReturn {
+  const [preview, setPreview] = useState<SkillUploadPreview | null>(null);
+  const [validationError, setValidationError] = useState<string | null>(null);
+  const [isProcessing, setIsProcessing] = useState(false);
+  const [artifact, setArtifact] = useState<Uint8Array | null>(null);
+
+  const abortRef = useRef(0);
+
+  const reset = useCallback(() => {
+    abortRef.current++;
+    setPreview(null);
+    setValidationError(null);
+    setIsProcessing(false);
+    setArtifact(null);
+  }, []);
+
+  const processFile = useCallback(async (file: File) => {
+    const callId = ++abortRef.current;
+    setIsProcessing(true);
+    setValidationError(null);
+    setPreview(null);
+    setArtifact(null);
+
+    try {
+      const bytes = new Uint8Array(await file.arrayBuffer());
+
+      if (abortRef.current !== callId) return;
+
+      if (!isZip(bytes)) {
+        setValidationError("File is not a valid ZIP archive");
+        return;
+      }
+
+      const { unzipSync, strFromU8 } = await import("fflate");
+      const unzipped = unzipSync(bytes);
+
+      if (abortRef.current !== callId) return;
+
+      const entries = Object.entries(unzipped);
+      const skillMdEntry = findSkillMd(entries);
+
+      if (!skillMdEntry) {
+        setValidationError("ZIP must contain a SKILL.md file at the root level");
+        return;
+      }
+
+      const skillMdContent = strFromU8(skillMdEntry[1]);
+      const frontmatter = parseFrontmatter(skillMdContent);
+
+      if (!frontmatter) {
+        setValidationError("SKILL.md must have valid YAML frontmatter (---\\n...\\n---)");
+        return;
+      }
+
+      if (!frontmatter.name || typeof frontmatter.name !== "string") {
+        setValidationError("SKILL.md frontmatter must include a 'name' field");
+        return;
+      }
+
+      const name = frontmatter.name;
+      if (name.length > NAME_MAX_LENGTH) {
+        setValidationError(`Skill name must be ${NAME_MAX_LENGTH} characters or fewer`);
+        return;
+      }
+
+      if (!NAME_PATTERN.test(name)) {
+        setValidationError(
+          "Skill name must contain only lowercase letters, numbers, and hyphens, starting with a letter or number",
+        );
+        return;
+      }
+
+      const files: SkillFileEntry[] = entries.map(([path, data]) => ({
+        path,
+        size: data.length,
+        isDirectory: data.length === 0 && path.endsWith("/"),
+      }));
+
+      const totalSize = files.reduce((sum, f) => sum + f.size, 0);
+      const description =
+        typeof frontmatter.description === "string"
+          ? frontmatter.description
+          : "";
+
+      if (abortRef.current !== callId) return;
+
+      setPreview({ name, description, files, skillMdContent, totalSize });
+      setArtifact(bytes);
+    } catch (err) {
+      if (abortRef.current !== callId) return;
+      const message =
+        err instanceof Error ? err.message : "Failed to process file";
+      setValidationError(`Invalid ZIP archive: ${message}`);
+    } finally {
+      if (abortRef.current === callId) {
+        setIsProcessing(false);
+      }
+    }
+  }, []);
+
+  return { preview, validationError, isProcessing, processFile, reset, artifact };
+}
+
+// ---------------------------------------------------------------------------
+// Internal utilities
+// ---------------------------------------------------------------------------
+
+function isZip(bytes: Uint8Array): boolean {
+  if (bytes.length < 4) return false;
+  return (
+    bytes[0] === ZIP_MAGIC_BYTES[0] &&
+    bytes[1] === ZIP_MAGIC_BYTES[1] &&
+    bytes[2] === ZIP_MAGIC_BYTES[2] &&
+    bytes[3] === ZIP_MAGIC_BYTES[3]
+  );
+}
+
+function findSkillMd(
+  entries: [string, Uint8Array][],
+): [string, Uint8Array] | undefined {
+  return entries.find(
+    ([path]) => path === "SKILL.md" || path.match(/^[^/]+\/SKILL\.md$/),
+  );
+}
+
+function parseFrontmatter(content: string): Record<string, unknown> | null {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match) return null;
+
+  try {
+    const parsed = parseYaml(match[1]);
+    if (typeof parsed === "object" && parsed !== null) {
+      return parsed as Record<string, unknown>;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}