skild 0.4.5 → 0.4.6

package/dist/index.js

@@ -9,7 +9,19 @@ import { createRequire } from "module";
 import fs2 from "fs";
 import path2 from "path";
 import chalk3 from "chalk";
-import { deriveChildSource, fetchWithTimeout, installRegistrySkill, installSkill, isValidAlias, loadRegistryAuth, materializeSourceToTemp, resolveRegistryAlias, resolveRegistryUrl, SkildError, PLATFORMS as PLATFORMS2 } from "@skild/core";
+import {
+  deriveChildSource,
+  fetchWithTimeout,
+  installRegistrySkill,
+  installSkill,
+  isValidAlias,
+  loadRegistryAuth,
+  materializeSourceToTemp,
+  resolveRegistryAlias,
+  resolveRegistryUrl,
+  SkildError,
+  PLATFORMS as PLATFORMS2
+} from "@skild/core";
 
 // src/utils/logger.ts
 import chalk from "chalk";
@@ -75,21 +87,8 @@ var logger = {
 import readline from "readline";
 import chalk2 from "chalk";
 import { PLATFORMS } from "@skild/core";
-var PLATFORM_DISPLAY = {
-  claude: { name: "Claude" },
-  codex: { name: "Codex" },
-  copilot: { name: "Copilot" },
-  antigravity: { name: "Antigravity" }
-};
 function buildSkillTree(skills) {
-  const allNode = {
-    id: "all",
-    name: "All Skills",
-    depth: 1,
-    children: [],
-    leafIndices: [],
-    isLeaf: false
-  };
+  const allNode = createTreeNode("all", "All Skills", 1, false);
   for (let i = 0; i < skills.length; i++) {
     const relPath = skills[i].relPath;
     const parts = relPath === "." ? ["."] : relPath.split("/").filter(Boolean);
@@ -100,21 +99,32 @@ function buildSkillTree(skills) {
       const nodeId = parts.slice(0, d + 1).join("/");
       let child = current.children.find((c2) => c2.name === part);
       if (!child) {
-        child = {
-          id: nodeId,
-          name: part,
-          depth: d + 2,
-          // +2 because allNode is depth 1
-          children: [],
-          leafIndices: [],
-          isLeaf: d === parts.length - 1
-        };
+        child = createTreeNode(nodeId, part, d + 2, d === parts.length - 1);
         current.children.push(child);
       }
       child.leafIndices.push(i);
       current = child;
     }
   }
+  collapseIntermediateNodes(allNode);
+  return wrapWithRoot(allNode);
+}
+function buildPlatformTree(items) {
+  const allNode = createTreeNode("all", "All Platforms", 1, false);
+  for (let i = 0; i < items.length; i++) {
+    const platform = items[i].platform;
+    allNode.children.push(createTreeNode(platform, platform, 2, true, [i]));
+    allNode.leafIndices.push(i);
+  }
+  return wrapWithRoot(allNode);
+}
+function createTreeNode(id, name, depth, isLeaf, leafIndices = []) {
+  return { id, name, depth, children: [], leafIndices, isLeaf };
+}
+function wrapWithRoot(allNode) {
+  return { id: "", name: ".", depth: 0, children: [allNode], leafIndices: [...allNode.leafIndices], isLeaf: false };
+}
+function collapseIntermediateNodes(allNode) {
   while (allNode.children.length === 1 && !allNode.children[0].isLeaf && allNode.children[0].children.length > 0) {
     const singleChild = allNode.children[0];
     for (const grandchild of singleChild.children) {
@@ -122,8 +132,6 @@ function buildSkillTree(skills) {
     }
     allNode.children = singleChild.children;
   }
-  const root = { id: "", name: ".", depth: 0, children: [allNode], leafIndices: allNode.leafIndices.slice(), isLeaf: false };
-  return root;
 }
 function adjustDepth(node, delta) {
   node.depth += delta;
@@ -134,28 +142,54 @@ function adjustDepth(node, delta) {
 function flattenTree(root) {
   const result = [];
   function walk(node) {
-    if (node.id !== "") {
-      result.push(node);
-    }
-    for (const child of node.children) {
-      walk(child);
-    }
-  }
-  for (const child of root.children) {
-    walk(child);
+    if (node.id !== "") result.push(node);
+    for (const child of node.children) walk(child);
   }
+  for (const child of root.children) walk(child);
   return result;
 }
-function getNodeState(node, selected) {
+function getNodeSelection(node, selected) {
   const total = node.leafIndices.length;
-  if (total === 0) return "none";
-  let count = 0;
+  if (total === 0) return { state: "none", selectedCount: 0 };
+  let selectedCount = 0;
   for (const idx of node.leafIndices) {
-    if (selected.has(idx)) count++;
+    if (selected.has(idx)) selectedCount++;
   }
-  if (count === 0) return "none";
-  if (count === total) return "all";
-  return "partial";
+  let state = "none";
+  if (selectedCount === total) state = "all";
+  else if (selectedCount > 0) state = "partial";
+  return { state, selectedCount };
+}
+function createRenderer(title, subtitle, flatNodes, selected, getCursor, formatNode) {
+  function renderContent() {
+    const lines = [];
+    lines.push(chalk2.bold.cyan(title));
+    lines.push(chalk2.dim(subtitle));
+    lines.push("");
+    const cursor = getCursor();
+    for (let i = 0; i < flatNodes.length; i++) {
+      const node = flatNodes[i];
+      const selection = getNodeSelection(node, selected);
+      lines.push(formatNode(node, selection, i === cursor));
+    }
+    lines.push("");
+    return lines;
+  }
+  function getLineCount() {
+    return 4 + flatNodes.length;
+  }
+  return { renderContent, getLineCount };
+}
+function writeToTerminal(stdout, lines) {
+  for (const line of lines) {
+    stdout.write(line + "\n");
+  }
+}
+function clearAndRerender(stdout, lineCount, lines) {
+  stdout.write("\x1B[?25l");
+  stdout.write(`\x1B[${lineCount}A`);
+  stdout.write("\x1B[0J");
+  writeToTerminal(stdout, lines);
 }
 async function interactiveTreeSelect(items, options) {
   const { title, subtitle, buildTree, formatNode, defaultAll, defaultSelected } = options;
@@ -178,103 +212,97 @@ async function interactiveTreeSelect(items, options) {
   stdin.setRawMode(true);
   stdin.resume();
   readline.emitKeypressEvents(stdin);
-  function render() {
-    stdout.write("\x1B[?25l");
-    const totalLines = flatNodes.length + 4;
-    stdout.write(`\x1B[${totalLines}A`);
-    stdout.write("\x1B[0J");
-    stdout.write(`
-${chalk2.bold.cyan(title)}
-`);
-    stdout.write(`${chalk2.dim(subtitle)}
-
-`);
-    for (let i = 0; i < flatNodes.length; i++) {
-      const node = flatNodes[i];
-      const state = getNodeState(node, selected);
-      const isCursor = i === cursor;
-      stdout.write(formatNode(node, state, isCursor) + "\n");
-    }
-    stdout.write("\n");
-  }
-  function initialRender() {
-    stdout.write(`
-${chalk2.bold.cyan(title)}
-`);
-    stdout.write(`${chalk2.dim(subtitle)}
-
-`);
-    for (let i = 0; i < flatNodes.length; i++) {
-      const node = flatNodes[i];
-      const state = getNodeState(node, selected);
-      const isCursor = i === cursor;
-      stdout.write(formatNode(node, state, isCursor) + "\n");
-    }
-    stdout.write("\n");
-  }
-  initialRender();
+  const renderer = createRenderer(title, subtitle, flatNodes, selected, () => cursor, formatNode);
+  writeToTerminal(stdout, renderer.renderContent());
   return new Promise((resolve) => {
-    function cleanup() {
+    function cleanup(clear = false) {
+      if (clear) {
+        const lineCount = renderer.getLineCount();
+        stdout.write(`\x1B[${lineCount}A`);
+        stdout.write("\x1B[0J");
+      }
       stdin.setRawMode(wasRaw);
       stdin.pause();
       stdin.removeListener("keypress", onKeypress);
       stdout.write("\x1B[?25h");
     }
+    function rerender() {
+      clearAndRerender(stdout, renderer.getLineCount(), renderer.renderContent());
+    }
+    function toggleNode(node) {
+      const { state } = getNodeSelection(node, selected);
+      if (state === "all") {
+        for (const idx of node.leafIndices) selected.delete(idx);
+      } else {
+        for (const idx of node.leafIndices) selected.add(idx);
+      }
+    }
+    function toggleAll() {
+      if (selected.size === items.length) {
+        selected.clear();
+      } else {
+        for (let i = 0; i < items.length; i++) selected.add(i);
+      }
+    }
     function onKeypress(_str, key) {
       if (key.ctrl && key.name === "c") {
-        cleanup();
+        cleanup(true);
         resolve(null);
         return;
       }
       if (key.name === "return" || key.name === "enter") {
-        cleanup();
-        const result = Array.from(selected);
-        if (result.length === 0) {
-          resolve(null);
-        } else {
-          resolve(result);
-        }
+        cleanup(true);
+        resolve(selected.size > 0 ? Array.from(selected) : null);
         return;
       }
       if (key.name === "up") {
         cursor = (cursor - 1 + flatNodes.length) % flatNodes.length;
-        render();
+        rerender();
         return;
       }
       if (key.name === "down") {
         cursor = (cursor + 1) % flatNodes.length;
-        render();
+        rerender();
         return;
       }
       if (key.name === "space") {
-        const node = flatNodes[cursor];
-        const state = getNodeState(node, selected);
-        if (state === "all") {
-          for (const idx of node.leafIndices) {
-            selected.delete(idx);
-          }
-        } else {
-          for (const idx of node.leafIndices) {
-            selected.add(idx);
-          }
-        }
-        render();
+        toggleNode(flatNodes[cursor]);
+        rerender();
         return;
       }
       if (key.name === "a") {
-        const allSelected = selected.size === items.length;
-        if (allSelected) {
-          selected.clear();
-        } else {
-          for (let i = 0; i < items.length; i++) selected.add(i);
-        }
-        render();
+        toggleAll();
+        rerender();
         return;
       }
     }
     stdin.on("keypress", onKeypress);
   });
 }
+var PLATFORM_DISPLAY = {
+  claude: "Claude",
+  codex: "Codex",
+  copilot: "Copilot",
+  antigravity: "Antigravity"
+};
+function formatTreeNode(node, selection, isCursor, options = {}) {
+  const { state, selectedCount } = selection;
+  const totalCount = node.leafIndices.length;
+  const indent = "  ".repeat(node.depth - 1);
+  const checkbox = state === "all" ? chalk2.green("\u25CF") : state === "partial" ? chalk2.yellow("\u25D0") : chalk2.dim("\u25CB");
+  const name = isCursor ? chalk2.cyan.underline(node.name) : node.name;
+  const cursorMark = isCursor ? chalk2.cyan("\u203A ") : "  ";
+  let count = "";
+  if (totalCount > 1) {
+    count = chalk2.dim(` (${selectedCount}/${totalCount})`);
+  }
+  const suffix = options.suffix || "";
+  let hint = "";
+  if (isCursor && totalCount > 0) {
+    hint = state === "all" ? chalk2.dim(" \u2190 Space to deselect") : chalk2.dim(" \u2190 Space to select");
+  }
+  return `${cursorMark}${indent}${checkbox} ${name}${count}${suffix}${hint}`;
+}
 async function promptSkillsInteractive(skills, options = {}) {
   if (skills.length === 0) return null;
   const targetPlatforms = options.targetPlatforms || [];
@@ -292,100 +320,53 @@ async function promptSkillsInteractive(skills, options = {}) {
     title: "Select skills to install",
     subtitle: "\u2191\u2193 navigate \u2022 Space toggle \u2022 Enter confirm",
     buildTree: buildSkillTree,
-    formatNode: (node, state, isCursor) => {
-      const indent = "  ".repeat(node.depth - 1);
-      const checkbox = state === "all" ? chalk2.green("\u25CF") : state === "partial" ? chalk2.yellow("\u25D0") : chalk2.dim("\u25CB");
-      let installedTag = "";
+    formatNode: (node, selection, isCursor) => {
+      let suffix = "";
       if (node.isLeaf && node.leafIndices.length === 1) {
         const skill = skills[node.leafIndices[0]];
         if (skill?.installedPlatforms?.length) {
           if (skill.installedPlatforms.length === targetPlatforms.length && targetPlatforms.length > 0) {
-            installedTag = chalk2.dim(" [installed]");
+            suffix = chalk2.dim(" [installed]");
           } else if (skill.installedPlatforms.length > 0) {
-            installedTag = chalk2.dim(` [installed on ${skill.installedPlatforms.length}]`);
+            suffix = chalk2.dim(` [installed on ${skill.installedPlatforms.length}]`);
           }
         }
       }
-      const name = isCursor ? chalk2.cyan.underline(node.name) : node.name;
-      const cursor = isCursor ? chalk2.cyan("\u203A ") : "  ";
-      const count = node.leafIndices.length > 1 ? chalk2.dim(` (${node.leafIndices.length})`) : "";
-      let hint = "";
-      if (isCursor && node.leafIndices.length > 0) {
-        if (installedTag && state !== "all") {
-          hint = chalk2.dim(" \u2190 Space to reinstall");
-        } else {
-          hint = state === "all" ? chalk2.dim(" \u2190 Space to deselect") : chalk2.dim(" \u2190 Space to select");
-        }
+      const formatted = formatTreeNode(node, selection, isCursor, { suffix });
+      if (isCursor && suffix && selection.state !== "all") {
+        return formatted.replace("\u2190 Space to select", "\u2190 Space to reinstall");
       }
-      return `${cursor}${indent}${checkbox} ${name}${count}${installedTag}${hint}`;
+      return formatted;
     },
     defaultAll: false,
-    // We handle default selection manually
     defaultSelected
   });
-  if (!selectedIndices || selectedIndices.length === 0) {
-    return null;
-  }
+  if (!selectedIndices) return null;
+  const selectedSkills = selectedIndices.map((i) => skills[i]);
+  const names = selectedSkills.map((s) => s.relPath === "." ? s.suggestedSource : s.relPath);
   console.log(chalk2.green(`
-\u2713 ${selectedIndices.length} skill${selectedIndices.length > 1 ? "s" : ""} selected
+\u2713 Selected ${selectedSkills.length} skill${selectedSkills.length > 1 ? "s" : ""}: ${chalk2.cyan(names.join(", "))}
 `));
-  return selectedIndices.map((i) => skills[i]);
+  return selectedSkills;
 }
 async function promptPlatformsInteractive(options = {}) {
   const platformItems = PLATFORMS.map((p) => ({ platform: p }));
   const selectedIndices = await interactiveTreeSelect(platformItems, {
     title: "Select target platforms",
     subtitle: "\u2191\u2193 navigate \u2022 Space toggle \u2022 Enter confirm",
-    buildTree: (items) => {
-      const allNode = {
-        id: "all",
-        name: "All Platforms",
-        depth: 1,
-        children: [],
-        leafIndices: [],
-        isLeaf: false
-      };
-      for (let i = 0; i < items.length; i++) {
-        const p = items[i].platform;
-        allNode.children.push({
-          id: p,
-          name: p,
-          depth: 2,
-          children: [],
-          leafIndices: [i],
-          isLeaf: true
-        });
-        allNode.leafIndices.push(i);
-      }
-      const root = { id: "", name: ".", depth: 0, children: [allNode], leafIndices: allNode.leafIndices.slice(), isLeaf: false };
-      return root;
-    },
-    formatNode: (node, state, isCursor) => {
-      const indent = "  ".repeat(node.depth - 1);
-      const checkbox = state === "all" ? chalk2.green("\u25CF") : state === "partial" ? chalk2.yellow("\u25D0") : chalk2.dim("\u25CB");
-      let displayName = node.name;
-      if (node.name !== "All Platforms") {
-        const platform = node.name;
-        const display = PLATFORM_DISPLAY[platform];
-        if (display) displayName = display.name;
-      }
-      const name = isCursor ? chalk2.cyan.underline(displayName) : displayName;
-      const cursor = isCursor ? chalk2.cyan("\u203A ") : "  ";
-      const count = node.leafIndices.length > 1 ? chalk2.dim(` (${node.leafIndices.length})`) : "";
-      let hint = "";
-      if (isCursor && node.leafIndices.length > 0) {
-        hint = state === "all" ? chalk2.dim(" \u2190 Space to deselect") : chalk2.dim(" \u2190 Space to select");
-      }
-      return `${cursor}${indent}${checkbox} ${name}${count}${hint}`;
+    buildTree: buildPlatformTree,
+    formatNode: (node, selection, isCursor) => {
+      const displayName = node.name === "All Platforms" ? node.name : PLATFORM_DISPLAY[node.name] || node.name;
+      const modifiedNode = { ...node, name: displayName };
+      return formatTreeNode(modifiedNode, selection, isCursor);
     },
     defaultAll: options.defaultAll !== false
   });
-  if (!selectedIndices || selectedIndices.length === 0) {
-    return null;
-  }
+  if (!selectedIndices) return null;
   const selected = selectedIndices.map((i) => PLATFORMS[i]);
+  const names = selected.map((p) => PLATFORM_DISPLAY[p] || p);
   console.log(chalk2.green(`
-\u2713 Installing to ${selected.length} platform${selected.length > 1 ? "s" : ""}
+\u2713 Installing to ${selected.length} platform${selected.length > 1 ? "s" : ""}: ${chalk2.cyan(names.join(", "))}
 `));
   return selected;
 }
@@ -491,315 +472,381 @@ function asDiscoveredSkills(discovered, toSuggestedSource, toMaterializedDir) {
     materializedDir: toMaterializedDir ? toMaterializedDir(d) : void 0
   }));
 }
-async function install(source, options = {}) {
+function createContext(source, options) {
   const scope = options.local ? "project" : "global";
   const auth = loadRegistryAuth();
-  const registryUrlForDeps = options.registry || auth?.registryUrl;
+  const registryUrl = options.registry || auth?.registryUrl;
   const jsonOnly = Boolean(options.json);
-  const recursive = Boolean(options.recursive);
   const yes = Boolean(options.yes);
-  const maxDepth = parsePositiveInt(options.depth, 6);
-  const maxSkills = parsePositiveInt(options.maxSkills, 200);
   const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY) && !jsonOnly;
-  const requestedAll = Boolean(options.all);
-  const requestedTarget = options.target;
-  if (requestedAll && options.target) {
-    const message = "Invalid options: use either --all or --target, not both.";
-    if (jsonOnly) printJson({ ok: false, error: message });
-    else console.error(chalk3.red(message));
-    process.exitCode = 1;
-    return;
-  }
   let targets = [];
-  let deferPlatformSelection = false;
-  if (requestedAll) {
+  let needsPlatformPrompt = false;
+  if (options.all) {
     targets = [...PLATFORMS2];
-  } else if (requestedTarget) {
-    targets = [requestedTarget];
+  } else if (options.target) {
+    targets = [options.target];
   } else if (yes) {
     targets = [...PLATFORMS2];
   } else if (interactive) {
-    deferPlatformSelection = true;
+    needsPlatformPrompt = true;
     targets = [...PLATFORMS2];
   } else {
     targets = ["claude"];
   }
-  const allPlatformsSelected = targets.length === PLATFORMS2.length;
-  let resolvedSource = source.trim();
+  return {
+    source,
+    options,
+    scope,
+    registryUrl,
+    jsonOnly,
+    interactive,
+    yes,
+    maxDepth: parsePositiveInt(options.depth, 6),
+    maxSkills: parsePositiveInt(options.maxSkills, 200),
+    resolvedSource: source.trim(),
+    targets,
+    forceOverwrite: Boolean(options.force),
+    needsPlatformPrompt,
+    discoveredSkills: null,
+    selectedSkills: null,
+    isSingleSkill: false,
+    materializedDir: null,
+    cleanupMaterialized: null,
+    results: [],
+    errors: [],
+    skipped: [],
+    spinner: null
+  };
+}
+async function resolveSource(ctx) {
+  if (ctx.options.all && ctx.options.target) {
+    const message = "Invalid options: use either --all or --target, not both.";
+    if (ctx.jsonOnly) printJson({ ok: false, error: message });
+    else console.error(chalk3.red(message));
+    process.exitCode = 1;
+    return false;
+  }
+  try {
+    if (looksLikeAlias(ctx.resolvedSource)) {
+      if (ctx.spinner) ctx.spinner.text = `Resolving ${chalk3.cyan(ctx.resolvedSource)}...`;
+      const registryUrl = resolveRegistryUrl(ctx.registryUrl);
+      const resolved = await resolveRegistryAlias(registryUrl, ctx.resolvedSource);
+      if (!ctx.jsonOnly) {
+        logger.info(`Resolved ${chalk3.cyan(ctx.resolvedSource)} \u2192 ${chalk3.cyan(resolved.spec)} (${resolved.type})`);
+      }
+      ctx.resolvedSource = resolved.spec;
+    }
+  } catch (error) {
+    const message = error instanceof SkildError ? error.message : error instanceof Error ? error.message : String(error);
+    if (ctx.jsonOnly) printJson({ ok: false, error: message });
+    else console.error(chalk3.red(message));
+    process.exitCode = 1;
+    return false;
+  }
+  return true;
+}
+async function discoverSkills(ctx) {
+  const { resolvedSource, maxDepth, maxSkills, jsonOnly } = ctx;
+  if (ctx.spinner) {
+    ctx.spinner.text = `Discovery at ${chalk3.cyan(ctx.source)}...`;
+  }
   try {
-    if (looksLikeAlias(resolvedSource)) {
-      const registryUrl = resolveRegistryUrl(registryUrlForDeps);
-      const resolved = await resolveRegistryAlias(registryUrl, resolvedSource);
-      if (!jsonOnly) logger.info(`Resolved ${chalk3.cyan(resolvedSource)} \u2192 ${chalk3.cyan(resolved.spec)} (${resolved.type})`);
-      resolvedSource = resolved.spec;
+    if (resolvedSource.startsWith("@") && resolvedSource.includes("/")) {
+      ctx.isSingleSkill = true;
+      ctx.selectedSkills = [{ relPath: resolvedSource, suggestedSource: resolvedSource }];
+      return true;
+    }
+    const maybeLocalRoot = path2.resolve(resolvedSource);
+    const isLocal = fs2.existsSync(maybeLocalRoot);
+    if (isLocal) {
+      const hasSkillMd2 = fs2.existsSync(path2.join(maybeLocalRoot, "SKILL.md"));
+      if (hasSkillMd2) {
+        ctx.isSingleSkill = true;
+        ctx.selectedSkills = [{ relPath: maybeLocalRoot, suggestedSource: resolvedSource }];
+        return true;
+      }
+      const discovered2 = discoverSkillDirsWithHeuristics(maybeLocalRoot, { maxDepth, maxSkills });
+      if (discovered2.length === 0) {
+        const message = `No SKILL.md found at ${maybeLocalRoot} (or within subdirectories).`;
+        if (jsonOnly) {
+          printJson({ ok: false, error: "SKILL_MD_NOT_FOUND", message, source: ctx.source, resolvedSource });
+        } else {
+          if (ctx.spinner) ctx.spinner.stop();
+          console.error(chalk3.red(message));
+        }
+        process.exitCode = 1;
+        return false;
+      }
+      ctx.discoveredSkills = asDiscoveredSkills(discovered2, (d) => path2.join(maybeLocalRoot, d.relPath));
+      return true;
+    }
+    const materialized = await materializeSourceToTemp(resolvedSource);
+    ctx.materializedDir = materialized.dir;
+    ctx.cleanupMaterialized = materialized.cleanup;
+    const hasSkillMd = fs2.existsSync(path2.join(ctx.materializedDir, "SKILL.md"));
+    if (hasSkillMd) {
+      ctx.isSingleSkill = true;
+      ctx.selectedSkills = [{ relPath: ".", suggestedSource: resolvedSource, materializedDir: ctx.materializedDir }];
+      return true;
+    }
+    const discovered = discoverSkillDirsWithHeuristics(ctx.materializedDir, { maxDepth, maxSkills });
+    if (discovered.length === 0) {
+      const message = `No SKILL.md found in source "${resolvedSource}".`;
+      if (jsonOnly) {
+        printJson({ ok: false, error: "SKILL_MD_NOT_FOUND", message, source: ctx.source, resolvedSource });
+      } else {
+        if (ctx.spinner) ctx.spinner.stop();
+        console.error(chalk3.red(message));
+      }
+      process.exitCode = 1;
+      return false;
     }
+    ctx.discoveredSkills = asDiscoveredSkills(
+      discovered,
+      (d) => deriveChildSource(resolvedSource, d.relPath),
+      (d) => d.absDir
+    );
+    return true;
   } catch (error) {
     const message = error instanceof SkildError ? error.message : error instanceof Error ? error.message : String(error);
     if (jsonOnly) printJson({ ok: false, error: message });
+    else {
+      if (ctx.spinner) ctx.spinner.stop();
+      console.error(chalk3.red(message));
+    }
+    process.exitCode = 1;
+    return false;
+  }
+}
+async function promptSelections(ctx) {
+  const { discoveredSkills, isSingleSkill, jsonOnly, interactive, yes, options } = ctx;
+  if (isSingleSkill) {
+    if (ctx.needsPlatformPrompt) {
+      if (ctx.spinner) ctx.spinner.stop();
+      const selectedPlatforms = await promptPlatformsInteractive({ defaultAll: true });
+      if (!selectedPlatforms) {
+        console.log(chalk3.red("No platforms selected."));
+        process.exitCode = 1;
+        return false;
+      }
+      ctx.targets = selectedPlatforms;
+      ctx.needsPlatformPrompt = false;
+    }
+    return true;
+  }
+  if (!discoveredSkills || discoveredSkills.length === 0) {
+    return false;
+  }
+  if (discoveredSkills.length > ctx.maxSkills) {
+    const message = `Found more than ${ctx.maxSkills} skills. Increase --max-skills to proceed.`;
+    if (jsonOnly) printJson({ ok: false, error: "TOO_MANY_SKILLS", message, source: ctx.source, resolvedSource: ctx.resolvedSource, maxSkills: ctx.maxSkills });
     else console.error(chalk3.red(message));
     process.exitCode = 1;
+    return false;
+  }
+  if (!options.recursive && !yes) {
+    if (jsonOnly) {
+      const foundOutput = discoveredSkills.map(({ relPath, suggestedSource }) => ({ relPath, suggestedSource }));
+      printJson({
+        ok: false,
+        error: "MULTI_SKILL_SOURCE",
+        message: "Source is not a skill root (missing SKILL.md). Multiple skills were found.",
+        source: ctx.source,
+        resolvedSource: ctx.resolvedSource,
+        found: foundOutput
+      });
+      process.exitCode = 1;
+      return false;
+    }
+    if (ctx.spinner) ctx.spinner.stop();
+    const headline = discoveredSkills.length === 1 ? `No SKILL.md found at root. Found 1 skill.
+` : `No SKILL.md found at root. Found ${discoveredSkills.length} skills.
+`;
+    console.log(chalk3.yellow(headline));
+    if (!interactive) {
+      console.log(chalk3.dim(`Tip: rerun with ${chalk3.cyan("skild install <source> --recursive")} to install all.`));
+      process.exitCode = 1;
+      return false;
+    }
+  }
+  if (!yes && interactive) {
+    if (ctx.spinner) ctx.spinner.stop();
+    if (options.recursive) {
+      const headline = discoveredSkills.length === 1 ? `No SKILL.md found at root. Found 1 skill.
+` : `No SKILL.md found at root. Found ${discoveredSkills.length} skills.
+`;
+      console.log(chalk3.yellow(headline));
+    }
+    const selected = await promptSkillsInteractive(discoveredSkills, { defaultAll: true });
+    if (!selected) {
+      console.log(chalk3.red("No skills selected."));
+      process.exitCode = 1;
+      return false;
+    }
+    ctx.selectedSkills = selected;
+    if (ctx.needsPlatformPrompt) {
+      const selectedPlatforms = await promptPlatformsInteractive({ defaultAll: true });
+      if (!selectedPlatforms) {
+        console.log(chalk3.red("No platforms selected."));
+        process.exitCode = 1;
+        return false;
+      }
+      ctx.targets = selectedPlatforms;
+      ctx.needsPlatformPrompt = false;
+    }
+    if (ctx.spinner) ctx.spinner.start();
+  } else {
+    ctx.selectedSkills = discoveredSkills;
+  }
+  return true;
+}
+async function executeInstalls(ctx) {
+  const { selectedSkills, targets, scope, forceOverwrite, registryUrl, spinner } = ctx;
+  if (!selectedSkills || selectedSkills.length === 0) {
     return;
   }
-  const results = [];
-  const errors = [];
-  const skipped = [];
-  let effectiveRecursive = recursive;
-  let recursiveSkillCount = null;
-  let forceOverwriteAll = Boolean(options.force);
-  async function installOne(inputSource, materializedDir) {
-    for (const targetPlatform of targets) {
+  if (spinner) {
+    spinner.text = selectedSkills.length > 1 ? `Installing ${chalk3.cyan(ctx.source)} \u2014 ${selectedSkills.length} skills...` : `Installing ${chalk3.cyan(ctx.source)}...`;
+  }
+  for (const skill of selectedSkills) {
+    if (spinner) {
+      spinner.text = `Installing ${chalk3.cyan(skill.relPath === "." ? ctx.source : skill.relPath)}...`;
+    }
+    for (const platform of targets) {
       try {
-        const record = inputSource.startsWith("@") && inputSource.includes("/") ? await installRegistrySkill(
-          { spec: inputSource, registryUrl: registryUrlForDeps },
-          { platform: targetPlatform, scope, force: forceOverwriteAll }
+        const record = skill.suggestedSource.startsWith("@") && skill.suggestedSource.includes("/") ? await installRegistrySkill(
+          { spec: skill.suggestedSource, registryUrl },
+          { platform, scope, force: forceOverwrite }
         ) : await installSkill(
-          { source: inputSource, materializedDir },
-          { platform: targetPlatform, scope, force: forceOverwriteAll, registryUrl: registryUrlForDeps }
+          { source: skill.suggestedSource, materializedDir: skill.materializedDir },
+          { platform, scope, force: forceOverwrite, registryUrl }
         );
-        results.push(record);
-        void reportDownload(record, registryUrlForDeps);
+        ctx.results.push(record);
+        void reportDownload(record, registryUrl);
       } catch (error) {
         if (error instanceof SkildError && error.code === "ALREADY_INSTALLED") {
           const details = error.details;
-          skipped.push({
-            skillName: details?.skillName || inputSource,
-            platform: targetPlatform,
+          ctx.skipped.push({
+            skillName: details?.skillName || skill.suggestedSource,
+            platform,
             installDir: details?.installDir || ""
           });
           continue;
         }
         const message = error instanceof SkildError ? error.message : error instanceof Error ? error.message : String(error);
-        errors.push({ platform: targetPlatform, error: message, inputSource });
+        ctx.errors.push({ platform, error: message, inputSource: skill.suggestedSource });
       }
     }
   }
-  async function resolveDiscoveredSelection(found, spinner) {
-    if (found.length === 0) return null;
-    if (found.length > maxSkills) {
-      const message = `Found more than ${maxSkills} skills. Increase --max-skills to proceed.`;
-      if (jsonOnly) printJson({ ok: false, error: "TOO_MANY_SKILLS", message, source, resolvedSource, maxSkills });
-      else console.error(chalk3.red(message));
-      process.exitCode = 1;
-      return null;
-    }
-    if (!effectiveRecursive) {
-      if (jsonOnly) {
-        const foundOutput = found.map(({ relPath, suggestedSource }) => ({ relPath, suggestedSource }));
-        printJson({
-          ok: false,
-          error: "MULTI_SKILL_SOURCE",
-          message: "Source is not a skill root (missing SKILL.md). Multiple skills were found.",
-          source,
-          resolvedSource,
-          found: foundOutput
-        });
-        process.exitCode = 1;
-        return null;
-      }
-      if (spinner) spinner.stop();
-      const headline = found.length === 1 ? `No SKILL.md found at root. Found 1 skill.
-` : `No SKILL.md found at root. Found ${found.length} skills.
-`;
-      console.log(chalk3.yellow(headline));
-      if (!interactive && !yes) {
-        console.log(chalk3.dim(`Tip: rerun with ${chalk3.cyan("skild install <source> --recursive")} to install all.`));
-        process.exitCode = 1;
-        return null;
-      }
-      if (!yes) {
-        const selected = await promptSkillsInteractive(found, { defaultAll: true });
-        if (!selected) {
-          console.log(chalk3.red("No skills selected."));
-          process.exitCode = 1;
-          return null;
-        }
-        if (deferPlatformSelection) {
-          const selectedPlatforms = await promptPlatformsInteractive({ defaultAll: true });
-          if (!selectedPlatforms) {
-            console.log(chalk3.red("No platforms selected."));
-            process.exitCode = 1;
-            return null;
-          }
-          targets = selectedPlatforms;
-          deferPlatformSelection = false;
-        }
-        effectiveRecursive = true;
-        if (spinner) spinner.start();
-        recursiveSkillCount = selected.length;
-        return selected;
-      }
-      effectiveRecursive = true;
+}
+function reportResults(ctx) {
+  const { results, errors, skipped, spinner, jsonOnly, selectedSkills, targets } = ctx;
+  if (ctx.cleanupMaterialized) {
+    ctx.cleanupMaterialized();
+  }
+  const isMultiSkill = (selectedSkills?.length ?? 0) > 1;
+  if (jsonOnly) {
+    if (!isMultiSkill && targets.length === 1) {
+      if (errors.length) printJson({ ok: false, error: errors[0]?.error || "Install failed." });
+      else printJson(results[0] ?? null);
+    } else {
+      printJson({
+        ok: errors.length === 0,
+        source: ctx.source,
+        resolvedSource: ctx.resolvedSource,
+        scope: ctx.scope,
+        recursive: isMultiSkill,
+        all: targets.length === PLATFORMS2.length,
+        skillCount: selectedSkills?.length ?? 0,
+        results,
+        errors,
+        skipped
+      });
     }
-    recursiveSkillCount = found.length;
-    return found;
+    process.exitCode = errors.length ? 1 : 0;
+    return;
   }
-  try {
-    const spinner = jsonOnly ? null : createSpinner(
-      allPlatformsSelected ? `Installing ${chalk3.cyan(source)} to ${chalk3.dim("all platforms")} (${scope})...` : targets.length > 1 ? `Installing ${chalk3.cyan(source)} to ${chalk3.dim(`${targets.length} platforms`)} (${scope})...` : `Installing ${chalk3.cyan(source)} to ${chalk3.dim(targets[0])} (${scope})...`
-    );
-    let cleanupMaterialized = null;
-    let materializedRoot = null;
-    try {
-      async function ensurePlatformSelection() {
-        if (!deferPlatformSelection) return true;
-        const selectedPlatforms = await promptPlatformsInteractive({ defaultAll: true });
-        if (!selectedPlatforms) {
-          console.log(chalk3.red("No platforms selected."));
-          process.exitCode = 1;
-          return false;
-        }
-        targets = selectedPlatforms;
-        deferPlatformSelection = false;
-        return true;
-      }
-      if (resolvedSource.startsWith("@") && resolvedSource.includes("/")) {
-        if (!await ensurePlatformSelection()) return;
-        await installOne(resolvedSource);
-      } else {
-        const maybeLocalRoot = path2.resolve(resolvedSource);
-        const isLocal = fs2.existsSync(maybeLocalRoot);
-        if (isLocal) {
-          const hasSkillMd = fs2.existsSync(path2.join(maybeLocalRoot, "SKILL.md"));
-          if (hasSkillMd) {
-            if (!await ensurePlatformSelection()) return;
-            await installOne(resolvedSource);
-          } else {
-            const discovered = discoverSkillDirsWithHeuristics(maybeLocalRoot, { maxDepth, maxSkills });
-            if (discovered.length === 0) {
-              const message = `No SKILL.md found at ${maybeLocalRoot} (or within subdirectories).`;
-              if (jsonOnly) {
-                printJson({ ok: false, error: "SKILL_MD_NOT_FOUND", message, source, resolvedSource });
-              } else {
-                if (spinner) spinner.stop();
-                console.error(chalk3.red(message));
-              }
-              process.exitCode = 1;
-              return;
-            }
-            const found = asDiscoveredSkills(discovered, (d) => path2.join(maybeLocalRoot, d.relPath));
-            const selected = await resolveDiscoveredSelection(found, spinner);
-            if (!selected) return;
-            if (spinner) spinner.text = `Installing ${chalk3.cyan(source)} \u2014 discovered ${selected.length} skills...`;
-            for (const skill of selected) {
-              if (spinner) spinner.text = `Installing ${chalk3.cyan(skill.relPath)} (${scope})...`;
-              await installOne(skill.suggestedSource, skill.materializedDir);
-            }
-          }
-        } else {
-          const materialized = await materializeSourceToTemp(resolvedSource);
-          cleanupMaterialized = materialized.cleanup;
-          materializedRoot = materialized.dir;
-          const hasSkillMd = fs2.existsSync(path2.join(materializedRoot, "SKILL.md"));
-          if (hasSkillMd) {
-            await installOne(resolvedSource, materializedRoot);
-          } else {
-            const discovered = discoverSkillDirsWithHeuristics(materializedRoot, { maxDepth, maxSkills });
-            if (discovered.length === 0) {
-              const message = `No SKILL.md found in source "${resolvedSource}".`;
-              if (jsonOnly) {
-                printJson({ ok: false, error: "SKILL_MD_NOT_FOUND", message, source, resolvedSource });
-              } else {
-                if (spinner) spinner.stop();
-                console.error(chalk3.red(message));
-              }
-              process.exitCode = 1;
-              return;
-            }
-            const found = asDiscoveredSkills(
-              discovered,
-              (d) => deriveChildSource(resolvedSource, d.relPath),
-              (d) => d.absDir
-            );
-            const selected = await resolveDiscoveredSelection(found, spinner);
-            if (!selected) return;
-            if (spinner) spinner.text = `Installing ${chalk3.cyan(source)} \u2014 discovered ${selected.length} skills...`;
-            for (const skill of selected) {
-              if (spinner) spinner.text = `Installing ${chalk3.cyan(skill.relPath)} (${scope})...`;
-              await installOne(skill.suggestedSource, skill.materializedDir);
-            }
-          }
-        }
-      }
-    } finally {
-      if (cleanupMaterialized) cleanupMaterialized();
-    }
-    if (jsonOnly) {
-      if (!effectiveRecursive && targets.length === 1) {
-        if (errors.length) printJson({ ok: false, error: errors[0]?.error || "Install failed." });
-        else printJson(results[0] ?? null);
-      } else {
-        printJson({
-          ok: errors.length === 0,
-          source,
-          resolvedSource,
-          scope,
-          recursive: effectiveRecursive,
-          all: allPlatformsSelected,
-          recursiveSkillCount,
-          results,
-          errors
-        });
-      }
-      process.exitCode = errors.length ? 1 : 0;
-      return;
-    }
-    if (errors.length === 0) {
-      const displayName = results[0]?.canonicalName || results[0]?.name || source;
-      spinner.succeed(
-        effectiveRecursive ? `Installed ${chalk3.green(String(recursiveSkillCount ?? results.length))}${chalk3.dim(" skills")} to ${chalk3.dim(`${targets.length} platforms`)}` : targets.length > 1 ? `Installed ${chalk3.green(displayName)} to ${chalk3.dim(`${results.length} platforms`)}` : `Installed ${chalk3.green(displayName)} to ${chalk3.dim(results[0]?.installDir || "")}`
+  if (errors.length === 0 && (results.length > 0 || skipped.length > 0)) {
+    const displayName = results[0]?.canonicalName || results[0]?.name || ctx.source;
+    if (skipped.length > 0) {
+      spinner?.succeed(
+        `Installed ${chalk3.green(results.length)} and skipped ${chalk3.dim(skipped.length)} (already installed) to ${chalk3.dim(`${targets.length} platforms`)}`
       );
     } else {
-      const attempted = results.length + errors.length;
-      spinner.fail(
-        effectiveRecursive ? `Install had failures (${errors.length}/${attempted} installs failed)` : `Failed to install ${chalk3.red(source)} to ${errors.length}/${targets.length} platforms`
+      spinner?.succeed(
+        isMultiSkill ? `Installed ${chalk3.green(String(selectedSkills?.length ?? results.length))}${chalk3.dim(" skills")} to ${chalk3.dim(`${targets.length} platforms`)}` : targets.length > 1 ? `Installed ${chalk3.green(displayName)} to ${chalk3.dim(`${results.length} platforms`)}` : `Installed ${chalk3.green(displayName)} to ${chalk3.dim(results[0]?.installDir || "")}`
       );
-      process.exitCode = 1;
-      if (!effectiveRecursive && targets.length === 1 && errors[0]) console.error(chalk3.red(errors[0].error));
     }
-    if (!effectiveRecursive && targets.length === 1 && results[0]) {
-      const record = results[0];
-      if (record.hasSkillMd) logger.installDetail("SKILL.md found \u2713");
-      else logger.installDetail("Warning: No SKILL.md found", true);
-      if (record.skill?.validation && !record.skill.validation.ok) {
-        logger.installDetail(`Validation: ${chalk3.yellow("failed")} (${record.skill.validation.issues.length} issues)`, true);
-      } else if (record.skill?.validation?.ok) {
-        logger.installDetail(`Validation: ${chalk3.green("ok")}`);
-      }
-    } else if (effectiveRecursive || targets.length > 1) {
-      for (const r of results.slice(0, 60)) {
-        const displayName = r.canonicalName || r.name;
-        const suffix = r.hasSkillMd ? chalk3.green("\u2713") : chalk3.yellow("\u26A0");
-        console.log(`  ${suffix} ${chalk3.cyan(displayName)} \u2192 ${chalk3.dim(r.platform)}`);
-      }
-      if (results.length > 60) console.log(chalk3.dim(`  ... and ${results.length - 60} more`));
-      if (errors.length) {
-        console.log(chalk3.yellow("\nFailures:"));
-        for (const e of errors) console.log(chalk3.yellow(`  - ${e.platform}: ${e.error}`));
-      }
-      process.exitCode = errors.length ? 1 : 0;
+  } else if (errors.length > 0) {
+    const attempted = results.length + errors.length;
+    spinner?.fail(
+      isMultiSkill ? `Install had failures (${errors.length}/${attempted} installs failed)` : `Failed to install ${chalk3.red(ctx.source)} to ${errors.length}/${targets.length} platforms`
+    );
+    process.exitCode = 1;
+    if (!isMultiSkill && targets.length === 1 && errors[0]) {
+      console.error(chalk3.red(errors[0].error));
     }
-    if (skipped.length > 0) {
-      const uniqueSkills = [...new Set(skipped.map((s) => s.skillName))];
-      console.log(chalk3.dim(`
+  }
+  if (isMultiSkill || targets.length > 1) {
+    for (const r of results.slice(0, 60)) {
+      const displayName = r.canonicalName || r.name;
+      const suffix = r.hasSkillMd ? chalk3.green("\u2713") : chalk3.yellow("\u26A0");
+      console.log(`  ${suffix} ${chalk3.cyan(displayName)} \u2192 ${chalk3.dim(r.platform)}`);
+    }
+    if (results.length > 60) console.log(chalk3.dim(`  ... and ${results.length - 60} more`));
+    if (errors.length) {
+      console.log(chalk3.yellow("\nFailures:"));
+      for (const e of errors) console.log(chalk3.yellow(`  - ${e.platform}: ${e.error}`));
+    }
+    process.exitCode = errors.length ? 1 : 0;
+  } else if (!isMultiSkill && targets.length === 1 && results[0]) {
+    const record = results[0];
+    if (record.hasSkillMd) logger.installDetail("SKILL.md found \u2713");
+    else logger.installDetail("Warning: No SKILL.md found", true);
+    if (record.skill?.validation && !record.skill.validation.ok) {
+      logger.installDetail(`Validation: ${chalk3.yellow("failed")} (${record.skill.validation.issues.length} issues)`, true);
+    } else if (record.skill?.validation?.ok) {
+      logger.installDetail(`Validation: ${chalk3.green("ok")}`);
+    }
+  }
+  if (skipped.length > 0) {
+    const uniqueSkills = [...new Set(skipped.map((s) => s.skillName))];
+    console.log(chalk3.dim(`
 Skipped ${skipped.length} already installed (${uniqueSkills.length} skill${uniqueSkills.length > 1 ? "s" : ""}):`));
-      const bySkill = /* @__PURE__ */ new Map();
-      for (const s of skipped) {
-        const platforms = bySkill.get(s.skillName) || [];
-        platforms.push(s.platform);
-        bySkill.set(s.skillName, platforms);
-      }
-      for (const [skillName, platforms] of bySkill.entries()) {
-        const platformsStr = platforms.length === PLATFORMS2.length ? "all platforms" : platforms.join(", ");
-        console.log(chalk3.dim(`  - ${skillName} (${platformsStr})`));
-      }
-      console.log(chalk3.dim(`
-To reinstall, use: ${chalk3.cyan("skild install <source> --force")}`));
+    const bySkill = /* @__PURE__ */ new Map();
+    for (const s of skipped) {
+      const platforms = bySkill.get(s.skillName) || [];
+      platforms.push(s.platform);
+      bySkill.set(s.skillName, platforms);
+    }
+    for (const [skillName, platforms] of bySkill.entries()) {
+      const platformsStr = platforms.length === PLATFORMS2.length ? "all platforms" : platforms.join(", ");
+      console.log(chalk3.dim(`  - ${skillName} (${platformsStr})`));
     }
+    console.log(chalk3.dim(`
+To reinstall, use: ${chalk3.cyan("skild install <source> --force")}`));
+  }
+}
+async function install(source, options = {}) {
+  const ctx = createContext(source, options);
+  if (!ctx.jsonOnly) {
+    ctx.spinner = createSpinner(`Interpreting ${chalk3.cyan(ctx.source)}...`);
+  }
+  try {
+    if (!await resolveSource(ctx)) return;
+    if (!await discoverSkills(ctx)) return;
+    if (!await promptSelections(ctx)) return;
+    await executeInstalls(ctx);
+    reportResults(ctx);
   } catch (error) {
     const message = error instanceof SkildError ? error.message : error instanceof Error ? error.message : String(error);
-    if (jsonOnly) printJson({ ok: false, error: message });
-    else console.error(chalk3.red(message));
+    if (ctx.jsonOnly) printJson({ ok: false, error: message });
+    else {
+      if (ctx.spinner) ctx.spinner.fail(chalk3.red(message));
+      else console.error(chalk3.red(message));
+    }
     process.exitCode = 1;
+    if (ctx.cleanupMaterialized) ctx.cleanupMaterialized();
   }
 }
 async function reportDownload(record, registryOverride) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skild",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "The npm for Agent Skills — Discover, install, manage, and publish AI Agent Skills with ease.",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,7 +38,7 @@
     "commander": "^12.1.0",
     "ora": "^8.0.1",
     "tar": "^7.4.3",
-    "@skild/core": "^0.4.5"
+    "@skild/core": "^0.4.6"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",