openskillmd 0.2.0 → 0.3.0

package/README.md

@@ -66,6 +66,10 @@ The API base URL is resolved in this order:
 OPENSKILL_API_URL=http://localhost:8080/api osm search testing
 ```
 
+> Maintainers: see [docs/environments-and-releases.md](docs/environments-and-releases.md)
+> for how environments (staging/prod) and release channels (`latest`/`beta`) work —
+> **one CLI, never per-environment packages.**
+
 ## Coming soon
 
 Authenticated publishing (`osm login` / `osm publish`) is in development and not

package/dist/index.js

@@ -7,6 +7,16 @@ import { Command } from "commander";
 import { spawn } from "child_process";
 import { createRequire } from "module";
 import chalk3 from "chalk";
+import ora from "ora";
+
+// src/lib/config.ts
+import { chmod, mkdir, readFile, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+import { z as z2 } from "zod";
+
+// src/lib/env.ts
+import { z } from "zod";
 
 // src/lib/format.ts
 import chalk2 from "chalk";
@@ -89,6 +99,155 @@ function jsonResult(obj) {
   process.stdout.write(JSON.stringify(obj) + "\n");
 }
 
+// src/lib/env.ts
+var envSchema = z.object({
+  OPENSKILL_API_URL: z.preprocess(
+    // An empty string behaved like "unset" before validation existed
+    // (`process.env.X || fallback`); keep that contract.
+    (value) => value === "" ? void 0 : value,
+    z.url(
+      "OPENSKILL_API_URL must be a full URL, e.g. https://staging.openskill.md/api"
+    ).optional()
+  )
+});
+function parseEnv(raw) {
+  const result = envSchema.safeParse(raw);
+  if (!result.success) {
+    const issue = result.error.issues[0];
+    const where = issue?.path.join(".") ?? "environment";
+    return { ok: false, message: `${where}: ${issue?.message ?? "invalid"}` };
+  }
+  return { ok: true, env: result.data };
+}
+var cached;
+function getEnv() {
+  if (cached) return cached;
+  const result = parseEnv(process.env);
+  if (!result.ok) {
+    console.error(
+      errorMessage(
+        result.message,
+        "Fix or unset the variable, then re-run the command."
+      )
+    );
+    process.exit(2);
+  }
+  cached = result.env;
+  return cached;
+}
+
+// src/lib/config.ts
+var CONFIG_DIR = join(homedir(), ".openskill");
+var CONFIG_FILE = join(CONFIG_DIR, "config.json");
+var configSchema = z2.object({
+  token: z2.string().min(1).optional(),
+  email: z2.email().optional(),
+  baseUrl: z2.url().optional()
+});
+async function loadConfig() {
+  let raw;
+  try {
+    raw = await readFile(CONFIG_FILE, "utf-8");
+  } catch {
+    return {};
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    warnInvalidConfig("not valid JSON");
+    return {};
+  }
+  const result = configSchema.safeParse(parsed);
+  if (!result.success) {
+    const issue = result.error.issues[0];
+    warnInvalidConfig(
+      `${issue?.path.join(".") ?? "config"}: ${issue?.message ?? "invalid"}`
+    );
+    return {};
+  }
+  return result.data;
+}
+function warnInvalidConfig(reason) {
+  process.stderr.write(
+    `Warning: ignoring invalid ${CONFIG_FILE} (${reason}) \u2014 re-run \`osm login\` or fix the file.
+`
+  );
+}
+var DEFAULT_API_BASE_URL = "https://staging.openskill.md/api";
+function getApiBaseUrl(config) {
+  const raw = getEnv().OPENSKILL_API_URL || config.baseUrl || DEFAULT_API_BASE_URL;
+  return raw.replace(/\/+$/, "");
+}
+
+// src/lib/api.ts
+var _apiBase;
+async function getApiBase() {
+  if (_apiBase) return _apiBase;
+  const config = await loadConfig();
+  _apiBase = getApiBaseUrl(config);
+  return _apiBase;
+}
+async function resolveApiBase() {
+  return getApiBase();
+}
+async function resolveWebOrigin() {
+  return (await getApiBase()).replace(/\/api\/?$/, "");
+}
+var ApiError = class extends Error {
+  statusCode;
+  constructor(statusCode, message) {
+    super(message);
+    this.name = "ApiError";
+    this.statusCode = statusCode;
+  }
+};
+async function fetchApi(path6) {
+  const base = await getApiBase();
+  const url = `${base}${path6}`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new ApiError(res.status, `API returned ${res.status} for ${path6}`);
+  }
+  return res.json();
+}
+async function searchApi(query) {
+  return fetchApi(`/search?q=${encodeURIComponent(query)}`);
+}
+async function getSkill(slug) {
+  return fetchApi(`/skills/${encodeURIComponent(slug)}`);
+}
+async function getBlueprint(slug) {
+  return fetchApi(`/blueprints/${encodeURIComponent(slug)}`);
+}
+async function getCollections(params) {
+  const qs = new URLSearchParams();
+  if (params?.search) qs.set("search", params.search);
+  qs.set("limit", String(params?.limit ?? 50));
+  const res = await fetchApi(
+    `/collections?${qs.toString()}`
+  );
+  return res.data;
+}
+async function getCollection(slug) {
+  return fetchApi(`/collections/${encodeURIComponent(slug)}`);
+}
+async function listMcpServers(params) {
+  const qs = new URLSearchParams();
+  if (params?.search) qs.set("search", params.search);
+  if (params?.category) qs.set("category", params.category);
+  qs.set("limit", String(params?.limit ?? 50));
+  qs.set("sort", "stars");
+  qs.set("order", "desc");
+  return fetchApi(`/mcp-servers?${qs.toString()}`);
+}
+async function getMcpCategories() {
+  return fetchApi("/mcp-servers/categories");
+}
+async function getMcpServer(slug) {
+  return fetchApi(`/mcp-servers/${encodeURIComponent(slug)}`);
+}
+
 // src/commands/add.ts
 var require2 = createRequire(import.meta.url);
 function stripSkillsBanner(chunk) {
@@ -103,17 +262,64 @@ function validateSource(source) {
     };
   }
   if (!/[/@:.]/.test(source)) {
+    return { ok: false, code: "needs-resolution", slug: source };
+  }
+  return { ok: true };
+}
+async function resolveSlug(slug) {
+  let skill;
+  try {
+    skill = await getSkill(slug);
+  } catch (err) {
+    if (err instanceof ApiError && err.statusCode === 404) {
+      return {
+        ok: false,
+        message: `No skill named "${slug}" in the registry.`,
+        suggestion: "Run `osm search <query>` to find it, or pass owner/repo directly."
+      };
+    }
     return {
       ok: false,
-      code: 2,
-      message: `"${source}" looks like an openskill slug, not a source identifier.`,
-      suggestion: "Use owner/repo@skill (e.g. anthropics/skills@frontend-design) or run `osm search <query>` to find it."
+      message: `Couldn't reach the registry to resolve "${slug}".`,
+      suggestion: "Check your connection (and OPENSKILL_API_URL, if set), or pass owner/repo directly."
     };
   }
-  return { ok: true };
+  const skillName = skill.name || null;
+  if (skill.githubOwner && skill.githubRepo) {
+    const source = `${skill.githubOwner}/${skill.githubRepo}`;
+    return {
+      ok: true,
+      source,
+      skillName,
+      note: skillName ? `resolved ${slug} \u2192 ${source} (skill: ${skillName})` : `resolved ${slug} \u2192 ${source}`
+    };
+  }
+  if (skill.sourceUrl && /^https?:\/\//.test(skill.sourceUrl)) {
+    return {
+      ok: true,
+      source: skill.sourceUrl,
+      skillName,
+      note: skillName ? `resolved ${slug} \u2192 ${skill.sourceUrl} (skill: ${skillName})` : `resolved ${slug} \u2192 ${skill.sourceUrl}`
+    };
+  }
+  return {
+    ok: false,
+    message: `"${slug}" lives only in the OpenSkill registry \u2014 it has no GitHub source to install from yet.`,
+    suggestion: `Run \`osm info ${slug}\` to inspect it.`
+  };
+}
+function toSkillSlug(name) {
+  return name.toLowerCase().replace(/[\s_]+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
 }
-function buildSkillsArgs(source, opts = {}) {
+function buildSkillsArgs(source, opts = {}, skillFilter = null) {
   const args = ["add", source, "-y"];
+  if (skillFilter) {
+    args.push("--skill", skillFilter);
+    const kebab = toSkillSlug(skillFilter);
+    if (kebab && kebab !== skillFilter.toLowerCase()) {
+      args.push("--skill", kebab);
+    }
+  }
   for (const a of opts.agent ?? []) {
     args.push("-a", a);
   }
@@ -121,11 +327,12 @@ function buildSkillsArgs(source, opts = {}) {
   if (opts.copy) args.push("--copy");
   return args;
 }
-function buildJsonResult(source, opts, code, capturedStderr) {
+function buildJsonResult(source, opts, code, capturedStderr, resolvedFrom = null) {
   if (code === 0) {
     return {
       ok: true,
       source,
+      resolvedFrom,
       agent: opts.agent ?? null,
       scope: opts.global ? "user" : "project"
     };
@@ -133,6 +340,7 @@ function buildJsonResult(source, opts, code, capturedStderr) {
   return {
     ok: false,
     source,
+    resolvedFrom,
     error: {
       code: `INSTALL_EXIT_${code}`,
       message: capturedStderr.trim() || "install failed"
@@ -140,10 +348,40 @@ function buildJsonResult(source, opts, code, capturedStderr) {
   };
 }
 async function addCommand(source, opts = {}) {
+  let installSource = source;
+  let resolvedFrom = null;
+  let skillFilter = null;
   const validation = validateSource(source);
   if (!validation.ok) {
-    console.error(errorMessage(validation.message, validation.suggestion));
-    process.exit(validation.code);
+    if (validation.code !== "needs-resolution") {
+      console.error(errorMessage(validation.message, validation.suggestion));
+      process.exit(validation.code);
+    }
+    const spinner = opts.json ? null : ora({
+      text: `Resolving "${validation.slug}" in the registry...`,
+      color: "magenta"
+    }).start();
+    const resolved = await resolveSlug(validation.slug);
+    spinner?.stop();
+    if (!resolved.ok) {
+      if (opts.json) {
+        jsonResult({
+          ok: false,
+          source,
+          resolvedFrom: null,
+          error: { code: "SLUG_RESOLUTION_FAILED", message: resolved.message }
+        });
+      } else {
+        console.error(errorMessage(resolved.message, resolved.suggestion));
+      }
+      process.exit(2);
+    }
+    if (!opts.json) {
+      console.error(chalk3.gray(`  \u2192 ${resolved.note}`));
+    }
+    installSource = resolved.source;
+    resolvedFrom = validation.slug;
+    skillFilter = resolved.skillName;
   }
   let binPath;
   try {
@@ -157,13 +395,16 @@ async function addCommand(source, opts = {}) {
     );
     process.exit(3);
   }
-  const args = buildSkillsArgs(source, opts);
+  const args = buildSkillsArgs(installSource, opts, skillFilter);
   if (!opts.json) {
     console.error(chalk3.gray("  \u2192 fetching skill files\u2026"));
     console.error("");
   }
   const child = spawn(process.execPath, [binPath, ...args], {
     stdio: ["inherit", "pipe", "pipe"],
+    // env.ts carve-out: this is a *write* into the child installer's env
+    // (opting it out of telemetry), not a read of our own config — so it
+    // doesn't go through getEnv().
     env: { ...process.env, DISABLE_TELEMETRY: "1" }
   });
   let capturedStderr = "";
@@ -189,7 +430,9 @@ async function addCommand(source, opts = {}) {
     child.once("error", () => resolve(3));
   });
   if (opts.json) {
-    jsonResult(buildJsonResult(source, opts, code, capturedStderr));
+    jsonResult(
+      buildJsonResult(installSource, opts, code, capturedStderr, resolvedFrom)
+    );
   }
   process.exit(code);
 }
@@ -197,97 +440,7 @@ async function addCommand(source, opts = {}) {
 // src/commands/browse.ts
 import chalk4 from "chalk";
 import inquirer from "inquirer";
-import ora from "ora";
-
-// src/lib/config.ts
-import { readFile, writeFile, mkdir, chmod } from "fs/promises";
-import { join } from "path";
-import { homedir } from "os";
-var CONFIG_DIR = join(homedir(), ".openskill");
-var CONFIG_FILE = join(CONFIG_DIR, "config.json");
-async function loadConfig() {
-  try {
-    const raw = await readFile(CONFIG_FILE, "utf-8");
-    return JSON.parse(raw);
-  } catch {
-    return {};
-  }
-}
-var DEFAULT_API_BASE_URL = "https://staging.openskill.md/api";
-function getApiBaseUrl(config) {
-  const raw = process.env.OPENSKILL_API_URL || config.baseUrl || DEFAULT_API_BASE_URL;
-  return raw.replace(/\/+$/, "");
-}
-
-// src/lib/api.ts
-var _apiBase;
-async function getApiBase() {
-  if (_apiBase) return _apiBase;
-  const config = await loadConfig();
-  _apiBase = getApiBaseUrl(config);
-  return _apiBase;
-}
-async function resolveApiBase() {
-  return getApiBase();
-}
-async function resolveWebOrigin() {
-  return (await getApiBase()).replace(/\/api\/?$/, "");
-}
-var ApiError = class extends Error {
-  statusCode;
-  constructor(statusCode, message) {
-    super(message);
-    this.name = "ApiError";
-    this.statusCode = statusCode;
-  }
-};
-async function fetchApi(path6) {
-  const base = await getApiBase();
-  const url = `${base}${path6}`;
-  const res = await fetch(url);
-  if (!res.ok) {
-    throw new ApiError(res.status, `API returned ${res.status} for ${path6}`);
-  }
-  return res.json();
-}
-async function searchApi(query) {
-  return fetchApi(`/search?q=${encodeURIComponent(query)}`);
-}
-async function getSkill(slug) {
-  return fetchApi(`/skills/${encodeURIComponent(slug)}`);
-}
-async function getBlueprint(slug) {
-  return fetchApi(`/blueprints/${encodeURIComponent(slug)}`);
-}
-async function getCollections(params) {
-  const qs = new URLSearchParams();
-  if (params?.search) qs.set("search", params.search);
-  qs.set("limit", String(params?.limit ?? 50));
-  const res = await fetchApi(
-    `/collections?${qs.toString()}`
-  );
-  return res.data;
-}
-async function getCollection(slug) {
-  return fetchApi(`/collections/${encodeURIComponent(slug)}`);
-}
-async function listMcpServers(params) {
-  const qs = new URLSearchParams();
-  if (params?.search) qs.set("search", params.search);
-  if (params?.category) qs.set("category", params.category);
-  qs.set("limit", String(params?.limit ?? 50));
-  qs.set("sort", "stars");
-  qs.set("order", "desc");
-  return fetchApi(`/mcp-servers?${qs.toString()}`);
-}
-async function getMcpCategories() {
-  return fetchApi("/mcp-servers/categories");
-}
-async function getMcpServer(slug) {
-  return fetchApi(`/mcp-servers/${encodeURIComponent(slug)}`);
-}
-
-// src/commands/browse.ts
+import ora2 from "ora";
 var EXIT_SENTINEL = "__exit__";
 async function browseCommand() {
   try {
@@ -316,7 +469,7 @@ async function browseCommand() {
   }
 }
 async function browseCollections() {
-  const spinner = ora({ text: "Loading collections...", color: "magenta" }).start();
+  const spinner = ora2({ text: "Loading collections...", color: "magenta" }).start();
   const collections = await getCollections({ limit: 50 });
   spinner.stop();
   if (collections.length === 0) {
@@ -338,7 +491,7 @@ async function browseCollections() {
     }
   ]);
   if (slug === EXIT_SENTINEL) return;
-  const detailSpinner = ora({ text: "Loading collection...", color: "magenta" }).start();
+  const detailSpinner = ora2({ text: "Loading collection...", color: "magenta" }).start();
   const collection = await getCollection(slug);
   detailSpinner.stop();
   renderCollection(collection);
@@ -416,7 +569,7 @@ function renderCollection(collection) {
   );
 }
 async function browseMcpServers() {
-  const spinner = ora({ text: "Loading MCP categories...", color: "magenta" }).start();
+  const spinner = ora2({ text: "Loading MCP categories...", color: "magenta" }).start();
   const categories = await getMcpCategories();
   spinner.stop();
   if (categories.length === 0) {
@@ -438,7 +591,7 @@ async function browseMcpServers() {
     }
   ]);
   if (category === EXIT_SENTINEL) return;
-  const listSpinner = ora({ text: "Loading MCP servers...", color: "magenta" }).start();
+  const listSpinner = ora2({ text: "Loading MCP servers...", color: "magenta" }).start();
   const { data: servers } = await listMcpServers({ category, limit: 50 });
   listSpinner.stop();
   process.stderr.write(sectionHeader(`MCP Servers \xB7 ${category}`) + "\n");
@@ -467,9 +620,9 @@ async function browseMcpServers() {
 
 // src/commands/info.ts
 import chalk5 from "chalk";
-import ora2 from "ora";
+import ora3 from "ora";
 async function infoCommand(slug) {
-  const spinner = ora2({ text: `Fetching info for "${slug}"...`, color: "magenta" }).start();
+  const spinner = ora3({ text: `Fetching info for "${slug}"...`, color: "magenta" }).start();
   try {
     const skill = await getSkill(slug);
     spinner.stop();
@@ -633,7 +786,9 @@ import path from "path";
 var SAFE_SLUG_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
 function sanitizeSlug(slug) {
   if (!SAFE_SLUG_PATTERN.test(slug)) {
-    throw new Error(`Invalid slug "${slug}". Slugs must contain only lowercase letters, numbers, hyphens, dots, and underscores.`);
+    throw new Error(
+      `Invalid slug "${slug}". Slugs must contain only lowercase letters, numbers, hyphens, dots, and underscores.`
+    );
   }
   if (slug.includes("..") || slug.includes("/") || slug.includes("\\")) {
     throw new Error(`Invalid slug "${slug}". Path separators are not allowed.`);
@@ -989,9 +1144,9 @@ async function removeCommand(slug) {
 import fs4 from "fs";
 import path5 from "path";
 import chalk10 from "chalk";
-import ora3 from "ora";
+import ora4 from "ora";
 async function routerInstallCommand() {
-  const spinner = ora3({ text: "Downloading OpenSkill router...", color: "magenta" }).start();
+  const spinner = ora4({ text: "Downloading OpenSkill router...", color: "magenta" }).start();
   try {
     const origin = await resolveWebOrigin();
     const res = await fetch(`${origin}/skills/router/SKILL.md`);
@@ -1186,9 +1341,9 @@ async function scoreCommand(filepath) {
 
 // src/commands/search.ts
 import chalk12 from "chalk";
-import ora4 from "ora";
+import ora5 from "ora";
 async function searchCommand(query) {
-  const spinner = ora4({ text: `Searching for "${query}"...`, color: "magenta" }).start();
+  const spinner = ora5({ text: `Searching for "${query}"...`, color: "magenta" }).start();
   try {
     const results = await searchApi(query);
     spinner.stop();
@@ -1273,7 +1428,7 @@ async function searchCommand(query) {
 }
 
 // src/program.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.0";
 var BrandedCommand = class _BrandedCommand extends Command {
   createCommand(name) {
     return new _BrandedCommand(name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openskillmd",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The OpenSkill CLI (osm) — search, add, score, and explore AI agent skills from your terminal",
   "type": "module",
   "bin": {
@@ -54,7 +54,8 @@
     "inquirer": "^12.6.0",
     "open": "^10.2.0",
     "ora": "^8.2.0",
-    "skills": "^1.4.6"
+    "skills": "^1.4.6",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.0.0",