create-thally-docs 0.10.118 → 0.10.119

package/README.md

@@ -13,13 +13,13 @@ cd my-docs
 npm run dev
 ```
 
-Sites created from a starter that includes the `thally` CLI
-(`@thallylabs/cli`) as a dev dependency can run `npx thally dev` instead, which
-also prints the local `llms.txt` and MCP endpoints once the server is ready.
-The completion message prints the right command for the project you created.
+The default site does not bundle the Thally CLI or deployment tooling. Run
+`npm run check` to validate documentation, or `npm run starter:update` to preview
+a framework update using the current official CLI. Legacy sites that explicitly
+install a local CLI retain their existing preview command.
 
-The dev server starts at [http://localhost:3040](http://localhost:3040) and
-automatically uses the next available port when needed. A freshly scaffolded
+The dev server starts at [http://localhost:3040](http://localhost:3040). If that
+port is occupied, run `npm run dev -- --port 3041`. A freshly scaffolded
 site is agent-ready out of the box and scores 100/A on the built-in
 [Agent Readiness Score](https://github.com/thallylabs/thally).
 
@@ -74,7 +74,7 @@ runs retain subprocess output for scripts and CI. These options also work with
 | Command | What it does |
 | --- | --- |
 | `create-thally-docs <dir>` | Scaffold a new project |
-| `create-thally-docs migrate <github-or-docs-url> [dir]` | Import a docs repository or public docs site through the shared migration engine |
+| `create-thally-docs migrate <github-or-docs-url-or-directory> [dir]` | Import a docs repository or public docs site through the shared migration engine |
 | `create-thally-docs check [dir] [--fix] [--ci] [--drift] [--external]` | Lint content for broken links, orphan pages, and missing frontmatter; `--external` also checks links to public hosts (bounded, warnings only) |
 | `create-thally-docs translate --locale <code>` | Translate content into another locale |
 
@@ -88,6 +88,36 @@ destination runtime still apply. For example:
 npx create-thally-docs migrate https://docs.example.com my-docs --max-pages 1500 --yes
 ```
 
+A local checkout works without making a private repository public:
+
+```bash
+npx create-thally-docs migrate "../private docs" my-docs --platform mintlify --yes
+npx create-thally-docs migrate https://docs.example.com my-docs --openapi https://docs.example.com/openapi.json --yes
+```
+
+Local sources are supported by the local CLI (`thally migrate` forwards the same
+arguments). The selected input and output must be separate directories. The
+importer snapshots documentation inputs without executing configuration; it skips
+hidden files, dependency directories and symlinks that escape the selected root.
+The Cloud and MCP URL adapters do not gain access to local paths or `file://` URLs.
+
+Website migration restores publisher-provided embedded OpenAPI operations and
+can discover a single linked `openapi.json`/`openapi.yaml` specification. Supply
+`--openapi <https-url>` when the source does not expose one, or links several.
+Only unambiguous operation routes are bound to crawled pages; their original
+prose and URLs stay intact, and generated API navigation excludes those operations.
+Markdown mirror links retain `.md`; machine indexes and spec links use the new
+site's equivalent routes. The migration report identifies unresolved internal links
+and unsupported frontmatter that need review. Supported code-fence labels,
+line numbers, wrapping, focus and highlights remain portable.
+
+An in-place import (`--into <dir>`) preserves authored files that conflict with
+incoming content and lists them in `migration-report.json`; validation fails until
+you resolve those conflicts. Authored navigation is merged. Untouched sample
+navigation is replaced only after comparison with the project's verified immutable
+starter archive and unchanged sample content. If provenance cannot be proved, the
+existing navigation is preserved and the report explains why.
+
 Interactive migrations ask whether the source is Mintlify, Docusaurus, Fern, or
 another auto-detected platform. When automatic detection receives a live
 website URL, the CLI recommends its source GitHub repository and requires
@@ -111,7 +141,7 @@ embedded by Mintlify when it is available, with bounded same-site crawling as a
 fallback.
 
 Migrated OpenAPI specs are written to `openapi/`, not `public/` (which the host
-serves as-is). `--into` never deletes files: an older copy of a spec already in
+serves as-is). `--into` never deletes authored files; only verified unchanged starter samples may be removed: an older copy of a spec already in
 `public/` stays publicly downloadable (a `public/openapi.json` even answers
 `/openapi.json` in place of the filtered spec), so the migration lists such files and
 `thally check` warns about them until you delete them manually.

package/dist/{chunk-JKC4FXSW.js → chunk-44WRU5LD.js}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-L2YCVQBR.js";
 import {
   readStarterReleaseManifest
-} from "./chunk-QPHUUFSH.js";
+} from "./chunk-C4DPGWFM.js";
 import {
   STABLE_SCAFFOLD_RELEASE
 } from "./chunk-FMVUFWZP.js";

package/dist/{chunk-SVB25WSN.js → chunk-6MT76XGS.js}

@@ -9,7 +9,7 @@ import {
 } from "./chunk-J7255UQA.js";
 import {
   downloadStarter
-} from "./chunk-JKC4FXSW.js";
+} from "./chunk-44WRU5LD.js";
 import {
   terminal
 } from "./chunk-L2YCVQBR.js";
@@ -22,6 +22,7 @@ import { resolve as resolve2 } from "path";
 import { execFileSync, execSync, spawn } from "child_process";
 import { existsSync, readFileSync } from "fs";
 import { join, resolve } from "path";
+import semver from "semver";
 function slugify(name) {
   return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
 }
@@ -34,7 +35,7 @@ async function runProjectCommand(command, args, cwd, timeout, onProgress) {
       stdio: isQuiet ? ["ignore", "pipe", "pipe"] : "inherit",
       // Windows resolves npm via a .cmd shim; command and arguments here are
       // fixed by the toolchain, never interpolated from imported content.
-      shell: process.platform === "win32" && command === "npm"
+      shell: process.platform === "win32" && ["npm", "pnpm", "yarn"].includes(command)
     });
     let tail = Buffer.alloc(0);
     let omitted = false;
@@ -121,18 +122,51 @@ async function initGit(targetDir) {
     terminal.warn("Could not finish Git setup. Run git status in the project directory, fix the reported issue, then retry the commit.");
   }
 }
-async function installDeps(targetDir) {
+function detectPackageManager(targetDir, requested, userAgent = process.env.npm_config_user_agent) {
+  if (requested) return requested;
+  if (existsSync(join(targetDir, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(targetDir, "yarn.lock"))) return "yarn";
+  if (userAgent?.startsWith("pnpm/")) return "pnpm";
+  if (userAgent?.startsWith("yarn/")) return "yarn";
+  return "npm";
+}
+function dependencyInstallArguments(targetDir, manager) {
+  if (manager !== "npm") return ["install"];
+  return [
+    existsSync(join(targetDir, "package-lock.json")) ? "ci" : "install",
+    "--no-audit",
+    "--no-fund",
+    "--progress=false"
+  ];
+}
+function assertProjectNodeVersion(targetDir, nodeVersion = process.versions.node) {
+  const manifest = JSON.parse(readFileSync(join(targetDir, "package.json"), "utf8"));
+  const range = manifest.engines?.node;
+  if (range === void 0) return;
+  if (typeof range !== "string" || !semver.validRange(range)) {
+    throw new Error("The documentation project declares an invalid Node.js engine range.");
+  }
+  if (!semver.satisfies(nodeVersion, range)) {
+    throw new Error(`This documentation project requires Node.js ${range}; you are using ${nodeVersion}. Switch to a supported Node.js version and retry installation. Your project files and lockfile are preserved.`);
+  }
+}
+async function installDeps(targetDir, requested) {
+  const manager = detectPackageManager(targetDir, requested);
+  const args = dependencyInstallArguments(targetDir, manager);
   try {
-    await terminal.step("Install dependencies", (update) => runProjectCommand("npm", [
-      "install",
-      "--prefer-offline",
-      "--no-audit",
-      "--no-fund",
-      "--progress=false"
-    ], targetDir, void 0, (message) => update(`Install dependencies: ${message}`)), "Dependencies installed");
+    assertProjectNodeVersion(targetDir);
+    await terminal.step("Install dependencies", (update) => runProjectCommand(
+      manager,
+      args,
+      targetDir,
+      void 0,
+      (message) => update(`Install dependencies: ${message}`)
+    ), "Dependencies installed");
   } catch (error) {
     const failure = error;
     if (failure.output?.trim()) terminal.error(failure.output.trimEnd());
+    else terminal.error(failure.message);
+    terminal.warn(`Installation did not complete. Your content and lockfile were kept. Retry: cd ${quoteDirectory(targetDir)} && ${manager} ${args.join(" ")}. If a package is incomplete, remove only node_modules before retrying.`);
     throw error;
   }
 }
@@ -148,18 +182,22 @@ function declaresThallyCli(directory) {
     return false;
   }
 }
-function devCommand(directory, needsInstall = false) {
+function devCommand(directory, needsInstall = false, requested) {
   const binary = join(directory, "node_modules", ".bin", "thally");
   const hasLocalCli = needsInstall ? declaresThallyCli(directory) : existsSync(binary) || existsSync(`${binary}.cmd`);
-  return hasLocalCli ? "npx thally dev" : "npm run dev";
+  const manager = detectPackageManager(directory, requested);
+  if (!hasLocalCli) return `${manager} run dev`;
+  return manager === "npm" ? "npx thally dev" : manager === "pnpm" ? "pnpm exec thally dev" : "yarn thally dev";
 }
-function previewCommand(directory, needsInstall = false) {
-  return `cd ${quoteDirectory(directory)} && ${needsInstall ? "npm install && " : ""}${devCommand(directory, needsInstall)}`;
+function previewCommand(directory, needsInstall = false, requested) {
+  const manager = detectPackageManager(directory, requested);
+  const install = manager === "npm" && existsSync(join(directory, "package-lock.json")) ? "npm ci" : `${manager} install`;
+  return `cd ${quoteDirectory(directory)} && ${needsInstall ? `${install} && ` : ""}${devCommand(directory, needsInstall, requested)}`;
 }
 function logo(version) {
   terminal.intro("init", version, "Build and publish docs for people and AI tools.");
 }
-function success(projectDir, projectName, dependenciesInstalled) {
+function success(projectDir, projectName, dependenciesInstalled, requested) {
   terminal.detail("Project", projectName);
   terminal.detail("Output", projectDir);
   terminal.section("Make it yours", [
@@ -168,7 +206,7 @@ function success(projectDir, projectName, dependenciesInstalled) {
     "src/data/site.ts  Name, links, and branding"
   ]);
   terminal.outro("Your docs project is ready. The dev server will print your preview URL.");
-  terminal.nextAction("Preview locally", previewCommand(projectDir, !dependenciesInstalled));
+  terminal.nextAction("Preview locally", previewCommand(projectDir, !dependenciesInstalled, requested));
 }
 
 // src/scaffold.ts
@@ -221,12 +259,12 @@ async function scaffold(options) {
   let dependenciesInstalled = false;
   if (doInstall) {
     try {
-      await installDeps(targetDir);
+      await installDeps(targetDir, options.packageManager);
       dependenciesInstalled = true;
     } catch (error) {
       const exitCode = error.exitCode;
       if (!continueOnInstallFailure || exitCode === 130 || exitCode === 143) throw error;
-      terminal.warn('Dependency installation failed. The project was created; run "npm install" in it to finish.');
+      terminal.warn("Dependency installation failed. The project was created; use the recovery command above to finish.");
     }
   }
   await initGit(targetDir);

package/dist/{chunk-7UPLZRN4.js → chunk-7BAJKUBN.js}

@@ -1,16 +1,17 @@
 #!/usr/bin/env node
 import {
   downloadStarter
-} from "./chunk-JKC4FXSW.js";
+} from "./chunk-44WRU5LD.js";
 import {
   applyStarterRuntimeSyncPlan,
+  areStarterFileContentsEquivalent,
   captureTargetPrecondition,
   mergeStarterOwnershipContracts,
   parseStarterReleaseManifest,
   planStarterRuntimeSync,
   readStarterReleaseManifest,
   starterManifestSha256
-} from "./chunk-QPHUUFSH.js";
+} from "./chunk-C4DPGWFM.js";
 import {
   STABLE_SCAFFOLD_RELEASE,
   SUPPORTED_SCAFFOLD_RELEASES
@@ -36,10 +37,6 @@ var STRUCTURED_MANUAL_REVIEW_PATHS = /* @__PURE__ */ new Set([
   "package-lock.json"
 ]);
 var MISSING_JSON_VALUE = /* @__PURE__ */ Symbol("missing-json-value");
-function hasSameBytes(left, right) {
-  if (!left || !right) return left === right;
-  return left.equals(right);
-}
 function isJsonObject(value) {
   return value !== MISSING_JSON_VALUE && value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -121,10 +118,10 @@ function resolveManualReviewMutations(paths, downstreamFiles, previousReleaseFil
     const downstream = downstreamFiles.get(path);
     const previous = previousReleaseFiles.get(path);
     const target = targetReleaseFiles.get(path);
-    if (hasSameBytes(previous, target) || hasSameBytes(downstream, target)) {
+    if (areStarterFileContentsEquivalent(path, previous, target) || areStarterFileContentsEquivalent(path, downstream, target)) {
       continue;
     }
-    if (hasSameBytes(downstream, previous)) {
+    if (areStarterFileContentsEquivalent(path, downstream, previous)) {
       if (target) mutations.writeFiles.set(path, target);
       else mutations.deletePaths.push(path);
       continue;
@@ -136,7 +133,7 @@ function resolveManualReviewMutations(paths, downstreamFiles, previousReleaseFil
         target
       });
       if (merged.content) {
-        if (!hasSameBytes(downstream, merged.content)) {
+        if (!areStarterFileContentsEquivalent(path, downstream, merged.content)) {
           mutations.writeFiles.set(path, merged.content);
         }
         continue;
@@ -343,7 +340,7 @@ async function resolveStarterUpdateBase(options) {
       assertRecoveryPackages(options.targetDir, baselineDir, baseline.packages);
       return { release, recoveredProvenance: true, manifestSha256 };
     }
-    throw new Error("The project starter manifest is edited, unknown, or has no verified published framework baseline; refusing to update.");
+    throw new Error("The project starter manifest is edited, unknown, or has no verified published framework baseline; refusing to update. If this project was created by a newer release, retry with npx --yes --package=@thallylabs/cli@latest thally starter update. Keep starter-release.json unchanged.");
   } finally {
     rmSync(workspace, { recursive: true, force: true });
   }
@@ -354,7 +351,7 @@ function assertForwardRelease(previous, target, releases) {
   }
   if (previous.source.commitSha === target.source.commitSha) return;
   if (previous.starterVersion > target.starterVersion) {
-    throw new Error("The installed CLI does not contain a newer starter release.");
+    throw new Error("The installed CLI does not contain a newer starter release. Retry with npx --yes --package=@thallylabs/cli@latest thally starter update.");
   }
   if (previous.starterVersion === target.starterVersion) {
     const targetIndex = releases.findIndex(
@@ -364,7 +361,7 @@ function assertForwardRelease(previous, target, releases) {
       (release) => release.source.commitSha === previous.source.commitSha
     );
     if (targetIndex === -1 || previousIndex === -1 || previousIndex <= targetIndex) {
-      throw new Error("The installed CLI does not contain a newer starter release.");
+      throw new Error("The installed CLI does not contain a newer starter release. Retry with npx --yes --package=@thallylabs/cli@latest thally starter update.");
     }
   }
 }

package/dist/{chunk-QPHUUFSH.js → chunk-C4DPGWFM.js}

@@ -5,6 +5,22 @@ import {
 
 // src/starter-sync.ts
 import { createHash } from "crypto";
+
+// src/starter-file-comparison.ts
+var textPolicies = /* @__PURE__ */ new Set([".gitignore", ".gitattributes"]);
+function areStarterFileContentsEquivalent(path, left, right) {
+  if (!left || !right) return left === right;
+  if (left.equals(right)) return true;
+  const filename = path.split(/[\\/]/).at(-1) ?? "";
+  if (!/\.(?:[cm]?[jt]sx?|jsonc?|mdx?|ya?ml|css|html|svg|txt)$/.test(filename) && !textPolicies.has(filename)) return false;
+  if (left.includes(0) || right.includes(0)) return false;
+  const leftText = left.toString("utf8");
+  const rightText = right.toString("utf8");
+  if (!Buffer.from(leftText).equals(left) || !Buffer.from(rightText).equals(right)) return false;
+  return leftText.replace(/\r\n/g, "\n") === rightText.replace(/\r\n/g, "\n");
+}
+
+// src/starter-sync.ts
 import {
   copyFileSync,
   existsSync,
@@ -249,7 +265,7 @@ function collectFiles(root, contract, desiredOwnership) {
 }
 function sameFile(left, right) {
   if (!left || !right) return left === right;
-  return readFileSync(left).equals(readFileSync(right));
+  return areStarterFileContentsEquivalent(left, readFileSync(left), readFileSync(right));
 }
 function fileSha256(path) {
   return createHash("sha256").update(readFileSync(path)).digest("hex");
@@ -520,6 +536,7 @@ function applyStarterRuntimeSyncPlan(newStarterDir, targetDir, plan, ownership,
 }
 
 export {
+  areStarterFileContentsEquivalent,
   parseStarterOwnershipContract,
   mergeStarterOwnershipContracts,
   starterManifestSha256,