skild 0.0.7 → 0.0.8

package/README.md

@@ -12,4 +12,15 @@ npm i -g skild
 
 ```bash
 skild --help
+
+# Install a skill (Git URL / degit shorthand / local dir)
+skild install https://github.com/anthropics/skills/tree/main/skills/pdf
+skild install anthropics/skills/skills/pdf#main
+skild install ./path/to/your-skill
+
+# Target platform + project-level install
+skild install https://github.com/anthropics/skills/tree/main/skills/pdf -t codex --local
+
+# List installed skills
+skild list -t codex --local
 ```

package/dist/index.js

@@ -3,54 +3,124 @@
 // src/index.ts
 import { Command } from "commander";
 import chalk3 from "chalk";
+import { createRequire } from "module";
 
 // src/commands/install.ts
-import { execSync } from "child_process";
-import path2 from "path";
-import fs2 from "fs";
-import chalk from "chalk";
-import ora from "ora";
+import chalk2 from "chalk";
 
-// src/utils/config.ts
-import os from "os";
-import path from "path";
+// src/services/skill-installer.ts
+import degit from "degit";
+import path4 from "path";
+
+// src/utils/fs-helpers.ts
 import fs from "fs";
-function getSkillsDir(platform = "claude", projectLevel = false) {
-  const base = projectLevel ? process.cwd() : os.homedir();
-  switch (platform) {
-    case "claude":
-      return path.join(base, projectLevel ? ".claude" : ".claude", "skills");
-    case "codex":
-      return path.join(base, projectLevel ? ".codex" : ".codex", "skills");
-    case "copilot":
-      return path.join(base, ".github", "skills");
-    default:
-      return path.join(base, ".claude", "skills");
+import path from "path";
+function isDirEmpty(dir) {
+  try {
+    const entries = fs.readdirSync(dir);
+    return entries.length === 0;
+  } catch {
+    return true;
   }
 }
-var SKILLS_DIR = getSkillsDir("claude", false);
-function ensureSkillsDir(platform = "claude", projectLevel = false) {
-  const dir = getSkillsDir(platform, projectLevel);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
+function safeRemoveDir(dir) {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
   }
-  return dir;
 }
-function getSkillPath(skillName, platform = "claude", projectLevel = false) {
-  return path.join(getSkillsDir(platform, projectLevel), skillName);
+function isDirectory(filePath) {
+  try {
+    return fs.statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function pathExists(filePath) {
+  return fs.existsSync(filePath);
+}
+function copyDir(src, dest) {
+  fs.cpSync(src, dest, { recursive: true });
+}
+function hasSkillMd(skillPath) {
+  return fs.existsSync(path.join(skillPath, "SKILL.md"));
+}
+function getSubdirectories(dir) {
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+function sanitizeForPathSegment(value) {
+  return value.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+function createTempDir(parentDir, prefix) {
+  const safePrefix = sanitizeForPathSegment(prefix || "tmp");
+  const template = path.join(parentDir, `.skild-${safePrefix}-`);
+  return fs.mkdtempSync(template);
+}
+function replaceDirAtomic(sourceDir, destDir) {
+  const backupDir = fs.existsSync(destDir) ? `${destDir}.bak-${Date.now()}` : null;
+  try {
+    if (backupDir) {
+      fs.renameSync(destDir, backupDir);
+    }
+    fs.renameSync(sourceDir, destDir);
+    if (backupDir) {
+      safeRemoveDir(backupDir);
+    }
+  } catch (error) {
+    try {
+      if (!fs.existsSync(destDir) && backupDir && fs.existsSync(backupDir)) {
+        fs.renameSync(backupDir, destDir);
+      }
+    } catch {
+    }
+    try {
+      if (fs.existsSync(sourceDir)) {
+        safeRemoveDir(sourceDir);
+      }
+    } catch {
+    }
+    throw error;
+  }
 }
 
-// src/commands/install.ts
+// src/services/source-parser.ts
+import path2 from "path";
+function classifySource(source) {
+  const resolvedPath = path2.resolve(source);
+  if (pathExists(resolvedPath)) {
+    return "local";
+  }
+  if (/^https?:\/\//i.test(source) || source.includes("github.com")) {
+    return "github-url";
+  }
+  if (/^[^/]+\/[^/]+/.test(source)) {
+    return "degit-shorthand";
+  }
+  return "unknown";
+}
 function extractSkillName(url) {
-  const treeMatch = url.match(/\/tree\/[^/]+\/(.+?)(?:\/)?$/);
+  const maybeLocalPath = path2.resolve(url);
+  if (pathExists(maybeLocalPath)) {
+    return path2.basename(maybeLocalPath) || "unknown-skill";
+  }
+  const cleaned = url.replace(/[#?].*$/, "");
+  const treeMatch = cleaned.match(/\/tree\/[^/]+\/(.+?)(?:\/)?$/);
   if (treeMatch) {
     return treeMatch[1].split("/").pop() || "unknown-skill";
   }
-  const repoMatch = url.match(/github\.com\/[^/]+\/([^/]+)/);
+  const repoMatch = cleaned.match(/github\.com\/[^/]+\/([^/]+)/);
   if (repoMatch) {
     return repoMatch[1].replace(/\.git$/, "");
   }
-  return "unknown-skill";
+  const parts = cleaned.split("/").filter(Boolean);
+  if (parts.length >= 2) {
+    return parts[parts.length - 1] || "unknown-skill";
+  }
+  return cleaned || "unknown-skill";
 }
 function toDegitPath(url) {
   const treeMatch = url.match(/github\.com\/([^/]+)\/([^/]+)\/tree\/([^/]+)\/(.+?)(?:\/)?$/);
@@ -64,75 +134,271 @@ function toDegitPath(url) {
   }
   return url;
 }
-async function install(source, options = {}) {
-  const platform = options.target || "claude";
+function resolveLocalPath(source) {
+  const resolvedPath = path2.resolve(source);
+  return pathExists(resolvedPath) ? resolvedPath : null;
+}
+
+// src/utils/config.ts
+import os from "os";
+import path3 from "path";
+import fs2 from "fs";
+
+// src/constants.ts
+var PLATFORMS = ["claude", "codex", "copilot"];
+var DEFAULT_PLATFORM = "claude";
+var ERROR_MESSAGES = {
+  EMPTY_INSTALL_DIR: (source) => `Installed directory is empty for source: ${source}
+Source likely does not point to a valid subdirectory.
+Try: https://github.com/<owner>/<repo>/tree/<branch>/skills/<skill-name>
+Example: https://github.com/anthropics/skills/tree/main/skills/pdf`,
+  INVALID_SOURCE: (source) => `Unsupported source "${source}". Use a Git URL (e.g. https://github.com/owner/repo) or degit shorthand (e.g. owner/repo[/subdir][#ref]).`,
+  NOT_A_DIRECTORY: (path6) => `Source path is not a directory: ${path6}`,
+  NO_SKILLS_INSTALLED: "No skills installed.",
+  INSTALL_HINT: "Use `skild install <url>` to install a skill."
+};
+var SUCCESS_MESSAGES = {
+  SKILL_MD_FOUND: "SKILL.md found \u2713",
+  SKILL_MD_WARNING: "Warning: No SKILL.md found"
+};
+
+// src/utils/config.ts
+function getSkillsDir(platform = DEFAULT_PLATFORM, projectLevel = false) {
+  const base = projectLevel ? process.cwd() : os.homedir();
+  switch (platform) {
+    case "claude":
+      return path3.join(base, ".claude", "skills");
+    case "codex":
+      return path3.join(base, ".codex", "skills");
+    case "copilot":
+      return path3.join(base, ".github", "skills");
+    default:
+      return path3.join(base, ".claude", "skills");
+  }
+}
+var SKILLS_DIR = getSkillsDir(DEFAULT_PLATFORM, false);
+function ensureSkillsDir(platform = DEFAULT_PLATFORM, projectLevel = false) {
+  const dir = getSkillsDir(platform, projectLevel);
+  if (!fs2.existsSync(dir)) {
+    fs2.mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+function getSkillPath(skillName, platform = DEFAULT_PLATFORM, projectLevel = false) {
+  return path3.join(getSkillsDir(platform, projectLevel), skillName);
+}
+
+// src/services/skill-installer.ts
+async function cloneRemote(degitSrc, targetPath) {
+  const emitter = degit(degitSrc, { force: true, verbose: false });
+  await emitter.clone(targetPath);
+}
+function copyLocal(sourcePath, targetPath) {
+  if (!isDirectory(sourcePath)) {
+    throw new Error(ERROR_MESSAGES.NOT_A_DIRECTORY(sourcePath));
+  }
+  copyDir(sourcePath, targetPath);
+}
+function validateStaging(stagingPath, source) {
+  if (isDirEmpty(stagingPath)) {
+    throw new Error(ERROR_MESSAGES.EMPTY_INSTALL_DIR(source));
+  }
+}
+function resolveInstallContext(source, options = {}) {
+  const platform = options.target || DEFAULT_PLATFORM;
   const projectLevel = options.local || false;
-  ensureSkillsDir(platform, projectLevel);
   const skillName = extractSkillName(source);
+  const skillsDir = getSkillsDir(platform, projectLevel);
   const targetPath = getSkillPath(skillName, platform, projectLevel);
-  const degitPath = toDegitPath(source);
   const locationLabel = projectLevel ? "project" : "global";
-  const spinner = ora(`Installing ${chalk.cyan(skillName)} to ${chalk.dim(platform)} (${locationLabel})...`).start();
+  const localPath = resolveLocalPath(source);
+  const sourceType = localPath ? "local" : classifySource(source);
+  if (!localPath && sourceType === "unknown") {
+    throw new Error(ERROR_MESSAGES.INVALID_SOURCE(source));
+  }
+  const degitPath = localPath ? null : toDegitPath(source);
+  return {
+    source,
+    sourceType,
+    localPath,
+    degitPath,
+    skillName,
+    platform,
+    projectLevel,
+    skillsDir,
+    targetPath,
+    locationLabel
+  };
+}
+async function installSkillFromContext(context) {
+  ensureSkillsDir(context.platform, context.projectLevel);
+  const tempRoot = createTempDir(context.skillsDir, context.skillName);
+  const stagingPath = path4.join(tempRoot, "staging");
   try {
-    execSync(`npx degit ${degitPath} "${targetPath}" --force`, {
-      stdio: "pipe"
-    });
-    spinner.succeed(`Installed ${chalk.green(skillName)} to ${chalk.dim(targetPath)}`);
-    const skillMdPath = path2.join(targetPath, "SKILL.md");
-    const hasSkillMd = fs2.existsSync(skillMdPath);
-    if (hasSkillMd) {
-      console.log(chalk.dim(`  \u2514\u2500 SKILL.md found \u2713`));
+    if (context.localPath) {
+      copyLocal(context.localPath, stagingPath);
     } else {
-      console.log(chalk.yellow(`  \u2514\u2500 Warning: No SKILL.md found`));
+      if (!context.degitPath) {
+        throw new Error(ERROR_MESSAGES.INVALID_SOURCE(context.source));
+      }
+      await cloneRemote(context.degitPath, stagingPath);
     }
+    validateStaging(stagingPath, context.source);
+    replaceDirAtomic(stagingPath, context.targetPath);
+    return {
+      skillName: context.skillName,
+      platform: context.platform,
+      projectLevel: context.projectLevel,
+      targetPath: context.targetPath,
+      hasSkillMd: hasSkillMd(context.targetPath)
+    };
+  } finally {
+    safeRemoveDir(tempRoot);
+  }
+}
+
+// src/utils/logger.ts
+import chalk from "chalk";
+import ora from "ora";
+function createSpinner(message) {
+  return ora(message).start();
+}
+var logger = {
+  /**
+   * Log a success message with green checkmark.
+   */
+  success: (message) => {
+    console.log(chalk.green("\u2713"), message);
+  },
+  /**
+   * Log a warning message with yellow color.
+   */
+  warn: (message) => {
+    console.log(chalk.yellow("\u26A0"), message);
+  },
+  /**
+   * Log an error message with red color.
+   */
+  error: (message) => {
+    console.error(chalk.red("\u2717"), message);
+  },
+  /**
+   * Log an info message with cyan color.
+   */
+  info: (message) => {
+    console.log(chalk.cyan("\u2139"), message);
+  },
+  /**
+   * Log a dimmed/subtle message.
+   */
+  dim: (message) => {
+    console.log(chalk.dim(message));
+  },
+  /**
+   * Log a bold header.
+   */
+  header: (message) => {
+    console.log(chalk.bold(message));
+  },
+  /**
+   * Log a skill entry with status indicator.
+   */
+  skillEntry: (name, path6, hasSkillMd2) => {
+    const status = hasSkillMd2 ? chalk.green("\u2713") : chalk.yellow("\u26A0");
+    console.log(`  ${status} ${chalk.cyan(name)}`);
+    console.log(chalk.dim(`    \u2514\u2500 ${path6}`));
+  },
+  /**
+   * Log installation result details.
+   */
+  installDetail: (message, isWarning = false) => {
+    const color = isWarning ? chalk.yellow : chalk.dim;
+    console.log(color(`  \u2514\u2500 ${message}`));
+  }
+};
+
+// src/commands/install.ts
+async function install(source, options = {}) {
+  let context;
+  try {
+    context = resolveInstallContext(source, options);
   } catch (error) {
-    spinner.fail(`Failed to install ${chalk.red(skillName)}`);
-    console.error(chalk.red(error.message || error));
-    process.exit(1);
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(chalk2.red(message));
+    process.exitCode = 1;
+    return;
+  }
+  const spinner = createSpinner(
+    `Installing ${chalk2.cyan(context.skillName)} to ${chalk2.dim(context.platform)} (${context.locationLabel})...`
+  );
+  try {
+    const result = await installSkillFromContext(context);
+    spinner.succeed(`Installed ${chalk2.green(result.skillName)} to ${chalk2.dim(result.targetPath)}`);
+    if (result.hasSkillMd) {
+      logger.installDetail(SUCCESS_MESSAGES.SKILL_MD_FOUND);
+    } else {
+      logger.installDetail(SUCCESS_MESSAGES.SKILL_MD_WARNING, true);
+    }
+  } catch (error) {
+    spinner.fail(`Failed to install ${chalk2.red(context.skillName)}`);
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(chalk2.red(message));
+    process.exitCode = 1;
   }
 }
 
 // src/commands/list.ts
-import fs3 from "fs";
-import path3 from "path";
-import chalk2 from "chalk";
-async function list() {
-  ensureSkillsDir();
-  const entries = fs3.readdirSync(SKILLS_DIR, { withFileTypes: true });
-  const skills = entries.filter((e) => e.isDirectory());
+import path5 from "path";
+async function list(options = {}) {
+  const platform = options.target || DEFAULT_PLATFORM;
+  const projectLevel = options.local || false;
+  const skillsDir = ensureSkillsDir(platform, projectLevel);
+  const skills = getSubdirectories(skillsDir);
   if (skills.length === 0) {
-    console.log(chalk2.dim("No skills installed."));
-    console.log(chalk2.dim(`Use ${chalk2.cyan("skild install <url>")} to install a skill.`));
+    logger.dim(ERROR_MESSAGES.NO_SKILLS_INSTALLED);
+    logger.dim(ERROR_MESSAGES.INSTALL_HINT);
     return;
   }
-  console.log(chalk2.bold(`
-\u{1F4E6} Installed Skills (${skills.length}):
-`));
-  for (const skill of skills) {
-    const skillPath = path3.join(SKILLS_DIR, skill.name);
-    const skillMdPath = path3.join(skillPath, "SKILL.md");
-    const hasSkillMd = fs3.existsSync(skillMdPath);
-    const status = hasSkillMd ? chalk2.green("\u2713") : chalk2.yellow("\u26A0");
-    console.log(`  ${status} ${chalk2.cyan(skill.name)}`);
-    console.log(chalk2.dim(`    \u2514\u2500 ${skillPath}`));
+  const locationLabel = projectLevel ? "project" : "global";
+  logger.header(`
+\u{1F4E6} Installed Skills (${skills.length}) \u2014 ${platform} (${locationLabel}):
+`);
+  for (const skillName of skills) {
+    const skillPath = path5.join(skillsDir, skillName);
+    const hasSkill = hasSkillMd(skillPath);
+    logger.skillEntry(skillName, skillPath, hasSkill);
   }
   console.log("");
 }
 
+// src/types/index.ts
+function isPlatform(value) {
+  return typeof value === "string" && PLATFORMS.includes(value);
+}
+
 // src/index.ts
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
 var program = new Command();
-program.name("skild").description("The npm for Agent Skills \u2014 Discover, install, manage, and publish AI Agent Skills with ease.").version("0.0.1");
-program.command("install <source>").alias("i").description("Install a Skill from a GitHub URL or registry name").option("-t, --target <platform>", "Target platform: claude, codex, copilot", "claude").option("-l, --local", "Install to project-level directory instead of global").action(async (source, options) => {
+program.name("skild").description("The npm for Agent Skills \u2014 Discover, install, manage, and publish AI Agent Skills with ease.").version(version);
+program.command("install <source>").alias("i").description("Install a Skill from a Git URL, degit shorthand, or local directory").option("-t, --target <platform>", "Target platform: claude, codex, copilot", DEFAULT_PLATFORM).option("-l, --local", "Install to project-level directory instead of global").action(async (source, options) => {
+  const platform = isPlatform(options.target) ? options.target : DEFAULT_PLATFORM;
   await install(source, {
-    target: options.target,
+    target: platform,
     local: options.local
   });
 });
-program.command("list").alias("ls").description("List installed Skills").action(async () => {
-  await list();
+program.command("list").alias("ls").description("List installed Skills").option("-t, --target <platform>", "Target platform: claude, codex, copilot", DEFAULT_PLATFORM).option("-l, --local", "List project-level directory instead of global").action(async (options) => {
+  const platform = isPlatform(options.target) ? options.target : DEFAULT_PLATFORM;
+  await list({
+    target: platform,
+    local: options.local
+  });
 });
 program.action(() => {
   console.log(chalk3.bold("\n\u{1F6E1}\uFE0F skild \u2014 Get your agents skilled.\n"));
   program.outputHelp();
 });
-program.parse();
+var argv = process.argv.slice();
+if (argv[2] === "--") argv.splice(2, 1);
+program.parse(argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skild",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "The npm for Agent Skills — Discover, install, manage, and publish AI Agent Skills with ease.",
   "type": "module",
   "main": "./dist/index.js",