@mdocs/cli 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# @mdocs/cli
+
+Command-line interface for mDocs — spins up a local documentation server that serves markdown files from cloned GitHub repositories.
+
+## Installation
+
+```sh
+npm install -g @mdocs/cli
+```
+
+Or run without installing:
+
+```sh
+npx @mdocs/cli <command>
+```
+
+## Requirements
+
+- Node.js >= 18
+- Git (must be available in `PATH`)
+
+## Commands
+
+### `mdocs setup`
+
+Initializes the `.mdocs/` project structure in the target directory.
+
+```sh
+mdocs setup [options]
+```
+
+| Option | Description | Default |
+|---|---|---|
+| `-d, --data-dir <dir>` | Directory to initialize | current working directory |
+
+Creates:
+```
+.mdocs/
+└── repos/
+```
+
+### `mdocs serve`
+
+Starts the mDocs local HTTP server. If `.mdocs/` does not exist, you will be prompted to initialize it first.
+
+```sh
+mdocs serve [options]
+```
+
+| Option | Description | Default |
+|---|---|---|
+| `-p, --port <port>` | Port to listen on | `4873` |
+| `-H, --host <host>` | Host to bind to | `127.0.0.1` |
+| `-d, --data-dir <dir>` | Directory containing `.mdocs/` | current working directory |
+| `-o, --origin <origin>` | Extra CORS origin to allow | — |
+
+**Examples:**
+
+```sh
+# Start with defaults
+mdocs serve
+
+# Custom port
+mdocs serve --port 5000
+
+# Allow a custom frontend origin
+mdocs serve --origin http://localhost:5173
+
+# Point at a specific data directory
+mdocs serve --data-dir /path/to/project
+```
+
+Once running, the server is available at `http://127.0.0.1:4873` by default.
+
+## Typical workflow
+
+```sh
+# 1. Initialize in your project
+cd my-project
+mdocs setup
+
+# 2. Start the server
+mdocs serve
+
+# 3. Use the REST API to clone a repo and browse its docs
+curl -X POST http://127.0.0.1:4873/api/repos/clone \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://github.com/owner/repo"}'
+```
+
+## REST API
+
+The CLI delegates all HTTP logic to `@mdocs/server`. See the [`@mdocs/server` README](../server/README.md) for the full API reference.
+
+## Related packages
+
+- [`@mdocs/server`](https://www.npmjs.com/package/@mdocs/server) — the underlying HTTP server (used internally by this CLI)

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/serve.ts
+import chalk2 from "chalk";
+import inquirer from "inquirer";
+import { startServer, DEFAULT_ORIGINS } from "@mdocs/server";
+
+// src/lib/mdocs.ts
+import { existsSync, mkdirSync } from "fs";
+import { join } from "path";
+var MDOCS_DIR = ".mdocs";
+var REPOS_DIR = join(MDOCS_DIR, "repos");
+function mdocsExists(cwd) {
+  return existsSync(join(cwd, MDOCS_DIR));
+}
+function reposDirExists(cwd) {
+  return existsSync(join(cwd, REPOS_DIR));
+}
+function createMdocsStructure(cwd) {
+  mkdirSync(join(cwd, REPOS_DIR), { recursive: true });
+}
+function resolveDataDir(dataDir) {
+  if (!dataDir) return process.cwd();
+  return dataDir.startsWith(".") ? join(process.cwd(), dataDir) : dataDir;
+}
+
+// src/commands/setup.ts
+import chalk from "chalk";
+async function runSetup(cwd) {
+  const dir = resolveDataDir(cwd);
+  console.log(chalk.dim("\n  Setting up mDocs project structure...\n"));
+  createMdocsStructure(dir);
+  console.log(chalk.green("  \u2713") + chalk.white(`  ${MDOCS_DIR}/`));
+  console.log(chalk.green("  \u2713") + chalk.white(`  ${REPOS_DIR}/`));
+  console.log(chalk.bold.green("\n  mDocs initialized successfully!\n"));
+}
+
+// src/lib/banner.ts
+import gradient from "gradient-string";
+import figlet from "figlet";
+var GRADIENT = ["#06b6d4", "#8b5cf6", "#ec4899"];
+function printBanner() {
+  const text = figlet.textSync("mDocs", { font: "ANSI Shadow" });
+  console.log(gradient(GRADIENT).multiline(text));
+  console.log();
+}
+
+// src/commands/serve.ts
+async function serve(options) {
+  const cwd = resolveDataDir(options.dataDir);
+  const port = parseInt(options.port, 10);
+  const host = options.host;
+  if (!mdocsExists(cwd) || !reposDirExists(cwd)) {
+    console.log(chalk2.yellow("\n  \u26A0  No .mdocs directory found in this project.\n"));
+    const { confirm } = await inquirer.prompt([
+      {
+        type: "confirm",
+        name: "confirm",
+        message: "Would you like to initialize mDocs for this project?",
+        default: true
+      }
+    ]);
+    if (!confirm) {
+      console.log(
+        chalk2.dim("\n  Aborted. Run ") + chalk2.cyan("mdocs setup") + chalk2.dim(" to initialize manually.\n")
+      );
+      process.exit(0);
+    }
+    await runSetup(cwd);
+  }
+  console.log(chalk2.dim(`
+  Starting server on ${host}:${port}...
+`));
+  const origins = options.origin ? [options.origin, ...DEFAULT_ORIGINS] : DEFAULT_ORIGINS;
+  const server = await startServer({ port, host, dataDir: cwd, origins });
+  printBanner();
+  console.log(
+    chalk2.bold("  Server running at ") + chalk2.bold.underline.cyan(`http://${host}:${port}`)
+  );
+  console.log(chalk2.dim(`  Health: http://${host}:${port}/health`));
+  if (options.origin) {
+    console.log(chalk2.dim(`  CORS origin: ${options.origin}`));
+  }
+  console.log(chalk2.dim("\n  Press Ctrl+C to stop.\n"));
+  process.on("SIGINT", () => {
+    console.log(chalk2.dim("\n  Stopping mDocs server\u2026\n"));
+    server.close(() => process.exit(0));
+  });
+}
+
+// src/index.ts
+var program = new Command();
+program.name("mdocs").description("mDocs \u2014 local documentation server").version("0.1.0");
+program.command("serve").description("Start the mDocs local server").option("-p, --port <port>", "Port to listen on", "4873").option("-H, --host <host>", "Host to bind to", "127.0.0.1").option("-d, --data-dir <dir>", "Directory that holds (or will hold) .mdocs/").option("-o, --origin <origin>", "Allowed CORS origin").action(serve);
+program.command("setup").description("Initialize .mdocs/ project structure in the current directory").option("-d, --data-dir <dir>", "Target directory (defaults to cwd)").action((opts) => runSetup(opts.dataDir));
+program.parse();

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@mdocs/cli",
+  "version": "0.1.0",
+  "description": "mDocs CLI — start the local documentation server",
+  "type": "module",
+  "bin": {
+    "mdocs": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "figlet": "^1.7.0",
+    "gradient-string": "^2.0.2",
+    "inquirer": "^9.2.23",
+    "@mdocs/server": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/figlet": "^1.5.8",
+    "@types/node": "^20.14.0",
+    "tsup": "^8.1.0",
+    "tsx": "^4.15.0",
+    "typescript": "^5.4.5"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "dev:serve": "tsx src/index.ts serve",
+    "typecheck": "tsc --noEmit"
+  }
+}