@readme/cli 0.0.30 → 0.0.31

package/README.md

@@ -50,6 +50,33 @@ Starts a local dev server so you can preview your docs as you write them. Watche
 npx @readme/cli dev
 ```
 
+## GitHub Action
+
+This repo also publishes itself as a GitHub Action, so a workflow can run `lint`, `oas:validate`, or `oas:sync` directly, pinned to a version, without an `npx` install step on every run:
+
+```yaml
+- uses: readmeio/cli@v1
+  with:
+    readme: oas:sync
+```
+
+The `readme` input is the same command you'd run on the CLI, e.g. `lint`, `oas:validate --dereference`, or `oas:sync`. Each command exits non-zero on a real problem, same as running it locally, and publishes its results as step outputs — `has-errors`, `skipped-count`, `total-errors`, and more (see [`action.yml`](./action.yml) for the full list) — so a later step can check them directly instead of parsing log output:
+
+```yaml
+- name: Sync reference pages from OpenAPI specs
+  id: sync
+  uses: readmeio/cli@v1
+  with:
+    readme: oas:sync
+```
+
+```yaml
+- if: steps.sync.outputs.skipped-count != '0'
+  run: echo "::error::oas:sync skipped a page — see the sync step above."
+```
+
+Note: the first run of a workflow using this Action installs one extra dependency (`@readme/markdown`) behind the scenes before your command runs — this is expected, and only adds a few seconds.
+
 ## Feedback
 
 If something doesn't work right, or if you have suggestions, please [open an issue](https://github.com/readmeio/cli/issues). We're actively building this and want to hear from you.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readme/cli",
-  "version": "0.0.30",
+  "version": "0.0.31",
   "description": "The ReadMe CLI",
   "type": "module",
   "bin": {
@@ -25,7 +25,8 @@
   ],
   "scripts": {
     "start": "node bin/readme.js",
-    "test": "node --test src/**/*.test.js test/*.test.js"
+    "test": "node --test src/**/*.test.js test/*.test.js",
+    "build:gha": "ncc build src/gha.js -o dist-gha --external @readme/markdown"
   },
   "engines": {
     "node": ">=22"
@@ -56,5 +57,8 @@
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "update-notifier": "^7.3.1"
+  },
+  "devDependencies": {
+    "@vercel/ncc": "^0.45.0"
   }
 }

package/src/commands/lint.js

@@ -1,11 +1,9 @@
-import { createRequire } from 'node:module'
 import { collectFiles, runValidators } from '../utils/lint.js'
 import { createHumanReporter, createJsonReporter, createGithubReporter } from '../utils/reporter.js'
 import { printHeader, isAgenticCli } from '../utils/eyes.js'
 import * as styles from '../utils/styles.js'
-
-const require = createRequire(import.meta.url)
-const pkg = require('../../package.json')
+import { writeGithubActionsOutputs } from '../utils/gha-output.js'
+import pkg from '../../package.json' with { type: 'json' }
 
 export const command = 'lint'
 export const order = 1
@@ -59,6 +57,8 @@ export async function run(options, _cmd, ctx) {
 
   reporter.finish(files.length, results, files, { fix: options.fix, gitRoot })
 
+  writeGithubActionsOutputs({ 'has-errors': String(hasErrors), results })
+
   if (hasErrors) {
     // Wait for stdout to flush (important when piped to a file), then exit
     await new Promise((resolve) => process.stdout.write('', resolve))

package/src/commands/oas-sync.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { createRequire } from 'node:module';
 import matter from 'gray-matter';
 import * as styles from '../utils/styles.js';
+import { writeGithubActionsOutputs } from '../utils/gha-output.js';
 
 const require = createRequire(import.meta.url);
 const yaml = require('js-yaml');
@@ -115,6 +116,60 @@ function resolveLocalPathItemRef(entry, spec) {
   return finish();
 }
 
+/**
+ * Resolve the `x-internal` extension for an operation the way the platform
+ * does on OAS upload: an operation-level value wins, falling back to the
+ * spec root. `present` is false when neither sets it, in which case the
+ * page's visibility is left to whoever owns it (new pages default to
+ * visible, existing pages keep whatever `hidden` they already have).
+ * `x-readme: { internal: true }` is deliberately not read — the platform's
+ * page sync only honors the bare `x-internal` key.
+ */
+function resolveXInternal(operation, spec) {
+  if (operation && 'x-internal' in operation) return { present: true, value: operation['x-internal'] };
+  if (spec && 'x-internal' in spec) return { present: true, value: spec['x-internal'] };
+  return { present: false, value: undefined };
+}
+
+/**
+ * Find every `x-readme: { internal: ... }` in a spec. The `oas` package
+ * documents it as an alternative spelling of `x-internal`, but the platform's
+ * page sync never reads it (see `resolveXInternal`), so it silently has no
+ * effect. Returns human-readable locations (`root`, `GET /pets`,
+ * `webhook POST newPet`) for lint to warn about.
+ */
+export function findIgnoredInternalExtensions(spec) {
+  const hasInternal = (obj) => {
+    const xReadme = obj?.['x-readme'];
+    return !!xReadme && typeof xReadme === 'object' && 'internal' in xReadme;
+  };
+
+  const locations = [];
+  if (hasInternal(spec)) locations.push('root');
+
+  for (const [entries, isWebhook] of [[spec?.paths, false], [spec?.webhooks, true]]) {
+    for (const [name, rawItem] of Object.entries(entries || {})) {
+      for (const [method, operation] of Object.entries(resolveLocalPathItemRef(rawItem, spec) || {})) {
+        if (!HTTP_METHODS.has(method) || !hasInternal(operation)) continue;
+        locations.push(`${isWebhook ? 'webhook ' : ''}${method.toUpperCase()} ${name}`);
+      }
+    }
+  }
+  return locations;
+}
+
+/**
+ * Read a root-level ReadMe extension, in the same precedence as the `oas`
+ * package's `getExtension()` with no operation: `x-readme.<name>`, then
+ * `x-<name>`, then a bare `<name>`.
+ */
+function getRootExtension(spec, name) {
+  const xReadme = spec?.['x-readme'];
+  if (xReadme && typeof xReadme === 'object' && name in xReadme) return xReadme[name];
+  if (spec && `x-${name}` in spec) return spec[`x-${name}`];
+  return spec?.[name];
+}
+
 /**
  * Extract operations from an OAS spec's `paths`, plus its OAS 3.1 `webhooks`
  * (callouts the API itself makes to a client-registered URL, not endpoints the
@@ -143,9 +198,11 @@ export function extractOperations(spec) {
           operationId,
           summary: operation.summary || null,
           description: operation.description || null,
-          tag: (operation.tags && operation.tags[0]) || null,
+          // The platform groups by the first *non-empty* tag.
+          tag: (Array.isArray(operation.tags) && operation.tags.find((t) => t)) || null,
           path: pathStr,
           isWebhook,
+          xInternal: resolveXInternal(operation, spec),
         });
       }
     }
@@ -264,7 +321,7 @@ function stringifyFrontmatter(frontmatter) {
   return matter.stringify('', frontmatter).replace(/\n+$/, '');
 }
 
-function buildPageContent({ oasFilename, operationId, isWebhook }) {
+function buildPageContent({ oasFilename, operationId, isWebhook, hidden = false }) {
   const frontmatter = {
     api: {
       file: oasFilename,
@@ -274,19 +331,12 @@ function buildPageContent({ oasFilename, operationId, isWebhook }) {
       // what the platform stamps on a page generated from `webhooks`.
       ...(isWebhook ? { webhook: true } : {}),
     },
-    // Mirror the platform's OAS-upload behavior: a newly added endpoint is
-    // always written `hidden: false`, even when its tag and siblings are
-    // `hidden: true`. The backend does not infer this from a missing field, so
-    // it must be written explicitly.
-    //
-    // @todo Honor the `x-internal` OpenAPI extension for page visibility, to
-    // match gitto#2095 (RM-4616 / CX-3303): resolve `hidden` from operation-level
-    // `x-internal`, falling back to root-level, else false; and hide a tag's
-    // index page when all of its operations are `x-internal: true`. Deferred to
-    // keep oas:sync create-only — the resync-side rules (re-applying x-internal
-    // to existing pages, parent hide-ratchet) would require mutating existing
-    // pages, which this command intentionally never does.
-    hidden: false,
+    // The backend does not infer visibility from a missing field, so it's
+    // always written explicitly: `x-internal` when the spec sets it (see
+    // `resolveXInternal`), otherwise `false` — mirroring the platform's
+    // OAS-upload, which writes a new endpoint visible even when its tag and
+    // siblings are hidden.
+    hidden,
   };
 
   return stringifyFrontmatter(frontmatter);
@@ -307,6 +357,25 @@ function buildTagIndexContent(title, description) {
   return stringifyFrontmatter(frontmatter);
 }
 
+/**
+ * Kebab-case a folder segment: lowercase, with any run of whitespace or other
+ * non-alphanumeric characters (a space, an underscore, ...) collapsed to a
+ * single hyphen. Two roles: (1) as an equivalence key, so "Shipping Labels",
+ * "shipping labels" and "shipping-labels" are recognized as the same
+ * folder no matter which spelling is already on disk (see
+ * `existingFoldersBySlug`); and (2) as the spelling used when *creating* a
+ * folder that doesn't exist under any spelling yet, matching what a fresh
+ * platform OAS-upload would produce. Neither spelling is the one "true"
+ * form — this just needs one fixed spelling to create with and to compare
+ * against.
+ */
+function slugifyFolder(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
 /**
  * The category-folder grouping for an operation. A tagged operation groups
  * under its own tag, as before. An untagged operation groups under a folder
@@ -316,11 +385,35 @@ function buildTagIndexContent(title, description) {
  * one "Other" folder.
  */
 function operationGroup(op) {
-  if (op.tag) return { folder: safeSegment(op.tag, 'Other').toLowerCase(), title: op.tag };
-  const folder = safeSegment(op.path.replace(/[/{}]/g, ''), 'operation').toLowerCase();
+  if (op.tag) return { folder: slugifyFolder(safeSegment(op.tag, 'Other')) || 'other', title: op.tag };
+  const folder = slugifyFolder(safeSegment(op.path.replace(/[/{}]/g, ''), 'operation')) || 'operation';
   return { folder, title: op.path };
 }
 
+/**
+ * Map every existing directory directly under `apiDir` to its slugified
+ * name (`slug -> actual on-disk name`), with a single directory read. Used
+ * to resolve a group's folder: whatever spelling is already on disk
+ * (hyphenated, space-separated, hand-authored, ...) is authoritative and
+ * must be reused rather than spawning a second, differently-spelled folder
+ * next to it. A slug with no entry here has nothing on disk yet, so the
+ * caller falls back to creating it under its hyphenated slug — the spelling
+ * a fresh platform OAS-upload would produce.
+ */
+function existingFoldersBySlug(apiDir) {
+  const bySlug = new Map();
+  let entries;
+  try {
+    entries = fs.readdirSync(apiDir, { withFileTypes: true });
+  } catch {
+    return bySlug; // apiDir doesn't exist yet — nothing to reuse.
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) bySlug.set(slugifyFolder(entry.name), entry.name);
+  }
+  return bySlug;
+}
+
 /**
  * Collect every slug already used across the entire reference/ tree, as a
  * lowercase-slug -> owner-count map. Reference page slugs share one flat
@@ -397,6 +490,133 @@ function reserveSlug(takenSlugs, base) {
   return chosen;
 }
 
+/**
+ * Rewrite a page's frontmatter in place, keeping its body. `mutate` receives
+ * a copy of the parsed frontmatter and edits it. Returns true if the file
+ * changed. A copy matters: gray-matter caches parse results by input string,
+ * so mutating the returned `data` would poison later parses of that content.
+ */
+function updateFrontmatter(filePath, mutate) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const parsed = matter(content);
+  const data = structuredClone(parsed.data);
+  mutate(data);
+  const next = parsed.content.trim()
+    ? matter.stringify(parsed.content, data)
+    : stringifyFrontmatter(data);
+  if (next === content || JSON.stringify(data) === JSON.stringify(parsed.data)) return false;
+  fs.writeFileSync(filePath, next);
+  return true;
+}
+
+/**
+ * Merge an OAS-derived slug order into an existing `_order.yaml` list, the
+ * way the platform does (gitto's `applyOASOrder`): only the slots already
+ * held by one of `orderedSlugs` are refilled, left to right, in OAS order;
+ * every other entry (hand-authored pages, other APIs) keeps its position.
+ * Slugs not yet listed are inserted right after the last refilled slot, or
+ * appended when none of them are listed yet.
+ */
+export function applyOASOrder(currentOrder, orderedSlugs) {
+  const desired = [...new Set(orderedSlugs)];
+  const desiredSet = new Set(desired);
+  // A hand-edited _order.yaml can list the same slug more than once. Collapse
+  // duplicates up front so each slot corresponds to exactly one distinct slug;
+  // otherwise there are more slots than slugs to refill them with, and the
+  // surplus slots would be filled with `undefined`.
+  const order = [...new Set(currentOrder)];
+  if (!order.length) return desired;
+
+  const slots = order.map((s, i) => (desiredSet.has(s) ? i : -1)).filter((i) => i > -1);
+  if (!slots.length) return [...order, ...desired];
+
+  const remaining = [...desired];
+  for (const index of slots) order[index] = remaining.shift();
+  if (remaining.length) order.splice(slots.at(-1) + 1, 0, ...remaining);
+  return order;
+}
+
+const INDEX_FILES = ['index.md', 'index.mdx', 'index.html'];
+
+/**
+ * Whether a tag folder's category page looks untouched since it was
+ * generated (mirrors gitto's `isAutoGeneratedParentPage`): no body, no
+ * frontmatter beyond title/hidden/excerpt, a title that slugifies to the
+ * folder name (allowing a `-N` uniqueness suffix), and an excerpt, if any,
+ * that is text the spec supplies.
+ *
+ * The excerpt needs care. The platform never writes one, but this CLI stamps
+ * the tag's description as `excerpt` on the pages it generates (see
+ * `buildTagIndexContent`), so its presence alone can't mean "hand-edited".
+ * Nothing records what a page was generated from, and by the time a folder
+ * is being cleaned up its tag has often left the spec, so the excerpt can't
+ * be checked against "its" tag either. What can be checked is whether the
+ * current spec still supplies that exact text under *any* tag
+ * (`specDescriptions`): a generated excerpt is always lifted from
+ * `tags[].description`, and a retag that renames a tag usually keeps its
+ * description, so this recognizes generated pages across the common rename.
+ * An excerpt the spec no longer supplies could be a description that left
+ * the spec, or a person's edit; with no way to tell them apart, the page is
+ * reported as hand-edited and `cleanupTagFolder` flattens it rather than
+ * deleting it. A stale page can be removed by hand; a deleted edit is gone.
+ */
+function isGeneratedTagIndex(indexPath, specDescriptions) {
+  let parsed;
+  try {
+    parsed = matter(fs.readFileSync(indexPath, 'utf-8'));
+  } catch {
+    return false;
+  }
+  const { data, content } = parsed;
+  if (content.trim()) return false;
+  if (typeof data.title !== 'string' || !('hidden' in data)) return false;
+  if (Object.keys(data).some((k) => !['title', 'hidden', 'excerpt'].includes(k))) return false;
+  if ('excerpt' in data && !specDescriptions.has(data.excerpt)) return false;
+
+  const dirSlug = slugifyFolder(path.basename(path.dirname(indexPath)));
+  const titleSlug = slugifyFolder(data.title);
+  return dirSlug === titleSlug || new RegExp(`^${titleSlug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}-\\d+$`).test(dirSlug);
+}
+
+/**
+ * After `apply-tag-changes` moves pages out of a tag folder, clean up the
+ * folder if it's now empty (gitto's `cleanupParentDirectory`). A generated
+ * category page is deleted along with its folder; a hand-edited one is kept
+ * by flattening `tag/index.md` into a sibling `tag.md` (same slug, so the
+ * parent `_order.yaml` entry still applies).
+ */
+function cleanupTagFolder(dir, { refDir, specDescriptions, takenSlugs, changes }) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return;
+  }
+  const others = entries.filter((e) => !INDEX_FILES.includes(e) && e !== '_order.yaml');
+  if (others.length) return;
+
+  const parentDir = path.dirname(dir);
+  const slug = path.basename(dir);
+  const indexFile = entries.find((e) => INDEX_FILES.includes(e));
+
+  if (!indexFile || isGeneratedTagIndex(path.join(dir, indexFile), specDescriptions)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+    removeFromOrder(path.join(parentDir, '_order.yaml'), slug);
+    if (indexFile) {
+      releaseSlug(takenSlugs, slug);
+      changes.deleted.push(path.relative(refDir, path.join(dir, indexFile)));
+    }
+    return;
+  }
+
+  const from = path.join(dir, indexFile);
+  const to = path.join(parentDir, `${slug}${path.extname(indexFile)}`);
+  if (fs.existsSync(to)) return;
+  fs.renameSync(from, to);
+  fs.rmSync(dir, { recursive: true, force: true });
+  changes.moved.push({ from: path.relative(refDir, from), to: path.relative(refDir, to) });
+}
+
 /**
  * Run the sync for a single OAS file. Returns changes for that file.
  *
@@ -410,6 +630,15 @@ function syncOneOas(refDir, oasFilename, spec, takenSlugs) {
     'api',
   );
 
+  // Hyphen vs. space in a group's folder name is not a meaningful difference
+  // — "shipping-labels" and "shipping labels" are the same folder to a
+  // human and to the platform, just spelled differently. One directory read
+  // up front (existingFoldersBySlug) is enough to resolve every group's
+  // folder for this API as an O(1) lookup, rather than walking apiDir again
+  // for each distinct tag/group.
+  const apiDir = path.join(refDir, infoTitle);
+  const foldersBySlug = existingFoldersBySlug(apiDir);
+
   const existingPages = collectExistingPages(refDir).filter(
     (p) => p.data.api.file === oasFilename,
   );
@@ -422,7 +651,12 @@ function syncOneOas(refDir, oasFilename, spec, takenSlugs) {
     );
   }
 
-  const changes = { added: [], deleted: [], skipped: [] };
+  const changes = { added: [], deleted: [], moved: [], updated: [], skipped: [] };
+
+  // Root-only opt-ins; only an explicit `true` counts, so a missing or
+  // malformed value leaves existing placement and order alone.
+  const applyTagChanges = getRootExtension(spec, 'apply-tag-changes') === true;
+  const applyEndpointOrder = getRootExtension(spec, 'apply-endpoint-order') === true;
 
   // Tag descriptions from the spec's top-level `tags` array, used for the
   // per-tag category landing page (index.md).
@@ -431,6 +665,9 @@ function syncOneOas(refDir, oasFilename, spec, takenSlugs) {
       .filter((t) => t && t.name)
       .map((t) => [t.name, t.description || null]),
   );
+  // Every description the spec supplies, regardless of which tag: what an
+  // emptied tag folder's excerpt is checked against (see `isGeneratedTagIndex`).
+  const specDescriptions = new Set([...tagDescriptions.values()].filter(Boolean));
 
   // Deletes: pages referencing operations that no longer exist.
   for (const [opId, page] of pagesByOpId) {
@@ -478,16 +715,20 @@ function syncOneOas(refDir, oasFilename, spec, takenSlugs) {
   // declared tag.
   const declaredOrder = (Array.isArray(spec.tags) ? spec.tags : [])
     .filter((t) => t && t.name)
-    .map((t) => safeSegment(t.name, 'Other').toLowerCase());
+    .map((t) => slugifyFolder(safeSegment(t.name, 'Other')) || 'other');
   const orderedFolders = [
     ...declaredOrder.filter((folder) => groupsByFolder.has(folder)),
     ...[...groupsByFolder.keys()].filter((folder) => !declaredOrder.includes(folder)),
   ];
 
+  const groupDirs = new Map();
+  const createdIndexes = new Set();
   for (const folder of orderedFolders) {
     const { title, description } = groupsByFolder.get(folder);
-    const pageDir = path.join(refDir, infoTitle, folder);
+    const actualFolder = foldersBySlug.get(folder) || folder;
+    const pageDir = path.join(refDir, infoTitle, actualFolder);
     if (!isWithin(refDir, pageDir)) continue;
+    groupDirs.set(folder, pageDir);
 
     const indexPath = path.join(pageDir, 'index.md');
     if (!fs.existsSync(indexPath)) {
@@ -495,15 +736,80 @@ function syncOneOas(refDir, oasFilename, spec, takenSlugs) {
       fs.mkdirSync(pageDir, { recursive: true });
       fs.writeFileSync(indexPath, buildTagIndexContent(title, description));
       changes.added.push(path.relative(refDir, indexPath));
+      createdIndexes.add(indexPath);
       // The category page's slug is the folder name; reserve it so no operation
       // takes it. Only when just-created — an existing index.md was already
       // counted by collectReferenceSlugs's initial disk walk.
-      takeSlug(takenSlugs, folder);
+      takeSlug(takenSlugs, actualFolder);
+    } else if (applyTagChanges) {
+      // With `apply-tag-changes`, the spec owns the category page's title and
+      // excerpt too (a tag with no description clears the excerpt). Its body
+      // and any other frontmatter are the user's and are kept.
+      const updated = updateFrontmatter(indexPath, (data) => {
+        data.title = title;
+        if (description) data.excerpt = description;
+        else delete data.excerpt;
+      });
+      if (updated) changes.updated.push(path.relative(refDir, indexPath));
     }
-    addToOrder(path.join(refDir, infoTitle, '_order.yaml'), folder);
+    addToOrder(path.join(refDir, infoTitle, '_order.yaml'), actualFolder);
     addToOrder(path.join(refDir, '_order.yaml'), infoTitle);
   }
 
+  // Where each of this spec's operations ends up this run, by operationKey.
+  const opPaths = new Map();
+  const vacatedDirs = new Set();
+
+  // Existing pages: by default they stay wherever they are. Two opt-ins can
+  // touch them: `x-internal` (visibility) and `apply-tag-changes` (placement).
+  for (const [key, op] of specOps) {
+    const page = pagesByOpId.get(key);
+    if (!page) continue;
+    let filePath = page.filePath;
+
+    // `apply-tag-changes`: a page still inside this API's category follows
+    // its tag's folder, even if it was hand-moved or nested elsewhere in the
+    // category. A page moved to another category is the user's call and is
+    // never touched. Legacy pages literally named index.md are left alone —
+    // moving one would turn it into the destination folder's category page.
+    const targetDir = groupDirs.get(operationGroup(op).folder);
+    if (
+      applyTagChanges &&
+      targetDir &&
+      isWithin(apiDir, filePath) &&
+      path.basename(filePath) !== 'index.md' &&
+      path.dirname(filePath) !== targetDir
+    ) {
+      const target = path.join(targetDir, path.basename(filePath));
+      if (fs.existsSync(target)) {
+        changes.skipped.push({ path: path.relative(refDir, target), operationId: op.operationId });
+      } else {
+        const fromDir = path.dirname(filePath);
+        const slug = path.basename(filePath, '.md');
+        fs.mkdirSync(targetDir, { recursive: true });
+        fs.renameSync(filePath, target);
+        removeFromOrder(path.join(fromDir, '_order.yaml'), slug);
+        addToOrder(path.join(targetDir, '_order.yaml'), slug);
+        vacatedDirs.add(fromDir);
+        changes.moved.push({ from: page.relativePath, to: path.relative(refDir, target) });
+        filePath = target;
+      }
+    }
+
+    // `x-internal`, when the spec sets it (operation or root), decides the
+    // page's visibility in both directions. When it's absent the page keeps
+    // its own `hidden` — removing the extension never unhides a page.
+    if (op.xInternal.present) {
+      const hidden = Boolean(op.xInternal.value);
+      const updated = updateFrontmatter(filePath, (data) => {
+        data.hidden = hidden;
+      });
+      if (updated) changes.updated.push(path.relative(refDir, filePath));
+    }
+
+    opPaths.set(key, filePath);
+  }
+
   // Adds: operation pages with no page yet. Title/excerpt are owned by the OAS
   // spec at render time, so generated pages carry only the api reference. Slugs
   // are lowercased to match the platform's OAS-upload output.
@@ -511,7 +817,7 @@ function syncOneOas(refDir, oasFilename, spec, takenSlugs) {
     if (pagesByOpId.has(key)) continue;
 
     const { folder } = operationGroup(op);
-    const pageDir = path.join(refDir, infoTitle, folder);
+    const pageDir = path.join(refDir, infoTitle, foldersBySlug.get(folder) || folder);
     // Reference slugs share one flat namespace, so uniquify against every slug
     // already in reference/ — a collision (or the reserved `index` slug) gets a
     // numeric suffix rather than being skipped.
@@ -526,14 +832,82 @@ function syncOneOas(refDir, oasFilename, spec, takenSlugs) {
     }
     fs.mkdirSync(pageDir, { recursive: true });
 
-    const content = buildPageContent({ oasFilename, operationId: op.operationId, isWebhook: op.isWebhook });
+    const content = buildPageContent({
+      oasFilename,
+      operationId: op.operationId,
+      isWebhook: op.isWebhook,
+      hidden: op.xInternal.present ? Boolean(op.xInternal.value) : false,
+    });
     fs.writeFileSync(pagePath, content);
 
     addToOrder(path.join(pageDir, '_order.yaml'), slug);
 
     changes.added.push(path.relative(refDir, pagePath));
+    opPaths.set(key, pagePath);
+  }
+
+  // `x-internal` on category pages: a folder whose operations are *all*
+  // internal gets its category page hidden too. This only ever hides — a
+  // category page is never unhidden by sync, so a manual `hidden: true`
+  // survives. Mirroring the platform, a category page created this run
+  // counts any truthy `x-internal`; an existing one needs an explicit `true`.
+  const childrenByDir = new Map();
+  for (const [key, filePath] of opPaths) {
+    const dir = path.dirname(filePath);
+    if (!childrenByDir.has(dir)) childrenByDir.set(dir, []);
+    childrenByDir.get(dir).push(specOps.get(key).xInternal);
+  }
+  for (const [dir, children] of childrenByDir) {
+    const indexPath = path.join(dir, 'index.md');
+    if (!fs.existsSync(indexPath)) continue;
+    const isNew = createdIndexes.has(indexPath);
+    const allHidden = children.every((x) => x.present && (isNew ? Boolean(x.value) : x.value === true));
+    if (!allHidden) continue;
+    const updated = updateFrontmatter(indexPath, (data) => {
+      data.hidden = true;
+    });
+    if (updated && !isNew) changes.updated.push(path.relative(refDir, indexPath));
   }
 
+  // Tag folders emptied by `apply-tag-changes` moves. Never the API's own
+  // category folder, and never a folder an operation still lives in.
+  for (const dir of vacatedDirs) {
+    if (!isWithin(apiDir, dir) || childrenByDir.has(dir)) continue;
+    cleanupTagFolder(dir, { refDir, specDescriptions, takenSlugs, changes });
+  }
+
+  // `apply-endpoint-order`: reorder each folder's operation pages to match
+  // the order they're declared in the spec (paths, then webhooks). Only this
+  // API's pages are reordered, and only among the `_order.yaml` slots they
+  // already hold — other entries keep their place. Files never move.
+  if (applyEndpointOrder) {
+    const orderByDir = new Map();
+    for (const key of specOps.keys()) {
+      const filePath = opPaths.get(key);
+      if (!filePath || !isWithin(apiDir, filePath)) continue;
+      // A legacy page named index.md is ordered in its parent, by folder name.
+      const isIndex = path.basename(filePath) === 'index.md';
+      const dir = isIndex ? path.dirname(path.dirname(filePath)) : path.dirname(filePath);
+      const slug = isIndex ? path.basename(path.dirname(filePath)) : path.basename(filePath, '.md');
+      if (!orderByDir.has(dir)) orderByDir.set(dir, []);
+      orderByDir.get(dir).push(slug);
+    }
+    for (const [dir, slugs] of orderByDir) {
+      const orderPath = path.join(dir, '_order.yaml');
+      const current = fs.existsSync(orderPath) ? parseOrderYaml(fs.readFileSync(orderPath, 'utf-8')) : [];
+      const next = applyOASOrder(current, slugs);
+      if (next.join('\n') === current.join('\n')) continue;
+      writeOrderYaml(orderPath, next);
+      changes.updated.push(path.relative(refDir, orderPath));
+    }
+  }
+
+  // Two passes can each touch the same tag page in one run (`apply-tag-changes`
+  // syncing its title/excerpt, then `x-internal` hiding it once every operation
+  // in it is internal). Report each file once so the printed list and the
+  // `updated-count` output reflect files, not writes.
+  changes.updated = [...new Set(changes.updated)];
+
   return changes;
 }
 
@@ -546,7 +920,8 @@ function syncOneOas(refDir, oasFilename, spec, takenSlugs) {
  *
  * @param {string | { cwd?: string }} input  Repo root path, or `{ cwd }` object.
  * @returns {null | Array<{ filename: string, spec: object, opCount: number,
- *   changes: { added: string[], deleted: string[] } }>}
+ *   changes: { added: string[], deleted: string[], moved: { from, to }[],
+ *   updated: string[], skipped: { path, operationId }[] } }>}
  *   Returns null if there's no reference/ dir or no specs.
  */
 export function syncOas(input) {
@@ -571,30 +946,34 @@ export function syncOas(input) {
   return allChanges;
 }
 
-export async function run(_options, _cmd, ctx) {
-  const { gitRoot } = ctx;
-  const refDir = path.join(gitRoot, 'reference');
-
-  if (!fs.existsSync(refDir)) {
-    styles.error('No reference/ directory found.');
-    process.exit(1);
-  }
-
-  const results = syncOas(gitRoot);
-
-  if (!results) {
-    styles.info('No OpenAPI spec files found in reference/.');
-    return;
-  }
-
+/**
+ * Print sync results per spec and return aggregate totals (used by the CLI
+ * command). Mirrors validateOasFiles in oas-validate.js: printing and
+ * summarizing is a presentation concern kept separate from syncOas's pure
+ * programmatic API above.
+ *
+ * @param {ReturnType<typeof syncOas>} results
+ * @returns {{ totalAdded: number, totalDeleted: number, totalMoved: number,
+ *   totalUpdated: number, totalSkipped: number,
+ *   skipped: Array<{ filename: string, path: string, operationId: string }> }}
+ */
+export function printSyncResults(results) {
   let totalAdded = 0;
   let totalDeleted = 0;
+  let totalMoved = 0;
+  let totalUpdated = 0;
   let totalSkipped = 0;
+  const skipped = [];
 
   for (const { filename, spec, opCount, changes } of results) {
     const title = spec.info?.title || filename;
     const hasChanges =
-      changes.added.length + changes.deleted.length + changes.skipped.length > 0;
+      changes.added.length +
+        changes.deleted.length +
+        changes.moved.length +
+        changes.updated.length +
+        changes.skipped.length >
+      0;
 
     const dot = hasChanges ? styles.warn('●') : styles.success('●');
     console.log();
@@ -610,25 +989,99 @@ export async function run(_options, _cmd, ctx) {
     for (const file of changes.deleted) {
       console.log(`    ${styles.err('−')} Deleted ${file}`);
     }
+    for (const { from, to } of changes.moved) {
+      console.log(`    ${styles.warn('→')} Moved ${from} to ${to}`);
+    }
+    for (const file of changes.updated) {
+      console.log(`    ${styles.warn('~')} Updated ${file}`);
+    }
     for (const { path: file, operationId } of changes.skipped) {
       console.log(
         `    ${styles.warn('!')} Skipped ${file} for "${operationId}" (destination already exists)`,
       );
+      skipped.push({ filename, path: file, operationId });
     }
 
     totalAdded += changes.added.length;
     totalDeleted += changes.deleted.length;
+    totalMoved += changes.moved.length;
+    totalUpdated += changes.updated.length;
     totalSkipped += changes.skipped.length;
   }
 
+  return { totalAdded, totalDeleted, totalMoved, totalUpdated, totalSkipped, skipped };
+}
+
+export async function run(_options, _cmd, ctx) {
+  const { gitRoot } = ctx;
+  const refDir = path.join(gitRoot, 'reference');
+
+  if (!fs.existsSync(refDir)) {
+    styles.error('No reference/ directory found.');
+    writeGithubActionsOutputs({
+      'added-count': '0',
+      'deleted-count': '0',
+      'moved-count': '0',
+      'updated-count': '0',
+      'skipped-count': '0',
+      skipped: [],
+      'has-errors': 'true',
+    });
+    process.exit(1);
+  }
+
+  const results = syncOas(gitRoot);
+
+  if (!results) {
+    styles.info('No OpenAPI spec files found in reference/.');
+    writeGithubActionsOutputs({
+      'added-count': '0',
+      'deleted-count': '0',
+      'moved-count': '0',
+      'updated-count': '0',
+      'skipped-count': '0',
+      skipped: [],
+      'has-errors': 'false',
+    });
+    return;
+  }
+
+  const { totalAdded, totalDeleted, totalMoved, totalUpdated, totalSkipped, skipped } =
+    printSyncResults(results);
+
   console.log();
-  const total = totalAdded + totalDeleted;
-  const skippedNote = totalSkipped > 0 ? `, ${totalSkipped} skipped` : '';
-  if (total === 0 && totalSkipped === 0) {
-    styles.ok('Reference pages are already in sync.');
+  const total = totalAdded + totalDeleted + totalMoved + totalUpdated;
+  const extra = [
+    totalMoved > 0 ? `${totalMoved} moved` : null,
+    totalUpdated > 0 ? `${totalUpdated} updated` : null,
+  ].filter(Boolean);
+  const extraNote = extra.length ? `, ${extra.join(', ')}` : '';
+  // A skip means a page couldn't be written where it should've gone — either
+  // a spec-crafted path trying to escape reference/, or the destination
+  // already existing in a way sync's own bookkeeping didn't expect. Neither
+  // is something to quietly succeed past, so this fails the same way lint
+  // and oas:validate already fail on a real problem, rather than leaving it
+  // to whoever wraps this command in CI to notice and fail on it themselves.
+  if (totalSkipped > 0) {
+    const syncedNote = total > 0 ? ` (${totalAdded} added, ${totalDeleted} deleted${extraNote})` : '';
+    styles.error(`${totalSkipped} ${totalSkipped === 1 ? 'page' : 'pages'} skipped${syncedNote} — see above for which, and why.`);
   } else if (total === 0) {
-    styles.warning(`No pages synced; ${totalSkipped} skipped (destination already exists).`);
+    styles.ok('Reference pages are already in sync.');
   } else {
-    styles.ok(`Synced: ${totalAdded} added, ${totalDeleted} deleted${skippedNote}.`);
+    styles.ok(`Synced: ${totalAdded} added, ${totalDeleted} deleted${extraNote}.`);
+  }
+
+  writeGithubActionsOutputs({
+    'added-count': String(totalAdded),
+    'deleted-count': String(totalDeleted),
+    'moved-count': String(totalMoved),
+    'updated-count': String(totalUpdated),
+    'skipped-count': String(totalSkipped),
+    skipped,
+    'has-errors': String(totalSkipped > 0),
+  });
+
+  if (totalSkipped > 0) {
+    process.exit(1);
   }
 }

package/src/commands/oas-validate.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import OASNormalize from 'oas-normalize';
 import { findOasFiles, extractOperations } from './oas-sync.js';
 import * as styles from '../utils/styles.js';
+import { writeGithubActionsOutputs } from '../utils/gha-output.js';
 
 export const command = 'oas:validate';
 export const order = 3;
@@ -182,6 +183,13 @@ export async function run(options, _cmd, ctx) {
 
   if (!fs.existsSync(refDir)) {
     styles.error('No reference/ directory found.');
+    writeGithubActionsOutputs({
+      'has-errors': 'true',
+      'total-errors': '0',
+      'total-warnings': '0',
+      'total-valid': '0',
+      'file-count': '0',
+    });
     process.exit(1);
   }
 
@@ -189,11 +197,26 @@ export async function run(options, _cmd, ctx) {
 
   if (!result) {
     styles.info('No OpenAPI spec files found in reference/.');
+    writeGithubActionsOutputs({
+      'has-errors': 'false',
+      'total-errors': '0',
+      'total-warnings': '0',
+      'total-valid': '0',
+      'file-count': '0',
+    });
     return;
   }
 
   const { totalErrors, totalWarnings, totalValid, fileCount } = result;
 
+  writeGithubActionsOutputs({
+    'has-errors': String(totalErrors > 0),
+    'total-errors': String(totalErrors),
+    'total-warnings': String(totalWarnings),
+    'total-valid': String(totalValid),
+    'file-count': String(fileCount),
+  });
+
   console.log();
   if (totalErrors > 0) {
     const parts = [`${totalErrors} ${totalErrors === 1 ? 'error' : 'errors'}`];

package/src/gha-pre.js

@@ -0,0 +1,29 @@
+// Pre step for the readmeio/cli GitHub Action (see action.yml's runs.pre).
+//
+// dist-gha/index.js (built by the build:gha script) excludes @readme/markdown
+// from its bundle: it's a ~25MB package with 50+ dependencies (including
+// tailwindcss and postcss) pulled in for one narrow helper the "lint" command
+// uses, mdxishTags, and bundling it whole breaks on its embedded CSS/asset
+// references. Rather than vendoring that whole tree into this repo, this step
+// installs just that one package into the action's own directory immediately
+// before dist-gha/index.js runs, so plain Node module resolution finds it.
+//
+// GITHUB_ACTION_PATH looked like the natural way to find that directory (and
+// is what a version of this file first tried), but it came back undefined
+// when actually tested on a real Actions runner. import.meta.dirname doesn't
+// depend on the runner setting anything at all -- it's just "where is this
+// file" -- and it's the same approach readmeio/rdme's own pre-step
+// (bin/write-gha-pjson.js) already uses.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+const actionPath = path.resolve(import.meta.dirname, '..');
+const pkg = JSON.parse(readFileSync(path.join(actionPath, 'package.json'), 'utf-8'));
+const range = pkg.dependencies['@readme/markdown'];
+
+execFileSync(
+  'npm',
+  ['install', '--no-save', '--no-audit', '--no-fund', '--prefix', actionPath, `@readme/markdown@${range}`],
+  { stdio: 'inherit' },
+);

package/src/gha.js

@@ -0,0 +1,104 @@
+// Entrypoint for the readmeio/cli GitHub Action. Deliberately does NOT go
+// through src/cli.js — that bootstraps the full CLI by scanning src/commands/
+// on disk at runtime (fs.readdirSync + dynamic import), which a bundler can't
+// follow statically. This file instead imports just the three commands the
+// Action exposes directly, so `ncc build` can produce one dependency-free
+// file with no runtime install step (see package.json's build:gha script).
+//
+// Takes one input, `readme` (env var INPUT_README per GitHub Actions'
+// convention), a plain command string such as "lint" or
+// "oas:validate --dereference". Split into a command name and flags; there's
+// no need for a full argument parser since each of these three commands only
+// ever takes simple boolean flags.
+//
+// Each command's own run() already writes its structured results (has-errors,
+// skipped-count, etc.) to GITHUB_OUTPUT itself, via utils/gha-output.js's
+// GITHUB_ACTIONS-detecting helper — so this file just needs to call run() and
+// let it do what it already does, exit code included.
+
+import * as lint from './commands/lint.js';
+import * as oasValidate from './commands/oas-validate.js';
+import * as oasSync from './commands/oas-sync.js';
+import { writeGithubActionsOutputs } from './utils/gha-output.js';
+
+// Each command's run(options, cmd, ctx) only ever reads specific boolean
+// flags off `options` (confirmed by reading all three) and never uses `cmd`
+// (the commander Command instance normal CLI invocation would pass) — so a
+// plain options object and a null cmd are enough here.
+const COMMANDS = {
+  'lint': { run: lint.run, flags: ['json', 'github', 'fix'] },
+  'validate': { run: lint.run, flags: ['json', 'github', 'fix'] }, // alias, matches src/commands/lint.js
+  'oas:validate': { run: oasValidate.run, flags: ['dereference'] },
+  'oas:sync': { run: oasSync.run, flags: [] },
+};
+
+function parseInput(input) {
+  const tokens = input.trim().split(/\s+/).filter(Boolean);
+  const [command, ...rest] = tokens;
+  return { command, rest };
+}
+
+export async function run() {
+  const input = process.env.INPUT_README || '';
+  const { command, rest } = parseInput(input);
+
+  const entry = COMMANDS[command];
+  if (!entry) {
+    console.error(
+      `::error::Unknown or unsupported command "${command || '(empty)'}" for the \`readme\` input. ` +
+        `Supported: ${[...new Set(Object.keys(COMMANDS).filter((k) => k !== 'validate'))].join(', ')}.`,
+    );
+    writeGithubActionsOutputs({ 'has-errors': 'true' });
+    process.exit(1);
+  }
+
+  // Every trailing token must be exactly "--<a supported flag>" — anything
+  // else (a short option like "-d", a malformed token, a misspelled flag)
+  // is rejected rather than silently dropped. An earlier version of this
+  // only checked tokens that already happened to start with "--", which let
+  // anything shaped differently (like "-d") skip validation entirely and
+  // run the command with default options with no indication anything was
+  // wrong.
+  const flags = new Set();
+  const badTokens = [];
+  for (const token of rest) {
+    const flag = token.startsWith('--') ? token.slice(2) : null;
+    if (flag && entry.flags.includes(flag)) {
+      flags.add(flag);
+    } else {
+      badTokens.push(token);
+    }
+  }
+
+  if (badTokens.length > 0) {
+    console.error(
+      `::error::Unknown option${badTokens.length > 1 ? 's' : ''} ${badTokens.map((t) => `"${t}"`).join(', ')} for "${command}". ` +
+        `Supported: ${entry.flags.length > 0 ? entry.flags.map((f) => `--${f}`).join(', ') : '(none)'}.`,
+    );
+    writeGithubActionsOutputs({ 'has-errors': 'true' });
+    process.exit(1);
+  }
+
+  const options = {};
+  for (const flag of entry.flags) options[flag] = flags.has(flag);
+
+  // The customer's repo, checked out by their own workflow before this
+  // action runs — not this action's own (separately checked-out) source.
+  const gitRoot = process.env.GITHUB_WORKSPACE || process.cwd();
+
+  await entry.run(options, null, { gitRoot });
+}
+
+run().catch((err) => {
+  console.error(err);
+  // A thrown error (as opposed to a command's own controlled process.exit)
+  // means whatever run() was doing never reached its own
+  // writeGithubActionsOutputs call, so this is the last chance to publish
+  // has-errors — without it, a downstream `if: always()` step would see an
+  // empty string, on exactly the failure path where that check matters
+  // most. Command-specific fields (skipped-count, results, etc.) aren't
+  // meaningful here since they were never computed, so has-errors is all
+  // this can honestly guarantee.
+  writeGithubActionsOutputs({ 'has-errors': 'true' });
+  process.exit(1);
+});

package/src/utils/gha-output.js

@@ -0,0 +1,32 @@
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+
+/**
+ * Writes each field as a GitHub Actions step output, so a workflow can read
+ * e.g. `steps.sync.outputs.skipped-count` instead of scraping printed text.
+ * A no-op anywhere else (a plain local CLI run, or CI systems other than
+ * GitHub Actions), detected the same way GitHub's own `@actions/core`
+ * toolkit does: the `GITHUB_ACTIONS` env var GitHub sets on every runner,
+ * plus the `GITHUB_OUTPUT` file path it provides for the current step.
+ *
+ * @param {Record<string, string | object | Array<unknown>>} fields  Values are
+ *   written as-is if already a string, JSON-stringified otherwise.
+ */
+export function writeGithubActionsOutputs(fields) {
+  if (process.env.GITHUB_ACTIONS !== 'true') return;
+  const outputPath = process.env.GITHUB_OUTPUT;
+  if (!outputPath) return;
+
+  const lines = Object.entries(fields).map(([name, value]) => {
+    const text = typeof value === 'string' ? value : JSON.stringify(value);
+    // A random delimiter, rather than a fixed one like "EOF", matters here:
+    // `value` can echo back content from a customer's own docs/OAS files
+    // (an error message quoting their spec, say), and a guessable delimiter
+    // could let that content prematurely close the heredoc and inject extra
+    // key=value pairs into the outputs file.
+    const delimiter = `ghadelimiter_${randomUUID()}`;
+    return `${name}<<${delimiter}\n${text}\n${delimiter}`;
+  });
+
+  fs.appendFileSync(outputPath, `${lines.join('\n')}\n`);
+}

package/src/utils/lint.js

@@ -1,6 +1,15 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { pathToFileURL, fileURLToPath } from 'node:url'
+import * as componentsValidator from '../validators/components.js'
+import * as contentValidator from '../validators/content.js'
+import * as duplicatesValidator from '../validators/duplicates.js'
+import * as frontmatterValidator from '../validators/frontmatter.js'
+import * as linksValidator from '../validators/links.js'
+import * as nestingValidator from '../validators/nesting.js'
+import * as oasReferenceValidator from '../validators/oas-reference.js'
+import * as oasSchemaValidator from '../validators/oas-schema.js'
+import * as orderingValidator from '../validators/ordering.js'
+import * as recipesValidator from '../validators/recipes.js'
 
 const TARGET_PATTERNS = [
   { dir: 'custom_blocks', ext: ['.mdx', '.md'] },
@@ -32,24 +41,30 @@ export function collectFiles(gitRoot) {
   return files.sort()
 }
 
+// Every validator in src/validators/, imported statically (rather than
+// discovered via a runtime directory scan) so this file — and anything that
+// imports it, like the GitHub Action entrypoint in src/gha.js — can be
+// bundled into a single file by a tool like ncc. Add a new validator's
+// import above and its module here.
+const ALL_VALIDATORS = [
+  componentsValidator,
+  contentValidator,
+  duplicatesValidator,
+  frontmatterValidator,
+  linksValidator,
+  nestingValidator,
+  oasReferenceValidator,
+  oasSchemaValidator,
+  orderingValidator,
+  recipesValidator,
+]
+
 /**
- * Auto-discover all validators from src/validators/.
  * Validators can export `validate()` for per-file checks and/or
  * `validateAll()` for cross-file checks (like ordering).
  */
-async function loadValidators() {
-  const validatorsDir = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'validators')
-  const files = fs.readdirSync(validatorsDir).filter((f) => f.endsWith('.js'))
-  const validators = []
-
-  for (const file of files) {
-    const mod = await import(pathToFileURL(path.join(validatorsDir, file)).href)
-    if (mod.name && (mod.validate || mod.validateAll)) {
-      validators.push(mod)
-    }
-  }
-
-  return validators
+function loadValidators() {
+  return ALL_VALIDATORS.filter((mod) => mod.name && (mod.validate || mod.validateAll))
 }
 
 /**

package/src/validators/oas-reference.js

@@ -1,7 +1,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import matter from 'gray-matter';
-import { findOasFiles, extractOperations, collectExistingPages, syncOas, operationKey } from '../commands/oas-sync.js';
+import {
+  findOasFiles,
+  extractOperations,
+  collectExistingPages,
+  syncOas,
+  operationKey,
+  findIgnoredInternalExtensions,
+} from '../commands/oas-sync.js';
 
 export const name = 'oas-reference';
 
@@ -16,6 +23,17 @@ export function validateAll(files, gitRoot, { fix } = {}) {
   const oasMap = new Map();
   for (const { filename, spec } of oasFiles) {
     oasMap.set(filename, { spec, ops: extractOperations(spec) });
+
+    // Check: `x-readme.internal`, which ReadMe ignores for page visibility.
+    for (const location of findIgnoredInternalExtensions(spec)) {
+      results.push({
+        file: `reference/${filename}`,
+        rule: name,
+        severity: 'warning',
+        message: `"x-readme.internal" is ignored by ReadMe (${location}); use "x-internal" instead to hide pages`,
+        fixable: false,
+      });
+    }
   }
 
   // Collect all reference pages with api frontmatter.
@@ -87,8 +105,11 @@ export function validateAll(files, gitRoot, { fix } = {}) {
     }
   }
 
-  // Apply fixes by running the full sync.
-  if (fix && results.length > 0) {
+  // Apply fixes by running the full sync — but only when something reported
+  // is actually fixable. The sync adds, deletes, moves, hides and reorders
+  // reference files, which is far too much to do on the strength of an
+  // unfixable warning (`x-readme.internal`, a page pointing at a missing spec).
+  if (fix && results.some((r) => r.fixable)) {
     const syncResults = syncOas(gitRoot);
     if (syncResults) {
       for (const r of results) {