@skilltap/core 0.4.4 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilltap/core",
-  "version": "0.4.4",
+  "version": "0.5.2",
   "description": "Core library for skilltap — agent skill management",
   "type": "module",
   "license": "MIT",

package/src/config.ts

@@ -92,7 +92,11 @@ enabled = ["skills.sh"]
 # name = "my-org"
 # url = "https://skills.example.com"
 
-# Tap definitions (repeatable section)
+# Built-in tap: the official skilltap-skills collection.
+# Set to false to opt out of the built-in tap entirely.
+builtin_tap = true
+
+# Additional tap definitions (repeatable section)
 # [[taps]]
 # name = "home"
 # url = "https://gitea.example.com/nathan/my-skills-tap"

package/src/frontmatter.test.ts

@@ -0,0 +1,85 @@
+import { describe, test, expect } from "bun:test";
+import { parseSkillFrontmatter } from "./frontmatter";
+
+describe("parseSkillFrontmatter", () => {
+  test("parses simple single-line values", () => {
+    const content = `---
+name: my-skill
+description: A short description
+license: MIT
+---
+`;
+    const result = parseSkillFrontmatter(content);
+    expect(result).toEqual({
+      name: "my-skill",
+      description: "A short description",
+      license: "MIT",
+    });
+  });
+
+  test("returns null when no frontmatter", () => {
+    expect(parseSkillFrontmatter("No frontmatter here")).toBeNull();
+  });
+
+  test("coerces boolean values", () => {
+    const result = parseSkillFrontmatter("---\nfoo: true\nbar: false\n---\n");
+    expect(result?.foo).toBe(true);
+    expect(result?.bar).toBe(false);
+  });
+
+  test("coerces numeric values", () => {
+    const result = parseSkillFrontmatter("---\ncount: 42\n---\n");
+    expect(result?.count).toBe(42);
+  });
+
+  test("parses folded block scalar (>)", () => {
+    const content = `---
+name: my-skill
+description: >
+  This is a long description
+  that spans multiple lines.
+license: MIT
+---
+`;
+    const result = parseSkillFrontmatter(content);
+    expect(result?.description).toBe("This is a long description that spans multiple lines.");
+    expect(result?.license).toBe("MIT");
+  });
+
+  test("parses literal block scalar (|)", () => {
+    const content = `---
+name: my-skill
+description: |
+  Line one.
+  Line two.
+---
+`;
+    const result = parseSkillFrontmatter(content);
+    expect(result?.description).toBe("Line one.\nLine two.");
+  });
+
+  test("folded block scalar with single line", () => {
+    const content = `---
+description: >
+  Single line text.
+---
+`;
+    const result = parseSkillFrontmatter(content);
+    expect(result?.description).toBe("Single line text.");
+  });
+
+  test("block scalar followed by another key", () => {
+    const content = `---
+name: my-skill
+description: >
+  Multi-line
+  description here.
+license: Apache-2.0
+---
+`;
+    const result = parseSkillFrontmatter(content);
+    expect(result?.description).toBe("Multi-line description here.");
+    expect(result?.license).toBe("Apache-2.0");
+    expect(result?.name).toBe("my-skill");
+  });
+});

package/src/frontmatter.ts

@@ -1,6 +1,7 @@
 /**
  * Parse YAML-style frontmatter between leading --- delimiters.
  * Returns null if no frontmatter found.
+ * Supports block scalars: > (folded) and | (literal).
  */
 export function parseSkillFrontmatter(
   content: string,
@@ -10,16 +11,34 @@ export function parseSkillFrontmatter(
   // biome-ignore lint/style/noNonNullAssertion: match[1] is defined because the regex has a capturing group
   const block = match[1]!;
   const data: Record<string, unknown> = {};
-  for (const line of block.split("\n")) {
+  const lines = block.split("\n");
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i]!;
     const sep = line.indexOf(":");
-    if (sep === -1) continue;
+    if (sep === -1) { i++; continue; }
     const key = line.slice(0, sep).trim();
-    if (!key) continue;
+    if (!key) { i++; continue; }
     const raw = line.slice(sep + 1).trim();
-    if (raw === "true") data[key] = true;
-    else if (raw === "false") data[key] = false;
-    else if (raw !== "" && !Number.isNaN(Number(raw))) data[key] = Number(raw);
-    else data[key] = raw;
+    if (raw === ">" || raw === "|") {
+      const style = raw;
+      const parts: string[] = [];
+      i++;
+      while (i < lines.length) {
+        const next = lines[i]!;
+        if (next.length > 0 && (next[0] === " " || next[0] === "\t")) {
+          parts.push(next.trimStart());
+          i++;
+        } else break;
+      }
+      data[key] = style === ">" ? parts.join(" ").trim() : parts.join("\n").trimEnd();
+    } else {
+      if (raw === "true") data[key] = true;
+      else if (raw === "false") data[key] = false;
+      else if (raw !== "" && !Number.isNaN(Number(raw))) data[key] = Number(raw);
+      else data[key] = raw;
+      i++;
+    }
   }
   return data;
 }

package/src/install.npm.test.ts

@@ -439,7 +439,10 @@ describe("updateSkill — npm", () => {
           integrity: v2.integrity,
         });
 
-        const result = await updateSkill({ yes: true });
+        const result = await updateSkill(
+          { yes: true },
+          async () => ({ tier: "unverified" as const }),
+        );
         expect(result.ok).toBe(true);
         if (!result.ok) return;
 
@@ -464,5 +467,5 @@ describe("updateSkill — npm", () => {
       await removeTmpDir(tgzDir1);
       await removeTmpDir(tgzDir2);
     }
-  });
+  }, 30_000);
 });

package/src/schemas/config.ts

@@ -53,6 +53,8 @@ export const ConfigSchema = z.object({
   security: SecurityConfigSchema.prefault({}),
   "agent-mode": AgentModeSchema.prefault({}),
   registry: RegistryConfigSchema,
+  /** Whether the built-in skilltap-skills tap is enabled. Set to false to opt out. */
+  builtin_tap: z.boolean().default(true),
   taps: z
     .array(
       z.object({

package/src/self-update.ts

@@ -60,7 +60,7 @@ async function writeCache(configDir: string, latest: string): Promise<void> {
   }
 }
 
-async function fetchLatestVersion(): Promise<string | null> {
+export async function fetchLatestVersion(): Promise<string | null> {
   try {
     const response = await fetch(
       `https://api.github.com/repos/${GITHUB_OWNER}/${GITHUB_REPO}/releases/latest`,

package/src/taps.test.ts

@@ -9,7 +9,14 @@ import {
 import { loadConfig } from "./config";
 import { installSkill } from "./install";
 import type { TapEntry } from "./taps";
-import { addTap, loadTaps, removeTap, searchTaps, updateTap } from "./taps";
+import {
+  addTap,
+  loadTaps,
+  parseGitHubTapShorthand,
+  removeTap,
+  searchTaps,
+  updateTap,
+} from "./taps";
 
 type Env = {
   SKILLTAP_HOME?: string;
@@ -74,6 +81,61 @@ async function createLocalSkillRepo(
   return { path: repoDir, cleanup: () => removeTmpDir(repoDir) };
 }
 
+// ─── Unit tests: parseGitHubTapShorthand ───────────────────────────────────
+
+describe("parseGitHubTapShorthand", () => {
+  test("parses owner/repo", () => {
+    expect(parseGitHubTapShorthand("user/my-tap")).toEqual({
+      name: "my-tap",
+      url: "https://github.com/user/my-tap.git",
+    });
+  });
+
+  test("parses github:owner/repo", () => {
+    expect(parseGitHubTapShorthand("github:acme/skills")).toEqual({
+      name: "skills",
+      url: "https://github.com/acme/skills.git",
+    });
+  });
+
+  test("strips @ref suffix", () => {
+    expect(parseGitHubTapShorthand("user/tap@main")).toEqual({
+      name: "tap",
+      url: "https://github.com/user/tap.git",
+    });
+  });
+
+  test("returns null for bare names", () => {
+    expect(parseGitHubTapShorthand("my-tap")).toBeNull();
+  });
+
+  test("returns null for full URLs", () => {
+    expect(
+      parseGitHubTapShorthand("https://github.com/user/repo.git"),
+    ).toBeNull();
+  });
+
+  test("returns null for npm: prefix", () => {
+    expect(parseGitHubTapShorthand("npm:my-package")).toBeNull();
+  });
+
+  test("returns null for local paths", () => {
+    expect(parseGitHubTapShorthand("./local")).toBeNull();
+    expect(parseGitHubTapShorthand("/abs/path")).toBeNull();
+    expect(parseGitHubTapShorthand("~/home")).toBeNull();
+  });
+
+  test("returns null for three-part paths", () => {
+    expect(parseGitHubTapShorthand("a/b/c")).toBeNull();
+  });
+
+  test("returns null for git@ URLs", () => {
+    expect(
+      parseGitHubTapShorthand("git@github.com:user/repo.git"),
+    ).toBeNull();
+  });
+});
+
 // ─── Unit tests: searchTaps ────────────────────────────────────────────────
 
 describe("searchTaps", () => {

package/src/taps.ts

@@ -11,6 +11,12 @@ import type { Tap, TapSkill } from "./schemas/tap";
 import { TapSchema } from "./schemas/tap";
 import { err, type GitError, ok, type Result, UserError } from "./types";
 
+/** The built-in tap — always available unless explicitly opted out via config. */
+export const BUILTIN_TAP = {
+  name: "skilltap-skills",
+  url: "https://github.com/nklisch/skilltap-skills.git",
+} as const;
+
 export type TapEntry = { tapName: string; skill: TapSkill };
 
 export type UpdateTapResult = {
@@ -63,6 +69,57 @@ function registrySourceToRepo(source: RegistrySource): string {
   }
 }
 
+export type GitHubTapShorthand = { name: string; url: string };
+
+const GH_LOCAL_PREFIXES = ["./", "/", "~/"];
+const GH_URL_PROTOCOLS = ["https://", "http://", "git@", "ssh://", "npm:"];
+
+/** Parse GitHub shorthand (owner/repo) into a tap name + clone URL. Returns null if not shorthand. */
+export function parseGitHubTapShorthand(
+  source: string,
+): GitHubTapShorthand | null {
+  let s = source;
+  if (s.startsWith("github:")) s = s.slice("github:".length);
+  else if (!s.includes("/")) return null;
+
+  if (GH_URL_PROTOCOLS.some((p) => s.startsWith(p))) return null;
+  if (GH_LOCAL_PREFIXES.some((p) => s.startsWith(p))) return null;
+
+  // Strip @ref suffix (taps always clone HEAD)
+  const atIdx = s.lastIndexOf("@");
+  if (atIdx !== -1) s = s.slice(0, atIdx);
+
+  const parts = s.split("/").filter(Boolean);
+  if (parts.length !== 2) return null;
+
+  const [owner, repo] = parts;
+  return {
+    name: repo!,
+    url: `https://github.com/${owner}/${repo}.git`,
+  };
+}
+
+/** Returns true if the built-in tap is already cloned locally. */
+export async function isBuiltinTapCloned(): Promise<boolean> {
+  return Bun.file(join(tapDir(BUILTIN_TAP.name), "tap.json")).exists();
+}
+
+/**
+ * Ensure the built-in tap is cloned locally. Idempotent — no-op if already present.
+ * Returns ok(undefined) whether freshly cloned or already present.
+ */
+export async function ensureBuiltinTap(): Promise<Result<void, UserError | GitError>> {
+  const dir = tapDir(BUILTIN_TAP.name);
+  const exists = await Bun.file(join(dir, "tap.json")).exists();
+  if (exists) return ok(undefined);
+
+  const gitCheck = await checkGitInstalled();
+  if (!gitCheck.ok) return gitCheck;
+
+  const cloneResult = await clone(BUILTIN_TAP.url, dir, { depth: 1 });
+  return cloneResult;
+}
+
 export async function addTap(
   name: string,
   url: string,
@@ -72,6 +129,15 @@ export async function addTap(
   if (!configResult.ok) return configResult;
   const config = configResult.value;
 
+  if (name === BUILTIN_TAP.name && config.builtin_tap !== false) {
+    return err(
+      new UserError(
+        `'${BUILTIN_TAP.name}' is the built-in tap and is already included.`,
+        "To disable it, set 'builtin_tap = false' in your config.toml.",
+      ),
+    );
+  }
+
   if (config.taps.some((t) => t.name === name)) {
     return err(
       new UserError(
@@ -123,6 +189,23 @@ export async function removeTap(
   if (!configResult.ok) return configResult;
   const config = configResult.value;
 
+  // Special case: disable the built-in tap
+  if (name === BUILTIN_TAP.name) {
+    if (config.builtin_tap === false) {
+      return err(
+        new UserError(
+          `Built-in tap '${BUILTIN_TAP.name}' is already disabled.`,
+          "Set 'builtin_tap = true' in config.toml to re-enable it.",
+        ),
+      );
+    }
+    config.builtin_tap = false;
+    const saveResult = await saveConfig(config);
+    if (!saveResult.ok) return saveResult;
+    await rm(tapDir(name), { recursive: true, force: true });
+    return ok(undefined);
+  }
+
   const idx = config.taps.findIndex((t) => t.name === name);
   if (idx === -1) {
     return err(
@@ -152,6 +235,46 @@ export async function updateTap(
   if (!configResult.ok) return configResult;
   const config = configResult.value;
 
+  const updated: Record<string, number> = {};
+  const http: string[] = [];
+
+  // Handle built-in tap: update if enabled and requested
+  if (name === BUILTIN_TAP.name) {
+    if (config.builtin_tap === false) {
+      return err(
+        new UserError(
+          `Tap '${BUILTIN_TAP.name}' is not configured.`,
+          "Set 'builtin_tap = true' in config.toml to re-enable it.",
+        ),
+      );
+    }
+    const dir = tapDir(BUILTIN_TAP.name);
+    if (!(await Bun.file(join(dir, "tap.json")).exists())) {
+      return err(
+        new UserError(
+          `Built-in tap '${BUILTIN_TAP.name}' is not yet cloned.`,
+          "Run 'skilltap tap install' to set it up.",
+        ),
+      );
+    }
+    const pullResult = await pull(dir);
+    if (!pullResult.ok) return pullResult;
+    const tapResult = await loadTapJson(dir, BUILTIN_TAP.name);
+    updated[BUILTIN_TAP.name] = tapResult.ok ? tapResult.value.skills.length : 0;
+    return ok({ updated, http });
+  }
+
+  // Update all: include built-in tap if enabled and cloned
+  if (!name && config.builtin_tap !== false) {
+    const dir = tapDir(BUILTIN_TAP.name);
+    if (await Bun.file(join(dir, "tap.json")).exists()) {
+      const pullResult = await pull(dir);
+      if (!pullResult.ok) return pullResult;
+      const tapResult = await loadTapJson(dir, BUILTIN_TAP.name);
+      updated[BUILTIN_TAP.name] = tapResult.ok ? tapResult.value.skills.length : 0;
+    }
+  }
+
   const targets = name
     ? config.taps.filter((t) => t.name === name)
     : config.taps;
@@ -165,9 +288,6 @@ export async function updateTap(
     );
   }
 
-  const updated: Record<string, number> = {};
-  const http: string[] = [];
-
   for (const tap of targets) {
     if (tap.type === "http") {
       http.push(tap.name);
@@ -193,6 +313,17 @@ export async function loadTaps(): Promise<Result<TapEntry[], UserError>> {
 
   const entries: TapEntry[] = [];
 
+  // Load built-in tap first (if enabled and already cloned)
+  if (config.builtin_tap !== false) {
+    const dir = tapDir(BUILTIN_TAP.name);
+    const tapResult = await loadTapJson(dir, BUILTIN_TAP.name);
+    if (tapResult.ok) {
+      for (const skill of tapResult.value.skills) {
+        entries.push({ tapName: BUILTIN_TAP.name, skill });
+      }
+    }
+  }
+
   for (const tap of config.taps) {
     if (tap.type === "http") {
       // HTTP registry: fetch skills from API

package/src/update.ts

@@ -22,6 +22,8 @@ import { scanSemantic } from "./security/semantic";
 import { wrapShell } from "./shell";
 import { createAgentSymlinks, removeAgentSymlinks } from "./symlink";
 import { parseGitHubRepo, resolveTrust } from "./trust";
+
+type ResolveTrustFn = typeof resolveTrust;
 import type { Result } from "./types";
 import {
   err,
@@ -172,6 +174,7 @@ async function updateNpmSkill(
   installed: { skills: InstalledSkill[] },
   options: UpdateOptions,
   result: UpdateResult,
+  _resolveTrust: ResolveTrustFn,
 ): Promise<Result<void, UserError | NetworkError | ScanError>> {
   // biome-ignore lint/style/noNonNullAssertion: caller checks record.repo?.startsWith("npm:")
   const { name: packageName } = parseNpmSource(record.repo!);
@@ -262,7 +265,7 @@ async function updateNpmSkill(
     await refreshAgentSymlinks(record, options.projectRoot);
 
     // Re-verify trust for the new version
-    const newTrust = await resolveTrust({
+    const newTrust = await _resolveTrust({
       adapter: "npm",
       url: record.repo!,
       tap: record.tap,
@@ -294,6 +297,7 @@ async function updateGitSkill(
   installed: { skills: InstalledSkill[] },
   options: UpdateOptions,
   result: UpdateResult,
+  _resolveTrust: ResolveTrustFn,
 ): Promise<Result<void, UserError | GitError | ScanError>> {
   // Standalone: work dir is the install path. Multi-skill: work dir is the cache.
   const isMulti = record.path !== null;
@@ -388,7 +392,7 @@ async function updateGitSkill(
   if (!newShaResult.ok) return newShaResult;
 
   // Re-verify trust for the updated skill
-  const newTrust = await resolveTrust({
+  const newTrust = await _resolveTrust({
     adapter: "git",
     url: record.repo ?? "",
     tap: record.tap,
@@ -412,6 +416,7 @@ async function updateGitSkill(
 
 export async function updateSkill(
   options: UpdateOptions = {},
+  _resolveTrust: ResolveTrustFn = resolveTrust,
 ): Promise<Result<UpdateResult, UserError | GitError | ScanError | NetworkError>> {
   debug("updateSkill", { name: options.name ?? "all" });
   const installedResult = await loadInstalled();
@@ -444,10 +449,10 @@ export async function updateSkill(
 
     // Dispatch to adapter-specific update handler
     if (record.repo?.startsWith("npm:")) {
-      const npmResult = await updateNpmSkill(record, installed, options, result);
+      const npmResult = await updateNpmSkill(record, installed, options, result, _resolveTrust);
       if (!npmResult.ok) return npmResult;
     } else {
-      const gitResult = await updateGitSkill(record, installed, options, result);
+      const gitResult = await updateGitSkill(record, installed, options, result, _resolveTrust);
       if (!gitResult.ok) return gitResult;
     }
   }