@intentius/chant 0.124.27 → 0.124.29

package/src/cli/run-events.ts

@@ -0,0 +1,57 @@
+/**
+ * `--events-json` (#4041): a command's run-event stream on stdout, one
+ * `run-event.schema.json` line per event, also kept on this host for replay
+ * (#4042, `../run-event-store.ts`). Shared by `chant run`, the
+ * components commands that deploy (promote, rollback, redeploy, fan-out) and
+ * the pull-request loop (pr-plan, pr-apply).
+ */
+
+import { formatError } from "./format";
+import { openRunEventStore, teeLines } from "../run-event-store";
+import { openRunEventStream, resolveRunEventRun, type RunEventStream } from "../run-event-stream";
+import type { RunEventKind } from "../run-event";
+import type { ParsedArgs } from "./registry";
+
+/** Refuse `--events-json` beside `--progress-json`: both print to stdout. Returns true after printing why. */
+export function refusesBothStreams(args: Pick<ParsedArgs, "eventsJson" | "progressJson">): boolean {
+  if (!args.eventsJson || !args.progressJson) return false;
+  console.error(formatError({
+    message: "--events-json and --progress-json both stream to stdout",
+    hint: "Pass one. --events-json prints the run-event stream; --progress-json prints the older progress lines.",
+  }));
+  return true;
+}
+
+/** Refuse `--events-json` beside `--json` where `--json` prints a report to stdout (pr-plan, pr-apply). Returns true after printing why. */
+export function refusesEventsWithJson(args: Pick<ParsedArgs, "eventsJson" | "json">, report: string): boolean {
+  if (!args.eventsJson || !args.json) return false;
+  console.error(formatError({
+    message: "--events-json and --json both stream to stdout",
+    hint: `Pass one. --events-json prints the run-event stream; --json prints ${report}.`,
+  }));
+  return true;
+}
+
+/** Writes one line to stdout. */
+export const stdoutLine = (line: string): void => void process.stdout.write(line);
+
+/**
+ * The run's stream on stdout when `--events-json` was passed, else
+ * undefined. Each line goes to stdout, to this host's store and to `also`
+ * when given. The run is named by `runId` when the caller has one (so a
+ * release record and the stream name the same run), else by the CI run or a
+ * local id.
+ */
+export async function openCliRunEvents(
+  args: Pick<ParsedArgs, "eventsJson">,
+  run: { kind: RunEventKind; name: string; runId?: string; cwd?: string },
+  also?: (line: string) => void,
+): Promise<RunEventStream | undefined> {
+  if (!args.eventsJson) return undefined;
+  const resolved = await resolveRunEventRun(run);
+  // #4042: the stream is also kept on this host, so `chant run events <run>`
+  // replays it. Only a command that was asked for a stream keeps one.
+  const store = await openRunEventStore(run.cwd ?? process.cwd(), resolved.runId);
+  // `also`: a third copy of each line, such as `--report-url`'s upload (#4007).
+  return openRunEventStream(resolved, teeLines(stdoutLine, store?.write.bind(store), also)!);
+}

package/src/cli/version.ts

@@ -1,15 +1,5 @@
-import { createRequire } from "node:module";
-
 /**
- * The installed chant's version, read from `@intentius/chant`'s own
- * package.json, or "0.0.0" when it can't be read. The path is the same from
- * `src/cli/` and `dist/cli/`, so it holds whether chant runs from source or
- * from its build.
+ * The installed chant's version. It lives in `../chant-version.ts`, outside
+ * `cli/`, so the Op entry can name it without loading the CLI (#4041).
  */
-export const CHANT_VERSION: string = (() => {
-  try {
-    return (createRequire(import.meta.url)("../../package.json") as { version?: string }).version ?? "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-})();
+export { CHANT_VERSION } from "../chant-version";

package/src/codegen/docs-in-site.test.ts

@@ -0,0 +1,166 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+
+import { docsPipeline, writeDocsSite } from "./docs";
+import { DOCS_SITE_DEPENDENCIES, findChantDocsSite, rebaseImports, resolveDocsMode } from "./docs-in-site";
+import type { DocsConfig } from "./docs-types";
+
+/**
+ * chant #3993: inside the chant repository a lexicon's docs are a section of
+ * the main Starlight site. These run against a fake repository (a `docs/`
+ * whose package.json is the chant docs package) with one lexicon under it.
+ */
+
+let repo: string;
+let lex: string;
+
+function config(overrides: Partial<DocsConfig> = {}): DocsConfig {
+  return {
+    name: "fixture",
+    displayName: "Fixture",
+    description: "fixture lexicon",
+    distDir: join(lex, "dist"),
+    outDir: join(lex, "docs"),
+    srcDir: join(lex, "src"),
+    basePath: "/chant/lexicons/fixture/",
+    ...overrides,
+  };
+}
+
+function page(name: string, frontmatter: string, body = "Body.\n"): void {
+  mkdirSync(join(lex, "docs", "pages"), { recursive: true });
+  writeFileSync(join(lex, "docs", "pages", name), `---\n${frontmatter}\n---\n\n${body}`);
+}
+
+const section = () => join(repo, "docs", "src", "content", "docs", "lexicons", "fixture");
+
+beforeEach(() => {
+  vi.stubEnv("CHANT_DOCS_MODE", "");
+  vi.stubEnv("CHANT_DOCS_SITE", "");
+  repo = mkdtempSync(join(tmpdir(), "chant-docs-in-site-"));
+  mkdirSync(join(repo, "docs"), { recursive: true });
+  writeFileSync(join(repo, "docs", "package.json"), JSON.stringify({ name: "@intentius/chant-docs" }));
+  writeFileSync(join(repo, "docs", "astro.config.mjs"), "export default {};\n");
+  lex = join(repo, "lexicons", "fixture");
+  mkdirSync(join(lex, "dist"), { recursive: true });
+  mkdirSync(join(lex, "src"), { recursive: true });
+  writeFileSync(
+    join(lex, "dist", "manifest.json"),
+    JSON.stringify({ name: "fixture", version: "0.0.0", intrinsics: [{ name: "ref", description: "a ref" }] }),
+  );
+  writeFileSync(join(lex, "dist", "meta.json"), JSON.stringify({}));
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  rmSync(repo, { recursive: true, force: true });
+});
+
+describe("which mode writeDocsSite runs in", () => {
+  test("a lexicon inside the chant repository goes in-site", () => {
+    expect(findChantDocsSite(lex)).toBe(join(repo, "docs"));
+    expect(resolveDocsMode(config())).toEqual({ mode: "in-site", siteDir: join(repo, "docs") });
+  });
+
+  test("a docs site that is not chant's does not count", () => {
+    writeFileSync(join(repo, "docs", "package.json"), JSON.stringify({ name: "someone-elses-docs" }));
+    expect(findChantDocsSite(lex)).toBeUndefined();
+    expect(resolveDocsMode(config()).mode).toBe("standalone");
+  });
+
+  test("config.mode and CHANT_DOCS_MODE override the detection", () => {
+    expect(resolveDocsMode(config({ mode: "standalone" })).mode).toBe("standalone");
+    vi.stubEnv("CHANT_DOCS_MODE", "standalone");
+    expect(resolveDocsMode(config()).mode).toBe("standalone");
+  });
+
+  test("in-site mode with no main site to write into is an error", () => {
+    rmSync(join(repo, "docs"), { recursive: true });
+    expect(() => resolveDocsMode(config({ mode: "in-site" }))).toThrow(/in-site mode needs the chant docs site/);
+  });
+});
+
+describe("in-site mode", () => {
+  test("writes pages and a sidebar fragment into the main site, and no app files", () => {
+    page("start.mdx", "title: Start\ndiataxis: tutorial");
+    page("secret.mdx", "title: Secret\ndiataxis: reference\nhidden: true");
+    const cfg = config();
+    writeDocsSite(cfg, docsPipeline(cfg));
+
+    for (const f of ["index.mdx", "start.mdx", "secret.mdx", "intrinsics.mdx", "serialization.mdx"]) {
+      expect(existsSync(join(section(), f)), f).toBe(true);
+    }
+    for (const f of ["package.json", "astro.config.mjs", "tsconfig.json", "src"]) {
+      expect(existsSync(join(lex, "docs", f)), f).toBe(false);
+    }
+
+    const fragment = JSON.parse(readFileSync(join(section(), "_sidebar.json"), "utf-8"));
+    expect(fragment.hidden).toEqual(["lexicons/fixture/secret"]);
+    expect(fragment.group.label).toBe("Fixture");
+    expect(fragment.group.collapsed).toBe(true);
+    expect(fragment.group.items.map((i: { label: string }) => i.label)).toEqual(["Overview", "Tutorials", "Reference"]);
+    expect(fragment.group.items[0]).toEqual({ label: "Overview", slug: "lexicons/fixture" });
+    expect(fragment.group.items[1]).toEqual({
+      label: "Tutorials",
+      collapsed: true,
+      items: [{ label: "Start", slug: "lexicons/fixture/start" }],
+    });
+  });
+
+  test("generated reference tables get the diataxis field their sidebar group names", () => {
+    const cfg = config();
+    writeDocsSite(cfg, docsPipeline(cfg));
+    expect(readFileSync(join(section(), "intrinsics.mdx"), "utf-8")).toMatch(/^---\n[\s\S]*\ndiataxis: reference\n---/);
+    expect(readFileSync(join(section(), "index.mdx"), "utf-8")).not.toContain("diataxis:");
+  });
+
+  test("a page the pipeline stops emitting is gone after the next run", () => {
+    page("start.mdx", "title: Start\ndiataxis: tutorial");
+    const cfg = config();
+    writeDocsSite(cfg, docsPipeline(cfg));
+    rmSync(join(lex, "docs", "pages", "start.mdx"));
+    writeDocsSite(cfg, docsPipeline(cfg));
+    expect(existsSync(join(section(), "start.mdx"))).toBe(false);
+  });
+
+  test("a page's import of the app's Diagram component points at the main site's", () => {
+    page("concepts.mdx", "title: Concepts\ndiataxis: explanation", "import Diagram from '../../components/Diagram.astro';\n\n<Diagram name=\"x\" alt=\"x\" />\n");
+    const cfg = config();
+    writeDocsSite(cfg, docsPipeline(cfg));
+    expect(readFileSync(join(section(), "concepts.mdx"), "utf-8")).toContain(
+      "import Diagram from '../../../../components/Diagram.astro';",
+    );
+  });
+});
+
+describe("rebaseImports", () => {
+  test("re-points relative imports and leaves code fences and packages alone", () => {
+    const outDir = "/r/lexicons/x/docs";
+    const pageDir = "/r/docs/src/content/docs/lexicons/x";
+    const src = [
+      "import { Aside } from '@astrojs/starlight/components';",
+      "import raw from '../../../../examples/a.ts?raw';",
+      "```ts",
+      "import { y } from '../src/y';",
+      "```",
+    ].join("\n");
+    expect(rebaseImports(src, { outDir, siteDir: "/r/docs", pageDir }).split("\n")).toEqual([
+      "import { Aside } from '@astrojs/starlight/components';",
+      "import raw from '../../../../../../lexicons/x/examples/a.ts?raw';",
+      "```ts",
+      "import { y } from '../src/y';",
+      "```",
+    ]);
+  });
+});
+
+describe("standalone docs app pins", () => {
+  test("match the main docs site's Starlight and Astro", () => {
+    const docsPkg = JSON.parse(readFileSync(join(import.meta.dirname, "..", "..", "..", "..", "docs", "package.json"), "utf-8"));
+    for (const dep of ["@astrojs/starlight", "astro", "sharp"]) {
+      expect(DOCS_SITE_DEPENDENCIES[dep], dep).toBe(docsPkg.dependencies[dep]);
+    }
+  });
+});

package/src/codegen/docs-in-site.ts

@@ -0,0 +1,182 @@
+/**
+ * The in-site mode of the lexicon docs pipeline (chant #3993).
+ *
+ * Inside the chant repository every lexicon's docs are a section of the main
+ * Starlight site in `docs/`: one Astro build, one search index, one design.
+ * `writeDocsSite` writes a lexicon's pages to
+ * `docs/src/content/docs/lexicons/<name>/` and, beside them, `_sidebar.json`,
+ * the lexicon's collapsed sidebar group with its Diátaxis subgroups. The main
+ * site's `astro.config.mjs` reads every fragment through
+ * `docs/src/lexicon-sidebar.mjs`. Nothing else is written: no package.json, no
+ * Astro config, no components.
+ *
+ * Outside the repository (a third-party lexicon, a project scaffolded by
+ * `chant init-lexicon`) the pipeline keeps writing a standalone Starlight app
+ * into the lexicon's own `docs/`, as it always has.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { dirname, join, relative, resolve, sep } from "path";
+
+import { QUADRANT_LABELS, QUADRANTS } from "./docs-pages";
+import { quadrantItems } from "./docs-sidebar";
+import type { DocsConfig, DocsResult, Quadrant, SidebarPage } from "./docs-types";
+
+export type DocsSiteMode = "in-site" | "standalone";
+
+/**
+ * The dependencies a standalone lexicon docs app installs. They match
+ * `docs/package.json`, so a lexicon built on its own renders with the same
+ * Starlight and Astro as the main site; a test holds the two together.
+ */
+export const DOCS_SITE_DEPENDENCIES: Readonly<Record<string, string>> = {
+  "@astrojs/starlight": "^0.37.6",
+  astro: "5.6.1",
+  sharp: "^0.34.2",
+};
+
+/** Package name of the main docs site, `docs/package.json` in the chant repository. */
+const CHANT_DOCS_PACKAGE = "@intentius/chant-docs";
+
+/**
+ * The chant repository's main docs site (`<repo>/docs`) above `start`, or
+ * undefined. A directory qualifies when its `docs/package.json` is the chant
+ * docs package and `docs/astro.config.mjs` exists beside it, so a third-party
+ * repository with a docs site of its own is never mistaken for chant.
+ */
+export function findChantDocsSite(start: string): string | undefined {
+  let dir = resolve(start);
+  for (;;) {
+    const docs = join(dir, "docs");
+    const pkg = join(docs, "package.json");
+    if (existsSync(pkg) && existsSync(join(docs, "astro.config.mjs"))) {
+      try {
+        if ((JSON.parse(readFileSync(pkg, "utf-8")) as { name?: unknown }).name === CHANT_DOCS_PACKAGE) return docs;
+      } catch {
+        // Not JSON: not chant's docs site. Keep walking.
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+/**
+ * Which mode `writeDocsSite` runs in, and the main site's directory for
+ * in-site mode. `config.mode` wins, then `CHANT_DOCS_MODE`; with neither, a
+ * lexicon inside the chant repository goes in-site and any other standalone.
+ * `config.siteDir` or `CHANT_DOCS_SITE` names the main site when the walk up
+ * from `outDir` would not find it.
+ */
+export function resolveDocsMode(config: DocsConfig): { mode: DocsSiteMode; siteDir?: string } {
+  const env = process.env.CHANT_DOCS_MODE;
+  const requested = config.mode ?? (env === "in-site" || env === "standalone" ? env : undefined);
+  if (requested === "standalone") return { mode: "standalone" };
+  const siteDir = config.siteDir || process.env.CHANT_DOCS_SITE || findChantDocsSite(config.outDir);
+  if (requested === "in-site") {
+    if (!siteDir) {
+      throw new Error(
+        `[docs:${config.name}] in-site mode needs the chant docs site: none above ${resolve(config.outDir)}. ` +
+          `Set siteDir or CHANT_DOCS_SITE, or use standalone mode.`,
+      );
+    }
+    return { mode: "in-site", siteDir: resolve(siteDir) };
+  }
+  return siteDir ? { mode: "in-site", siteDir: resolve(siteDir) } : { mode: "standalone" };
+}
+
+/** Where a lexicon's section lives inside the main site's content collection. */
+export function sectionContentDir(siteDir: string, name: string): string {
+  return join(siteDir, "src", "content", "docs", "lexicons", name);
+}
+
+/**
+ * The lexicon's sidebar group for the main site: the lexicon's display name,
+ * collapsed, holding its overview and one collapsed group per non-empty
+ * Diátaxis quadrant. Slugs are prefixed with `lexicons/<name>/`.
+ */
+export function buildSectionGroup(config: DocsConfig, result: DocsResult): Record<string, unknown> {
+  const prefix = `lexicons/${config.name}`;
+  const byQuadrant = new Map<Quadrant, SidebarPage[]>();
+  for (const page of result.sidebarPages) {
+    if (page.hidden) continue;
+    const list = byQuadrant.get(page.quadrant) ?? [];
+    list.push({ ...page, slug: `${prefix}/${page.slug}` });
+    byQuadrant.set(page.quadrant, list);
+  }
+  const items: Array<Record<string, unknown>> = [{ label: "Overview", slug: prefix }];
+  for (const q of QUADRANTS) {
+    const pages = byQuadrant.get(q);
+    if (!pages || pages.length === 0) continue;
+    items.push({ label: QUADRANT_LABELS[q], collapsed: true, items: collapseGroups(quadrantItems(pages)) });
+  }
+  return { label: config.displayName, collapsed: true, items };
+}
+
+/** Every nested group starts collapsed, as on the rest of the main site. */
+function collapseGroups(items: Array<Record<string, unknown>>): Array<Record<string, unknown>> {
+  return items.map((item) =>
+    Array.isArray(item.items)
+      ? { label: item.label, collapsed: true, items: collapseGroups(item.items as Array<Record<string, unknown>>) }
+      : item,
+  );
+}
+
+/** Slugs of pages written but kept out of the sidebar, prefixed for the main site. */
+export function hiddenSectionSlugs(config: DocsConfig, result: DocsResult): string[] {
+  const listed = new Set(result.sidebarPages.map((p) => p.slug));
+  return [...result.pages.keys()]
+    .map((f) => f.replace(/\.mdx?$/, ""))
+    .filter((slug) => slug !== "index" && !listed.has(slug))
+    .sort()
+    .map((slug) => `lexicons/${config.name}/${slug}`);
+}
+
+/**
+ * Give a page the `diataxis` field of the quadrant the sidebar files it under,
+ * when it has none. Authored pages always carry one; the generated reference
+ * tables do not, and the main site's Diátaxis check reads the field.
+ */
+export function withQuadrant(content: string, quadrant: Quadrant | undefined): string {
+  if (!quadrant || !content.startsWith("---\n")) return content;
+  const end = content.indexOf("\n---", 4);
+  if (end === -1) return content;
+  if (/^diataxis:/m.test(content.slice(4, end))) return content;
+  return `${content.slice(0, end)}\ndiataxis: ${quadrant}${content.slice(end)}`;
+}
+
+const IMPORT_RE = /^(\s*import\s[^'"]*?\sfrom\s+|\s*import\s+)(['"])(\.\.?\/[^'"]+)\2(.*)$/;
+
+/**
+ * Re-point a page's relative ESM imports from where the standalone app kept
+ * the page (`<outDir>/src/content/docs/`) to where the main site keeps it.
+ * An import of the app's own components (`<outDir>/src/components/X`) goes to
+ * the main site's `src/components/X`, which holds the one shared copy.
+ * Fenced code blocks are left alone; their `import` lines are examples.
+ */
+export function rebaseImports(content: string, opts: { outDir: string; siteDir: string; pageDir: string }): string {
+  const fromDir = join(resolve(opts.outDir), "src", "content", "docs");
+  const appComponents = join(resolve(opts.outDir), "src", "components") + sep;
+  const siteComponents = join(opts.siteDir, "src", "components");
+  let fence: string | null = null;
+  return content
+    .split("\n")
+    .map((line) => {
+      const marker = line.match(/^\s*(`{3,}|~{3,})/)?.[1];
+      if (marker) {
+        if (fence === null) fence = marker[0];
+        else if (marker[0] === fence) fence = null;
+        return line;
+      }
+      if (fence !== null) return line;
+      const m = line.match(IMPORT_RE);
+      if (!m) return line;
+      let target = resolve(fromDir, m[3]);
+      if (target.startsWith(appComponents)) target = join(siteComponents, target.slice(appComponents.length));
+      let spec = relative(opts.pageDir, target).split(sep).join("/");
+      if (!spec.startsWith(".")) spec = `./${spec}`;
+      return `${m[1]}${m[2]}${spec}${m[2]}${m[4]}`;
+    })
+    .join("\n");
+}

package/src/codegen/docs-site/AgentPrompt.astro

@@ -6,14 +6,26 @@
 // render it from their PageTitle override; lexicon sites get a copy of this
 // file from writeDocsSite (docs.ts). The content schema refuses a prompt with
 // no "Never" line. No Starlight import here, so the file works from any site.
+// `text`, `label` and `note` replace the page's prompt and the caption (the
+// main site's home page passes the setup prompt); an `icon` slot goes before
+// the label (the main site passes its logo).
 interface Props {
 	text?: string;
+	label?: string;
+	note?: string;
 }
+const {
+	label = 'Optional: hand this page to your coding agent',
+	note = 'The steps work by hand too.',
+} = Astro.props;
 const prompt = (Astro.props.text ?? Astro.locals.starlightRoute?.entry.data.prompt)?.trim();
 ---
 {prompt && (
 	<figure class="chant-prompt not-content" id="agent-prompt">
-		<figcaption>Optional: hand this page to your coding agent</figcaption>
+		<figcaption>
+			<span class="label"><slot name="icon" />{label}</span>
+			{note && <span class="note">{note}</span>}
+		</figcaption>
 		<details>
 			<summary>
 				<pre class="peek" aria-hidden="true">{prompt}</pre>
@@ -69,11 +81,24 @@ const prompt = (Astro.props.text ?? Astro.locals.starlightRoute?.entry.data.prom
 		--chant-prompt-blue: #60a5fa;
 	}
 	figcaption {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: baseline;
+		gap: 0.25rem 0.75rem;
 		padding: 0.7rem 1rem 0.4rem;
+	}
+	.label {
+		display: inline-flex;
+		align-items: center;
+		gap: 0.5rem;
 		font-size: 0.85rem;
 		font-weight: 600;
 		color: var(--sl-color-white);
 	}
+	.note {
+		font-size: 0.75rem;
+		color: var(--sl-color-gray-3);
+	}
 	summary {
 		display: block;
 		list-style: none;

package/src/codegen/docs-types.ts

@@ -38,8 +38,21 @@ export interface DocsConfig {
   suppressPages?: string[];
   /** Source directory for scanning rule files (defaults to srcDir sibling of distDir) */
   srcDir?: string;
-  /** Base path for the generated Astro site (e.g. '/lexicons/aws/') */
+  /** Base path for the generated Astro site (e.g. '/lexicons/aws/'). Standalone mode only. */
   basePath?: string;
+  /**
+   * Where `writeDocsSite` writes (chant #3993). `in-site`: the lexicon's pages
+   * and sidebar fragment go into the chant repository's main docs site.
+   * `standalone`: a Starlight app of its own in `outDir`. Unset, the
+   * `CHANT_DOCS_MODE` environment variable decides, and without it a lexicon
+   * inside the chant repository goes in-site and any other standalone.
+   */
+  mode?: "in-site" | "standalone";
+  /**
+   * The main docs site (`<chant repo>/docs`) for in-site mode. Defaults to
+   * `CHANT_DOCS_SITE`, then to the first one found walking up from `outDir`.
+   */
+  siteDir?: string;
   /** Root directory for resolving {{file:...}} markers in extra page content */
   examplesDir?: string;
   /**

package/src/codegen/docs.ts

@@ -8,10 +8,19 @@
  */
 
 import { copyFileSync, existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "fs";
-import { join } from "path";
+import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 
 import { expandFileMarkers } from "./docs-file-markers";
+import {
+  DOCS_SITE_DEPENDENCIES,
+  buildSectionGroup,
+  hiddenSectionSlugs,
+  rebaseImports,
+  resolveDocsMode,
+  sectionContentDir,
+  withQuadrant,
+} from "./docs-in-site";
 import { readAuthoredPages } from "./docs-pages";
 import { scanRules, generateRules } from "./docs-rule-scanning";
 import { buildSidebar } from "./docs-sidebar";
@@ -22,6 +31,14 @@ import type { DocsConfig, DocsResult, ManifestJSON, MetaEntry, SidebarPage } fro
 export { expandFileMarkers } from "./docs-file-markers";
 export type { DocsConfig, DocsResult, Quadrant, SidebarPage } from "./docs-types";
 export { QUADRANTS, QUADRANT_LABELS, readAuthoredPages } from "./docs-pages";
+export {
+  DOCS_SITE_DEPENDENCIES,
+  buildSectionGroup,
+  findChantDocsSite,
+  resolveDocsMode,
+  sectionContentDir,
+  type DocsSiteMode,
+} from "./docs-in-site";
 
 // ── Pipeline ───────────────────────────────────────────────────────
 
@@ -279,6 +296,46 @@ export function writeDocsPages(result: DocsResult, outDir: string): void {
   }
 }
 
+/**
+ * Write a lexicon's docs from pipeline results, in the mode
+ * {@link resolveDocsMode} picks: inside the chant repository, a section of the
+ * main site ({@link writeDocsSection}); anywhere else, a standalone Starlight
+ * app ({@link writeStandaloneDocsSite}). Every lexicon's `docs.ts` calls this,
+ * so neither they nor the `chant init-lexicon` scaffold choose a mode.
+ */
+export function writeDocsSite(config: DocsConfig, result: DocsResult): void {
+  const { mode, siteDir } = resolveDocsMode(config);
+  if (mode === "in-site" && siteDir) writeDocsSection(config, result, siteDir);
+  else writeStandaloneDocsSite(config, result);
+}
+
+/**
+ * Write a lexicon's pages into the main docs site (chant #3993): every page
+ * under `docs/src/content/docs/lexicons/<name>/`, and `_sidebar.json` beside
+ * them with the lexicon's sidebar group and its hidden pages. The section is
+ * build output, so the directory is replaced whole on every run; a page the
+ * pipeline stopped emitting cannot linger. No app files are written.
+ */
+export function writeDocsSection(config: DocsConfig, result: DocsResult, siteDir: string): void {
+  const sectionDir = sectionContentDir(siteDir, config.name);
+  rmSync(sectionDir, { recursive: true, force: true });
+  mkdirSync(sectionDir, { recursive: true });
+
+  const quadrantOf = new Map(result.sidebarPages.map((p) => [`${p.slug}.mdx`, p.quadrant]));
+  for (const [filename, content] of result.pages) {
+    const filePath = join(sectionDir, filename);
+    const pageDir = dirname(filePath);
+    mkdirSync(pageDir, { recursive: true });
+    const page = rebaseImports(withQuadrant(content, quadrantOf.get(filename)), { outDir: config.outDir, siteDir, pageDir });
+    writeFileSync(filePath, page);
+  }
+
+  writeFileSync(
+    join(sectionDir, "_sidebar.json"),
+    JSON.stringify({ group: buildSectionGroup(config, result), hidden: hiddenSectionSlugs(config, result) }, null, 2) + "\n",
+  );
+}
+
 /**
  * Scaffold a standalone Starlight docs site from pipeline results.
  *
@@ -286,7 +343,7 @@ export function writeDocsPages(result: DocsResult, outDir: string): void {
  * pages under src/content/docs/. The resulting directory can be built with
  * `npm install && npm run build`.
  */
-export function writeDocsSite(config: DocsConfig, result: DocsResult): void {
+export function writeStandaloneDocsSite(config: DocsConfig, result: DocsResult): void {
   const outDir = config.outDir;
   const contentDir = join(outDir, "src", "content", "docs");
 
@@ -350,11 +407,7 @@ export function writeDocsSite(config: DocsConfig, result: DocsResult): void {
           build: "astro build",
           preview: "astro preview",
         },
-        dependencies: {
-          "@astrojs/starlight": "^0.37.6",
-          astro: "^5.6.1",
-          sharp: "^0.34.2",
-        },
+        dependencies: { ...DOCS_SITE_DEPENDENCIES },
       },
       null,
       2,

package/src/codegen/rehype-base-url.d.mts

@@ -3,6 +3,8 @@ export interface RehypeBaseUrlOptions {
   base: string;
   /** Project-wide base used to detect already-correctly-prefixed cross-site links. */
   projectBase?: string;
+  /** Per-page base, by the page's source path; undefined falls back to `base`. */
+  baseFor?: (path: string) => string | undefined;
 }
 
 type HastNode = {
@@ -14,4 +16,4 @@ type HastNode = {
 
 export default function rehypeBaseUrl(
   opts: RehypeBaseUrlOptions,
-): (tree: HastNode) => void;
+): (tree: HastNode, file?: { path?: string }) => void;

package/src/codegen/rehype-base-url.mjs

@@ -11,9 +11,16 @@
  * idempotently skips hrefs that already start with the site's own base or the
  * project-wide base.
  *
+ * `baseFor` lets one site hold sections with their own root (chant #3993): the
+ * main docs site builds every lexicon's pages under /chant/lexicons/<name>/,
+ * and a lexicon page's `/foo/` has always meant its own lexicon's root, as it
+ * did when each lexicon was a separate site. `baseFor(file.path)` returns the
+ * base for that page, or undefined to use `base`.
+ *
  * @typedef {Object} RehypeBaseUrlOptions
  * @property {string} base - Site base, e.g. "/chant" or "/chant/lexicons/aws". Trailing/leading slashes optional.
  * @property {string} [projectBase] - Project-wide base used to detect already-correctly-prefixed cross-site links.
+ * @property {(path: string) => string | undefined} [baseFor] - Per-page base, by the page's source path.
  */
 
 const PROTOCOL_RE = /^[a-z][a-z0-9+.-]*:/i;
@@ -26,16 +33,12 @@ function normalizeBase(value) {
  * @param {RehypeBaseUrlOptions} opts
  */
 export default function rehypeBaseUrl(opts) {
-  const base = normalizeBase(opts.base);
-  if (base === "/") {
-    return () => {};
-  }
-  const ownPrefix = base + "/";
+  const siteBase = normalizeBase(opts.base);
   const projectPrefix = opts.projectBase
     ? normalizeBase(opts.projectBase) + "/"
     : null;
 
-  function rewrite(node) {
+  function rewrite(node, base, ownPrefix) {
     if (
       node &&
       node.type === "element" &&
@@ -58,11 +61,14 @@ export default function rehypeBaseUrl(opts) {
       }
     }
     if (node && node.children) {
-      for (const child of node.children) rewrite(child);
+      for (const child of node.children) rewrite(child, base, ownPrefix);
     }
   }
 
-  return (tree) => {
-    rewrite(tree);
+  return (tree, file) => {
+    const own = opts.baseFor && file && typeof file.path === "string" ? opts.baseFor(file.path) : undefined;
+    const base = own ? normalizeBase(own) : siteBase;
+    if (base === "/") return;
+    rewrite(tree, base, base + "/");
   };
 }