llmond 0.1.0

package/README.md

@@ -0,0 +1,20 @@
+# llmond
+
+Install agent skills, and report the install to [llmond.com](https://llmond.com).
+
+```sh
+npx llmond add owner/repo --skill some-skill
+npx llmond search pdf form filler   # needs LLMOND_API_KEY
+```
+
+`add` is a thin wrapper around the [skills.sh](https://skills.sh) CLI: it runs
+`npx skills@latest add owner/repo` with your terminal attached, and that is what
+does the installing.
+
+On a successful install it posts exactly five fields to `api.llmond.com`:
+`owner`, `repo`, `slug`, `agent`, `cli_version`. Never file contents, never
+paths, never a machine or user identifier. That count is the point of the
+wrapper: skills.sh reports installs only for skills listed there.
+
+Set `LLMOND_NO_TELEMETRY=1` to install with no post at all. `LLMOND_AGENT` sets
+the default `--agent`, `LLMOND_API_URL` points the CLI at another api.

package/bin/lib.mjs

@@ -0,0 +1,92 @@
+// Argument parsing, output shaping and the telemetry payload for the llmond CLI. Kept out
+// of the bin so all of it is unit-testable without spawning anything (../test).
+
+import { readFileSync } from "node:fs";
+
+export const DEFAULT_API_URL = "https://api.llmond.com";
+
+// The version we report as cli_version comes from this package, so a published build can
+// never claim a number other than its own.
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+export const USAGE = `llmond ${VERSION} - install agent skills with usage signals for llmond.com
+
+Usage:
+  llmond add <owner/repo> [--skill <slug>] [--agent <name>] [-y]
+  llmond search <query...>
+  llmond --version
+  llmond --help
+
+Env:
+  LLMOND_API_URL        api base url (default ${DEFAULT_API_URL})
+  LLMOND_API_KEY        api key, needed by search
+  LLMOND_AGENT          default value for --agent
+  LLMOND_NO_TELEMETRY   set to 1 to install without reporting anything`;
+
+export function apiBase(env = {}) {
+  return (env.LLMOND_API_URL || DEFAULT_API_URL).replace(/\/+$/, "");
+}
+
+// EXACTLY the five fields the endpoint takes, and nothing else: no paths, no file
+// contents, no machine or user identifier. The README promises this list, so this is the
+// one place that decides what leaves the machine.
+export function buildTelemetryPayload({ owner, repo, slug, agent, cliVersion }) {
+  const payload = { owner, repo };
+  if (slug) payload.slug = slug;
+  if (agent) payload.agent = agent;
+  if (cliVersion) payload.cli_version = cliVersion;
+  return payload;
+}
+
+export function formatHit(hit) {
+  const id = [hit.owner, hit.repo, hit.slug].filter(Boolean).join("/");
+  return `${id}  ${hit.installs ?? 0} installs  ${hit.stars ?? 0} stars`;
+}
+
+function parseAdd(args, env) {
+  let spec;
+  let slug;
+  let agent = env.LLMOND_AGENT || undefined;
+  let yes = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--skill" || arg === "--agent") {
+      const value = args[++i];
+      if (value === undefined || value.startsWith("-")) return { cmd: "error", message: `${arg} needs a value` };
+      if (arg === "--skill") slug = value;
+      else agent = value;
+    } else if (arg === "-y" || arg === "--yes") {
+      yes = true;
+    } else if (arg.startsWith("-")) {
+      return { cmd: "error", message: `unknown flag: ${arg}` };
+    } else if (spec === undefined) {
+      spec = arg;
+    } else {
+      return { cmd: "error", message: `unexpected argument: ${arg}` };
+    }
+  }
+  if (spec === undefined) return { cmd: "error", message: "add needs an owner/repo" };
+  const parts = spec.split("/");
+  // owner/repo/slug is how the catalog names a skill, so it is the likely typo here; say
+  // what the right form is rather than half-guessing which part was meant as the slug
+  if (parts.length === 3) {
+    const hint = `try: llmond add ${parts[0]}/${parts[1]} --skill ${parts[2]}`;
+    return { cmd: "error", message: `not an owner/repo: ${spec} (${hint})` };
+  }
+  if (parts.length !== 2 || !parts[0] || !parts[1]) return { cmd: "error", message: `not an owner/repo: ${spec}` };
+  return { cmd: "add", owner: parts[0], repo: parts[1], slug, agent, yes };
+}
+
+export function parseArgs(argv, env = {}) {
+  const [command, ...rest] = argv;
+  if (command === "--help" || command === "-h" || command === "help") return { cmd: "help" };
+  if (command === "--version" || command === "-v") return { cmd: "version" };
+  if (command === undefined) return { cmd: "error", message: "no command given" };
+  if (command === "add") return parseAdd(rest, env);
+  if (command === "search") {
+    const query = rest.join(" ").trim();
+    if (!query) return { cmd: "error", message: "search needs a query" };
+    return { cmd: "search", query };
+  }
+  return { cmd: "error", message: `unknown command: ${command}` };
+}

package/bin/llmond.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// llmond - install agent skills, and tell llmond.com that the install happened.
+//
+// The install itself is the skills.sh CLI (`npx skills@latest add ...`), spawned with
+// inherited stdio: this wrapper adds no install logic of its own, and nothing about the
+// installed skill reaches us beyond its name. On a successful install it posts five short
+// fields to api.llmond.com, which is the only install count we own - skills.sh's number
+// stays 0 forever for anything not listed there. LLMOND_NO_TELEMETRY=1 turns the post off.
+
+import { spawnSync } from "node:child_process";
+import { apiBase, buildTelemetryPayload, formatHit, parseArgs, USAGE, VERSION } from "./lib.mjs";
+
+const TELEMETRY_TIMEOUT_MS = 2_000;
+const SEARCH_TIMEOUT_MS = 10_000;
+const SEARCH_LIMIT = 10;
+
+// Fire and forget, in every sense: the response is not read, errors are swallowed, and
+// the install's exit code never depends on any of it.
+async function reportInstall(payload, env) {
+  if (env.LLMOND_NO_TELEMETRY && env.LLMOND_NO_TELEMETRY !== "0") return;
+  try {
+    await fetch(`${apiBase(env)}/v1/telemetry/install`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(TELEMETRY_TIMEOUT_MS),
+    });
+  } catch { /* the skill is already installed; our api being down is not the user's problem */ }
+}
+
+async function runAdd(cmd, env) {
+  // the two -y flags belong to different programs: `-y` is npx's "install it without
+  // asking", `--yes` is the skills CLI's own non-interactive flag, which is the one -y means
+  const args = ["-y", "skills@latest", "add", `${cmd.owner}/${cmd.repo}`];
+  if (cmd.slug) args.push("--skill", cmd.slug);
+  if (cmd.yes) args.push("--yes");
+  const run = spawnSync("npx", args, { stdio: "inherit" });
+  if (run.error) {
+    console.error(`llmond: could not run npx: ${run.error.message}`);
+    return 1;
+  }
+  const code = run.status ?? 1; // a signal kill leaves status null: report it as a failure
+  if (code === 0) await reportInstall(buildTelemetryPayload({ ...cmd, cliVersion: VERSION }), env);
+  return code;
+}
+
+async function runSearch(cmd, env) {
+  const key = env.LLMOND_API_KEY;
+  // /v1/search is keyed, so without one there is nothing to send: say what is missing and
+  // stop, rather than spending a round trip to be told 401 by the server
+  if (!key) {
+    console.error("llmond: search needs an api key - set LLMOND_API_KEY (get one at llmond.com)");
+    return 1;
+  }
+  const url = `${apiBase(env)}/v1/search?q=${encodeURIComponent(cmd.query)}&limit=${SEARCH_LIMIT}`;
+  let res;
+  try {
+    // unlike the telemetry post this one has a person waiting on it, but not forever
+    res = await fetch(url, { headers: { "x-api-key": key }, signal: AbortSignal.timeout(SEARCH_TIMEOUT_MS) });
+  } catch (e) {
+    console.error(`llmond: search failed: ${e.message}`);
+    return 1;
+  }
+  if (!res.ok) {
+    console.error(`llmond: search failed: HTTP ${res.status}`);
+    return 1;
+  }
+  const body = await res.json();
+  for (const hit of body.data ?? []) console.log(formatHit(hit));
+  return 0;
+}
+
+const cmd = parseArgs(process.argv.slice(2), process.env);
+let code = 0;
+if (cmd.cmd === "help") {
+  console.log(USAGE);
+} else if (cmd.cmd === "version") {
+  console.log(VERSION);
+} else if (cmd.cmd === "add") {
+  code = await runAdd(cmd, process.env);
+} else if (cmd.cmd === "search") {
+  code = await runSearch(cmd, process.env);
+} else {
+  console.error(`llmond: ${cmd.message}`);
+  console.error(USAGE);
+  code = 1;
+}
+process.exit(code);

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "llmond",
+  "version": "0.1.0",
+  "description": "Install agent skills with usage signals for llmond.com",
+  "type": "module",
+  "bin": {
+    "llmond": "./bin/llmond.mjs"
+  },
+  "files": [
+    "bin"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mertbuilds/skilldb.git",
+    "directory": "cli"
+  }
+}