@mandujs/core 0.25.2 → 0.26.0

package/src/content/llms-txt.ts

@@ -72,8 +72,19 @@ export interface GenerateLLMSTxtOptions {
    * an absolute origin (e.g. `https://example.com`) to produce an
    * outward-facing llms.txt that third-party crawlers can consume
    * without resolving against the host.
+   *
+   * Alias for `baseUrl` — accepts either name so the API reads
+   * naturally whether the caller thinks in "site base path" or
+   * "absolute URL".
    */
   basePath?: string;
+  /**
+   * Alias for `basePath`. When both are provided, `baseUrl` wins
+   * (callers explicitly typing an absolute URL typically mean
+   * "use this verbatim"). Useful in docs-site configs that already
+   * expose `baseUrl` for their router / canonical URL helpers.
+   */
+  baseUrl?: string;
   /**
    * When true, include each entry's body verbatim under its heading.
    * This produces the `llms-full.txt` variant — significantly larger
@@ -92,6 +103,18 @@ export interface GenerateLLMSTxtOptions {
    * omits the trailing `: {summary}` tail.
    */
   getSummary?: (entry: CollectionEntry<unknown>) => string;
+  /**
+   * When true, emit a nested heading structure that groups entries
+   * by their first slug segment (the "category"). With `full: true`
+   * this produces an `llms-full.txt` that mirrors the docs sidebar
+   * layout — useful for LLM crawlers that consume the
+   * category-section convention.
+   *
+   * The category headings use `###` so they nest cleanly under the
+   * `##` collection heading. Entries without a slash in their slug
+   * are placed under an implicit "root" section.
+   */
+  groupByCategory?: boolean;
 }
 
 /**
@@ -108,11 +131,13 @@ export async function generateLLMSTxt(
   const {
     siteName,
     description,
-    basePath = "/",
     full = false,
     includeDrafts = false,
     getSummary,
+    groupByCategory = false,
   } = options;
+  // `baseUrl` wins when both are provided — see the option JSDoc.
+  const basePath = options.baseUrl ?? options.basePath ?? "/";
 
   const lines: string[] = [];
   if (siteName) {
@@ -140,23 +165,54 @@ export async function generateLLMSTxt(
 
     lines.push(`## ${input.name}`);
     lines.push("");
-    for (const entry of sorted) {
-      const title =
-        typeof (entry.data as { title?: unknown })?.title === "string"
-          ? String((entry.data as { title: string }).title)
-          : entry.slug || "index";
-      const href = joinHref(basePath, input.name, entry.slug);
-      const summary = getSummary
-        ? getSummary(entry)
-        : typeof (entry.data as { description?: unknown })?.description === "string"
-          ? String((entry.data as { description: string }).description)
-          : "";
-      const tail = summary ? `: ${summary}` : "";
-      lines.push(`- [${title}](${href})${tail}`);
-      if (full) {
-        lines.push("");
-        lines.push(entry.content);
+
+    if (groupByCategory) {
+      // Bucket entries by their first slug segment. Entries without
+      // a slash go under the "__root__" sentinel so we can render
+      // them above the categorized groups.
+      const groups = new Map<string, typeof sorted>();
+      for (const entry of sorted) {
+        const [head, ...rest] = entry.slug.split("/");
+        const key = rest.length > 0 ? head : "__root__";
+        const bucket = groups.get(key);
+        if (bucket) bucket.push(entry);
+        else groups.set(key, [entry]);
+      }
+      // Emit root-level entries first (if any), then categorized
+      // groups in alphabetical category order for determinism.
+      const rootEntries = groups.get("__root__") ?? [];
+      for (const entry of rootEntries) {
+        lines.push(renderEntryLine(entry, input.name, basePath, getSummary));
+        if (full) {
+          lines.push("");
+          lines.push(entry.content);
+          lines.push("");
+        }
+      }
+      const categoryKeys = Array.from(groups.keys())
+        .filter((k) => k !== "__root__")
+        .sort();
+      for (const catKey of categoryKeys) {
+        if (rootEntries.length > 0) lines.push("");
+        lines.push(`### ${catKey}`);
         lines.push("");
+        for (const entry of groups.get(catKey) ?? []) {
+          lines.push(renderEntryLine(entry, input.name, basePath, getSummary));
+          if (full) {
+            lines.push("");
+            lines.push(entry.content);
+            lines.push("");
+          }
+        }
+      }
+    } else {
+      for (const entry of sorted) {
+        lines.push(renderEntryLine(entry, input.name, basePath, getSummary));
+        if (full) {
+          lines.push("");
+          lines.push(entry.content);
+          lines.push("");
+        }
       }
     }
     lines.push("");
@@ -177,6 +233,31 @@ async function loadInput(input: LLMSTxtInput): Promise<CollectionEntry<unknown>[
   return entries as CollectionEntry<unknown>[];
 }
 
+/**
+ * Format a single entry as a `- [Title](href): summary` line. Split
+ * out from the main loop so both the flat and the categorized
+ * rendering paths share the same output shape.
+ */
+function renderEntryLine(
+  entry: CollectionEntry<unknown>,
+  collectionName: string,
+  basePath: string,
+  getSummary: ((entry: CollectionEntry<unknown>) => string) | undefined
+): string {
+  const title =
+    typeof (entry.data as { title?: unknown })?.title === "string"
+      ? String((entry.data as { title: string }).title)
+      : entry.slug || "index";
+  const href = joinHref(basePath, collectionName, entry.slug);
+  const summary = getSummary
+    ? getSummary(entry)
+    : typeof (entry.data as { description?: unknown })?.description === "string"
+      ? String((entry.data as { description: string }).description)
+      : "";
+  const tail = summary ? `: ${summary}` : "";
+  return `- [${title}](${href})${tail}`;
+}
+
 function joinHref(base: string, collectionName: string, slug: string): string {
   const parts = [collectionName, slug].filter((x) => x !== "" && x !== "/");
   const tail = parts.join("/").replace(/\/+/g, "/");

package/src/content/prebuild.test.ts

@@ -24,6 +24,11 @@ import {
   shouldAutoPrebuild,
   runPrebuildScripts,
   PrebuildError,
+  PrebuildTimeoutError,
+  resolvePrebuildTimeout,
+  DEFAULT_PREBUILD_TIMEOUT_MS,
+  PREBUILD_TIMEOUT_ENV,
+  defaultSpawn,
   type SpawnHook,
 } from "./prebuild";
 
@@ -247,3 +252,320 @@ describe("runPrebuildScripts", () => {
     expect(spawn.calls[0].timeoutMs).toBe(2 * 60 * 1000);
   });
 });
+
+// ---------------------------------------------------------------------------
+// resolvePrebuildTimeout (Issue #203)
+// ---------------------------------------------------------------------------
+
+describe("resolvePrebuildTimeout", () => {
+  const originalEnv = process.env[PREBUILD_TIMEOUT_ENV];
+  afterEach(() => {
+    if (originalEnv === undefined) delete process.env[PREBUILD_TIMEOUT_ENV];
+    else process.env[PREBUILD_TIMEOUT_ENV] = originalEnv;
+  });
+
+  it("returns DEFAULT_PREBUILD_TIMEOUT_MS (120s) when no override", () => {
+    delete process.env[PREBUILD_TIMEOUT_ENV];
+    expect(resolvePrebuildTimeout()).toBe(DEFAULT_PREBUILD_TIMEOUT_MS);
+    expect(DEFAULT_PREBUILD_TIMEOUT_MS).toBe(120_000);
+  });
+
+  it("explicit arg wins over env var", () => {
+    process.env[PREBUILD_TIMEOUT_ENV] = "5000";
+    expect(resolvePrebuildTimeout(1234)).toBe(1234);
+  });
+
+  it("env var is used when no explicit arg", () => {
+    process.env[PREBUILD_TIMEOUT_ENV] = "7500";
+    expect(resolvePrebuildTimeout()).toBe(7500);
+  });
+
+  it("ignores invalid env var (non-numeric) and falls back to default", () => {
+    process.env[PREBUILD_TIMEOUT_ENV] = "not-a-number";
+    expect(resolvePrebuildTimeout()).toBe(DEFAULT_PREBUILD_TIMEOUT_MS);
+  });
+
+  it("ignores invalid env var (zero / negative) and falls back to default", () => {
+    process.env[PREBUILD_TIMEOUT_ENV] = "0";
+    expect(resolvePrebuildTimeout()).toBe(DEFAULT_PREBUILD_TIMEOUT_MS);
+    process.env[PREBUILD_TIMEOUT_ENV] = "-5";
+    expect(resolvePrebuildTimeout()).toBe(DEFAULT_PREBUILD_TIMEOUT_MS);
+  });
+
+  it("ignores non-positive explicit arg", () => {
+    delete process.env[PREBUILD_TIMEOUT_ENV];
+    expect(resolvePrebuildTimeout(0)).toBe(DEFAULT_PREBUILD_TIMEOUT_MS);
+    expect(resolvePrebuildTimeout(-1)).toBe(DEFAULT_PREBUILD_TIMEOUT_MS);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Issue #203 — Timeout + error surface regressions
+// ---------------------------------------------------------------------------
+
+describe("runPrebuildScripts — timeout surface (Issue #203)", () => {
+  let dir = "";
+  beforeEach(() => { dir = mktmp("timeout-"); });
+  afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }); });
+
+  it("honours MANDU_PREBUILD_TIMEOUT_MS env override when timeoutMs omitted", async () => {
+    const originalEnv = process.env[PREBUILD_TIMEOUT_ENV];
+    process.env[PREBUILD_TIMEOUT_ENV] = "9999";
+    try {
+      writeFile(dir, "scripts/prebuild-1.ts");
+      const spawn = makeMockSpawn(() => ({ exitCode: 0, durationMs: 1 }));
+      await runPrebuildScripts({ rootDir: dir, spawn });
+      expect(spawn.calls[0].timeoutMs).toBe(9999);
+    } finally {
+      if (originalEnv === undefined) delete process.env[PREBUILD_TIMEOUT_ENV];
+      else process.env[PREBUILD_TIMEOUT_ENV] = originalEnv;
+    }
+  });
+
+  it("explicit timeoutMs wins over env var", async () => {
+    const originalEnv = process.env[PREBUILD_TIMEOUT_ENV];
+    process.env[PREBUILD_TIMEOUT_ENV] = "9999";
+    try {
+      writeFile(dir, "scripts/prebuild-1.ts");
+      const spawn = makeMockSpawn(() => ({ exitCode: 0, durationMs: 1 }));
+      await runPrebuildScripts({ rootDir: dir, spawn, timeoutMs: 2222 });
+      expect(spawn.calls[0].timeoutMs).toBe(2222);
+    } finally {
+      if (originalEnv === undefined) delete process.env[PREBUILD_TIMEOUT_ENV];
+      else process.env[PREBUILD_TIMEOUT_ENV] = originalEnv;
+    }
+  });
+
+  it("defaultSpawn throws PrebuildTimeoutError with script name + limit when the script runs longer than timeout", async () => {
+    // Script sleeps 300ms — we set timeout 80ms, so the timer must win.
+    // We use `Bun.sleep` + `process.exit(0)` so the script exits cleanly
+    // if somehow the kill is skipped (no zombie in test harness).
+    const scriptAbs = writeFile(
+      dir,
+      "scripts/prebuild-slow.ts",
+      "await Bun.sleep(300);\nprocess.exit(0);\n",
+    );
+
+    let caught: unknown;
+    try {
+      await defaultSpawn({ scriptPath: scriptAbs, cwd: dir, timeoutMs: 80 });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(PrebuildTimeoutError);
+    expect(caught).toBeInstanceOf(PrebuildError); // subclass relationship
+    const err = caught as PrebuildTimeoutError;
+    expect(err.timeoutMs).toBe(80);
+    expect(err.scriptPath).toContain("prebuild-slow.ts");
+    // Message contract: includes script name + timeout limit + override hint.
+    expect(err.message).toContain("prebuild-slow.ts");
+    expect(err.message).toContain("80ms");
+    expect(err.message).toContain("dev.prebuildTimeoutMs");
+    expect(err.message).toContain(PREBUILD_TIMEOUT_ENV);
+    // Regression beacon: message MUST NOT contain the opaque
+    // "non-Error thrown" string Issue #203 was reported against.
+    expect(err.message).not.toContain("non-Error thrown");
+  });
+
+  it("runPrebuildScripts surfaces PrebuildTimeoutError via injected spawn", async () => {
+    writeFile(dir, "scripts/prebuild-slow.ts");
+    const spawn: SpawnHook = async (args) => {
+      throw new PrebuildTimeoutError({
+        scriptPath: args.scriptPath,
+        timeoutMs: args.timeoutMs,
+        durationMs: args.timeoutMs,
+      });
+    };
+    let caught: unknown;
+    try {
+      await runPrebuildScripts({ rootDir: dir, spawn, timeoutMs: 100 });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(PrebuildTimeoutError);
+    const err = caught as PrebuildTimeoutError;
+    expect(err.timeoutMs).toBe(100);
+    expect(err.scriptPath).toContain("prebuild-slow.ts");
+  });
+});
+
+describe("runPrebuildScripts — error preservation (Issue #203)", () => {
+  let dir = "";
+  beforeEach(() => { dir = mktmp("err-surface-"); });
+  afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }); });
+
+  it("preserves the inner Error message ('boom') when a spawn rejection occurs", async () => {
+    writeFile(dir, "scripts/prebuild.ts");
+    const inner = new Error("boom");
+    const spawn: SpawnHook = async () => {
+      throw inner;
+    };
+    let caught: unknown;
+    try {
+      await runPrebuildScripts({ rootDir: dir, spawn });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(PrebuildError);
+    const err = caught as PrebuildError & { cause?: unknown };
+    // The inner message MUST appear verbatim — the whole point of #203.
+    expect(err.message).toContain("boom");
+    // Regression beacon.
+    expect(err.message).not.toContain("non-Error thrown");
+    // The inner error is attached as `.cause` so debug tooling can
+    // recover its stack.
+    expect(err.cause).toBe(inner);
+  });
+
+  it("preserves stack via .cause when inner Error has a stack", async () => {
+    writeFile(dir, "scripts/prebuild.ts");
+    const inner = new Error("kaboom");
+    const originalStack = inner.stack;
+    expect(originalStack).toBeTruthy();
+    const spawn: SpawnHook = async () => {
+      throw inner;
+    };
+    let caught: unknown;
+    try {
+      await runPrebuildScripts({ rootDir: dir, spawn });
+    } catch (e) {
+      caught = e;
+    }
+    const err = caught as PrebuildError & { cause?: Error };
+    expect(err.cause).toBe(inner);
+    expect(err.cause?.stack).toBe(originalStack);
+  });
+
+  it("handles non-Error rejections (string) without producing 'non-Error thrown'", async () => {
+    writeFile(dir, "scripts/prebuild.ts");
+    const spawn: SpawnHook = async () => {
+      // Raw string throw — the pathological case Issue #203 was about.
+      throw "spawn blew up";
+    };
+    let caught: unknown;
+    try {
+      await runPrebuildScripts({ rootDir: dir, spawn });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(PrebuildError);
+    const err = caught as PrebuildError & { cause?: unknown };
+    // The raw string survives into `.message`.
+    expect(err.message).toContain("spawn blew up");
+    expect(err.message).not.toContain("non-Error thrown");
+    expect(err.cause).toBe("spawn blew up");
+  });
+
+  it("handles non-Error rejections (object) without producing 'non-Error thrown'", async () => {
+    writeFile(dir, "scripts/prebuild.ts");
+    const raw = { code: "EBADF", info: "fd closed" };
+    const spawn: SpawnHook = async () => {
+      throw raw;
+    };
+    let caught: unknown;
+    try {
+      await runPrebuildScripts({ rootDir: dir, spawn });
+    } catch (e) {
+      caught = e;
+    }
+    const err = caught as PrebuildError & { cause?: unknown };
+    expect(err.message).toContain("EBADF");
+    expect(err.message).not.toContain("non-Error thrown");
+    expect(err.cause).toBe(raw);
+  });
+
+  it("includes stdout/stderr tails in PrebuildError.message for non-zero exit", async () => {
+    writeFile(dir, "scripts/prebuild.ts");
+    const stderrSample = Array.from({ length: 15 }, (_, i) => `err-line-${i + 1}`).join("\n");
+    const stdoutSample = Array.from({ length: 12 }, (_, i) => `out-line-${i + 1}`).join("\n");
+    const spawn: SpawnHook = async () => ({
+      exitCode: 1,
+      durationMs: 5,
+      stdoutTail: stdoutSample,
+      stderrTail: stderrSample,
+    });
+    let caught: unknown;
+    try {
+      await runPrebuildScripts({ rootDir: dir, spawn });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(PrebuildError);
+    const err = caught as PrebuildError;
+    // Exactly last 10 stderr lines are kept.
+    expect(err.message).toContain("err-line-15");
+    expect(err.message).toContain("err-line-6"); // the 10-from-last
+    expect(err.message).not.toContain("err-line-5"); // trimmed
+    // Stdout tail is also present (10 lines out of 12).
+    expect(err.message).toContain("out-line-12");
+    expect(err.message).toContain("out-line-3");
+    expect(err.message).not.toContain("out-line-2");
+    // Structured fields carry the full captured tails.
+    expect(err.stderrTail).toBe(stderrSample);
+    expect(err.stdoutTail).toBe(stdoutSample);
+  });
+
+  it("omits empty tail sections when the spawn hook didn't capture", async () => {
+    writeFile(dir, "scripts/prebuild.ts");
+    const spawn: SpawnHook = async () => ({ exitCode: 2, durationMs: 3 });
+    let caught: unknown;
+    try {
+      await runPrebuildScripts({ rootDir: dir, spawn });
+    } catch (e) {
+      caught = e;
+    }
+    const err = caught as PrebuildError;
+    // The "exited with code 2" prefix is present but no "--- stderr ---" sections.
+    expect(err.message).toContain("exited with code 2");
+    expect(err.message).not.toContain("--- stderr");
+    expect(err.message).not.toContain("--- stdout");
+  });
+
+  it("normalizes Windows-style CRLF line endings in stderr tail", async () => {
+    writeFile(dir, "scripts/prebuild.ts");
+    const crlf = ["a", "b", "c", "d"].join("\r\n");
+    const spawn: SpawnHook = async () => ({
+      exitCode: 1,
+      durationMs: 1,
+      stderrTail: crlf,
+    });
+    let caught: unknown;
+    try {
+      await runPrebuildScripts({ rootDir: dir, spawn });
+    } catch (e) {
+      caught = e;
+    }
+    const err = caught as PrebuildError;
+    // All 4 lines survive (under the 10-line cap).
+    expect(err.message).toContain("a\nb\nc\nd");
+    // No raw \r\n survived.
+    expect(err.message).not.toContain("\r\n");
+  });
+});
+
+describe("PrebuildTimeoutError shape (Issue #203)", () => {
+  it("is a subclass of PrebuildError so existing `instanceof PrebuildError` callers still match", () => {
+    const err = new PrebuildTimeoutError({
+      scriptPath: "/tmp/foo/scripts/prebuild.ts",
+      timeoutMs: 500,
+      durationMs: 500,
+    });
+    expect(err).toBeInstanceOf(PrebuildTimeoutError);
+    expect(err).toBeInstanceOf(PrebuildError);
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe("PrebuildTimeoutError");
+    expect(err.exitCode).toBeNull();
+  });
+
+  it("message names the script + limit + override paths", () => {
+    const err = new PrebuildTimeoutError({
+      scriptPath: "/repo/scripts/prebuild-seed.ts",
+      timeoutMs: 250,
+      durationMs: 250,
+    });
+    expect(err.message).toContain("prebuild-seed.ts");
+    expect(err.message).toContain("250ms");
+    expect(err.message).toContain("dev.prebuildTimeoutMs");
+    expect(err.message).toContain(PREBUILD_TIMEOUT_ENV);
+  });
+});