@mdocs/server 0.1.0

package/README.md

@@ -0,0 +1,248 @@
+# @mdocs/server
+
+Local HTTP server for mDocs. Clones public GitHub repositories, scans them for markdown files, and exposes their content over a REST API.
+
+## Installation
+
+```sh
+npm install @mdocs/server
+```
+
+## Requirements
+
+- Node.js >= 18
+- Git (must be available in `PATH` for clone/sync operations)
+
+## Programmatic usage
+
+### `startServer(overrides?)`
+
+Starts the server and returns a Node.js `http.Server`.
+
+```ts
+import { startServer } from '@mdocs/server';
+
+const server = await startServer({
+  port: 4873,
+  host: '127.0.0.1',
+  dataDir: '/path/to/project',
+  origins: ['http://localhost:3000'],
+});
+
+console.log('Server started');
+```
+
+### `createApp(config)`
+
+Creates and returns an Express app without starting it — useful for testing or custom server setups.
+
+```ts
+import { createApp, parseConfig } from '@mdocs/server';
+
+const config = parseConfig({ port: 4873 });
+const app = createApp(config);
+
+app.listen(config.port, config.host);
+```
+
+### `parseConfig(overrides?)`
+
+Merges overrides with environment variables and built-in defaults.
+
+```ts
+import { parseConfig } from '@mdocs/server';
+
+const config = parseConfig({ port: 5000 });
+// { port: 5000, host: '127.0.0.1', dataDir: process.cwd(), origins: [...] }
+```
+
+## Configuration
+
+| Option | Env var | Default |
+|---|---|---|
+| `port` | `PORT` | `4873` |
+| `host` | `HOST` | `127.0.0.1` |
+| `dataDir` | `DATA_DIR` | `process.cwd()` |
+| `origins` | — | `['http://localhost:3000', 'http://127.0.0.1:3000', 'https://mdocs.vercel.app']` |
+
+## Standalone usage
+
+Run the server directly without the CLI:
+
+```sh
+node node_modules/@mdocs/server/dist/index.js
+```
+
+Or with environment variables:
+
+```sh
+PORT=5000 DATA_DIR=/my/project node node_modules/@mdocs/server/dist/index.js
+```
+
+## REST API
+
+Base URL: `http://127.0.0.1:4873`
+
+---
+
+### Health
+
+#### `GET /health`
+
+Returns server status.
+
+```jsonc
+// 200 OK
+{ "ok": true, "name": "mdocs-server", "version": "0.1.0" }
+```
+
+---
+
+### Repositories
+
+#### `GET /api/repos`
+
+Lists all tracked repositories.
+
+```jsonc
+// 200 OK
+[
+  {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "name": "owner/repo",
+    "url": "https://github.com/owner/repo",
+    "branch": "main",
+    "clonedAt": "2026-05-09T10:00:00.000Z",
+    "lastSyncedAt": null,
+    "currentCommit": "abc1234...",
+    "fileCount": 12
+  }
+]
+```
+
+---
+
+#### `POST /api/repos/clone`
+
+Clones a public GitHub repository and starts tracking it.
+
+**Request body:**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `url` | `string` | Yes | Public GitHub HTTPS URL (`https://github.com/owner/repo`) |
+| `branch` | `string` | No | Branch to clone (defaults to the repo's default branch) |
+
+```sh
+curl -X POST http://127.0.0.1:4873/api/repos/clone \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://github.com/owner/repo", "branch": "main"}'
+```
+
+```jsonc
+// 201 Created
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "owner/repo",
+  "url": "https://github.com/owner/repo",
+  "branch": "main",
+  "clonedAt": "2026-05-09T10:00:00.000Z",
+  "lastSyncedAt": null,
+  "currentCommit": "abc1234...",
+  "fileCount": 12
+}
+```
+
+> Only public `https://github.com/owner/repo` URLs are accepted. SSH URLs and non-GitHub hosts are rejected.
+
+---
+
+#### `POST /api/repos/:repoId/sync`
+
+Pulls the latest changes for a tracked repository (`git pull --ff-only`).
+
+```sh
+curl -X POST http://127.0.0.1:4873/api/repos/550e8400-e29b-41d4-a716-446655440000/sync
+```
+
+Returns the updated `RepoMeta` object.
+
+---
+
+#### `DELETE /api/repos/:repoId`
+
+Removes a repository from tracking and deletes its local clone.
+
+```sh
+curl -X DELETE http://127.0.0.1:4873/api/repos/550e8400-e29b-41d4-a716-446655440000
+```
+
+```
+204 No Content
+```
+
+---
+
+### Files
+
+#### `GET /api/repos/:repoId/files`
+
+Lists all markdown files in the repository (`.md`, `.mdx`, `.markdown`). Files larger than 1 MB and common non-doc directories (`node_modules`, `dist`, `.git`, etc.) are excluded.
+
+```jsonc
+// 200 OK
+[
+  {
+    "id": "docs/intro.md",
+    "repoId": "550e8400-e29b-41d4-a716-446655440000",
+    "name": "intro.md",
+    "relPath": "docs/intro.md",
+    "size": 1024,
+    "lastModified": 1746784800000
+  }
+]
+```
+
+---
+
+#### `GET /api/repos/:repoId/files/:path`
+
+Returns the content of a specific file.
+
+```sh
+curl http://127.0.0.1:4873/api/repos/550e8400-e29b-41d4-a716-446655440000/files/docs/intro.md
+```
+
+```jsonc
+// 200 OK
+{
+  "id": "docs/intro.md",
+  "repoId": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "intro.md",
+  "relPath": "docs/intro.md",
+  "size": 1024,
+  "lastModified": 1746784800000,
+  "content": "# Introduction\n\nWelcome to the docs..."
+}
+```
+
+---
+
+## TypeScript types
+
+All public types are exported:
+
+```ts
+import type { Config, RepoMeta, FileRef, FileContent } from '@mdocs/server';
+```
+
+## Security
+
+- CORS is enforced — only origins listed in `config.origins` are allowed.
+- Only `https://github.com` URLs are accepted for cloning.
+- File reads are path-traversal-safe — resolved paths are checked to stay within the clone directory.
+- Repository IDs are validated against path traversal before any file operation.
+
+## Related packages
+
+- [`@mdocs/cli`](https://www.npmjs.com/package/@mdocs/cli) — CLI wrapper around this server

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import { Server } from 'node:http';
+import { Express } from 'express';
+
+interface RepoMeta {
+    id: string;
+    name: string;
+    url: string;
+    branch: string;
+    clonedAt: string;
+    lastSyncedAt: string | null;
+    currentCommit: string | null;
+    fileCount: number;
+}
+interface FileRef {
+    id: string;
+    repoId: string;
+    name: string;
+    relPath: string;
+    size: number;
+    lastModified: number;
+}
+interface FileContent extends FileRef {
+    content: string;
+}
+interface Config {
+    port: number;
+    host: string;
+    dataDir: string;
+    origins: string[];
+}
+
+declare function createApp(config: Config): Express;
+
+declare const DEFAULT_PORT = 4873;
+declare const DEFAULT_HOST = "127.0.0.1";
+declare const DEFAULT_ORIGINS: string[];
+declare function parseConfig(overrides?: Partial<Config>): Config;
+declare function reposDir(dataDir: string): string;
+
+declare function startServer(overrides?: Partial<Config>): Promise<Server>;
+
+export { type Config, DEFAULT_HOST, DEFAULT_ORIGINS, DEFAULT_PORT, type FileContent, type FileRef, type RepoMeta, createApp, parseConfig, reposDir, startServer };

package/dist/index.js

@@ -0,0 +1,377 @@
+// src/index.ts
+import { fileURLToPath } from "url";
+import { resolve as resolve3 } from "path";
+
+// src/app.ts
+import express from "express";
+
+// src/security/cors.ts
+import cors from "cors";
+function createCorsMiddleware(config) {
+  return cors({
+    origin: (origin, cb) => {
+      if (!origin) return cb(null, true);
+      if (config.origins.includes(origin)) return cb(null, true);
+      cb(new Error(`Origin ${origin} is not allowed`));
+    },
+    methods: ["GET", "POST", "DELETE", "OPTIONS"],
+    allowedHeaders: ["Content-Type"]
+  });
+}
+
+// src/routes/health.ts
+import { Router } from "express";
+function healthRouter() {
+  const router = Router();
+  router.get("/", (_req, res) => {
+    res.json({ ok: true, name: "mdocs-server", version: "0.1.0" });
+  });
+  return router;
+}
+
+// src/routes/repos.ts
+import { Router as Router3 } from "express";
+import { randomUUID } from "crypto";
+import { join as join4 } from "path";
+
+// src/config.ts
+import { resolve } from "path";
+var DEFAULT_PORT = 4873;
+var DEFAULT_HOST = "127.0.0.1";
+var MDOCS_DIR = ".mdocs";
+var REPOS_SUBDIR = "repos";
+var DEFAULT_ORIGINS = [
+  "http://localhost:3000",
+  "http://127.0.0.1:3000",
+  "https://mdocs.vercel.app"
+];
+function parseConfig(overrides = {}) {
+  return {
+    port: overrides.port ?? parseInt(process.env["PORT"] ?? String(DEFAULT_PORT), 10),
+    host: overrides.host ?? process.env["HOST"] ?? DEFAULT_HOST,
+    dataDir: overrides.dataDir ?? process.env["DATA_DIR"] ?? process.cwd(),
+    origins: overrides.origins ?? DEFAULT_ORIGINS
+  };
+}
+function reposDir(dataDir) {
+  return resolve(dataDir, MDOCS_DIR, REPOS_SUBDIR);
+}
+
+// src/security/github-url.ts
+function validateGitHubUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "https:") return null;
+    if (parsed.hostname !== "github.com") return null;
+    const parts = parsed.pathname.replace(/^\//, "").replace(/\.git$/, "").split("/");
+    if (parts.length !== 2 || !parts[0] || !parts[1]) return null;
+    return { owner: parts[0], repo: parts[1] };
+  } catch {
+    return null;
+  }
+}
+
+// src/services/git.ts
+import { spawn } from "child_process";
+function run(args, cwd) {
+  return new Promise((resolve4, reject) => {
+    const proc = spawn("git", args, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (chunk) => stdout += chunk.toString());
+    proc.stderr.on("data", (chunk) => stderr += chunk.toString());
+    proc.on("close", (code) => {
+      if (code === 0) resolve4(stdout.trim());
+      else reject(new Error(stderr.trim() || `git exited with code ${code}`));
+    });
+    proc.on("error", reject);
+  });
+}
+async function cloneRepo(url, dest, branch) {
+  const args = ["clone", url, dest, "--single-branch"];
+  if (branch) args.push("--branch", branch);
+  await run(args);
+}
+async function pullRepo(repoPath) {
+  await run(["pull", "--ff-only"], repoPath);
+}
+async function getHeadCommit(repoPath) {
+  return run(["rev-parse", "HEAD"], repoPath);
+}
+async function getDefaultBranch(repoPath) {
+  try {
+    return await run(["symbolic-ref", "--short", "HEAD"], repoPath);
+  } catch {
+    return "main";
+  }
+}
+
+// src/services/scanner.ts
+import { readdirSync, statSync } from "fs";
+import { join, relative, basename, extname } from "path";
+var SKIP_DIRS = /* @__PURE__ */ new Set([
+  ".git",
+  "node_modules",
+  ".next",
+  "dist",
+  "build",
+  ".turbo",
+  "vendor",
+  ".cache"
+]);
+var MD_EXTS = /* @__PURE__ */ new Set([".md", ".markdown", ".mdx"]);
+var MAX_FILE_SIZE = 1024 * 1024;
+function scanMarkdownFiles(repoPath, repoId) {
+  const results = [];
+  function walk(dir) {
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (SKIP_DIRS.has(entry)) continue;
+      const fullPath = join(dir, entry);
+      let stat;
+      try {
+        stat = statSync(fullPath);
+      } catch {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        walk(fullPath);
+        continue;
+      }
+      if (!stat.isFile()) continue;
+      if (!MD_EXTS.has(extname(entry).toLowerCase())) continue;
+      if (stat.size > MAX_FILE_SIZE) continue;
+      const relPath = relative(repoPath, fullPath).replace(/\\/g, "/");
+      results.push({
+        id: relPath,
+        repoId,
+        name: basename(entry),
+        relPath,
+        size: stat.size,
+        lastModified: stat.mtimeMs
+      });
+    }
+  }
+  walk(repoPath);
+  return results;
+}
+
+// src/services/repo-store.ts
+import { readFileSync, writeFileSync, existsSync, readdirSync as readdirSync2, unlinkSync, rmSync } from "fs";
+import { join as join2 } from "path";
+function listRepos(reposDir2) {
+  if (!existsSync(reposDir2)) return [];
+  return readdirSync2(reposDir2).filter((f) => f.endsWith(".json")).flatMap((f) => {
+    try {
+      return [JSON.parse(readFileSync(join2(reposDir2, f), "utf8"))];
+    } catch {
+      return [];
+    }
+  });
+}
+function getRepo(reposDir2, id) {
+  if (id.includes("/") || id.includes("\\") || id.includes("..")) return null;
+  const file = join2(reposDir2, `${id}.json`);
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function saveRepo(reposDir2, meta) {
+  writeFileSync(join2(reposDir2, `${meta.id}.json`), JSON.stringify(meta, null, 2), "utf8");
+}
+function deleteRepo(reposDir2, id) {
+  if (id.includes("/") || id.includes("\\") || id.includes("..")) return;
+  const metaFile = join2(reposDir2, `${id}.json`);
+  const cloneDir = join2(reposDir2, id);
+  if (existsSync(metaFile)) unlinkSync(metaFile);
+  if (existsSync(cloneDir)) rmSync(cloneDir, { recursive: true, force: true });
+}
+
+// src/routes/files.ts
+import { Router as Router2 } from "express";
+import { readFileSync as readFileSync2, statSync as statSync2, existsSync as existsSync2 } from "fs";
+import { join as join3 } from "path";
+
+// src/security/paths.ts
+import { resolve as resolve2 } from "path";
+function safeResolve(base, ...parts) {
+  const resolved = resolve2(base, ...parts);
+  return resolved.startsWith(base) ? resolved : null;
+}
+
+// src/routes/files.ts
+function filesRouter(config) {
+  const router = Router2({ mergeParams: true });
+  const reposDir2 = reposDir(config.dataDir);
+  router.get("*", (req, res) => {
+    const { repoId } = req.params;
+    if (!getRepo(reposDir2, repoId)) {
+      res.status(404).json({ error: "Repository not found" });
+      return;
+    }
+    const cloneDir = join3(reposDir2, repoId);
+    const relPath = req.path === "/" ? "" : decodeURIComponent(req.path.slice(1));
+    if (!relPath) {
+      res.json(scanMarkdownFiles(cloneDir, repoId));
+      return;
+    }
+    const absPath = safeResolve(cloneDir, relPath);
+    if (!absPath) {
+      res.status(400).json({ error: "Invalid file path" });
+      return;
+    }
+    if (!existsSync2(absPath)) {
+      res.status(404).json({ error: "File not found" });
+      return;
+    }
+    try {
+      const stat = statSync2(absPath);
+      const content = readFileSync2(absPath, "utf8");
+      const file = {
+        id: relPath,
+        repoId,
+        name: relPath.split("/").pop() ?? relPath,
+        relPath,
+        size: stat.size,
+        lastModified: stat.mtimeMs,
+        content
+      };
+      res.json(file);
+    } catch {
+      res.status(500).json({ error: "Failed to read file" });
+    }
+  });
+  return router;
+}
+
+// src/routes/repos.ts
+function reposRouter(config) {
+  const router = Router3();
+  const reposDir2 = reposDir(config.dataDir);
+  router.use("/:repoId/files", filesRouter(config));
+  router.get("/", (_req, res) => {
+    res.json(listRepos(reposDir2));
+  });
+  router.post("/clone", async (req, res) => {
+    const { url, branch } = req.body;
+    if (!url || typeof url !== "string") {
+      res.status(400).json({ error: '"url" is required' });
+      return;
+    }
+    const parsed = validateGitHubUrl(url);
+    if (!parsed) {
+      res.status(400).json({ error: "Only public GitHub HTTPS URLs are supported (https://github.com/owner/repo)" });
+      return;
+    }
+    const id = randomUUID();
+    const cloneDir = join4(reposDir2, id);
+    try {
+      await cloneRepo(url, cloneDir, branch);
+      const detectedBranch = branch ?? await getDefaultBranch(cloneDir);
+      const currentCommit = await getHeadCommit(cloneDir);
+      const files = scanMarkdownFiles(cloneDir, id);
+      const meta = {
+        id,
+        name: `${parsed.owner}/${parsed.repo}`,
+        url,
+        branch: detectedBranch,
+        clonedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        lastSyncedAt: null,
+        currentCommit,
+        fileCount: files.length
+      };
+      saveRepo(reposDir2, meta);
+      res.status(201).json(meta);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+  router.post("/:repoId/sync", async (req, res) => {
+    const { repoId } = req.params;
+    const meta = getRepo(reposDir2, repoId);
+    if (!meta) {
+      res.status(404).json({ error: "Repository not found" });
+      return;
+    }
+    const cloneDir = join4(reposDir2, repoId);
+    try {
+      await pullRepo(cloneDir);
+      const currentCommit = await getHeadCommit(cloneDir);
+      const files = scanMarkdownFiles(cloneDir, repoId);
+      const updated = {
+        ...meta,
+        currentCommit,
+        fileCount: files.length,
+        lastSyncedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      saveRepo(reposDir2, updated);
+      res.json(updated);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+  router.delete("/:repoId", (req, res) => {
+    const { repoId } = req.params;
+    if (!getRepo(reposDir2, repoId)) {
+      res.status(404).json({ error: "Repository not found" });
+      return;
+    }
+    deleteRepo(reposDir2, repoId);
+    res.status(204).send();
+  });
+  return router;
+}
+
+// src/app.ts
+function createApp(config) {
+  const app = express();
+  app.use(createCorsMiddleware(config));
+  app.use(express.json());
+  app.use("/health", healthRouter());
+  app.use("/api/repos", reposRouter(config));
+  app.use((_req, res) => {
+    res.status(404).json({ error: "Not found" });
+  });
+  return app;
+}
+
+// src/index.ts
+async function startServer(overrides = {}) {
+  const config = parseConfig(overrides);
+  const app = createApp(config);
+  return new Promise((resolve_, reject) => {
+    const server = app.listen(config.port, config.host, () => resolve_(server));
+    server.on("error", reject);
+  });
+}
+var __filename2 = fileURLToPath(import.meta.url);
+var isMain = process.argv[1] !== void 0 && resolve3(process.argv[1]) === resolve3(__filename2);
+if (isMain) {
+  const config = parseConfig();
+  startServer(config).then(() => {
+    console.log(`mDocs server listening at http://${config.host}:${config.port}`);
+  }).catch((err) => {
+    console.error("Failed to start server:", err.message);
+    process.exit(1);
+  });
+}
+export {
+  DEFAULT_HOST,
+  DEFAULT_ORIGINS,
+  DEFAULT_PORT,
+  createApp,
+  parseConfig,
+  reposDir,
+  startServer
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@mdocs/server",
+  "version": "0.1.0",
+  "description": "mDocs local HTTP server",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "cors": "^2.8.5",
+    "express": "^4.19.2"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@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",
+    "typecheck": "tsc --noEmit"
+  }
+}