@caik.dev/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,816 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+import { readFileSync as readFileSync3 } from "fs";
+import { fileURLToPath } from "url";
+import { dirname as dirname2, join as join2 } from "path";
+import chalk2 from "chalk";
+
+// src/errors.ts
+var CaikError = class extends Error {
+  constructor(message, suggestion, exitCode = 1) {
+    super(message);
+    this.suggestion = suggestion;
+    this.exitCode = exitCode;
+    this.name = "CaikError";
+  }
+};
+function mapHttpError(status, body) {
+  const message = typeof body === "object" && body !== null && "message" in body ? String(body.message) : `Request failed with status ${status}`;
+  switch (status) {
+    case 401:
+      return new CaikError(message, "Run 'caik init --auth' to sign in.");
+    case 403:
+      return new CaikError(message, "You don't have permission for this action.");
+    case 404:
+      return new CaikError(message, "Run 'caik search <query>' to find artifacts.");
+    case 400:
+      return new CaikError(message, "Check your input and try again.");
+    case 429:
+      return new CaikError("Rate limited. Please wait and try again.");
+    case 500:
+    case 502:
+    case 503:
+      return new CaikError("Server error. The API may be temporarily unavailable.", "Try again in a few moments, or check 'caik status'.");
+    default:
+      return new CaikError(message);
+  }
+}
+function mapNetworkError(err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+    return new CaikError(
+      "Could not connect to the CAIK API.",
+      "Check your --api-url or CAIK_API_URL environment variable. Is the server running?"
+    );
+  }
+  if (msg.includes("ETIMEDOUT") || msg.includes("timeout")) {
+    return new CaikError(
+      "Request timed out.",
+      "The API may be slow or unreachable. Try again or check 'caik status'."
+    );
+  }
+  return new CaikError(`Network error: ${msg}`);
+}
+
+// src/api.ts
+var CaikApiClient = class {
+  baseUrl;
+  apiKey;
+  verbose;
+  constructor(config) {
+    this.baseUrl = config.apiUrl.replace(/\/+$/, "");
+    this.apiKey = config.apiKey;
+    this.verbose = config.verbose ?? false;
+  }
+  async get(path, params) {
+    const url = new URL(`${this.baseUrl}/api/v1${path}`);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== void 0) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    return this.request(url.toString(), { method: "GET" });
+  }
+  async post(path, body) {
+    return this.request(`${this.baseUrl}/api/v1${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+  }
+  async patch(path, body) {
+    return this.request(`${this.baseUrl}/api/v1${path}`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+  }
+  async del(path) {
+    return this.request(`${this.baseUrl}/api/v1${path}`, { method: "DELETE" });
+  }
+  async request(url, init) {
+    const headers = {
+      ...init.headers
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    if (this.verbose) {
+      console.error(`[verbose] ${init.method} ${url}`);
+    }
+    const start = Date.now();
+    let response;
+    try {
+      response = await fetch(url, { ...init, headers });
+    } catch (err) {
+      throw mapNetworkError(err);
+    }
+    if (this.verbose) {
+      console.error(`[verbose] ${response.status} (${Date.now() - start}ms)`);
+    }
+    if (!response.ok) {
+      let body;
+      try {
+        body = await response.json();
+      } catch {
+        body = await response.text().catch(() => null);
+      }
+      throw mapHttpError(response.status, body);
+    }
+    if (response.status === 204) {
+      return void 0;
+    }
+    return response.json();
+  }
+};
+
+// src/config.ts
+import { readFileSync, writeFileSync, mkdirSync, chmodSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+var DEFAULT_CONFIG = {
+  apiUrl: "https://caik.dev",
+  defaultLimit: 10,
+  version: 1
+};
+function getConfigDir() {
+  return join(homedir(), ".caik");
+}
+function getConfigPath() {
+  return join(getConfigDir(), "config.json");
+}
+function readConfig() {
+  const path = getConfigPath();
+  if (!existsSync(path)) {
+    return { ...DEFAULT_CONFIG };
+  }
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(raw);
+    return { ...DEFAULT_CONFIG, ...parsed };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+function writeConfig(config) {
+  const dir = getConfigDir();
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true, mode: 448 });
+  }
+  const path = getConfigPath();
+  writeFileSync(path, JSON.stringify(config, null, 2) + "\n", "utf-8");
+  chmodSync(path, 384);
+}
+function resolveConfig(opts) {
+  const config = readConfig();
+  return {
+    apiUrl: opts.apiUrl ?? process.env.CAIK_API_URL ?? config.apiUrl ?? DEFAULT_CONFIG.apiUrl,
+    apiKey: opts.apiKey ?? process.env.CAIK_API_KEY ?? config.apiKey
+  };
+}
+
+// src/format.ts
+import chalk from "chalk";
+import ora from "ora";
+import Table from "cli-table3";
+function success(msg) {
+  return chalk.green(`\u2713 ${msg}`);
+}
+function error(msg) {
+  return chalk.red(`\u2717 ${msg}`);
+}
+function info(msg) {
+  return chalk.cyan(`\u2192 ${msg}`);
+}
+function dim(msg) {
+  return chalk.dim(msg);
+}
+function heading(msg) {
+  return chalk.bold.white(msg);
+}
+function createSpinner(text) {
+  return ora({ text, color: "cyan" });
+}
+function renderTable(headers, rows) {
+  const table = new Table({
+    head: headers.map((h) => chalk.bold.cyan(h)),
+    style: { head: [], border: ["dim"] },
+    chars: {
+      top: "\u2500",
+      "top-mid": "\u252C",
+      "top-left": "\u250C",
+      "top-right": "\u2510",
+      bottom: "\u2500",
+      "bottom-mid": "\u2534",
+      "bottom-left": "\u2514",
+      "bottom-right": "\u2518",
+      left: "\u2502",
+      "left-mid": "\u251C",
+      mid: "\u2500",
+      "mid-mid": "\u253C",
+      right: "\u2502",
+      "right-mid": "\u2524",
+      middle: "\u2502"
+    }
+  });
+  for (const row of rows) {
+    table.push(row);
+  }
+  return table.toString();
+}
+function outputResult(data, opts) {
+  if (opts.json) {
+    console.log(JSON.stringify(data, null, 2));
+  }
+}
+function formatNumber(n) {
+  return n.toLocaleString("en-US");
+}
+function truncate(str, maxLen) {
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 1) + "\u2026";
+}
+
+// src/commands/search.ts
+function registerSearchCommand(program2) {
+  program2.command("search <query>").description("Search for artifacts in the CAIK registry").option("--primitive <type>", "Filter by primitive type (executable, knowledge, connector, composition, reference)").option("--tag <tag>", "Filter by tag (can be repeated)", (val, prev) => [...prev, val], []).option("--platform <platform>", "Filter by platform (claude, cursor, node, etc.)").option("--limit <n>", "Maximum results to return", "10").option("--offset <n>", "Skip first N results (for pagination)", "0").addHelpText("after", `
+Examples:
+  caik search "auth middleware"
+  caik search "calendar" --primitive executable --limit 5
+  caik search "react" --tag frontend --json`).action(async (query, opts) => {
+    const globalOpts = program2.opts();
+    const { apiUrl, apiKey } = resolveConfig(globalOpts);
+    const client = new CaikApiClient({ apiUrl, apiKey, verbose: globalOpts.verbose });
+    const spinner = createSpinner("Searching...");
+    if (!globalOpts.json) spinner.start();
+    const filters = {};
+    if (opts.primitive) filters.primitive = opts.primitive;
+    if (opts.tag.length > 0) filters.tags = opts.tag;
+    if (opts.platform) filters.platforms = [opts.platform];
+    const result = await client.post("/search", {
+      query,
+      filters: Object.keys(filters).length > 0 ? filters : void 0,
+      limit: parseInt(opts.limit, 10),
+      offset: parseInt(opts.offset, 10)
+    });
+    if (!globalOpts.json) spinner.stop();
+    if (globalOpts.json) {
+      outputResult(result, { json: true });
+      return;
+    }
+    if (result.results.length === 0) {
+      console.log(`No artifacts found for "${query}".`);
+      return;
+    }
+    const table = renderTable(
+      ["Name", "Primitive", "Quality", "Installs", "Tags"],
+      result.results.map((a) => [
+        a.slug,
+        a.primitive,
+        a.qualityScore != null ? String(a.qualityScore) : "\u2014",
+        formatNumber(a.installCount),
+        truncate((a.tags ?? []).join(", "), 30)
+      ])
+    );
+    console.log(table);
+    console.log(`
+${result.total} result${result.total !== 1 ? "s" : ""} found.`);
+    if (result.hasMore) {
+      console.log(`Use --offset ${parseInt(opts.offset, 10) + parseInt(opts.limit, 10)} to see more.`);
+    }
+    client.post("/telemetry/search", {
+      query,
+      resultsCount: result.total
+    }).catch(() => {
+    });
+  });
+}
+
+// src/commands/install.ts
+import { existsSync as existsSync2 } from "fs";
+import { writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
+import { dirname, resolve } from "path";
+import { execSync } from "child_process";
+import { createInterface } from "readline/promises";
+function detectPlatform() {
+  if (existsSync2(".claude") || existsSync2("CLAUDE.md")) return "claude";
+  if (existsSync2(".cursor")) return "cursor";
+  if (existsSync2("node_modules") || existsSync2("package.json")) return "node";
+  return void 0;
+}
+function registerInstallCommand(program2) {
+  program2.command("install <slug>").description("Install an artifact from the CAIK registry").option("--platform <platform>", "Target platform (auto-detected if not specified)").option("-y, --yes", "Skip confirmation prompts (for CI/scripting)").addHelpText("after", `
+Examples:
+  caik install auth-middleware
+  caik install my-skill --platform claude`).action(async (slug, opts) => {
+    const globalOpts = program2.opts();
+    const { apiUrl, apiKey } = resolveConfig(globalOpts);
+    const client = new CaikApiClient({ apiUrl, apiKey, verbose: globalOpts.verbose });
+    const platform = opts.platform ?? detectPlatform();
+    const spinner = createSpinner(`Fetching ${slug}...`);
+    if (!globalOpts.json) spinner.start();
+    const params = { platform };
+    const installInfo = await client.get(`/install/${encodeURIComponent(slug)}`, params);
+    if (globalOpts.json) {
+      spinner.stop();
+      outputResult(installInfo, { json: true });
+      return;
+    }
+    spinner.text = `Installing ${installInfo.artifact.name}...`;
+    const skipConfirm = Boolean(opts.yes);
+    const cwd = process.cwd();
+    const safeFiles = [];
+    if (installInfo.files && installInfo.files.length > 0) {
+      for (const file of installInfo.files) {
+        const resolvedPath = resolve(cwd, file.path);
+        if (!resolvedPath.startsWith(cwd + "/") && resolvedPath !== cwd) {
+          spinner.stop();
+          console.log(error(`Rejected file path outside working directory: ${file.path}`));
+          spinner.start();
+          continue;
+        }
+        safeFiles.push({ resolvedPath, content: file.content });
+      }
+    }
+    const hasFiles = safeFiles.length > 0;
+    const hasInstallCmd = Boolean(installInfo.installCommand);
+    const hasPostHook = Boolean(installInfo.postInstallHook);
+    if (!skipConfirm && (hasFiles || hasInstallCmd || hasPostHook)) {
+      spinner.stop();
+      console.log(info("\n--- Install plan ---"));
+      if (hasFiles) {
+        console.log(info("Files to write:"));
+        for (const f of safeFiles) {
+          console.log(info(`  ${f.resolvedPath}`));
+        }
+      }
+      if (hasInstallCmd) {
+        console.log(info(`Install command: ${installInfo.installCommand}`));
+      }
+      if (hasPostHook) {
+        console.log(info(`Post-install hook: ${installInfo.postInstallHook}`));
+      }
+      console.log();
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await rl.question("Continue? (y/N) ");
+      rl.close();
+      if (answer.toLowerCase() !== "y") {
+        console.log(info("Installation cancelled."));
+        return;
+      }
+      spinner.start();
+    }
+    for (const file of safeFiles) {
+      const dir = dirname(file.resolvedPath);
+      if (!existsSync2(dir)) {
+        mkdirSync2(dir, { recursive: true });
+      }
+      writeFileSync2(file.resolvedPath, file.content, "utf-8");
+    }
+    if (installInfo.installCommand) {
+      try {
+        execSync(installInfo.installCommand, { stdio: "pipe" });
+      } catch (err) {
+        spinner.stop();
+        console.error(error(`Install command failed: ${err instanceof Error ? err.message : String(err)}`));
+        client.post("/telemetry/install", {
+          artifactSlug: slug,
+          platform,
+          success: false,
+          errorMessage: err instanceof Error ? err.message : String(err)
+        }).catch(() => {
+        });
+        process.exit(1);
+      }
+    }
+    if (installInfo.postInstallHook) {
+      try {
+        execSync(installInfo.postInstallHook, { stdio: "pipe" });
+      } catch {
+      }
+    }
+    spinner.stop();
+    console.log(success(`Installed ${installInfo.artifact.name}`));
+    if (installInfo.contract?.touchedPaths) {
+      console.log(info(`Files: ${installInfo.contract.touchedPaths.join(", ")}`));
+    }
+    client.post("/telemetry/install", {
+      artifactSlug: slug,
+      platform,
+      success: true
+    }).catch(() => {
+    });
+  });
+}
+
+// src/commands/init.ts
+import { createInterface as createInterface2 } from "readline/promises";
+import { stdin, stdout } from "process";
+function registerInitCommand(program2) {
+  program2.command("init").description("Configure the CAIK CLI").option("--auth", "Set up authentication (opens browser)").addHelpText("after", `
+Examples:
+  caik init
+  caik init --auth`).action(async (opts) => {
+    const rl = createInterface2({ input: stdin, output: stdout });
+    try {
+      const config = readConfig();
+      const apiUrl = await rl.question(`API URL (${config.apiUrl}): `);
+      if (apiUrl.trim()) {
+        config.apiUrl = apiUrl.trim();
+      }
+      const apiKey = await rl.question("API Key (leave blank to skip): ");
+      if (apiKey.trim()) {
+        config.apiKey = apiKey.trim();
+      }
+      writeConfig(config);
+      console.log(success("CAIK CLI configured"));
+      console.log(info(`Config saved to ~/.caik/config.json`));
+      if (config.apiKey) {
+        const client = new CaikApiClient({ apiUrl: config.apiUrl, apiKey: config.apiKey });
+        try {
+          const karma = await client.get("/me/karma");
+          console.log(success("API connection verified \u2014 authenticated"));
+        } catch {
+          console.log(error("Could not verify API connection. Check your API key."));
+        }
+      }
+    } finally {
+      rl.close();
+    }
+  });
+}
+
+// src/commands/status.ts
+import { existsSync as existsSync3 } from "fs";
+function registerStatusCommand(program2) {
+  program2.command("status").description("Show CLI configuration and connectivity status").action(async () => {
+    const globalOpts = program2.opts();
+    const config = readConfig();
+    const { apiUrl, apiKey } = resolveConfig(globalOpts);
+    if (globalOpts.json) {
+      const data = {
+        apiUrl,
+        apiKeyConfigured: !!apiKey,
+        platforms: {
+          claude: existsSync3(".claude") || existsSync3("CLAUDE.md"),
+          cursor: existsSync3(".cursor"),
+          node: existsSync3("node_modules") || existsSync3("package.json")
+        }
+      };
+      const client2 = new CaikApiClient({ apiUrl, apiKey, verbose: globalOpts.verbose });
+      try {
+        if (apiKey) {
+          const karma = await client2.get("/me/karma");
+          data.authenticated = true;
+          data.user = karma;
+        }
+        data.apiReachable = true;
+      } catch {
+        data.apiReachable = false;
+        data.authenticated = false;
+      }
+      outputResult(data, { json: true });
+      return;
+    }
+    console.log(heading("CAIK CLI Status"));
+    console.log("\u2550".repeat(40));
+    console.log(`API URL:          ${apiUrl}`);
+    console.log(`API Key:          ${apiKey ? `${dim("configured")} (${apiKey.slice(0, 12)}...)` : dim("not set")}`);
+    const client = new CaikApiClient({ apiUrl, apiKey, verbose: globalOpts.verbose });
+    try {
+      if (apiKey) {
+        const karma = await client.get("/me/karma");
+        console.log(`Authenticated:    ${success("yes")}`);
+        console.log(`User:             ${karma.handle ?? karma.displayName ?? "unknown"} (${karma.karmaTier})`);
+      } else {
+        console.log(`Authenticated:    ${dim("no (no API key)")}`);
+      }
+    } catch {
+      console.log(`API Reachable:    ${error("no")}`);
+    }
+    console.log("");
+    console.log(heading("Local Platforms Detected"));
+    console.log("\u2500".repeat(40));
+    const platforms = [
+      { name: "Claude", check: existsSync3(".claude") || existsSync3("CLAUDE.md") },
+      { name: "Cursor", check: existsSync3(".cursor") },
+      { name: "Node.js", check: existsSync3("node_modules") || existsSync3("package.json") }
+    ];
+    for (const p of platforms) {
+      console.log(`  ${p.name}: ${p.check ? success("detected") : dim("not found")}`);
+    }
+  });
+}
+
+// src/commands/stats.ts
+var PRIMITIVES = ["executable", "knowledge", "connector", "composition", "reference"];
+function registerStatsCommand(program2) {
+  program2.command("stats").description("Show CAIK ecosystem statistics").addHelpText("after", `
+Examples:
+  caik stats
+  caik stats --json`).action(async () => {
+    const globalOpts = program2.opts();
+    const { apiUrl, apiKey } = resolveConfig(globalOpts);
+    const client = new CaikApiClient({ apiUrl, apiKey, verbose: globalOpts.verbose });
+    const spinner = createSpinner("Fetching stats...");
+    if (!globalOpts.json) spinner.start();
+    const counts = {};
+    let totalInstalls = 0;
+    await Promise.all(
+      PRIMITIVES.map(async (primitive) => {
+        try {
+          const result = await client.get(
+            `/artifacts/by-primitive/${primitive}`,
+            { limit: "1", offset: "0" }
+          );
+          counts[primitive] = result.total;
+        } catch {
+          counts[primitive] = 0;
+        }
+      })
+    );
+    const totalArtifacts = Object.values(counts).reduce((a, b) => a + b, 0);
+    if (!globalOpts.json) spinner.stop();
+    if (globalOpts.json) {
+      outputResult({ totalArtifacts, byPrimitive: counts, totalInstalls }, { json: true });
+      return;
+    }
+    console.log(heading("CAIK Registry Stats"));
+    console.log("\u2550".repeat(40));
+    console.log(`Total artifacts:  ${formatNumber(totalArtifacts)}`);
+    console.log("");
+    console.log("By primitive:");
+    for (const [primitive, count] of Object.entries(counts)) {
+      const label = primitive.charAt(0).toUpperCase() + primitive.slice(1);
+      console.log(`  ${label.padEnd(16)} ${formatNumber(count)}`);
+    }
+  });
+}
+
+// src/commands/publish.ts
+import { readFileSync as readFileSync2, existsSync as existsSync4 } from "fs";
+function registerPublishCommand(program2) {
+  program2.command("publish [path]").description("Publish an artifact to the CAIK registry").requiredOption("--name <name>", "Artifact name").requiredOption("--description <desc>", "Artifact description (min 20 chars)").option("--slug <slug>", "Custom slug (auto-generated from name if omitted)").option("--primitive <type>", "Primitive type", "executable").option("--platform <platform>", "Target platform(s) (comma-separated)", "claude").option("--tag <tag>", "Add a tag (can be repeated)", (val, prev) => [...prev, val], []).option("--source-url <url>", "Source code URL").addHelpText("after", `
+Examples:
+  caik publish ./my-skill --name "My Skill" --description "A useful skill for Claude" --tag productivity
+  caik publish --name "Auth Helper" --description "Authentication middleware helper" --primitive knowledge`).action(async (path, opts) => {
+    const globalOpts = program2.opts();
+    const { apiUrl, apiKey } = resolveConfig(globalOpts);
+    if (!apiKey) {
+      throw new CaikError("Authentication required to publish.", "Run 'caik init --auth' to sign in.");
+    }
+    const client = new CaikApiClient({ apiUrl, apiKey, verbose: globalOpts.verbose });
+    let content;
+    if (path) {
+      if (!existsSync4(path)) {
+        throw new CaikError(`File not found: ${path}`);
+      }
+      content = readFileSync2(path, "utf-8");
+    }
+    const tags = opts.tag.length > 0 ? opts.tag : ["general"];
+    const platforms = opts.platform.split(",").map((p) => p.trim());
+    const spinner = createSpinner("Publishing artifact...");
+    if (!globalOpts.json) spinner.start();
+    const result = await client.post("/artifacts", {
+      slug: opts.slug,
+      name: opts.name,
+      description: opts.description,
+      primitive: opts.primitive,
+      platforms,
+      tags,
+      content,
+      sourceUrl: opts.sourceUrl
+    });
+    if (!globalOpts.json) spinner.stop();
+    if (globalOpts.json) {
+      outputResult(result, { json: true });
+      return;
+    }
+    console.log(success(`Published "${result.name}"`));
+    console.log(info(`Slug: ${result.slug}`));
+    console.log(info(`Status: ${result.status}`));
+  });
+}
+
+// src/commands/review-queue.ts
+function registerReviewQueueCommand(program2) {
+  program2.command("review-queue").description("List artifacts pending review (admin only)").option("--limit <n>", "Maximum results", "20").option("--offset <n>", "Skip first N results", "0").action(async (opts) => {
+    const globalOpts = program2.opts();
+    const { apiUrl, apiKey } = resolveConfig(globalOpts);
+    if (!apiKey) {
+      throw new CaikError("Authentication required.", "Run 'caik init --auth' to sign in.");
+    }
+    const client = new CaikApiClient({ apiUrl, apiKey, verbose: globalOpts.verbose });
+    const spinner = createSpinner("Fetching review queue...");
+    if (!globalOpts.json) spinner.start();
+    const result = await client.get("/admin/review-queue", {
+      limit: opts.limit,
+      offset: opts.offset
+    });
+    if (!globalOpts.json) spinner.stop();
+    if (globalOpts.json) {
+      outputResult(result, { json: true });
+      return;
+    }
+    if (result.results.length === 0) {
+      console.log("No artifacts pending review.");
+      return;
+    }
+    const table = renderTable(
+      ["Slug", "Name", "Primitive", "Author", "Submitted"],
+      result.results.map((r) => [
+        r.slug,
+        r.name,
+        r.primitive,
+        r.authorHandle ?? "unknown",
+        new Date(r.createdAt).toLocaleDateString()
+      ])
+    );
+    console.log(table);
+    console.log(`
+${result.total} pending artifact${result.total !== 1 ? "s" : ""}.`);
+  });
+}
+
+// src/commands/approve.ts
+function registerApproveCommand(program2) {
+  program2.command("approve <slug>").description("Approve a pending artifact (admin only)").action(async (slug) => {
+    const globalOpts = program2.opts();
+    const { apiUrl, apiKey } = resolveConfig(globalOpts);
+    if (!apiKey) {
+      throw new CaikError("Authentication required.", "Run 'caik init --auth' to sign in.");
+    }
+    const client = new CaikApiClient({ apiUrl, apiKey, verbose: globalOpts.verbose });
+    const spinner = createSpinner(`Approving ${slug}...`);
+    if (!globalOpts.json) spinner.start();
+    const result = await client.post(`/admin/approve/${encodeURIComponent(slug)}`);
+    if (!globalOpts.json) spinner.stop();
+    if (globalOpts.json) {
+      outputResult(result, { json: true });
+      return;
+    }
+    console.log(success(`Artifact "${slug}" approved`));
+  });
+}
+
+// src/commands/flag.ts
+function registerFlagCommand(program2) {
+  program2.command("flag <slug>").description("Flag an artifact for review").requiredOption("--reason <reason>", "Reason for flagging (min 10 chars)").option("--severity <level>", "Severity level (low, medium, high)", "medium").addHelpText("after", `
+Examples:
+  caik flag my-artifact --reason "Contains outdated API calls that may cause errors"
+  caik flag bad-skill --reason "Security concern: requests unnecessary permissions" --severity high`).action(async (slug, opts) => {
+    const globalOpts = program2.opts();
+    const { apiUrl, apiKey } = resolveConfig(globalOpts);
+    if (!apiKey) {
+      throw new CaikError("Authentication required.", "Run 'caik init --auth' to sign in.");
+    }
+    const client = new CaikApiClient({ apiUrl, apiKey, verbose: globalOpts.verbose });
+    const spinner = createSpinner(`Flagging ${slug}...`);
+    if (!globalOpts.json) spinner.start();
+    const result = await client.post(`/artifacts/${encodeURIComponent(slug)}/flag`, {
+      slug,
+      reason: opts.reason,
+      severity: opts.severity
+    });
+    if (!globalOpts.json) spinner.stop();
+    if (globalOpts.json) {
+      outputResult(result, { json: true });
+      return;
+    }
+    console.log(success(`Flagged "${slug}" for review (severity: ${opts.severity})`));
+  });
+}
+
+// src/commands/alternatives.ts
+function registerAlternativesCommand(program2) {
+  program2.command("alternatives <slug>").description("Show alternatives and similar artifacts").addHelpText("after", `
+Examples:
+  caik alternatives auth-middleware`).action(async (slug) => {
+    const globalOpts = program2.opts();
+    const { apiUrl, apiKey } = resolveConfig(globalOpts);
+    const client = new CaikApiClient({ apiUrl, apiKey, verbose: globalOpts.verbose });
+    const spinner = createSpinner(`Finding alternatives for ${slug}...`);
+    if (!globalOpts.json) spinner.start();
+    const artifact = await client.get(`/artifacts/${encodeURIComponent(slug)}`);
+    let similar = { results: [], total: 0, hasMore: false };
+    if (artifact.tags && artifact.tags.length > 0) {
+      similar = await client.post("/search", {
+        query: artifact.name,
+        filters: { primitive: artifact.primitive },
+        limit: 10
+      });
+      similar.results = similar.results.filter((a) => a.slug !== slug);
+    }
+    if (!globalOpts.json) spinner.stop();
+    if (globalOpts.json) {
+      outputResult({ artifact: { slug: artifact.slug, name: artifact.name }, alternatives: similar.results }, { json: true });
+      return;
+    }
+    if (similar.results.length === 0) {
+      console.log(info(`No alternatives found for "${artifact.name}".`));
+      return;
+    }
+    const table = renderTable(
+      ["Name", "Primitive", "Quality", "Installs"],
+      similar.results.map((a) => [
+        a.slug,
+        a.primitive,
+        a.qualityScore != null ? String(a.qualityScore) : "\u2014",
+        formatNumber(a.installCount)
+      ])
+    );
+    console.log(`Alternatives to "${artifact.name}":
+`);
+    console.log(table);
+  });
+}
+
+// src/commands/update.ts
+function registerUpdateCommand(program2) {
+  program2.command("update [slug]").description("Check for and apply artifact updates").option("--yes", "Skip confirmation prompt").action(async (slug) => {
+    console.log(info("Update checking is not yet available. Reinstall artifacts with 'caik install <slug>' to get the latest version."));
+  });
+}
+
+// src/commands/uninstall.ts
+function registerUninstallCommand(program2) {
+  program2.command("uninstall <slug>").description("Remove an installed artifact").action(async (slug) => {
+    console.log(info("Uninstall is not yet available. Manually remove the artifact files to uninstall."));
+  });
+}
+
+// src/commands/karma.ts
+function registerKarmaCommand(program2) {
+  program2.command("karma").description("Show your karma and contribution breakdown").action(async () => {
+    const globalOpts = program2.opts();
+    const { apiUrl, apiKey } = resolveConfig(globalOpts);
+    if (!apiKey) {
+      throw new CaikError("Authentication required to view karma.", "Run 'caik init --auth' to sign in.");
+    }
+    const client = new CaikApiClient({ apiUrl, apiKey, verbose: globalOpts.verbose });
+    const spinner = createSpinner("Fetching karma...");
+    if (!globalOpts.json) spinner.start();
+    const karma = await client.get("/me/karma");
+    if (!globalOpts.json) spinner.stop();
+    if (globalOpts.json) {
+      outputResult(karma, { json: true });
+      return;
+    }
+    console.log(heading("Your CAIK Karma"));
+    console.log("\u2550".repeat(40));
+    console.log(`Tier:             ${karma.karmaTier}`);
+    console.log(`Total karma:      ${formatNumber(karma.karma)}`);
+    console.log(`Level:            ${karma.contributionLevel}`);
+    console.log(`Handle:           ${karma.handle}`);
+  });
+}
+
+// src/index.ts
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname2(__filename);
+var version = "0.0.1";
+try {
+  const pkgPath = join2(__dirname, "..", "package.json");
+  const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+  version = pkg.version;
+} catch {
+}
+var program = new Command().name("caik").description("CAIK \u2014 Collective AI Knowledge CLI\nSearch, install, and publish AI artifacts from your terminal.").version(version, "-v, --version").option("--api-url <url>", "API base URL (default: https://caik.dev)").option("--api-key <key>", "API key for authentication").option("--verbose", "Show detailed output including API calls").option("--json", "Output raw JSON (for scripting)");
+registerSearchCommand(program);
+registerInstallCommand(program);
+registerInitCommand(program);
+registerStatusCommand(program);
+registerStatsCommand(program);
+registerPublishCommand(program);
+registerReviewQueueCommand(program);
+registerApproveCommand(program);
+registerFlagCommand(program);
+registerAlternativesCommand(program);
+registerUpdateCommand(program);
+registerUninstallCommand(program);
+registerKarmaCommand(program);
+program.exitOverride();
+async function main() {
+  try {
+    await program.parseAsync(process.argv);
+  } catch (err) {
+    if (err instanceof CaikError) {
+      console.error(chalk2.red(`\u2717 ${err.message}`));
+      if (err.suggestion) {
+        console.error(chalk2.dim(`  ${err.suggestion}`));
+      }
+      process.exit(err.exitCode);
+    }
+    if (err instanceof Error && "exitCode" in err) {
+      const exitCode = err.exitCode;
+      process.exit(exitCode);
+    }
+    console.error(chalk2.red(`\u2717 Unexpected error: ${err instanceof Error ? err.message : String(err)}`));
+    process.exit(1);
+  }
+}
+main();

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@caik.dev/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "CAIK CLI — Search, install, and publish AI artifacts from your terminal",
+  "bin": {
+    "caik": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts --",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.3",
+    "ora": "^9.3.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0"
+  }
+}