ht-skills 0.1.0

package/README.md

@@ -0,0 +1,17 @@
+# ht-skills
+
+CLI for installing and submitting skills from HT Skills Marketplace.
+
+## Usage
+
+```powershell
+npx ht-skills install repo-bug-analyze --registry http://skills.ic.aeroht.local
+```
+
+## Commands
+
+```text
+ht-skills search <query> [--registry <url>] [--limit <n>]
+ht-skills submit <skillDir> [--registry <url>] [--submitter <name>] [--visibility public|private|shared] [--shared-with a@b.com,c@d.com] [--publish-now]
+ht-skills install <slug[@version]> [--registry <url>] [--target <dir>] [--tool codex|claude|vscode]
+```

package/bin/ht-skills.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+const cli = require("../lib/cli");
+
+cli.main().catch((error) => {
+  // eslint-disable-next-line no-console
+  console.error(`error: ${error.message}`);
+  process.exitCode = 1;
+});

package/lib/cli.js

@@ -0,0 +1,637 @@
+const fs = require("fs/promises");
+const os = require("os");
+const path = require("path");
+const readline = require("readline/promises");
+
+const INSTALL_TARGETS = {
+  codex: {
+    label: "Codex",
+    resolveTarget(homeDir, slug) {
+      return path.join(homeDir, ".codex", "skills", slug);
+    },
+  },
+  claude: {
+    label: "Claude",
+    resolveTarget(homeDir, slug) {
+      return path.join(homeDir, ".claude", "skills", slug);
+    },
+  },
+  vscode: {
+    label: "VS Code",
+    resolveTarget(homeDir, slug) {
+      return path.join(homeDir, ".copilot", "skills", slug);
+    },
+  },
+};
+
+const TOOL_ALIASES = {
+  "claude-code": "claude",
+  "github-copilot": "vscode",
+};
+
+function printHelp() {
+  // eslint-disable-next-line no-console
+  console.log(`Usage:
+  ht-skills search <query> [--registry <url>] [--limit <n>]
+  ht-skills submit <skillDir> [--registry <url>] [--submitter <name>] [--visibility public|private|shared] [--shared-with a@b.com,c@d.com] [--publish-now]
+  ht-skills install <slug[@version]> [--registry <url>] [--target <dir>] [--tool codex|claude|vscode]
+
+Examples:
+  ht-skills search openai --registry http://localhost:8787
+  ht-skills submit ./examples/hello-skill --registry http://localhost:8787
+  ht-skills install hello-skill@1.0.0 --registry http://localhost:8787 --tool codex
+  ht-skills install hello-skill@1.0.0 --registry http://localhost:8787 --tool codex,claude,vscode
+  ht-skills install hello-skill --registry http://localhost:8787`);
+}
+
+function parseArgs(argv) {
+  const result = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith("--")) {
+      result._.push(token);
+      continue;
+    }
+
+    const [key, inlineValue] = token.slice(2).split("=", 2);
+    if (inlineValue !== undefined) {
+      result[key] = inlineValue;
+      continue;
+    }
+
+    const next = argv[i + 1];
+    if (!next || next.startsWith("--")) {
+      result[key] = true;
+      continue;
+    }
+    result[key] = next;
+    i += 1;
+  }
+  return result;
+}
+
+function getRegistryUrl(flags) {
+  return String(flags.registry || process.env.SKILLS_REGISTRY_URL || "http://localhost:8787").replace(/\/$/, "");
+}
+
+async function requestJson(url, options = {}) {
+  const res = await fetch(url, options);
+  const text = await res.text();
+  let payload;
+  try {
+    payload = text ? JSON.parse(text) : {};
+  } catch {
+    payload = { raw: text };
+  }
+  if (!res.ok) {
+    const message = payload.error || text || `HTTP ${res.status}`;
+    throw new Error(message);
+  }
+  return payload;
+}
+
+async function walkFiles(baseDir) {
+  const results = [];
+  const ignored = new Set([".git", "node_modules", ".DS_Store"]);
+
+  async function walk(currentDir) {
+    const entries = await fs.readdir(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (ignored.has(entry.name)) {
+        continue;
+      }
+
+      const absolutePath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(absolutePath);
+      } else if (entry.isFile()) {
+        results.push(absolutePath);
+      }
+    }
+  }
+
+  await walk(baseDir);
+  return results;
+}
+
+function parseSpec(spec) {
+  const [slug, version] = String(spec).split("@", 2);
+  if (!slug) {
+    throw new Error("install requires <slug> or <slug>@<version>");
+  }
+  return { slug, version: version || null };
+}
+
+function getAvailableInstallTargets(slug, { homeDir = os.homedir() } = {}) {
+  return Object.entries(INSTALL_TARGETS).map(([id, target]) => ({
+    id,
+    label: target.label,
+    target: target.resolveTarget(homeDir, slug),
+  }));
+}
+
+function normalizeToolIds(rawTool) {
+  if (!rawTool) return [];
+  const values = Array.isArray(rawTool) ? rawTool : [rawTool];
+  const output = [];
+  const seen = new Set();
+
+  for (const value of values) {
+    const parts = String(value)
+      .split(",")
+      .map((item) => item.trim().toLowerCase())
+      .filter(Boolean);
+
+    for (const part of parts) {
+      if (part === "all" || part === "*") {
+        return Object.keys(INSTALL_TARGETS);
+      }
+      const normalizedPart = TOOL_ALIASES[part] || part;
+      if (!INSTALL_TARGETS[normalizedPart]) {
+        throw new Error(`unknown tool: ${part}`);
+      }
+      if (!seen.has(normalizedPart)) {
+        seen.add(normalizedPart);
+        output.push(normalizedPart);
+      }
+    }
+  }
+
+  return output;
+}
+
+function parseInstallSelection(input, availableTargets) {
+  const trimmed = String(input || "").trim().toLowerCase();
+  if (!trimmed) {
+    return [];
+  }
+  if (trimmed === "all" || trimmed === "*") {
+    return availableTargets.map((item) => item.id);
+  }
+
+  const byNumber = new Map(availableTargets.map((item, index) => [String(index + 1), item.id]));
+  const byId = new Map(availableTargets.map((item) => [item.id, item.id]));
+  const values = trimmed
+    .split(/[,\s]+/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+
+  const result = [];
+  const seen = new Set();
+  for (const value of values) {
+    const resolved = byNumber.get(value) || byId.get(value);
+    if (!resolved) {
+      throw new Error(`unknown selection: ${value}`);
+    }
+    if (!seen.has(resolved)) {
+      seen.add(resolved);
+      result.push(resolved);
+    }
+  }
+  return result;
+}
+
+function resolveInstallTargets({ toolIds, target, slug, version, homeDir = os.homedir() }) {
+  if (target && toolIds.length > 1) {
+    throw new Error("--target can only be used with a single install destination");
+  }
+
+  if (target) {
+    return [{
+      id: toolIds[0] || "custom",
+      label: toolIds[0] ? INSTALL_TARGETS[toolIds[0]].label : "Custom",
+      target: path.resolve(target),
+    }];
+  }
+
+  if (toolIds.length > 0) {
+    return toolIds.map((toolId) => ({
+      id: toolId,
+      label: INSTALL_TARGETS[toolId].label,
+      target: INSTALL_TARGETS[toolId].resolveTarget(homeDir, slug),
+    }));
+  }
+
+  return [{
+    id: "local",
+    label: "Local",
+    target: path.resolve(process.cwd(), "installed-skills", slug, version || "latest"),
+  }];
+}
+
+function formatCount(value, noun) {
+  return `${value} ${noun}${value === 1 ? "" : "s"}`;
+}
+
+function formatInstallSummary(target, colorize = (text) => text) {
+  return `${colorize(target.label, "accent")} ${colorize("->", "muted")} ${target.target}`;
+}
+
+function formatTargetsNote(installTargets, colorize = (text) => text) {
+  return installTargets
+    .map((target, index) => `${colorize(`${index + 1}.`, "muted")} ${formatInstallSummary(target, colorize)}`)
+    .join("\n");
+}
+
+function printFallbackIntro({ registry, slug, version, skillName, skillDescription, installTargets }, log = console.log) {
+  log("");
+  log("ht-skills");
+  log("");
+  log(`Source: ${registry}`);
+  log(`Skill: ${skillName} (${slug}@${version})`);
+  if (skillDescription) {
+    log(skillDescription);
+  }
+  log("");
+  log(`Found ${installTargets.length} install target${installTargets.length === 1 ? "" : "s"}`);
+  for (const line of formatTargetsNote(installTargets).split("\n")) {
+    log(`  ${line}`);
+  }
+  log("");
+}
+
+async function loadTerminalUi() {
+  const [{ intro, outro, note, multiselect, spinner, isCancel, cancel }, pcModule] = await Promise.all([
+    import("@clack/prompts"),
+    import("picocolors"),
+  ]);
+  const pc = pcModule.default || pcModule;
+  return {
+    intro,
+    outro,
+    note,
+    multiselect,
+    spinner,
+    isCancel,
+    cancel,
+    pc,
+  };
+}
+
+function createUiColorizer(pc) {
+  return (text, tone = "default") => {
+    const value = String(text);
+    switch (tone) {
+      case "accent":
+        return pc.cyan(pc.bold(value));
+      case "muted":
+        return pc.dim(value);
+      case "success":
+        return pc.green(value);
+      case "warn":
+        return pc.yellow(value);
+      default:
+        return value;
+    }
+  };
+}
+
+async function selectInstallTargets({ availableTargets, ask = null, ui = null }) {
+  if (ui) {
+    const selection = await ui.multiselect({
+      message: "Which tools do you want to install to?",
+      options: availableTargets.map((target) => ({
+        value: target.id,
+        label: target.label,
+        hint: target.target,
+      })),
+      required: true,
+    });
+
+    if (ui.isCancel(selection)) {
+      ui.cancel("Install cancelled.");
+      const error = new Error("install cancelled");
+      error.cancelled = true;
+      throw error;
+    }
+
+    return selection;
+  }
+
+  while (true) {
+    const answer = await ask("Which tools do you want to install to? (number, name, or 'all'): ");
+    let selected;
+    try {
+      selected = parseInstallSelection(answer, availableTargets);
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.log(`Invalid selection: ${error.message}`);
+      continue;
+    }
+    if (selected.length === 0) {
+      // eslint-disable-next-line no-console
+      console.log("Please choose at least one install target.");
+      continue;
+    }
+    return selected;
+  }
+}
+
+async function writeBundleToTarget(bundle, targetPath) {
+  await fs.mkdir(targetPath, { recursive: true });
+
+  for (const file of bundle.files) {
+    const absolutePath = path.join(targetPath, file.path);
+    await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+    await fs.writeFile(absolutePath, Buffer.from(file.content_base64, "base64"));
+  }
+}
+
+async function fetchResolvedVersion(registry, parsed, requestJsonImpl) {
+  if (parsed.version) {
+    return parsed.version;
+  }
+  const latest = await requestJsonImpl(`${registry}/api/skills/${encodeURIComponent(parsed.slug)}`);
+  if (!latest.latestVersion) {
+    throw new Error(`failed to resolve latest version for ${parsed.slug}`);
+  }
+  return latest.latestVersion;
+}
+
+async function cmdSearch(flags, deps = {}) {
+  const log = deps.log || ((message) => console.log(message));
+  const requestJsonImpl = deps.requestJson || requestJson;
+  const query = flags._.join(" ").trim();
+  if (!query) {
+    throw new Error("search requires a keyword");
+  }
+
+  const registry = getRegistryUrl(flags);
+  const limit = Number(flags.limit || 20);
+  const url = `${registry}/api/skills/search?q=${encodeURIComponent(query)}&limit=${encodeURIComponent(limit)}`;
+  const data = await requestJsonImpl(url);
+
+  if (!data.items || data.items.length === 0) {
+    log("no results");
+    return;
+  }
+
+  for (const item of data.items) {
+    log(`${item.slug}@${item.latestVersion}  ${item.name}  ${item.description || ""}`);
+  }
+}
+
+async function cmdInstall(flags, deps = {}) {
+  const requestJsonImpl = deps.requestJson || requestJson;
+  const ask = deps.ask || null;
+  const isInteractive = typeof deps.isInteractive === "boolean"
+    ? deps.isInteractive
+    : Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const homeDir = deps.homeDir || os.homedir();
+  const log = deps.log || ((message) => console.log(message));
+  const canUseFancyUi = Boolean(isInteractive && !ask && !deps.disableUi);
+  const ui = canUseFancyUi ? await loadTerminalUi().catch(() => null) : null;
+  const colorize = ui ? createUiColorizer(ui.pc) : (text) => String(text);
+  const spec = flags._[0];
+  if (!spec) {
+    throw new Error("install requires a skill spec, for example my-skill@1.0.0");
+  }
+
+  const registry = getRegistryUrl(flags);
+  const parsed = parseSpec(spec);
+
+  const resolveSpinner = ui ? ui.spinner() : null;
+  if (resolveSpinner) {
+    ui.intro(ui.pc.bgCyan(ui.pc.black(" ht-skills ")));
+    resolveSpinner.start(`Resolving ${parsed.slug}`);
+  }
+  const version = await fetchResolvedVersion(registry, parsed, requestJsonImpl);
+  if (resolveSpinner) {
+    resolveSpinner.stop(`Resolved ${parsed.slug}@${version}`);
+  }
+
+  let toolIds = normalizeToolIds(flags.tool);
+  const renderInstallLine = deps.renderInstallLine || ((target) => `installed ${parsed.slug}@${version} -> ${target.target}`);
+  let metadata = null;
+
+  const metadataSpinner = ui ? ui.spinner() : null;
+  if (metadataSpinner) {
+    metadataSpinner.start("Loading skill metadata");
+  }
+  try {
+    metadata = await requestJsonImpl(
+      `${registry}/api/skills/${encodeURIComponent(parsed.slug)}/${encodeURIComponent(version)}`,
+    );
+  } catch {
+    metadata = null;
+  }
+  if (metadataSpinner) {
+    metadataSpinner.stop(metadata?.manifest?.name
+      ? `Loaded ${metadata.manifest.name}`
+      : "Loaded install metadata");
+  }
+
+  const skillName = metadata?.manifest?.name || parsed.slug;
+  const skillDescription = metadata?.manifest?.description || "";
+
+  if (toolIds.length === 0 && !flags.target && isInteractive) {
+    const availableTargets = getAvailableInstallTargets(parsed.slug, { homeDir });
+    if (availableTargets.length > 0 && ui) {
+      ui.note(
+        [
+          `${colorize("Source", "muted")}: ${registry}`,
+          `${colorize("Skill", "muted")}: ${colorize(skillName, "accent")} ${colorize(`(${parsed.slug}@${version})`, "muted")}`,
+          skillDescription ? `${colorize("Summary", "muted")}: ${skillDescription}` : "",
+          "",
+          `${colorize("Available targets", "muted")}:`,
+          formatTargetsNote(availableTargets, colorize),
+        ].filter(Boolean).join("\n"),
+        "Install plan",
+      );
+    } else if (availableTargets.length > 0) {
+      printFallbackIntro({
+        registry,
+        slug: parsed.slug,
+        version,
+        skillName,
+        skillDescription,
+        installTargets: availableTargets,
+      }, log);
+    }
+
+    if (availableTargets.length > 0) {
+      toolIds = await selectInstallTargets({
+        availableTargets,
+        ask: ask || (async (promptText) => {
+          const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+          });
+          try {
+            return await rl.question(promptText);
+          } finally {
+            rl.close();
+          }
+        }),
+        ui,
+      });
+    }
+  }
+
+  const installTargets = resolveInstallTargets({
+    toolIds,
+    target: flags.target,
+    slug: parsed.slug,
+    version,
+    homeDir,
+  });
+
+  if (!ui) {
+    printFallbackIntro({
+      registry,
+      slug: parsed.slug,
+      version,
+      skillName,
+      skillDescription,
+      installTargets,
+    }, log);
+  }
+
+  const bundleSpinner = ui ? ui.spinner() : null;
+  if (bundleSpinner) {
+    bundleSpinner.start("Downloading skill bundle");
+  }
+  const bundle = await requestJsonImpl(
+    `${registry}/api/skills/${encodeURIComponent(parsed.slug)}/${encodeURIComponent(version)}/bundle`,
+  );
+  if (bundleSpinner) {
+    bundleSpinner.stop(`Downloaded ${parsed.slug}@${version}`);
+  }
+
+  const installSpinner = ui ? ui.spinner() : null;
+  if (installSpinner) {
+    installSpinner.start(`Installing to ${formatCount(installTargets.length, "target")}`);
+  }
+
+  for (const target of installTargets) {
+    await writeBundleToTarget(bundle, target.target);
+
+    const metadataPath = path.join(target.target, ".marketplace-install.json");
+    await fs.writeFile(
+      metadataPath,
+      `${JSON.stringify(
+        {
+          slug: parsed.slug,
+          version,
+          installedAt: new Date().toISOString(),
+          registry,
+          checksum: bundle.checksum,
+          tool: target.id,
+        },
+        null,
+        2,
+      )}\n`,
+      "utf8",
+    );
+
+    if (!ui) {
+      log(renderInstallLine(target));
+    }
+  }
+
+  if (installSpinner) {
+    installSpinner.stop(`Installed to ${formatCount(installTargets.length, "target")}`);
+  }
+
+  if (installTargets.length > 0) {
+    if (ui) {
+      ui.note(formatTargetsNote(installTargets, colorize), "Installed to");
+      ui.outro(`Installed ${ui.pc.cyan(parsed.slug)} to ${installTargets.length} target${installTargets.length === 1 ? "" : "s"}.`);
+    } else {
+      log(`Installed ${parsed.slug} to ${formatCount(installTargets.length, "target")}`);
+    }
+  }
+
+  return installTargets;
+}
+
+async function cmdSubmit(flags, deps = {}) {
+  const requestJsonImpl = deps.requestJson || requestJson;
+  const log = deps.log || ((message) => console.log(message));
+  const skillDirArg = flags._[0] || ".";
+  const skillDir = path.resolve(skillDirArg);
+  const manifestPath = path.resolve(flags.manifest || path.join(skillDir, "skill.json"));
+  const manifestRaw = await fs.readFile(manifestPath, "utf8");
+  const manifest = JSON.parse(manifestRaw);
+
+  const filePaths = await walkFiles(skillDir);
+  const files = [];
+  for (const absolutePath of filePaths) {
+    if (path.resolve(absolutePath) === manifestPath) {
+      continue;
+    }
+    const content = await fs.readFile(absolutePath);
+    files.push({
+      path: path.relative(skillDir, absolutePath).replace(/\\/g, "/"),
+      content_base64: content.toString("base64"),
+    });
+  }
+
+  const body = {
+    manifest,
+    files,
+    submitter: String(flags.submitter || process.env.USERNAME || os.userInfo().username || "anonymous"),
+  };
+
+  if (flags.visibility) {
+    body.visibility = String(flags.visibility);
+  }
+  if (flags["shared-with"]) {
+    body.shared_with = String(flags["shared-with"])
+      .split(",")
+      .map((item) => item.trim())
+      .filter(Boolean);
+  }
+  if (flags["publish-now"]) {
+    body.publish_now = true;
+  }
+
+  const registry = getRegistryUrl(flags);
+  const result = await requestJsonImpl(`${registry}/api/skills/submit`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+  log(JSON.stringify(result, null, 2));
+}
+
+async function main(argv = process.argv) {
+  const [, , command, ...rest] = argv;
+  const flags = parseArgs(rest);
+
+  if (!command || command === "help" || command === "--help") {
+    printHelp();
+    return;
+  }
+  if (command === "search") {
+    await cmdSearch(flags);
+    return;
+  }
+  if (command === "install") {
+    await cmdInstall(flags);
+    return;
+  }
+  if (command === "submit") {
+    await cmdSubmit(flags);
+    return;
+  }
+
+  throw new Error(`unknown command: ${command}`);
+}
+
+module.exports = {
+  INSTALL_TARGETS,
+  parseArgs,
+  parseSpec,
+  normalizeToolIds,
+  parseInstallSelection,
+  getAvailableInstallTargets,
+  resolveInstallTargets,
+  fetchResolvedVersion,
+  cmdInstall,
+  cmdSearch,
+  cmdSubmit,
+  main,
+};

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "ht-skills",
+  "version": "0.1.0",
+  "description": "CLI for installing and submitting skills from HT Skills Marketplace.",
+  "type": "commonjs",
+  "bin": {
+    "ht-skills": "./bin/ht-skills.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "picocolors": "^1.1.1"
+  }
+}