dogsbay 0.2.0-beta.17 → 0.2.0-beta.18

package/dist/commands/site-build.js

@@ -17,7 +17,8 @@
 import { existsSync } from "node:fs";
 import { dirname, isAbsolute, resolve } from "node:path";
 import pc from "picocolors";
-import { emitAstroPages, emitSiteConfig, emitConfigDerivedFiles, emitAgentReadinessFiles, emitMissingTranslationStubs, emitSwitcherMap, emitTaxonomyRoutes, emitPluginRuntime, normalizeBasePath, basePathSegments, } from "@dogsbay/format-astro";
+import { emitAstroPages, emitPassthroughAstroPages, emitSiteConfig, emitConfigDerivedFiles, emitAgentReadinessFiles, emitMissingTranslationStubs, emitSwitcherMap, emitTaxonomyRoutes, emitPluginRuntime, normalizeBasePath, basePathSegments, } from "@dogsbay/format-astro";
+import { collectPassthroughEntries } from "../passthrough-astro.js";
 import { configToAstroOptions, findConfig, loadConfig, resolveOutputDir, } from "../config/index.js";
 import { filterSourcesForMode, importContent, primaryModeFiltersAnything, } from "../import-content.js";
 import { resolveSource } from "../source-resolver.js";
@@ -170,7 +171,30 @@ export async function siteBuild(cwd, options) {
     // config-derived, so changes in dogsbay.config.yml propagate without
     // re-running site init.
     emitSiteConfig(outputDir, config.site.name, astroOpts);
-    const { generated, outputNav } = await emitAstroPages(pages, nav, outputDir, astroOpts);
+    const { generated, outputNav, generatedPaths } = await emitAstroPages(pages, nav, outputDir, astroOpts);
+    // Passthrough Astro pages — hand-authored .astro files that live
+    // alongside the markdown sources and are listed in nav.yml. Picked
+    // up by walking the source directories for *.astro and intersecting
+    // with the resolved nav hrefs. Collisions with generated pages are
+    // a build error (loud, not silent overwrite). See
+    // plans/passthrough-astro-pages.md.
+    const passthroughCopies = [];
+    for (const sourceDir of resolvedSources) {
+        const entries = collectPassthroughEntries(sourceDir, outputNav, {
+            basePath: normalizeBasePath(astroOpts.basePath),
+        });
+        for (const entry of entries) {
+            passthroughCopies.push({
+                source: entry.source,
+                sourceAbs: entry.sourceAbs,
+                outputRelPath: entry.outputRelPath,
+            });
+        }
+    }
+    if (passthroughCopies.length > 0) {
+        const { copied } = emitPassthroughAstroPages(passthroughCopies, outputDir, generatedPaths);
+        console.log(`  Copied ${copied} passthrough .astro page${copied === 1 ? "" : "s"}`);
+    }
     emitConfigDerivedFiles(outputDir, astroOpts);
     emitAgentReadinessFiles(pages, outputNav, outputDir, config.site.name, astroOpts);
     // switcherMap.json — per-page version-equivalent lookup. No-op

package/dist/passthrough-astro.js

@@ -0,0 +1,152 @@
+/**
+ * Passthrough Astro page collection.
+ *
+ * Hand-authored `.astro` files that live under a content source's
+ * directory get copied verbatim to `src/pages/<basePath>/...` at
+ * build time. Authors opt in by listing the file in `nav.yml`; the
+ * intersection of "files on disk" and "hrefs in nav" defines the
+ * passthrough set.
+ *
+ * See plans/passthrough-astro-pages.md.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, posix, relative, sep } from "node:path";
+/**
+ * Walk `contentDir` for `.astro` files, compute each one's canonical
+ * href, and return only the entries whose href appears in the
+ * resolved nav. Files outside the nav are ignored — passthrough is
+ * opt-in to avoid accidentally publishing scratch components.
+ */
+export function collectPassthroughEntries(contentDir, nav, options) {
+    if (!existsSync(contentDir))
+        return [];
+    const navHrefs = collectNavHrefs(nav);
+    const candidates = walkAstroFiles(contentDir, contentDir);
+    const entries = [];
+    for (const sourceAbs of candidates) {
+        const source = toPosix(relative(contentDir, sourceAbs));
+        const href = sourceToHref(source, options.basePath);
+        if (!navHrefs.has(href))
+            continue;
+        entries.push({
+            source,
+            sourceAbs,
+            outputRelPath: sourceToOutputRelPath(source, options.basePath),
+            href,
+        });
+    }
+    return entries;
+}
+/**
+ * Recursively gather every `.astro` file under `dir`. Skips
+ * `node_modules`, dot-directories, and any directory named
+ * `_components` / `_partials` (a common convention for "this is
+ * shared, don't publish it" — leaves authors an obvious escape
+ * hatch when they want to ship private helpers alongside content).
+ */
+function walkAstroFiles(dir, root) {
+    const out = [];
+    let entries = [];
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith("."))
+            continue;
+        if (entry.name === "node_modules")
+            continue;
+        if (entry.name === "_components" || entry.name === "_partials")
+            continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...walkAstroFiles(full, root));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".astro")) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+/**
+ * Compute the public-facing href for a source path. Mirrors the
+ * slug logic in `format-dogsbay-md/src/nav-file.ts:fileToHref` so a
+ * passthrough .astro file produces the same href as a hypothetical
+ * .md sibling at the same path.
+ *
+ * - "tutorials/playground.astro" → "/docs/tutorials/playground"
+ * - "reference/index.astro"      → "/docs/reference"
+ * - "index.astro"                → "/docs"
+ */
+function sourceToHref(source, basePath) {
+    let slug = source.replace(/\.astro$/i, "");
+    if (slug.endsWith("/index"))
+        slug = slug.slice(0, -"/index".length);
+    if (slug === "index")
+        slug = "";
+    const prefix = basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
+    return slug ? `${prefix}/${slug}` : prefix || "";
+}
+/**
+ * Compute the output path (relative to outputDir) where a passthrough
+ * source should be copied. Preserves the source's directory shape
+ * under `src/pages/<basePath segments>/`. Index files survive as
+ * `index.astro` so Astro's directory-routing matches the nav href.
+ */
+function sourceToOutputRelPath(source, basePath) {
+    const baseSegs = basePath.split("/").filter((s) => s.length > 0);
+    const sourceSegs = source.split("/");
+    return ["src", "pages", ...baseSegs, ...sourceSegs].join(sep);
+}
+/** Walk a NavItem tree collecting every href into a Set. */
+function collectNavHrefs(nav) {
+    const out = new Set();
+    const stack = [...nav];
+    while (stack.length > 0) {
+        const item = stack.pop();
+        if (item.href)
+            out.add(item.href);
+        if (item.children)
+            stack.push(...item.children);
+    }
+    return out;
+}
+/**
+ * Normalize backslashes (Windows path separators) to forward slashes
+ * before doing any href / slug computation. The slug shape is
+ * URL-flavoured even on Windows.
+ */
+function toPosix(p) {
+    return p.split(sep).join(posix.sep);
+}
+/**
+ * Build the slug set covered by the passthrough entries. Used by
+ * site-build to assert no collision with generated slugs from
+ * `emitAstroPages`.
+ */
+export function passthroughSlugs(entries) {
+    return new Set(entries.map((e) => e.href));
+}
+/**
+ * Convenience guard — verify every passthrough source still exists
+ * on disk. Walking already only returns existing files, but this
+ * helper is useful when entries are constructed externally (e.g. in
+ * tests).
+ */
+export function assertPassthroughFilesExist(entries) {
+    for (const entry of entries) {
+        if (!existsSync(entry.sourceAbs)) {
+            throw new Error(`Passthrough Astro source missing: ${entry.source} ` +
+                `(resolved: ${entry.sourceAbs})`);
+        }
+    }
+    // Touch statSync to detect non-file entries (defensive)
+    for (const entry of entries) {
+        const st = statSync(entry.sourceAbs);
+        if (!st.isFile()) {
+            throw new Error(`Passthrough Astro source is not a file: ${entry.source}`);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dogsbay",
-  "version": "0.2.0-beta.17",
+  "version": "0.2.0-beta.18",
   "description": "CLI for Dogsbay — scaffold, build, and serve documentation sites with markdown / MkDocs / Obsidian / OpenAPI sources",
   "type": "module",
   "bin": {
@@ -32,14 +32,14 @@
     "picocolors": "^1.1.0",
     "prompts": "^2.4.2",
     "yaml": "^2.8.3",
-    "@dogsbay/format-mkdocs": "0.2.0-beta.17",
-    "@dogsbay/format-astro": "0.2.0-beta.17",
-    "@dogsbay/format-obsidian": "0.2.0-beta.17",
-    "@dogsbay/format-mdx": "0.2.0-beta.17",
-    "@dogsbay/format-starlight": "0.2.0-beta.17",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.17",
-    "@dogsbay/format-openapi": "0.2.0-beta.17",
-    "@dogsbay/types": "0.2.0-beta.17"
+    "@dogsbay/format-mkdocs": "0.2.0-beta.18",
+    "@dogsbay/format-obsidian": "0.2.0-beta.18",
+    "@dogsbay/format-mdx": "0.2.0-beta.18",
+    "@dogsbay/format-starlight": "0.2.0-beta.18",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.18",
+    "@dogsbay/format-openapi": "0.2.0-beta.18",
+    "@dogsbay/format-astro": "0.2.0-beta.18",
+    "@dogsbay/types": "0.2.0-beta.18"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",