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

package/bin/pano-client.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js'
+
+process.exitCode = await run(process.argv.slice(2))

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@panomc/client-gen",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-dev.62",
+  "description": "Generates a typed JavaScript client from a Pano OpenAPI document and scaffolds headless sites (pano-client).",
+  "author": "PanoMC",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "url": "https://github.com/PanoMC/sdk"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "pano-client": "./bin/pano-client.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "templates"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/canonical.js

@@ -0,0 +1,36 @@
+import { createHash } from 'node:crypto'
+
+/**
+ * Deep copy with every object's keys sorted. Arrays keep their order.
+ * @param {any} value
+ * @returns {any}
+ */
+export function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys)
+  if (value && typeof value === 'object') {
+    /** @type {Record<string, any>} */
+    const out = {}
+    for (const key of Object.keys(value).sort()) out[key] = sortKeys(value[key])
+    return out
+  }
+  return value
+}
+
+/**
+ * The one text form of an OpenAPI document: sorted keys, two spaces, trailing newline.
+ * Generated `openapi.json` files and the byte comparison of `pull` / `check` use it.
+ * @param {any} doc
+ */
+export function canonicalJson(doc) {
+  return JSON.stringify(sortKeys(doc), null, 2) + '\n'
+}
+
+/** @param {string|Uint8Array} data */
+export function sha256(data) {
+  return createHash('sha256').update(data).digest('hex')
+}
+
+/** Short stable fingerprint used in `plugins/index.json`. @param {string|Uint8Array} data */
+export function shortHash(data) {
+  return sha256(data).slice(0, 16)
+}

package/src/check.js

@@ -0,0 +1,143 @@
+// check: compare a pulled directory with a running Pano (doc 06 §2.4). Exit 1 on removed / changed operations.
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join, resolve } from 'node:path'
+import { shortHash } from './canonical.js'
+import { ClientGenError } from './errors.js'
+import { collectOperations, fingerprint } from './operations.js'
+import { getText, isSafeName, parseJson, trimBase, unreachableMessage } from './http.js'
+
+/**
+ * @typedef {Object} CheckOptions
+ * @property {string} url
+ * @property {string} [dir]       default src/lib/pano
+ * @property {string} [cwd]
+ * @property {typeof fetch} [fetch]
+ * @property {string | null} [installedCore]
+ */
+
+/**
+ * @typedef {Object} CheckReport
+ * @property {boolean} ok
+ * @property {string[]} problems   removed / changed operations, removed plugins, changed controllers
+ * @property {string[]} notes      additions and skipped parts (never fail the check)
+ */
+
+/** @param {any} doc @param {string} label @param {any} oldDoc @param {string[]} problems @param {string[]} notes */
+function diffDocs(label, oldDoc, doc, problems, notes) {
+  const before = new Map(collectOperations(oldDoc).map((o) => [o.name, o]))
+  const after = new Map(collectOperations(doc).map((o) => [o.name, o]))
+  for (const [name, op] of before) {
+    const now = after.get(name)
+    if (!now) problems.push(`${label}: removed ${name} (${op.method} ${op.path})`)
+    else if (fingerprint(oldDoc, op) !== fingerprint(doc, now)) {
+      const moved = now.method !== op.method || now.path !== op.path
+      problems.push(`${label}: changed ${name} (${op.method} ${op.path}${moved ? ` -> ${now.method} ${now.path}` : ''})`)
+    }
+  }
+  for (const [name, op] of after) if (!before.has(name)) notes.push(`${label}: new ${name} (${op.method} ${op.path})`)
+}
+
+/** @param {string} p */
+function readJson(p) {
+  return JSON.parse(readFileSync(p, 'utf8'))
+}
+
+/**
+ * @param {CheckOptions} options
+ * @returns {Promise<CheckReport>}
+ */
+export async function check(options) {
+  if (!options.url) throw new ClientGenError('check needs --url <pano>, e.g. --url http://localhost:8088')
+  const base = trimBase(options.url)
+  const cwd = resolve(options.cwd ?? process.cwd())
+  const dir = resolve(cwd, options.dir ?? 'src/lib/pano')
+  const fetchOpts = { fetch: options.fetch, onUnreachable: () => unreachableMessage(base) }
+  /** @type {string[]} */
+  const problems = []
+  /** @type {string[]} */
+  const notes = []
+
+  if (!existsSync(join(dir, 'plugins', 'index.json')) && !existsSync(join(dir, 'core', 'openapi.json'))) {
+    throw new ClientGenError(`Nothing to check in ${dir}. Run pano-client pull --url ${base} first.`)
+  }
+
+  // ---- core: the pulled snapshot, else the installed @panomc/client one
+  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`)
+  let coreSnapshot = join(dir, 'core', 'openapi.json')
+  if (!existsSync(coreSnapshot)) {
+    let installed = options.installedCore
+    if (installed === undefined) {
+      try {
+        installed = createRequire(join(cwd, 'package.json')).resolve('@panomc/client/core/openapi.json')
+      } catch {
+        installed = null
+      }
+    }
+    coreSnapshot = installed ?? ''
+  }
+  if (coreSnapshot && existsSync(coreSnapshot)) diffDocs('core', readJson(coreSnapshot), coreDoc, problems, notes)
+  else notes.push('core: no snapshot to compare with, skipped')
+
+  // ---- plugins
+  /** @type {Record<string, any>} */
+  const index = existsSync(join(dir, 'plugins', 'index.json')) ? readJson(join(dir, 'plugins', 'index.json')) : {}
+  /** @type {Map<string, any>} */
+  const packages = new Map()
+  const listRes = await getText(`${base}/api/v1/plugin-packages`, fetchOpts)
+  if (listRes.ok) {
+    const plugins = parseJson(listRes.text, `${base}/api/v1/plugin-packages`)?.plugins ?? {}
+    for (const id of Object.keys(plugins)) packages.set(id, plugins[id] ?? {})
+  } else {
+    notes.push(`plugins: ${base}/api/v1/plugin-packages answered ${listRes.status}, plugins without a UI package are checked by their OpenAPI only`)
+  }
+
+  for (const ns of Object.keys(index).sort()) {
+    const entry = index[ns]
+    const pluginId = entry?.pluginId
+    if (!isSafeName(ns) || !isSafeName(pluginId)) continue
+    const id = encodeURIComponent(pluginId)
+    const pkg = packages.get(pluginId)
+
+    // OpenAPI
+    const snapshot = join(dir, 'plugins', ns, 'openapi.json')
+    const docRes = await getText(`${base}/api/v1/plugins/${id}/_/openapi.json`, fetchOpts)
+    if (docRes.ok) {
+      if (existsSync(snapshot)) diffDocs(ns, readJson(snapshot), parseJson(docRes.text, `${pluginId} openapi.json`), problems, notes)
+      else problems.push(`${ns}: now ships an OpenAPI document (run pano-client pull)`)
+    } else if (existsSync(snapshot)) {
+      if (listRes.ok && !pkg) problems.push(`${ns}: plugin ${pluginId} is no longer active on this Pano (run pano-client pull)`)
+      else problems.push(`${ns}: plugin ${pluginId} no longer ships an OpenAPI document (answered ${docRes.status}, run pano-client pull)`)
+      continue
+    } else if (listRes.ok && !pkg) {
+      problems.push(`${ns}: plugin ${pluginId} is no longer active on this Pano (run pano-client pull)`)
+      continue
+    }
+
+    // controllers
+    if (entry.controllersHash || (pkg && pkg.controllers)) {
+      let current = null
+      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) current = shortHash(mjs.text + '\0' + (types.ok ? types.text : ''))
+      }
+      if (current !== (entry.controllersHash ?? null)) {
+        problems.push(`${ns}: controllers changed (run pano-client pull)`)
+      }
+    }
+  }
+
+  // plugins that appeared since the pull
+  for (const [pluginId, pkg] of packages) {
+    const ns = pkg && typeof pkg.namespace === 'string' && pkg.namespace ? pkg.namespace : pluginId.replace(/^pano-plugin-/, '')
+    if (!index[ns]) notes.push(`${ns}: plugin ${pluginId} is active but was not pulled`)
+  }
+
+  return { ok: problems.length === 0, problems, notes }
+}
+

package/src/cli.js

@@ -0,0 +1,106 @@
+import { mkdirSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { parseArgs } from 'node:util'
+import { check } from './check.js'
+import { ClientGenError } from './errors.js'
+import { generateClient } from './generate.js'
+import { scaffold } from './new.js'
+import { pull, writeFiles } from './pull.js'
+
+export const USAGE = `pano-client - typed client generator for Pano
+
+  pano-client generate --input <openapi.json> --out <dir>
+  pano-client pull --url <pano> [--out src/lib/pano] [--plugin <pluginId>]...
+  pano-client check --url <pano> [--dir src/lib/pano]
+  pano-client new <dir> [--url <pano>] [--from <dir>] [--no-install]
+`
+
+/**
+ * @param {string[]} argv   arguments after the program name
+ * @param {{ cwd?: string, stdout?: (s: string) => void, stderr?: (s: string) => void, fetch?: typeof fetch }} [io]
+ * @returns {Promise<number>} exit code
+ */
+export async function run(argv, io = {}) {
+  const out = io.stdout ?? ((s) => process.stdout.write(s + '\n'))
+  const err = io.stderr ?? ((s) => process.stderr.write(s + '\n'))
+  const cwd = io.cwd ?? process.cwd()
+  const [command, ...rest] = argv
+
+  if (!command || command === '--help' || command === '-h' || command === 'help') {
+    out(USAGE)
+    return command ? 0 : 1
+  }
+
+  try {
+    switch (command) {
+      case 'generate': {
+        const { values } = parseArgs({ args: rest, options: { input: { type: 'string' }, out: { type: 'string' } } })
+        if (!values.input || !values.out) throw new ClientGenError('generate needs --input <openapi.json> and --out <dir>')
+        let text
+        try {
+          text = readFileSync(resolve(cwd, values.input), 'utf8')
+        } catch {
+          throw new ClientGenError(`Cannot read ${resolve(cwd, values.input)}`)
+        }
+        const gen = generateClient(text)
+        gen.warnings.forEach((w) => err(`warning: ${w}`))
+        const dir = resolve(cwd, values.out)
+        mkdirSync(dir, { recursive: true })
+        writeFiles(dir, gen.files)
+        out(`generated ${gen.operations.length} operations in ${dir}`)
+        return 0
+      }
+      case 'pull': {
+        const { values } = parseArgs({
+          args: rest,
+          options: { url: { type: 'string' }, out: { type: 'string' }, plugin: { type: 'string', multiple: true } }
+        })
+        await pull({ url: values.url ?? '', out: values.out, plugins: values.plugin, cwd, fetch: io.fetch, log: out })
+        return 0
+      }
+      case 'check': {
+        const { values } = parseArgs({ args: rest, options: { url: { type: 'string' }, dir: { type: 'string' } } })
+        const report = await check({ url: values.url ?? '', dir: values.dir, cwd, fetch: io.fetch })
+        report.notes.forEach((n) => out(n))
+        if (report.ok) {
+          out('ok: the generated client matches this Pano')
+          return 0
+        }
+        report.problems.forEach((p) => err(p))
+        err('The generated client is out of date. Run pano-client pull.')
+        return 1
+      }
+      case 'new': {
+        const { values, positionals } = parseArgs({
+          args: rest,
+          allowPositionals: true,
+          options: { url: { type: 'string' }, from: { type: 'string' }, 'no-install': { type: 'boolean' } }
+        })
+        const r = await scaffold({
+          dir: positionals[0] ?? '',
+          url: values.url,
+          from: values.from,
+          install: !values['no-install'],
+          cwd,
+          fetch: io.fetch,
+          log: out
+        })
+        out(`\nNext: cd ${positionals[0]} && bun dev`)
+        return r.dir ? 0 : 1
+      }
+      default:
+        err(`Unknown command "${command}".\n\n${USAGE}`)
+        return 1
+    }
+  } catch (e) {
+    if (e instanceof ClientGenError) {
+      err(e.message)
+      return 1
+    }
+    if (e && typeof e === 'object' && /** @type {any} */ (e).code?.startsWith?.('ERR_PARSE_ARGS')) {
+      err(`${/** @type {Error} */ (e).message}\n\n${USAGE}`)
+      return 1
+    }
+    throw e
+  }
+}

package/src/errors.js

@@ -0,0 +1,8 @@
+/** An expected failure: the CLI prints the message as is (no stack) and exits 1. */
+export class ClientGenError extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message)
+    this.name = 'ClientGenError'
+  }
+}

package/src/generate.js

@@ -0,0 +1,201 @@
+// OpenAPI 3.1 document -> index.js, types.js, operations.js, openapi.json (doc 06 §2.3). Pure and deterministic.
+import { canonicalJson, sortKeys } from './canonical.js'
+import { ClientGenError } from './errors.js'
+import { collectOperations, pascal } from './operations.js'
+import { isIdent, objectProperties, oneLine, propKey, quote, schemaType } from './schema.js'
+
+const HEADER = '// Generated by pano-client from openapi.json. Do not edit; run pano-client again.\n'
+
+/**
+ * @typedef {Object} GenerateResult
+ * @property {Record<string, string>} files   file name -> content: index.js, types.js, operations.js, openapi.json
+ * @property {string[]} warnings
+ * @property {import('./operations.js').Operation[]} operations
+ */
+
+/**
+ * @param {any} input   parsed OpenAPI 3.1 document, or its JSON text
+ * @returns {GenerateResult}
+ */
+export function generateClient(input) {
+  /** @type {any} */
+  let doc = input
+  if (typeof input === 'string') {
+    try {
+      doc = JSON.parse(input)
+    } catch (e) {
+      throw new ClientGenError(`The OpenAPI document is not valid JSON: ${/** @type {Error} */ (e).message}`)
+    }
+  }
+  if (!doc || typeof doc !== 'object' || typeof doc.paths !== 'object') {
+    throw new ClientGenError('The input is not an OpenAPI document (no "paths" object).')
+  }
+  doc = sortKeys(doc)
+
+  /** @type {string[]} */
+  const warnings = []
+  const warn = (/** @type {string} */ m) => warnings.push(m)
+  const operations = collectOperations(doc, warn)
+
+  // type names: components.schemas first, then the per-operation aliases
+  const schemas = doc.components && typeof doc.components.schemas === 'object' && doc.components.schemas ? doc.components.schemas : {}
+  /** @type {Map<string, string>} */
+  const typeNames = new Map()
+  const taken = new Set()
+  for (const raw of Object.keys(schemas)) {
+    let name = isIdent(raw) ? raw : pascal(raw) || 'Schema'
+    if (/^[0-9]/.test(name)) name = '_' + name
+    let unique = name
+    for (let n = 2; taken.has(unique); n++) unique = `${name}${n}`
+    if (unique !== name) warn(`schema "${raw}" maps to a type name that is taken, using "${unique}"`)
+    taken.add(unique)
+    typeNames.set(raw, unique)
+  }
+  const claim = (/** @type {string} */ base) => {
+    let name = base
+    if (taken.has(name)) name = base + 'Operation'
+    for (let n = 2; taken.has(name); n++) name = `${base}Operation${n}`
+    taken.add(name)
+    return name
+  }
+  const refIn = (/** @type {boolean} */ local) => (/** @type {string} */ name) => {
+    const t = typeNames.get(name)
+    if (t === undefined) {
+      warn(`reference to unknown schema "${name}", typed as any`)
+      return 'any'
+    }
+    return local ? t : `import('./types.js').${t}`
+  }
+  const localCtx = { ref: refIn(true) }
+  const importCtx = { ref: refIn(false) }
+
+  // ---- types.js
+  const typeBlocks = []
+  for (const raw of [...typeNames.keys()].sort()) {
+    const name = /** @type {string} */ (typeNames.get(raw))
+    typeBlocks.push(typedef(name, schemas[raw], localCtx))
+  }
+
+  /** @type {Map<import('./operations.js').Operation, { response: string, request: string | null }>} */
+  const opTypes = new Map()
+  for (const op of operations) {
+    const base = pascal(op.name)
+    let response
+    if (op.undocumented) response = 'any'
+    else if (op.response.kind === 'json') response = schemaType(op.response.schema, localCtx)
+    else if (op.response.kind === 'text') response = 'string'
+    else if (op.response.kind === 'blob') response = 'Blob'
+    else response = 'void'
+    const responseName = claim(`${base}Response`)
+    typeBlocks.push(`/** @typedef {${response}} ${responseName} */`)
+
+    let requestName = null
+    if (op.body && !op.undocumented) {
+      if (op.body.kind === 'json') {
+        requestName = claim(`${base}Request`)
+        typeBlocks.push(typedef(requestName, op.body.schema, localCtx))
+      }
+    }
+    opTypes.set(op, { response: responseName, request: requestName })
+  }
+  const typesJs = HEADER + '\n' + typeBlocks.join('\n\n') + (typeBlocks.length ? '\n\n' : '') + 'export {};\n'
+
+  // ---- operations.js
+  const opLines = operations.map(
+    (op) =>
+      `  ${propKey(op.name)}: { method: ${quote(op.method)}, path: ${quote(op.path)}, auth: ${quote(op.auth)}, mutation: ${op.mutation} }`
+  )
+  const operationsJs =
+    HEADER + '\n' + `export const operations = /** @type {const} */ ({\n${opLines.join(',\n')}${opLines.length ? '\n' : ''}});\n`
+
+  // ---- index.js
+  const fnBlocks = operations.map((op) => {
+    const t = /** @type {{ response: string, request: string | null }} */ (opTypes.get(op))
+    const { type: paramsType, required } = paramsOf(op, t.request, importCtx)
+    const lines = ['/**']
+    const doc1 = oneLine(op.summary) || oneLine(op.description) || `${op.method} ${op.path}`
+    lines.push(` * ${doc1}`)
+    if (op.summary && op.description && oneLine(op.description) !== oneLine(op.summary)) lines.push(` * ${oneLine(op.description)}`)
+    if (op.deprecated) lines.push(' * @deprecated')
+    lines.push(` * @param {import('@panomc/client').PanoClient} client`)
+    lines.push(` * @param {${paramsType}} ${required ? 'params' : '[params]'}`)
+    lines.push(
+      ` * @returns {Promise<import('@panomc/client').ApiResult<import('./types.js').${t.response}>>}`
+    )
+    lines.push(' */')
+    lines.push(`export const ${op.name} = (client, params) => client.request(operations.${op.name}, params);`)
+    return lines.join('\n')
+  })
+  const indexJs = HEADER + "import { operations } from './operations.js';\n\n" + fnBlocks.join('\n\n') + (fnBlocks.length ? '\n' : '')
+
+  return {
+    files: { 'index.js': indexJs, 'types.js': typesJs, 'operations.js': operationsJs, 'openapi.json': canonicalJson(doc) },
+    warnings,
+    operations
+  }
+}
+
+/**
+ * @param {import('./operations.js').Operation} op
+ * @param {string | null} requestName
+ * @param {import('./schema.js').TypeContext} ctx
+ */
+function paramsOf(op, requestName, ctx) {
+  const members = []
+  let required = false
+  if (op.undocumented) {
+    if (/\{[^}]+\}/.test(op.path)) {
+      members.push('path: Record<string, string | number | boolean>')
+      required = true
+    }
+    members.push('query?: Record<string, any>')
+    if (op.mutation) members.push('body?: any')
+  } else {
+    const pathParams = op.parameters.filter((p) => p.in === 'path')
+    const queryParams = op.parameters.filter((p) => p.in === 'query')
+    if (pathParams.length) {
+      members.push(`path: { ${pathParams.map((p) => `${propKey(p.name)}: ${schemaType(p.schema, ctx)}`).join(', ')} }`)
+      required = true
+    }
+    if (queryParams.length) {
+      const anyRequired = queryParams.some((p) => p.required)
+      members.push(
+        `query${anyRequired ? '' : '?'}: { ${queryParams.map((p) => `${propKey(p.name)}${p.required ? '' : '?'}: ${schemaType(p.schema, ctx)}`).join(', ')} }`
+      )
+      if (anyRequired) required = true
+    }
+    if (op.body) {
+      const type =
+        op.body.kind === 'form' ? 'FormData' : op.body.kind === 'json' && requestName ? `import('./types.js').${requestName}` : 'any'
+      members.push(`body${op.body.required ? '' : '?'}: ${type}`)
+      if (op.body.required) required = true
+    }
+  }
+  members.push('signal?: AbortSignal')
+  return { type: `{ ${members.join(', ')} }`, required }
+}
+
+/**
+ * @param {string} name
+ * @param {any} schema
+ * @param {import('./schema.js').TypeContext} ctx
+ */
+function typedef(name, schema, ctx) {
+  const props = objectProperties(schema, ctx)
+  const description = schema && typeof schema === 'object' ? oneLine(schema.description) : ''
+  const deprecated = schema && typeof schema === 'object' && schema.deprecated === true
+  if (props) {
+    const lines = ['/**']
+    if (description) lines.push(` * ${description}`)
+    if (deprecated) lines.push(' * @deprecated')
+    lines.push(` * @typedef {Object} ${name}`)
+    for (const p of props) {
+      lines.push(` * @property {${p.type}} ${p.optional ? `[${p.name}]` : p.name}${p.description ? ` ${p.description}` : ''}`)
+    }
+    lines.push(' */')
+    return lines.join('\n')
+  }
+  const type = schemaType(schema, ctx)
+  if (!description && !deprecated) return `/** @typedef {${type}} ${name} */`
+  return ['/**', ...(description ? [` * ${description}`] : []), ...(deprecated ? [' * @deprecated'] : []), ` * @typedef {${type}} ${name}`, ' */'].join('\n')
+}