@easydocs/cli 0.1.4

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 EasyDocs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @easydocs/cli
+
+Zero-install proxy and spec export for [EasyDocs](https://github.com/RubenGlez/easydocs).
+
+## Proxy mode — zero code changes
+
+Route your requests through the EasyDocs proxy and it captures traffic automatically. No middleware to install, no code to change.
+
+```bash
+npx @easydocs/cli proxy --project=my-api --port=3999
+```
+
+Then send requests through the proxy:
+
+```
+http://localhost:3999?target=https://api.example.com/users
+```
+
+Every request is captured and an OpenAPI spec is generated in the background.
+
+## Dashboard
+
+```bash
+npx @easydocs/cli dashboard
+# requires @easydocs/dashboard to be installed
+npm install -D @easydocs/dashboard
+```
+
+## Export spec
+
+```bash
+# JSON (default)
+npx @easydocs/cli export
+
+# YAML
+npx @easydocs/cli export --yaml
+
+# Scoped to a project
+npx @easydocs/cli export --project=my-api
+
+# Pipe to a file
+npx @easydocs/cli export > openapi.json
+```
+
+## Flags
+
+| Flag | Command | Default | Description |
+|------|---------|---------|-------------|
+| `--port=<n>` | proxy | `3999` | Port for the proxy server |
+| `--port=<n>` | dashboard | `4999` | Port for the dashboard |
+| `--project=<slug>` | proxy, export | `default` | Scope to a project |
+| `--yaml` | export | — | Output YAML instead of JSON |
+| `--prod` | dashboard | — | Run `next start` instead of `next dev` |
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `EASYDOCS_DB_URL` | Database URL (default: `~/.easydocs/db.sqlite`) |
+| `OPENAI_API_KEY` | OpenAI API key |
+| `ANTHROPIC_API_KEY` | Anthropic API key |
+| `EASYDOCS_DASHBOARD_PATH` | Path to a custom dashboard directory |

package/dist/index.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { createDB, getAllEndpoints, getEndpointsByProject, findOrCreateProject } from "@easydocs/core";
+import { capture } from "@easydocs/core";
+import { createServer } from "http";
+import { createRequire } from "module";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { spawn } from "child_process";
+import yaml from "js-yaml";
+var [, , command, ...args] = process.argv;
+switch (command) {
+  case "dashboard":
+    await runDashboard(args);
+    break;
+  case "export":
+    await runExport(args);
+    break;
+  case "proxy":
+  case void 0:
+    await runProxy(args);
+    break;
+  default:
+    console.error(
+      `Unknown command: ${command}
+
+Usage:
+  easydocs [proxy]           Start proxy server
+  easydocs dashboard         Start the docs dashboard
+  easydocs export            Export spec to stdout
+
+Flags:
+  --project=<slug>           Scope to a project (default: all)
+  --port=<n>                 Port for proxy (default: 3999) or dashboard (default: 4999)
+  --yaml                     Export as YAML instead of JSON
+  --prod                     Dashboard: run next start instead of next dev`
+    );
+    process.exit(1);
+}
+function getFlag(args2, name) {
+  const entry = args2.find((a) => a.startsWith(`--${name}=`));
+  return entry?.split("=").slice(1).join("=");
+}
+function findDashboardDir() {
+  if (process.env.EASYDOCS_DASHBOARD_PATH) {
+    return process.env.EASYDOCS_DASHBOARD_PATH;
+  }
+  try {
+    const req = createRequire(join(process.cwd(), "package.json"));
+    const pkgPath = req.resolve("@easydocs/dashboard/package.json");
+    return dirname(pkgPath);
+  } catch {
+  }
+  let dir = process.cwd();
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, "pnpm-workspace.yaml"))) {
+      const candidate = join(dir, "apps", "dashboard");
+      if (existsSync(join(candidate, "package.json"))) return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+async function runDashboard(args2) {
+  const port = parseInt(getFlag(args2, "port") ?? "4999", 10);
+  const prod = args2.includes("--prod");
+  const dashboardDir = findDashboardDir();
+  if (!dashboardDir) {
+    console.error("[EasyDocs] Dashboard package not found.\n");
+    console.error("Install it:");
+    console.error("  npm install -D @easydocs/dashboard");
+    console.error("  pnpm add -D @easydocs/dashboard\n");
+    console.error("Then run:");
+    console.error("  npx easydocs dashboard");
+    console.error("\nOr set EASYDOCS_DASHBOARD_PATH to your dashboard directory.");
+    process.exit(1);
+  }
+  const nextBin = join(dashboardDir, "node_modules", ".bin", "next");
+  const cmd = existsSync(nextBin) ? nextBin : "next";
+  const mode = prod ? ["start", "--port", String(port)] : ["dev", "--port", String(port)];
+  console.log(`[EasyDocs] Starting dashboard (${prod ? "production" : "dev"}) \u2192 http://localhost:${port}`);
+  const child = spawn(cmd, mode, {
+    cwd: dashboardDir,
+    stdio: "inherit",
+    shell: process.platform === "win32",
+    env: { ...process.env, EASYDOCS_DB_URL: process.env.EASYDOCS_DB_URL }
+  });
+  child.on("exit", (code) => process.exit(code ?? 0));
+}
+async function runExport(args2) {
+  const format = args2.includes("--yaml") ? "yaml" : "json";
+  const projectSlug = getFlag(args2, "project");
+  const db = createDB(process.env.EASYDOCS_DB_URL);
+  let endpoints;
+  if (projectSlug) {
+    const projectId = await findOrCreateProject(db, projectSlug);
+    endpoints = await getEndpointsByProject(db, projectId);
+  } else {
+    endpoints = await getAllEndpoints(db);
+  }
+  const spec = {
+    openapi: "3.0.3",
+    info: { title: projectSlug ?? "API Documentation", version: "1.0.0" },
+    paths: endpoints.reduce((acc, e) => {
+      if (!e.path || !e.method) return acc;
+      const activeSpec = e.isManuallyEdited && e.manualSpec ? e.manualSpec : e.spec;
+      if (!activeSpec) return acc;
+      if (!acc[e.path]) acc[e.path] = {};
+      acc[e.path][e.method.toLowerCase()] = activeSpec;
+      return acc;
+    }, {})
+  };
+  process.stdout.write(format === "yaml" ? yaml.dump(spec) : JSON.stringify(spec, null, 2));
+}
+async function runProxy(args2) {
+  const port = parseInt(getFlag(args2, "port") ?? "3999", 10);
+  const projectSlug = getFlag(args2, "project") ?? "default";
+  const server = createServer(async (req, res) => {
+    const reqUrl = new URL(req.url ?? "/", `http://localhost:${port}`);
+    const targetParam = reqUrl.searchParams.get("target");
+    if (!targetParam) {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Missing ?target=<url> query parameter" }));
+      return;
+    }
+    let targetUrl;
+    try {
+      targetUrl = new URL(decodeURIComponent(targetParam));
+    } catch {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Invalid target URL" }));
+      return;
+    }
+    const method = req.method ?? "GET";
+    const startedAt = Date.now();
+    let requestBody;
+    if (method !== "GET" && method !== "HEAD") {
+      requestBody = await new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(c));
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+      });
+    }
+    const upstream = await fetch(targetUrl.toString(), {
+      method,
+      headers: Object.fromEntries(
+        Object.entries(req.headers).filter(([k]) => k !== "host").map(([k, v]) => [k, String(v)])
+      ),
+      body: requestBody
+    });
+    const responseText = await upstream.text();
+    let responseBody;
+    try {
+      responseBody = JSON.parse(responseText);
+    } catch {
+      responseBody = responseText;
+    }
+    let parsedRequestBody = null;
+    if (requestBody?.length) {
+      try {
+        parsedRequestBody = JSON.parse(requestBody.toString());
+      } catch {
+        parsedRequestBody = requestBody.toString();
+      }
+    }
+    capture(
+      {
+        method,
+        path: targetUrl.pathname,
+        query: Object.fromEntries(targetUrl.searchParams.entries()),
+        params: {},
+        body: parsedRequestBody,
+        response: responseBody,
+        status: upstream.status,
+        requestHeaders: req.headers,
+        responseHeaders: Object.fromEntries(upstream.headers.entries()),
+        durationMs: Date.now() - startedAt
+      },
+      { project: projectSlug }
+    );
+    res.writeHead(upstream.status, Object.fromEntries(upstream.headers.entries()));
+    res.end(responseText);
+  });
+  server.listen(port, () => {
+    console.log(`[EasyDocs] Proxy \u2192 http://localhost:${port} (project: ${projectSlug})`);
+    console.log(`[EasyDocs] Usage: http://localhost:${port}?target=https://api.example.com/users`);
+    console.log(`[EasyDocs] Dashboard: npx easydocs dashboard`);
+  });
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@easydocs/cli",
+  "version": "0.1.4",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "description": "EasyDocs CLI — proxy mode and spec export",
+  "type": "module",
+  "bin": {
+    "easydocs": "./dist/index.js"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0",
+    "@easydocs/core": "0.1.4"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20",
+    "tsup": "^8.3.0",
+    "typescript": "^5"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}