@beel_es/cli 0.1.0 → 0.1.2

package/README.md

@@ -36,10 +36,21 @@ npx @beel_es/cli invoices export-excel --output invoices.xlsx
 npx @beel_es/cli --live invoices list          # production
 ```
 
-`--data` accepts inline JSON, `@file.json`, or `-` for stdin. Binary responses (PDF, ZIP, Excel) require `--output <path>`.
+`--data` accepts inline JSON, `@file.json`, or `-` for stdin. It is only **required** for endpoints whose request body is mandatory (e.g. `invoices create`); for lifecycle actions with an optional body (e.g. `invoices mark-paid`) it is optional, and verbs with no body (e.g. `invoices issue`) don't expose it at all. Each command's `--help` shows whether `--data` is required or optional. Binary responses (PDF, ZIP, Excel) require `--output <path>`.
 
 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.2",
       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",
@@ -10964,7 +10964,22 @@ function printJson(data) {
   process.stdout.write(`${JSON.stringify(data, null, 2)}
 `);
 }
+var INFO_CODES = /* @__PURE__ */ new Set(["commander.help", "commander.helpDisplayed", "commander.version"]);
+function commanderErrorToContract(error) {
+  if (INFO_CODES.has(error.code) || error.exitCode === 0) {
+    return { contract: null, exit: error.exitCode };
+  }
+  return { contract: { code: "USAGE_ERROR", message: stripErrorPrefix(error.message) }, exit: EXIT.USAGE };
+}
+function stripErrorPrefix(message) {
+  return message.replace(/^error:\s*/i, "");
+}
 function fail(error) {
+  if (error instanceof CommanderError) {
+    const { contract, exit } = commanderErrorToContract(error);
+    if (contract) writeError({ code: contract.code, message: contract.message });
+    process.exit(exit);
+  }
   if (error instanceof UsageError) {
     writeError({ code: "USAGE_ERROR", message: error.message });
     process.exit(EXIT.USAGE);
@@ -11081,10 +11096,11 @@ function buildQueryParams(doc, rawParams) {
 function deriveBody(doc, operation) {
   const requestBody = resolveRef(doc, operation.requestBody);
   const content = requestBody?.content;
-  if (!content) return null;
-  if ("application/json" in content) return "json";
-  if ("multipart/form-data" in content) return "multipart";
-  return null;
+  if (!content) return { kind: null, required: false };
+  const required = requestBody?.required === true;
+  if ("application/json" in content) return { kind: "json", required };
+  if ("multipart/form-data" in content) return { kind: "multipart", required };
+  return { kind: null, required: false };
 }
 function deriveBinaryResponse(doc, operation) {
   const responses = operation.responses ?? {};
@@ -11107,6 +11123,7 @@ function buildManifest(doc) {
       const operation = pathItem[method];
       if (!operation || typeof operation.operationId !== "string") continue;
       const group = deriveGroup(path);
+      const body = deriveBody(doc, operation);
       commands.push({
         group,
         action: deriveAction(group, operation.operationId, method, path),
@@ -11116,7 +11133,8 @@ function buildManifest(doc) {
         operationId: operation.operationId,
         pathParams: extractPathParams(path),
         queryParams: buildQueryParams(doc, [...sharedParams, ...operation.parameters ?? []]),
-        body: deriveBody(doc, operation),
+        body: body.kind,
+        bodyRequired: body.required,
         binaryResponse: deriveBinaryResponse(doc, operation)
       });
     }
@@ -11260,7 +11278,10 @@ function registerCommand(group, spec) {
     else sub.option(flag, description);
   }
   if (spec.body === "json") {
-    sub.requiredOption("--data <json>", "JSON body: inline, @file.json, or - for stdin");
+    const hint = spec.bodyRequired ? "JSON body (required)" : "JSON body (optional)";
+    const description = `${hint}: inline, @file.json, or - for stdin`;
+    if (spec.bodyRequired) sub.requiredOption("--data <json>", description);
+    else sub.option("--data <json>", description);
   }
   if (spec.binaryResponse) {
     sub.requiredOption("--output <path>", "Write the binary response to this file");
@@ -11372,14 +11393,152 @@ 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(
   "BeeL invoicing API CLI. JSON output on stdout, errors on stderr. Sandbox by default; pass --live for production."
 ).version(version).option("--live", "Use the live (production) API key instead of the test one");
+program2.exitOverride();
+program2.configureOutput({ outputError: () => {
+} });
 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.2",
   "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",