@lgtm-hq/ai-skills 0.5.4 → 0.6.0

package/lib/gateway-commands.js

@@ -1,4 +1,5 @@
 import { loadVendors } from "./catalog.js";
+import { getPackageVersion } from "./package-version.js";
 import { pruneMissingLockEntries, readLockfile, writeLockfile } from "./lockfile.js";
 import { resolveScope } from "./options.js";
 import { buildSkillsArguments, buildSkillsRemoveArguments, runSkills } from "./skills-runner.js";
@@ -60,7 +61,7 @@ export async function updateSkills(options, dependencies = {}) {
   );
   await writeLock({
     ...prunedLock,
-    gatewayVersion: process.env.npm_package_version ?? "0.0.0-dev",
+    gatewayVersion: getPackageVersion(),
     skills,
   });
   return { pruned, updated };
@@ -147,7 +148,7 @@ function resolveSources(skills, vendors) {
   for (const [name, entry] of Object.entries(skills)) {
     const source =
       entry.vendor === "lgtm-hq"
-        ? `lgtm-hq/ai-skills@v${process.env.npm_package_version ?? "0.0.0-dev"}`
+        ? `lgtm-hq/ai-skills@v${getPackageVersion()}`
         : resolveVendorSource(entry, vendors);
     sources.set(source, [...(sources.get(source) ?? []), name]);
   }
@@ -180,7 +181,7 @@ function resolveVendorSource(entry, vendors) {
  */
 function sourceSha(vendor, currentSha, vendors) {
   if (vendor === "lgtm-hq") {
-    return `v${process.env.npm_package_version ?? "0.0.0-dev"}`;
+    return `v${getPackageVersion()}`;
   }
   return vendors.find((candidate) => candidate.id === vendor)?.sha ?? currentSha;
 }

package/lib/install.js

@@ -1,107 +1,167 @@
-import { createInterface } from "node:readline/promises";
-import { stdin, stdout } from "node:process";
-
 import { loadBundles, loadVendorIndex, loadVendors } from "./catalog.js";
 import { mergeLockEntries, readLockfile, writeLockfile } from "./lockfile.js";
 import { resolveScope } from "./options.js";
+import { getPackageVersion } from "./package-version.js";
 import { buildSkillsArguments, runSkills } from "./skills-runner.js";
-
-/**
- * Prompt for a numbered item.
- *
- * @template T
- * @param {string} label - Prompt heading.
- * @param {T[]} items - Selectable values.
- * @param {(item: T) => string} describe - Human-readable item formatter.
- * @param {{question: (query: string) => Promise<string>}} prompt - Interactive prompt.
- * @returns {Promise<T>} Selected value.
- */
-async function choose(label, items, describe, prompt) {
-  stdout.write(`${label}\n`);
-  items.forEach((item, index) => stdout.write(`  ${index + 1}. ${describe(item)}\n`));
-  const response = await prompt.question("> ");
-  const selection = Number.parseInt(response, 10) - 1;
-  if (!Number.isInteger(selection) || !items[selection]) {
-    throw new Error("Choose a listed number");
-  }
-  return items[selection];
-}
+import { createClackUi, KNOWN_AGENTS } from "./ui.js";
 
 /**
  * Fill unset install selections through the terminal picker.
  *
+ * Happy path asks for catalog source (+ vendor skill) and agents. Scope defaults
+ * to global, installs symlink (not copy), and uses overwrite for the gateway
+ * fail-closed `--on-conflict` API without prompting — upstream `skills` does
+ * not implement conflict policies yet.
+ *
  * @param {{agents: string[], bundle: string | null, copy: boolean, global: boolean, onConflict: string | null, project: boolean, skills: string[], vendor: string | null, yes: boolean}} options - Initial install options.
- * @param {{question: (query: string) => Promise<string>}} prompt - Interactive prompt.
+ * @param {ReturnType<typeof createClackUi>} [ui] - Injectable interactive UI.
  * @returns {Promise<typeof options>} Fully selected options.
  */
-export async function completeInteractively(options, prompt) {
+export async function completeInteractively(options, ui = createClackUi()) {
+  ui.intro("ai-skills gateway");
+
   const bundles = await loadBundles();
   const vendors = await loadVendors();
-  const source = await choose(
-    "Choose a first-party bundle or vendor catalog:",
-    [
-      ...Object.entries(bundles.groups).map(([id, bundle]) => ({
-        id,
-        kind: "bundle",
-        label: `${bundle.name} — ${bundle.description}`,
-      })),
-      ...vendors.vendors.map((vendor) => ({
-        id: vendor.id,
-        kind: "vendor",
-        label: `${vendor.repo} @ ${vendor.sha.slice(0, 12)}`,
-      })),
-    ],
-    (item) => item.label,
-    prompt,
+  const sourceChoices = [
+    ...Object.entries(bundles.groups).map(([id, bundle]) => ({
+      value: `bundle:${id}`,
+      label: `${bundle.name} — ${bundle.description}`,
+    })),
+    ...vendors.vendors.map((vendor) => ({
+      value: `vendor:${vendor.id}`,
+      label: `${vendor.repo} @ ${vendor.sha.slice(0, 12)}`,
+    })),
+  ];
+
+  const sourceValue = await cancelable(
+    ui,
+    ui.select({
+      message: "Install from which catalog?",
+      options: sourceChoices,
+    }),
   );
+  const [sourceKind, sourceId] = splitSourceValue(sourceValue);
 
-  if (source.kind === "bundle") {
-    const bundle = bundles.groups[source.id];
-    options.bundle = source.id;
+  if (sourceKind === "bundle") {
+    const bundle = bundles.groups[sourceId];
+    options.bundle = sourceId;
     options.skills = bundle.skills;
   } else {
-    const index = await loadVendorIndex(source.id);
-    const skill = await choose(
-      `Choose a skill from ${index.vendor.repo}:`,
-      index.skills,
-      (item) => item.name,
-      prompt,
+    const index = await loadVendorIndex(sourceId);
+    const skillName = await cancelable(
+      ui,
+      ui.select({
+        message: `Skill from ${index.vendor.repo}`,
+        options: index.skills.map((skill) => ({
+          value: skill.name,
+          label: skill.name,
+        })),
+      }),
     );
-    options.vendor = source.id;
-    options.skills = [skill.name];
+    options.vendor = sourceId;
+    options.skills = [skillName];
   }
 
   if (options.agents.length === 0) {
-    const agents = await prompt.question(
-      "Agent(s), comma-separated (blank lets skills CLI detect): ",
-    );
-    options.agents = agents
-      .split(",")
-      .map((agent) => agent.trim())
-      .filter(Boolean);
-  }
-  if (!options.copy) {
-    options.copy = (await prompt.question("Copy files instead of symlink? [y/N] "))
-      .trim()
-      .toLowerCase()
-      .startsWith("y");
-  }
-  if (!options.onConflict) {
-    options.onConflict = await choose(
-      "When an installed skill conflicts:",
-      ["keep", "overwrite", "skip"],
-      (item) => item,
-      prompt,
+    const selected = await cancelable(
+      ui,
+      ui.multiselect({
+        message: "Install into which agents?",
+        options: [
+          ...KNOWN_AGENTS,
+          {
+            value: "__detect__",
+            label: "Detect installed agents (may target many tools)",
+          },
+        ],
+        initialValues: KNOWN_AGENTS.map((agent) => agent.value),
+        required: true,
+      }),
     );
+    if (selected.length === 1 && selected[0] === "__detect__") {
+      options.agents = [];
+      ui.note(
+        "Leaving agents unset so the upstream skills CLI can detect targets.",
+        "Agent detection",
+      );
+    } else {
+      options.agents = selected.filter((agent) => agent !== "__detect__");
+    }
   }
+
   if (!options.global && !options.project) {
-    const scope = await choose("Install scope:", ["global", "project"], (item) => item, prompt);
+    const scope = await cancelable(
+      ui,
+      ui.select({
+        message: "Install scope",
+        options: [
+          { value: "global", label: "Global (user home — recommended)" },
+          { value: "project", label: "Project (this repository)" },
+        ],
+        initialValue: "global",
+      }),
+    );
     options.global = scope === "global";
     options.project = scope === "project";
   }
+
+  // Symlink is the default; only offer copy as an advanced opt-in.
+  if (!options.copy) {
+    const advanced = await cancelable(
+      ui,
+      ui.confirm({
+        message: "Show advanced options (copy files instead of symlink)?",
+        initialValue: false,
+      }),
+    );
+    if (advanced) {
+      options.copy = await cancelable(
+        ui,
+        ui.confirm({
+          message: "Copy files into each agent instead of symlinking from ~/.agents/skills?",
+          initialValue: false,
+        }),
+      );
+    }
+  }
+
+  if (!options.onConflict) {
+    // Gateway still requires an explicit policy for -y; interactive defaults to
+    // overwrite so we do not ask a jargon question for a no-op upstream flag.
+    options.onConflict = "overwrite";
+  }
+
+  ui.outro("Starting install…");
   return options;
 }
 
+/**
+ * Split a `kind:id` catalog selection value.
+ *
+ * @param {string} value - Combined select value.
+ * @returns {[string, string]} Kind and id.
+ */
+function splitSourceValue(value) {
+  const separator = value.indexOf(":");
+  return [value.slice(0, separator), value.slice(separator + 1)];
+}
+
+/**
+ * Abort when Clack reports cancel (Ctrl+C / escape).
+ *
+ * @template T
+ * @param {ReturnType<typeof createClackUi>} ui - UI adapter.
+ * @param {Promise<T>} valuePromise - Pending prompt result.
+ * @returns {Promise<Exclude<T, symbol>>} Resolved non-cancel value.
+ */
+async function cancelable(ui, valuePromise) {
+  const value = await valuePromise;
+  if (ui.isCancel(value)) {
+    throw new Error("Install cancelled");
+  }
+  return /** @type {Exclude<T, symbol>} */ (value);
+}
+
 /**
  * Install a first-party bundle or SHA-pinned vendor skill.
  *
@@ -112,6 +172,11 @@ export async function completeInteractively(options, prompt) {
  * @returns {Promise<void>} Resolves when the skills CLI succeeds.
  */
 export async function install(options, run = runSkills, now = () => new Date(), lockEnvironment) {
+  if (options.onConflict && options.onConflict !== "overwrite") {
+    throw new Error(
+      `--on-conflict=${options.onConflict} is unsupported: upstream skills CLI has no conflict policy. Omit the flag, use overwrite, or remove the existing skill first.`,
+    );
+  }
   let source;
   let selectedOptions = options;
   let vendor;
@@ -141,7 +206,7 @@ export async function install(options, run = runSkills, now = () => new Date(),
         skills: bundle.skills,
       };
     }
-    const packageVersion = process.env.npm_package_version ?? "0.0.0-dev";
+    const packageVersion = getPackageVersion();
     source = `lgtm-hq/ai-skills@v${packageVersion}`;
   }
   const scope = resolveScope(selectedOptions);
@@ -184,7 +249,7 @@ async function createLockEntries(options, vendor, now) {
           agents: options.agents,
           installedAt,
           repo: "lgtm-hq/ai-skills",
-          sha: `v${process.env.npm_package_version ?? "0.0.0-dev"}`,
+          sha: `v${getPackageVersion()}`,
           skillPath: `skills/${name}/SKILL.md`,
           vendor: "lgtm-hq",
         },
@@ -221,10 +286,5 @@ async function createLockEntries(options, vendor, now) {
  * @returns {Promise<void>} Resolves when installation completes.
  */
 export async function installInteractively(options) {
-  const prompt = createInterface({ input: stdin, output: stdout });
-  try {
-    await install(await completeInteractively(options, prompt));
-  } finally {
-    prompt.close();
-  }
+  await install(await completeInteractively(options));
 }

package/lib/lockfile.js

@@ -2,6 +2,8 @@ import { access, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
+import { getPackageVersion } from "./package-version.js";
+
 const LOCKFILE_VERSION = 1;
 
 const AGENT_SKILL_PATHS = {
@@ -156,7 +158,7 @@ export async function isSkillInstalled(name, entry, scope, environment = {}) {
  */
 function createLockfile(scope) {
   return {
-    gatewayVersion: process.env.npm_package_version ?? "0.0.0-dev",
+    gatewayVersion: getPackageVersion(),
     scope,
     skills: {},
     version: LOCKFILE_VERSION,

package/lib/options.js

@@ -1,10 +1,10 @@
 /**
- * Minimum supported version of the upstream skills CLI.
+ * Minimum supported version of the upstream skills CLI (npm package `skills`).
  *
- * Keeping this value in the wrapper makes every invocation reproducible within
- * a compatible major version while allowing upstream patches.
+ * Pin a real published 1.x floor so `bunx skills@^…` resolves. Upstream is on
+ * the 1.x line (there is no 0.16.0). Caret allows compatible 1.x patches.
  */
-export const MINIMUM_SKILLS_VERSION = "0.16.0";
+export const MINIMUM_SKILLS_VERSION = "1.5.0";
 
 /**
  * Parse wrapper command-line arguments.
@@ -113,8 +113,12 @@ export function validateUnattendedOptions(options) {
   if (options.skills.length === 0 && !options.bundle) {
     throw new Error("-y requires at least one --skill for a vendor");
   }
-  if (!options.onConflict) {
-    throw new Error("-y requires --on-conflict=keep, overwrite, or skip");
+  // Upstream `skills` has no conflict policy. Accept omitted/`overwrite` only so
+  // keep|skip cannot silently no-op under a fail-closed API.
+  if (options.onConflict && options.onConflict !== "overwrite") {
+    throw new Error(
+      `--on-conflict=${options.onConflict} is unsupported: upstream skills CLI has no conflict policy. Omit the flag, use overwrite, or remove the existing skill first.`,
+    );
   }
 }
 

package/lib/package-version.js

@@ -0,0 +1,22 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Resolve the gateway package version for install pins and lock metadata.
+ *
+ * `bunx` / direct `node bin/ai-skills.js` do not set `npm_package_version`, so
+ * fall back to the on-disk `package.json` shipped in the published tarball.
+ *
+ * @param {{env?: NodeJS.ProcessEnv, packageJsonPath?: string}} [options] - Injectable paths/env for tests.
+ * @returns {string} Semver package version.
+ */
+export function getPackageVersion(options = {}) {
+  const env = options.env ?? process.env;
+  if (env.npm_package_version) {
+    return env.npm_package_version;
+  }
+  const packageJsonPath =
+    options.packageJsonPath ?? join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+  return JSON.parse(readFileSync(packageJsonPath, "utf8")).version;
+}

package/lib/skills-runner.js

@@ -25,9 +25,9 @@ export function buildSkillsArguments(options, source) {
   if (options.copy) {
     args.push("--copy");
   }
-  if (options.onConflict) {
-    args.push("--on-conflict", options.onConflict);
-  }
+  // Gateway still accepts --on-conflict for unattended fail-closed API stability,
+  // but upstream `skills` (through 1.5.x) does not implement that flag — do not
+  // forward a no-op that implies conflict handling the CLI does not provide.
   if (options.yes) {
     args.push("-y");
   }

package/lib/ui.js

@@ -0,0 +1,37 @@
+import * as clack from "@clack/prompts";
+
+/**
+ * Agents the gateway surfaces in interactive install.
+ *
+ * Keep labels user-facing; values match upstream `skills -a` identifiers.
+ */
+export const KNOWN_AGENTS = [
+  { value: "claude-code", label: "Claude Code (~/.claude/skills)" },
+  { value: "cursor", label: "Cursor (~/.cursor/skills)" },
+  { value: "codex", label: "Codex (~/.codex/skills)" },
+];
+
+/**
+ * Build the default interactive UI (Clack).
+ *
+ * @returns {{
+ *   intro: (message: string) => void,
+ *   outro: (message: string) => void,
+ *   note: (message: string, title?: string) => void,
+ *   select: (options: {message: string, options: {value: string, label: string}[], initialValue?: string}) => Promise<string | symbol>,
+ *   multiselect: (options: {message: string, options: {value: string, label: string}[], initialValues?: string[], required?: boolean}) => Promise<string[] | symbol>,
+ *   confirm: (options: {message: string, initialValue?: boolean}) => Promise<boolean | symbol>,
+ *   isCancel: (value: unknown) => boolean,
+ * }} Interactive UI adapter.
+ */
+export function createClackUi() {
+  return {
+    intro: clack.intro,
+    outro: clack.outro,
+    note: clack.note,
+    select: clack.select,
+    multiselect: clack.multiselect,
+    confirm: clack.confirm,
+    isCancel: clack.isCancel,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lgtm-hq/ai-skills",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Pinned installer gateway for first-party and vendor AI skills.",
   "license": "MIT",
   "homepage": "https://github.com/lgtm-hq/ai-skills#readme",
@@ -28,5 +28,8 @@
   "scripts": {
     "test": "bun test --coverage"
   },
-  "type": "module"
+  "type": "module",
+  "dependencies": {
+    "@clack/prompts": "1.7.0"
+  }
 }