skillshelf 0.1.0

package/src/core/library.ts

@@ -0,0 +1,101 @@
+// Load the canonical library: crawl the library root, merge overlays into
+// effective skills, attach provenance from the lockfile, content-hash, list.
+
+import { existsSync } from "node:fs";
+import { basename, dirname, sep } from "node:path";
+import type { Skill } from "../types.ts";
+import { crawl } from "./crawl.ts";
+import { withOverlay } from "./overlay.ts";
+import { readLockfile, provenanceForName } from "./provenance.ts";
+
+/**
+ * Derive a primary-domain hint from a skill dir inside the library: the first
+ * path segment under the library root is the primary-domain folder.
+ *   <lib>/bioinfo/foo/SKILL.md -> "bioinfo"
+ */
+function libraryPrimaryDomain(libraryRoot: string): (dir: string) => string | null {
+  const rootParts = libraryRoot.replace(/\/+$/, "").split(sep);
+  // Structural folders that are not real domains (bridge/layout dirs).
+  const STRUCTURAL = new Set([".agents", ".claude", "skills", "skill", "_retired"]);
+  return (dir: string) => {
+    const parts = dir.split(sep);
+    // dir is <lib>/<domain>/<name>; domain is the segment right after root.
+    if (parts.length > rootParts.length + 1) {
+      const seg = parts[rootParts.length] ?? null;
+      if (seg && !STRUCTURAL.has(seg)) return seg;
+    }
+    // Not a clean domain folder (e.g. a .agents mirror) — let frontmatter win.
+    return null;
+  };
+}
+
+/**
+ * Load the canonical library at `libraryPath` into effective Skill[]:
+ * crawl + overlay-merge + provenance attach. Returns [] if the path is missing.
+ */
+export async function loadLibrary(libraryPath: string): Promise<Skill[]> {
+  if (!existsSync(libraryPath)) return [];
+
+  const { skills } = await crawl([libraryPath], {
+    primaryDomainOf: libraryPrimaryDomain(libraryPath),
+  });
+
+  const lock = await readLockfile(libraryPath);
+
+  const effective: Skill[] = [];
+  for (const s of skills) {
+    const merged = await withOverlay(s);
+    const prov = provenanceForName(lock, merged.name);
+    effective.push(prov ? { ...merged, source: prov } : merged);
+  }
+  // stable ordering: primaryDomain then name
+  effective.sort((a, b) => {
+    const da = a.primaryDomain ?? "~";
+    const db = b.primaryDomain ?? "~";
+    if (da !== db) return da < db ? -1 : 1;
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+  });
+  return effective;
+}
+
+/** Filter out retired skills (the activatable set). */
+export function activeSkills(skills: Skill[]): Skill[] {
+  return skills.filter((s) => !s.retired);
+}
+
+/** Find a skill by exact name (first match). */
+export function findByName(skills: Skill[], name: string): Skill | undefined {
+  return skills.find((s) => s.name === name);
+}
+
+/** Fuzzy search over name + description. Returns matches scored, best first. */
+export function searchSkills(skills: Skill[], query: string): Skill[] {
+  const q = query.toLowerCase().trim();
+  if (q === "") return [];
+  const terms = q.split(/\s+/);
+  const scored: Array<{ skill: Skill; score: number }> = [];
+  for (const s of skills) {
+    const name = s.name.toLowerCase();
+    const desc = s.description.toLowerCase();
+    const domains = s.domains.join(" ").toLowerCase();
+    let score = 0;
+    for (const t of terms) {
+      if (name === t) score += 100;
+      else if (name.includes(t)) score += 40;
+      if (desc.includes(t)) score += 10;
+      if (domains.includes(t)) score += 15;
+    }
+    if (score > 0) scored.push({ skill: s, score });
+  }
+  scored.sort((a, b) => b.score - a.score || (a.skill.name < b.skill.name ? -1 : 1));
+  return scored.map((x) => x.skill);
+}
+
+/** All unique domains across the library (sorted). */
+export function listDomains(skills: Skill[]): string[] {
+  const set = new Set<string>();
+  for (const s of skills) for (const d of s.domains) set.add(d);
+  return [...set].sort();
+}
+
+export { basename as _basename, dirname as _dirname };

package/src/core/overlay.ts

@@ -0,0 +1,63 @@
+// Sidecar overlay (`<skill>.shelf.json`) read/write/merge.
+// Effective skill = upstream frontmatter + overlay.
+
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import type { Overlay, Skill } from "../types.ts";
+
+/** Path to a skill's overlay file. */
+export function overlayPath(skill: Skill): string {
+  return join(skill.path, `${skill.name}.shelf.json`);
+}
+
+/** Read a skill's overlay, or null if none / unreadable. */
+export async function readOverlay(skill: Skill): Promise<Overlay | null> {
+  const p = overlayPath(skill);
+  if (!existsSync(p)) return null;
+  try {
+    const text = await Bun.file(p).text();
+    const parsed = JSON.parse(text) as Overlay;
+    if (!parsed || typeof parsed !== "object") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** Write a skill's overlay (pretty-printed JSON). */
+export async function writeOverlay(skill: Skill, overlay: Overlay): Promise<void> {
+  const p = overlayPath(skill);
+  await Bun.write(p, JSON.stringify(overlay, null, 2) + "\n");
+}
+
+/**
+ * Merge an overlay onto a base skill, producing the effective skill.
+ * Overlay domains are unioned onto upstream domains (primary stays first).
+ * Does not mutate the input.
+ */
+export function applyOverlay(skill: Skill, overlay: Overlay | null): Skill {
+  if (!overlay) return skill;
+  const domains = [...skill.domains];
+  if (Array.isArray(overlay.domains)) {
+    for (const d of overlay.domains) {
+      const s = String(d).trim();
+      if (s !== "" && !domains.includes(s)) domains.push(s);
+    }
+  }
+  const primaryDomain =
+    skill.primaryDomain ?? (domains.length > 0 ? domains[0]! : null);
+  return { ...skill, domains, primaryDomain };
+}
+
+/** Load + apply a skill's overlay from disk in one step. */
+export async function withOverlay(skill: Skill): Promise<Skill> {
+  const overlay = await readOverlay(skill);
+  return applyOverlay(skill, overlay);
+}
+
+/** Bundles a skill belongs to per its overlay (explicit membership). Empty if none. */
+export async function overlayBundles(skill: Skill): Promise<string[]> {
+  const overlay = await readOverlay(skill);
+  if (!overlay?.bundles) return [];
+  return overlay.bundles.map((b) => String(b).trim()).filter((b) => b !== "");
+}

package/src/core/provenance.ts

@@ -0,0 +1,130 @@
+// Provenance lockfile read/write + git origin detection for imported skills.
+// Lockfile lives at <library>/shelf.lock.json.
+
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import type { LockEntry, Lockfile, Provenance } from "../types.ts";
+
+export const LOCKFILE_NAME = "shelf.lock.json";
+
+export function lockfilePath(libraryPath: string): string {
+  return join(libraryPath, LOCKFILE_NAME);
+}
+
+function emptyLockfile(): Lockfile {
+  return { version: 1, entries: {} };
+}
+
+/** Read the lockfile at the library root; returns an empty lockfile if absent/invalid. */
+export async function readLockfile(libraryPath: string): Promise<Lockfile> {
+  const p = lockfilePath(libraryPath);
+  if (!existsSync(p)) return emptyLockfile();
+  try {
+    const text = await Bun.file(p).text();
+    const parsed = JSON.parse(text) as Lockfile;
+    if (!parsed || typeof parsed !== "object" || typeof parsed.entries !== "object") {
+      return emptyLockfile();
+    }
+    return { version: 1, entries: parsed.entries ?? {} };
+  } catch {
+    return emptyLockfile();
+  }
+}
+
+/** Write the lockfile (pretty JSON). */
+export async function writeLockfile(libraryPath: string, lock: Lockfile): Promise<void> {
+  const p = lockfilePath(libraryPath);
+  await Bun.write(p, JSON.stringify(lock, null, 2) + "\n");
+}
+
+/** Upsert one entry by name and persist. Returns the updated lockfile. */
+export async function recordEntry(
+  libraryPath: string,
+  entry: LockEntry,
+): Promise<Lockfile> {
+  const lock = await readLockfile(libraryPath);
+  lock.entries[entry.name] = entry;
+  await writeLockfile(libraryPath, lock);
+  return lock;
+}
+
+/** Remove one entry by name and persist. Returns true if it existed. */
+export async function removeEntry(libraryPath: string, name: string): Promise<boolean> {
+  const lock = await readLockfile(libraryPath);
+  if (!(name in lock.entries)) return false;
+  delete lock.entries[name];
+  await writeLockfile(libraryPath, lock);
+  return true;
+}
+
+/** Provenance for a skill name from a loaded lockfile, or null. */
+export function provenanceForName(lock: Lockfile, name: string): Provenance | null {
+  const e = lock.entries[name];
+  if (!e) return null;
+  return {
+    source: e.source,
+    ref: e.ref,
+    channel: e.channel,
+    installedAt: e.installedAt,
+    localEdits: e.localEdits,
+  };
+}
+
+export interface GitOrigin {
+  /** remote URL, e.g. https://github.com/owner/repo.git */
+  remote: string;
+  /** normalized "github:owner/repo" form if it parses, else the remote */
+  source: string;
+  /** current commit SHA */
+  ref: string;
+}
+
+function normalizeGithub(remote: string): string {
+  // git@github.com:owner/repo.git  |  https://github.com/owner/repo(.git)
+  const m =
+    remote.match(/github\.com[:/]+([^/]+)\/([^/]+?)(?:\.git)?$/) ?? null;
+  if (m) return `github:${m[1]}/${m[2]}`;
+  return remote;
+}
+
+/**
+ * Detect the git origin of a directory (an imported skill that retains a .git).
+ * Returns null if not a git repo or git is unavailable. Never throws.
+ */
+export async function detectGitOrigin(dir: string): Promise<GitOrigin | null> {
+  try {
+    const remoteProc = Bun.spawnSync(
+      ["git", "-C", dir, "config", "--get", "remote.origin.url"],
+      { stdout: "pipe", stderr: "ignore" },
+    );
+    if (remoteProc.exitCode !== 0) return null;
+    const remote = remoteProc.stdout.toString().trim();
+    if (remote === "") return null;
+
+    const refProc = Bun.spawnSync(["git", "-C", dir, "rev-parse", "HEAD"], {
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    const ref = refProc.exitCode === 0 ? refProc.stdout.toString().trim() : "";
+
+    return { remote, source: normalizeGithub(remote), ref };
+  } catch {
+    return null;
+  }
+}
+
+/** Build a LockEntry from a detected git origin. */
+export function entryFromGit(
+  name: string,
+  origin: GitOrigin,
+  opts: { channel?: string; installedAt?: string } = {},
+): LockEntry {
+  return {
+    name,
+    source: origin.source,
+    ref: origin.ref,
+    channel: opts.channel ?? "github",
+    installedAt: opts.installedAt ?? new Date().toISOString(),
+    localEdits: false,
+  };
+}

package/src/lib/frontmatter.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import { parseFrontmatter, serializeFrontmatter } from "./frontmatter.ts";
+
+describe("parseFrontmatter", () => {
+  test("scalar key/value + body", () => {
+    const r = parseFrontmatter("---\nname: foo\ndescription: hello world\n---\n# Body\n");
+    expect(r.hasFrontmatter).toBe(true);
+    expect(r.data.name).toBe("foo");
+    expect(r.data.description).toBe("hello world");
+    expect(r.body).toBe("# Body\n");
+  });
+
+  test("inline list", () => {
+    const r = parseFrontmatter('---\ndomains: [bioinfo, "qc-x", coding]\n---\nbody');
+    expect(r.data.domains).toEqual(["bioinfo", "qc-x", "coding"]);
+  });
+
+  test("block scalar literal |", () => {
+    const r = parseFrontmatter(
+      "---\nname: x\ndescription: |\n  line one\n  line two\n---\nbody",
+    );
+    expect(r.data.description).toBe("line one\nline two");
+  });
+
+  test("folded block scalar >-", () => {
+    const r = parseFrontmatter(
+      "---\nname: x\ndescription: >-\n  folded line one\n  folded line two\n---\nbody",
+    );
+    expect(r.data.description).toBe("folded line one folded line two");
+  });
+
+  test("block list with - items", () => {
+    const r = parseFrontmatter("---\ndomains:\n  - a\n  - b\n---\nbody");
+    expect(r.data.domains).toEqual(["a", "b"]);
+  });
+
+  test("no frontmatter returns whole text as body", () => {
+    const r = parseFrontmatter("# just markdown\nno fences");
+    expect(r.hasFrontmatter).toBe(false);
+    expect(r.body).toBe("# just markdown\nno fences");
+  });
+
+  test("missing closing fence is treated as no frontmatter", () => {
+    const r = parseFrontmatter("---\nname: x\nnever closes");
+    expect(r.hasFrontmatter).toBe(false);
+  });
+
+  test("round-trips scalars and lists", () => {
+    const out = serializeFrontmatter(
+      { name: "foo", domains: ["a", "b"] },
+      "# Body\n",
+    );
+    const r = parseFrontmatter(out);
+    expect(r.data.name).toBe("foo");
+    expect(r.data.domains).toEqual(["a", "b"]);
+    expect(r.body.trim()).toBe("# Body");
+  });
+});

package/src/lib/frontmatter.ts

@@ -0,0 +1,231 @@
+// Minimal YAML frontmatter parser/serializer.
+// Handles the subset real SKILL.md files use:
+//   - leading/trailing `---` fences
+//   - scalar `key: value`
+//   - inline lists `key: [a, b, c]`
+//   - block lists (`key:` then `  - item` lines)
+//   - block scalars `key: |` and `key: >-` (folded/literal multi-line)
+//   - quoted scalars ("..." / '...')
+// Robust to missing/extra keys. NOT a general YAML implementation.
+
+export interface Frontmatter {
+  data: Record<string, unknown>;
+  /** the body after the closing `---` fence (with no leading newline) */
+  body: string;
+  /** true if a frontmatter block was actually present */
+  hasFrontmatter: boolean;
+}
+
+const FENCE = "---";
+
+function stripQuotes(s: string): string {
+  const t = s.trim();
+  if (t.length >= 2) {
+    const first = t[0];
+    const last = t[t.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return t.slice(1, -1);
+    }
+  }
+  return t;
+}
+
+function parseInlineList(s: string): string[] {
+  // s includes surrounding brackets: [a, "b, with comma", 'c']
+  const inner = s.trim().slice(1, -1).trim();
+  if (inner === "") return [];
+  // Split on commas OUTSIDE quotes so quoted items containing commas stay intact.
+  const items: string[] = [];
+  let buf = "";
+  let quote: '"' | "'" | null = null;
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i]!;
+    if (quote) {
+      if (ch === quote) quote = null;
+      buf += ch;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+      buf += ch;
+    } else if (ch === ",") {
+      items.push(buf);
+      buf = "";
+    } else {
+      buf += ch;
+    }
+  }
+  items.push(buf);
+  return items.map((x) => stripQuotes(x.trim())).filter((x) => x.length > 0);
+}
+
+function parseScalar(raw: string): unknown {
+  const v = stripQuotes(raw.trim());
+  if (v === "true") return true;
+  if (v === "false") return false;
+  if (v === "null" || v === "~" || v === "") return v === "" ? "" : null;
+  if (/^-?\d+$/.test(v)) return Number(v);
+  return v;
+}
+
+/**
+ * Parse a SKILL.md (or any markdown) string into frontmatter data + body.
+ * Never throws; on malformed input returns hasFrontmatter:false with full text as body.
+ */
+export function parseFrontmatter(text: string): Frontmatter {
+  const normalized = text.replace(/\r\n/g, "\n");
+  if (!normalized.startsWith(FENCE)) {
+    return { data: {}, body: normalized, hasFrontmatter: false };
+  }
+  const lines = normalized.split("\n");
+  // first line is the opening fence (may have trailing spaces)
+  if (lines[0]?.trim() !== FENCE) {
+    return { data: {}, body: normalized, hasFrontmatter: false };
+  }
+  // find closing fence
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i]?.trim() === FENCE) {
+      end = i;
+      break;
+    }
+  }
+  if (end === -1) {
+    return { data: {}, body: normalized, hasFrontmatter: false };
+  }
+
+  const fmLines = lines.slice(1, end);
+  const body = lines.slice(end + 1).join("\n").replace(/^\n+/, "");
+  const data: Record<string, unknown> = {};
+
+  for (let i = 0; i < fmLines.length; i++) {
+    const line = fmLines[i]!;
+    if (line.trim() === "" || line.trim().startsWith("#")) continue;
+    // top-level keys are unindented
+    const m = line.match(/^([A-Za-z0-9_-]+):(.*)$/);
+    if (!m) continue;
+    const key = m[1]!;
+    const rest = m[2]!;
+    const restTrim = rest.trim();
+
+    // block scalar: | or > with optional chomp indicators
+    if (/^[|>][+-]?\s*$/.test(restTrim)) {
+      const folded = restTrim[0] === ">";
+      const collected: string[] = [];
+      let j = i + 1;
+      // determine block indentation from first non-empty child line
+      let blockIndent = -1;
+      while (j < fmLines.length) {
+        const cur = fmLines[j]!;
+        if (cur.trim() === "") {
+          collected.push("");
+          j++;
+          continue;
+        }
+        const indent = cur.length - cur.trimStart().length;
+        if (blockIndent === -1) {
+          if (indent === 0) break; // not part of block
+          blockIndent = indent;
+        }
+        if (indent < blockIndent) break;
+        collected.push(cur.slice(blockIndent));
+        j++;
+      }
+      i = j - 1;
+      // trim trailing blank lines
+      while (collected.length && collected[collected.length - 1] === "") {
+        collected.pop();
+      }
+      data[key] = folded
+        ? collected.join(" ").replace(/\s+/g, " ").trim()
+        : collected.join("\n");
+      continue;
+    }
+
+    // inline list
+    if (restTrim.startsWith("[") && restTrim.endsWith("]")) {
+      data[key] = parseInlineList(restTrim);
+      continue;
+    }
+
+    // block list: `key:` followed by `  - item` lines
+    if (restTrim === "") {
+      const items: string[] = [];
+      let j = i + 1;
+      while (j < fmLines.length) {
+        const cur = fmLines[j]!;
+        const ct = cur.trim();
+        if (ct === "") {
+          j++;
+          continue;
+        }
+        const lm = ct.match(/^-\s+(.*)$/);
+        if (!lm || cur.length - cur.trimStart().length === 0) break;
+        items.push(stripQuotes(lm[1]!.trim()));
+        j++;
+      }
+      if (items.length > 0) {
+        data[key] = items;
+        i = j - 1;
+      } else {
+        data[key] = "";
+      }
+      continue;
+    }
+
+    // plain scalar
+    data[key] = parseScalar(rest);
+  }
+
+  return { data, body, hasFrontmatter: true };
+}
+
+function needsQuoting(s: string): boolean {
+  return /[:#\[\]{}&*!|>'"%@`,]/.test(s) || /^\s|\s$/.test(s) || s === "";
+}
+
+function serializeScalar(v: unknown): string {
+  if (v === null) return "null";
+  if (typeof v === "boolean" || typeof v === "number") return String(v);
+  const s = String(v);
+  if (s.includes("\n")) {
+    // emit as literal block scalar
+    const indented = s
+      .split("\n")
+      .map((l) => "  " + l)
+      .join("\n");
+    return "|\n" + indented;
+  }
+  if (needsQuoting(s)) {
+    return JSON.stringify(s);
+  }
+  return s;
+}
+
+/**
+ * Serialize frontmatter data + body back into a SKILL.md string.
+ * Keys are emitted in insertion order. Arrays become inline lists.
+ */
+export function serializeFrontmatter(
+  data: Record<string, unknown>,
+  body: string,
+): string {
+  const out: string[] = [FENCE];
+  for (const [key, value] of Object.entries(data)) {
+    if (value === undefined) continue;
+    if (Array.isArray(value)) {
+      const items = value.map((x) =>
+        needsQuoting(String(x)) ? JSON.stringify(String(x)) : String(x),
+      );
+      out.push(`${key}: [${items.join(", ")}]`);
+    } else {
+      const s = serializeScalar(value);
+      if (s.startsWith("|\n")) {
+        out.push(`${key}: ${s}`);
+      } else {
+        out.push(`${key}: ${s}`);
+      }
+    }
+  }
+  out.push(FENCE);
+  const trimmedBody = body.replace(/^\n+/, "");
+  return out.join("\n") + "\n\n" + trimmedBody + (trimmedBody.endsWith("\n") ? "" : "\n");
+}