create-thally-docs 0.10.78 → 0.10.80

package/dist/chunk-VGE5L66Z.js

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+import {
+  findPublicSpecs,
+  shadowNote
+} from "./chunk-KDLP27DS.js";
+import {
+  initGit,
+  installDeps,
+  runProjectCommand,
+  scaffold
+} from "./chunk-KGKSB3PU.js";
+import {
+  pruneMissingSiteLinks
+} from "./chunk-4VKRBJV2.js";
+import {
+  terminal
+} from "./chunk-L2YCVQBR.js";
+
+// src/migrate/index.ts
+import { existsSync as existsSync2, mkdirSync, mkdtempSync, readFileSync as readFileSync2, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { setImmediate } from "timers/promises";
+import { basename, dirname, isAbsolute, join as join2, relative, resolve, sep } from "path";
+import {
+  cloneGitHubRepository,
+  importSourceRef,
+  hydrateRemoteApiSpecs,
+  migrateUrl,
+  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/index.ts
+function projectPath(projectDir, candidate) {
+  const target = resolve(projectDir, candidate);
+  const fromRoot = relative(resolve(projectDir), target);
+  if (isAbsolute(fromRoot) || fromRoot === ".." || fromRoot.startsWith(`..${sep}`)) {
+    throw new Error(`Generated migration path escapes the project: ${candidate}`);
+  }
+  return target;
+}
+function ignoreQuarantineDirectory(projectDir) {
+  const ignorePath = projectPath(projectDir, ".gitignore");
+  const existing = existsSync2(ignorePath) ? readFileSync2(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";
+  writeFileSync(ignorePath, `${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 (!existsSync2(configPath)) return void 0;
+  return JSON.parse(readFileSync2(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 fetchSourceRefs(mappings, warnings) {
+  const imports = [];
+  for (const mapping of mappings) {
+    const root = mkdtempSync(join2(tmpdir(), "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 = join2(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 {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }
+  return imports;
+}
+async function discoverMigration(options) {
+  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
+      };
+      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 = mkdtempSync(join2(tmpdir(), "thally-migrate-"));
+  const cloneDir = join2(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 {
+    rmSync(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 = resolve(options.projectDir);
+  const bundle = await discoverMigration(options);
+  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 ${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 (!existsSync2(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 rendered = await terminal.step("Rendering documentation", () => renderFiles(bundle, {
+    existingConfig: options.into ? readExistingConfig(projectDir) : void 0,
+    existingComponentRegistry: existsSync2(projectPath(projectDir, "src/mdx/custom-components.tsx")) ? readFileSync2(projectPath(projectDir, "src/mdx/custom-components.tsx"), "utf8") : void 0
+  }), "Documentation rendered");
+  await terminal.step("Writing documentation", async (update) => {
+    let written = 0;
+    for (const file of rendered) {
+      const destination = projectPath(projectDir, file.path);
+      mkdirSync(dirname(destination), { recursive: true });
+      writeFileSync(destination, file.content);
+      written += 1;
+      if (written % 32 === 0) {
+        update(`Writing documentation (${written}/${rendered.length} files)`);
+        await setImmediate();
+      }
+    }
+    if (bundle.quarantinedFiles?.length) ignoreQuarantineDirectory(projectDir);
+  }, `Imported ${bundle.pages.length} pages and ${bundle.assets.length} 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);
+  const quarantinedPages = (bundle.quarantinedFiles ?? []).filter((file) => /\.mdx?$/i.test(file.path)).length;
+  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,
+    sourceRefs: bundle.sourceRefs ?? [],
+    quarantined: quarantinedPages,
+    quarantinedAssets: (bundle.quarantinedFiles?.length ?? 0) - quarantinedPages,
+    droppedGatedPages: bundle.droppedGatedPages ?? 0,
+    warnings: bundle.warnings,
+    validation
+  }, 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: bundle.pages.length,
+    assetsWritten: bundle.assets.length,
+    projectDir,
+    platform: bundle.platform,
+    warnings: bundle.warnings,
+    validation,
+    reportPath
+  };
+}
+
+export {
+  migrateDocs
+};

package/dist/{chunk-W5WQ2V7P.js → chunk-WWIATVAD.js}

@@ -5,12 +5,14 @@ import {
 import {
   STABLE_SCAFFOLD_RELEASE
 } from "./chunk-BP2REWTO.js";
+import {
+  terminal
+} from "./chunk-L2YCVQBR.js";
 
 // src/download.ts
 import { Readable, Transform, pipeline } from "stream";
 import { promisify } from "util";
 import {
-  cpSync,
   lstatSync,
   mkdtempSync,
   readdirSync,
@@ -20,6 +22,7 @@ import {
 } from "fs";
 import { tmpdir } from "os";
 import { dirname, join } from "path";
+import { cp } from "fs/promises";
 import { extract } from "tar";
 var pipelineAsync = promisify(pipeline);
 var STARTER_FETCH_TIMEOUT_MS = 15e3;
@@ -86,9 +89,16 @@ function compressedArchiveLimit() {
 }
 async function downloadStarter(targetDir, siteName, release = STABLE_SCAFFOLD_RELEASE, options = {}) {
   if (options.announce !== false) {
-    console.log("");
-    console.log(`  \u23F3 Creating ${siteName?.trim() || "your docs site"}...`);
+    await terminal.step(
+      `Downloading starter for ${siteName?.trim() || "your docs site"}`,
+      () => extractStarter(targetDir, release),
+      "Starter downloaded"
+    );
+    return;
   }
+  await extractStarter(targetDir, release);
+}
+async function extractStarter(targetDir, release) {
   const targetEntry = lstatSync(targetDir);
   if (!targetEntry.isDirectory() || targetEntry.isSymbolicLink()) {
     throw new Error("The Thally starter target must be a regular directory.");
@@ -137,7 +147,7 @@ async function downloadStarter(targetDir, siteName, release = STABLE_SCAFFOLD_RE
     );
     try {
       for (const entry of readdirSync(stagingDir)) {
-        cpSync(join(stagingDir, entry), join(deliveryDir, entry), {
+        await cp(join(stagingDir, entry), join(deliveryDir, entry), {
           recursive: true,
           errorOnExist: true
         });