dogsbay 0.2.0-beta.43 → 0.2.0-beta.44

package/dist/commands/migrate-mkdocs.js

@@ -77,6 +77,17 @@ export async function migrateMkdocs(source, options) {
         console.log("Pass --force to overwrite.");
         process.exit(1);
     }
+    // On a --force re-run the existing dogsbay.config.yml carries
+    // deployment config the user owns — site.url + site.basePath —
+    // that has NO other source: it isn't in mkdocs.yml, and --site-url
+    // is deliberately not inherited from the source. Read it so a
+    // re-run that omits the flags preserves those values instead of
+    // silently resetting site.url to unset and basePath to /docs.
+    // Explicit --site-url / --base-path flags still win; a fresh
+    // migration (no existing config) is unaffected.
+    const existingDeployment = existingConfig
+        ? readExistingDeployment(existingConfig)
+        : {};
     console.log();
     console.log(pc.bold(`Migrating MkDocs site to Dogsbay-MD: ${siteName}`));
     console.log(`Source:  ${sourceDir}`);
@@ -147,13 +158,18 @@ export async function migrateMkdocs(source, options) {
     // site.url is left unset and the build emits relative URLs.
     // sourceSiteUrl is kept only to warn the user it was dropped.
     const sourceSiteUrl = config.site_url || undefined;
-    const siteUrl = options.siteUrl || undefined;
+    // Precedence: --site-url flag → existing config (--force re-run) →
+    // unset. Never the source mkdocs.yml's site_url.
+    const siteUrl = options.siteUrl || existingDeployment.siteUrl || undefined;
     const repoUrl = config.repo_url || undefined;
-    // --base-path controls where docs sit under the host. Default
-    // /docs (matches every scaffolded dogsbay site); pass --base-path
-    // "" to serve at the host root — common for a dedicated repo or
-    // GitHub Pages project site.
-    const basePath = options.basePath !== undefined ? options.basePath : "/docs";
+    // --base-path controls where docs sit under the host. Precedence:
+    // --base-path flag → existing config (--force re-run) → /docs
+    // default (matches every scaffolded dogsbay site). Pass
+    // --base-path "" to serve at the host root — common for a
+    // dedicated repo or GitHub Pages project site.
+    const basePath = options.basePath !== undefined
+        ? options.basePath
+        : existingDeployment.basePath ?? "/docs";
     const siteDescription = config.site_description || undefined;
     const dogsbayConfig = {
         schemaVersion: 1,
@@ -183,6 +199,17 @@ export async function migrateMkdocs(source, options) {
     };
     writeFileSync(join(outputDir, "dogsbay.config.yml"), serializeConfig(dogsbayConfig, "yaml"));
     console.log(pc.green(`Wrote`) + ` dogsbay.config.yml`);
+    // Surface preserved deployment config so a --force re-run isn't a
+    // silent black box — the user sees what carried over.
+    if (!options.siteUrl && existingDeployment.siteUrl) {
+        console.log(pc.green(`Kept`) +
+            ` site.url from the existing config: ${existingDeployment.siteUrl}`);
+    }
+    if (options.basePath === undefined &&
+        existingDeployment.basePath !== undefined) {
+        console.log(pc.green(`Kept`) +
+            ` site.basePath from the existing config: "${existingDeployment.basePath}"`);
+    }
     if (sourceSiteUrl && !siteUrl) {
         console.log(pc.yellow(`Note:`) +
             ` source site_url (${sourceSiteUrl}) was not carried over —` +
@@ -532,6 +559,30 @@ function extractAutodocOptions(mkdocsConfig) {
     }
     return Object.keys(out).length > 0 ? out : null;
 }
+/**
+ * Read the user-owned deployment config — `site.url` + `site.basePath`
+ * — out of an existing `dogsbay.config.yml` so a `--force` re-run can
+ * preserve them when the `--site-url` / `--base-path` flags are
+ * omitted.
+ *
+ * Lenient on purpose: `YAML.parse` reads both .yml and .json (JSON is
+ * valid YAML), and an unparseable / unexpected-shape config falls
+ * through to `{}` rather than aborting the migration — a re-run
+ * should never be blocked by a stale config it's about to overwrite.
+ */
+function readExistingDeployment(configPath) {
+    try {
+        const parsed = YAML.parse(readFileSync(configPath, "utf-8"));
+        const site = parsed?.site;
+        return {
+            siteUrl: typeof site?.url === "string" ? site.url : undefined,
+            basePath: typeof site?.basePath === "string" ? site.basePath : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * Extract macros plugin data file mappings from mkdocs.yml.
  * Returns { varName: absolutePath } for each `include_yaml` entry,
@@ -929,7 +980,18 @@ function buildMigrationNotes(args) {
         }
         lines.push("Set the destination URL in `dogsbay.config.yml`:", "", "```yaml", "site:", "  url: https://you.github.io/your-repo   # drives sitemap, llms.txt, canonical", `  basePath: ${basePath || '""'}`, "```", "", "Or re-run the migration with `--site-url` (and optionally", "`--base-path`).", "");
     }
-    lines.push("## Re-running the migration", "", "If you find a regression and we ship a fix, re-run with `--force`:", "", "```bash", `npx dogsbay migrate-mkdocs ${sourceDir} --output ${outputDir} --force`, "```", "", "Note that `--force` overwrites all generated files; any hand edits", "to `./content/*.md` since the last migration will be lost. Commit", "your work first.", "");
+    // Re-run command — spell out the deployment flags so the
+    // documented command reproduces the same site.url / basePath even
+    // against a fresh output dir. (A bare `--force` re-run also
+    // preserves them now, read back from the existing config — see the
+    // note below — but a self-contained command is the safer thing to
+    // copy.)
+    const rerunFlags = ["--output", outputDir, "--force"];
+    if (siteUrl)
+        rerunFlags.push("--site-url", siteUrl);
+    if (basePath !== "/docs")
+        rerunFlags.push("--base-path", `"${basePath}"`);
+    lines.push("## Re-running the migration", "", "If you find a regression and a later release fixes it, re-run", "with `--force`:", "", "```bash", `npx dogsbay migrate-mkdocs ${sourceDir} ${rerunFlags.join(" ")}`, "```", "", "`--force` overwrites all generated files; any hand edits to", "`./content/*.md` since the last migration will be lost — commit", "your work first.", "", "Your deployment config is preserved across a re-run: `site.url`", "and `site.basePath` are read back from the existing", "`dogsbay.config.yml` when the `--site-url` / `--base-path` flags", "are omitted (the flags still win when passed). Everything else in", "the config is re-derived from the source `mkdocs.yml`.", "");
     if (lossy.length > 0) {
         lines.push("## Known limitations", "");
         lines.push("The following files have content that didn't fully round-trip", "into Dogsbay-MD. Review each one and fix manually:", "");

package/package.json

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