rovecode 0.3.3 → 0.4.0-beta.2

package/src/skills/index.ts

@@ -1,387 +0,0 @@
-/** Skills module (hermes pattern): SKILL.md files with frontmatter index,
- *  mtime+size manifest invalidation, usage sidecars, deterministic staleness.
- *  No LLM consolidation — lifecycle is a pure function of usage age.
- *
- *  agentskills.io shape (port #72): the frontmatter block is still read by parseFrontmatter below — which folds
- *  `>`/`|` block scalars, the form 3 of the 19 anthropics/skills descriptions are written in — and the FIELDS are
- *  then validated by spec.ts validateSkillMeta in LENIENT mode: an unreadable file, a missing block and an
- *  empty/missing description are INVALID (not loaded); every other spec deviation — a description over 1024 chars,
- *  a missing or non-conforming name, name ≠ directory, compatibility over 500, a non-string metadata value, an
- *  unknown key — LOADS with a line in ScanResult.warnings. Before that, such a file either loaded silently wrong or
- *  vanished from the index with nothing said. A missing `name:` falls back to the directory name.
- *
- *  A directory holding SKILL.md is a LEAF: find() does not descend into it, so a skill's own
- *  `references/example/SKILL.md` is not a second indexed skill (it used to be, which let a skill that merely
- *  documents itself inflate the prompt index). Dot-dirs are skipped, which is also what keeps the installer's
- *  `.install-<token>` / `.old-<token>` staging invisible to a concurrent scan (pack.ts).
- *
- *  Trust, stated as a DECISION and not an omission: a project `.rovecode/skills/` is walked whether or not the
- *  checkout is trusted. This repository's trust gate (core/trust.ts) exists to stop a cloned repo from making us
- *  RUN code — hooks, sandbox.json, the command-bearing settings keys, project MCP servers — and a skill is prompt
- *  text, which is a different class of problem. What is still open, and should be written down rather than implied:
- *  a cloned repo's skill DESCRIPTIONS do reach the system prompt through the index, so this is a prompt-injection
- *  path, and `.rovecode/memory/MEMORY.md` is the same path by another route. Both want ONE answer (withhold from the
- *  prompt with a boot note, self-trusting our own writes) rather than two half-answers in one binary, so the seam is
- *  here — SkillStoreOptions.walkProject — and deliberately not wired to anything yet. `allowed-tools` is likewise
- *  parsed and carried as DATA: nothing enforces it, and skills-spec.test.ts pins that, because a field that reads
- *  like a permission is one refactor away from being a security claim we never implemented. */
-
-import {
-  existsSync, readFileSync, readdirSync, renameSync, statSync, utimesSync, writeFileSync,
-} from "node:fs";
-import { rovecodeHome } from "../providers/auth.ts";
-import { basename, dirname, join, resolve } from "node:path";
-import { parseSkillFrontmatter, validateSkillMeta, type SkillFrontmatter } from "./spec.ts";
-
-/** The spec view of a file parseFrontmatter already read: its flat fields (block scalars folded) with the
- *  shapes and the `metadata:` map that only the spec walker can see. The two readers agree on every flat
- *  key; where they differ — an indented `metadata:` map, a list — the spec walker is the one that knows. */
-function specViewOf(fm: Record<string, string>, raw: string): SkillFrontmatter {
-  const spec = parseSkillFrontmatter(raw);
-  const fields = { ...(spec?.fields ?? {}), ...fm }; // parseFrontmatter wins on flat values (its block-scalar folding)
-  return {
-    fields,
-    shapes: spec?.shapes ?? Object.fromEntries(Object.keys(fm).map((k) => [k, "scalar" as const])),
-    metadata: spec?.metadata ?? {},
-    metadataNonString: spec?.metadataNonString ?? [],
-    body: spec?.body ?? "",
-  };
-}
-
-export const SKILL_FILE = "SKILL.md";
-/** the two per-skill sidecars (usage below; the versioned.ts edit ledger) — never resources, never packed */
-export const SIDECAR_SUFFIXES: readonly string[] = [".usage.json", ".versions.jsonl"];
-export const isSidecarName = (name: string): boolean => SIDECAR_SUFFIXES.some((x) => name.endsWith(x));
-export const MAX_DESCRIPTION_CHARS = 60;
-export const STALE_AFTER_MS = 1000 * 60 * 60 * 24 * 90; // 90 days
-
-export type SkillScope = "project" | "global";
-
-export interface Skill {
-  name: string;
-  /** one line for the system-prompt index: clipped to MAX_DESCRIPTION_CHARS on a word boundary */
-  description: string;
-  /** the description as written, however long — what `skill_view` and the market show */
-  fullDescription: string;
-  /** top-level `version`, else `metadata.version`, else "0.0.0" */
-  version: string;
-  /** absolute path of the SKILL.md */
-  path: string;
-  /** absolute skill directory — relative paths inside the skill resolve against it */
-  dir: string;
-  /** content after the frontmatter block */
-  body: string;
-  scope: SkillScope;
-  mtimeMs: number;
-  size: number;
-  license?: string;
-  compatibility?: string;
-  /** the `metadata:` map (string → string) */
-  metadata: Record<string, string>;
-  /** `allowed-tools` whitespace-split — DATA ONLY: nothing enforces it (see the header) */
-  allowedTools: string[];
-}
-
-export interface InvalidSkill { path: string; reason: string }
-/** a skill that LOADED with a spec deviation (lenient mode) */
-export interface SkillWarning { path: string; reason: string }
-
-export interface SkillUsage {
-  viewCount: number;
-  lastViewedAt: number;
-}
-
-export interface ScanChanges {
-  added: string[];
-  removed: string[];
-  changed: string[];
-}
-
-const IGNORED_DIRS: Record<string, true> = { node_modules: true, ".git": true };
-export interface ScanResult {
-  skills: Skill[];
-  invalid: InvalidSkill[];
-  /** loaded-with-warning files of this scan (added / changed only, like `invalid`) */
-  warnings: SkillWarning[];
-  changes: ScanChanges;
-}
-
-/** The skills dir of a scope: `<cwd>/.rovecode/skills` or `<user home>/skills` (ROVECODE_HOME honoured).
- *  The ONE place the two joins live, so the CLI and the store cannot disagree (mcpConfigPath precedent). */
-export function skillsDir(cwd: string, scope: SkillScope): string {
-  return scope === "project" ? join(cwd, ".rovecode", "skills") : join(rovecodeHome(), "skills");
-}
-
-export interface SkillStoreOptions {
-  /** project skills dir (default: <cwd>/.rovecode/skills) */
-  projectDir?: string;
-  /** global skills dir; null disables (default: ~/.rovecode/skills) */
-  globalDir?: string | null;
-  /** max directory depth when walking for SKILL.md (default 3) */
-  maxDepth?: number;
-  /** the seam named in the header: false leaves the project dir out of every scan. Nothing sets it today —
-   *  skills are prompt text, and the trust gate is about running code. Default true. */
-  walkProject?: boolean;
-  /** more roots — a plugin's skills folder (src/plugins) — walked like the two above, tagged with the
-   *  scope the plugin itself has (a project plugin's skills win a name clash as the project's own would) */
-  extraDirs?: readonly { dir: string; scope: SkillScope }[];
-}
-
-// ---------- Frontmatter ----------
-
-/** Split `---\nkey: value` frontmatter from body. Returns null when no block.
- *
- *  Values may be a plain scalar, or a YAML block scalar — `key: >` / `|` / `>-` / `|-` followed by
- *  more-indented lines, which real SKILL.md files use for anything longer than a phrase. Measured on
- *  anthropics/skills (2026-09-05): 3 of 19 skills write their description that way, and reading only
- *  the header line gave `description: ">"` — not an error, just a skill whose one-line summary is a
- *  punctuation mark, with its continuation lines mistaken for keys of their own. That is worse than
- *  rejecting it, because nothing says anything went wrong. Folded (`>`) joins its lines with a space,
- *  literal (`|`) keeps the newlines, a trailing `-` strips the final newline. The rest of YAML —
- *  anchors, nested maps, lists — is still out of scope: this is a frontmatter reader, not a parser. */
-export function parseFrontmatter(text: string): { fm: Record<string, string>; body: string } | null {
-  if (!text.startsWith("---")) return null;
-  const end = text.indexOf("\n---", 3);
-  if (end === -1) return null;
-  const closeEnd = end + 1 + text.slice(end + 1).indexOf("\n") + 1; // past the closing `---` line
-  const block = text.slice(4, end); // skip leading `---\n`
-  const body = text.slice(closeEnd).replace(/^\r?\n/, "");
-  const fm: Record<string, string> = {};
-  const lines = block.split(/\r?\n/);
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i] as string;
-    if (/^\s/.test(line)) continue;                 // an orphan continuation is not a key of its own
-    const c = line.indexOf(":");
-    if (c === -1) continue;
-    const k = line.slice(0, c).trim();
-    if (!k) continue;
-    const rest = line.slice(c + 1).trim();
-    const m = /^([|>])([+-]?)$/.exec(rest);
-    if (m === null) { fm[k] = rest.replace(/^["']|["']$/g, ""); continue; }
-    const folded = m[1] === ">";
-    const owned: string[] = [];
-    while (i + 1 < lines.length) {
-      const next = lines[i + 1] as string;
-      if (next.trim() !== "" && !/^\s/.test(next)) break;   // back to column 0: the block ended
-      owned.push(next.replace(/^\s+/, ""));
-      i++;
-    }
-    while (owned.length > 0 && owned[owned.length - 1] === "") owned.pop();
-    fm[k] = folded ? owned.join(" ").replace(/\s+/g, " ").trim() : owned.join("\n");
-  }
-  return { fm, body };
-}
-
-/** Clip to the index budget on a word boundary, with an ellipsis so a reader can tell it was cut. */
-export function clipDescription(text: string): string {
-  const one = text.replace(/\s+/g, " ").trim();
-  if (one.length <= MAX_DESCRIPTION_CHARS) return one;
-  const cut = one.slice(0, MAX_DESCRIPTION_CHARS - 1);
-  const sp = cut.lastIndexOf(" ");
-  return `${(sp > MAX_DESCRIPTION_CHARS / 2 ? cut.slice(0, sp) : cut).replace(/[,;:.]$/, "")}…`;
-}
-
-/** Lenient load: `invalid` only for an unreadable file, a missing block or an empty description; every other
- *  spec deviation is a warning and the skill loads (see the header). */
-function parseSkillFile(path: string, scope: SkillScope): { skill: Skill; warnings: string[] } | { invalid: InvalidSkill } {
-  let text: string;
-  try {
-    text = readFileSync(path, "utf8");
-  } catch (e) {
-    return { invalid: { path, reason: `unreadable: ${(e as Error).message}` } };
-  }
-  const parsed = parseFrontmatter(text);
-  if (!parsed) return { invalid: { path, reason: "missing frontmatter block" } };
-  const dir = dirname(path);
-  // the spec field set over the SAME reader as before: parseFrontmatter's flat map plus its block scalars,
-  // spec.ts's `metadata:` walk for the nested map, then the lenient checks
-  const v = validateSkillMeta(specViewOf(parsed.fm, text), basename(dir), "lenient");
-  if (v.errors.length > 0) return { invalid: { path, reason: v.errors.join("; ") } };
-  const description = v.meta.description;
-  // A long description is CLIPPED for the index, never a reason to reject the skill. The cap exists to
-  // protect the system prompt (50 skills x a 950-char description is 47 KB of prefix), and clipping
-  // protects it just as well while a hard reject throws away a working skill for being wordy. Measured
-  // on anthropics/skills (2026-09-05): 16 of 19 real skills are over the cap, median 319 chars, longest
-  // 950 — the whole public corpus would have been unusable. The two other places rovecode reads a
-  // description already clip (plugins/manifest.ts, tui/commands.ts); this was the outlier.
-  const st = statSync(path);
-  return {
-    skill: {
-      name: v.meta.name,
-      description: clipDescription(description),
-      fullDescription: description,
-      version: v.meta.version || "0.0.0",
-      path, dir, body: parsed.body, scope,
-      mtimeMs: st.mtimeMs, size: st.size,
-      ...(v.meta.license !== undefined ? { license: v.meta.license } : {}),
-      ...(v.meta.compatibility !== undefined ? { compatibility: v.meta.compatibility } : {}),
-      metadata: v.meta.metadata,
-      allowedTools: v.meta.allowedTools,
-    },
-    warnings: v.warnings,
-  };
-}
-
-// ---------- Usage sidecar ----------
-
-export function usagePath(skillFile: string): string {
-  return skillFile + ".usage.json";
-}
-
-export function readUsage(skillFile: string): SkillUsage | undefined {
-  const p = usagePath(skillFile);
-  if (!existsSync(p)) return undefined;
-  try {
-    const raw = JSON.parse(readFileSync(p, "utf8")) as Partial<SkillUsage>;
-    return {
-      viewCount: typeof raw.viewCount === "number" ? raw.viewCount : 0,
-      lastViewedAt: typeof raw.lastViewedAt === "number" ? raw.lastViewedAt : 0,
-    };
-  } catch {
-    return undefined; // corrupt sidecar → treat as never used
-  }
-}
-
-/** Atomic write: temp file + rename, so a concurrent reader never sees a partial sidecar. */
-export function writeUsageAtomic(skillFile: string, usage: SkillUsage): void {
-  const p = usagePath(skillFile);
-  const tmp = p + ".tmp";
-  writeFileSync(tmp, JSON.stringify(usage, null, 2));
-  renameSync(tmp, p);
-}
-
-// ---------- Lifecycle ----------
-
-/** Deterministic: stale when last view (or, never viewed, file mtime) is older than 90d. */
-export function skillLifecycle(
-  skill: Pick<Skill, "mtimeMs">,
-  usage: SkillUsage | undefined,
-  now: number,
-): "active" | "stale" {
-  const lastActivity = usage && usage.viewCount > 0 ? usage.lastViewedAt : skill.mtimeMs;
-  return now - lastActivity > STALE_AFTER_MS ? "stale" : "active";
-}
-
-// ---------- Store ----------
-
-export class SkillStore {
-  private readonly projectDir: string;
-  private readonly globalDir: string | null;
-  private readonly maxDepth: number;
-  /** path → parsed skill (cache valid while manifest matches) */
-  private cache = new Map<string, Skill>();
-  /** path → `mtimeMs:size` (hermes manifest invalidation) */
-  private manifest = new Map<string, string>();
-
-  constructor(readonly cwd: string, opts: SkillStoreOptions = {}) {
-    this.projectDir = resolve(cwd, opts.projectDir ?? join(".rovecode", "skills"));
-    this.globalDir = opts.globalDir === null
-      ? null
-      // rovecodeHome(), not homedir(): ROVECODE_HOME is how every other part of rovecode finds its
-      // config — hooks, settings, plugins, credentials — and skills were the one that ignored it. So a
-      // user who set it read skills from a directory nothing else used, and every test that isolates
-      // itself with a scratch home silently indexed the DEVELOPER's real skills instead. That is how
-      // this was found: installing one skill into a real home broke a plugin test that never touches
-      // skills, and the failure named a skill the test had never heard of.
-      : resolve(opts.globalDir ?? join(rovecodeHome(), "skills"));
-    this.maxDepth = opts.maxDepth ?? 3;
-    this.walkProject = opts.walkProject !== false;
-    this.extraDirs = (opts.extraDirs ?? []).map(({ dir, scope }) => [resolve(cwd, dir), scope]);
-  }
-  private readonly extraDirs: Array<[string, SkillScope]>;
-  private readonly walkProject: boolean;
-
-  private dirs(): Array<[string, SkillScope]> {
-    const d: Array<[string, SkillScope]> = this.walkProject ? [[this.projectDir, "project"]] : [];
-    if (this.globalDir && existsSync(this.globalDir)) d.push([this.globalDir, "global"]);
-    for (const [dir, scope] of this.extraDirs) if (existsSync(dir)) d.push([dir, scope]);
-    return d;
-  }
-
-  private find(root: string, dir: string = root, depth: number = 0): string[] {
-    let entries;
-    try {
-      entries = readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return [];
-    }
-    // A dir holding SKILL.md is a LEAF: its sub-dirs are that skill's own resources, never skills of their own.
-    if (entries.some((e) => e.isFile() && e.name === SKILL_FILE)) return [join(dir, SKILL_FILE)];
-    const found: string[] = [];
-    for (const e of entries) {
-      const p = join(dir, e.name);
-      if (e.isFile() && e.name === SKILL_FILE) found.push(p);
-      else if (e.isDirectory() && depth < this.maxDepth && !IGNORED_DIRS[e.name] && !e.name.startsWith(".")) {
-        found.push(...this.find(root, p, depth + 1));
-      }
-    }
-    return found;
-  }
-
-  /** Rescan: stat every SKILL.md, diff the manifest, reparse only added/changed files. */
-  scan(): ScanResult {
-    const next = new Map<string, string>();
-    const scopeOf = new Map<string, SkillScope>(); // by root, not by path prefix: a plugin's project skills live outside <cwd>/.rovecode/skills
-    for (const [dir, scope] of this.dirs()) {
-      for (const p of this.find(dir)) {
-        try {
-          const st = statSync(p);
-          next.set(p, `${st.mtimeMs}:${st.size}`);
-          if (!scopeOf.has(p)) scopeOf.set(p, scope);
-        } catch { /* vanished between readdir and stat */ }
-      }
-    }
-    const changes: ScanChanges = { added: [], removed: [], changed: [] };
-    for (const [p, sig] of next) {
-      if (!this.manifest.has(p)) changes.added.push(p);
-      else if (this.manifest.get(p) !== sig) changes.changed.push(p);
-    }
-    for (const p of this.manifest.keys()) if (!next.has(p)) changes.removed.push(p);
-
-    const invalid: InvalidSkill[] = [];
-    const warnings: SkillWarning[] = [];
-    for (const p of [...changes.added, ...changes.changed]) {
-      const scope = scopeOf.get(p) ?? (p.startsWith(this.projectDir) ? "project" : "global");
-      const r = parseSkillFile(p, scope);
-      if ("skill" in r) {
-        this.cache.set(p, r.skill);
-        for (const reason of r.warnings) warnings.push({ path: p, reason });
-      } else { this.cache.delete(p); invalid.push(r.invalid); }
-    }
-    for (const p of changes.removed) this.cache.delete(p);
-    this.manifest = next;
-    return { skills: this.list(), invalid, warnings, changes };
-  }
-
-  /** Project scope wins on name collisions with the global dir. */
-  list(): Skill[] {
-    const byName = new Map<string, Skill>();
-    for (const s of this.cache.values()) {
-      const prev = byName.get(s.name);
-      if (!prev || (prev.scope === "global" && s.scope === "project")) byName.set(s.name, s);
-    }
-    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
-  }
-
-  get(name: string): Skill | undefined {
-    return this.list().find((s) => s.name === name);
-  }
-
-  usage(name: string): SkillUsage | undefined {
-    const s = this.get(name);
-    return s ? readUsage(s.path) : undefined;
-  }
-
-  /** Record one view. Returns the updated sidecar contents. */
-  bumpUsage(skill: Skill, now: number = Date.now()): SkillUsage {
-    const prev = readUsage(skill.path);
-    const usage: SkillUsage = { viewCount: (prev?.viewCount ?? 0) + 1, lastViewedAt: now };
-    writeUsageAtomic(skill.path, usage);
-    return usage;
-  }
-}
-
-/** Touch a skill file's mtime (same size) so manifest invalidation is observable in tests. */
-export function touchSkillFile(path: string, at: Date = new Date()): void {
-  utimesSync(path, at, at);
-}

package/src/skills/pack.ts

@@ -1,220 +0,0 @@
-/** Skill packaging + install (port #72): `<name>.tar.gz` through the Bun.Archive built-in (no tar / zip dependency)
- *  and a staged install finished by a rename swap. Pattern sources (no code copied): opencode-2026
- *  skill/discovery.ts:94-124 (MIT — stage into a hidden `.tmp-<token>` dir, validate, rename the old skill aside,
- *  rename staging in, remove the old; on failure put the old back) and the house writeUsageAtomic temp + rename
- *  idiom (index.ts). The agentskills.io specification defines NO archive format: a tar.gz holding ONE top-level
- *  directory named after the skill is rovecode's convention (`.skill` zips are neither produced nor consumed).
- *
- *  Safety: every archive entry is checked BEFORE anything is written — the `files()` keys (checkArchiveEntries: `..`,
- *  absolute, drive letter, backslash, empty segment, archive shape) AND the raw tar headers (findLinkMember: a symlink,
- *  hard-link, device or fifo member is refused — `files()` lists regular files only, so those members are invisible to
- *  the key check). The staged tree is then written file-by-file from that validated Map (materialise); libarchive's
- *  `extract` is never called: on POSIX it would create a symlink member and write the next entry THROUGH it, outside
- *  the staging dir, and Bun 1.3.14's `extract` also silently flattens `../x` INTO the target and drops `C:/x` (both
- *  probed). The observable pin is "exit 2 and nothing under the skills dir changed". Staging is a dot-dir inside the
- *  skills dir (`.install-<token>`: invisible to the scanner, same volume as the target so the rename is atomic); the
- *  staged SKILL.md must load through the SAME lenient loader as a scan with zero invalid files before anything is renamed.
- *  File bytes go into the archive via readFileSync — Bun issue #28459 (open): `Bun.file()` inputs yield EMPTY entries.
- *  Pure fs + archive: cli/skills-cmd.ts owns argv, io and exit codes (SkillCmdError.code: 1 refused · 2 io / unsafe). */
-
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
-import { gunzipSync } from "node:zlib";
-import { isSidecarName, SKILL_FILE, SkillStore } from "./index.ts";
-
-export const MAX_ARCHIVE_ENTRIES = 2000;
-export const MAX_ARCHIVE_BYTES = 64 * 1024 * 1024;
-/** gunzip output cap for the header walk: a 64 MiB skill plus its headers fits, a header-only gzip bomb does not */
-export const INFLATE_CAP = 2 * MAX_ARCHIVE_BYTES;
-const SKIP_DIRS = new Set([".git", "node_modules"]);
-
-/** a refused (1) or failed (2) skills command; the CLI prints the message and exits with `code` */
-export class SkillCmdError extends Error {
-  constructor(message: string, readonly code: 1 | 2) {
-    super(message);
-  }
-}
-
-/** Every regular file under `dir` as sorted posix-relative paths; usage / version sidecars, .git and node_modules
- *  skipped; a symlink anywhere → SkillCmdError(1) (an archive must not carry links, a copy must not follow them). */
-export function collectSkillFiles(dir: string): string[] {
-  const out: string[] = [];
-  const walk = (d: string, rel: string): void => {
-    for (const e of readdirSync(d, { withFileTypes: true })) {
-      const r = rel === "" ? e.name : `${rel}/${e.name}`;
-      const st = lstatSync(join(d, e.name));
-      if (st.isSymbolicLink()) throw new SkillCmdError(`symlink refused: ${r}`, 1);
-      if (st.isDirectory()) { if (!SKIP_DIRS.has(e.name)) walk(join(d, e.name), r); }
-      else if (st.isFile() && !isSidecarName(e.name)) out.push(r);
-    }
-  };
-  walk(dir, "");
-  return out.sort();
-}
-
-/** gzip tarball bytes: `<name>/<rel>` for every collected file, keys sorted (posix), contents via readFileSync. */
-export async function packSkill(dir: string, name: string): Promise<Uint8Array> {
-  const entries: Record<string, Uint8Array> = {};
-  for (const rel of collectSkillFiles(dir)) entries[`${name}/${rel}`] = readFileSync(join(dir, rel));
-  return new Bun.Archive(entries, { compress: "gzip" }).bytes();
-}
-
-/** The pre-write rules over `files()` keys: the reason the archive is refused, or null when it may be unpacked. */
-export function checkArchiveEntries(keys: readonly string[]): string | null {
-  if (keys.length === 0) return "archive is empty";
-  if (keys.length > MAX_ARCHIVE_ENTRIES) return `archive has ${keys.length} entries (max ${MAX_ARCHIVE_ENTRIES})`;
-  const tops = new Set<string>();
-  for (const key of keys) {
-    const shown = JSON.stringify(key);
-    if (key.includes("\\")) return `unsafe entry ${shown}: backslash`;
-    if (key.startsWith("/")) return `unsafe entry ${shown}: absolute path`;
-    if (/^[A-Za-z]:/.test(key)) return `unsafe entry ${shown}: drive letter`;
-    const segs = key.split("/");
-    if (segs.some((s) => s === "")) return `unsafe entry ${shown}: empty path segment`;
-    if (segs.some((s) => s === ".." || s === ".")) return `unsafe entry ${shown}: relative segment`;
-    if (segs.length < 2) return `entry ${shown} is not inside a top-level directory`;
-    tops.add(segs[0]!);
-  }
-  if (tops.size !== 1) return `archive must hold exactly one top-level directory (found ${[...tops].sort().join(", ")})`;
-  const top = [...tops][0]!;
-  if (!keys.includes(`${top}/${SKILL_FILE}`)) return `top-level directory ${JSON.stringify(top)} has no ${SKILL_FILE}`;
-  return null;
-}
-
-/** Member types a skill archive may not carry — `files()` never lists them, so an install would silently drop a hard
- *  link and (on POSIX, under `extract`) follow a symlink out of the staging dir. */
-const LINK_TYPES: Record<string, string> = { "1": "hard link", "2": "symlink", "3": "character device", "4": "block device", "6": "fifo" };
-
-/** Walk the raw ustar headers and name the first link / device / fifo member, or null. gzip (1f 8b) is inflated under
- *  INFLATE_CAP (past it → a refusal); a body that is not ustar at its first header, or a size field the walk cannot
- *  read, returns null — `files()` already accepted the archive and materialise() writes only its regular-file keys, so
- *  the walk is what NAMES a malformed archive, not what keeps a missed member harmless. */
-export function findLinkMember(bytes: Uint8Array): string | null {
-  let tar: Uint8Array = bytes;
-  if (bytes[0] === 0x1f && bytes[1] === 0x8b) {
-    try { tar = gunzipSync(bytes, { maxOutputLength: INFLATE_CAP }); }
-    catch (e) { return (e as NodeJS.ErrnoException).code === "ERR_BUFFER_TOO_LARGE" ? `archive inflates past ${INFLATE_CAP} bytes` : null; }
-  }
-  const text = (off: number, len: number): string => new TextDecoder().decode(tar.subarray(off, off + len)).replace(/\0[\s\S]*$/, "");
-  if (text(257, 5) !== "ustar") return null;
-  for (let off = 0; off + 512 <= tar.length && tar[off] !== 0; ) { // an all-zero block (empty name) ends the archive
-    const size = parseInt(text(off + 124, 12).trim() || "0", 8);
-    if (!Number.isFinite(size)) return null; // base-256 size or garbage: leave it to files()
-    const kind = LINK_TYPES[String.fromCharCode(tar[off + 156]!)];
-    if (kind !== undefined) {
-      const prefix = text(off + 345, 155);
-      return `unsafe entry ${JSON.stringify(prefix === "" ? text(off, 100) : `${prefix}/${text(off, 100)}`)}: ${kind} member`;
-    }
-    off += 512 + Math.ceil(size / 512) * 512;
-  }
-  return null;
-}
-
-/** Write the validated regular-file entries under `dir` — these keys are the ONLY thing that ever reaches the disk
- *  (no `extract`: no link members, no directory members, no mode bits from the archive). */
-async function materialise(files: Map<string, File>, dir: string): Promise<void> {
-  for (const [key, file] of files) {
-    const path = join(dir, key);
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, new Uint8Array(await file.arrayBuffer()));
-  }
-}
-
-export interface InstallOptions {
-  /** replace an existing `<skills dir>/<name>` (rename-swap; the old copy is restored when the swap fails) */
-  force?: boolean;
-  /** test seam: the per-file copy used while staging a directory (default copyFileSync) */
-  copyFile?: (src: string, dst: string) => void;
-  /** test seam: runs after the old skill was moved aside and before staging moves in — a throw exercises the rollback */
-  onSwap?: () => void;
-}
-export interface InstallResult { name: string; version: string; path: string; warnings: string[] }
-
-const token = (): string => Math.random().toString(36).slice(2, 10);
-
-function stagingDir(skillsDir: string): string {
-  mkdirSync(skillsDir, { recursive: true });
-  const dir = join(skillsDir, `.install-${token()}`);
-  mkdirSync(dir);
-  return dir;
-}
-
-function removeDir(dir: string): void {
-  for (let attempt = 1; ; attempt++) {
-    try { rmSync(dir, { recursive: true, force: true }); return; }
-    catch (e) { if (attempt >= 5) throw e; Bun.sleepSync(40 * attempt); } // Windows: a closing handle inside the tree
-  }
-}
-
-/** Copy a skill directory (sidecars excluded) into the skills dir under its LOADED name. */
-export function installFromDir(src: string, skillsDir: string, opts: InstallOptions = {}): InstallResult {
-  const from = resolve(src);
-  if (!existsSync(join(from, SKILL_FILE))) throw new SkillCmdError(`${from} has no ${SKILL_FILE}`, 2);
-  const files = collectSkillFiles(from);
-  const staging = stagingDir(skillsDir);
-  try {
-    const dest = join(staging, basename(from)); // the source basename, so a missing `name:` falls back to the right dir
-    const copy = opts.copyFile ?? copyFileSync;
-    for (const rel of files) {
-      const to = join(dest, rel);
-      mkdirSync(dirname(to), { recursive: true });
-      copy(join(from, rel), to);
-    }
-    return finish(staging, skillsDir, opts);
-  } catch (e) {
-    removeDir(staging);
-    throw e;
-  }
-}
-
-/** Unpack a tar.gz body: keys AND tar headers checked BEFORE anything is written, the tree written from the validated
- *  Map (never `extract`), then the same loader as a scan, then the rename swap. */
-export async function installFromBytes(bytes: Uint8Array, skillsDir: string, opts: InstallOptions = {}): Promise<InstallResult> {
-  if (bytes.length > MAX_ARCHIVE_BYTES) throw new SkillCmdError(`archive is ${bytes.length} bytes (max ${MAX_ARCHIVE_BYTES})`, 2);
-  let files: Map<string, File>;
-  try { files = await new Bun.Archive(bytes).files(); }
-  catch (e) { throw new SkillCmdError(`not a tar.gz archive: ${e instanceof Error ? e.message : String(e)}`, 2); }
-  const reason = checkArchiveEntries([...files.keys()]) ?? findLinkMember(bytes);
-  if (reason !== null) throw new SkillCmdError(reason, 2);
-  let total = 0;
-  for (const f of files.values()) total += f.size;
-  if (total > MAX_ARCHIVE_BYTES) throw new SkillCmdError(`archive unpacks to ${total} bytes (max ${MAX_ARCHIVE_BYTES})`, 2);
-  const staging = stagingDir(skillsDir);
-  try {
-    await materialise(files, staging);
-    return finish(staging, skillsDir, opts);
-  } catch (e) {
-    removeDir(staging);
-    throw e;
-  }
-}
-
-/** Validate the staged tree with the runtime's loader, then swap it into place. Throws with staging still present
- *  (the callers remove it); after a failed swap the old skill is back and no `.old-*` dir remains. */
-function finish(staging: string, skillsDir: string, opts: InstallOptions): InstallResult {
-  const r = new SkillStore(skillsDir, { projectDir: staging, globalDir: null }).scan();
-  if (r.invalid.length > 0) throw new SkillCmdError(`staged skill is invalid: ${r.invalid.map((i) => i.reason).join("; ")}`, 2);
-  if (r.skills.length !== 1) throw new SkillCmdError(`expected exactly one skill, found ${r.skills.length}`, 2);
-  const skill = r.skills[0]!;
-  if (!/^[^/\\]+$/.test(skill.name) || skill.name === "." || skill.name === ".." || skill.name.startsWith(".")) {
-    throw new SkillCmdError(`refusing skill name ${JSON.stringify(skill.name)}`, 2);
-  }
-  const target = join(skillsDir, skill.name);
-  const warnings = r.warnings.map((w) => w.reason);
-  if (existsSync(target)) {
-    if (!opts.force) throw new SkillCmdError(`${target} already exists (use --force to replace it)`, 1);
-    const old = join(skillsDir, `.old-${token()}`);
-    renameSync(target, old);
-    try {
-      opts.onSwap?.();
-      renameSync(skill.dir, target);
-    } catch (e) {
-      rmSync(target, { recursive: true, force: true });
-      renameSync(old, target);
-      throw e;
-    }
-    removeDir(old);
-  } else renameSync(skill.dir, target);
-  removeDir(staging);
-  return { name: skill.name, version: skill.version, path: target, warnings };
-}