aicoolies 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# aicoolies
+
+Official CLI for the [aicoolies](https://aicoolies.com) developer-tools knowledge graph.
+
+Every command is an unauthenticated read of the public API. There is no API key, no signup, and no
+configuration — the CLI has zero runtime dependencies and talks to production over `fetch`.
+
+```bash
+npx aicoolies meta
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `aicoolies meta` | Collection counts and freshness timestamps (`/api/agents/meta`) |
+| `aicoolies context [--include tools,reviews] [--compact] [--category slug]` | Filterable catalog index (`/api/agents/context`) |
+| `aicoolies search <query>` | Search tools by name or slug in the CC-BY dataset |
+| `aicoolies tool <slug>` | One tool record from the CC-BY dataset |
+| `aicoolies resources` | Official developer resource URLs, fetched through the aicoolies MCP server |
+| `aicoolies openapi` | The OpenAPI 3.1 document |
+| `aicoolies --version` | Print the CLI version |
+
+Output is JSON on stdout, so it pipes into `jq` cleanly:
+
+```bash
+npx aicoolies context --include tools --compact | jq '.tools | length'
+```
+
+## Environment
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `AICOOLIES_URL` | `https://aicoolies.com` | API origin, for pointing the CLI at a local instance |
+
+## Errors
+
+Failures are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem documents. The CLI prints the
+machine-readable `code` and the human-readable `detail`, and includes the retry delay when the public
+rate limit is hit.
+
+## Related
+
+- [Developer portal](https://aicoolies.com/developers) — API docs, versioning, rate limits, error model
+- [OpenAPI](https://aicoolies.com/openapi.json) · [MCP server](https://aicoolies.com/mcp) · [llms.txt](https://aicoolies.com/llms.txt)
+- [Open data](https://aicoolies.com/data) — CC-BY 4.0 tool, comparison, and review datasets
+
+MIT licensed. The catalog datasets are CC-BY 4.0, attribution `aicoolies.com`.

package/aicoolies.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const BASE = process.env.AICOOLIES_URL ?? 'https://aicoolies.com'
+
+function packageVersion() {
+  try {
+    // The CLI ships as its own package: the manifest sits next to this file
+    // both in the repo and in the published tarball.
+    const manifest = readFileSync(fileURLToPath(new URL('./package.json', import.meta.url)), 'utf8')
+    return JSON.parse(manifest).version ?? '0.0.0'
+  } catch {
+    return '0.0.0'
+  }
+}
+
+const HELP = `aicoolies — official CLI for the aicoolies.com catalog
+
+Usage:
+  aicoolies meta                      Collection counts and freshness timestamps
+  aicoolies context [options]         Catalog index (--include tools,reviews --compact --category slug)
+  aicoolies search <query>            Search tools by name or slug
+  aicoolies tool <slug>               One tool record from the CC-BY dataset
+  aicoolies resources                 Official developer resource URLs (via the MCP server)
+  aicoolies openapi                   OpenAPI 3.1 document
+  aicoolies --version
+  aicoolies --help
+
+Every command is an unauthenticated read of the public API — no API key, no signup.
+
+Environment:
+  AICOOLIES_URL   API origin (default ${BASE})
+`
+
+function flag(args, name) {
+  const index = args.indexOf(name)
+  if (index === -1) return undefined
+  return args[index + 1]
+}
+
+async function readJson(path) {
+  const response = await fetch(`${BASE}${path}`, {
+    headers: { Accept: 'application/json' },
+  })
+  if (!response.ok) {
+    // The API answers failures with RFC 9457 problem documents; surface the
+    // machine-readable code and the human detail instead of a bare status.
+    const problem = await response.json().catch(() => null)
+    if (problem && typeof problem === 'object' && problem.code) {
+      const retry = problem.retry_after_seconds ? ` (retry in ${problem.retry_after_seconds}s)` : ''
+      throw new Error(
+        `${path} failed: ${problem.code} — ${problem.detail ?? problem.title}${retry}`,
+      )
+    }
+    throw new Error(`${path} returned ${response.status}`)
+  }
+  return response.json()
+}
+
+async function callMcpTool(name, args = {}) {
+  const response = await fetch(`${BASE}/mcp`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json, text/event-stream',
+    },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'tools/call',
+      params: { name, arguments: args },
+    }),
+  })
+  const payload = await response.json()
+  if (payload.error) throw new Error(`${name} failed: ${payload.error.message}`)
+  return payload.result?.structuredContent ?? payload.result
+}
+
+async function main(argv) {
+  const [command, ...rest] = argv
+  if (!command || command === '--help' || command === 'help' || command === '-h') {
+    process.stdout.write(HELP)
+    return
+  }
+
+  if (command === '--version' || command === '-v' || command === 'version') {
+    process.stdout.write(`${packageVersion()}\n`)
+    return
+  }
+
+  switch (command) {
+    case 'meta': {
+      process.stdout.write(`${JSON.stringify(await readJson('/api/agents/meta'), null, 2)}\n`)
+      return
+    }
+    case 'resources': {
+      process.stdout.write(
+        `${JSON.stringify(await callMcpTool('list_developer_resources'), null, 2)}\n`,
+      )
+      return
+    }
+    case 'openapi': {
+      process.stdout.write(`${JSON.stringify(await readJson('/openapi.json'), null, 2)}\n`)
+      return
+    }
+    case 'context': {
+      const params = new URLSearchParams()
+      const include = flag(rest, '--include')
+      const category = flag(rest, '--category')
+      if (include) params.set('include', include)
+      if (category) params.set('category', category)
+      if (rest.includes('--compact')) params.set('compact', 'true')
+      const query = params.toString()
+      process.stdout.write(
+        `${JSON.stringify(await readJson(`/api/agents/context${query ? `?${query}` : ''}`), null, 2)}\n`,
+      )
+      return
+    }
+    case 'search': {
+      const q = rest.join(' ').trim().toLowerCase()
+      if (!q) throw new Error('search needs a query')
+      const payload = await readJson('/data/tools.json')
+      const tools = Array.isArray(payload.tools) ? payload.tools : []
+      const hits = tools
+        .filter((tool) => `${tool.slug} ${tool.name}`.toLowerCase().includes(q))
+        .slice(0, 15)
+      process.stdout.write(`${JSON.stringify(hits, null, 2)}\n`)
+      return
+    }
+    case 'tool': {
+      const slug = rest[0]
+      if (!slug) throw new Error('tool needs a slug')
+      const payload = await readJson('/data/tools.json')
+      const tools = Array.isArray(payload.tools) ? payload.tools : []
+      const tool = tools.find((entry) => entry.slug === slug)
+      if (!tool) throw new Error(`unknown tool: ${slug}`)
+      process.stdout.write(`${JSON.stringify(tool, null, 2)}\n`)
+      return
+    }
+    default:
+      throw new Error(`unknown command: ${command}`)
+  }
+}
+
+main(process.argv.slice(2)).catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : error}\n`)
+  process.exitCode = 1
+})

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "aicoolies",
+  "version": "0.1.0",
+  "description": "Official CLI for the aicoolies.com developer-tools catalog — unauthenticated reads of the public API, MCP, and CC-BY datasets",
+  "license": "MIT",
+  "homepage": "https://aicoolies.com/developers#cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rasitakyol/aicoolies.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://aicoolies.com/contact"
+  },
+  "keywords": [
+    "aicoolies",
+    "cli",
+    "developer-tools",
+    "ai-tools",
+    "catalog",
+    "mcp",
+    "openapi",
+    "agents"
+  ],
+  "type": "module",
+  "bin": {
+    "aicoolies": "aicoolies.mjs"
+  },
+  "files": [
+    "aicoolies.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}