create-thally-docs 0.10.30 → 0.10.32

package/README.md

@@ -63,6 +63,33 @@ projected into Thally. A live Mintlify URL uses the structured configuration
 embedded by Mintlify when it is available, with bounded same-site crawling as a
 fallback.
 
+Repository-local JSX/TSX components and supported static dependencies are copied
+into the customer-owned MDX registry. Simple interactive HTML blocks are moved
+into client components, and locale/root routing is normalized. Unsupported
+customizations remain visible as warnings rather than being silently dropped.
+
+After importing, the CLI runs static content checks and writes
+`migration-report.json`. A failed check or build returns a nonzero exit status;
+the imported files remain available for inspection. Warnings may include
+pre-existing source problems and compatibility limitations even when a build
+passes. Review them before publishing. Use `--skip-validation` for an explicit
+import-only run; its report is marked unverified. An existing `--into` project
+without a build script is also reported as unverified.
+
+Dependency installation and production builds require explicit authorization:
+answer the interactive trust prompt or pass `--trust-source` for a source you
+have reviewed. `--yes` does not grant that authorization. Without it, files are
+imported and statically checked, but the build is skipped and the report stays
+unverified. MCP callers use `trustSource: true` only after the user authorizes
+execution. `--skip-validation` also skips installation, even with trust granted.
+Imported MDX and JSX/TSX are executable code; static migration analysis is not a
+sandbox. Review the imported files before installing or building them manually.
+
+A fresh migration leaves the destination repository unset. After creating the
+new repository, set `site.repoUrl` in `src/data/site.ts` to its root GitHub URL
+to enable edit and issue links. The source location remains in the migration
+report; it is not used as the destination for reader feedback.
+
 Prefer a single binary? Install [`@thallylabs/cli`](https://www.npmjs.com/package/@thallylabs/cli)
 and use `thally init`, which delegates here.
 

package/dist/{chunk-4RPHM4NA.js → chunk-74SGZLEY.js}

@@ -5,7 +5,7 @@ import {
 } from "./chunk-ORUAMPNF.js";
 import {
   downloadStarter
-} from "./chunk-XAUCGJ6B.js";
+} from "./chunk-FLSOVTVO.js";
 
 // src/scaffold.ts
 import { existsSync, mkdirSync, readdirSync } from "fs";

package/dist/chunk-E5URHAYU.js

@@ -0,0 +1,611 @@
+#!/usr/bin/env node
+import {
+  initGit,
+  installDeps,
+  readDocsJson,
+  scaffold,
+  writeDocsJson
+} from "./chunk-74SGZLEY.js";
+
+// src/migrate/index.ts
+import { existsSync as existsSync3, mkdirSync, mkdtempSync, readFileSync as readFileSync3, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { dirname, isAbsolute, join as join3, relative as relative2, resolve, sep } from "path";
+import {
+  cloneGitHubRepository,
+  migrateRepository,
+  migrateUrl,
+  parseGitHubRepositoryUrl,
+  renderMigrationFiles
+} from "@thallylabs/migrate";
+
+// src/migrate/validate.ts
+import { spawnSync } from "child_process";
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join2 } from "path";
+
+// src/check.ts
+import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import { join, extname, relative } from "path";
+import { execFileSync } from "child_process";
+
+// src/frontmatter.ts
+import { parse as parseYaml } from "yaml";
+function parseFrontmatter(raw) {
+  const source = raw.charCodeAt(0) === 65279 ? raw.slice(1) : raw;
+  const opening = /^---([^\r\n]*)\r?\n/.exec(source);
+  if (!opening || opening[1].startsWith("-")) return { content: source, data: {} };
+  const language = opening[1].trim().toLowerCase();
+  const remainder = source.slice(opening[0].length);
+  const closing = /^---[ \t]*\r?$/m.exec(remainder);
+  const matter = closing ? remainder.slice(0, closing.index) : remainder;
+  let content = closing ? remainder.slice(closing.index + closing[0].length) : "";
+  if (content.startsWith("\r\n")) content = content.slice(2);
+  else if (content.startsWith("\n")) content = content.slice(1);
+  if (matter.trim() === "" || !["", "yaml", "yml"].includes(language)) {
+    return { content, data: {} };
+  }
+  const parsed = parseYaml(matter);
+  return {
+    content,
+    data: parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {}
+  };
+}
+
+// src/check.ts
+import { parse as parseYaml2 } from "yaml";
+function gitLocal(projectDir, args) {
+  try {
+    const out = execFileSync("git", args, { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return { ok: true, out: out.trim() };
+  } catch {
+    return { ok: false, out: "" };
+  }
+}
+function checkDrift(projectDir, file, data, issues) {
+  const sources = data.sources;
+  const verifiedCommit = data.verifiedCommit;
+  if (!Array.isArray(sources) || sources.length === 0 || typeof verifiedCommit !== "string" || !verifiedCommit.trim()) {
+    return;
+  }
+  const commit = verifiedCommit.trim();
+  if (!gitLocal(projectDir, ["cat-file", "-e", `${commit}^{commit}`]).ok) {
+    issues.push({
+      severity: "warning",
+      message: `Cannot verify freshness: verifiedCommit "${commit.slice(0, 8)}" is not in git history \u2014 run with a full clone (fetch-depth: 0).`,
+      file
+    });
+    return;
+  }
+  for (const src of sources) {
+    if (typeof src !== "string" || !src.trim()) continue;
+    const colon = src.indexOf(":");
+    let filePath = src;
+    if (colon > 0) {
+      const alias = src.slice(0, colon);
+      if (alias !== "." && alias !== "self") {
+        issues.push({
+          severity: "warning",
+          message: `Cross-repo source "${src}" \u2014 drift check skipped (needs the referenced repo; see multi-repo setup).`,
+          file
+        });
+        continue;
+      }
+      filePath = src.slice(colon + 1);
+    }
+    filePath = filePath.replace(/^\.\//, "").replace(/#.*$/, "");
+    const changed = gitLocal(projectDir, ["log", "--format=%H", `${commit}..HEAD`, "--", filePath]).out;
+    if (changed) {
+      const n = changed.split("\n").filter(Boolean).length;
+      issues.push({
+        severity: "warning",
+        message: `Drift: source "${src}" changed in ${n} commit(s) since it was verified \u2014 this page may be stale.`,
+        file
+      });
+    }
+  }
+}
+function collectNavPageIds(groups, seen, duplicates) {
+  for (const page of groups) {
+    if (typeof page === "string") {
+      if (seen.has(page)) duplicates.add(page);
+      else seen.add(page);
+    } else if (page.pages) {
+      collectNavPageIds(page.pages, seen, duplicates);
+    }
+  }
+}
+function scanMdx(dir, results) {
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const fullPath = join(dir, entry);
+    try {
+      const stat = statSync(fullPath);
+      if (stat.isDirectory()) scanMdx(fullPath, results);
+      else if (extname(entry).toLowerCase() === ".mdx") results.push(fullPath);
+    } catch {
+    }
+  }
+}
+function addOrphanToNav(projectDir, pageId) {
+  const config = readDocsJson(projectDir);
+  const tab = config.tabs.find((candidate) => !candidate.href && !candidate.api && (candidate.pages?.length || candidate.groups?.length));
+  if (!tab) return;
+  if (tab.pages) {
+    if (!tab.pages.includes(pageId)) {
+      tab.pages.push(pageId);
+      writeDocsJson(projectDir, config);
+    }
+    return;
+  }
+  if (!tab.groups) return;
+  const lastGroup = tab.groups[tab.groups.length - 1];
+  const existing = lastGroup.pages.filter((p) => typeof p === "string");
+  if (!existing.includes(pageId)) {
+    lastGroup.pages.push(pageId);
+    writeDocsJson(projectDir, config);
+  }
+}
+function slugify(text) {
+  return text.toLowerCase().trim().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-");
+}
+function extractHeadingAnchors(content) {
+  const anchors = /* @__PURE__ */ new Set();
+  for (const line of content.split("\n")) {
+    const m = /^#{1,6}\s+(.+?)\s*#*\s*$/.exec(line);
+    if (m) anchors.add(slugify(m[1]));
+  }
+  return anchors;
+}
+function extractLinks(content) {
+  const links = [];
+  const lines = content.split("\n");
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\s*(```|~~~)/.test(lines[i])) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const line = lines[i].replace(/`[^`]*`/g, "");
+    for (const m of line.matchAll(/\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g)) {
+      links.push({ target: m[1], line: i + 1 });
+    }
+    for (const m of line.matchAll(/href=["']([^"']+)["']/g)) {
+      links.push({ target: m[1], line: i + 1 });
+    }
+  }
+  return links;
+}
+function localizedPage(pageId, secondaryLocales) {
+  const [first, ...rest] = pageId.split("/");
+  if (secondaryLocales.has(first) && rest.length > 0) {
+    return { navPageId: rest.join("/"), locale: first };
+  }
+  return { navPageId: pageId };
+}
+function pageIdToPath(pageId, secondaryLocales) {
+  const { navPageId, locale } = localizedPage(pageId, secondaryLocales);
+  const basePath = navPageId === "introduction" ? "/" : `/${navPageId}`;
+  return locale ? `/${locale}${basePath === "/" ? "" : basePath}` : basePath;
+}
+function resolveLink(target, redirects) {
+  let current = target;
+  let anchor;
+  const seen = /* @__PURE__ */ new Set();
+  while (true) {
+    if (/^(?:https?:)?\/\//i.test(current)) return { path: current, external: true };
+    const hash = current.indexOf("#");
+    if (hash >= 0) anchor = current.slice(hash + 1);
+    const beforeHash = hash >= 0 ? current.slice(0, hash) : current;
+    const path = beforeHash.split("?", 1)[0].replace(/\/$/, "") || "/";
+    if (seen.has(path)) return { path, anchor, cycle: true };
+    seen.add(path);
+    const redirected = redirects.get(path);
+    if (!redirected) return { path, anchor };
+    current = redirected;
+  }
+}
+function validateOpenApi(projectDir, source, issues) {
+  const specPath = source.startsWith("/") ? join(projectDir, "public", source.slice(1)) : join(projectDir, source);
+  if (!existsSync(specPath)) {
+    issues.push({ severity: "error", message: `API reference points at "${source}" but the file does not exist`, file: source });
+    return;
+  }
+  let spec;
+  try {
+    const raw = readFileSync(specPath, "utf8");
+    spec = source.endsWith(".json") ? JSON.parse(raw) : parseYaml2(raw);
+  } catch (err) {
+    issues.push({ severity: "error", message: `OpenAPI spec is not valid ${source.endsWith(".json") ? "JSON" : "YAML"}: ${err.message}`, file: source });
+    return;
+  }
+  const s = spec;
+  if (typeof s?.openapi !== "string" && typeof s?.swagger !== "string") {
+    issues.push({ severity: "error", message: 'OpenAPI spec is missing the "openapi" (or "swagger") version field', file: source });
+  }
+  if (typeof s?.info !== "object" || s.info === null) {
+    issues.push({ severity: "error", message: 'OpenAPI spec is missing the "info" object', file: source });
+  }
+  const paths = s?.paths;
+  if (typeof paths !== "object" || paths === null) {
+    issues.push({ severity: "error", message: 'OpenAPI spec is missing the "paths" object', file: source });
+  } else {
+    const methods = /* @__PURE__ */ new Set(["get", "post", "put", "patch", "delete", "options", "head", "trace"]);
+    for (const [p, ops] of Object.entries(paths)) {
+      if (typeof ops !== "object" || ops === null) {
+        issues.push({ severity: "error", message: `OpenAPI path "${p}" is not an object`, file: source });
+        continue;
+      }
+      const hasOp = Object.keys(ops).some((k) => methods.has(k.toLowerCase()));
+      if (!hasOp) {
+        issues.push({ severity: "warning", message: `OpenAPI path "${p}" has no operations`, file: source });
+      }
+    }
+  }
+}
+async function runCheck(projectDir, options) {
+  const { fix, ci } = options;
+  if (!existsSync(join(projectDir, "docs.json"))) {
+    console.error(`
+  \u274C Not a Thally project: docs.json not found in ${projectDir}
+`);
+    return 1;
+  }
+  const contentDir = join(projectDir, "src", "content");
+  const issues = [];
+  const config = readDocsJson(projectDir);
+  const secondaryLocales = new Set(
+    (config.i18n?.locales ?? []).map((locale) => locale.code).filter((code) => code !== config.i18n?.defaultLocale)
+  );
+  const generatedApiPaths = /* @__PURE__ */ new Set([
+    "/api",
+    ...Array.from(secondaryLocales, (locale) => `/${locale}/api`)
+  ]);
+  const redirectDestinations = new Map(
+    (config.redirects ?? []).map((redirect) => [
+      redirect.source.replace(/\/$/, "") || "/",
+      redirect.destination
+    ])
+  );
+  const navPageIds = /* @__PURE__ */ new Set();
+  const duplicates = /* @__PURE__ */ new Set();
+  for (const tab of config.tabs) {
+    const hasNavigationNodes = Boolean(tab.pages?.length || tab.groups?.length);
+    if (tab.href && !hasNavigationNodes) {
+      if (tab.href.startsWith("/")) navPageIds.add(tab.href.slice(1) || "introduction");
+      continue;
+    }
+    if (tab.api && tab.api.navigation !== false && !hasNavigationNodes) continue;
+    if (!hasNavigationNodes) {
+      issues.push({ severity: "error", message: `Tab "${tab.tab}" has no groups and no href \u2014 it will render empty` });
+      continue;
+    }
+    collectNavPageIds(tab.pages ?? [], navPageIds, duplicates);
+    collectNavPageIds(tab.groups ?? [], navPageIds, duplicates);
+  }
+  for (const dup of duplicates) {
+    issues.push({ severity: "warning", message: `[duplicate] "${dup}" appears more than once in docs.json` });
+  }
+  for (const pageId of navPageIds) {
+    const candidates = [join(contentDir, `${pageId}.mdx`), join(contentDir, `${pageId}/index.mdx`)];
+    if (!candidates.some((c) => existsSync(c))) {
+      issues.push({ severity: "error", message: `"${pageId}" is in docs.json but has no MDX file`, file: `src/content/${pageId}.mdx` });
+    }
+  }
+  const allFiles = [];
+  if (existsSync(contentDir)) scanMdx(contentDir, allFiles);
+  const fixedOrphans = [];
+  const validPaths = /* @__PURE__ */ new Set(["/"]);
+  const anchorsByPath = /* @__PURE__ */ new Map();
+  const linksByFile = [];
+  for (const filePath of allFiles) {
+    const rel = filePath.slice(contentDir.length + 1).replace(/\.mdx$/, "").replace(/\\/g, "/");
+    const pageId = rel.endsWith("/index") ? rel.slice(0, -6) : rel;
+    const { navPageId } = localizedPage(pageId, secondaryLocales);
+    if (!navPageIds.has(navPageId)) {
+      if (fix) {
+        addOrphanToNav(projectDir, pageId);
+        fixedOrphans.push(pageId);
+      } else {
+        issues.push({ severity: "warning", message: `"${pageId}" is not in docs.json nav (orphan)`, file: relative(projectDir, filePath) });
+      }
+    }
+    let data = {};
+    let content = "";
+    let lineOffset = 0;
+    try {
+      const raw = readFileSync(filePath, "utf8");
+      const parsed = parseFrontmatter(raw);
+      data = parsed.data;
+      content = parsed.content;
+      lineOffset = raw.slice(0, raw.indexOf(content)).split("\n").length - 1;
+    } catch {
+      issues.push({ severity: "error", message: `Could not parse frontmatter`, file: relative(projectDir, filePath) });
+      continue;
+    }
+    const rel2 = relative(projectDir, filePath);
+    if (!data.title) issues.push({ severity: "warning", message: `Missing "title" in frontmatter`, file: rel2 });
+    if (!data.description) issues.push({ severity: "warning", message: `Missing "description" in frontmatter`, file: rel2 });
+    if (typeof data.openapi !== "string" && content.trim().length < 50) {
+      issues.push({ severity: "warning", message: `Very short body (${content.trim().length} chars) \u2014 page may be empty`, file: rel2 });
+    }
+    if (options.drift) checkDrift(projectDir, rel2, data, issues);
+    const path = pageIdToPath(pageId, secondaryLocales);
+    const anchors = extractHeadingAnchors(content);
+    validPaths.add(path);
+    validPaths.add(`/${pageId}`);
+    anchorsByPath.set(path, anchors);
+    anchorsByPath.set(`/${pageId}`, anchors);
+    linksByFile.push({ file: rel2, path, anchors, links: extractLinks(content), offset: lineOffset });
+  }
+  for (const [path, anchors] of [...anchorsByPath]) {
+    if (secondaryLocales.has(path.split("/")[1])) continue;
+    for (const locale of secondaryLocales) {
+      const localized = `/${locale}${path === "/" ? "" : path}`;
+      if (validPaths.has(localized)) continue;
+      validPaths.add(localized);
+      anchorsByPath.set(localized, anchors);
+    }
+  }
+  for (const { file, anchors, links, offset } of linksByFile) {
+    for (const { target, line: contentLine } of links) {
+      const line = contentLine + offset;
+      if (/^(https?:|mailto:|tel:)/i.test(target)) continue;
+      if (target.startsWith("#")) {
+        const anchor2 = target.slice(1);
+        if (anchor2 && !anchors.has(anchor2)) {
+          issues.push({ severity: "warning", message: `Broken anchor: "${target}" not found on this page`, file, line });
+        }
+        continue;
+      }
+      if (!target.startsWith("/")) continue;
+      const { path, anchor, cycle, external } = resolveLink(target, redirectDestinations);
+      if (external) continue;
+      const isGeneratedApiPath = Array.from(generatedApiPaths).some(
+        (prefix) => path === prefix || path.startsWith(`${prefix}/`)
+      );
+      if (!cycle && (isGeneratedApiPath || path.startsWith("/_next") || /\.[a-z0-9]+$/i.test(path))) continue;
+      if (cycle || !validPaths.has(path)) {
+        issues.push({ severity: "error", message: `Broken link: "${target}" \u2014 no page at "${path}"`, file, line });
+      } else if (anchor && !anchorsByPath.get(path)?.has(anchor)) {
+        issues.push({ severity: "warning", message: `Broken anchor: "${target}" \u2014 no heading "#${anchor}" on that page`, file, line });
+      }
+    }
+  }
+  for (const tab of config.tabs) {
+    if (tab.api?.source) validateOpenApi(projectDir, tab.api.source, issues);
+  }
+  const errors = issues.filter((i) => i.severity === "error");
+  options.onIssues?.(issues);
+  const warnings = issues.filter((i) => i.severity === "warning");
+  if (ci) {
+    for (const issue of issues) {
+      const loc = issue.file ? `file=${issue.file}${issue.line ? `,line=${issue.line}` : ""}` : "";
+      console.log(`::${issue.severity} ${loc}::${issue.message}`);
+    }
+    console.log(`
+thally check: ${errors.length} error(s), ${warnings.length} warning(s)`);
+    return errors.length > 0 ? 1 : 0;
+  }
+  console.log(`
+  Linting ${projectDir}...
+`);
+  if (errors.length === 0 && warnings.length === 0 && fixedOrphans.length === 0) {
+    console.log("  \u2705 No issues found.\n");
+    return 0;
+  }
+  console.log(`  \u274C ${errors.length} error${errors.length !== 1 ? "s" : ""}, \u26A0\uFE0F  ${warnings.length} warning${warnings.length !== 1 ? "s" : ""}
+`);
+  if (errors.length > 0) {
+    console.log("  ERRORS:");
+    for (const issue of errors) {
+      console.log(`    ${issue.message}`);
+      if (issue.file) console.log(`    \u2192 ${issue.file}${issue.line ? `:${issue.line}` : ""}`);
+    }
+    console.log("");
+  }
+  if (warnings.length > 0) {
+    console.log("  WARNINGS:");
+    for (const issue of warnings) {
+      console.log(`    ${issue.message}`);
+      if (issue.file) console.log(`    \u2192 ${issue.file}${issue.line ? `:${issue.line}` : ""}`);
+    }
+    console.log("");
+  }
+  if (fixedOrphans.length > 0) {
+    console.log(`  \u2705 Auto-fixed ${fixedOrphans.length} orphan page${fixedOrphans.length > 1 ? "s" : ""} (added to nav):`);
+    for (const p of fixedOrphans) console.log(`    + ${p}`);
+    console.log("");
+  }
+  if (!fix && warnings.some((w) => w.message.includes("orphan"))) {
+    console.log("  Tip: run with --fix to auto-add orphan pages to navigation.\n");
+  }
+  return errors.length > 0 ? 1 : 0;
+}
+
+// src/migrate/validate.ts
+async function validateMigration(projectDir, skip = false, trustSource = 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 {
+    result.content = await runCheck(projectDir, { fix: false, ci: true, onIssues: (issues) => {
+      result.diagnostics = issues;
+    } }) === 0 ? "passed" : "failed";
+    if (result.content === "failed") result.messages.push("Content validation failed. Review the check output; source links are not silently rewritten.");
+  } catch (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;
+  }
+  if (trustSource !== true) {
+    result.messages.push("Production build skipped: source execution was not authorized. Review the imported code before running npm install and npm run build, or explicitly authorize a trusted migration with --trust-source.");
+    return result;
+  }
+  const packagePath = join2(projectDir, "package.json");
+  try {
+    const manifest = existsSync2(packagePath) ? JSON.parse(readFileSync2(packagePath, "utf8")) : void 0;
+    if (!manifest?.scripts?.build) {
+      result.messages.push("No build script is available; production rendering is not verified.");
+      return result;
+    }
+    const build = spawnSync(process.platform === "win32" ? "npm.cmd" : "npm", ["run", "build"], {
+      cwd: projectDir,
+      stdio: "inherit",
+      timeout: 10 * 60 * 1e3
+    });
+    result.build = build.status === 0 && !build.error ? "passed" : "failed";
+    if (result.build === "failed") result.messages.push("Production build failed. Review the build output before publishing.");
+  } catch (error) {
+    result.build = "failed";
+    result.messages.push(`Production build failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return result;
+}
+
+// src/migrate/index.ts
+function projectPath(projectDir, candidate) {
+  const target = resolve(projectDir, candidate);
+  const fromRoot = relative2(resolve(projectDir), target);
+  if (isAbsolute(fromRoot) || fromRoot === ".." || fromRoot.startsWith(`..${sep}`)) {
+    throw new Error(`Generated migration path escapes the project: ${candidate}`);
+  }
+  return target;
+}
+function readExistingConfig(projectDir) {
+  const configPath = projectPath(projectDir, "docs.json");
+  if (!existsSync3(configPath)) return void 0;
+  return JSON.parse(readFileSync3(configPath, "utf8"));
+}
+function resetFreshMigrationContent(projectDir) {
+  const contentDirectory = projectPath(projectDir, "src/content");
+  rmSync(contentDirectory, { recursive: true, force: true });
+  mkdirSync(contentDirectory, { recursive: true });
+  for (const sampleSpec of ["openapi.yaml", "openapi.json"]) {
+    rmSync(projectPath(projectDir, sampleSpec), { force: true });
+  }
+}
+async function discoverMigration(options) {
+  const url = new URL(options.sourceUrl);
+  if (url.hostname.toLowerCase() !== "github.com") {
+    console.log(`  \u{1F310} Discovering public docs at ${url.origin}${url.pathname}...`);
+    return migrateUrl({
+      sourceUrl: options.sourceUrl,
+      platform: options.platform,
+      maxPages: options.maxPages,
+      fetcher: options.fetcher
+    });
+  }
+  const source = parseGitHubRepositoryUrl(options.sourceUrl);
+  if (options.branch) source.branch = options.branch;
+  const temporaryRoot = mkdtempSync(join3(tmpdir(), "thally-migrate-"));
+  const cloneDir = join3(temporaryRoot, "repository");
+  console.log(`  \u{1F4E6} Cloning ${source.owner}/${source.repo}...`);
+  try {
+    await cloneGitHubRepository(source, cloneDir);
+    return migrateRepository({
+      repositoryDir: cloneDir,
+      sourceUrl: options.sourceUrl,
+      docsDir: options.docsDir ?? (source.docsDir || void 0),
+      platform: options.platform
+    });
+  } finally {
+    rmSync(temporaryRoot, { recursive: true, force: true });
+  }
+}
+async function migrateDocs(options) {
+  const projectDir = resolve(options.projectDir);
+  const bundle = await discoverMigration(options);
+  if (!options.into) {
+    console.log(`
+  \u{1F3D7}  Scaffolding new project at ${projectDir}...`);
+    await scaffold({
+      projectDir,
+      projectName: options.projectName ?? bundle.site?.name ?? "My Docs",
+      description: bundle.site?.description ?? `Documentation migrated from ${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
+    });
+    resetFreshMigrationContent(projectDir);
+  } else if (!existsSync3(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;
+    bundle.docsConfig.i18n ??= { defaultLocale: "en", locales: [{ code: "en", label: "English" }] };
+  }
+  const rendered = renderMigrationFiles(bundle, {
+    existingConfig: options.into ? readExistingConfig(projectDir) : void 0,
+    existingComponentRegistry: existsSync3(projectPath(projectDir, "src/mdx/custom-components.tsx")) ? readFileSync3(projectPath(projectDir, "src/mdx/custom-components.tsx"), "utf8") : void 0
+  });
+  for (const file of rendered) {
+    const destination = projectPath(projectDir, file.path);
+    mkdirSync(dirname(destination), { recursive: true });
+    writeFileSync(destination, file.content);
+  }
+  for (const warning of bundle.warnings) {
+    console.warn(`  \u26A0  ${warning.message}${warning.source ? ` (${warning.source})` : ""}`);
+  }
+  console.log(`  \u2713 Imported ${bundle.pages.length} pages and ${bundle.assets.length} assets from ${bundle.platform}.`);
+  let installationFailed = false;
+  if (!options.into && options.trustSource === true && !options.skipValidation) {
+    try {
+      installDeps(projectDir);
+    } catch {
+      installationFailed = true;
+    }
+  }
+  console.log("\n  Validating imported documentation...");
+  const validation = await validateMigration(projectDir, options.skipValidation, options.trustSource === true, installationFailed);
+  const reportPath = projectPath(projectDir, "migration-report.json");
+  writeFileSync(reportPath, `${JSON.stringify({
+    version: 1,
+    sourceUrl: `${new URL(options.sourceUrl).origin}${new URL(options.sourceUrl).pathname}`,
+    platform: bundle.platform,
+    pages: bundle.pages.length,
+    assets: bundle.assets.length,
+    components: bundle.componentFiles?.length ?? 0,
+    warnings: bundle.warnings,
+    validation
+  }, null, 2)}
+`);
+  for (const message of validation.messages) console.warn(`  \u26A0  ${message}`);
+  console.log(`  Migration report: ${reportPath}`);
+  if (validation.content === "passed" && validation.build === "passed") {
+    console.log(`  \u2713 Content and production build passed.${bundle.warnings.length ? " Review the migration warnings for compatibility limitations." : ""}`);
+  } else {
+    console.warn("  Import retained, but validation is incomplete. Do not publish without reviewing the report.");
+  }
+  if (!options.into) initGit(projectDir);
+  return {
+    pagesWritten: bundle.pages.length,
+    assetsWritten: bundle.assets.length,
+    projectDir,
+    platform: bundle.platform,
+    warnings: bundle.warnings,
+    validation,
+    reportPath
+  };
+}
+
+export {
+  parseFrontmatter,
+  runCheck,
+  migrateDocs
+};

package/dist/{chunk-XAUCGJ6B.js → chunk-FLSOVTVO.js}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   readStarterReleaseManifest
-} from "./chunk-PMAJ4BVM.js";
+} from "./chunk-HYGEXPZG.js";
 import {
   STABLE_SCAFFOLD_RELEASE
-} from "./chunk-SSKXNB6D.js";
+} from "./chunk-ZFCZE7M7.js";
 
 // src/download.ts
 import { Readable, Transform, pipeline } from "stream";

package/dist/{chunk-PMAJ4BVM.js → chunk-HYGEXPZG.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   STABLE_SCAFFOLD_RELEASE
-} from "./chunk-SSKXNB6D.js";
+} from "./chunk-ZFCZE7M7.js";
 
 // src/starter-sync.ts
 import { createHash } from "crypto";