@yoyo-bot/cli 0.1.0

package/src/commands/list.ts

@@ -0,0 +1,43 @@
+import pc from "picocolors";
+import { api } from "../lib/api.js";
+
+export async function listCommand(opts: { owner?: string; page?: string; json?: boolean }): Promise<void> {
+  const page = Number(opts.page ?? 1);
+  const pageSize = 20;
+
+  let result;
+  try {
+    result = await api.listBinders(opts.owner, page, pageSize);
+  } catch (err) {
+    console.error(pc.red(`Failed to list binders: ${String(err)}`));
+    process.exit(1);
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (result.items.length === 0) {
+    console.log(pc.dim("No binders found."));
+    return;
+  }
+
+  const title = opts.owner ? `Binders by ${opts.owner}` : "All binders";
+  console.log(pc.bold(`\n${title}`) + pc.dim(` (${result.total} total)\n`));
+
+  for (const b of result.items) {
+    const name = pc.cyan(`${b.owner}/${b.slug}`);
+    const ver = b.version ? pc.dim(`v${b.version}`) : "";
+    const badge =
+      b.verification === "official" ? pc.yellow(" ✦") : b.verification === "verified" ? pc.green(" ✓") : "";
+    const dl = b.downloads != null ? pc.dim(` · ${b.downloads.toLocaleString()} downloads`) : "";
+    console.log(`  ${name}${badge}  ${ver}${dl}`);
+    if (b.description) console.log(`    ${pc.dim(b.description.slice(0, 80))}`);
+    console.log();
+  }
+
+  if (result.total > page * pageSize) {
+    console.log(pc.dim(`Page ${page} of ${Math.ceil(result.total / pageSize)} — use --page to navigate`));
+  }
+}

package/src/commands/publish.ts

@@ -0,0 +1,117 @@
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import pc from "picocolors";
+import { api, ApiError } from "../lib/api.js";
+import { getApiKey } from "../lib/config.js";
+
+interface PublishOptions {
+  dir?: string;
+  dryRun?: boolean;
+  json?: boolean;
+}
+
+interface BinderManifest {
+  slug: string;
+  displayName?: string;
+  description?: string;
+  version: string;
+  tab?: string;
+  tags?: string[];
+  platforms?: string[];
+  license?: string;
+  dependencies?: Record<string, string>;
+}
+
+export async function publishCommand(opts: PublishOptions): Promise<void> {
+  const cwd = opts.dir ? resolve(opts.dir) : process.cwd();
+  const manifestPath = join(cwd, "binder.json");
+
+  if (!existsSync(manifestPath)) {
+    console.error(pc.red("No binder.json found. Run: yoyo init"));
+    process.exit(1);
+  }
+
+  let manifest: BinderManifest;
+  try {
+    const raw = await readFile(manifestPath, "utf8");
+    manifest = JSON.parse(raw) as BinderManifest;
+  } catch {
+    console.error(pc.red("Failed to parse binder.json."));
+    process.exit(1);
+  }
+
+  if (!manifest.slug) {
+    console.error(pc.red("binder.json missing required field: slug"));
+    process.exit(1);
+  }
+  if (!manifest.version) {
+    console.error(pc.red("binder.json missing required field: version"));
+    process.exit(1);
+  }
+
+  const key = await getApiKey();
+  if (!key) {
+    console.error(pc.red("Not authenticated. Run: yoyo auth"));
+    process.exit(1);
+  }
+
+  // Read page.md as readme if present
+  let readme: string | undefined;
+  const pagePath = join(cwd, "page.md");
+  if (existsSync(pagePath)) {
+    readme = await readFile(pagePath, "utf8");
+  } else {
+    const readmePath = join(cwd, "README.md");
+    if (existsSync(readmePath)) readme = await readFile(readmePath, "utf8");
+  }
+
+  if (opts.dryRun || opts.json) {
+    const payload = {
+      slug: manifest.slug,
+      displayName: manifest.displayName,
+      description: manifest.description,
+      version: manifest.version,
+      readme,
+      tags: manifest.tags ?? [],
+      tab: manifest.tab,
+      license: manifest.license,
+      platforms: manifest.platforms ?? [],
+      dependencies: manifest.dependencies ?? {},
+    };
+    if (opts.json) {
+      console.log(JSON.stringify({ dryRun: opts.dryRun ?? false, payload }, null, 2));
+    } else {
+      console.log(pc.yellow("Dry run — would publish:"));
+      console.log(`  ${manifest.slug}@${manifest.version}`);
+    }
+    return;
+  }
+
+  console.log(pc.dim(`Publishing ${manifest.slug}@${manifest.version}…`));
+
+  try {
+    const result = await api.publish({
+      slug: manifest.slug,
+      displayName: manifest.displayName,
+      description: manifest.description,
+      version: manifest.version,
+      readme,
+      tags: manifest.tags ?? [],
+      tab: manifest.tab,
+      license: manifest.license,
+      platforms: manifest.platforms ?? [],
+      dependencies: manifest.dependencies ?? {},
+    });
+
+    console.log(pc.green(`\nPublished ${result.slug}@${result.version}`));
+    console.log(pc.dim(`ID: ${result.id}`));
+  } catch (err) {
+    if (err instanceof ApiError) {
+      console.error(pc.red(`Publish failed (${err.status}): ${err.message}`));
+    } else {
+      console.error(pc.red(`Publish failed: ${String(err)}`));
+    }
+    process.exit(1);
+  }
+}

package/src/commands/search.ts

@@ -0,0 +1,40 @@
+import pc from "picocolors";
+import { api } from "../lib/api.js";
+
+export async function searchCommand(query: string, opts: { limit?: string; json?: boolean }): Promise<void> {
+  const pageSize = Math.min(Number(opts.limit ?? 10), 50);
+
+  let result;
+  try {
+    result = await api.search(query, 1, pageSize);
+  } catch (err: unknown) {
+    console.error(pc.red("Search failed: " + String(err)));
+    process.exit(1);
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (result.items.length === 0) {
+    console.log(pc.dim(`No results for "${query}"`));
+    return;
+  }
+
+  console.log(pc.bold(`\nSearch results for "${query}"`) + pc.dim(` (${result.total} total)\n`));
+
+  for (const b of result.items) {
+    const name = pc.cyan(`${b.owner}/${b.slug}`);
+    const ver = b.version ? pc.dim(`v${b.version}`) : "";
+    const badge = b.verification === "official" ? pc.yellow(" ✦") : b.verification === "verified" ? pc.green(" ✓") : "";
+    console.log(`  ${name}${badge}  ${ver}`);
+    if (b.description) {
+      console.log(`    ${pc.dim(b.description.slice(0, 80))}`);
+    }
+    if (b.tags?.length) {
+      console.log(`    ${pc.dim(b.tags.slice(0, 5).join(", "))}`);
+    }
+    console.log();
+  }
+}

package/src/commands/unbind.ts

@@ -0,0 +1,34 @@
+import { rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { existsSync } from "node:fs";
+import pc from "picocolors";
+
+interface UnbindOptions {
+  dir?: string;
+  force?: boolean;
+}
+
+function defaultBindRoot(): string {
+  return join(homedir(), ".yoyo", "binders");
+}
+
+export async function unbindCommand(ref: string, opts: UnbindOptions): Promise<void> {
+  const parts = ref.split("/");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    console.error(pc.red(`Invalid ref "${ref}". Expected <owner>/<slug>`));
+    process.exit(1);
+  }
+  const [owner, slug] = parts;
+  const bindRoot = opts.dir ? resolve(opts.dir) : defaultBindRoot();
+  const bindDir = join(bindRoot, owner!, slug!);
+
+  if (!existsSync(bindDir)) {
+    console.error(pc.red(`Not bound: ${ref} (${bindDir} not found)`));
+    process.exit(1);
+  }
+
+  console.log(pc.dim(`Removing ${bindDir}…`));
+  await rm(bindDir, { recursive: true, force: true });
+  console.log(pc.green(`Unbound ${ref}`));
+}

package/src/commands/whoami.ts

@@ -0,0 +1,34 @@
+import pc from "picocolors";
+import { api, ApiError } from "../lib/api.js";
+import { getApiKey } from "../lib/config.js";
+
+export async function whoamiCommand(opts: { json?: boolean }): Promise<void> {
+  const key = await getApiKey();
+  if (!key) {
+    console.error(pc.red("Not authenticated. Run: yoyo auth"));
+    process.exit(1);
+  }
+
+  let user;
+  try {
+    user = await api.whoami();
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 401) {
+      console.error(pc.red("Invalid or expired API key. Run: yoyo auth"));
+    } else {
+      console.error(pc.red(`Error: ${String(err)}`));
+    }
+    process.exit(1);
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(user, null, 2));
+    return;
+  }
+
+  console.log();
+  console.log(`  ${pc.bold(user.displayName ?? user.slug)}`);
+  console.log(`  ${pc.dim("Slug")}   ${user.slug}`);
+  if (user.email) console.log(`  ${pc.dim("Email")}  ${user.email}`);
+  console.log();
+}

package/src/index.ts

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { program } from "commander";
+import { searchCommand } from "./commands/search.js";
+import { bindCommand } from "./commands/bind.js";
+import { unbindCommand } from "./commands/unbind.js";
+import { publishCommand } from "./commands/publish.js";
+import { initCommand } from "./commands/init.js";
+import { authCommand } from "./commands/auth.js";
+import { whoamiCommand } from "./commands/whoami.js";
+import { listCommand } from "./commands/list.js";
+
+program
+  .name("yoyo")
+  .description("Yoyo — the AI agent binder registry CLI")
+  .version("0.0.1");
+
+program
+  .command("search <query>")
+  .description("Search for binders in the registry")
+  .option("-l, --limit <n>", "max results", "10")
+  .option("--json", "output JSON")
+  .action((query: string, opts) => searchCommand(query, opts));
+
+program
+  .command("bind <owner/slug>")
+  .description("Bind (install) a binder to ~/.yoyo/binders/")
+  .option("-v, --version <ver>", "specific version")
+  .option("-d, --dir <path>", "bind root directory")
+  .option("--dry-run", "preview without writing")
+  .option("--json", "output JSON")
+  .action((ref: string, opts) => bindCommand(ref, opts));
+
+program
+  .command("unbind <owner/slug>")
+  .description("Remove a bound binder")
+  .option("-d, --dir <path>", "bind root directory")
+  .option("-f, --force", "skip confirmation")
+  .action((ref: string, opts) => unbindCommand(ref, opts));
+
+program
+  .command("list")
+  .description("List binders in the registry")
+  .option("--owner <slug>", "filter by owner")
+  .option("--page <n>", "page number", "1")
+  .option("--json", "output JSON")
+  .action((opts) => listCommand(opts));
+
+program
+  .command("publish")
+  .description("Publish binder from current directory")
+  .option("-d, --dir <path>", "binder directory (default: cwd)")
+  .option("--dry-run", "preview without uploading")
+  .option("--json", "output JSON")
+  .action((opts) => publishCommand(opts));
+
+program
+  .command("init")
+  .description("Scaffold a new binder in the current directory")
+  .option("-d, --dir <path>", "target directory (default: cwd)")
+  .option("-y, --yes", "skip prompts, use defaults")
+  .action((opts) => initCommand(opts));
+
+program
+  .command("auth")
+  .description("Save your Yoyo API key to ~/.yoyo/config.json")
+  .option("-k, --key <apiKey>", "API key (omit to prompt)")
+  .option("--url <apiUrl>", "custom API URL")
+  .action((opts) => authCommand(opts));
+
+program
+  .command("whoami")
+  .description("Show the currently authenticated user")
+  .option("--json", "output JSON")
+  .action((opts) => whoamiCommand(opts));
+
+program.parseAsync(process.argv);

package/src/lib/api.ts

@@ -0,0 +1,118 @@
+import { getApiKey, getApiUrl } from "./config.js";
+
+export class ApiError extends Error {
+  constructor(
+    public status: number,
+    message: string,
+    public body?: unknown
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+async function request<T>(
+  method: string,
+  path: string,
+  opts: { body?: unknown; auth?: boolean } = {}
+): Promise<T> {
+  const base = await getApiUrl();
+  const url = `${base}${path}`;
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+
+  if (opts.auth !== false) {
+    const key = await getApiKey();
+    if (key) headers["Authorization"] = `Bearer ${key}`;
+  }
+
+  const res = await fetch(url, {
+    method,
+    headers,
+    body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+  });
+
+  if (!res.ok) {
+    let detail = "";
+    try {
+      const j = (await res.json()) as { message?: string; error?: string };
+      detail = j.message ?? j.error ?? "";
+    } catch {}
+    throw new ApiError(res.status, detail || res.statusText);
+  }
+
+  return res.json() as Promise<T>;
+}
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface BinderSummary {
+  owner: string;
+  slug: string;
+  displayName?: string;
+  description?: string;
+  version?: string;
+  downloads?: number;
+  tab?: string;
+  verification?: "official" | "verified" | "none";
+  tags?: string[];
+}
+
+export interface BinderDetail extends BinderSummary {
+  readme?: string;
+  latestVersion?: {
+    version: string;
+    tarballUrl?: string;
+    tarballSha256?: string;
+    platforms?: string[];
+  };
+}
+
+export interface SearchResult {
+  items: BinderSummary[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+
+export interface WhoamiResult {
+  id: string;
+  slug: string;
+  displayName?: string;
+  email?: string;
+}
+
+// ── API calls ──────────────────────────────────────────────────────────────
+
+export const api = {
+  search: (q: string, page = 1, pageSize = 20) =>
+    request<SearchResult>("GET", `/binders?q=${encodeURIComponent(q)}&page=${page}&pageSize=${pageSize}`, {
+      auth: false,
+    }),
+
+  getBinder: (owner: string, slug: string) =>
+    request<BinderDetail>("GET", `/binders/${encodeURIComponent(owner)}/${encodeURIComponent(slug)}`, {
+      auth: false,
+    }),
+
+  listBinders: (owner?: string, page = 1, pageSize = 20) => {
+    const ownerQ = owner ? `&owner=${encodeURIComponent(owner)}` : "";
+    return request<SearchResult>("GET", `/binders?page=${page}&pageSize=${pageSize}${ownerQ}`, {
+      auth: false,
+    });
+  },
+
+  whoami: () => request<WhoamiResult>("GET", "/auth/me"),
+
+  publish: (data: {
+    slug: string;
+    displayName?: string;
+    description?: string;
+    version: string;
+    readme?: string;
+    tags?: string[];
+    tab?: string;
+    license?: string;
+    platforms?: string[];
+    dependencies?: Record<string, string>;
+  }) => request<{ id: string; slug: string; version: string }>("POST", "/binders", { body: data }),
+};

package/src/lib/config.ts

@@ -0,0 +1,45 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { existsSync } from "node:fs";
+
+export interface YoyoConfig {
+  apiKey?: string;
+  apiUrl?: string;
+}
+
+export function configPath(): string {
+  return join(homedir(), ".yoyo", "config.json");
+}
+
+export function defaultApiUrl(): string {
+  return process.env.YOYO_API_URL ?? "https://api.yoyo.bot/v1";
+}
+
+export async function loadConfig(): Promise<YoyoConfig> {
+  const p = configPath();
+  if (!existsSync(p)) return {};
+  try {
+    const raw = await readFile(p, "utf8");
+    return JSON.parse(raw) as YoyoConfig;
+  } catch {
+    return {};
+  }
+}
+
+export async function saveConfig(cfg: YoyoConfig): Promise<void> {
+  const p = configPath();
+  await mkdir(dirname(p), { recursive: true });
+  await writeFile(p, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+}
+
+export async function getApiKey(): Promise<string | undefined> {
+  if (process.env.YOYO_API_KEY) return process.env.YOYO_API_KEY;
+  const cfg = await loadConfig();
+  return cfg.apiKey;
+}
+
+export async function getApiUrl(): Promise<string> {
+  const cfg = await loadConfig();
+  return process.env.YOYO_API_URL ?? cfg.apiUrl ?? "https://api.yoyo.bot/v1";
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "composite": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}