@opengeni/core 0.28.1 → 1.0.0

package/src/domain/skill-imports.ts

@@ -2,6 +2,8 @@ import { createHash } from "node:crypto";
 import type { SkillImportPreview, SkillImportSource } from "@opengeni/contracts";
 import {
   buildPortableSkillArtifact,
+  parsePortableSkillFrontmatter,
+  PORTABLE_SKILL_MAX_FILE_BYTES,
   PORTABLE_SKILL_MAX_FILES,
   PORTABLE_SKILL_MAX_TOTAL_BYTES,
   type SkillLibraryFile,
@@ -17,6 +19,11 @@ export type GitHubSkillTreeEntry = Readonly<{
 }>;
 
 export type GitHubSkillSourceClient = Readonly<{
+  downloadSnapshot?(
+    owner: string,
+    repository: string,
+    slug: string,
+  ): Promise<readonly SkillLibraryFile[]>;
   resolveCommit(owner: string, repository: string, ref: string): Promise<string>;
   listTree(
     owner: string,
@@ -50,12 +57,27 @@ export async function resolveSkillImport(
   client: GitHubSkillSourceClient,
 ): Promise<ResolvedSkillImport> {
   const parsed = parseSkillSource(rawUrl);
+  if (parsed.source === "skills_sh" && client.downloadSnapshot) {
+    const files = await client.downloadSnapshot(parsed.owner, parsed.repository, parsed.skillSlug!);
+    return buildResolvedImport(parsed, files, parsed.skillSlug!, null);
+  }
   const sourceCommit = await client.resolveCommit(parsed.owner, parsed.repository, parsed.ref);
   if (!gitCommit.test(sourceCommit)) {
     throw new HTTPException(422, { message: "GitHub returned an invalid source commit" });
   }
   const tree = await client.listTree(parsed.owner, parsed.repository, sourceCommit);
-  const sourcePath = selectSkillRoot(parsed, tree);
+  // Metadata discovery and the selected artifact share immutable blobs. This
+  // avoids reading SKILL.md twice without caching mutable refs or remote URLs.
+  const blobs = new Map<string, Promise<Uint8Array>>();
+  const readBlob = (sha: string) => {
+    let pending = blobs.get(sha);
+    if (!pending) {
+      pending = client.readBlob(parsed.owner, parsed.repository, sha);
+      blobs.set(sha, pending);
+    }
+    return pending;
+  };
+  const sourcePath = await selectSkillRoot(parsed, tree, readBlob, sourceCommit);
   const entries = skillFilesUnderRoot(tree, sourcePath);
   const declaredBytes = entries.reduce((sum, entry) => sum + (entry.size ?? 0), 0);
   if (entries.length > PORTABLE_SKILL_MAX_FILES) {
@@ -69,11 +91,11 @@ export async function resolveSkillImport(
     });
   }
   const files = await mapConcurrent(entries, maxConcurrentBlobReads, async (entry) => {
+    // Keep provider/network failures distinct from UTF-8 validation failures.
+    const bytes = await readBlob(entry.sha);
     let content: string;
     try {
-      content = new TextDecoder("utf-8", { fatal: true }).decode(
-        await client.readBlob(parsed.owner, parsed.repository, entry.sha),
-      );
+      content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
     } catch {
       throw new HTTPException(422, {
         message: `Skill file is not valid UTF-8 text: ${relativeSkillPath(entry.path, sourcePath)}`,
@@ -81,6 +103,15 @@ export async function resolveSkillImport(
     }
     return { path: relativeSkillPath(entry.path, sourcePath), content };
   });
+  return buildResolvedImport(parsed, files, sourcePath, sourceCommit);
+}
+
+function buildResolvedImport(
+  parsed: ParsedSkillSource,
+  files: readonly SkillLibraryFile[],
+  sourcePath: string,
+  commit: string | null,
+): ResolvedSkillImport {
   let artifact;
   try {
     artifact = buildPortableSkillArtifact(files);
@@ -90,8 +121,25 @@ export async function resolveSkillImport(
     });
   }
   const repositoryUrl = `https://github.com/${parsed.owner}/${parsed.repository}`;
-  const sourceUrl =
-    sourcePath === "."
+  // The existing revision field holds our content digest for registry snapshots;
+  // snapshots do not provide a Git commit or a repository-relative folder path.
+  const sourceCommit = commit ?? artifact.contentSha256;
+  if (
+    !commit &&
+    artifact.name
+      .toLowerCase()
+      .replace(/[\s_]+/g, "-")
+      .replace(/[^a-z0-9-]/g, "")
+      .replace(/-+/g, "-")
+      .replace(/^-|-$/g, "") !== parsed.skillSlug!.toLowerCase()
+  ) {
+    throw new HTTPException(422, {
+      message: "The downloaded skill does not match the requested name",
+    });
+  }
+  const sourceUrl = !commit
+    ? `https://skills.sh/${parsed.owner}/${parsed.repository}/${parsed.skillSlug}`
+    : sourcePath === "."
       ? `${repositoryUrl}/tree/${sourceCommit}`
       : `${repositoryUrl}/tree/${sourceCommit}/${encodeGitHubPath(sourcePath)}`;
   const warnings: string[] = [];
@@ -106,6 +154,7 @@ export async function resolveSkillImport(
   }
   return {
     preview: {
+      markdown: artifact.files.find((file) => file.path === "SKILL.md")?.content,
       source: parsed.source,
       sourceUrl,
       repositoryUrl,
@@ -159,7 +208,12 @@ export function parseSkillSource(rawUrl: string): ParsedSkillSource {
       message: "Skill imports require a credential-free HTTPS URL without a fragment",
     });
   }
-  const segments = url.pathname.split("/").filter(Boolean).map(decodeURIComponent);
+  let segments: string[];
+  try {
+    segments = url.pathname.split("/").filter(Boolean).map(decodeURIComponent);
+  } catch {
+    throw new HTTPException(422, { message: "The Skill URL contains invalid encoding" });
+  }
   if (url.hostname === "skills.sh" || url.hostname === "www.skills.sh") {
     if (segments.length !== 3) {
       throw new HTTPException(422, {
@@ -212,14 +266,14 @@ export function parseSkillSource(rawUrl: string): ParsedSkillSource {
   const ref = segments[3];
   if (!ref) throw new HTTPException(422, { message: "The GitHub URL is missing a revision" });
   const pathSegments = segments.slice(4);
-  if (pathSegments.length === 0) {
+  if (pathSegments.length === 0 && mode === "blob") {
     throw new HTTPException(422, { message: "The GitHub URL is missing a Skill folder" });
   }
-  const requestedPath = normalizeGitHubPath(
+  const folderSegments =
     mode === "blob" && pathSegments.at(-1)?.toLowerCase() === "skill.md"
       ? pathSegments.slice(0, -1)
-      : pathSegments,
-  );
+      : pathSegments;
+  const requestedPath = folderSegments.length === 0 ? "." : normalizeGitHubPath(folderSegments);
   return {
     source: "github",
     owner,
@@ -231,7 +285,12 @@ export function parseSkillSource(rawUrl: string): ParsedSkillSource {
   };
 }
 
-function selectSkillRoot(source: ParsedSkillSource, tree: readonly GitHubSkillTreeEntry[]): string {
+async function selectSkillRoot(
+  source: ParsedSkillSource,
+  tree: readonly GitHubSkillTreeEntry[],
+  readBlob: (sha: string) => Promise<Uint8Array>,
+  sourceCommit: string,
+): Promise<string> {
   const skillFiles = tree
     .filter(
       (entry) =>
@@ -239,7 +298,7 @@ function selectSkillRoot(source: ParsedSkillSource, tree: readonly GitHubSkillTr
         entry.mode !== "120000" &&
         (entry.path === "SKILL.md" || entry.path.endsWith("/SKILL.md")),
     )
-    .map((entry) => entry.path.slice(0, -"/SKILL.md".length) || ".")
+    .map((entry) => (entry.path === "SKILL.md" ? "." : entry.path.slice(0, -"/SKILL.md".length)))
     .sort();
   if (source.requestedPath) {
     const root = source.requestedPath;
@@ -250,9 +309,61 @@ function selectSkillRoot(source: ParsedSkillSource, tree: readonly GitHubSkillTr
     }
     return root;
   }
-  const candidates = source.skillSlug
-    ? skillFiles.filter((path) => path.split("/").at(-1) === source.skillSlug)
-    : skillFiles;
+  let candidates = skillFiles;
+  if (source.skillSlug) {
+    // skills.sh identifies frontmatter names, not necessarily folder basenames
+    // (e.g. vercel-react-best-practices lives in skills/react-best-practices).
+    // Bound discovery as well as the eventual artifact; exact folder URLs avoid
+    // this scan for very large repositories or duplicate names.
+    if (skillFiles.length > PORTABLE_SKILL_MAX_FILES) {
+      throw new HTTPException(422, {
+        message: "Too many Skill candidates; paste the exact GitHub folder URL",
+      });
+    }
+    let metadataBytes = 0;
+    const entriesByPath = new Map(tree.map((entry) => [entry.path, entry]));
+    const matches = await mapConcurrent(skillFiles, maxConcurrentBlobReads, async (root) => {
+      const entry = entriesByPath.get(root === "." ? "SKILL.md" : `${root}/SKILL.md`)!;
+      if ((entry.size ?? 0) > PORTABLE_SKILL_MAX_FILE_BYTES) {
+        throw new HTTPException(422, {
+          message: "Skill metadata is too large; paste the exact GitHub folder URL",
+        });
+      }
+      const bytes = await readBlob(entry.sha);
+      metadataBytes += bytes.byteLength;
+      if (
+        bytes.byteLength > PORTABLE_SKILL_MAX_FILE_BYTES ||
+        metadataBytes > PORTABLE_SKILL_MAX_TOTAL_BYTES
+      ) {
+        throw new HTTPException(422, {
+          message: "Skill metadata is too large; paste the exact GitHub folder URL",
+        });
+      }
+      let markdown: string;
+      try {
+        markdown = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+      } catch {
+        throw new HTTPException(422, {
+          message: "Skill metadata is not valid UTF-8; paste the exact GitHub folder URL",
+        });
+      }
+      return (
+        parsePortableSkillFrontmatter(markdown).name?.toLowerCase() ===
+        source.skillSlug!.toLowerCase()
+      );
+    });
+    candidates = skillFiles.filter((_, index) => matches[index]);
+    if (candidates.length === 0) {
+      // A folder basename is not a skills.sh identity. Never silently import a
+      // different frontmatter name from a stale directory-shaped link.
+      const folders = skillFiles.filter((path) => path.split("/").at(-1) === source.skillSlug);
+      const exactPath =
+        folders.length === 1 ? encodeGitHubPath(folders[0]!) : "<exact-skill-folder-path>";
+      throw new HTTPException(422, {
+        message: `No Skill frontmatter name matches skills.sh slug "${source.skillSlug}"; the link may be stale. Check the current Skill name, or explicitly select the intended Skill using its exact GitHub folder URL: https://github.com/${source.owner}/${source.repository}/tree/${sourceCommit}/${exactPath}`,
+      });
+    }
+  }
   if (candidates.length === 0) {
     throw new HTTPException(422, { message: "No Skill folder with SKILL.md was found" });
   }
@@ -332,13 +443,22 @@ async function mapConcurrent<Input, Output>(
 ): Promise<Output[]> {
   const output = new Array<Output>(values.length);
   let next = 0;
+  let failed = false;
   await Promise.all(
     Array.from({ length: Math.min(concurrency, values.length) }, async () => {
       for (;;) {
+        if (failed) return;
         const index = next;
         next += 1;
         if (index >= values.length) return;
-        output[index] = await map(values[index]!);
+        try {
+          output[index] = await map(values[index]!);
+        } catch (error) {
+          // Let existing reads settle, but do not launch further provider calls
+          // after any peer detects a failed request or an exceeded byte budget.
+          failed = true;
+          throw error;
+        }
       }
     }),
   );

package/src/domain/skill-search.ts

@@ -0,0 +1,221 @@
+import type { Settings } from "@opengeni/config";
+import { pinnedFetch, readResponseJsonBounded } from "@opengeni/network";
+
+export type PublicSkillSearchInput = Readonly<{
+  query: string;
+  limit?: number;
+  owner?: string;
+}>;
+
+export type PublicSkillSearchResult = Readonly<{
+  provider: "skills_sh";
+  query: string;
+  items: readonly Readonly<{
+    id: string;
+    name: string;
+    source: string;
+    skillId: string;
+    url: string;
+    installs: number;
+  }>[];
+  nextCursor: null;
+}>;
+
+export type PublicSkillSearchClient = Readonly<{
+  search(input: PublicSkillSearchInput): Promise<PublicSkillSearchResult>;
+}>;
+
+export type PublicSkillSearchErrorCode =
+  | "invalid_query"
+  | "rate_limited"
+  | "timeout"
+  | "unavailable"
+  | "invalid_response";
+
+export class PublicSkillSearchError extends Error {
+  constructor(
+    readonly code: PublicSkillSearchErrorCode,
+    message: string,
+    readonly retryAfterSeconds: number | null = null,
+  ) {
+    super(message);
+    this.name = "PublicSkillSearchError";
+  }
+}
+
+// Undocumented, unauthenticated compatibility endpoint used by the official CLI.
+// Verified 2026-09-08 against vercel-labs/skills commit
+// 1682051d48c34f5eb135e6475c1a965dce05e820, src/find.ts. This is NOT the documented
+// /api/v1/skills/search API (which requires Vercel OIDC). Keep this contract behind
+// this adapter: no promised pagination/quota, no CLI dependency or credentials.
+const endpoint = "https://skills.sh/api/search";
+const timeoutMs = 10_000;
+const maxResponseBytes = 256 * 1024;
+const maxResults = 20;
+const ownerPattern = /^[a-z0-9](?:[a-z0-9-]{0,38})$/iu;
+const segmentPattern = /^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$/iu;
+
+export function createPublicSkillSearchClient(
+  settings: Settings,
+  fetcher: typeof pinnedFetch = pinnedFetch,
+): PublicSkillSearchClient {
+  return {
+    async search(input) {
+      const query = input.query.trim();
+      const limit = input.limit ?? maxResults;
+      const owner = input.owner?.trim().toLowerCase();
+      if (
+        query.length < 2 ||
+        query.length > 200 ||
+        /[\u0000-\u001f\u007f]/u.test(query) ||
+        !Number.isSafeInteger(limit) ||
+        limit < 1 ||
+        limit > maxResults ||
+        (owner !== undefined && !ownerPattern.test(owner))
+      ) {
+        throw new PublicSkillSearchError("invalid_query", "Invalid public Skill search parameters");
+      }
+      const url = new URL(endpoint);
+      url.searchParams.set("q", query);
+      url.searchParams.set("limit", String(limit));
+      if (owner) url.searchParams.set("owner", owner);
+      const controller = new AbortController();
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const deadline = new Promise<never>((_, reject) => {
+        timer = setTimeout(() => {
+          controller.abort();
+          reject(new PublicSkillSearchError("timeout", "Public Skill search timed out"));
+        }, timeoutMs);
+      });
+      try {
+        return await Promise.race([
+          deadline,
+          (async () => {
+            const response = await fetcher(
+              url,
+              {
+                method: "GET",
+                headers: { accept: "application/json" },
+                credentials: "omit",
+                redirect: "manual",
+                signal: controller.signal,
+              },
+              settings,
+              { label: "Public Skill search", requireHttpsOutsideLocalTest: true },
+            );
+            if (controller.signal.aborted || !response.ok) {
+              void response.body?.cancel().catch(() => undefined);
+              if (controller.signal.aborted) {
+                throw new PublicSkillSearchError("timeout", "Public Skill search timed out");
+              }
+              if (response.status === 429) {
+                throw new PublicSkillSearchError(
+                  "rate_limited",
+                  "Public Skill search is rate limited",
+                  parseRetryAfter(response.headers.get("retry-after")),
+                );
+              }
+              throw new PublicSkillSearchError("unavailable", "Public Skill search is unavailable");
+            }
+            let payload: unknown;
+            try {
+              payload = await readResponseJsonBounded(
+                response,
+                maxResponseBytes,
+                "Public Skill search",
+                {
+                  signal: controller.signal,
+                },
+              );
+            } catch {
+              throw new PublicSkillSearchError(
+                controller.signal.aborted ? "timeout" : "invalid_response",
+                controller.signal.aborted
+                  ? "Public Skill search timed out"
+                  : "Public Skill search returned an invalid response",
+              );
+            }
+            return normalizeResponse(payload, query, limit, owner);
+          })(),
+        ]);
+      } catch (error) {
+        if (error instanceof PublicSkillSearchError) throw error;
+        throw new PublicSkillSearchError(
+          controller.signal.aborted ? "timeout" : "unavailable",
+          controller.signal.aborted
+            ? "Public Skill search timed out"
+            : "Public Skill search is unavailable",
+        );
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+  };
+}
+
+function normalizeResponse(
+  payload: unknown,
+  query: string,
+  limit: number,
+  owner: string | undefined,
+): PublicSkillSearchResult {
+  const invalid = () =>
+    new PublicSkillSearchError(
+      "invalid_response",
+      "Public Skill search returned an invalid response",
+    );
+  if (!isRecord(payload) || !Array.isArray(payload.skills) || payload.skills.length > maxResults) {
+    throw invalid();
+  }
+  const seen = new Set<string>();
+  const items: PublicSkillSearchResult["items"][number][] = [];
+  for (const skill of payload.skills) {
+    if (!isRecord(skill) || typeof skill.id !== "string" || typeof skill.source !== "string")
+      throw invalid();
+    const parts = skill.id.split("/");
+    // Website-hosted skills cannot use our GitHub import flow. Their presence
+    // must not discard the supported results in the same response.
+    if (parts.length === 2 && skill.source === parts[0]) continue;
+    if (
+      parts.length !== 3 ||
+      !ownerPattern.test(parts[0]!) ||
+      !parts.every((part) => segmentPattern.test(part)) ||
+      skill.source !== parts.slice(0, 2).join("/") ||
+      (skill.skillId !== undefined && skill.skillId !== parts[2]) ||
+      typeof skill.name !== "string" ||
+      !skill.name.trim() ||
+      skill.name.length > 200 ||
+      /[\u0000-\u001f\u007f]/u.test(skill.name) ||
+      typeof skill.installs !== "number" ||
+      !Number.isSafeInteger(skill.installs) ||
+      skill.installs < 0 ||
+      (owner !== undefined && parts[0]!.toLowerCase() !== owner)
+    )
+      throw invalid();
+    if (seen.has(skill.id)) continue;
+    seen.add(skill.id);
+    items.push({
+      id: skill.id,
+      name: skill.name.trim(),
+      source: skill.source,
+      skillId: parts[2]!,
+      url: `https://skills.sh/${parts.map(encodeURIComponent).join("/")}`,
+      installs: skill.installs,
+    });
+  }
+  return { provider: "skills_sh", query, items: items.slice(0, limit), nextCursor: null };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseRetryAfter(value: string | null): number | null {
+  if (value === null) return null;
+  if (/^\d+$/u.test(value)) {
+    const seconds = Number(value);
+    return Number.isSafeInteger(seconds) ? seconds : null;
+  }
+  const date = Date.parse(value);
+  return Number.isFinite(date) ? Math.max(0, Math.ceil((date - Date.now()) / 1000)) : null;
+}

package/src/domain/skills.ts

@@ -0,0 +1,104 @@
+import type {
+  SkillFile,
+  SkillInstallInput,
+  SkillRevisionInput,
+  SkillSaveInput,
+  SkillRemoveInput,
+} from "@opengeni/contracts";
+import { validateSkillTextFiles } from "@opengeni/contracts";
+import { buildPortableSkillArtifact } from "@opengeni/runtime/skill-library";
+import {
+  applySkillLifecycle,
+  listSkillRecords,
+  skillFilesContentHash,
+  type Database,
+  type SkillReadContext,
+} from "@opengeni/db";
+export { replayPortableSkillInstall } from "@opengeni/db";
+
+/** Canonical text-only folder; rejects invalid Unicode before PostgreSQL conversion. */
+export function validateSkillFiles(files: readonly SkillFile[]): SkillFile[] {
+  validateSkillTextFiles(files);
+  const result = files.map(({ path, content }) => ({ path, content }));
+  if (!result.some((file) => file.path === "SKILL.md" && file.content.trim()))
+    throw new Error("Skill requires nonempty SKILL.md");
+  return result.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+
+/** Separate from the historical SKILL.md hash, which must never be rewritten. */
+export function skillBundleHash(files: readonly SkillFile[]): string {
+  return skillFilesContentHash(validateSkillFiles(files));
+}
+
+export const listSkills = listSkillRecords;
+export async function removeSkill(db: Database, input: SkillRemoveInput) {
+  const { accountId, workspaceId, actor, ...request } = input;
+  return applySkillLifecycle(
+    db,
+    { accountId, workspaceId, actor },
+    { ...request, operation: "remove" },
+  );
+}
+export async function readSkill(
+  db: Database,
+  context: SkillReadContext,
+  skillId: string,
+  revisionId?: string,
+) {
+  return (
+    (
+      await listSkillRecords(db, context, {
+        skillId,
+        ...(revisionId ? { revisionId } : {}),
+        limit: 1,
+      })
+    )[0] ?? null
+  );
+}
+export async function saveSkill(db: Database, input: SkillSaveInput) {
+  const { accountId, workspaceId, actor, ...request } = input;
+  const artifact = buildPortableSkillArtifact(validateSkillFiles(input.files));
+  return applySkillLifecycle(
+    db,
+    { accountId, workspaceId, actor },
+    {
+      ...request,
+      operation: "save",
+      files: artifact.files,
+      title: artifact.name,
+      description: artifact.description,
+    },
+  );
+}
+export async function installSkill(db: Database, input: SkillInstallInput) {
+  const { accountId, workspaceId, actor, ...request } = input;
+  return applySkillLifecycle(
+    db,
+    { accountId, workspaceId, actor },
+    { ...request, operation: "install" },
+  );
+}
+export async function approveSkill(db: Database, input: SkillRevisionInput) {
+  const { accountId, workspaceId, actor, ...request } = input;
+  return applySkillLifecycle(
+    db,
+    { accountId, workspaceId, actor },
+    { ...request, operation: "approve" },
+  );
+}
+export async function rejectSkill(db: Database, input: SkillRevisionInput) {
+  const { accountId, workspaceId, actor, ...request } = input;
+  return applySkillLifecycle(
+    db,
+    { accountId, workspaceId, actor },
+    { ...request, operation: "reject" },
+  );
+}
+export async function restoreSkill(db: Database, input: SkillRevisionInput) {
+  const { accountId, workspaceId, actor, ...request } = input;
+  return applySkillLifecycle(
+    db,
+    { accountId, workspaceId, actor },
+    { ...request, operation: "restore" },
+  );
+}