@beel_es/cli 0.1.0 → 0.1.1

package/README.md

@@ -40,6 +40,17 @@ npx @beel_es/cli --live invoices list          # production
 
 Discover everything with `--help` at any level: `beel --help`, `beel invoices --help`, `beel invoices list --help` (flags, enums and defaults come from the API spec).
 
+### Docs search (no API key needed)
+
+Search [docs.beel.es](https://docs.beel.es) locally — fetches `llms-full.txt` once (cached 15 min) and prints only the matching sections. An agent gets the relevant ~2KB instead of the full 660KB docs:
+
+```bash
+npx @beel_es/cli docs list                       # all pages (JSON)
+npx @beel_es/cli docs search idempotency key     # top matching sections (markdown)
+npx @beel_es/cli docs search rate limit --limit 5
+npx @beel_es/cli docs get glossary               # one full page
+```
+
 ### Generic escape hatch
 
 Any endpoint, even ones this CLI version doesn't know yet:

package/dist/index.js

@@ -10797,7 +10797,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@beel_es/cli",
-      version: "0.1.0",
+      version: "0.1.1",
       description: "Agent-first CLI for the BeeL invoicing API. Commands are derived at startup from the embedded OpenAPI spec. Run with npx @beel_es/cli \u2014 no install needed.",
       license: "MIT",
       type: "module",
@@ -11372,6 +11372,140 @@ function registerRequest(program3) {
   });
 }
 
+// src/docs/fetch.ts
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync4, statSync, mkdirSync as mkdirSync2, existsSync as existsSync2 } from "fs";
+import { tmpdir } from "os";
+import { join as join2 } from "path";
+var CACHE_TTL_MS = 15 * 60 * 1e3;
+function docsBaseUrl(env = process.env) {
+  return env.BEEL_DOCS_URL ?? "https://docs.beel.es";
+}
+async function fetchDocsFile(file, env = process.env) {
+  const cacheDir = join2(tmpdir(), "beel-cli-docs-cache");
+  const cachePath = join2(cacheDir, file);
+  if (existsSync2(cachePath) && Date.now() - statSync(cachePath).mtimeMs < CACHE_TTL_MS) {
+    return readFileSync3(cachePath, "utf8");
+  }
+  const url = `${docsBaseUrl(env)}/${file}`;
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new UsageError(`Cannot fetch docs from ${url} (HTTP ${response.status})`);
+  }
+  const text = await response.text();
+  mkdirSync2(cacheDir, { recursive: true });
+  writeFileSync4(cachePath, text);
+  return text;
+}
+
+// src/docs/parse.ts
+function splitChunks(fullText) {
+  const chunks = [];
+  let page = "";
+  let heading = null;
+  let buffer = [];
+  let inFence = false;
+  const flush = () => {
+    const content = buffer.join("\n").trim();
+    if (page && content) chunks.push({ page, heading, content });
+    buffer = [];
+  };
+  for (const line of fullText.split("\n")) {
+    if (line.trimStart().startsWith("```")) {
+      inFence = !inFence;
+      buffer.push(line);
+      continue;
+    }
+    if (!inFence && line.startsWith("# ")) {
+      flush();
+      page = line.slice(2).trim();
+      heading = null;
+      continue;
+    }
+    if (!inFence && line.startsWith("## ")) {
+      flush();
+      heading = line.slice(3).trim();
+      continue;
+    }
+    buffer.push(line);
+  }
+  flush();
+  return chunks;
+}
+function parseIndex(indexText) {
+  const pages = [];
+  for (const line of indexText.split("\n")) {
+    const match = line.match(/^-\s*\[([^\]]+)\]\((\S+)\)\s*-?\s*(.*)$/);
+    if (match) {
+      pages.push({ title: match[1], url: match[2], description: match[3].trim() });
+    }
+  }
+  return pages;
+}
+function scoreChunk(chunk, terms) {
+  const haystack = chunk.content.toLowerCase();
+  const titleHaystack = `${chunk.page} ${chunk.heading ?? ""}`.toLowerCase();
+  let score = 0;
+  let termsHit = 0;
+  for (const term of terms) {
+    const t = term.toLowerCase();
+    const contentHits = haystack.split(t).length - 1;
+    const titleHits = titleHaystack.split(t).length - 1;
+    if (contentHits + titleHits > 0) termsHit++;
+    score += contentHits + titleHits * 5;
+  }
+  if (termsHit === terms.length && terms.length > 1) score *= 2;
+  return termsHit === 0 ? 0 : score;
+}
+function searchChunks(chunks, terms, limit) {
+  return chunks.map((chunk) => ({ chunk, score: scoreChunk(chunk, terms) })).filter((s) => s.score > 0).sort((a, b) => b.score - a.score).slice(0, limit).map((s) => s.chunk);
+}
+function findPage(chunks, titleQuery) {
+  const q = titleQuery.toLowerCase();
+  const titles = [...new Set(chunks.map((c) => c.page))];
+  const exact = titles.find((t) => t.toLowerCase() === q);
+  const partial = titles.filter((t) => t.toLowerCase().includes(q));
+  const title = exact ?? (partial.length === 1 ? partial[0] : void 0);
+  if (!title) return [];
+  return chunks.filter((c) => c.page === title);
+}
+
+// src/commands/docs.ts
+function registerDocs(program3) {
+  const docs = program3.command("docs").description(
+    "Search the BeeL API docs. Downloads docs.beel.es/llms-full.txt once (cached 15 min in tmpdir), then filters locally \u2014 search terms never leave your machine. No API key needed."
+  );
+  docs.command("list").description("List all documentation pages").action(async () => {
+    const index = await fetchDocsFile("llms.txt");
+    printJson(parseIndex(index));
+  });
+  docs.command("search").description("Search the docs; prints only the matching sections as markdown").argument("<terms...>", "Search terms").option("--limit <n>", "Max sections to print", Number, 3).action(async (terms, opts) => {
+    const full = await fetchDocsFile("llms-full.txt");
+    const results = searchChunks(splitChunks(full), terms, opts.limit);
+    if (results.length === 0) {
+      throw new UsageError(`No docs sections match: ${terms.join(" ")}. Try 'beel docs list' to see available pages.`);
+    }
+    printChunks(results);
+  });
+  docs.command("get").description("Print a full documentation page as markdown").argument("<title...>", 'Page title (or unambiguous part of it), e.g. "idempotency"').action(async (titleParts) => {
+    const full = await fetchDocsFile("llms-full.txt");
+    const chunks = findPage(splitChunks(full), titleParts.join(" "));
+    if (chunks.length === 0) {
+      throw new UsageError(`No page matches '${titleParts.join(" ")}' unambiguously. Run 'beel docs list' to see titles.`);
+    }
+    printChunks(chunks);
+  });
+}
+function printChunks(chunks) {
+  for (const chunk of chunks) {
+    const location = chunk.heading ? `${chunk.page} \u203A ${chunk.heading}` : chunk.page;
+    process.stdout.write(`
+\u2501\u2501\u2501 ${location} \u2501\u2501\u2501
+
+${chunk.content}
+`);
+  }
+}
+
 // src/index.ts
 var { version } = require_package();
 var program2 = new Command("beel").description(
@@ -11380,6 +11514,7 @@ var program2 = new Command("beel").description(
 registerLogin(program2);
 registerConfig(program2);
 registerRequest(program2);
+registerDocs(program2);
 try {
   registerSpecCommands(program2, (0, import_yaml.parse)(public_api_default));
 } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beel_es/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Agent-first CLI for the BeeL invoicing API. Commands are derived at startup from the embedded OpenAPI spec. Run with npx @beel_es/cli — no install needed.",
   "license": "MIT",
   "type": "module",