skillshelf 0.1.0

package/src/lib/fs.ts

@@ -0,0 +1,186 @@
+// Filesystem helpers: realpath-dedupe, safe symlink ops, directory walking.
+// Bun built-ins + node:fs/node:path only. No external deps.
+
+import { realpathSync, existsSync, lstatSync } from "node:fs";
+import {
+  mkdir,
+  readdir,
+  symlink,
+  rm,
+  lstat,
+  realpath,
+} from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+/** Resolve a path to its canonical real location; falls back to resolve() if it doesn't exist. */
+export function realpathOrSelf(p: string): string {
+  try {
+    return realpathSync(p);
+  } catch {
+    return resolve(p);
+  }
+}
+
+/** Async variant. */
+export async function realpathOrSelfAsync(p: string): Promise<string> {
+  try {
+    return await realpath(p);
+  } catch {
+    return resolve(p);
+  }
+}
+
+/**
+ * De-duplicate a list of paths by their realpath (handles aliased mounts like
+ * cloud-sync mirror locations). Returns the first-seen path for each realpath.
+ */
+export function dedupeByRealpath(paths: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const p of paths) {
+    const rp = realpathOrSelf(p);
+    if (seen.has(rp)) continue;
+    seen.add(rp);
+    out.push(p);
+  }
+  return out;
+}
+
+export function pathExists(p: string): boolean {
+  return existsSync(p);
+}
+
+export function isSymlink(p: string): boolean {
+  try {
+    return lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+export async function isDirectory(p: string): Promise<boolean> {
+  try {
+    const st = await lstat(p);
+    if (st.isSymbolicLink()) {
+      const rp = await realpathOrSelfAsync(p);
+      const rst = await lstat(rp).catch(() => null);
+      return rst?.isDirectory() ?? false;
+    }
+    return st.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Create a symlink, creating parent dirs. If `force`, replace any existing entry. */
+export async function safeSymlink(
+  target: string,
+  linkPath: string,
+  opts: { force?: boolean } = {},
+): Promise<void> {
+  await mkdir(dirname(linkPath), { recursive: true });
+  if (existsSync(linkPath) || isSymlink(linkPath)) {
+    if (!opts.force) {
+      // idempotent: if it already points at target, do nothing
+      try {
+        const cur = await realpath(linkPath);
+        if (cur === (await realpathOrSelfAsync(target))) return;
+      } catch {
+        /* fallthrough to remove */
+      }
+    }
+    await rm(linkPath, { recursive: true, force: true });
+  }
+  await symlink(target, linkPath);
+}
+
+/** Remove a symlink (only if it is a symlink, unless force). Returns true if removed. */
+export async function removeSymlink(
+  linkPath: string,
+  opts: { force?: boolean } = {},
+): Promise<boolean> {
+  if (!isSymlink(linkPath)) {
+    if (!opts.force) return false;
+    if (!existsSync(linkPath)) return false;
+  }
+  await rm(linkPath, { recursive: true, force: true });
+  return true;
+}
+
+export interface WalkOptions {
+  /** max depth (0 = only the root's direct entries). Default Infinity. */
+  maxDepth?: number;
+  /** directory names to skip entirely (e.g. node_modules). */
+  skipDirs?: Set<string>;
+  /** follow symlinked dirs. Default false. */
+  followSymlinks?: boolean;
+}
+
+export interface WalkEntry {
+  path: string;
+  name: string;
+  isDirectory: boolean;
+  isSymlink: boolean;
+  depth: number;
+}
+
+/**
+ * Recursively walk a directory yielding entries. Never throws on individual
+ * unreadable dirs (skips them). Skips `skipDirs` by name at any depth.
+ */
+export async function* walk(
+  root: string,
+  opts: WalkOptions = {},
+): AsyncGenerator<WalkEntry> {
+  const maxDepth = opts.maxDepth ?? Infinity;
+  const skipDirs = opts.skipDirs ?? new Set(["node_modules", ".git"]);
+  const follow = opts.followSymlinks ?? false;
+
+  async function* recurse(dir: string, depth: number): AsyncGenerator<WalkEntry> {
+    let entries: Awaited<ReturnType<typeof readdir>> = [];
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = join(dir, e.name);
+      const link = e.isSymbolicLink();
+      let isDir = e.isDirectory();
+      if (link) {
+        isDir = await isDirectory(full);
+      }
+      yield { path: full, name: e.name, isDirectory: isDir, isSymlink: link, depth };
+      if (isDir && depth < maxDepth) {
+        if (skipDirs.has(e.name)) continue;
+        if (link && !follow) continue;
+        yield* recurse(full, depth + 1);
+      }
+    }
+  }
+
+  yield* recurse(root, 0);
+}
+
+/** Ensure a directory exists. */
+export async function ensureDir(p: string): Promise<void> {
+  await mkdir(p, { recursive: true });
+}
+
+/** List immediate subdirectory names of a dir (non-recursive). Empty on error. */
+export async function listDirNames(dir: string): Promise<string[]> {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const out: string[] = [];
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        out.push(e.name);
+      } else if (e.isSymbolicLink() && (await isDirectory(join(dir, e.name)))) {
+        out.push(e.name);
+      }
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}

package/src/types.ts

@@ -0,0 +1,186 @@
+// skillshelf — domain model + command contract.
+// This file is the source-of-truth type surface every command author codes against.
+
+/**
+ * Where an imported / third-party skill came from. `null` for hand-written skills.
+ * Mirrors the provenance lockfile shape (see Lockfile / LockEntry below).
+ */
+export interface Provenance {
+  /** e.g. "github:owner/repo@path" */
+  source: string;
+  /** installed commit SHA or version tag */
+  ref: string;
+  /** where it was fetched from */
+  channel: "github" | "vercel-registry" | string;
+  /** ISO-8601 timestamp of install */
+  installedAt: string;
+  /** true if the local upstream body diverged from the pristine fetched copy */
+  localEdits: boolean;
+}
+
+/**
+ * A single skill as discovered on disk (crawl) or in the canonical library.
+ * `domains` is the *effective* tag list (upstream frontmatter + overlay merged).
+ */
+export interface Skill {
+  /** unique slug, from frontmatter `name` or directory name */
+  name: string;
+  /** frontmatter `description` (may be multi-line) */
+  description: string;
+  /** primary domain folder this skill physically lives under (library), or inferred. null if unknown */
+  primaryDomain: string | null;
+  /** effective domain tags (primary first), de-duplicated */
+  domains: string[];
+  /** absolute path to the skill directory (the dir containing SKILL.md) */
+  path: string;
+  /** absolute path to the SKILL.md body file */
+  bodyPath: string;
+  /** absolute paths to bundled reference files (everything in the dir besides SKILL.md / overlay / lock) */
+  refFiles: string[];
+  /** provenance for third-party skills; null for hand-written */
+  source: Provenance | null;
+  /** true if found under a _retired/ dir — tagged, not activated */
+  retired: boolean;
+  /** if this is a bridge mirror (.agents/skills) of another skill, the canonical skill's path; else null */
+  mirrorOf: string | null;
+  /** sha-256 of the SKILL.md body content (for dedupe/drift detection) */
+  contentHash: string;
+}
+
+/**
+ * Sidecar overlay stored as `<skill>.shelf.json` next to SKILL.md.
+ * Holds *your* additions that survive upstream `update`.
+ */
+export interface Overlay {
+  /** extra/override domain tags */
+  domains?: string[];
+  /** explicit bundle membership names */
+  bundles?: string[];
+  /** free-form notes */
+  notes?: string;
+}
+
+/** A single provenance lockfile entry. */
+export interface LockEntry {
+  name: string;
+  /** e.g. "github:owner/repo@path" */
+  source: string;
+  /** installed commit SHA or version tag */
+  ref: string;
+  channel: "github" | "vercel-registry" | string;
+  /** ISO-8601 */
+  installedAt: string;
+  /** true if upstream body diverged locally */
+  localEdits: boolean;
+  /**
+   * Hash of the upstream SKILL.md body as it was at install/update time.
+   * Enables true 3-way divergence: local == installedHash => user did NOT edit
+   * (safe to re-pull even if upstream moved); local != installedHash => user
+   * hand-edited (do not clobber without --force). Optional for legacy entries.
+   */
+  installedHash?: string;
+}
+
+/** The whole lockfile (`shelf.lock.json` at the library root). */
+export interface Lockfile {
+  version: 1;
+  entries: Record<string, LockEntry>;
+}
+
+/**
+ * A bundle = a tag query over `domains[]`. Resolving a bundle yields every skill
+ * tagged with the bundle's domain. Bundles are virtual, never folders.
+ */
+export interface Bundle {
+  /** bundle name == the domain tag it queries (e.g. "bioinfo") */
+  name: string;
+  /** skills resolved into this bundle */
+  skills: Skill[];
+}
+
+/**
+ * A duplicate/drift group produced by dedupe: skills sharing a name (and/or hash).
+ * `canonical` is the chosen authoritative copy; `divergent` are drifted copies.
+ */
+export interface DuplicateGroup {
+  name: string;
+  /** the chosen canonical skill (prefers library/non-mirror/non-retired) */
+  canonical: Skill;
+  /** other copies that differ in content hash (drifted) */
+  divergent: Skill[];
+  /** exact-duplicate copies (same hash, different path) */
+  duplicates: Skill[];
+  /** true if every copy shares the same content hash */
+  identical: boolean;
+}
+
+/**
+ * Snapshot fed to the AI inference pass (`skl infer`). Deterministic core only
+ * assembles this; the LLM call lives elsewhere.
+ */
+export interface InferenceCorpus {
+  skills: Array<{
+    name: string;
+    description: string;
+    currentDomains: string[];
+    bodyPreview: string;
+  }>;
+  /** domain vocabulary observed across the library */
+  observedDomains: string[];
+  generatedAt: string;
+}
+
+/** Resolved configuration for a skillshelf invocation. */
+export interface Config {
+  /** absolute path to the canonical library (skill content) */
+  libraryPath: string;
+  /** absolute path to the global-core symlink target (~/.claude/skills) */
+  globalCoreTarget: string;
+  /** absolute path to the config file that was read, if any */
+  configFile: string | null;
+  /** how libraryPath was resolved */
+  source: "env" | "config" | "default";
+}
+
+/** Optional on-disk config file (~/.skillshelf/config.json). */
+export interface ConfigFile {
+  /** override library path */
+  library?: string;
+  /** override global-core target */
+  globalCore?: string;
+}
+
+/**
+ * The execution context handed to every command's `run()`.
+ * Built by `loadContext()` in src/config.ts.
+ */
+export interface Ctx {
+  /** resolved config (paths + provenance) */
+  config: Config;
+  /** convenience alias for config.libraryPath */
+  libraryPath: string;
+  /** load the canonical library (effective skills, overlays merged) */
+  loadLibrary: () => Promise<Skill[]>;
+  /** human-readable logging to stdout */
+  log: (...args: unknown[]) => void;
+  /** machine-parseable single-line JSON to stdout */
+  json: (value: unknown) => void;
+  /** error logging to stderr */
+  error: (...args: unknown[]) => void;
+}
+
+/** Metadata every command module must export. */
+export interface CommandMeta {
+  name: string;
+  summary: string;
+  usage: string;
+}
+
+/** The function signature every command module must export as `run`. */
+export type CommandRun = (argv: string[], ctx: Ctx) => Promise<number>;
+
+/** Full shape of a command module (`src/commands/*.ts`). */
+export interface CommandModule {
+  meta: CommandMeta;
+  run: CommandRun;
+}