@inditextech/docouture-antora-extensions 0.1.0-SNAPSHOT.40.1

package/lib/html-to-markdown.js

@@ -0,0 +1,259 @@
+'use strict'
+
+const { parse, NodeType } = require('node-html-parser')
+
+// Same rationale as search-index.js's own STRIPPED_TAGS/STRIPPED_CLASSES:
+// the table of contents Asciidoctor emits inline in some layouts and any
+// inline icon SVGs are page furniture, not article content, and neither
+// survives translation to Markdown meaningfully.
+const STRIPPED_TAGS = new Set(['svg'])
+const STRIPPED_CLASSES = new Set(['toc', 'icon'])
+
+// Asciidoctor's five admonition kinds (NOTE/TIP/IMPORTANT/CAUTION/WARNING),
+// each rendered as `<div class="admonitionblock <kind>">`. See
+// admonitionToMarkdown for why this needs its own case rather than falling
+// through to the generic table handler.
+const ADMONITION_LABELS = {
+  note: 'Note',
+  tip: 'Tip',
+  important: 'Important',
+  caution: 'Caution',
+  warning: 'Warning',
+}
+
+const BLOCK_TAGS = new Set(['p', 'div', 'section', 'article', 'header', 'footer', 'aside', 'figure', 'figcaption'])
+
+/**
+ * Converts one page's converted-HTML article body (`page.contents` at the
+ * `navigationBuilt` event — chrome-free, since page-composer has not yet
+ * wrapped it in the UI layout; see llms-txt.js's own header) into Markdown
+ * suitable for `llms-full.txt`.
+ *
+ * Deliberately narrow: this repo's pages are built from a known, small set
+ * of block shapes (Asciidoctor's own admonitions/tables/code blocks, plus
+ * this project's card/step/tabs/accordion block extensions — see
+ * search-index.js's own note on those). Anything not explicitly handled
+ * below is opened up and its text recursed into, the same fallback
+ * search-index.js's walk() uses for the same reason: an unrecognised
+ * wrapper's prose should still surface somewhere rather than vanish.
+ *
+ * @param {String} html
+ * @returns {String} Markdown
+ */
+module.exports = function htmlToMarkdown(html) {
+  // node-html-parser treats `<pre>` as a "block text" element by default —
+  // the same bucket as `<script>`/`<style>` — and keeps its content as raw,
+  // unparsed text rather than a `<code>` child element. That is exactly
+  // wrong for a fenced code block: it needs the language class off the
+  // nested `<code>`, so parsing has to be told to open `<pre>` up too. Note
+  // this has to be done by OMITTING `pre` from the map, not setting it to
+  // `false`: the parser's `is_block_text_element` check tests key presence
+  // only, ignoring the boolean value — `{ pre: false }` still block-texts it.
+  const root = parse(html, { blockTextElements: { script: true, style: true } })
+  const md = blockToMarkdown(root, 0)
+  // Collapse the accumulation of blank lines block joins tend to produce
+  // down to at most one, and trim the trailing whitespace every block
+  // emitter leaves behind it.
+  return md.replace(/\n{3,}/g, '\n\n').trim()
+}
+
+function blockToMarkdown(node, listDepth) {
+  let out = ''
+  for (const child of node.childNodes) {
+    out += nodeToMarkdown(child, listDepth)
+  }
+  return out
+}
+
+function nodeToMarkdown(node, listDepth) {
+  if (node.nodeType === NodeType.TEXT_NODE) return node.text
+  if (node.nodeType !== NodeType.ELEMENT_NODE) return ''
+
+  const tag = node.rawTagName?.toLowerCase()
+  if (STRIPPED_TAGS.has(tag)) return ''
+  const classes = node.classList?.value || []
+  if (classes.some((cls) => STRIPPED_CLASSES.has(cls))) return ''
+  if (tag === 'div' && classes.includes('admonitionblock')) return admonitionToMarkdown(node, classes)
+
+  switch (tag) {
+    case 'h1':
+    case 'h2':
+    case 'h3':
+    case 'h4':
+    case 'h5':
+    case 'h6':
+      return `\n\n${'#'.repeat(Number(tag[1]))} ${inlineText(node)}\n\n`
+
+    case 'pre': {
+      const code = node.querySelector('code')
+      const lang = (code?.classList?.value || []).map((c) => c.replace(/^language-/, '')).find(Boolean) || ''
+      const text = (code || node).text.replace(/\n+$/, '')
+      return `\n\n\`\`\`${lang}\n${text}\n\`\`\`\n\n`
+    }
+
+    case 'code':
+      return `\`${node.text}\``
+
+    case 'strong':
+    case 'b': {
+      const text = inlineText(node)
+      // An icon font glyph (`<i class="fa icon-warning">`, no text content —
+      // the glyph is painted by CSS `content`) falls through here empty.
+      // Emphasising nothing would render as a bare `**`/`*`, so it is
+      // dropped rather than kept.
+      return text ? `**${text}**` : ''
+    }
+
+    case 'em':
+    case 'i': {
+      const text = inlineText(node)
+      return text ? `*${text}*` : ''
+    }
+
+    case 'a': {
+      const href = node.getAttribute('href')
+      const text = inlineText(node)
+      // Antora's `sectanchors` emits an empty `<a class="anchor">` right
+      // before every heading's own text, purely for a CSS hover affordance —
+      // see the asciidoc skill's own note on the attribute. No text, no link
+      // worth keeping.
+      if (!text) return ''
+      return href ? `[${text}](${href})` : text
+    }
+
+    case 'img': {
+      const alt = node.getAttribute('alt') || ''
+      const src = node.getAttribute('src') || ''
+      return `![${alt}](${src})`
+    }
+
+    case 'br':
+      return '\n'
+
+    case 'hr':
+      return '\n\n---\n\n'
+
+    case 'blockquote':
+      return `\n\n${blockToMarkdown(node, listDepth)
+        .trim()
+        .split('\n')
+        .map((line) => `> ${line}`)
+        .join('\n')}\n\n`
+
+    case 'ul':
+    case 'ol':
+      return `\n\n${listToMarkdown(node, listDepth, tag === 'ol')}\n\n`
+
+    case 'li':
+      // Handled by listToMarkdown per item; a stray <li> outside ul/ol
+      // (shouldn't happen in Asciidoctor output) just falls through to its
+      // own content below.
+      return blockToMarkdown(node, listDepth)
+
+    case 'table':
+      return `\n\n${tableToMarkdown(node)}\n\n`
+
+    case 'p':
+      return `\n\n${inlineText(node)}\n\n`
+
+    default:
+      // Generic wrapper (div/section/this project's own block extensions/
+      // etc.) — open it up rather than drop its text. Block-level tags get
+      // paragraph breaks around them so prose from adjacent wrappers doesn't
+      // run together; the smaller set of pure-inline unknown tags does not.
+      if (BLOCK_TAGS.has(tag)) return `\n\n${blockToMarkdown(node, listDepth).trim()}\n\n`
+      return blockToMarkdown(node, listDepth)
+  }
+}
+
+function inlineText(node) {
+  return collapseWhitespace(blockToMarkdown(node, 0))
+}
+
+function collapseWhitespace(text) {
+  return text.replace(/\s+/g, ' ').trim()
+}
+
+// Asciidoctor renders an admonition as a two-cell `<table>`: `td.icon`
+// (an empty `<i>` painted by CSS/an icon font, no real content) and
+// `td.content` (the admonition's own body, sometimes with its own
+// `div.title` — the "Example"/custom caption text — ahead of the prose).
+// Falling through to the generic table handler would render the icon cell
+// as a bare, empty `**` (see the strong/em cases' own note) and produce a
+// one-row "table" that isn't really tabular data at all, so this is
+// rendered as a labelled blockquote instead — content only, icon dropped.
+function admonitionToMarkdown(node, classes) {
+  const kind = classes.find((cls) => cls in ADMONITION_LABELS)
+  const label = ADMONITION_LABELS[kind] || 'Note'
+  const contentCell = node.querySelector('td.content')
+  const body = (contentCell ? blockToMarkdown(contentCell, 0) : inlineText(node)).replace(/\n{3,}/g, '\n\n').trim()
+  const quoted = body
+    .split('\n')
+    .map((line) => (line ? `> ${line}` : '>'))
+    .join('\n')
+  return `\n\n> **${label}**\n${quoted}\n\n`
+}
+
+function listToMarkdown(listNode, depth, ordered) {
+  const indent = '  '.repeat(depth)
+  const lines = []
+  let i = 0
+  for (const child of listNode.childNodes) {
+    if (child.nodeType !== NodeType.ELEMENT_NODE || child.rawTagName?.toLowerCase() !== 'li') continue
+    i += 1
+    const marker = ordered ? `${i}.` : '-'
+    const { inline, nested } = splitListItem(child, depth)
+    lines.push(`${indent}${marker} ${inline}`)
+    if (nested) lines.push(nested)
+  }
+  return lines.join('\n')
+}
+
+// A list item's own text and a nested sub-list are pulled apart rather than
+// walked as one blob: the sub-list already renders itself fully indented (it
+// recurses with `depth + 1`), so folding it back through the generic inline
+// text path would double-indent it and, worse, collapse the blank line its
+// own block wrapping leaves behind into the middle of the item's text.
+function splitListItem(li, depth) {
+  let inline = ''
+  let nested = ''
+  for (const child of li.childNodes) {
+    const tag = child.nodeType === NodeType.ELEMENT_NODE ? child.rawTagName?.toLowerCase() : null
+    if (tag === 'ul' || tag === 'ol') {
+      nested += (nested ? '\n' : '') + listToMarkdown(child, depth + 1, tag === 'ol')
+    } else {
+      inline += nodeToMarkdown(child, depth)
+    }
+  }
+  return { inline: collapseWhitespace(inline), nested }
+}
+
+function tableToMarkdown(tableNode) {
+  const rows = []
+  // Backslash is escaped first: escaping `|` alone would let a source
+  // backslash immediately before one combine with the `\` this line just
+  // inserted, producing `\\|` — an escaped backslash followed by a live,
+  // unescaped column separator, the exact thing this escape exists to
+  // prevent.
+  const escapeCell = (text) => text.replace(/\\/g, '\\\\').replace(/\|/g, '\\|')
+  for (const rowNode of tableNode.querySelectorAll('tr')) {
+    const cells = rowNode.querySelectorAll('th,td').map((cell) => escapeCell(inlineText(cell)) || ' ')
+    if (cells.length) rows.push(cells)
+  }
+  if (!rows.length) return ''
+
+  const colCount = Math.max(...rows.map((r) => r.length))
+  const pad = (row) => {
+    const padded = row.slice()
+    while (padded.length < colCount) padded.push(' ')
+    return padded
+  }
+
+  const [header, ...body] = rows
+  const lines = [
+    `| ${pad(header).join(' | ')} |`,
+    `| ${Array(colCount).fill('---').join(' | ')} |`,
+    ...body.map((row) => `| ${pad(row).join(' | ')} |`),
+  ]
+  return lines.join('\n')
+}

package/lib/html-to-markdown.spec.js

@@ -0,0 +1,73 @@
+'use strict'
+
+import { describe, expect, it } from 'vitest'
+
+const htmlToMarkdown = require('./html-to-markdown')
+
+describe('htmlToMarkdown', () => {
+  it('converts headings', () => {
+    expect(htmlToMarkdown('<h1 id="a">Title</h1><h2 id="b">Sub</h2>')).toBe('# Title\n\n## Sub')
+  })
+
+  it('converts paragraphs and inline emphasis', () => {
+    const html = '<p>Some <strong>bold</strong> and <em>italic</em> text.</p>'
+    expect(htmlToMarkdown(html)).toBe('Some **bold** and *italic* text.')
+  })
+
+  it('converts links', () => {
+    expect(htmlToMarkdown('<p><a href="https://example.com">Example</a></p>')).toBe('[Example](https://example.com)')
+  })
+
+  it('converts inline code and fenced code blocks with a language', () => {
+    const html = '<p>Run <code>npm install</code></p><pre><code class="language-js">const x = 1;</code></pre>'
+    expect(htmlToMarkdown(html)).toBe('Run `npm install`\n\n```js\nconst x = 1;\n```')
+  })
+
+  it('converts unordered and ordered lists, including nesting', () => {
+    const html = '<ul><li>One</li><li>Two<ul><li>Nested</li></ul></li></ul>'
+    expect(htmlToMarkdown(html)).toBe('- One\n- Two\n  - Nested')
+
+    expect(htmlToMarkdown('<ol><li>First</li><li>Second</li></ol>')).toBe('1. First\n2. Second')
+  })
+
+  it('converts tables to GitHub-flavoured Markdown tables', () => {
+    const html = '<table><tr><th>A</th><th>B</th></tr><tr><td>1</td><td>2</td></tr></table>'
+    expect(htmlToMarkdown(html)).toBe('| A | B |\n| --- | --- |\n| 1 | 2 |')
+  })
+
+  it('drops table-of-contents and icon elements', () => {
+    const html = '<div class="toc"><a href="#a">A</a></div><p>Body</p><svg><path/></svg>'
+    expect(htmlToMarkdown(html)).toBe('Body')
+  })
+
+  it('opens up unrecognised wrapper elements rather than dropping their text', () => {
+    const html = '<div class="card"><h3 id="c">Card title</h3><p>Card body</p></div>'
+    expect(htmlToMarkdown(html)).toBe('### Card title\n\nCard body')
+  })
+
+  it("drops sectanchors' empty anchor links ahead of headings", () => {
+    const html = '<h2 id="x"><a class="anchor" href="#x"></a>Section</h2>'
+    expect(htmlToMarkdown(html)).toBe('## Section')
+  })
+
+  it('renders an admonition block as a labelled blockquote, dropping the icon cell', () => {
+    const html =
+      '<div class="admonitionblock warning"><table><tr>' +
+      '<td class="icon"><i class="fa icon-warning" title="Warning"></i></td>' +
+      '<td class="content"><div class="paragraph"><p>Careful here.</p></div></td>' +
+      '</tr></table></div>'
+    expect(htmlToMarkdown(html)).toBe('> **Warning**\n> Careful here.')
+  })
+
+  it('collapses the blank-line gap between an admonition title and its body', () => {
+    const html =
+      '<div class="admonitionblock note"><table><tr>' +
+      '<td class="icon"><i class="fa icon-note" title="Note"></i></td>' +
+      '<td class="content">' +
+      '<div class="title">Example</div>' +
+      '<div class="paragraph"><p>See the docs.</p></div>' +
+      '</td>' +
+      '</tr></table></div>'
+    expect(htmlToMarkdown(html)).toBe('> **Note**\n> Example\n>\n> See the docs.')
+  })
+})

package/lib/kroki-docker.js

@@ -0,0 +1,162 @@
+'use strict'
+
+const { execFile } = require('node:child_process')
+const { promisify } = require('node:util')
+const { access } = require('node:fs/promises')
+const path = require('node:path')
+
+// GH-44: starts the local Kroki service on demand, the first time a
+// `kroki-enabled: true` build actually needs it and finds nothing already
+// listening. No teardown of any kind — see kroki-prewarm.js's own header for
+// why: a container left running is reused by the next build (the
+// reachability check below short-circuits straight past a start attempt),
+// and simply discarded whenever the machine or CI runner it ran on goes
+// away. This is deliberately the ONE place across every invocation path —
+// `docouture dev`/`docouture build`, this monorepo's own `just dev`/`just
+// build-site`, a raw `antora` invocation, any consumer's own CI — that
+// starts Kroki, because it is the one piece of code every single one of
+// those paths runs through: the Antora pipeline extension itself.
+const execFileAsync = promisify(execFile)
+
+const BUNDLED_COMPOSE_FILE = path.join(__dirname, '..', 'resources', 'kroki-compose.yml')
+
+// The file `docouture eject kroki` copies the bundled compose definition to —
+// see that command's own header. Looked up relative to the PLAYBOOK's own
+// directory (`playbook.dir`, set by @antora/playbook-builder to wherever
+// `antora-playbook.yml` actually is), i.e. the site root, the same
+// directory `docouture eject kroki` writes it into.
+const OVERRIDE_FILENAME = 'kroki-compose.yml'
+
+const REACHABLE_TIMEOUT_MS = 1000
+const STARTUP_TIMEOUT_MS = 60000
+const POLL_INTERVAL_MS = 2000
+
+async function isReachable(url) {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), REACHABLE_TIMEOUT_MS)
+  try {
+    await fetch(url, { signal: controller.signal })
+    return true
+  } catch {
+    return false
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+async function resolveComposeFile(playbookDir) {
+  if (playbookDir) {
+    const override = path.join(playbookDir, OVERRIDE_FILENAME)
+    try {
+      await access(override)
+      return override
+    } catch {
+      // No ejected override — fall through to the bundled default.
+    }
+  }
+  return BUNDLED_COMPOSE_FILE
+}
+
+function sleep(ms) {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms))
+}
+
+/**
+ * Ensures a Kroki service answers at `url`, starting one via `docker
+ * compose` if nothing does yet. Never throws: a missing `docker` binary, a
+ * daemon that isn't running, or a service that never comes up within the
+ * timeout all degrade to a logged warning — kroki.js's own cache-miss
+ * fallback (raw diagram source, exactly like a disabled site) already
+ * handles the rest, so this never needs to fail a build itself.
+ *
+ * @param {string} url - the fixed Kroki URL (`kroki-config.js`'s `KROKI_URL`).
+ * @param {string | undefined} playbookDir - `playbook.dir`; used to look up
+ *   an ejected override compose file before falling back to the bundled one.
+ * @param {{ info: (fmt: string, ...args: unknown[]) => void, warn: (fmt: string, ...args: unknown[]) => void }} logger -
+ *   `info` gives every run — cache hit or cold start — a visible trail of
+ *   what actually happened, since the only prior signal was a `warn` on
+ *   failure; a healthy run was otherwise silent and indistinguishable from
+ *   Nx quietly replaying a stale cached build (see kroki-prewarm.js's own
+ *   header on cache interaction).
+ * @param {{ isReachable?: typeof isReachable, execFileAsync?: typeof execFileAsync, sleep?: typeof sleep }} [deps] -
+ *   swappable seams for tests, rather than mocking `node:child_process`/
+ *   `fetch` at the module level.
+ * @returns {Promise<void>}
+ */
+async function ensureKrokiRunning(url, playbookDir, logger, deps = {}) {
+  const checkReachable = deps.isReachable || isReachable
+  const runDockerCompose = deps.execFileAsync || execFileAsync
+  const wait = deps.sleep || sleep
+  const startedAt = Date.now()
+
+  if (await checkReachable(url)) {
+    logger.info('Kroki service already reachable at %s — reusing it', url)
+    return
+  }
+
+  const composeFile = await resolveComposeFile(playbookDir)
+  logger.info('Kroki service not reachable at %s yet — starting it via %s', url, composeFile)
+  let composeResult
+  try {
+    composeResult = await runDockerCompose('docker', ['compose', '-f', composeFile, 'up', '-d'])
+  } catch (err) {
+    // Node attaches `stdout`/`stderr` to the rejection itself (not just
+    // `message`) for a failed execFile — surfacing them is the difference
+    // between "is Docker installed?" and actually seeing docker's own error
+    // (a missing image, a port already bound, a daemon that refused the
+    // connection, ...).
+    const stdout = /** @type {{ stdout?: string }} */ (err).stdout
+    const stderr = /** @type {{ stderr?: string }} */ (err).stderr
+    logger.warn(
+      'Could not start the local Kroki service (%s) — is Docker installed and running? Diagrams will render as raw source until %s is reachable.%s',
+      /** @type {Error} */ (err).message,
+      url,
+      formatProcessOutput(stdout, stderr)
+    )
+    return
+  }
+  logger.info(
+    'docker compose up -d succeeded — waiting for %s to become reachable...%s',
+    url,
+    formatProcessOutput(composeResult && composeResult.stdout, composeResult && composeResult.stderr)
+  )
+
+  const deadline = Date.now() + STARTUP_TIMEOUT_MS
+  while (Date.now() < deadline) {
+    if (await checkReachable(url)) {
+      logger.info('Kroki service reachable at %s after %ds', url, Math.round((Date.now() - startedAt) / 1000))
+      return
+    }
+    logger.info(
+      'Still waiting for Kroki at %s to become reachable (%ds elapsed, giving up after %ds — a cold `docker compose up` pulling images for the first time is the usual reason this takes a while)...',
+      url,
+      Math.round((Date.now() - startedAt) / 1000),
+      STARTUP_TIMEOUT_MS / 1000
+    )
+    await wait(POLL_INTERVAL_MS)
+  }
+  logger.warn(
+    'Started the local Kroki service but it did not become reachable at %s within %ds — diagrams will render as raw source for this build.',
+    url,
+    STARTUP_TIMEOUT_MS / 1000
+  )
+}
+
+/**
+ * Renders captured process output for a log message — empty/whitespace-only
+ * streams (the common case: `docker compose up -d` is quiet on a warm image
+ * cache) contribute nothing, so a healthy run's log line doesn't grow a
+ * trailing blank appendix.
+ *
+ * @param {string | undefined} stdout
+ * @param {string | undefined} stderr
+ * @returns {string}
+ */
+function formatProcessOutput(stdout, stderr) {
+  const parts = []
+  if (stdout && stdout.trim()) parts.push('stdout:\n' + stdout.trim())
+  if (stderr && stderr.trim()) parts.push('stderr:\n' + stderr.trim())
+  return parts.length ? '\n' + parts.join('\n') : ''
+}
+
+module.exports = { ensureKrokiRunning, BUNDLED_COMPOSE_FILE, OVERRIDE_FILENAME }

package/lib/kroki-docker.spec.js

@@ -0,0 +1,92 @@
+'use strict'
+
+import { describe, expect, it, vi } from 'vitest'
+
+const { ensureKrokiRunning, BUNDLED_COMPOSE_FILE } = require('./kroki-docker')
+
+function logger() {
+  const warnings = []
+  const infos = []
+  return { warn: (...args) => warnings.push(args), info: (...args) => infos.push(args), warnings, infos }
+}
+
+describe('ensureKrokiRunning', () => {
+  it('does nothing when Kroki already answers', async () => {
+    const isReachable = vi.fn().mockResolvedValue(true)
+    const execFileAsync = vi.fn()
+    const log = logger()
+
+    await ensureKrokiRunning('http://localhost:8500', undefined, log, { isReachable, execFileAsync })
+
+    expect(execFileAsync).not.toHaveBeenCalled()
+    expect(log.warnings).toEqual([])
+    expect(log.infos.some(([msg]) => msg.includes('already reachable'))).toBe(true)
+  })
+
+  it('starts the bundled compose file when nothing answers, then succeeds on the next probe', async () => {
+    const isReachable = vi.fn().mockResolvedValueOnce(false).mockResolvedValueOnce(true)
+    const execFileAsync = vi.fn().mockResolvedValue({ stdout: '', stderr: '' })
+    const log = logger()
+
+    await ensureKrokiRunning('http://localhost:8500', undefined, log, { isReachable, execFileAsync })
+
+    expect(execFileAsync).toHaveBeenCalledTimes(1)
+    expect(execFileAsync).toHaveBeenCalledWith('docker', ['compose', '-f', BUNDLED_COMPOSE_FILE, 'up', '-d'])
+    expect(log.warnings).toEqual([])
+    expect(log.infos.some(([msg]) => msg.includes('starting it via'))).toBe(true)
+    expect(log.infos.some(([msg]) => msg.includes('up -d succeeded'))).toBe(true)
+    expect(log.infos.some(([msg]) => msg.includes('reachable at %s after'))).toBe(true)
+  })
+
+  it('warns and gives up quietly when docker compose itself fails (e.g. Docker not installed)', async () => {
+    const isReachable = vi.fn().mockResolvedValue(false)
+    const execFileAsync = vi.fn().mockRejectedValue(new Error('spawn docker ENOENT'))
+    const log = logger()
+
+    await ensureKrokiRunning('http://localhost:8500', undefined, log, { isReachable, execFileAsync })
+
+    expect(log.warnings.some(([msg]) => msg.includes('Could not start the local Kroki service'))).toBe(true)
+  })
+
+  it('warns when the service never becomes reachable within the timeout', async () => {
+    const isReachable = vi.fn().mockResolvedValue(false)
+    const execFileAsync = vi.fn().mockResolvedValue({ stdout: '', stderr: '' })
+    const sleep = vi.fn().mockResolvedValue(undefined)
+    const log = logger()
+
+    const realNow = Date.now
+    let now = 0
+    vi.spyOn(Date, 'now').mockImplementation(() => now)
+    // Advance the fake clock a bit further than the timeout on every sleep()
+    // call, so the polling loop's own `Date.now() < deadline` check exits
+    // after a couple of iterations instead of looping until a real 60s pass.
+    sleep.mockImplementation(async () => {
+      now += 30000
+    })
+
+    try {
+      await ensureKrokiRunning('http://localhost:8500', undefined, log, { isReachable, execFileAsync, sleep })
+    } finally {
+      Date.now = realNow
+    }
+
+    expect(log.warnings.some(([msg]) => msg.includes('did not become reachable'))).toBe(true)
+  })
+
+  it('prefers an ejected override compose file over the bundled default', async () => {
+    const isReachable = vi.fn().mockResolvedValueOnce(false).mockResolvedValueOnce(true)
+    const execFileAsync = vi.fn().mockResolvedValue({ stdout: '', stderr: '' })
+    const log = logger()
+
+    // No override file actually exists at this made-up path, so this also
+    // exercises the "falls back to the bundled file" branch — a real
+    // override's presence is covered by copy-template-style file-existence
+    // logic already tested at the CLI layer (eject.spec.ts).
+    await ensureKrokiRunning('http://localhost:8500', '/tmp/does-not-exist-kroki-docker-spec', log, {
+      isReachable,
+      execFileAsync,
+    })
+
+    expect(execFileAsync).toHaveBeenCalledWith('docker', ['compose', '-f', BUNDLED_COMPOSE_FILE, 'up', '-d'])
+  })
+})