@panomc/client-gen 0.0.0-stage → 1.0.0-dev.61

package/src/pull.js

@@ -0,0 +1,178 @@
+// pull: core document + every active plugin's OpenAPI and controllers from a running Pano (doc 06 §2.4).
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join, resolve } from 'node:path'
+import { canonicalJson, shortHash } from './canonical.js'
+import { ClientGenError } from './errors.js'
+import { generateClient } from './generate.js'
+import { getText, isSafeName, namespaceOf, parseJson, trimBase, unreachableMessage } from './http.js'
+
+/**
+ * @typedef {Object} PullOptions
+ * @property {string} url
+ * @property {string} [out]            default src/lib/pano
+ * @property {string[]} [plugins]      extra plugin ids that have no UI package
+ * @property {string} [cwd]
+ * @property {typeof fetch} [fetch]
+ * @property {string | null} [installedCore]  path of the installed @panomc/client core/openapi.json; default: resolved from cwd
+ * @property {(line: string) => void} [log]
+ */
+
+/**
+ * @typedef {Object} PullReport
+ * @property {'written'|'skipped'} core
+ * @property {{ pluginId: string, ns: string, openapi: boolean, controllers: boolean }[]} plugins
+ * @property {string[]} warnings
+ */
+
+/** @param {string} cwd */
+function findInstalledCore(cwd) {
+  try {
+    return createRequire(join(cwd, 'package.json')).resolve('@panomc/client/core/openapi.json')
+  } catch {
+    return null
+  }
+}
+
+/** @param {string} dir @param {Record<string, string>} files */
+export function writeFiles(dir, files) {
+  for (const [name, content] of Object.entries(files)) {
+    const target = join(dir, name)
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, content)
+  }
+}
+
+/**
+ * @param {PullOptions} options
+ * @returns {Promise<PullReport>}
+ */
+export async function pull(options) {
+  if (!options.url) throw new ClientGenError('pull needs --url <pano>, e.g. --url http://localhost:8088')
+  const base = trimBase(options.url)
+  const cwd = resolve(options.cwd ?? process.cwd())
+  const out = resolve(cwd, options.out ?? 'src/lib/pano')
+  const log = options.log ?? (() => {})
+  const fetchOpts = { fetch: options.fetch, onUnreachable: () => unreachableMessage(base) }
+  /** @type {string[]} */
+  const warnings = []
+  const warn = (/** @type {string} */ m) => {
+    warnings.push(m)
+    log(`warning: ${m}`)
+  }
+
+  // ---- core
+  const coreRes = await getText(`${base}/api/v1/openapi.json`, fetchOpts)
+  if (!coreRes.ok) {
+    throw new ClientGenError(`Pano answered ${coreRes.status} at ${base}/api/v1/openapi.json. Is this a Pano with the /api/v1 API?`)
+  }
+  const coreDoc = parseJson(coreRes.text, `${base}/api/v1/openapi.json`)
+  const coreCanonical = canonicalJson(coreDoc)
+  const installedPath = options.installedCore === undefined ? findInstalledCore(cwd) : options.installedCore
+  let coreState = /** @type {'written'|'skipped'} */ ('written')
+  if (installedPath && existsSync(installedPath) && readFileSync(installedPath, 'utf8') === coreCanonical) {
+    coreState = 'skipped'
+    log('core: matches the installed @panomc/client, import from @panomc/client/core')
+  } else {
+    const gen = generateClient(coreDoc)
+    gen.warnings.forEach((w) => warn(`core: ${w}`))
+    writeFiles(join(out, 'core'), gen.files)
+    log(`core: ${gen.operations.length} operations written to ${join(out, 'core')}`)
+  }
+
+  // ---- plugin package list
+  /** @type {Map<string, any>} */
+  const packages = new Map()
+  const listRes = await getText(`${base}/api/v1/plugin-packages`, fetchOpts)
+  if (listRes.ok) {
+    const list = parseJson(listRes.text, `${base}/api/v1/plugin-packages`)
+    const plugins = list && typeof list.plugins === 'object' && list.plugins ? list.plugins : {}
+    for (const id of Object.keys(plugins).sort()) packages.set(id, plugins[id] ?? {})
+  } else {
+    warn(`${base}/api/v1/plugin-packages answered ${listRes.status}; only plugins named with --plugin are pulled`)
+  }
+  for (const id of options.plugins ?? []) if (!packages.has(id)) packages.set(id, null)
+
+  // ---- per plugin
+  /** @type {Record<string, { pluginId: string, version: string | null, operationsHash: string | null, controllersHash: string | null }>} */
+  const index = {}
+  /** @type {PullReport['plugins']} */
+  const reported = []
+  const indexPath = join(out, 'plugins', 'index.json')
+  /** @type {Record<string, any>} */
+  let previous = {}
+  try {
+    previous = JSON.parse(readFileSync(indexPath, 'utf8'))
+  } catch {}
+
+  for (const [pluginId, pkg] of packages) {
+    if (!isSafeName(pluginId)) {
+      warn(`plugin id "${pluginId}" is not a valid id, skipped`)
+      continue
+    }
+    const ns = pkg && typeof pkg.namespace === 'string' && pkg.namespace ? pkg.namespace : namespaceOf(pluginId)
+    if (!isSafeName(ns) || index[ns]) {
+      warn(`plugin ${pluginId}: namespace "${ns}" is invalid or already taken, skipped`)
+      continue
+    }
+    const id = encodeURIComponent(pluginId)
+    const pluginDir = join(out, 'plugins', ns)
+
+    // OpenAPI
+    let operationsHash = null
+    let openapi = false
+    const docRes = await getText(`${base}/api/v1/plugins/${id}/_/openapi.json`, fetchOpts)
+    if (docRes.ok) {
+      const doc = parseJson(docRes.text, `${base}/api/v1/plugins/${pluginId}/_/openapi.json`)
+      const gen = generateClient(doc)
+      gen.warnings.forEach((w) => warn(`${ns}: ${w}`))
+      writeFiles(pluginDir, gen.files)
+      operationsHash = shortHash(gen.files['openapi.json'])
+      openapi = true
+      log(`${ns}: ${gen.operations.length} operations written to ${pluginDir}`)
+    } else if (docRes.status === 404) {
+      warn(`plugin ${pluginId} ships no OpenAPI (no client generated)`)
+    } else {
+      warn(`plugin ${pluginId}: ${base}/api/v1/plugins/${pluginId}/_/openapi.json answered ${docRes.status}, no client generated`)
+    }
+
+    // controllers
+    let controllersHash = null
+    let controllers = false
+    if (pkg && pkg.controllers) {
+      const mjs = await getText(`${base}/api/v1/plugins/${id}/_/ui/controllers/controllers.mjs`, fetchOpts)
+      const types = await getText(`${base}/api/v1/plugins/${id}/_/ui/contract/controllers.types.js`, fetchOpts)
+      if (mjs.ok) {
+        /** @type {Record<string, string>} */
+        const files = { 'controllers.mjs': mjs.text }
+        if (types.ok) files['controllers.types.js'] = types.text
+        else warn(`plugin ${pluginId}: controllers.types.js answered ${types.status}, controllers are copied without types`)
+        writeFiles(join(pluginDir, 'controllers'), files)
+        controllersHash = shortHash(mjs.text + '\0' + (types.ok ? types.text : ''))
+        controllers = true
+        log(`${ns}: controllers copied`)
+      } else {
+        warn(`plugin ${pluginId}: controllers.mjs answered ${mjs.status}, no controllers copied`)
+      }
+    }
+
+    index[ns] = {
+      pluginId,
+      version: pkg && typeof pkg.version === 'string' ? pkg.version : null,
+      operationsHash,
+      controllersHash
+    }
+    reported.push({ pluginId, ns, openapi, controllers })
+  }
+
+  // generated folders of plugins that are gone (only those a previous pull recorded)
+  for (const ns of Object.keys(previous)) {
+    if (!index[ns] && isSafeName(ns)) rmSync(join(out, 'plugins', ns), { recursive: true, force: true })
+  }
+
+  const sorted = Object.fromEntries(Object.keys(index).sort().map((k) => [k, index[k]]))
+  writeFiles(join(out, 'plugins'), { 'index.json': JSON.stringify(sorted, null, 2) + '\n' })
+  log(`plugins: ${Object.keys(sorted).length} recorded in ${indexPath}`)
+
+  return { core: coreState, plugins: reported, warnings }
+}

package/src/pull.test.js

@@ -0,0 +1,301 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { canonicalJson, shortHash } from './canonical.js'
+import { check } from './check.js'
+import { run } from './cli.js'
+import { ClientGenError } from './errors.js'
+import { pull } from './pull.js'
+import { FIXTURE, tmp } from './test-helpers.js'
+
+const core = JSON.parse(readFileSync(FIXTURE, 'utf8'))
+
+const marketDoc = {
+  openapi: '3.1.0',
+  info: { title: 'market', version: '1' },
+  servers: [{ url: '/api/plugins/pano-plugin-market' }],
+  paths: {
+    '/store/products': {
+      get: { operationId: 'ListProducts', responses: { 200: { content: { 'application/json': { schema: { type: 'object', properties: { items: { type: 'array', items: { $ref: '#/components/schemas/Product' } } } } } } } } }
+    },
+    '/store/products/{id}': {
+      get: { operationId: 'GetProduct', parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'integer' } }], responses: { 200: { content: { 'application/json': { schema: { $ref: '#/components/schemas/Product' } } } } } }
+    }
+  },
+  components: { schemas: { Product: { type: 'object', required: ['id'], properties: { id: { type: 'integer' }, name: { type: 'string' } } } } }
+}
+
+const extraDoc = {
+  openapi: '3.1.0',
+  servers: [{ url: '/api/plugins/pano-plugin-extra' }],
+  paths: { '/ping': { get: { operationId: 'Ping', responses: { 200: { description: 'pong' } } } } }
+}
+
+/** the stub's world; tests mutate it */
+function freshWorld() {
+  return {
+    core: structuredClone(core),
+    packages: /** @type {Record<string, any>} */ ({
+      'pano-plugin-market': { format: 1, pluginId: 'pano-plugin-market', namespace: 'market', version: '1.2.0', controllers: 'contract/controllers.json' },
+      'pano-plugin-faq': { format: 1, pluginId: 'pano-plugin-faq', namespace: 'faq', version: '0.3.1' }
+    }),
+    docs: /** @type {Record<string, any>} */ ({ 'pano-plugin-market': structuredClone(marketDoc), 'pano-plugin-extra': extraDoc }),
+    controllers: 'export const controllers = { cart: {} }\n',
+    types: '/** @typedef {{ count: number }} CartState */\nexport {};\n',
+    requests: /** @type {string[]} */ ([]),
+    listBroken: false
+  }
+}
+
+/** @type {ReturnType<typeof freshWorld>} */
+let world
+/** @type {any} */
+let server
+let base = ''
+const dirs = []
+
+beforeAll(() => {
+  world = freshWorld()
+  server = Bun.serve({
+    port: 0,
+    hostname: '127.0.0.1',
+    fetch(req) {
+      const path = new URL(req.url).pathname
+      world.requests.push(path)
+      const json = (/** @type {any} */ v) => new Response(JSON.stringify(v), { headers: { 'content-type': 'application/json' } })
+      if (path === '/api/v1/openapi.json') return json(world.core)
+      if (path === '/api/v1/plugin-packages') return world.listBroken ? new Response('nope', { status: 404 }) : json({ plugins: world.packages })
+      const m = /^\/api\/v1\/plugins\/([^/]+)\/_\/(.+)$/.exec(path)
+      if (m) {
+        const [, id, rest] = m
+        if (rest === 'openapi.json') return world.docs[id] ? json(world.docs[id]) : new Response('{"error":{"code":"NOT_FOUND"}}', { status: 404 })
+        if (id === 'pano-plugin-market' && rest === 'ui/controllers/controllers.mjs') return new Response(world.controllers, { headers: { 'content-type': 'text/javascript' } })
+        if (id === 'pano-plugin-market' && rest === 'ui/contract/controllers.types.js') return new Response(world.types)
+      }
+      return new Response('{"error":{"code":"NOT_FOUND"}}', { status: 404 })
+    }
+  })
+  base = `http://127.0.0.1:${server.port}`
+})
+afterAll(() => {
+  server.stop(true)
+  for (const d of dirs) rmSync(d, { recursive: true, force: true })
+})
+
+const newDir = (/** @type {string} */ n) => {
+  const d = tmp(n)
+  dirs.push(d)
+  return d
+}
+
+describe('pull', () => {
+  test('core, both plugins, controllers and the index', async () => {
+    world = Object.assign(world, freshWorld(), { requests: [] })
+    const cwd = newDir('pull')
+    const logs = []
+    const report = await pull({ url: base + '/', cwd, installedCore: null, log: (l) => logs.push(l) })
+    const out = join(cwd, 'src/lib/pano')
+
+    expect(report.core).toBe('written')
+    for (const f of ['index.js', 'types.js', 'operations.js', 'openapi.json']) {
+      expect(existsSync(join(out, 'core', f))).toBe(true)
+      expect(existsSync(join(out, 'plugins/market', f))).toBe(true)
+    }
+    expect(readFileSync(join(out, 'core/openapi.json'), 'utf8')).toBe(canonicalJson(core))
+    expect(readFileSync(join(out, 'plugins/market/index.js'), 'utf8')).toContain('export const listProducts')
+    expect(readFileSync(join(out, 'plugins/market/controllers/controllers.mjs'), 'utf8')).toBe(world.controllers)
+    expect(readFileSync(join(out, 'plugins/market/controllers/controllers.types.js'), 'utf8')).toBe(world.types)
+
+    // faq ships no OpenAPI: no folder, a warning, but it is recorded
+    expect(existsSync(join(out, 'plugins/faq'))).toBe(false)
+    expect(report.warnings).toContain('plugin pano-plugin-faq ships no OpenAPI (no client generated)')
+    expect(logs).toContain('warning: plugin pano-plugin-faq ships no OpenAPI (no client generated)')
+
+    const index = JSON.parse(readFileSync(join(out, 'plugins/index.json'), 'utf8'))
+    expect(Object.keys(index)).toEqual(['faq', 'market'])
+    expect(index.faq).toEqual({ pluginId: 'pano-plugin-faq', version: '0.3.1', operationsHash: null, controllersHash: null })
+    expect(index.market).toEqual({
+      pluginId: 'pano-plugin-market',
+      version: '1.2.0',
+      operationsHash: shortHash(canonicalJson(marketDoc)),
+      controllersHash: shortHash(world.controllers + '\0' + world.types)
+    })
+    // the plugin documents were read from the plugin paths, the controllers from _/ui
+    expect(world.requests).toContain('/api/v1/plugins/pano-plugin-market/_/openapi.json')
+    expect(world.requests).toContain('/api/v1/plugins/pano-plugin-market/_/ui/controllers/controllers.mjs')
+    expect(world.requests).toContain('/api/v1/plugins/pano-plugin-market/_/ui/contract/controllers.types.js')
+  })
+
+  test('a second pull writes identical bytes', async () => {
+    world = Object.assign(world, freshWorld())
+    const cwd = newDir('pull2')
+    await pull({ url: base, cwd, installedCore: null })
+    const read = () => ['core/index.js', 'plugins/market/types.js', 'plugins/index.json'].map((f) => readFileSync(join(cwd, 'src/lib/pano', f), 'utf8'))
+    const first = read()
+    await pull({ url: base, cwd, installedCore: null })
+    expect(read()).toEqual(first)
+  })
+
+  test('core/ is skipped when the installed @panomc/client snapshot is byte-equal', async () => {
+    world = Object.assign(world, freshWorld())
+    const cwd = newDir('pull-skip')
+    const installed = join(cwd, 'installed-openapi.json')
+    writeFileSync(installed, canonicalJson(core))
+    const report = await pull({ url: base, cwd, installedCore: installed })
+    expect(report.core).toBe('skipped')
+    expect(existsSync(join(cwd, 'src/lib/pano/core'))).toBe(false)
+    expect(existsSync(join(cwd, 'src/lib/pano/plugins/market/index.js'))).toBe(true)
+
+    writeFileSync(installed, canonicalJson({ ...core, info: { title: 'older', version: '0' } }))
+    expect((await pull({ url: base, cwd, installedCore: installed })).core).toBe('written')
+    expect(existsSync(join(cwd, 'src/lib/pano/core/index.js'))).toBe(true)
+  })
+
+  test('--plugin adds a plugin that is not in the package list; --out is honoured', async () => {
+    world = Object.assign(world, freshWorld())
+    const cwd = newDir('pull-plugin')
+    const report = await pull({ url: base, cwd, out: 'gen', plugins: ['pano-plugin-extra', 'pano-plugin-market'], installedCore: null })
+    expect(report.plugins.map((p) => p.ns).sort()).toEqual(['extra', 'faq', 'market'])
+    expect(readFileSync(join(cwd, 'gen/plugins/extra/index.js'), 'utf8')).toContain('export const ping')
+    const index = JSON.parse(readFileSync(join(cwd, 'gen/plugins/index.json'), 'utf8'))
+    expect(index.extra).toEqual({ pluginId: 'pano-plugin-extra', version: null, operationsHash: shortHash(canonicalJson(extraDoc)), controllersHash: null })
+  })
+
+  test('an extra plugin without OpenAPI warns and a plugin that left is removed on the next pull', async () => {
+    world = Object.assign(world, freshWorld())
+    const cwd = newDir('pull-gone')
+    await pull({ url: base, cwd, installedCore: null })
+    expect(existsSync(join(cwd, 'src/lib/pano/plugins/market'))).toBe(true)
+    delete world.packages['pano-plugin-market']
+    const report = await pull({ url: base, cwd, installedCore: null, plugins: ['pano-plugin-ghost'] })
+    expect(report.warnings).toContain('plugin pano-plugin-ghost ships no OpenAPI (no client generated)')
+    expect(existsSync(join(cwd, 'src/lib/pano/plugins/market'))).toBe(false)
+  })
+
+  test('unsafe plugin ids are skipped', async () => {
+    world = Object.assign(world, freshWorld())
+    const cwd = newDir('pull-unsafe')
+    const report = await pull({ url: base, cwd, installedCore: null, plugins: ['../evil'] })
+    expect(report.warnings.some((w) => w.includes('"../evil" is not a valid id'))).toBe(true)
+    expect(existsSync(join(cwd, 'src/lib/evil'))).toBe(false)
+  })
+
+  test('a Pano without the package list still pulls core and named plugins', async () => {
+    world = Object.assign(world, freshWorld(), { listBroken: true })
+    const cwd = newDir('pull-nolist')
+    const report = await pull({ url: base, cwd, installedCore: null, plugins: ['pano-plugin-extra'] })
+    world.listBroken = false
+    expect(report.warnings.some((w) => w.includes('/api/v1/plugin-packages answered 404'))).toBe(true)
+    expect(report.plugins.map((p) => p.ns)).toEqual(['extra'])
+  })
+
+  test('unreachable Pano: the exact message', async () => {
+    const dead = Bun.serve({ port: 0, hostname: '127.0.0.1', fetch: () => new Response('x') })
+    const url = `http://127.0.0.1:${dead.port}`
+    dead.stop(true)
+    const cwd = newDir('pull-dead')
+    await expect(pull({ url, cwd, installedCore: null })).rejects.toThrow(
+      `Pano did not answer at ${url}/api/v1/openapi.json. Is it running? Try --url http://localhost:8088`
+    )
+    const errs = []
+    const code = await run(['pull', '--url', url], { cwd, stderr: (s) => errs.push(s) })
+    expect(code).toBe(1)
+    expect(errs).toEqual([`Pano did not answer at ${url}/api/v1/openapi.json. Is it running? Try --url http://localhost:8088`])
+    expect(existsSync(join(cwd, 'src'))).toBe(false)
+  })
+
+  test('missing --url', async () => {
+    await expect(pull({ url: '' })).rejects.toBeInstanceOf(ClientGenError)
+  })
+
+  test('cli: pull with --plugin twice', async () => {
+    world = Object.assign(world, freshWorld())
+    const cwd = newDir('pull-cli')
+    const outs = []
+    const code = await run(['pull', '--url', base, '--out', 'o', '--plugin', 'pano-plugin-extra', '--plugin', 'pano-plugin-ghost'], { cwd, stdout: (s) => outs.push(s), stderr: () => {} })
+    expect(code).toBe(0)
+    expect(existsSync(join(cwd, 'o/plugins/extra/index.js'))).toBe(true)
+    expect(outs.some((l) => l.includes('plugin pano-plugin-ghost ships no OpenAPI (no client generated)'))).toBe(true)
+  })
+})
+
+describe('check', () => {
+  /** pulls the fresh world into a new dir and returns { cwd } */
+  async function pulled() {
+    world = Object.assign(world, freshWorld())
+    const cwd = newDir('check')
+    await pull({ url: base, cwd, installedCore: null })
+    return cwd
+  }
+
+  test('unchanged Pano: ok, exit 0', async () => {
+    const cwd = await pulled()
+    const report = await check({ url: base, cwd, installedCore: null })
+    expect(report).toEqual({ ok: true, problems: [], notes: [] })
+    const outs = []
+    expect(await run(['check', '--url', base, '--dir', 'src/lib/pano'], { cwd, stdout: (s) => outs.push(s), stderr: () => {} })).toBe(0)
+  })
+
+  test('removed and changed operations, a new one is only a note', async () => {
+    const cwd = await pulled()
+    delete world.core.paths['/api/v1/posts/{url}'].delete
+    world.core.paths['/api/v1/posts'].get.parameters.push({ name: 'q', in: 'query', schema: { type: 'string' } })
+    world.core.components.schemas.Author.properties.nick = { type: 'string' } // changes GetPost / GetPosts / CreatePost responses
+    world.core.paths['/api/v1/hello'] = { get: { operationId: 'Hello', responses: { 200: { description: 'hi' } } } }
+    const report = await check({ url: base, cwd, installedCore: null })
+    expect(report.ok).toBe(false)
+    expect(report.problems).toEqual([
+      'core: changed createPost (POST /api/v1/posts)',
+      'core: removed deletePost (DELETE /api/v1/posts/{url})',
+      'core: changed getPost (GET /api/v1/posts/{url})',
+      'core: changed getPosts (GET /api/v1/posts)'
+    ])
+    expect(report.notes).toContain('core: new hello (GET /api/v1/hello)')
+
+    const errs = []
+    expect(await run(['check', '--url', base], { cwd, stdout: () => {}, stderr: (s) => errs.push(s) })).toBe(1)
+    expect(errs).toContain('core: removed deletePost (DELETE /api/v1/posts/{url})')
+    expect(errs.at(-1)).toBe('The generated client is out of date. Run pano-client pull.')
+  })
+
+  test('controllersHash differs -> run pano-client pull', async () => {
+    const cwd = await pulled()
+    world.controllers += '// new action\n'
+    const report = await check({ url: base, cwd, installedCore: null })
+    expect(report.ok).toBe(false)
+    expect(report.problems).toEqual(['market: controllers changed (run pano-client pull)'])
+  })
+
+  test('plugin operation removed, and a plugin that is gone', async () => {
+    const cwd = await pulled()
+    delete world.docs['pano-plugin-market'].paths['/store/products']
+    let report = await check({ url: base, cwd, installedCore: null })
+    expect(report.problems).toEqual(['market: removed listProducts (GET /api/plugins/pano-plugin-market/store/products)'])
+
+    delete world.packages['pano-plugin-market']
+    delete world.docs['pano-plugin-market']
+    report = await check({ url: base, cwd, installedCore: null })
+    expect(report.problems).toEqual(['market: plugin pano-plugin-market is no longer active on this Pano (run pano-client pull)'])
+  })
+
+  test('core snapshot comes from the installed package when core/ was skipped', async () => {
+    world = Object.assign(world, freshWorld())
+    const cwd = newDir('check-installed')
+    const installed = join(cwd, 'installed.json')
+    writeFileSync(installed, canonicalJson(core))
+    await pull({ url: base, cwd, installedCore: installed })
+    expect((await check({ url: base, cwd, installedCore: installed })).ok).toBe(true)
+    delete world.core.paths['/api/v1/posts/{url}'].delete
+    expect((await check({ url: base, cwd, installedCore: installed })).problems).toEqual(['core: removed deletePost (DELETE /api/v1/posts/{url})'])
+  })
+
+  test('nothing pulled yet, and an unreachable Pano', async () => {
+    const empty = newDir('check-empty')
+    await expect(check({ url: base, cwd: empty })).rejects.toThrow(`Nothing to check in ${join(empty, 'src/lib/pano')}. Run pano-client pull --url ${base} first.`)
+    const cwd = await pulled()
+    const dead = Bun.serve({ port: 0, hostname: '127.0.0.1', fetch: () => new Response('x') })
+    const url = `http://127.0.0.1:${dead.port}`
+    dead.stop(true)
+    await expect(check({ url, cwd, installedCore: null })).rejects.toThrow(`Pano did not answer at ${url}/api/v1/openapi.json. Is it running? Try --url http://localhost:8088`)
+  })
+})

package/src/schema.js

@@ -0,0 +1,202 @@
+// OpenAPI 3.1 schema -> JSDoc type string. A plain walk over the JSON, no dependency.
+
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+
+/** @param {string} s */
+export const isIdent = (s) => IDENT.test(s)
+
+/** Property key as it appears in an object type literal. @param {string} s */
+export const propKey = (s) => (isIdent(s) ? s : quote(s))
+
+/** @param {string} s */
+export function quote(s) {
+  return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\r?\n/g, '\\n')}'`
+}
+
+/**
+ * Precedence of a rendered type: 0 union, 1 intersection, 2 atom (needs no parentheses anywhere).
+ * @typedef {{ s: string, p: number }} Rendered
+ */
+
+/** @param {Rendered} r @param {number} min */
+const at = (r, min) => (r.p < min ? `(${r.s})` : r.s)
+
+/** @param {string} s @returns {Rendered} */
+const atom = (s) => ({ s, p: 2 })
+
+/** @param {Rendered[]} parts @returns {Rendered} */
+function union(parts) {
+  const seen = new Set()
+  const out = []
+  for (const part of parts) {
+    if (seen.has(part.s)) continue
+    seen.add(part.s)
+    out.push(part)
+  }
+  if (out.length === 0) return atom('never')
+  if (out.length === 1) return out[0]
+  if (out.some((p) => p.s === 'any')) return atom('any')
+  return { s: out.map((p) => at(p, 0)).join(' | '), p: 0 }
+}
+
+/** @param {Rendered[]} parts @returns {Rendered} */
+function intersection(parts) {
+  if (parts.length === 1) return parts[0]
+  if (parts.length === 0) return atom('any')
+  return { s: parts.map((p) => at(p, 1)).join(' & '), p: 1 }
+}
+
+/** @param {any} v */
+function literal(v) {
+  if (typeof v === 'string') return quote(v)
+  if (v === null) return 'null'
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v)
+  return 'any'
+}
+
+/**
+ * @typedef {Object} TypeContext
+ * @property {(schemaName: string) => string} ref   how a components.schemas entry is named at the call site
+ */
+
+/**
+ * @param {any} schema
+ * @param {TypeContext} ctx
+ * @returns {string}
+ */
+export function schemaType(schema, ctx) {
+  return render(schema, ctx).s
+}
+
+/**
+ * @param {any} schema
+ * @param {TypeContext} ctx
+ * @returns {Rendered}
+ */
+function render(schema, ctx) {
+  if (schema === false) return atom('never')
+  if (schema === true || schema === null || typeof schema !== 'object') return atom('any')
+
+  if (typeof schema.$ref === 'string') {
+    const m = /^#\/components\/schemas\/(.+)$/.exec(schema.$ref)
+    if (!m) return atom('any')
+    const name = m[1].replace(/~1/g, '/').replace(/~0/g, '~')
+    const r = atom(ctx.ref(name))
+    return schema.nullable === true ? union([r, atom('null')]) : r
+  }
+
+  let out = renderBody(schema, ctx)
+  if (schema.nullable === true) out = union([out, atom('null')])
+  return out
+}
+
+/** @param {any} schema @param {TypeContext} ctx @returns {Rendered} */
+function renderBody(schema, ctx) {
+  if ('const' in schema) return atom(literal(schema.const))
+  if (Array.isArray(schema.enum)) return union(schema.enum.map((v) => atom(literal(v))))
+
+  /** @type {Rendered[]} */
+  const parts = []
+  if (Array.isArray(schema.allOf) && schema.allOf.length) {
+    parts.push(intersection(schema.allOf.map((/** @type {any} */ s) => render(s, ctx))))
+  }
+  for (const key of ['oneOf', 'anyOf']) {
+    if (Array.isArray(schema[key]) && schema[key].length) {
+      parts.push(union(schema[key].map((/** @type {any} */ s) => render(s, ctx))))
+    }
+  }
+
+  const hasShape = schema.type !== undefined || schema.properties || schema.additionalProperties !== undefined || schema.items
+  if (hasShape || parts.length === 0) {
+    const own = renderTyped(schema, ctx)
+    // allOf/oneOf next to a bare `type: object` adds nothing; keep the composed part alone
+    if (!(parts.length && own.s === 'Record<string, any>' && !schema.properties)) parts.push(own)
+  }
+  return intersection(parts)
+}
+
+/** @param {any} schema @param {TypeContext} ctx @returns {Rendered} */
+function renderTyped(schema, ctx) {
+  /** @type {string[]} */
+  let types = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : []
+  if (types.length === 0) {
+    if (schema.properties || schema.additionalProperties !== undefined) types = ['object']
+    else if (schema.items) types = ['array']
+    else return atom('any')
+  }
+  return union(types.map((t) => renderOne(t, schema, ctx)))
+}
+
+/** @param {string} type @param {any} schema @param {TypeContext} ctx @returns {Rendered} */
+function renderOne(type, schema, ctx) {
+  switch (type) {
+    case 'string':
+      return atom(schema.format === 'binary' ? 'Blob' : 'string')
+    case 'integer':
+    case 'number':
+      return atom('number')
+    case 'boolean':
+      return atom('boolean')
+    case 'null':
+      return atom('null')
+    case 'array':
+      return atom(`${at(schema.items === undefined ? atom('any') : render(schema.items, ctx), 2)}[]`)
+    case 'object':
+      return renderObject(schema, ctx)
+    default:
+      return atom('any')
+  }
+}
+
+/** @param {any} schema @param {TypeContext} ctx @returns {Rendered} */
+function renderObject(schema, ctx) {
+  const props = schema.properties && typeof schema.properties === 'object' ? schema.properties : {}
+  const names = Object.keys(props)
+  const extra = schema.additionalProperties
+  const extraType =
+    extra === undefined || extra === false
+      ? null
+      : extra === true
+        ? atom('any')
+        : render(extra, ctx)
+
+  if (names.length === 0) return atom(`Record<string, ${extraType ? extraType.s : 'any'}>`)
+
+  const required = new Set(Array.isArray(schema.required) ? schema.required : [])
+  const body = names
+    .map((n) => `${propKey(n)}${required.has(n) ? '' : '?'}: ${render(props[n], ctx).s}`)
+    .join(', ')
+  const literalType = atom(`{ ${body} }`)
+  return extraType ? intersection([literalType, atom(`Record<string, ${extraType.s}>`)]) : literalType
+}
+
+/**
+ * Names, types and descriptions of an object schema's properties when every name is a plain identifier,
+ * so the typedef can use `@property`. Null otherwise (the caller falls back to the inline literal).
+ * @param {any} schema
+ * @param {TypeContext} ctx
+ * @returns {{ name: string, type: string, optional: boolean, description: string }[] | null}
+ */
+export function objectProperties(schema, ctx) {
+  if (!schema || typeof schema !== 'object' || schema.$ref) return null
+  if (schema.allOf || schema.oneOf || schema.anyOf || schema.enum || 'const' in schema || schema.nullable === true) return null
+  if (schema.type !== undefined && schema.type !== 'object') return null
+  if (schema.additionalProperties !== undefined && schema.additionalProperties !== false) return null
+  const props = schema.properties
+  if (!props || typeof props !== 'object') return null
+  const names = Object.keys(props)
+  if (names.length === 0 || !names.every(isIdent)) return null
+  const required = new Set(Array.isArray(schema.required) ? schema.required : [])
+  return names.map((name) => ({
+    name,
+    type: render(props[name], ctx).s,
+    optional: !required.has(name),
+    description: oneLine(props[name] && typeof props[name] === 'object' ? props[name].description : '')
+  }))
+}
+
+/** Collapse text to one comment-safe line. @param {any} text */
+export function oneLine(text) {
+  if (typeof text !== 'string') return ''
+  return text.replace(/\*\//g, '*\\/').replace(/\s+/g, ' ').trim()
+}