@readme/cli 0.0.31 → 0.1.0

package/README.md

@@ -24,6 +24,16 @@ Syncs your `reference/` directory with your OpenAPI spec. It'll create, update,
 npx @readme/cli oas:sync
 ```
 
+### OpenAPI Bundle
+
+Combines a spec that's split across multiple files (external `$ref`s to partials) into a single self-contained file. Handy when your spec is assembled at build time and you want to drop the result into `reference/` from CI.
+
+```bash
+npx @readme/cli oas:bundle path/to/openapi.yaml --out reference/api.json
+```
+
+Without `--out`, the bundled spec is printed to stdout. The output format follows the `--out` extension (`.yaml`/`.yml` for YAML, JSON otherwise). This command works from any directory, so you can run it in your API's source repo.
+
 ### Import
 
 Imports content from an external folder and converts it into ReadMe's format using Claude. Great for migrating existing docs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readme/cli",
-  "version": "0.0.31",
+  "version": "0.1.0",
   "description": "The ReadMe CLI",
   "type": "module",
   "bin": {
@@ -44,6 +44,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.207",
     "@readme/markdown": "^13.3.0",
+    "@readme/openapi-parser": "^5.5.0",
     "@readmeio/git-format": "git+https://github.com/readmeio/git-format.git",
     "ajv": "^8.18.0",
     "chalk": "^5.4.1",

package/src/commands/import.js

@@ -30,6 +30,13 @@ export const skipBootstrap = true
 
 export const DEFAULT_MODEL = 'claude-sonnet-5'
 
+export function getClaudeReasoningOptions(model) {
+  if (model === 'sonnet' || model === DEFAULT_MODEL || model?.startsWith('claude-sonnet-5-')) {
+    return { thinking: { type: 'adaptive' }, effort: 'medium' }
+  }
+  return {}
+}
+
 export function args(cmd) {
   cmd.requiredOption(
     '--source <url-or-file...>',
@@ -39,10 +46,6 @@ export function args(cmd) {
   cmd.addOption(new Option('-m, --model <name>', 'Claude model alias: haiku, sonnet, opus').choices(['haiku', 'sonnet', 'opus']).default(DEFAULT_MODEL))
   cmd.option('--firecrawl-key <key>', 'Firecrawl API key (or set FIRECRAWL_API_KEY env var) — enables JS-rendered sidebar scraping')
   cmd.option('--skip-api-reference', 'Drop pages routed to the API Reference / reference dir. Use when uploading the OAS spec separately.')
-  cmd.option(
-    '--separate-changelog',
-    'Move changelog / release-notes pages into a top-level changelog/ directory instead of docs/Changelog/. Note: changelog/ is outside the git-format schema, so it will not lint or sync to ReadMe.',
-  )
   // Internal dev-only flag: skip the zip, keep staging, and boot the dev server
   // against it for quick visual previews. Hidden from --help.
   cmd.addOption(new Option('--test').hideHelp())
@@ -96,7 +99,6 @@ const OAS_SOURCE_CONFIDENCE = ['llms', 'mintlify', 'probe', 'html', 'sitemap', '
  * @param {string} [options.model]            Claude model alias: 'haiku' | 'sonnet' | 'opus'. Defaults to 'sonnet'.
  * @param {string} [options.firecrawlKey]     Firecrawl API key (falls back to FIRECRAWL_API_KEY env var).
  * @param {boolean} [options.skipApiReference] Drop pages routed to the API Reference dir.
- * @param {boolean} [options.separateChangelog] Move changelog pages into a top-level `changelog/` dir instead of `docs/Changelog/`.
  * @param {boolean} [options.test]            Skip the zip, keep staging, and boot the dev server.
  * @param {boolean} [options.debug]           Dump intermediate pipeline artifacts to a tmp dir.
  * @returns {Promise<{ source: 'url' | 'oas', outputZip?: string, stagingDir?: string, fileCount: number, duration: number, phases: Array<{ label: string, ms: number }> }>}
@@ -211,17 +213,11 @@ export async function importDocs(options) {
       stageOrganized(organized, stagingDir, { skipApiReference: !!options.skipApiReference, llmsPaths }),
     )
 
-    // Changelog pages stage into docs/Changelog/ (a schema-valid docs
-    // category). With --separate-changelog, relocate them afterwards into a
-    // top-level changelog/ dir — done as a post-staging move so the staged
-    // tree is a valid git-format layout up to this point.
-    if (options.separateChangelog) {
-      const movedChangelog = relocateChangelogDir(stagingDir)
-      if (movedChangelog > 0) {
-        styles.info(
-          `Moved ${styles.bold(String(movedChangelog))} changelog page${movedChangelog === 1 ? '' : 's'} into ${styles.bold('changelog/')} (--separate-changelog).`,
-        )
-      }
+    const movedChangelog = finalizeChangelogs(stagingDir)
+    if (movedChangelog > 0) {
+      styles.info(
+        `Staged ${styles.bold(String(movedChangelog))} changelog page${movedChangelog === 1 ? '' : 's'} in ${styles.bold('changelogs/')}.`,
+      )
     }
 
     const landingTitle =
@@ -442,9 +438,8 @@ async function produceOrganizedForSource(sourceUrl, options, timePhase, debugSna
 
   // Pre-extract changelog pages so AI / URL clustering / section-direct paths
   // never see them as candidates for organization. We re-attach them as a
-  // dedicated Changelog category once `organized` is finalized below — that
-  // guarantees they route to docs/Changelog/ (or to changelog/ with
-  // --separate-changelog) regardless of which organize path ran. Done here,
+  // dedicated Changelog category once `organized` is finalized below. Done
+  // here,
   // before knownUrls is derived, so every downstream consumer operates on the
   // already-changelog-free view.
   let extractedChangelog = []
@@ -657,8 +652,7 @@ async function produceOrganizedForSource(sourceUrl, options, timePhase, debugSna
       }
 
       // Same idea for changelog / release-notes pages — pull any whose URL
-      // carries a changelog-style segment into one "Changelog" category. It
-      // routes to docs/Changelog/ unless --separate-changelog relocates it.
+      // carries a changelog-style segment into one "Changelog" category.
       const movedChangelog = reclassifyChangelogPages(scraped)
       if (movedChangelog > 0) {
         styles.info(`Moved ${styles.bold(String(movedChangelog))} page${movedChangelog === 1 ? '' : 's'} into ${styles.bold('Changelog')} based on URL path.`)
@@ -1210,6 +1204,7 @@ export async function runAgent({ userPrompt, systemPrompt, cwd, model }) {
       canUseTool: makeStagingGuard(cwd),
       ...(systemPrompt ? { systemPrompt } : {}),
       ...(model ? { model } : {}),
+      ...getClaudeReasoningOptions(model),
     },
   })) {
     if (message.type === 'assistant' && message.message?.content) {
@@ -1222,7 +1217,8 @@ export async function runAgent({ userPrompt, systemPrompt, cwd, model }) {
       }
     } else if (message.type === 'result') {
       if (message.subtype && message.subtype !== 'success') {
-        const err = new Error(`Agent result subtype=${message.subtype}${message.error?.message ? ': ' + message.error.message : ''}`)
+        const details = claudeResultDetails(message)
+        const err = new Error(`Agent result subtype=${message.subtype}${details ? ` — ${details}` : ''}`)
         err.subtype = message.subtype
         err.result = message
         throw err
@@ -2741,9 +2737,8 @@ function injectChangelogCategory(organized, items) {
 /**
  * Sweep `/changelog/*`, `/release-notes/*` and `/releases/*` pages into one
  * "Changelog" category, wherever the site's sidebar happened to place them.
- * That category routes to `docs/Changelog/`; `--separate-changelog` later
- * relocates it to a top-level `changelog/` dir. Returns the number of pages
- * relocated.
+ * It is finalized as canonical top-level `changelogs/` output. Returns the
+ * number of pages relocated.
  */
 function reclassifyChangelogPages(scraped) {
   return reclassifyPagesByUrlSegment(scraped, {
@@ -3701,6 +3696,34 @@ async function organizeFromScratch(parsed, model) {
   return { title: raw.title, categories: expandedCategories }
 }
 
+function claudeResultDetails(message) {
+  const details = []
+  if (message.api_error_status != null) details.push(`API status ${message.api_error_status}`)
+  if (Array.isArray(message.errors)) details.push(...message.errors.filter((error) => typeof error === 'string' && error.trim()))
+  if (typeof message.result === 'string' && message.result.trim()) {
+    const result = message.result.replace(/\s+/g, ' ').trim()
+    details.push(result.length > 1000 ? `${result.slice(0, 1000)}…` : result)
+  }
+  return details.join('; ')
+}
+
+export function getStructuredOutput(message) {
+  const details = claudeResultDetails(message)
+  if (message.subtype === 'error_max_structured_output_retries') {
+    throw new Error(
+      'Claude could not produce output matching the schema after retries. ' +
+      `Likely hit the model's output limit — try --model sonnet.${details ? ` ${details}` : ''}`,
+    )
+  }
+  if (message.subtype && message.subtype !== 'success') {
+    throw new Error(`Claude failed: ${message.subtype}${details ? ` — ${details}` : ''}`)
+  }
+  if (!message.structured_output || typeof message.structured_output !== 'object') {
+    throw new Error(`Claude returned no structured output${details ? ` — ${details}` : ''}`)
+  }
+  return message.structured_output
+}
+
 /**
  * Shared Claude call for "send a prompt, get schema-validated JSON back".
  * Logs the prompts so we can see what went in, and runs a heartbeat so silent
@@ -3731,19 +3754,11 @@ async function runJsonQuery({ systemPrompt, userPrompt, model, schema }) {
         allowedTools: [],
         outputFormat: { type: 'json_schema', schema },
         ...(model ? { model } : {}),
+        ...getClaudeReasoningOptions(model),
       },
     })) {
       if (message.type === 'result') {
-        if (message.subtype === 'error_max_structured_output_retries') {
-          throw new Error(
-            'Claude could not produce output matching the schema after retries. ' +
-            'Likely hit the model\'s output limit — try --model sonnet.',
-          )
-        }
-        if (message.subtype && message.subtype !== 'success') {
-          throw new Error(`Claude failed: ${message.subtype}${message.error?.message ? ' — ' + message.error.message : ''}`)
-        }
-        structured = message.structured_output
+        structured = getStructuredOutput(message)
         break
       }
     }
@@ -4777,7 +4792,8 @@ function stageOrganized(organized, stagingDir, opts = {}) {
   for (const cat of eligibleCategories) collapseRedundantLayers(cat)
 
   // Slug names must be unique
-  const slugFor = ensureUniqueSlugs(eligibleCategories)
+  const slugFor = opts.slugFor || ensureUniqueSlugs(eligibleCategories)
+  disambiguateChangelogSiblingSlugs(eligibleCategories, slugFor)
 
   const labelFor = (p) => {
     if (p.url) return p.url
@@ -4945,31 +4961,80 @@ function countPagesDeep(pages) {
 }
 
 /**
- * Post-staging relocation for `--separate-changelog`: move the staged
- * `docs/Changelog/` category up to a top-level `changelog/` directory.
+ * Make changelog sibling slugs safe to write on case-insensitive filesystems.
+ * Guides retain their directory hierarchy, while changelogs are later flattened
+ * into one directory; the final flattening pass handles cross-level collisions.
  *
- * Done as a filesystem move *after* staging (rather than routing there
- * directly) so the staged tree is a valid git-format layout up to this point,
- * and the one schema-divergent step lives in a single, clearly-named place.
- * Note `changelog/` is not part of the git-format schema — it won't lint or
- * sync to ReadMe until git-format adds first-class changelog support.
+ * @param {Array<{ title?: string, pages?: object[] }>} categories Organized import categories.
+ * @param {Map<object, string>} slugFor Slugs keyed by page; mutated in place.
+ * @returns {void}
+ */
+function disambiguateChangelogSiblingSlugs(categories, slugFor) {
+  const changelogPages = []
+  for (const category of categories) {
+    const route = routeCategory(category.title)
+    if (route.topDir !== 'docs' || route.subDir !== 'Changelog') continue
+    changelogPages.push(...(category.pages || []))
+  }
+
+  const planSiblings = (pages) => {
+    const plannedPages = pages.filter((page) => slugFor.has(page))
+    const plannedSlugs = allocateChangelogFilenames(
+      plannedPages.map((page) => ({ ancestors: [], slug: slugFor.get(page) })),
+    )
+    for (const [index, page] of plannedPages.entries()) slugFor.set(page, plannedSlugs[index])
+    for (const page of pages) planSiblings(page.pages || [])
+  }
+  planSiblings(changelogPages)
+}
+
+/**
+ * Allocate case-insensitively unique filenames for a flat changelog directory.
  *
- * Returns the number of changelog pages moved (0 if there were none).
+ * @param {Array<{ ancestors: string[], slug: string }>} pages Changelog paths to flatten.
+ * @returns {string[]} Filenames in the same order as `pages`, without extensions.
  */
-function relocateChangelogDir(stagingDir) {
+function allocateChangelogFilenames(pages) {
+  const baseSlugs = pages.map((page) => [...page.ancestors, page.slug].join('-'))
+  const baseNames = baseSlugs.map((slug) => slug.toLowerCase())
+  const counts = new Map()
+  for (const name of baseNames) counts.set(name, (counts.get(name) || 0) + 1)
+
+  const reserved = new Set(baseNames)
+  const allocated = new Set()
+  return baseSlugs.map((baseSlug, index) => {
+    const baseName = baseNames[index]
+    if (counts.get(baseName) === 1 || !allocated.has(baseName)) {
+      allocated.add(baseName)
+      return baseSlug
+    }
+
+    for (let suffix = 2; ; suffix++) {
+      const filename = `${baseSlug}-${suffix}`
+      const name = filename.toLowerCase()
+      if (reserved.has(name) || allocated.has(name)) continue
+      allocated.add(name)
+      return filename
+    }
+  })
+}
+
+/**
+ * Convert the staged changelog category into the runner's canonical, flat
+ * `changelogs/` skeleton directory. This happens for every import so neither
+ * command-line nor programmatic callers can produce the legacy layout.
+ */
+function finalizeChangelogs(stagingDir) {
   const srcDir = path.join(stagingDir, 'docs', 'Changelog')
   if (!fs.existsSync(srcDir) || !fs.statSync(srcDir).isDirectory()) return 0
 
-  const dstDir = path.join(stagingDir, 'changelog')
+  const dstDir = path.join(stagingDir, 'changelogs')
   fs.renameSync(srcDir, dstDir)
 
-  // Collect every real x-import page from the (possibly nested) tree.
-  // Synthetic group-only stubs (no x-import — they exist only to render an
-  // empty parent in the sidebar) are dropped: the flat layout has no concept
-  // of containers, so they'd just be dead frontmatter.
   const pages = []
   const walk = (dir, ancestors) => {
-    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    for (const entry of entries) {
       const full = path.join(dir, entry.name)
       if (entry.isDirectory()) {
         walk(full, [...ancestors, entry.name])
@@ -4977,44 +5042,32 @@ function relocateChangelogDir(stagingDir) {
       }
       if (!entry.name.endsWith('.md')) continue
       const parsed = matter(fs.readFileSync(full, 'utf-8'))
-      if (!parsed.data || !parsed.data['x-import']) continue
+      if (!parsed.data?.['x-import']) continue
       if (entry.name === 'index.md' && ancestors.length > 0) {
         pages.push({ ancestors: ancestors.slice(0, -1), slug: ancestors.at(-1), content: parsed.content, data: parsed.data })
         continue
       }
-      const slug = entry.name.replace(/\.md$/, '')
-      pages.push({ ancestors, slug, content: parsed.content, data: parsed.data })
+      pages.push({ ancestors, slug: entry.name.replace(/\.md$/, ''), content: parsed.content, data: parsed.data })
     }
   }
   walk(dstDir, [])
 
-  // Wipe the nested tree and rewrite it flat. Filename concatenates the
-  // ancestor folder slugs with the leaf slug so siblings share a prefix —
-  // alphabetical order then naturally matches authored reading order, and
-  // names are unique across the (formerly nested) tree.
   fs.rmSync(dstDir, { recursive: true, force: true })
   fs.mkdirSync(dstDir, { recursive: true })
 
-  const flatSlugs = []
-  for (const p of pages) {
-    const flatSlug = [...p.ancestors, p.slug].join('-')
-    const frontmatter = { ...p.data }
+  for (const [index, filename] of allocateChangelogFilenames(pages).entries()) {
+    const page = pages[index]
+    const frontmatter = { ...page.data }
     delete frontmatter.icon
-    fs.writeFileSync(path.join(dstDir, `${flatSlug}.md`), matter.stringify(p.content, frontmatter))
-    flatSlugs.push(flatSlug)
+    fs.writeFileSync(path.join(dstDir, `${filename}.md`), matter.stringify(page.content, frontmatter))
   }
 
-  flatSlugs.sort()
-  fs.writeFileSync(path.join(dstDir, '_order.yaml'), flatSlugs.map((s) => `- ${yamlSafeSlug(s)}`).join('\n') + '\n')
-
-  // docs/_order.yaml lists the docs category subfolders — drop the moved one
-  // so the docs sidebar doesn't point at a folder that's no longer there.
   const docsOrderPath = path.join(stagingDir, 'docs', '_order.yaml')
   if (fs.existsSync(docsOrderPath)) {
     const entries = yamlRequire().load(fs.readFileSync(docsOrderPath, 'utf-8'))
-    const filtered = Array.isArray(entries) ? entries.filter((e) => e !== 'Changelog') : []
+    const filtered = Array.isArray(entries) ? entries.filter((entry) => entry !== 'Changelog') : []
     if (filtered.length > 0) {
-      fs.writeFileSync(docsOrderPath, filtered.map((s) => `- ${yamlSafeSlug(s)}`).join('\n') + '\n')
+      fs.writeFileSync(docsOrderPath, filtered.map((entry) => `- ${yamlSafeSlug(entry)}`).join('\n') + '\n')
     } else {
       fs.rmSync(docsOrderPath)
     }
@@ -5030,8 +5083,8 @@ function relocateChangelogDir(stagingDir) {
 function routeCategory(title) {
   const t = (title || '').trim()
   if (/^(api[ -]?reference|reference|api|endpoints?)$/i.test(t)) return { topDir: 'reference', subDir: null }
-  // Changelog-ish categories normalize to one docs/Changelog/ folder so the
-  // --separate-changelog relocation has a single, predictable source dir.
+  // Changelog categories initially share a staging folder before they are
+  // finalized as canonical top-level changelogs/ output.
   if (/^(changelog|change[ -]?log|release[ -]?notes?|releases?|what'?s[ -]?new)$/i.test(t)) return { topDir: 'docs', subDir: 'Changelog' }
   if (/^(recipes?|cookbook|tutorials?|how[ -]?tos?)$/i.test(t)) return { topDir: 'recipes', subDir: null }
   if (/^(custom[ -]?pages?|landing( page)?s?)$/i.test(t)) return { topDir: 'custom_pages', subDir: null }
@@ -5327,6 +5380,8 @@ export const __test__ = {
   isDocsUnderApiPath,
   filterUrlPagesTree,
   stageOrganized,
+  finalizeChangelogs,
+  allocateChangelogFilenames,
   urlIsApiReference,
   urlIsChangelog,
   reclassifyReferencePages,

package/src/commands/import.staging.test.js

@@ -4,9 +4,10 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import matter from 'gray-matter'
-import { __test__ } from './import.js'
+import { Command } from 'commander'
+import { args, __test__ } from './import.js'
 
-const { stageOrganized } = __test__
+const { stageOrganized, finalizeChangelogs, allocateChangelogFilenames } = __test__
 
 const originalLog = console.log
 afterEach(() => {
@@ -134,6 +135,77 @@ test('stageOrganized namespaces nested category folders that would otherwise sha
   })
 })
 
+test('finalizeChangelogs emits flat canonical changelogs without an order file and suffixes case-insensitive collisions', () => {
+  withStaging((stagingDir) => {
+    const changelogDir = path.join(stagingDir, 'docs', 'Changelog')
+    fs.mkdirSync(path.join(changelogDir, 'foo'), { recursive: true })
+    fs.writeFileSync(
+      path.join(changelogDir, 'foo', 'Bar.md'),
+      matter.stringify('', { title: 'Nested', icon: 'fa-book', 'x-import': 'https://example.com/nested' }),
+    )
+    fs.writeFileSync(
+      path.join(changelogDir, 'foo-bar.md'),
+      matter.stringify('', { title: 'Root', icon: 'fa-book', 'x-import': 'https://example.com/root' }),
+    )
+    fs.writeFileSync(
+      path.join(changelogDir, 'unchanged.md'),
+      matter.stringify('', { title: 'Unchanged', icon: 'fa-book', 'x-import': 'https://example.com/unchanged' }),
+    )
+    fs.writeFileSync(path.join(stagingDir, 'docs', '_order.yaml'), '- Changelog\n')
+
+    assert.equal(finalizeChangelogs(stagingDir), 3)
+
+    const outputDir = path.join(stagingDir, 'changelogs')
+    assert.deepEqual(fs.readdirSync(outputDir).sort(), ['foo-Bar.md', 'foo-bar-2.md', 'unchanged.md'])
+    assert.equal(fs.existsSync(path.join(outputDir, '_order.yaml')), false)
+    assert.equal(fs.existsSync(path.join(stagingDir, 'changelog')), false)
+    assert.equal(fs.existsSync(path.join(stagingDir, 'docs', 'Changelog')), false)
+    assert.equal(fs.existsSync(path.join(stagingDir, 'docs', '_order.yaml')), false)
+    assert.equal(readFm(path.join(outputDir, 'foo-Bar.md')).icon, undefined)
+    assert.equal(readFm(path.join(outputDir, 'foo-Bar.md'))['x-import'], 'https://example.com/nested')
+    assert.equal(readFm(path.join(outputDir, 'foo-bar-2.md'))['x-import'], 'https://example.com/root')
+    assert.equal(readFm(path.join(outputDir, 'unchanged.md'))['x-import'], 'https://example.com/unchanged')
+  })
+})
+
+test('stageOrganized retains case-only changelog names before finalization', () => {
+  withStaging((stagingDir) => {
+    const upper = { title: 'Upper A', url: 'https://example.com/A' }
+    const lower = { title: 'Lower a', url: 'https://example.com/a' }
+    const independent = { title: 'Independent a-2', url: 'https://example.com/a-2' }
+    stageOrganized(
+      { categories: [{ title: 'Changelog', pages: [upper, lower, independent] }] },
+      stagingDir,
+      { slugFor: new Map([[upper, 'A'], [lower, 'a'], [independent, 'a-2']]) },
+    )
+    assert.equal(finalizeChangelogs(stagingDir), 3)
+
+    const outputDir = path.join(stagingDir, 'changelogs')
+    assert.deepEqual(fs.readdirSync(outputDir).sort(), ['A.md', 'a-2.md', 'a-3.md'])
+    assert.equal(readFm(path.join(outputDir, 'A.md')).title, 'Upper A')
+    assert.equal(readFm(path.join(outputDir, 'a-3.md')).title, 'Lower a')
+    assert.equal(readFm(path.join(outputDir, 'a-2.md')).title, 'Independent a-2')
+  })
+})
+
+test('allocateChangelogFilenames preserves an independent numeric-suffix filename', () => {
+  assert.deepEqual(
+    allocateChangelogFilenames([
+      { ancestors: [], slug: 'A' },
+      { ancestors: [], slug: 'a' },
+      { ancestors: [], slug: 'a-2' },
+    ]),
+    ['A', 'a-3', 'a-2'],
+  )
+})
+
+test('import command has no conditional changelog layout option', () => {
+  const cmd = new Command()
+  args(cmd)
+
+  assert.equal(cmd.options.some((option) => option.long === '--separate-changelog'), false)
+})
+
 test('stageOrganized quotes YAML-unsafe slugs in _order.yaml', () => {
   withStaging((stagingDir) => {
     stageOrganized(

package/src/commands/oas-bundle.js

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { bundle } from '@readme/openapi-parser';
+import * as styles from '../utils/styles.js';
+
+const require = createRequire(import.meta.url);
+const yaml = require('js-yaml');
+
+export const command = 'oas:bundle';
+export const order = 4;
+export const category = 'OAS Tooling';
+export const description = 'Bundle a multi-file OpenAPI spec into a single file';
+// The input spec usually lives outside a ReadMe docs repo (e.g. the API's
+// source repo in CI), so don't require a version branch or docs/ dir.
+export const skipBootstrap = true;
+
+export function args(cmd) {
+  cmd
+    .argument('<spec>', 'Path to the root OpenAPI spec file (JSON or YAML)')
+    .option('-o, --out <path>', 'Write the bundled spec to this file instead of stdout');
+}
+
+/** Resolve external $refs into one document with only internal (#/...) pointers. */
+export async function bundleOas({ file, cwd } = {}) {
+  const specPath = path.resolve(cwd || process.cwd(), file);
+  if (!fs.existsSync(specPath)) {
+    throw new Error(`Spec file not found: ${specPath}`);
+  }
+  // Pass the path, not contents: openapi-parser then resolves relative $refs
+  // against the file's directory. oas-normalize reads first and loses that.
+  return bundle(specPath);
+}
+
+export function formatForPath(outPath) {
+  return /\.ya?ml$/i.test(outPath) ? 'yaml' : 'json';
+}
+
+export function serializeSpec(spec, format) {
+  if (format === 'yaml') return yaml.dump(spec, { noRefs: true, lineWidth: -1 });
+  return `${JSON.stringify(spec, null, 2)}\n`;
+}
+
+/** Bundle `file` and write it to `out` (format follows the extension). */
+export async function writeBundle({ file, out, cwd } = {}) {
+  const root = cwd || process.cwd();
+  const spec = await bundleOas({ file, cwd: root });
+  const outPath = path.resolve(root, out);
+  const format = formatForPath(outPath);
+
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, serializeSpec(spec, format));
+
+  return { spec, outPath, format };
+}
+
+export async function run(specArg, options) {
+  try {
+    if (options.out) {
+      const { spec, outPath } = await writeBundle({ file: specArg, out: options.out });
+      const opCount = countOperations(spec);
+      const rel = path.relative(process.cwd(), outPath);
+      const shown = rel && !rel.startsWith('..') ? rel : outPath;
+      styles.ok(`Bundled ${styles.bold(spec.info?.title || specArg)} (${opCount} ${opCount === 1 ? 'endpoint' : 'endpoints'}) → ${shown}`);
+      return;
+    }
+
+    const spec = await bundleOas({ file: specArg });
+    process.stdout.write(serializeSpec(spec, formatForPath(specArg)));
+  } catch (err) {
+    styles.error(`Bundle failed: ${err.message || String(err)}`);
+    process.exit(1);
+  }
+}
+
+const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace']);
+
+function countOperations(spec) {
+  let n = 0;
+  for (const item of Object.values(spec.paths || {})) {
+    if (!item || typeof item !== 'object') continue;
+    for (const key of Object.keys(item)) if (HTTP_METHODS.has(key)) n += 1;
+  }
+  return n;
+}