aiguild 1.0.0

package/README.md

@@ -0,0 +1,68 @@
+# aiguild CLI
+
+The official command-line tool for [AIGuild](https://aiguild.replit.app) — install and manage AI skills from your terminal.
+
+## Install
+
+```bash
+npm install -g aiguild
+```
+
+Or with pnpm:
+```bash
+pnpm add -g aiguild
+```
+
+## Quick Start
+
+**1. Get your API key**
+
+Go to [AIGuild → Settings → CLI Access](https://aiguild.replit.app/settings) and click **Generate Key**.
+
+**2. Authenticate**
+```bash
+aiguild auth login --key aiguild_xxxxxxxxxxxx
+```
+
+**3. Search and install skills**
+```bash
+aiguild search "sql optimizer"
+aiguild install sql-query-optimizer
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `aiguild auth login --key <key>` | Authenticate with your API key |
+| `aiguild auth logout` | Remove stored credentials |
+| `aiguild auth status` | Check current authentication |
+| `aiguild search [query]` | Search the skill registry |
+| `aiguild install <slug>` | Install a skill to your project |
+| `aiguild uninstall <slug>` | Remove an installed skill |
+| `aiguild info <slug>` | Show skill details |
+| `aiguild list` | List installed skills |
+| `aiguild update --check` | Check for available updates |
+| `aiguild update --all` | Update all outdated skills |
+| `aiguild config` | Show current configuration |
+
+## Options
+
+```bash
+aiguild search --framework crewai    # Filter by framework
+aiguild install my-skill --dir ./skills  # Custom install directory
+aiguild update --check               # Dry run, show available updates only
+```
+
+## Configuration
+
+Config is stored at `~/.aiguild/config.json`. You can also use environment variables:
+
+```bash
+AIGUILD_API_KEY=aiguild_xxx aiguild search
+AIGUILD_API_URL=http://localhost:3000 aiguild search  # Use local server
+```
+
+## Requirements
+
+- Node.js 18 or higher

package/bin/aiguild.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { registerAuth } from "../src/commands/auth.mjs";
+import { registerSearch } from "../src/commands/search.mjs";
+import { registerInfo } from "../src/commands/info.mjs";
+import { registerInstall } from "../src/commands/install.mjs";
+import { registerList } from "../src/commands/list.mjs";
+import { registerUpdate } from "../src/commands/update.mjs";
+import { loadConfig } from "../src/config.mjs";
+
+const pkg = { version: "1.0.0" };
+
+const program = new Command();
+
+program
+  .name("aiguild")
+  .description(
+    [
+      "",
+      "  \x1b[1mAIGuild CLI\x1b[0m — the skills registry for AI developers",
+      "",
+      "  Install, search, and manage AI skills from your terminal.",
+      "  Skills are reusable YAML workflows for LLM agents.",
+      "",
+    ].join("\n")
+  )
+  .version(pkg.version, "-v, --version", "Print version number")
+  .addHelpText(
+    "after",
+    [
+      "",
+      "  \x1b[2mQuick start:\x1b[0m",
+      "    aiguild auth login --key <key>   Authenticate with your API key",
+      "    aiguild search                   Browse the registry",
+      "    aiguild install <slug>           Install a skill",
+      "    aiguild list                     List installed skills",
+      "",
+      "  \x1b[2mGet your API key at: https://aiguild.dev \u2192 Settings \u2192 CLI Access\x1b[0m",
+      "",
+    ].join("\n")
+  );
+
+registerAuth(program);
+registerSearch(program);
+registerInfo(program);
+registerInstall(program);
+registerList(program);
+registerUpdate(program);
+
+// `aiguild config` — show current config
+program
+  .command("config")
+  .description("Show current CLI configuration")
+  .action(() => {
+    const cfg = loadConfig();
+    console.log("\n  \x1b[1mCurrent configuration\x1b[0m\n");
+    console.log(`  API URL    \x1b[36m${cfg.apiUrl || "https://aiguild.replit.app"}\x1b[0m`);
+    const key = cfg.apiKey;
+    if (key) {
+      const masked = key.slice(0, 12) + "•".repeat(Math.max(0, key.length - 16)) + key.slice(-4);
+      console.log(`  API Key    \x1b[36m${masked}\x1b[0m`);
+    } else {
+      console.log(`  API Key    \x1b[2mnot set\x1b[0m`);
+    }
+    const count = Object.keys(cfg.installed || {}).length;
+    console.log(`  Installed  \x1b[36m${count}\x1b[0m skill${count !== 1 ? "s" : ""}\n`);
+  });
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "aiguild",
+  "version": "1.0.0",
+  "description": "AIGuild CLI — install and manage AI skills from your terminal",
+  "type": "module",
+  "bin": {
+    "aiguild": "./bin/aiguild.mjs"
+  },
+  "scripts": {
+    "start": "node ./bin/aiguild.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["aiguild", "ai", "skills", "cli", "llm", "agent"],
+  "license": "MIT",
+  "homepage": "https://aiguild.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AIGuild/aiguild"
+  },
+  "bugs": {
+    "url": "https://github.com/AIGuild/aiguild/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/api.mjs

@@ -0,0 +1,30 @@
+import { getApiUrl } from "./config.mjs";
+
+export async function apiFetch(path, opts = {}) {
+  const url = `${getApiUrl()}${path}`;
+  const res = await fetch(url, {
+    ...opts,
+    headers: {
+      "Content-Type": "application/json",
+      "User-Agent": "aiguild-cli/1.0.0",
+      ...(opts.headers || {}),
+    },
+  });
+  const text = await res.text();
+  let data;
+  try { data = JSON.parse(text); } catch { data = { error: text }; }
+  if (!res.ok) {
+    throw new Error(data?.error || `HTTP ${res.status}`);
+  }
+  return data;
+}
+
+export async function apiAuthFetch(path, apiKey, opts = {}) {
+  return apiFetch(path, {
+    ...opts,
+    headers: {
+      ...(opts.headers || {}),
+      "x-aiguild-key": apiKey,
+    },
+  });
+}

package/src/commands/auth.mjs

@@ -0,0 +1,74 @@
+import { apiFetch, apiAuthFetch } from "../api.mjs";
+import { saveConfig, clearConfig, loadConfig, getApiKey } from "../config.mjs";
+
+export function registerAuth(program) {
+  const auth = program.command("auth").description("Manage CLI authentication");
+
+  auth
+    .command("login")
+    .description("Authenticate with your AIGuild API key")
+    .requiredOption("--key <key>", "Your AIGuild CLI API key (from Settings → CLI Access)")
+    .action(async ({ key }) => {
+      if (!key.startsWith("aiguild_")) {
+        console.error("\x1b[31m✖\x1b[0m Invalid key format. Keys must start with \x1b[36maiguild_\x1b[0m");
+        process.exit(1);
+      }
+      process.stdout.write("  Verifying key...");
+      try {
+        const data = await apiFetch("/api/v1/cli/auth", {
+          method: "POST",
+          body: JSON.stringify({ apiKey: key }),
+        });
+        saveConfig({ apiKey: key });
+        process.stdout.write("\r");
+        console.log(`\x1b[32m✔\x1b[0m Authenticated as \x1b[1m${data.user.username}\x1b[0m`);
+        console.log(`  Rank: \x1b[33m${data.user.rank || "Newcomer"}\x1b[0m  ·  Points: \x1b[36m${data.user.reputationPoints ?? 0}\x1b[0m`);
+        console.log(`  Key saved to \x1b[2m~/.aiguild/config.json\x1b[0m`);
+      } catch (e) {
+        process.stdout.write("\r");
+        console.error(`\x1b[31m✖\x1b[0m Authentication failed: ${e.message}`);
+        process.exit(1);
+      }
+    });
+
+  auth
+    .command("logout")
+    .description("Remove stored credentials")
+    .action(() => {
+      clearConfig();
+      console.log("\x1b[32m✔\x1b[0m Logged out. Config removed from \x1b[2m~/.aiguild/config.json\x1b[0m");
+    });
+
+  auth
+    .command("status")
+    .description("Show current authentication status")
+    .action(async () => {
+      const key = getApiKey();
+      if (!key) {
+        console.log("\x1b[33m○\x1b[0m Not authenticated. Run: \x1b[36maiguild auth login --key <key>\x1b[0m");
+        return;
+      }
+      process.stdout.write("  Checking session...");
+      try {
+        const data = await apiFetch("/api/v1/cli/auth", {
+          method: "POST",
+          body: JSON.stringify({ apiKey: key }),
+        });
+        process.stdout.write("\r");
+        console.log(`\x1b[32m✔\x1b[0m Authenticated as \x1b[1m${data.user.username}\x1b[0m`);
+        console.log(`  Rank: \x1b[33m${data.user.rank || "Newcomer"}\x1b[0m  ·  Points: \x1b[36m${data.user.reputationPoints ?? 0}\x1b[0m`);
+      } catch (e) {
+        process.stdout.write("\r");
+        console.error(`\x1b[31m✖\x1b[0m Session invalid: ${e.message}`);
+        process.exit(1);
+      }
+    });
+
+  auth
+    .command("set-url <url>")
+    .description("Override the AIGuild server URL (default: https://aiguild.replit.app)")
+    .action((url) => {
+      saveConfig({ apiUrl: url });
+      console.log(`\x1b[32m✔\x1b[0m API URL set to \x1b[36m${url}\x1b[0m`);
+    });
+}

package/src/commands/info.mjs

@@ -0,0 +1,52 @@
+import { apiFetch } from "../api.mjs";
+
+export function registerInfo(program) {
+  program
+    .command("info <slug>")
+    .description("Show detailed info about a skill")
+    .action(async (slug) => {
+      process.stdout.write(`  Fetching info for "${slug}"...`);
+      try {
+        const data = await apiFetch(`/api/v1/skills/${encodeURIComponent(slug)}/info`);
+        process.stdout.write("\r");
+        const s = data.skill || data;
+
+        console.log();
+        console.log(`\x1b[1m  ${s.name || s.slug}\x1b[0m  \x1b[2mv${s.version || "1.0.0"}\x1b[0m`);
+        console.log(`  \x1b[2m${s.slug}\x1b[0m`);
+        if (s.description) console.log(`\n  ${s.description}`);
+        console.log();
+
+        const rows = [
+          ["Author",    s.authorUsername || s.author || "—"],
+          ["Trust",     trustLabel(s.trustStatus)],
+          ["Installs",  String(s.installCount || 0)],
+          ["Framework", s.compatibleAgents?.join(", ") || "any"],
+          ["Tags",      (s.tags || []).join(", ") || "—"],
+          ["License",   s.license || "MIT"],
+        ];
+        for (const [label, value] of rows) {
+          console.log(`  \x1b[2m${label.padEnd(10)}\x1b[0m  ${value}`);
+        }
+
+        if (s.yamlContent || s.content) {
+          console.log(`\n  \x1b[33mYAML Preview:\x1b[0m`);
+          const lines = (s.yamlContent || s.content || "").split("\n").slice(0, 8);
+          for (const line of lines) console.log(`    \x1b[2m${line}\x1b[0m`);
+          if ((s.yamlContent || s.content || "").split("\n").length > 8) console.log(`    \x1b[2m...\x1b[0m`);
+        }
+
+        console.log(`\n  \x1b[2mInstall: aiguild install ${s.slug}\x1b[0m`);
+      } catch (e) {
+        process.stdout.write("\r");
+        console.error(`\x1b[31m✖\x1b[0m Skill not found: ${e.message}`);
+        process.exit(1);
+      }
+    });
+}
+
+function trustLabel(status) {
+  if (status === "master_verified") return "\x1b[33m★ Master Verified\x1b[0m";
+  if (status === "peer_reviewed")   return "\x1b[36m✓ Peer Reviewed\x1b[0m";
+  return "Community";
+}

package/src/commands/install.mjs

@@ -0,0 +1,84 @@
+import fs from "fs";
+import path from "path";
+import { apiFetch } from "../api.mjs";
+import { requireAuth, loadConfig, saveConfig } from "../config.mjs";
+
+const INSTALL_DIR_DEFAULT = path.join(process.cwd(), ".aiguild", "skills");
+
+function getInstallDir(opts) {
+  return opts.dir
+    ? path.resolve(opts.dir)
+    : (loadConfig().installDir || INSTALL_DIR_DEFAULT);
+}
+
+function loadInstalled() {
+  const cfg = loadConfig();
+  return cfg.installed || {};
+}
+
+function saveInstalled(installed) {
+  saveConfig({ installed });
+}
+
+export function registerInstall(program) {
+  program
+    .command("install <slug>")
+    .description("Download and install a skill to your project")
+    .option("-d, --dir <path>", "Target directory (default: ./.aiguild/skills)")
+    .option("--version <ver>", "Install a specific version")
+    .action(async (slug, opts) => {
+      requireAuth();
+      const installDir = getInstallDir(opts);
+      fs.mkdirSync(installDir, { recursive: true });
+
+      process.stdout.write(`  Fetching \x1b[36m${slug}\x1b[0m...`);
+      try {
+        const params = opts.version ? `?version=${encodeURIComponent(opts.version)}` : "";
+        const data = await apiFetch(`/api/v1/skills/${encodeURIComponent(slug)}/download${params}`);
+        process.stdout.write("\r");
+
+        const skill = data.skill || data;
+        const version = data.version || skill.currentVersion || "1.0.0";
+        const content = data.content || skill.yamlContent || "";
+        const filename = `${slug}.yaml`;
+        const filePath = path.join(installDir, filename);
+
+        fs.writeFileSync(filePath, content, "utf8");
+
+        const installed = loadInstalled();
+        installed[slug] = {
+          version,
+          installedAt: new Date().toISOString(),
+          path: filePath,
+        };
+        saveInstalled(installed);
+
+        console.log(`\x1b[32m✔\x1b[0m Installed \x1b[1m${skill.name || slug}\x1b[0m  \x1b[2mv${version}\x1b[0m`);
+        console.log(`  \x1b[2m→ ${filePath}\x1b[0m`);
+        if (skill.compatibleAgents?.length) {
+          console.log(`  Compatible with: \x1b[36m${skill.compatibleAgents.join(", ")}\x1b[0m`);
+        }
+      } catch (e) {
+        process.stdout.write("\r");
+        console.error(`\x1b[31m✖\x1b[0m Install failed: ${e.message}`);
+        process.exit(1);
+      }
+    });
+
+  program
+    .command("uninstall <slug>")
+    .description("Remove an installed skill")
+    .option("-d, --dir <path>", "Skills directory")
+    .action(async (slug, opts) => {
+      const installed = loadInstalled();
+      if (!installed[slug]) {
+        console.error(`\x1b[31m✖\x1b[0m "${slug}" is not installed`);
+        process.exit(1);
+      }
+      const record = installed[slug];
+      try { fs.unlinkSync(record.path); } catch {}
+      delete installed[slug];
+      saveInstalled(installed);
+      console.log(`\x1b[32m✔\x1b[0m Uninstalled \x1b[1m${slug}\x1b[0m`);
+    });
+}

package/src/commands/list.mjs

@@ -0,0 +1,24 @@
+import { loadConfig } from "../config.mjs";
+
+export function registerList(program) {
+  program
+    .command("list")
+    .alias("ls")
+    .description("List locally installed skills")
+    .action(() => {
+      const installed = loadConfig().installed || {};
+      const slugs = Object.keys(installed);
+      if (!slugs.length) {
+        console.log("\x1b[33m○\x1b[0m No skills installed yet. Try: \x1b[36maiguild search\x1b[0m");
+        return;
+      }
+      console.log(`\n  \x1b[1m${slugs.length}\x1b[0m skill${slugs.length !== 1 ? "s" : ""} installed:\n`);
+      for (const slug of slugs) {
+        const { version, installedAt, path: filePath } = installed[slug];
+        const date = installedAt ? new Date(installedAt).toLocaleDateString() : "—";
+        console.log(`  \x1b[1m${slug}\x1b[0m  \x1b[2mv${version}  ·  installed ${date}\x1b[0m`);
+        if (filePath) console.log(`  \x1b[2m  ${filePath}\x1b[0m`);
+        console.log();
+      }
+    });
+}

package/src/commands/search.mjs

@@ -0,0 +1,60 @@
+import { apiFetch } from "../api.mjs";
+
+function formatTrustBadge(status) {
+  if (status === "master_verified") return "\x1b[33m★ Master\x1b[0m";
+  if (status === "peer_reviewed")  return "\x1b[36m✓ Peer\x1b[0m";
+  return "\x1b[2m○ Community\x1b[0m";
+}
+
+function formatInstallCount(n) {
+  if (!n) return "0";
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
+  return String(n);
+}
+
+export function registerSearch(program) {
+  program
+    .command("search [query]")
+    .description("Search for skills in the AIGuild registry")
+    .option("-f, --framework <framework>", "Filter by framework (crewai, langgraph, n8n, langflow)")
+    .option("-t, --tag <tag>", "Filter by tag")
+    .option("-n, --limit <n>", "Max results to show", "10")
+    .action(async (query, opts) => {
+      const params = new URLSearchParams();
+      if (query) params.set("q", query);
+      if (opts.framework) params.set("framework", opts.framework);
+      if (opts.tag) params.set("tag", opts.tag);
+      params.set("limit", opts.limit);
+      params.set("trustStatus", "all");
+
+      process.stdout.write("  Searching...");
+      try {
+        const data = await apiFetch(`/api/v1/skills/search?${params}`);
+        process.stdout.write("\r");
+        const skills = data.skills || data;
+        if (!skills.length) {
+          console.log(`\x1b[33m○\x1b[0m No skills found${query ? ` for "${query}"` : ""}`);
+          return;
+        }
+        console.log(`\n  Found \x1b[1m${skills.length}\x1b[0m skill${skills.length !== 1 ? "s" : ""}${query ? ` matching "${query}"` : ""}:\n`);
+        for (const s of skills) {
+          const badge = formatTrustBadge(s.trustStatus);
+          const installs = formatInstallCount(s.installCount);
+          console.log(`  \x1b[1m${s.slug}\x1b[0m  ${badge}  \x1b[2m↓${installs}\x1b[0m`);
+          if (s.name && s.name !== s.slug) console.log(`    \x1b[2m${s.name}\x1b[0m`);
+          if (s.description) {
+            const desc = s.description.length > 80 ? s.description.slice(0, 77) + "..." : s.description;
+            console.log(`    ${desc}`);
+          }
+          const tags = (s.tags || []).slice(0, 4).join("  ");
+          if (tags) console.log(`    \x1b[36m${tags}\x1b[0m`);
+          console.log();
+        }
+        console.log(`  \x1b[2mInstall with: aiguild install <slug>\x1b[0m`);
+      } catch (e) {
+        process.stdout.write("\r");
+        console.error(`\x1b[31m✖\x1b[0m Search failed: ${e.message}`);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/update.mjs

@@ -0,0 +1,78 @@
+import { apiFetch } from "../api.mjs";
+import { requireAuth, loadConfig, saveConfig } from "../config.mjs";
+import fs from "fs";
+
+export function registerUpdate(program) {
+  program
+    .command("update [slug]")
+    .description("Update installed skills. Omit slug to check all.")
+    .option("--check", "Only show available updates, don't install")
+    .option("--all", "Update all outdated skills")
+    .action(async (slug, opts) => {
+      requireAuth();
+      const installed = loadConfig().installed || {};
+      const targets = slug
+        ? (installed[slug] ? { [slug]: installed[slug] } : null)
+        : installed;
+
+      if (!targets) {
+        console.error(`\x1b[31m✖\x1b[0m "${slug}" is not installed`);
+        process.exit(1);
+      }
+      const slugs = Object.keys(targets);
+      if (!slugs.length) {
+        console.log("\x1b[33m○\x1b[0m No skills installed. Run: \x1b[36maiguild install <slug>\x1b[0m");
+        return;
+      }
+
+      process.stdout.write("  Checking for updates...");
+      try {
+        const data = await apiFetch("/api/v1/skills/installed/updates", {
+          method: "POST",
+          body: JSON.stringify({
+            installed: slugs.map((s) => ({ slug: s, version: targets[s].version })),
+          }),
+        });
+        process.stdout.write("\r");
+
+        const updates = data.updates || [];
+        if (!updates.length) {
+          console.log("\x1b[32m✔\x1b[0m All skills are up to date");
+          return;
+        }
+
+        console.log(`\n  \x1b[1m${updates.length}\x1b[0m update${updates.length !== 1 ? "s" : ""} available:\n`);
+        for (const u of updates) {
+          console.log(`  \x1b[1m${u.slug}\x1b[0m  \x1b[2mv${u.currentVersion} → \x1b[0m\x1b[32mv${u.latestVersion}\x1b[0m`);
+          if (u.changelog) console.log(`    \x1b[2m${u.changelog}\x1b[0m`);
+        }
+        console.log();
+
+        if (opts.check) {
+          console.log(`  \x1b[2mRun \x1b[0m\x1b[36maiguild update --all\x1b[0m\x1b[2m to install all updates\x1b[0m`);
+          return;
+        }
+
+        const toUpdate = opts.all ? updates : (slug ? updates : []);
+        if (!toUpdate.length && !opts.all) {
+          console.log(`  \x1b[2mRun \x1b[0m\x1b[36maiguild update --all\x1b[0m\x1b[2m to install all updates\x1b[0m`);
+          return;
+        }
+
+        for (const u of toUpdate) {
+          process.stdout.write(`  Updating \x1b[36m${u.slug}\x1b[0m...`);
+          const dl = await apiFetch(`/api/v1/skills/${encodeURIComponent(u.slug)}/download`);
+          const record = installed[u.slug];
+          fs.writeFileSync(record.path, dl.content || "", "utf8");
+          installed[u.slug] = { ...record, version: u.latestVersion, installedAt: new Date().toISOString() };
+          saveConfig({ installed });
+          process.stdout.write("\r");
+          console.log(`  \x1b[32m✔\x1b[0m Updated \x1b[1m${u.slug}\x1b[0m to \x1b[32mv${u.latestVersion}\x1b[0m`);
+        }
+      } catch (e) {
+        process.stdout.write("\r");
+        console.error(`\x1b[31m✖\x1b[0m Update check failed: ${e.message}`);
+        process.exit(1);
+      }
+    });
+}

package/src/config.mjs

@@ -0,0 +1,47 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+const CONFIG_DIR = path.join(os.homedir(), ".aiguild");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+
+const DEFAULT_API_URL = process.env.AIGUILD_API_URL || "https://api.aiguild.dev";
+
+export function loadConfig() {
+  try {
+    if (fs.existsSync(CONFIG_FILE)) {
+      return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+    }
+  } catch {}
+  return { apiUrl: DEFAULT_API_URL };
+}
+
+export function saveConfig(updates) {
+  const current = loadConfig();
+  const next = { ...current, ...updates };
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(next, null, 2));
+  return next;
+}
+
+export function clearConfig() {
+  try { fs.unlinkSync(CONFIG_FILE); } catch {}
+}
+
+export function getApiUrl() {
+  return loadConfig().apiUrl || DEFAULT_API_URL;
+}
+
+export function getApiKey() {
+  return process.env.AIGUILD_API_KEY || loadConfig().apiKey || null;
+}
+
+export function requireAuth() {
+  const key = getApiKey();
+  if (!key) {
+    console.error("\x1b[31m✖\x1b[0m Not authenticated. Run: \x1b[36maiguild auth login --key <your-key>\x1b[0m");
+    console.error("  Get your key at: \x1b[2mSettings → CLI Access\x1b[0m");
+    process.exit(1);
+  }
+  return key;
+}