@takazudo/zudo-doc-history-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Takeshi Takatsudo
+
+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,70 @@
+# @takazudo/zudo-doc-history-server
+
+Standalone package for extracting and serving git history of documentation files. Has two modes: an HTTP server for local development and a CLI generator for CI builds.
+
+The history extraction logic was extracted from the Astro build pipeline so that expensive `git log --follow` calls do not block the main build, enabling a parallel CI strategy.
+
+## Modes
+
+### Server mode (local development)
+
+Runs an HTTP server that serves history on demand. Used by `pnpm dev` at the repository root, which starts both Astro and this server concurrently via `run-p`.
+
+```bash
+pnpm dev -- \
+  --content-dir src/content/docs \
+  --locale ja:src/content/docs-ja \
+  --port 4322
+```
+
+| Flag               | Required | Default | Description                                   |
+| ------------------ | -------- | ------- | --------------------------------------------- |
+| `--content-dir`    | Yes      | —       | Primary content directory to scan             |
+| `--locale <k>:<d>` | No       | —       | Extra locale directory (repeatable)           |
+| `--port`           | No       | `4322`  | HTTP port                                     |
+| `--max-entries`    | No       | `50`    | Max commits to include per file               |
+
+#### Endpoints
+
+- `GET /doc-history/{slug}.json` — Full history for a document
+- `GET /doc-history/{locale}/{slug}.json` — History for a localized document
+- `GET /health` — Health check
+
+The file index is refreshed every 10 seconds so newly added or renamed files are picked up without restarting the server. All responses include CORS headers for cross-origin dev access.
+
+### CLI mode (CI builds)
+
+Generates static `{slug}.json` files into an output directory. Used by the `build-history` CI job, which runs in parallel with the `build-site` Astro build.
+
+```bash
+pnpm generate -- \
+  --content-dir src/content/docs \
+  --locale ja:src/content/docs-ja \
+  --out-dir dist/doc-history
+```
+
+| Flag               | Required | Default | Description                               |
+| ------------------ | -------- | ------- | ----------------------------------------- |
+| `--content-dir`    | Yes      | —       | Primary content directory to scan         |
+| `--locale <k>:<d>` | No       | —       | Extra locale directory (repeatable)       |
+| `--out-dir`        | Yes      | —       | Output directory for the generated JSONs  |
+| `--max-entries`    | No       | `50`    | Max commits to include per file           |
+
+## Astro integration
+
+In dev mode, the Astro integration at `src/integrations/doc-history.ts` proxies `/doc-history/*` requests to this server. In build mode, the integration falls back to inline generation unless `SKIP_DOC_HISTORY=1` is set — which is the case in the CI `build-site` job so that the Astro build completes fast while the CLI `build-history` job generates the JSONs in parallel.
+
+## Build
+
+```bash
+pnpm build
+```
+
+Uses `tsup` to emit ESM output + DTS into `dist/`.
+
+## Design notes
+
+- **Synchronous git** — uses `execFileSync` for `git log` calls. The dev server is single-user and CI is inherently sequential, so async streaming is not needed.
+- **Repo-relative paths** — responses use relative file paths to avoid leaking absolute server paths.
+- **`--follow` for renames** — file history is tracked across renames with multiple fallback strategies.
+- **pnpm --filter CWD** — when run via `pnpm --filter`, the CWD is this package dir, so content paths passed from CI need `../../` prefix for repo-relative resolution.

package/dist/chunk-6M66L4CY.js

@@ -0,0 +1,176 @@
+// src/git-history.ts
+import { execFileSync } from "child_process";
+import { readdirSync } from "fs";
+import { join, relative } from "path";
+var QUIET = {
+  encoding: "utf-8",
+  stdio: ["pipe", "pipe", "pipe"]
+};
+var repoRootCache = null;
+function getRepoRoot() {
+  if (repoRootCache) return repoRootCache;
+  repoRootCache = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+    encoding: "utf-8"
+  }).trim();
+  return repoRootCache;
+}
+function toRepoRelative(absolutePath) {
+  return relative(getRepoRoot(), absolutePath);
+}
+function getFileCommits(filePath, maxEntries = 50) {
+  try {
+    const output = execFileSync(
+      "git",
+      [
+        "log",
+        "--follow",
+        "--format=%H",
+        "-n",
+        String(maxEntries),
+        "--",
+        filePath
+      ],
+      QUIET
+    ).trim();
+    return output ? [...new Set(output.split("\n"))] : [];
+  } catch {
+    return [];
+  }
+}
+function getFirstCommit(filePath) {
+  try {
+    const output = execFileSync(
+      "git",
+      [
+        "log",
+        "--follow",
+        "--reverse",
+        "--format=%H",
+        "--max-count=1",
+        "--",
+        filePath
+      ],
+      QUIET
+    ).trim();
+    if (!output) return null;
+    const first = output.split("\n")[0]?.trim();
+    return first ? first : null;
+  } catch {
+    return null;
+  }
+}
+function getCommitInfo(hash, filePath) {
+  try {
+    const output = execFileSync(
+      "git",
+      ["log", "-1", "--format=%H%n%aI%n%aN%n%s", hash, "--", filePath],
+      QUIET
+    ).trim();
+    const lines = output.split("\n");
+    return {
+      hash: lines[0] ?? hash,
+      date: lines[1] ?? "",
+      author: lines[2] ?? "",
+      message: lines[3] ?? ""
+    };
+  } catch {
+    return { hash, date: "", author: "", message: "" };
+  }
+}
+function getFileAtCommit(hash, filePath) {
+  const isAbsolute = filePath.startsWith("/");
+  const relPath = isAbsolute ? toRepoRelative(filePath) : filePath;
+  try {
+    return execFileSync("git", ["show", `${hash}:${relPath}`], QUIET);
+  } catch {
+    try {
+      const oldPath = execFileSync(
+        "git",
+        [
+          "log",
+          "-1",
+          "--follow",
+          "--diff-filter=R",
+          "--format=",
+          "--name-only",
+          hash,
+          "--",
+          relPath
+        ],
+        QUIET
+      ).trim();
+      if (oldPath) {
+        return execFileSync("git", ["show", `${hash}:${oldPath}`], QUIET);
+      }
+    } catch {
+    }
+    try {
+      const followOutput = execFileSync(
+        "git",
+        [
+          "log",
+          "--follow",
+          "--format=%H",
+          "--name-only",
+          "--diff-filter=AMRC",
+          "--",
+          relPath
+        ],
+        QUIET
+      ).trim();
+      const lines = followOutput.split("\n").filter(Boolean);
+      for (let i = 0; i < lines.length - 1; i += 2) {
+        if (lines[i] === hash && lines[i + 1]) {
+          return execFileSync(
+            "git",
+            ["show", `${hash}:${lines[i + 1]}`],
+            QUIET
+          );
+        }
+      }
+    } catch {
+    }
+    return "";
+  }
+}
+function getDocHistory(filePath, slug, maxEntries = 50) {
+  const commits = getFileCommits(filePath, maxEntries);
+  const entries = commits.map((hash) => {
+    const info = getCommitInfo(hash, filePath);
+    const content = getFileAtCommit(hash, filePath);
+    return { ...info, content };
+  });
+  const relPath = filePath.startsWith("/") ? toRepoRelative(filePath) : filePath;
+  return { slug, filePath: relPath, entries };
+}
+function collectContentFiles(dir) {
+  const results = [];
+  function walk(currentDir, baseDir) {
+    let entries;
+    try {
+      entries = readdirSync(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath, baseDir);
+      } else if (/\.mdx?$/.test(entry.name) && !entry.name.startsWith("_")) {
+        const rel = relative(baseDir, fullPath).replace(/\.mdx?$/, "").replace(/\/index$/, "");
+        results.push({ filePath: fullPath, slug: rel });
+      }
+    }
+  }
+  walk(dir, dir);
+  return results;
+}
+
+export {
+  getFileCommits,
+  getFirstCommit,
+  getCommitInfo,
+  getFileAtCommit,
+  getDocHistory,
+  collectContentFiles
+};

package/dist/chunk-F5LKLFOU.js

@@ -0,0 +1,125 @@
+// src/args.ts
+import { existsSync } from "fs";
+import { isAbsolute, resolve } from "path";
+function resolveContentPath(p) {
+  if (isAbsolute(p)) return p;
+  const initCwd = process.env["INIT_CWD"];
+  if (initCwd) {
+    const candidate = resolve(initCwd, p);
+    if (existsSync(candidate)) return candidate;
+    console.warn(
+      `doc-history-server: INIT_CWD candidate "${candidate}" does not exist; falling back to process.cwd()`
+    );
+  }
+  return resolve(p);
+}
+function requireNextArg(args, index, flag) {
+  if (index >= args.length) {
+    console.error(`Missing value for ${flag}`);
+    process.exit(1);
+  }
+  return args[index];
+}
+function parseLocaleArg(val) {
+  const colonIdx = val.indexOf(":");
+  if (colonIdx === -1) {
+    console.error(`Invalid --locale format: ${val} (expected key:dir)`);
+    process.exit(1);
+  }
+  return {
+    key: val.slice(0, colonIdx),
+    dir: resolveContentPath(val.slice(colonIdx + 1))
+  };
+}
+function parseCommonArgs(args, extra) {
+  let contentDir = "";
+  const locales = [];
+  let maxEntries = 50;
+  for (let i = 0; i < args.length; i++) {
+    const flag = args[i];
+    const next = () => requireNextArg(args, ++i, flag);
+    switch (flag) {
+      case "--content-dir":
+        contentDir = resolveContentPath(next());
+        break;
+      case "--locale":
+        locales.push(parseLocaleArg(next()));
+        break;
+      case "--max-entries": {
+        const n = Number(next());
+        if (Number.isNaN(n) || n < 1) {
+          console.error(`Invalid --max-entries value: ${args[i]}`);
+          process.exit(1);
+        }
+        maxEntries = n;
+        break;
+      }
+      default:
+        if (flag === "--") break;
+        if (!extra.onFlag(flag, next)) {
+          if (flag.startsWith("--")) {
+            console.error(`Unknown option: ${flag}`);
+            process.exit(1);
+          }
+        }
+    }
+  }
+  if (!contentDir) {
+    console.error("Missing required --content-dir option");
+    process.exit(1);
+  }
+  return { contentDir, locales, maxEntries };
+}
+function parseServerArgs(args) {
+  let port = 4322;
+  const common = parseCommonArgs(args, {
+    onFlag: (flag, next) => {
+      if (flag === "--port") {
+        const n = Number(next());
+        if (Number.isNaN(n) || n < 1) {
+          console.error(`Invalid --port value`);
+          process.exit(1);
+        }
+        port = n;
+        return true;
+      }
+      return false;
+    }
+  });
+  return { ...common, port };
+}
+function parseCliArgs(args) {
+  let outDir = "";
+  const common = parseCommonArgs(args, {
+    onFlag: (flag, next) => {
+      if (flag === "--out-dir") {
+        outDir = next();
+        return true;
+      }
+      return false;
+    }
+  });
+  if (!outDir) {
+    console.error("Missing required --out-dir option");
+    process.exit(1);
+  }
+  return { ...common, outDir };
+}
+
+// src/shared.ts
+import { resolve as resolve2 } from "path";
+function getContentDirEntries(contentDir, locales) {
+  const entries = [
+    [null, resolve2(contentDir)]
+  ];
+  for (const locale of locales) {
+    entries.push([locale.key, resolve2(locale.dir)]);
+  }
+  return entries;
+}
+
+export {
+  parseServerArgs,
+  parseCliArgs,
+  getContentDirEntries
+};

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import {
+  getContentDirEntries,
+  parseCliArgs
+} from "./chunk-F5LKLFOU.js";
+import {
+  collectContentFiles,
+  getDocHistory
+} from "./chunk-6M66L4CY.js";
+
+// src/cli.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+function generate(options2) {
+  const { contentDir, locales, outDir, maxEntries } = options2;
+  const startTime = performance.now();
+  const dirEntries = getContentDirEntries(contentDir, locales);
+  mkdirSync(outDir, { recursive: true });
+  let totalFiles = 0;
+  let errorCount = 0;
+  for (const [localeKey, dir] of dirEntries) {
+    const files = collectContentFiles(dir);
+    const label = localeKey ?? "default";
+    console.log(`Processing ${label}: ${files.length} files in ${dir}`);
+    for (const { filePath, slug } of files) {
+      try {
+        const history = getDocHistory(filePath, slug, maxEntries);
+        const prefixedSlug = localeKey ? `${localeKey}/${slug}` : slug;
+        const jsonPath = join(outDir, `${prefixedSlug}.json`);
+        mkdirSync(dirname(jsonPath), { recursive: true });
+        writeFileSync(jsonPath, JSON.stringify(history));
+        totalFiles++;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`  Skipped ${slug}: ${msg}`);
+        errorCount++;
+      }
+    }
+  }
+  const elapsed = ((performance.now() - startTime) / 1e3).toFixed(1);
+  console.log(
+    `
+Generated ${totalFiles} history files in ${elapsed}s${errorCount ? ` (${errorCount} errors)` : ""}`
+  );
+}
+var options = parseCliArgs(process.argv.slice(2));
+console.log(`doc-history-server: content-dir resolved to ${options.contentDir}`);
+for (const locale of options.locales) {
+  console.log(`doc-history-server: locale ${locale.key} resolved to ${locale.dir}`);
+}
+generate(options);

package/dist/git-history.d.ts

@@ -0,0 +1,45 @@
+import { DocHistoryEntry, DocHistoryData } from './types.js';
+
+/**
+ * Get the list of commit hashes that touched a file, newest first.
+ * Uses --follow to track renames.
+ * Limits to maxEntries commits (default 50).
+ */
+declare function getFileCommits(filePath: string, maxEntries?: number): string[];
+/**
+ * Get the oldest commit hash that touched a file (the file's "first" commit).
+ *
+ * Uses --follow + --reverse + --max-count=1. Note that git still has to walk
+ * the file's full history once before applying --reverse, so this is O(history)
+ * for that file path, not O(1). Acceptable here because the caller is a
+ * build-time helper run once per content file, not a hot path.
+ *
+ * Returns null when the file has no git history (untracked / not yet committed).
+ */
+declare function getFirstCommit(filePath: string): string | null;
+/**
+ * Get metadata for a specific commit on a file.
+ * Returns { hash, date, author, message } with full hash for unique identification.
+ */
+declare function getCommitInfo(hash: string, filePath: string): Omit<DocHistoryEntry, "content">;
+/**
+ * Get the file content at a specific commit.
+ * Accepts absolute paths and converts to repo-relative for git show.
+ * Handles renamed files by falling back to the old path via git log --follow.
+ */
+declare function getFileAtCommit(hash: string, filePath: string): string;
+/**
+ * Get the complete history for a document file.
+ * Returns DocHistoryData with all entries populated.
+ */
+declare function getDocHistory(filePath: string, slug: string, maxEntries?: number): DocHistoryData;
+/**
+ * Collect all MDX/md files in a content directory.
+ * Returns array of { filePath, slug } pairs.
+ */
+declare function collectContentFiles(dir: string): Array<{
+    filePath: string;
+    slug: string;
+}>;
+
+export { collectContentFiles, getCommitInfo, getDocHistory, getFileAtCommit, getFileCommits, getFirstCommit };

package/dist/git-history.js

@@ -0,0 +1,16 @@
+import {
+  collectContentFiles,
+  getCommitInfo,
+  getDocHistory,
+  getFileAtCommit,
+  getFileCommits,
+  getFirstCommit
+} from "./chunk-6M66L4CY.js";
+export {
+  collectContentFiles,
+  getCommitInfo,
+  getDocHistory,
+  getFileAtCommit,
+  getFileCommits,
+  getFirstCommit
+};

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import {
+  getContentDirEntries,
+  parseServerArgs
+} from "./chunk-F5LKLFOU.js";
+import {
+  collectContentFiles,
+  getDocHistory
+} from "./chunk-6M66L4CY.js";
+
+// src/server.ts
+import { createServer } from "http";
+import { resolve } from "path";
+var FILE_INDEX_REFRESH_MS = 1e4;
+function setCorsHeaders(res) {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+}
+function sendJson(res, status, data) {
+  setCorsHeaders(res);
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(data));
+}
+function buildFileIndex(dirEntries) {
+  const index = /* @__PURE__ */ new Map();
+  for (const [localeKey, contentDir] of dirEntries) {
+    const files = collectContentFiles(contentDir);
+    for (const file of files) {
+      const prefixedSlug = localeKey ? `${localeKey}/${file.slug}` : file.slug;
+      index.set(prefixedSlug, file);
+    }
+  }
+  return index;
+}
+function handleDocHistory(requestedSlug, fileIndex, maxEntries, res) {
+  const found = fileIndex.get(requestedSlug);
+  if (found) {
+    const history = getDocHistory(found.filePath, found.slug, maxEntries);
+    sendJson(res, 200, history);
+    return;
+  }
+  sendJson(res, 404, { error: `No doc found for slug: ${requestedSlug}` });
+}
+function startServer(options2) {
+  const { port, contentDir, locales, maxEntries } = options2;
+  const dirEntries = getContentDirEntries(contentDir, locales);
+  let fileIndex = buildFileIndex(dirEntries);
+  console.log(`Indexed ${fileIndex.size} documents`);
+  setInterval(() => {
+    try {
+      fileIndex = buildFileIndex(dirEntries);
+    } catch {
+    }
+  }, FILE_INDEX_REFRESH_MS);
+  const server = createServer((req, res) => {
+    const url = req.url ?? "";
+    if (req.method === "OPTIONS") {
+      setCorsHeaders(res);
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+    if (url === "/health") {
+      sendJson(res, 200, { status: "ok" });
+      return;
+    }
+    const match = url.match(/^\/doc-history\/(.+)\.json$/);
+    if (match) {
+      try {
+        const requestedSlug = decodeURIComponent(match[1]);
+        handleDocHistory(requestedSlug, fileIndex, maxEntries, res);
+      } catch (err) {
+        sendJson(res, 500, {
+          error: err instanceof Error ? err.message : "Internal error"
+        });
+      }
+      return;
+    }
+    sendJson(res, 404, { error: "Not found" });
+  });
+  server.listen(port, () => {
+    console.log(`Doc history server listening on http://localhost:${port}`);
+    console.log(`Content dir: ${resolve(contentDir)}`);
+    for (const locale of locales) {
+      console.log(`Locale ${locale.key}: ${resolve(locale.dir)}`);
+    }
+  });
+}
+
+// src/index.ts
+var options = parseServerArgs(process.argv.slice(2));
+console.log(`doc-history-server: content-dir resolved to ${options.contentDir}`);
+for (const locale of options.locales) {
+  console.log(`doc-history-server: locale ${locale.key} resolved to ${locale.dir}`);
+}
+startServer(options);

package/dist/types.d.ts

@@ -0,0 +1,24 @@
+/** A single git revision entry for a document */
+interface DocHistoryEntry {
+    /** Full commit hash (use .slice(0, 7) for display) */
+    hash: string;
+    /** ISO 8601 date string */
+    date: string;
+    /** Commit author name */
+    author: string;
+    /** First line of commit message */
+    message: string;
+    /** Full file content at this revision */
+    content: string;
+}
+/** Complete history data for a single document */
+interface DocHistoryData {
+    /** Document slug (route path) */
+    slug: string;
+    /** Relative file path in the repository */
+    filePath: string;
+    /** Git revision entries, newest first */
+    entries: DocHistoryEntry[];
+}
+
+export type { DocHistoryData, DocHistoryEntry };

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@takazudo/zudo-doc-history-server",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Standalone doc git-history service for zudo-doc — HTTP server + CLI batch generator. Decouples expensive `git log --follow` calls from the main build pipeline.",
+  "license": "MIT",
+  "author": "Takeshi Takatsudo",
+  "homepage": "https://zudo-doc.takazudomodular.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zudolab/zudo-doc.git",
+    "directory": "packages/doc-history-server"
+  },
+  "bugs": {
+    "url": "https://github.com/zudolab/zudo-doc/issues"
+  },
+  "keywords": [
+    "zudo-doc",
+    "documentation",
+    "git-history",
+    "mdx"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "doc-history-server": "./dist/index.js",
+    "doc-history-generate": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./git-history": {
+      "types": "./dist/git-history.d.ts",
+      "default": "./dist/git-history.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.1.1"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts src/git-history.ts src/types.ts --format esm --dts",
+    "dev": "tsx src/index.ts",
+    "generate": "tsx src/cli.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}