@readme/cli 0.0.29 → 0.0.31

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

@@ -0,0 +1,217 @@
+import { afterEach, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { __test__ } from './import.js'
+
+const {
+  injectSectionLandingPages,
+  parseMetaRefreshTarget,
+  parseHtmlCanonical,
+} = __test__
+
+const originalFetch = globalThis.fetch
+
+afterEach(() => {
+  globalThis.fetch = originalFetch
+})
+
+function mockLandingFetch(routes) {
+  globalThis.fetch = async (url) => {
+    const href = String(url)
+    const entry = routes[href]
+    if (!entry) return { ok: false, status: 404, url: href, text: async () => '' }
+    if (entry instanceof Error) throw entry
+    return {
+      ok: entry.ok !== false,
+      status: entry.status ?? 200,
+      url: entry.finalUrl || href,
+      text: async () => entry.body || '',
+    }
+  }
+}
+
+test('parseMetaRefreshTarget resolves relative, quoted, and entity-encoded targets', () => {
+  const base = 'https://example.com/docs/guides/'
+  assert.equal(
+    parseMetaRefreshTarget('<meta http-equiv="refresh" content="0;url=/docs/guides/intro">', base),
+    'https://example.com/docs/guides/intro',
+  )
+  assert.equal(
+    parseMetaRefreshTarget("<meta http-equiv='refresh' content='0; url=intro'>", base),
+    'https://example.com/docs/guides/intro',
+  )
+  assert.equal(
+    parseMetaRefreshTarget('<meta http-equiv="refresh" content="0;url=/docs/guides?tab=js&amp;x=1">', base),
+    'https://example.com/docs/guides?tab=js&x=1',
+  )
+  assert.equal(parseMetaRefreshTarget('<html><title>Guides</title></html>', base), null)
+  assert.equal(parseMetaRefreshTarget('', base), null)
+  assert.equal(parseMetaRefreshTarget('<meta http-equiv="refresh" content="5">', base), null)
+})
+
+test('parseHtmlCanonical resolves relative and entity-encoded hrefs', () => {
+  const base = 'https://example.com/docs/guides/'
+  assert.equal(
+    parseHtmlCanonical('<link rel="canonical" href="/docs/guides/intro">', base),
+    'https://example.com/docs/guides/intro',
+  )
+  assert.equal(
+    parseHtmlCanonical("<link rel='canonical' href='intro'>", base),
+    'https://example.com/docs/guides/intro',
+  )
+  assert.equal(
+    parseHtmlCanonical('<link rel="canonical" href="/docs/guides?tab=js&amp;x=1">', base),
+    'https://example.com/docs/guides?tab=js&x=1',
+  )
+  assert.equal(parseHtmlCanonical('<html></html>', base), null)
+  assert.equal(parseHtmlCanonical('', base), null)
+})
+
+test('injectSectionLandingPages prepends a real common-prefix landing page', async () => {
+  mockLandingFetch({
+    'https://example.com/docs/guides': { body: '<title>Guides</title>' },
+  })
+  const organized = {
+    categories: [
+      {
+        title: 'Guides',
+        pages: [
+          { title: 'Intro', url: 'https://example.com/docs/guides/intro' },
+          { title: 'Install', url: 'https://example.com/docs/guides/install' },
+        ],
+      },
+    ],
+  }
+
+  await injectSectionLandingPages(organized, 'https://example.com/docs')
+
+  assert.equal(organized.categories[0].pages[0].url, 'https://example.com/docs/guides')
+  assert.equal(organized.categories[0].pages[0].title, 'Guides')
+  assert.equal(organized.categories[0].pages.length, 3)
+})
+
+test('injectSectionLandingPages skips client-redirect stub landings via meta refresh', async () => {
+  mockLandingFetch({
+    'https://example.com/docs/guides': {
+      body: '<meta http-equiv="refresh" content="0;url=/docs/guides/intro">',
+    },
+  })
+  const organized = {
+    categories: [
+      {
+        title: 'Guides',
+        pages: [
+          { title: 'Intro', url: 'https://example.com/docs/guides/intro' },
+          { title: 'Install', url: 'https://example.com/docs/guides/install' },
+        ],
+      },
+    ],
+  }
+
+  await injectSectionLandingPages(organized, 'https://example.com/docs')
+  assert.deepEqual(
+    organized.categories[0].pages.map((p) => p.url),
+    ['https://example.com/docs/guides/intro', 'https://example.com/docs/guides/install'],
+  )
+})
+
+test('injectSectionLandingPages skips landings whose canonical points at a known child', async () => {
+  mockLandingFetch({
+    'https://example.com/docs/guides': {
+      body: '<link rel="canonical" href="/docs/guides/intro">',
+    },
+  })
+  const organized = {
+    categories: [
+      {
+        title: 'Guides',
+        pages: [
+          { title: 'Intro', url: 'https://example.com/docs/guides/intro' },
+          { title: 'Install', url: 'https://example.com/docs/guides/install' },
+        ],
+      },
+    ],
+  }
+
+  await injectSectionLandingPages(organized, 'https://example.com/docs')
+  assert.equal(organized.categories[0].pages.length, 2)
+})
+
+test('injectSectionLandingPages skips landings that HTTP-redirect onto a known child', async () => {
+  mockLandingFetch({
+    'https://example.com/docs/guides': {
+      finalUrl: 'https://example.com/docs/guides/intro',
+      body: '<title>Intro</title>',
+    },
+  })
+  const organized = {
+    categories: [
+      {
+        title: 'Guides',
+        pages: [
+          { title: 'Intro', url: 'https://example.com/docs/guides/intro' },
+          { title: 'Install', url: 'https://example.com/docs/guides/install' },
+        ],
+      },
+    ],
+  }
+
+  await injectSectionLandingPages(organized, 'https://example.com/docs')
+  assert.equal(organized.categories[0].pages.length, 2)
+})
+
+test('injectSectionLandingPages does not probe the import base or categories with a single child', async () => {
+  const seen = []
+  globalThis.fetch = async (url) => {
+    seen.push(String(url))
+    return { ok: true, status: 200, url: String(url), text: async () => '<title>Docs</title>' }
+  }
+  const organized = {
+    categories: [
+      {
+        title: 'Docs',
+        pages: [
+          { title: 'A', url: 'https://example.com/docs/a' },
+          { title: 'B', url: 'https://example.com/docs/b' },
+        ],
+      },
+      {
+        title: 'Lonely',
+        pages: [{ title: 'Only', url: 'https://example.com/docs/guides/only' }],
+      },
+    ],
+  }
+
+  await injectSectionLandingPages(organized, 'https://example.com/docs')
+  assert.deepEqual(seen, [])
+  assert.equal(organized.categories[0].pages.length, 2)
+  assert.equal(organized.categories[1].pages.length, 1)
+})
+
+test('injectSectionLandingPages ignores 404s and fetch failures', async () => {
+  mockLandingFetch({
+    'https://example.com/docs/guides': new Error('network down'),
+    'https://example.com/docs/api': { ok: false, status: 404, body: '' },
+  })
+  const organized = {
+    categories: [
+      {
+        title: 'Guides',
+        pages: [
+          { title: 'Intro', url: 'https://example.com/docs/guides/intro' },
+          { title: 'Install', url: 'https://example.com/docs/guides/install' },
+        ],
+      },
+      {
+        title: 'API',
+        pages: [
+          { title: 'Auth', url: 'https://example.com/docs/api/auth' },
+          { title: 'Errors', url: 'https://example.com/docs/api/errors' },
+        ],
+      },
+    ],
+  }
+
+  await injectSectionLandingPages(organized, 'https://example.com/docs')
+  assert.equal(organized.categories[0].pages.length, 2)
+  assert.equal(organized.categories[1].pages.length, 2)
+})

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

@@ -0,0 +1,158 @@
+import { afterEach, test } from 'node:test'
+import assert from 'node:assert/strict'
+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'
+
+const { stageOrganized } = __test__
+
+const originalLog = console.log
+afterEach(() => {
+  console.log = originalLog
+})
+
+function withStaging(fn) {
+  const stagingDir = fs.mkdtempSync(path.join(os.tmpdir(), 'import-staging-'))
+  console.log = () => {}
+  try {
+    return fn(stagingDir)
+  } finally {
+    fs.rmSync(stagingDir, { recursive: true, force: true })
+  }
+}
+
+function readFm(filePath) {
+  return matter(fs.readFileSync(filePath, 'utf8')).data
+}
+
+test('stageOrganized writes parent pages as index.md and leaves as slug.md', () => {
+  withStaging((stagingDir) => {
+    const parent = {
+      title: 'Getting Started',
+      url: 'https://example.com/docs/getting-started',
+      pages: [{ title: 'Install', url: 'https://example.com/docs/getting-started/install' }],
+    }
+    const leaf = { title: 'Pricing', url: 'https://example.com/docs/pricing' }
+
+    const result = stageOrganized(
+      { categories: [{ title: 'Guides', pages: [parent, leaf] }] },
+      stagingDir,
+    )
+
+    const parentIndex = path.join(stagingDir, 'docs', 'Guides', 'getting-started', 'index.md')
+    const child = path.join(stagingDir, 'docs', 'Guides', 'getting-started', 'install.md')
+    const leafFile = path.join(stagingDir, 'docs', 'Guides', 'pricing.md')
+    const siblingParent = path.join(stagingDir, 'docs', 'Guides', 'getting-started.md')
+
+    assert.equal(fs.existsSync(parentIndex), true)
+    assert.equal(fs.existsSync(child), true)
+    assert.equal(fs.existsSync(leafFile), true)
+    assert.equal(fs.existsSync(siblingParent), false)
+
+    assert.equal(readFm(parentIndex).title, 'Getting Started')
+    assert.equal(readFm(parentIndex)['x-import'], 'https://example.com/docs/getting-started')
+    assert.equal(readFm(child).title, 'Install')
+    assert.equal(readFm(leafFile).title, 'Pricing')
+
+    const guidesOrder = fs.readFileSync(path.join(stagingDir, 'docs', 'Guides', '_order.yaml'), 'utf8')
+    assert.match(guidesOrder, /^- getting-started$/m)
+    assert.match(guidesOrder, /^- pricing$/m)
+    assert.doesNotMatch(guidesOrder, /^- index$/m)
+
+    const nestedOrder = fs.readFileSync(
+      path.join(stagingDir, 'docs', 'Guides', 'getting-started', '_order.yaml'),
+      'utf8',
+    )
+    assert.match(nestedOrder, /^- install$/m)
+    assert.equal(result.fileCount, 3)
+  })
+})
+
+test('stageOrganized rescues /api/docs pages when skipping API reference categories', () => {
+  withStaging((stagingDir) => {
+    const result = stageOrganized(
+      {
+        categories: [
+          {
+            title: 'API Reference',
+            pages: [
+              { title: 'List pets', url: 'https://example.com/api/reference/pets' },
+              { title: 'Guides', url: 'https://example.com/api/docs/guides/intro' },
+              {
+                title: 'Mixed',
+                pages: [{ title: 'Pricing', url: 'https://example.com/api/docs/pricing' }],
+              },
+            ],
+          },
+        ],
+      },
+      stagingDir,
+      { skipApiReference: true },
+    )
+
+    assert.equal(result.skippedApiRef, 1)
+    assert.equal(fs.existsSync(path.join(stagingDir, 'reference')), false)
+
+    const rescuedDir = path.join(stagingDir, 'docs', 'API Docs')
+    const guides = path.join(rescuedDir, 'intro.md')
+    const pricing = path.join(rescuedDir, 'introduction', 'pricing.md')
+    assert.equal(fs.existsSync(guides), true)
+    assert.equal(fs.existsSync(pricing), true)
+    assert.equal(readFm(guides)['x-import'], 'https://example.com/api/docs/guides/intro')
+    assert.equal(readFm(pricing)['x-import'], 'https://example.com/api/docs/pricing')
+  })
+})
+
+test('stageOrganized namespaces nested category folders that would otherwise share a basename', () => {
+  withStaging((stagingDir) => {
+    stageOrganized(
+      {
+        categories: [
+          { title: 'Fundamentals', pages: [{ title: 'Hello', url: 'https://example.com/docs/hello' }] },
+          { title: 'cockroach/Fundamentals', pages: [{ title: 'SQL', url: 'https://example.com/docs/sql' }] },
+        ],
+      },
+      stagingDir,
+    )
+
+    const topLevel = path.join(stagingDir, 'docs', 'Fundamentals', 'hello.md')
+    const nestedDir = path.join(stagingDir, 'docs', 'cockroach', 'cockroach-fundamentals')
+    const nestedPage = path.join(nestedDir, 'sql.md')
+    const nestedIndex = path.join(nestedDir, 'index.md')
+
+    assert.equal(fs.existsSync(topLevel), true)
+    assert.equal(fs.existsSync(nestedPage), true)
+    assert.equal(fs.existsSync(nestedIndex), true)
+    assert.equal(readFm(nestedIndex).title, 'Fundamentals')
+    assert.equal('x-import' in readFm(nestedIndex), false)
+
+    const docsOrder = fs.readFileSync(path.join(stagingDir, 'docs', '_order.yaml'), 'utf8')
+    assert.match(docsOrder, /^- Fundamentals$/m)
+    assert.match(docsOrder, /^- cockroach\/cockroach-fundamentals$/m)
+  })
+})
+
+test('stageOrganized quotes YAML-unsafe slugs in _order.yaml', () => {
+  withStaging((stagingDir) => {
+    stageOrganized(
+      {
+        categories: [
+          {
+            title: 'Guides',
+            pages: [
+              { title: 'True', url: 'https://example.com/docs/true' },
+              { title: 'Null', url: 'https://example.com/docs/null' },
+            ],
+          },
+        ],
+      },
+      stagingDir,
+    )
+
+    const order = fs.readFileSync(path.join(stagingDir, 'docs', 'Guides', '_order.yaml'), 'utf8')
+    assert.match(order, /^- "true"$/m)
+    assert.match(order, /^- "null"$/m)
+  })
+})

package/src/commands/import.test.js

@@ -134,3 +134,249 @@ test('resolveRedirectedSourceUrl returns null when fetch throws', async () => {
   }
   assert.equal(await __test__.resolveRedirectedSourceUrl(new URL('https://example.com/')), null)
 })
+
+function mockDocsProbeFetch(files, { catchAllBody } = {}) {
+  globalThis.fetch = async (url) => {
+    const href = String(url)
+    if (new URL(href).hostname !== 'example.com') throw new Error('getaddrinfo ENOTFOUND')
+    const entry = files[href]
+    if (entry) return { ok: true, status: 200, url: entry.finalUrl || href, text: async () => entry.body || '' }
+    if (catchAllBody && !href.endsWith('/llms.txt')) return { ok: true, status: 200, url: href, text: async () => catchAllBody }
+    return { ok: false, status: 404, url: href, text: async () => '' }
+  }
+}
+
+test('resolveDocsBaseUrl adopts a path route whose trailing slash gets stripped by a redirect', async () => {
+  mockDocsProbeFetch({
+    'https://example.com/docs/': { finalUrl: 'https://example.com/docs', body: '<title>API Docs</title>' },
+  })
+  const result = await __test__.resolveDocsBaseUrl(new URL('https://example.com'))
+  assert.equal(result?.url.href, 'https://example.com/docs/')
+  assert.equal(result?.kind, 'path')
+  assert.equal(result?.hasLlms, false)
+})
+
+test('resolveDocsBaseUrl rejects a path route that redirects to the homepage', async () => {
+  mockDocsProbeFetch({
+    'https://example.com/docs/': { finalUrl: 'https://example.com/' },
+  })
+  assert.equal(await __test__.resolveDocsBaseUrl(new URL('https://example.com')), null)
+})
+
+test('resolveDocsBaseUrl skips SPA catch-all routes and adopts the route with distinct content', async () => {
+  mockDocsProbeFetch(
+    {
+      'https://example.com/developers/': { finalUrl: 'https://example.com/developers', body: '<title>API Documentation</title>' },
+    },
+    { catchAllBody: '<title>Example - Empowering</title>' },
+  )
+  const result = await __test__.resolveDocsBaseUrl(new URL('https://example.com'))
+  assert.equal(result?.url.href, 'https://example.com/developers/')
+  assert.equal(result?.kind, 'path')
+  assert.equal(result?.hasLlms, false)
+})
+
+test('resolveDocsBaseUrl returns null when every candidate fails', async () => {
+  mockDocsProbeFetch({})
+  assert.equal(await __test__.resolveDocsBaseUrl(new URL('https://example.com')), null)
+})
+
+test('inCandidateScope normalizes trailing slashes and enforces segment boundaries', () => {
+  const candidate = { kind: 'path', url: new URL('https://example.com/docs/') }
+  assert.equal(__test__.inCandidateScope(candidate, 'https://example.com/docs'), true)
+  assert.equal(__test__.inCandidateScope(candidate, 'https://www.example.com/docs'), true)
+  assert.equal(__test__.inCandidateScope(candidate, 'https://example.com/docs/llms.txt'), true)
+  assert.equal(__test__.inCandidateScope(candidate, 'https://example.com/DOCS//'), true)
+  assert.equal(__test__.inCandidateScope(candidate, 'https://example.com/docsomething'), false)
+  assert.equal(__test__.inCandidateScope(candidate, 'https://example.com/'), false)
+})
+
+function fernHtml(fragments, { aside = true, generator = false, extraBody = '' } = {}) {
+  const scripts = fragments.map((fragment) => `<script>self.__next_f.push([1,${JSON.stringify(fragment)}])</script>`).join('\n')
+  const head = generator ? '<meta name="generator" content="https://buildwithfern.com">' : ''
+  const sidebar = aside ? '<aside id="fern-sidebar" class="fern-sidebar-container"></aside>' : ''
+  return `<!doctype html><html><head>${head}</head><body>${sidebar}${extraBody}${scripts}</body></html>`
+}
+
+function mockHtmlFetch(pages) {
+  globalThis.fetch = async (url) => {
+    const entry = pages[String(url)]
+    if (entry === undefined) return { ok: false, status: 404, url: String(url), text: async () => '' }
+    if (entry instanceof Error) throw entry
+    return { ok: true, status: 200, url: String(url), text: async () => entry }
+  }
+}
+
+const GEN1_TREE =
+  '7a:["$","$L7b",null,{"children":[' +
+  '{"type":"sidebarGroup","id":"sidebar-group:section:docs/get-started","collapsed":"$undefined","children":[' +
+  '{"type":"section","id":"section:docs/get-started","title":"Get started","slug":"docs/get-started","hidden":false,"pointsTo":"$undefined","children":[' +
+  '{"type":"page","id":"page:intro","title":"Introduction","slug":"intro","hidden":false},' +
+  '{"type":"page","id":"page:secret","title":"Secret","slug":"secret","hidden":true},' +
+  '{"type":"section","id":"section:docs/nested","title":"Nested","slug":"nested/overview","hidden":false,"pointsTo":"$undefined","overviewPageId":"nested/overview.mdx","children":[' +
+  '{"type":"page","id":"page:nested/deep","title":"Deep page","slug":"nested/deep","hidden":false}]}]}]}]}]'
+
+const GEN2_TREE =
+  '7a:["$","$L7b",null,{"children":[' +
+  '{"type":"sidebarGroup","id":"c00ed6ec6366da0ae76c9bd27e2e2c23bf3785a61bbb0990","collapsed":"$undefined","children":[' +
+  '{"type":"section","id":"28eaf69e90e0a08edb3d6840439eeacb0b9dbdb3","title":"Get started","slug":"docs/get-started","hidden":false,"pointsTo":"$undefined","children":[' +
+  '{"type":"page","id":"bc59f5966f28f9f0c31ac71f02619db1e70e8c65","title":"Introduction","slug":"intro","hidden":false},' +
+  '{"type":"page","id":"3d9a0da0ad64e4f360afee1dee83e4ae1b848dff","title":"Secret","slug":"secret","hidden":true},' +
+  '{"type":"section","id":"75861c60edfc32eefed7d2a77f7d1b9563a7bb74","title":"Nested","slug":"nested/overview","hidden":false,"pointsTo":"$undefined","overviewPageId":"nested/overview.mdx","children":[' +
+  '{"type":"page","id":"03b7470af4ce00f9a9dc979ba32fec3fd1c4a7bd","title":"Deep page","slug":"nested/deep","hidden":false}]}]}]}]}]'
+
+function assertGetStartedTree(nav) {
+  assert.equal(nav.categories.length, 1)
+  const [category] = nav.categories
+  assert.equal(category.title, 'Get started')
+  assert.deepEqual(
+    category.pages.map((p) => p.url),
+    ['https://fern.example/intro', 'https://fern.example/nested/overview'],
+  )
+  assert.equal(category.pages[0].title, 'Introduction')
+  assert(!category.pages.some((p) => p.title === 'Secret'))
+  const nested = category.pages[1]
+  assert.equal(nested.title, 'Nested')
+  assert.deepEqual(nested.pages, [{ title: 'Deep page', url: 'https://fern.example/nested/deep' }])
+}
+
+test('tryFernNav parses the page:<slug> id generation into nested categories, skipping hidden pages', async () => {
+  mockHtmlFetch({ 'https://fern.example/intro': fernHtml([GEN1_TREE]) })
+  const nav = await __test__.tryFernNav('https://fern.example/intro', [])
+  assertGetStartedTree(nav)
+})
+
+test('tryFernNav parses the hashed id generation into the same categories', async () => {
+  mockHtmlFetch({ 'https://fern.example/intro': fernHtml([GEN2_TREE]) })
+  const nav = await __test__.tryFernNav('https://fern.example/intro', [])
+  assertGetStartedTree(nav)
+})
+
+test('tryFernNav detects via generator meta when the sidebar aside is absent', async () => {
+  mockHtmlFetch({ 'https://fern.example/intro': fernHtml([GEN1_TREE], { aside: false, generator: true }) })
+  const nav = await __test__.tryFernNav('https://fern.example/intro', [])
+  assertGetStartedTree(nav)
+})
+
+test('tryFernNav returns null when neither detection signal is present', async () => {
+  mockHtmlFetch({ 'https://fern.example/intro': fernHtml([GEN1_TREE], { aside: false }) })
+  assert.equal(await __test__.tryFernNav('https://fern.example/intro', []), null)
+})
+
+test('tryFernNav ignores prose mentions of the detection signals', async () => {
+  mockHtmlFetch({
+    'https://fern.example/intro': fernHtml([GEN1_TREE], {
+      aside: false,
+      extraBody: '<p>Docs generated with buildwithfern.com use an aside with id="fern-sidebar".</p>',
+    }),
+  })
+  assert.equal(await __test__.tryFernNav('https://fern.example/intro', []), null)
+})
+
+test('tryFernNav returns null when the page has no flight chunks', async () => {
+  mockHtmlFetch({ 'https://fern.example/intro': fernHtml([]) })
+  assert.equal(await __test__.tryFernNav('https://fern.example/intro', []), null)
+})
+
+test('tryFernNav retries from a known page when the entry URL is dead', async () => {
+  mockHtmlFetch({ 'https://fern.example/nested/deep': fernHtml([GEN1_TREE]) })
+  const nav = await __test__.tryFernNav('https://fern.example/dead-slug', [
+    { title: 'Deep page', url: 'https://fern.example/nested/deep.md', description: undefined },
+  ])
+  assert.equal(nav.categories.length, 1)
+  assert.equal(nav.categories[0].title, 'Get started')
+  assert.deepEqual(nav.categories[0].pages[1].pages, [{ title: 'Deep page', url: 'https://fern.example/nested/deep.md' }])
+})
+
+test('tryFernNav returns null when the entry URL is dead and the known page is not Fern', async () => {
+  mockHtmlFetch({ 'https://fern.example/nested/deep': fernHtml([GEN1_TREE], { aside: false }) })
+  assert.equal(
+    await __test__.tryFernNav('https://fern.example/dead-slug', [{ title: 'Deep page', url: 'https://fern.example/nested/deep.md', description: undefined }]),
+    null,
+  )
+})
+
+test('tryFernNav keeps the sidebar title but takes urls and descriptions from llms.txt', async () => {
+  mockHtmlFetch({ 'https://fern.example/intro': fernHtml([GEN1_TREE]) })
+  const nav = await __test__.tryFernNav('https://fern.example/intro', [
+    { title: 'Welcome', url: 'https://fern.example/intro.md', description: 'Start here' },
+  ])
+  assert.deepEqual(nav.categories[0].pages[0], { title: 'Introduction', url: 'https://fern.example/intro.md', description: 'Start here' })
+})
+
+test('tryFernNav treats section pointsTo as an alias: the first child keeps its page and the section becomes a titled group', async () => {
+  const tree =
+    '7a:["$","$L7b",null,{"children":[' +
+    '{"type":"sidebarGroup","id":"sidebar-group:section:docs/guides","children":[' +
+    '{"type":"section","id":"section:docs/guides","title":"Guides","slug":"docs/guides","hidden":false,"pointsTo":"$undefined","overviewPageId":"$undefined","children":[' +
+    '{"type":"section","id":"section:docs/guides/billing","title":"Billing","slug":"docs/guides/billing","hidden":false,"pointsTo":"billing/manage","overviewPageId":"$undefined","children":[' +
+    '{"type":"page","id":"page:billing/manage","title":"Manage billing","slug":"billing/manage","hidden":false},' +
+    '{"type":"page","id":"page:billing/limits","title":"Billing limits","slug":"billing/limits","hidden":false}]}]}]}]}]'
+  mockHtmlFetch({ 'https://fern.example/intro': fernHtml([tree]) })
+  const nav = await __test__.tryFernNav('https://fern.example/intro', [])
+  const [category] = nav.categories
+  assert.equal(category.title, 'Guides')
+  const billing = category.pages[0]
+  assert.equal(billing.title, 'Billing')
+  assert.equal(billing.url, null)
+  assert.deepEqual(
+    billing.pages.map((p) => [p.title, p.url]),
+    [
+      ['Manage billing', 'https://fern.example/billing/manage'],
+      ['Billing limits', 'https://fern.example/billing/limits'],
+    ],
+  )
+})
+
+const TAB_LIST =
+  '5f:["$","$L60",null,{"tabs":[' +
+  '{"type":"tab","id":"tab:docs","title":"Docs","slug":"docs","hidden":false,"pointsTo":"intro","child":{"type":"sidebarRoot","id":"sidebar:|||aa11","collapsed":"$undefined","children":[]}},' +
+  '{"type":"tab","id":"tab:api","title":"API Reference","slug":"api","hidden":false,"pointsTo":"api/start","child":{"type":"sidebarRoot","id":"sidebar:|||bb22","collapsed":"$undefined","children":[]}}]}]'
+
+const API_TAB_TREE =
+  '9c:["$","$L9d",null,{"children":[' +
+  '{"type":"apiPackage","id":"api-pkg:api/pets","title":"Pets","slug":"api/pets","hidden":false,"pointsTo":"api/start","children":[' +
+  '{"type":"endpoint","id":"api-leaf:api/start","title":"List pets","slug":"api/start","hidden":false,"method":"GET"},' +
+  '{"type":"endpoint","id":"api-leaf:api/pets/create","title":"Create pet","slug":"api/pets/create","hidden":false,"method":"POST"}]}]}]'
+
+test('tryFernNav fetches non-active tabs once and merges their trees', async () => {
+  mockHtmlFetch({
+    'https://fern.example/intro': fernHtml([GEN1_TREE, TAB_LIST]),
+    'https://fern.example/api/start': fernHtml([API_TAB_TREE]),
+  })
+  const nav = await __test__.tryFernNav('https://fern.example/intro', [])
+  assert.deepEqual(
+    nav.categories.map((c) => c.title),
+    ['Get started', 'Pets'],
+  )
+  assert.deepEqual(
+    nav.categories[1].pages.map((p) => p.url),
+    ['https://fern.example/api/start', 'https://fern.example/api/pets/create'],
+  )
+})
+
+test('tryFernNav names an untitled tab-tree root after its tab', async () => {
+  const untitledTabTree =
+    '9c:["$","$L9d",null,{"children":[' +
+    '{"type":"apiPackage","id":"api-pkg:api","title":"$undefined","slug":"api","hidden":false,"pointsTo":"api/start","children":[' +
+    '{"type":"endpoint","id":"api-leaf:api/start","title":"List pets","slug":"api/start","hidden":false,"method":"GET"},' +
+    '{"type":"endpoint","id":"api-leaf:api/pets/create","title":"Create pet","slug":"api/pets/create","hidden":false,"method":"POST"}]}]}]'
+  mockHtmlFetch({
+    'https://fern.example/intro': fernHtml([GEN1_TREE, TAB_LIST]),
+    'https://fern.example/api/start': fernHtml([untitledTabTree]),
+  })
+  const nav = await __test__.tryFernNav('https://fern.example/intro', [])
+  assert.deepEqual(
+    nav.categories.map((c) => c.title),
+    ['Get started', 'API Reference'],
+  )
+})
+
+test('tryFernNav keeps the entry tree when a tab fetch fails', async () => {
+  mockHtmlFetch({
+    'https://fern.example/intro': fernHtml([GEN1_TREE, TAB_LIST]),
+    'https://fern.example/api/start': new Error('network down'),
+  })
+  const nav = await __test__.tryFernNav('https://fern.example/intro', [])
+  assertGetStartedTree(nav)
+})

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))