create-thally-docs 0.10.118 → 0.10.119

package/dist/chunk-VCVHOOB5.js

@@ -0,0 +1,671 @@
+#!/usr/bin/env node
+import {
+  findPublicSpecs,
+  shadowNote
+} from "./chunk-KDLP27DS.js";
+import {
+  initGit,
+  installDeps,
+  runProjectCommand,
+  scaffold
+} from "./chunk-6MT76XGS.js";
+import {
+  pruneMissingSiteLinks
+} from "./chunk-UG3OXVLE.js";
+import {
+  resolveStarterUpdateBase
+} from "./chunk-7BAJKUBN.js";
+import {
+  downloadStarter
+} from "./chunk-44WRU5LD.js";
+import {
+  terminal
+} from "./chunk-L2YCVQBR.js";
+import {
+  areStarterFileContentsEquivalent
+} from "./chunk-C4DPGWFM.js";
+
+// src/migrate/index.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync5, mkdirSync as mkdirSync3, mkdtempSync as mkdtempSync3, readFileSync as readFileSync4, realpathSync as realpathSync2, rmSync as rmSync3, writeFileSync as writeFileSync2 } from "fs";
+import { tmpdir as tmpdir2 } from "os";
+import { basename, join as join5, resolve as resolve2 } from "path";
+import {
+  cloneGitHubRepository,
+  importSourceRef,
+  hydrateRemoteApiSpecs,
+  hydrateUrlOpenApi,
+  migrateUrl,
+  runUrlMigration,
+  parseGitHubRepositoryUrl,
+  sourceRefOversizeReason
+} from "@thallylabs/migrate";
+
+// src/migration-work.ts
+import { Worker } from "worker_threads";
+async function runMigrationWork(request, options) {
+  const worker = new Worker(options.workerUrl ?? new URL("./migration-worker.js", import.meta.url), {
+    workerData: request,
+    stdout: true,
+    stderr: true
+  });
+  worker.stdout.resume();
+  worker.stderr.resume();
+  try {
+    return await new Promise((complete, reject) => {
+      worker.once("message", (response) => {
+        if (response.error) reject(response.error);
+        else complete(response.result);
+      });
+      worker.once("error", reject);
+      worker.once("exit", (code) => reject(new Error(`Migration worker exited before returning a result (exit ${code}).`)));
+    });
+  } finally {
+    await worker.terminate();
+  }
+}
+function convertRepository(options, workerOptions = {}) {
+  return runMigrationWork({ operation: "repository", args: [options] }, workerOptions);
+}
+function renderFiles(bundle, options, workerOptions = {}) {
+  return runMigrationWork({ operation: "render", args: [bundle, options] }, workerOptions);
+}
+function discoverUrl(options, workerOptions = {}) {
+  return runMigrationWork({ operation: "url", args: [options] }, workerOptions);
+}
+function checkContent(projectDir, workerOptions = {}) {
+  return runMigrationWork({ operation: "check", args: [projectDir] }, workerOptions);
+}
+
+// src/migrate/validate.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+async function validateMigration(projectDir, skip = false, installationFailed = false) {
+  const result = { content: "skipped", build: "skipped", messages: [], diagnostics: [] };
+  if (skip) {
+    result.messages.push("Validation was explicitly skipped; this import is not verified.");
+    return result;
+  }
+  try {
+    const isQuiet = terminal.isRich && !terminal.isVerbose;
+    await terminal.step("Validate content", async () => {
+      const checked = await checkContent(projectDir);
+      const code = checked.code;
+      result.diagnostics = checked.diagnostics;
+      if (!isQuiet) {
+        for (const issue of checked.diagnostics) {
+          const location = issue.file ? `file=${issue.file}${issue.line ? `,line=${issue.line}` : ""}` : "";
+          console.log(`::${issue.severity} ${location}::${issue.message}`);
+        }
+        const errors = checked.diagnostics.filter((issue) => issue.severity === "error").length;
+        const warnings = checked.diagnostics.length - errors;
+        console.log(`
+thally check: ${errors} error(s), ${warnings} warning(s)`);
+      }
+      if (isQuiet) {
+        for (const issue of result.diagnostics) {
+          result.messages.push(`${issue.file ? `${issue.file}${issue.line ? `:${issue.line}` : ""}: ` : ""}${issue.message}`);
+        }
+      }
+      if (code !== 0) throw new Error("Review the content diagnostics; source links are not silently rewritten.");
+    }, "Content validated");
+    result.content = "passed";
+  } catch (error) {
+    if ([130, 143].includes(error.exitCode ?? 0)) throw error;
+    result.content = "failed";
+    result.messages.push(`Content validation failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (installationFailed) {
+    result.build = "failed";
+    result.messages.push("Dependency installation failed; production build was not attempted. Review the installation output before retrying.");
+    return result;
+  }
+  const packagePath = join(projectDir, "package.json");
+  try {
+    const manifest = existsSync(packagePath) ? JSON.parse(readFileSync(packagePath, "utf8")) : void 0;
+    if (!manifest?.scripts?.build) {
+      result.messages.push("No build script is available; production rendering is not verified.");
+      return result;
+    }
+    try {
+      await terminal.step("Validate production build", (update) => runProjectCommand("npm", ["run", "build"], projectDir, 10 * 60 * 1e3, (message) => update(`Production build: ${message}`)), "Production build validated");
+      result.build = "passed";
+    } catch (error) {
+      const failure = error;
+      if (failure.output?.trim()) terminal.error(failure.output.trimEnd());
+      throw error;
+    }
+  } catch (error) {
+    if ([130, 143].includes(error.exitCode ?? 0)) throw error;
+    result.build = "failed";
+    result.messages.push(`Production build failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return result;
+}
+
+// src/migrate/local-source.ts
+import { copyFileSync, existsSync as existsSync2, lstatSync, mkdirSync, readdirSync, realpathSync, statSync } from "fs";
+import { detectRepositoryDocsDir, projectMintlifyNavigation, readMintlifyConfig } from "@thallylabs/migrate";
+import { dirname, extname, isAbsolute, join as join2, relative, resolve, sep } from "path";
+var generatedDirectories = /* @__PURE__ */ new Set(["dist", "build", "coverage"]);
+var extensions = /* @__PURE__ */ new Set([".md", ".mdx", ".json", ".yaml", ".yml", ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".css", ".scss", ".sass", ".avif", ".bmp", ".gif", ".ico", ".jpeg", ".jpg", ".m4a", ".mp3", ".mp4", ".ogg", ".pdf", ".png", ".svg", ".wav", ".webm", ".webp"]);
+function contains(root, candidate) {
+  const path = relative(root, candidate);
+  return !isAbsolute(path) && path !== ".." && !path.startsWith(`..${sep}`);
+}
+function physicalPath(path) {
+  if (existsSync2(path)) return realpathSync(path);
+  const parent = dirname(path);
+  return parent === path ? path : join2(physicalPath(parent), relative(parent, path));
+}
+function assertSeparateMigrationDirectories(source, output) {
+  const sourceRoot = realpathSync(resolve(source));
+  if (!statSync(sourceRoot).isDirectory()) throw new Error("The local migration source must be a directory.");
+  const target = physicalPath(resolve(output));
+  if (contains(sourceRoot, target) || contains(target, sourceRoot)) {
+    throw new Error("Local migration source and output directories must not overlap. Choose a separate output directory.");
+  }
+}
+function assertMigrationDestination(projectDir, candidate = "") {
+  const root = resolve(projectDir);
+  const target = resolve(root, candidate);
+  if (!contains(root, target)) throw new Error(`Generated migration path escapes the project: ${candidate}`);
+  const parts = relative(root, target).split(sep).filter(Boolean);
+  let current = root;
+  for (const [index, part] of ["", ...parts].entries()) {
+    if (part) current = join2(current, part);
+    try {
+      const entry = lstatSync(current);
+      if (entry.isSymbolicLink()) throw new Error(`Migration destination must not traverse a symbolic link: ${current}`);
+      if ((index < parts.length || parts.length === 0) && !entry.isDirectory()) throw new Error(`Migration destination parent must be a directory: ${current}`);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  return target;
+}
+function snapshotLocalMigration(source, snapshot, docsDir) {
+  const root = realpathSync(resolve(source));
+  let files = 0;
+  let bytes = 0;
+  const visited = /* @__PURE__ */ new Set();
+  const safeName = (name) => name === ".mintignore" || !name.startsWith(".") && name !== "node_modules";
+  const detectedDocsDir = detectRepositoryDocsDir(root);
+  const conventionalDocsDir = ["docs", "documentation", "content", "pages", "src/content", "src/pages", "guide", "guides"].find((path) => {
+    try {
+      return lstatSync(join2(root, path)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+  const selectedDocsDir = docsDir ?? (detectedDocsDir || conventionalDocsDir);
+  const contentRoot = selectedDocsDir ? resolve(root, selectedDocsDir) : void 0;
+  if (contentRoot && (!contains(root, contentRoot) || existsSync2(contentRoot) && !contains(root, realpathSync(contentRoot)))) throw new Error("The selected documentation directory must remain inside the local source.");
+  const references = /* @__PURE__ */ new Set();
+  for (const configRoot of /* @__PURE__ */ new Set([root, ...contentRoot ? [contentRoot] : []])) {
+    const config = readMintlifyConfig(configRoot);
+    if (!config) continue;
+    for (const { ref } of projectMintlifyNavigation(config).pageReferences) {
+      const path = resolve(configRoot, ref.replace(/^\//, "").replace(/\.mdx?$/i, ""));
+      if (contains(root, path)) references.add(path);
+    }
+  }
+  const includesGeneratedName = (directory) => relative(root, directory).split(sep).some((name) => generatedDirectories.has(name));
+  const shouldCopyDirectory = (directory) => !includesGeneratedName(directory) || Boolean(contentRoot && contains(contentRoot, directory)) || [...references].some((page) => contains(directory, page));
+  function walk(directory, destination) {
+    const real = realpathSync(directory);
+    if (!contains(root, real) || visited.has(real)) return;
+    if (relative(root, real).split(sep).some((name) => name && !safeName(name))) return;
+    visited.add(real);
+    mkdirSync(destination, { recursive: true });
+    for (const entry of readdirSync(real, { withFileTypes: true })) {
+      if (!safeName(entry.name)) continue;
+      const path = join2(real, entry.name);
+      let actual;
+      try {
+        actual = realpathSync(path);
+      } catch {
+        continue;
+      }
+      if (!contains(root, actual) || relative(root, actual).split(sep).some((name) => !safeName(name))) continue;
+      const info = statSync(actual);
+      const target = join2(destination, entry.name);
+      if (info.isDirectory() && shouldCopyDirectory(path)) walk(actual, target);
+      else if (info.isFile() && (entry.name === ".mintignore" || extensions.has(extname(actual).toLowerCase()))) {
+        if (++files > 1e5 || (bytes += info.size) > 256e6 || info.size > 16e6) {
+          throw new Error("Local documentation exceeds the migration input limit (100000 files, 256 MB total, 16 MB per file). Select a smaller source directory.");
+        }
+        copyFileSync(actual, target);
+      }
+    }
+  }
+  walk(root, snapshot);
+}
+
+// src/migrate/into.ts
+import { existsSync as existsSync3, lstatSync as lstatSync2, mkdtempSync, readFileSync as readFileSync2, readdirSync as readdirSync2, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join as join3, relative as relative2 } from "path";
+import { isDeepStrictEqual } from "util";
+function seedFiles(directory) {
+  if (!existsSync3(directory)) return [];
+  return readdirSync2(directory, { withFileTypes: true }).flatMap((entry) => {
+    if (entry.isSymbolicLink()) throw new Error("Starter seed content contains a symbolic link.");
+    const path = join3(directory, entry.name);
+    return entry.isDirectory() ? seedFiles(path) : entry.isFile() ? [path] : [];
+  });
+}
+function untouchedSeedFiles(projectDir, baselineDir, existing) {
+  const baseline = JSON.parse(readFileSync2(join3(baselineDir, "docs.json"), "utf8"));
+  if (!isDeepStrictEqual(existing.tabs, baseline.tabs)) return void 0;
+  const seed = /* @__PURE__ */ new Map();
+  for (const path of seedFiles(join3(baselineDir, "src/content"))) {
+    const name = relative2(baselineDir, path).replace(/\\/g, "/");
+    const target = assertMigrationDestination(projectDir, name);
+    if (!existsSync3(target) || !lstatSync2(target).isFile()) return void 0;
+    const current = readFileSync2(target);
+    if (!areStarterFileContentsEquivalent(name, current, readFileSync2(path))) return void 0;
+    seed.set(name, current);
+  }
+  return seed;
+}
+async function migrationExistingConfig(projectDir, existing, warnings) {
+  const preserved = { config: existing, seedFiles: /* @__PURE__ */ new Map(), preconditions: /* @__PURE__ */ new Map() };
+  if (!existing) return preserved;
+  const initialConfig = readFileSync2(assertMigrationDestination(projectDir, "docs.json"));
+  preserved.preconditions.set("docs.json", initialConfig);
+  const manifest = assertMigrationDestination(projectDir, "starter-release.json");
+  if (!existsSync3(manifest)) return preserved;
+  const temporary = mkdtempSync(join3(tmpdir(), "thally-migration-seed-"));
+  try {
+    const initialManifest = readFileSync2(manifest);
+    const { release } = await resolveStarterUpdateBase({ targetDir: projectDir });
+    await downloadStarter(temporary, void 0, release, { announce: false });
+    if (!initialManifest.equals(readFileSync2(manifest)) || !initialConfig.equals(readFileSync2(assertMigrationDestination(projectDir, "docs.json")))) throw new Error("The project changed during starter verification. Retry migration.");
+    const seed = untouchedSeedFiles(projectDir, temporary, existing);
+    if (seed) {
+      return {
+        config: { ...existing, tabs: [] },
+        seedFiles: seed,
+        preconditions: new Map([["starter-release.json", initialManifest], ["docs.json", initialConfig], ...seed]),
+        seedRelease: { id: release.id, sourceCommit: release.source.commitSha }
+      };
+    }
+  } catch (error) {
+    warnings.push({ code: "unsupported-config", message: `Starter navigation could not be verified and was preserved. ${error instanceof Error ? error.message : String(error)}` });
+  } finally {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+  return preserved;
+}
+
+// src/migrate/materialize.ts
+import { chmodSync, existsSync as existsSync4, lstatSync as lstatSync3, mkdirSync as mkdirSync2, mkdtempSync as mkdtempSync2, readFileSync as readFileSync3, renameSync, rmSync as rmSync2, writeFileSync } from "fs";
+import { dirname as dirname2, join as join4 } from "path";
+function migrationFileState(projectDir, path) {
+  const target = assertMigrationDestination(projectDir, path);
+  if (!existsSync4(target)) return {};
+  const entry = lstatSync3(target);
+  if (!entry.isFile()) throw new Error(`Migration destination must be a regular file: ${path}`);
+  return { content: readFileSync3(target), mode: entry.mode };
+}
+function same(left, right) {
+  return left === void 0 || right === void 0 ? left === right : left.equals(right);
+}
+function materializeMigration(projectDir, files, deletePaths, options = {}) {
+  const mutations = [...files.map((file) => ({ path: file.path, content: Buffer.from(file.content) })), ...deletePaths.map((path) => ({ path, content: void 0 }))];
+  if (new Set(mutations.map((mutation) => mutation.path)).size !== mutations.length) throw new Error("Migration contains conflicting destination mutations.");
+  const originals = new Map(mutations.map(({ path }) => [path, migrationFileState(projectDir, path)]));
+  const expectations = new Map([...originals].map(([path, state]) => [path, state.content]));
+  for (const [path, bytes] of options.preconditions ?? []) expectations.set(path, bytes);
+  const unchanged = (path, expected) => {
+    if (!same(migrationFileState(projectDir, path).content, expected)) throw new Error(`Migration destination changed after planning: ${path}. Retry without overwriting the owner edit.`);
+  };
+  const transaction = mkdtempSync2(join4(dirname2(projectDir), ".thally-migration-transaction-"));
+  const applied = [];
+  let retainBackup = false;
+  const temporaryPath = (area, path) => assertMigrationDestination(join4(transaction, area), path);
+  try {
+    for (const mutation of mutations) {
+      const original = originals.get(mutation.path);
+      if (original.content !== void 0) {
+        const backup = temporaryPath("backup", mutation.path);
+        mkdirSync2(dirname2(backup), { recursive: true });
+        writeFileSync(backup, original.content, { mode: original.mode });
+        if (original.mode !== void 0) chmodSync(backup, original.mode);
+      }
+      if (mutation.content !== void 0) {
+        const stage = temporaryPath("stage", mutation.path);
+        mkdirSync2(dirname2(stage), { recursive: true });
+        writeFileSync(stage, mutation.content, { mode: original.mode });
+        if (original.mode !== void 0) chmodSync(stage, original.mode);
+      }
+    }
+    for (const [path, expected] of expectations) unchanged(path, expected);
+    for (const [index, mutation] of mutations.entries()) {
+      unchanged(mutation.path, expectations.get(mutation.path));
+      const destination = assertMigrationDestination(projectDir, mutation.path);
+      if (mutation.content === void 0) rmSync2(destination, { force: true });
+      else {
+        mkdirSync2(dirname2(destination), { recursive: true });
+        renameSync(temporaryPath("stage", mutation.path), destination);
+      }
+      applied.push(mutation);
+      options.onMutationApplied?.(mutation.path, index);
+    }
+  } catch (error) {
+    const rollbackErrors = [];
+    for (const mutation of applied.reverse()) {
+      try {
+        unchanged(mutation.path, mutation.content);
+        const destination = assertMigrationDestination(projectDir, mutation.path);
+        const original = originals.get(mutation.path);
+        if (original.content === void 0) rmSync2(destination, { force: true });
+        else renameSync(temporaryPath("backup", mutation.path), destination);
+      } catch (failure) {
+        rollbackErrors.push(failure);
+      }
+    }
+    if (rollbackErrors.length) {
+      retainBackup = true;
+      throw new AggregateError([error, ...rollbackErrors], `Migration failed and some files changed during rollback. Original files are retained at ${transaction}/backup; preserve owner edits before recovery.`);
+    }
+    throw error;
+  } finally {
+    if (!retainBackup) rmSync2(transaction, { recursive: true, force: true });
+  }
+}
+
+// src/migrate/links.ts
+import { literalRoute, migrationApiRoutes, pageEntryRoutes } from "@thallylabs/migrate";
+var machineRoutes = /* @__PURE__ */ new Set(["/llms.txt", "/llms-full.txt", "/openapi.json", "/openapi.yaml", "/robots.txt", "/sitemap.xml", "/skill.md", "/AGENTS.md", "/auth.md"]);
+function reportUnresolvedMigrationLinks(bundle) {
+  const routes = new Set([...bundle.pages.flatMap((page) => [...pageEntryRoutes(page), `/${page.navigationId}`, `/${page.id}.md`, `/api/docs/${page.id}`, `/api/markdown/${page.id}`]), ...migrationApiRoutes(bundle)].map((route) => literalRoute(route) ?? route));
+  routes.add("/");
+  for (const redirect of bundle.docsConfig.redirects ?? []) routes.add(literalRoute(redirect.source) ?? redirect.source);
+  for (const asset of bundle.assets) if (!asset.projectRelative) routes.add(literalRoute(`/${asset.path}`) ?? `/${asset.path}`);
+  for (const page of bundle.pages) {
+    const unknown = /* @__PURE__ */ new Set();
+    let fence;
+    for (const line of page.body.split("\n")) {
+      const marker = line.match(/^\s{0,3}(`{3,}|~{3,})/);
+      if (marker) {
+        if (!fence) fence = marker[1];
+        else if (marker[1][0] === fence[0] && marker[1].length >= fence.length && !line.slice(marker[0].length).trim()) fence = void 0;
+        continue;
+      }
+      if (fence) continue;
+      const prose = line.replace(/`[^`]*`/g, "");
+      for (const match of prose.matchAll(/(?:\]\(|\bhref=["'])(\/(?!\/)[^\s)"']+)/g)) {
+        const target = match[1].split(/[?#]/, 1)[0].replace(/\/+$/, "") || "/";
+        if (!routes.has(literalRoute(target) ?? target) && !machineRoutes.has(target)) unknown.add(target);
+      }
+    }
+    if (unknown.size) bundle.warnings.push({ code: "unsupported-config", source: page.id, message: `Internal links have no imported destination and require review: ${[...unknown].slice(0, 20).join(", ")}${unknown.size > 20 ? `, and ${unknown.size - 20} more` : ""}.` });
+  }
+}
+
+// src/migrate/index.ts
+function projectPath(projectDir, candidate) {
+  return assertMigrationDestination(projectDir, candidate);
+}
+function quarantineIgnoreFile(projectDir) {
+  const ignorePath = projectPath(projectDir, ".gitignore");
+  const existing = existsSync5(ignorePath) ? readFileSync4(ignorePath, "utf8") : "";
+  const rules = existing.split(/\r?\n/).map((line) => line.trim()).filter((line) => /^!?\/?migration-quarantine(?:\/(?:\*\*?)?)?$/.test(line));
+  if (rules.length > 0 && !rules[rules.length - 1].startsWith("!")) return;
+  const separator = existing === "" || existing.endsWith("\n") ? "" : "\n";
+  return { path: ".gitignore", content: `${existing}${separator}
+# Access-restricted pages withheld by migration: local only, never commit or deploy
+/migration-quarantine/
+` };
+}
+function readExistingConfig(projectDir) {
+  const configPath = projectPath(projectDir, "docs.json");
+  if (!existsSync5(configPath)) return void 0;
+  return JSON.parse(readFileSync4(configPath, "utf8"));
+}
+function resetFreshMigrationContent(projectDir) {
+  const contentDirectory = projectPath(projectDir, "src/content");
+  rmSync3(contentDirectory, { recursive: true, force: true });
+  mkdirSync3(contentDirectory, { recursive: true });
+  for (const sampleSpec of ["openapi.yaml", "openapi.json"]) {
+    rmSync3(projectPath(projectDir, sampleSpec), { force: true });
+  }
+}
+async function fetchSourceRefs(mappings, warnings) {
+  const imports = [];
+  for (const mapping of mappings) {
+    const root = mkdtempSync3(join5(tmpdir2(), "thally-source-ref-"));
+    try {
+      const source = parseGitHubRepositoryUrl(`https://github.com/${mapping.repo}`);
+      const tooLarge = await sourceRefOversizeReason(mapping.repo);
+      if (tooLarge) throw new Error(tooLarge);
+      const cloneDir = join5(root, "repository");
+      await cloneGitHubRepository(source, cloneDir, warnings, { skipSubmodules: true });
+      imports.push(importSourceRef(mapping, cloneDir));
+    } catch (error) {
+      warnings.push({ code: "fetch-failed", message: `sourceRef ${mapping.repo} was not imported: ${error instanceof Error ? error.message : String(error)}` });
+    } finally {
+      rmSync3(root, { recursive: true, force: true });
+    }
+  }
+  return imports;
+}
+async function discoverMigration(options) {
+  if (options.sourceDirectory) {
+    assertSeparateMigrationDirectories(options.sourceDirectory, options.projectDir);
+    const temporaryRoot2 = mkdtempSync3(join5(tmpdir2(), "thally-local-migrate-"));
+    try {
+      const snapshot = join5(temporaryRoot2, "source");
+      snapshotLocalMigration(options.sourceDirectory, snapshot, options.docsDir);
+      const bundle = await terminal.step("Converting local documentation", () => convertRepository({
+        repositoryDir: snapshot,
+        sourceUrl: "https://local.invalid/selected-directory",
+        // Namespace components stably without exposing the private checkout path.
+        componentNamespace: `local-${createHash("sha256").update(realpathSync2(options.sourceDirectory)).digest("hex").slice(0, 16)}`,
+        docsDir: options.docsDir,
+        platform: options.platform
+      }), "Local documentation converted");
+      return hydrateRemoteApiSpecs(bundle, options.fetcher);
+    } finally {
+      rmSync3(temporaryRoot2, { recursive: true, force: true });
+    }
+  }
+  const url = new URL(options.sourceUrl);
+  if (url.hostname.toLowerCase() !== "github.com") {
+    if (options.sourceRefs?.length) terminal.warn("--source-ref applies only to GitHub repository sources and was ignored.");
+    return terminal.step("Discovering public documentation", () => {
+      const discovery = {
+        sourceUrl: options.sourceUrl,
+        platform: options.platform,
+        maxPages: options.maxPages,
+        openapiUrl: options.openapiUrl
+      };
+      if (options.urlMigration) return runUrlMigration({ ...discovery, fetcher: options.fetcher, ...options.urlMigration }).then((run) => options.openapiUrl ? hydrateUrlOpenApi(run.bundle, options.openapiUrl, options.fetcher) : run.bundle);
+      return options.fetcher ? migrateUrl({ ...discovery, fetcher: options.fetcher }) : discoverUrl(discovery);
+    }, "Public documentation discovered");
+  }
+  const source = parseGitHubRepositoryUrl(options.sourceUrl);
+  if (options.branch) source.branch = options.branch;
+  const temporaryRoot = mkdtempSync3(join5(tmpdir2(), "thally-migrate-"));
+  const cloneDir = join5(temporaryRoot, "repository");
+  try {
+    const cloneWarnings = [];
+    await terminal.step(`Cloning ${source.owner}/${source.repo}`, () => cloneGitHubRepository(source, cloneDir, cloneWarnings), "Source repository cloned");
+    const sourceRefs = options.sourceRefs?.length ? await terminal.step("Importing sourceRef repositories", () => fetchSourceRefs(options.sourceRefs ?? [], cloneWarnings), "sourceRef repositories imported") : [];
+    const bundle = await terminal.step("Converting repository documentation", () => convertRepository({
+      sourceRefs,
+      repositoryDir: cloneDir,
+      sourceUrl: options.sourceUrl,
+      docsDir: options.docsDir ?? (source.docsDir || void 0),
+      platform: options.platform
+    }), "Repository documentation converted");
+    const hydrated = await terminal.step("Loading remote API specifications", () => hydrateRemoteApiSpecs(bundle, options.fetcher), "Remote API specifications loaded");
+    return cloneWarnings.length > 0 ? { ...hydrated, warnings: [...cloneWarnings, ...hydrated.warnings] } : hydrated;
+  } finally {
+    rmSync3(temporaryRoot, { recursive: true, force: true });
+  }
+}
+function publicSpecWarning(projectDir, bundle) {
+  const { specs, skipped } = findPublicSpecs(projectDir);
+  if (specs.length === 0 && skipped.length === 0) return null;
+  const migrated = new Set(bundle.assets.filter((asset) => asset.projectRelative).map((asset) => basename(asset.path)));
+  const lines = [
+    ...specs.map((spec) => `${spec.path}${migrated.has(basename(spec.path)) ? " (same file name as a migrated spec)" : ""}${spec.hasHiddenOperations ? " (contains x-excluded/x-hidden operations)" : ""}${shadowNote(spec.urlPath) ? ` (answers /${spec.urlPath} in place of the filtered specification)` : ""}`),
+    ...skipped.map((path) => `${path} (too large to inspect)`)
+  ];
+  return {
+    code: "unsupported-config",
+    message: `Existing OpenAPI files under public/ are served publicly as-is: ${lines.join("; ")}. Migrated specs are written to openapi/, and re-running migration does not remove old copies from public/. Delete any old copy manually (nothing was deleted), or its hidden operations stay downloadable.`
+  };
+}
+async function migrateDocs(options) {
+  const projectDir = resolve2(options.projectDir);
+  assertMigrationDestination(projectDir);
+  const bundle = await discoverMigration(options);
+  reportUnresolvedMigrationLinks(bundle);
+  if (!options.into) {
+    terminal.detail("Project", projectDir);
+    await scaffold({
+      projectDir,
+      projectName: options.projectName ?? bundle.site?.name ?? "My Docs",
+      description: bundle.site?.description ?? `Documentation migrated from ${options.sourceDirectory ? basename(resolve2(options.sourceDirectory)) : new URL(options.sourceUrl).hostname}`,
+      brandPreset: "primary",
+      // Source provenance is not the destination repository. Migrated pages
+      // live at new paths, so source URLs cannot power edit/issue actions.
+      repoUrl: "",
+      doInstall: false,
+      colors: bundle.site?.colors
+    });
+    resetFreshMigrationContent(projectDir);
+    pruneMissingSiteLinks(projectDir, new Set(bundle.pages.map((page) => page.id)));
+  } else if (!existsSync5(projectDir)) {
+    throw new Error(`Project directory "${projectDir}" does not exist. Use without --into to scaffold a new one.`);
+  }
+  if (!options.into) {
+    const starterConfig = readExistingConfig(projectDir);
+    if (starterConfig?.markdown) bundle.docsConfig.markdown ??= starterConfig.markdown;
+    if (!bundle.docsConfig.navbar?.primary) {
+      bundle.docsConfig.navbar = { ...bundle.docsConfig.navbar, primary: null };
+    }
+    bundle.docsConfig.i18n ??= { defaultLocale: "en", locales: [{ code: "en", label: "English" }] };
+  }
+  if (options.into) {
+    const stale = publicSpecWarning(projectDir, bundle);
+    if (stale) bundle.warnings.unshift(stale);
+  }
+  const existingPlan = options.into ? await migrationExistingConfig(projectDir, readExistingConfig(projectDir), bundle.warnings) : void 0;
+  const registryPath = projectPath(projectDir, "src/mdx/custom-components.tsx");
+  const registryBytes = existsSync5(registryPath) ? readFileSync4(registryPath) : void 0;
+  existingPlan?.preconditions.set("src/mdx/custom-components.tsx", registryBytes);
+  const rendered = await terminal.step("Rendering documentation", async () => renderFiles(bundle, {
+    existingConfig: existingPlan?.config,
+    existingComponentRegistry: registryBytes?.toString("utf8")
+  }), "Documentation rendered");
+  const conflicts = [];
+  const writePreconditions = new Map(existingPlan?.preconditions);
+  const writable = rendered.filter((file) => {
+    const path = projectPath(projectDir, file.path);
+    const current = existsSync5(path) ? readFileSync4(path) : void 0;
+    if (!writePreconditions.has(file.path)) writePreconditions.set(file.path, current);
+    if (!options.into || file.path === "docs.json" || file.path === "src/mdx/custom-components.tsx" || !current) return true;
+    if (current.equals(Buffer.from(file.content)) || existingPlan?.seedFiles.get(file.path)?.equals(current)) return true;
+    conflicts.push(file.path);
+    return false;
+  });
+  const conflictPaths = new Set(conflicts);
+  const pagesWritten = bundle.pages.filter((page) => !conflictPaths.has(`src/content/${page.id}.mdx`)).length;
+  const assetsWritten = bundle.assets.filter((asset) => !conflictPaths.has(asset.projectRelative ? asset.path : `public/${asset.path}`)).length;
+  if (conflicts.length) bundle.warnings.push({ code: "unsupported-config", message: `Existing authored files were preserved because imported content conflicts: ${conflicts.join(", ")}. Resolve these files before publishing.` });
+  const incomingPaths = new Set(rendered.map((file) => file.path));
+  const removedSeedPaths = [...existingPlan?.seedFiles.keys() ?? []].filter((path) => !incomingPaths.has(path));
+  const quarantineIgnore = bundle.quarantinedFiles?.length ? quarantineIgnoreFile(projectDir) : void 0;
+  if (quarantineIgnore) {
+    writable.push(quarantineIgnore);
+    const ignorePath = projectPath(projectDir, ".gitignore");
+    writePreconditions.set(".gitignore", existsSync5(ignorePath) ? readFileSync4(ignorePath) : void 0);
+  }
+  await terminal.step("Writing documentation", async () => {
+    projectPath(projectDir, "migration-report.json");
+    materializeMigration(projectDir, writable, removedSeedPaths, { preconditions: writePreconditions });
+  }, `Imported ${pagesWritten} pages and ${assetsWritten} assets from ${bundle.platform}`);
+  const format = (warning) => `${warning.message}${warning.source ? ` (${warning.source})` : ""}`;
+  for (const warning of bundle.warnings.filter((item) => item.code !== "gated-page")) terminal.warn(format(warning));
+  const gatedWarnings = bundle.warnings.filter((item) => item.code === "gated-page");
+  if (gatedWarnings.length > 0) {
+    terminal.warn("ACCESS-RESTRICTED CONTENT \u2014 review before publishing");
+    for (const warning of gatedWarnings) terminal.warn(format(warning));
+    if (bundle.droppedGatedPages) {
+      terminal.warn(`${bundle.droppedGatedPages} access-restricted page(s) were dropped by the file limit: not published and not saved under migration-quarantine/; recover them from the source repository.`);
+    }
+    if (bundle.quarantinedFiles?.length || gatedWarnings.some((warning) => !/dashboard access settings/i.test(warning.message))) {
+      terminal.warn("Before publishing, review migration-quarantine/assets/ and the dashboard access settings of the source site.");
+    }
+  }
+  let installationFailed = false;
+  if (!options.skipValidation) terminal.info("Migration validation runs project code locally, including imported MDX and components.");
+  if (!options.into && !options.skipValidation) {
+    try {
+      await installDeps(projectDir);
+    } catch (error) {
+      const exitCode = error.exitCode;
+      if (exitCode === 130 || exitCode === 143) throw error;
+      installationFailed = true;
+    }
+  }
+  terminal.info("Validating imported documentation...");
+  const validation = await validateMigration(projectDir, options.skipValidation, installationFailed);
+  if (conflicts.length) {
+    validation.content = "failed";
+    validation.messages.push(`${conflicts.length} existing file(s) conflict with imported content; owner files were preserved.`);
+  }
+  if (bundle.urlMigrationValidation && bundle.urlMigrationValidation.status !== "passed") {
+    validation.content = "failed";
+    validation.messages.push(`Source evidence validation is ${bundle.urlMigrationValidation.status}; ${bundle.urlMigrationValidation.issues.length} issue(s) require review.`);
+  }
+  const quarantinedPages = (bundle.quarantinedFiles ?? []).filter((file) => /\.mdx?$/i.test(file.path)).length;
+  const reportPath = projectPath(projectDir, "migration-report.json");
+  writeFileSync2(reportPath, `${JSON.stringify({
+    version: 1,
+    sourceUrl: options.sourceDirectory ? "local-directory" : `${new URL(options.sourceUrl).origin}${new URL(options.sourceUrl).pathname}`,
+    platform: bundle.platform,
+    pages: bundle.pages.length,
+    assets: bundle.assets.length,
+    pagesWritten,
+    assetsWritten,
+    components: bundle.componentFiles?.length ?? 0,
+    sourceRefs: bundle.sourceRefs ?? [],
+    quarantined: quarantinedPages,
+    quarantinedAssets: (bundle.quarantinedFiles?.length ?? 0) - quarantinedPages,
+    droppedGatedPages: bundle.droppedGatedPages ?? 0,
+    warnings: bundle.warnings,
+    conflicts,
+    removedSeedPaths,
+    ...existingPlan?.seedRelease ? { replacedSeedRelease: existingPlan.seedRelease } : {},
+    validation,
+    ...bundle.urlMigrationValidation ? { sourceValidation: bundle.urlMigrationValidation } : {}
+  }, null, 2)}
+`);
+  for (const message of validation.messages) terminal.warn(message);
+  terminal.detail("Migration report", reportPath);
+  if (validation.content === "passed" && validation.build === "passed") {
+    terminal.success(`Content and production build passed.${bundle.warnings.length ? " Review the migration warnings for compatibility limitations." : ""}`);
+  } else {
+    terminal.warn("Import retained, but validation is incomplete. Do not publish without reviewing the report.");
+  }
+  if (!options.into) await initGit(projectDir);
+  return {
+    pagesWritten,
+    assetsWritten,
+    projectDir,
+    platform: bundle.platform,
+    warnings: bundle.warnings,
+    validation,
+    reportPath
+  };
+}
+
+export {
+  migrateDocs
+};