@dokebi/cli 0.4.1 → 0.4.26

package/dist/openapi.js

@@ -0,0 +1,649 @@
+// `dokebi describe --openapi` (D-0077 C): one OpenAPI 3.1 document per app, built from the
+// description `dokebi describe` makes (the routes dokebi-web recorded, with their JSON Schemas,
+// the login rule of dokebi-auth, the csrf settings and the app's error codes). No external
+// OpenAPI library: OpenAPI 3.1 Schema Objects are JSON Schema 2020-12, so a route schema is
+// copied with the few draft-07 keywords Fastify's Ajv accepts rewritten to their 2020-12 form.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { debug, describeError } from './diagnostics.js';
+import { CliError } from './errors.js';
+export const OPENAPI_VERSION = '3.1.0';
+/** The HTTP methods an OpenAPI Path Item has. */
+const METHODS = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+/** Methods @dokebi/csrf checks (D-0076 §4). */
+const UNSAFE = new Set(['post', 'put', 'patch', 'delete']);
+/** Headers OpenAPI describes elsewhere (a header parameter with these names is ignored, §4.8.12). */
+const RESERVED_HEADERS = new Set(['accept', 'content-type', 'authorization', 'cookie']);
+/** Vite dev routes (template-inertia in development); describe mode registers none. */
+const VITE_ROUTE = /\/(?:@vite|@id|@fs|__vite|node_modules\/\.vite)(?:\/|$)/;
+/** Host names that resolve to this machine (D-0030 local domains). */
+const LOOPBACK = /^(?:localhost|[^.]+(?:\.[^.]+)*\.localhost|127(?:\.\d{1,3}){3}|\[::1\])$/i;
+const ERROR_SCHEMA = '#/components/schemas/DokebiError';
+/** The D-0074 error body. */
+export const ERROR_BODY_SCHEMA = Object.freeze({
+    type: 'object',
+    description: 'A Dokebi error answer (D-0074). `fix` and `details` are sent outside production only; a 5xx answer in production carries only `error`.',
+    required: ['error'],
+    properties: {
+        error: { type: 'string', description: 'The error code, for example VALIDATION_FAILED' },
+        message: { type: 'string' },
+        hint: { type: 'string', description: 'What the user can do' },
+        data: { type: 'object', description: 'Data the client may use' },
+        fields: {
+            type: 'array',
+            description: '422 VALIDATION_FAILED: every refused field, in order',
+            items: {
+                type: 'object',
+                required: ['field', 'message'],
+                properties: { field: { type: 'string' }, message: { type: 'string' } },
+            },
+        },
+        errors: {
+            type: 'object',
+            description: '422 VALIDATION_FAILED: the first message per field (Inertia useForm().errors)',
+            additionalProperties: { type: 'string' },
+        },
+        fix: { type: 'string', description: 'For developers; outside production only' },
+        details: { description: 'For developers; outside production only' },
+    },
+});
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const strings = (value) => Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+/** A components key: `^[a-zA-Z0-9.\-_]+$`. */
+function componentName(text) {
+    const name = text.replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^_+|_+$/g, '');
+    return name || 'schema';
+}
+// ── JSON Schema (as Fastify takes it) → OpenAPI 3.1 Schema Object ─────────────────────────────
+/**
+ * Converts one route schema. Local `$ref`s (`#/definitions/x`, `#/$defs/x`) move to
+ * `components.schemas` under `<prefix>.<name>` (a ref is resolved against the document there);
+ * other local pointers are inlined; a ref to a schema added with Fastify's `addSchema` is not in
+ * the description and becomes an open schema with `x-dokebi-ref`.
+ */
+class SchemaConverter {
+    #root;
+    #prefix;
+    #components;
+    #inlining = new Set();
+    constructor(root, prefix, components) {
+        this.#root = root;
+        this.#prefix = prefix;
+        this.#components = components;
+    }
+    convert(schema = this.#root, depth = 0) {
+        if (typeof schema === 'boolean')
+            return schema;
+        if (schema === null || typeof schema !== 'object' || Array.isArray(schema))
+            return {};
+        if (depth > 64)
+            return { description: 'Nested too deep to describe' };
+        const input = schema;
+        const output = {};
+        for (const [key, value] of Object.entries(input)) {
+            switch (key) {
+                // The OpenAPI document is the base: no own dialect or base URI inside it.
+                case '$schema':
+                case '$id':
+                case 'definitions':
+                case '$defs':
+                    break;
+                case '$ref':
+                    Object.assign(output, this.#ref(String(value), depth));
+                    break;
+                case 'nullable':
+                    break;
+                case 'items':
+                    if (Array.isArray(value)) {
+                        // draft-07 tuple: prefixItems, and additionalItems becomes items.
+                        output.prefixItems = value.map((item) => this.convert(item, depth + 1));
+                        if (input.additionalItems !== undefined)
+                            output.items = this.convert(input.additionalItems, depth + 1);
+                    }
+                    else
+                        output.items = this.convert(value, depth + 1);
+                    break;
+                case 'additionalItems':
+                    if (!Array.isArray(input.items))
+                        output.items ??= this.convert(value, depth + 1);
+                    break;
+                case 'dependencies': {
+                    const required = {};
+                    const schemas = {};
+                    for (const [name, item] of Object.entries(record(value)))
+                        if (Array.isArray(item))
+                            required[name] = item;
+                        else
+                            schemas[name] = this.convert(item, depth + 1);
+                    if (Object.keys(required).length)
+                        output.dependentRequired = required;
+                    if (Object.keys(schemas).length)
+                        output.dependentSchemas = schemas;
+                    break;
+                }
+                case 'properties':
+                case 'patternProperties':
+                case 'dependentSchemas':
+                    output[key] = Object.fromEntries(Object.entries(record(value)).map(([name, item]) => [
+                        name,
+                        this.convert(item, depth + 1),
+                    ]));
+                    break;
+                case 'additionalProperties':
+                case 'unevaluatedProperties':
+                case 'unevaluatedItems':
+                case 'propertyNames':
+                case 'contains':
+                case 'not':
+                case 'if':
+                case 'then':
+                case 'else':
+                    output[key] = this.convert(value, depth + 1);
+                    break;
+                case 'allOf':
+                case 'anyOf':
+                case 'oneOf':
+                case 'prefixItems':
+                    output[key] = Array.isArray(value)
+                        ? value.map((item) => this.convert(item, depth + 1))
+                        : value;
+                    break;
+                default:
+                    output[key] = value;
+            }
+        }
+        // Ajv's (and OpenAPI 3.0's) nullable: a type list with null in 3.1.
+        if (input.nullable === true) {
+            if (typeof output.type === 'string')
+                output.type = [output.type, 'null'];
+            else if (Array.isArray(output.type) && !output.type.includes('null'))
+                output.type = [...output.type, 'null'];
+            else if (output.type === undefined &&
+                Array.isArray(output.enum) &&
+                !output.enum.includes(null))
+                output.enum = [...output.enum, null];
+        }
+        return output;
+    }
+    #ref(ref, depth) {
+        const definition = /^#\/(definitions|\$defs)\/([^/]+)$/.exec(ref);
+        if (definition) {
+            const [, group, raw] = definition;
+            const name = decodePointer(raw);
+            const target = record(record(this.#root)[group])[name];
+            if (target === undefined)
+                return unresolved(ref);
+            const key = componentName(`${this.#prefix}.${name}`);
+            if (!Object.hasOwn(this.#components, key)) {
+                // Reserved first: a definition that refers to itself finds its own name.
+                this.#components[key] = {};
+                this.#components[key] = this.convert(target, depth + 1);
+            }
+            return { $ref: `#/components/schemas/${key}` };
+        }
+        if (ref === '#' || ref.startsWith('#/')) {
+            if (this.#inlining.has(ref))
+                return unresolved(ref);
+            const target = ref === '#' ? this.#root : pointer(this.#root, ref.slice(2));
+            if (target === undefined)
+                return unresolved(ref);
+            this.#inlining.add(ref);
+            try {
+                return record(this.convert(target, depth + 1));
+            }
+            finally {
+                this.#inlining.delete(ref);
+            }
+        }
+        return unresolved(ref);
+    }
+}
+function decodePointer(token) {
+    return decodeURIComponent(token).replace(/~1/g, '/').replace(/~0/g, '~');
+}
+function pointer(root, path) {
+    let current = root;
+    for (const token of path.split('/')) {
+        if (current === null || typeof current !== 'object')
+            return undefined;
+        current = current[decodePointer(token)];
+    }
+    return current;
+}
+function unresolved(ref) {
+    return {
+        description: `A schema this description cannot resolve (${ref}); see the route's code`,
+        'x-dokebi-ref': ref,
+    };
+}
+// ── paths ─────────────────────────────────────────────────────────────────────────────────────
+/** `/posts/:id(^\\d+)/*` → `/posts/{id}/{wildcard}` and the path parameter names. */
+export function openApiPath(url) {
+    const names = [];
+    let path = '';
+    for (let index = 0; index < url.length; index++) {
+        const char = url[index];
+        if (char === ':' && url[index + 1] === ':') {
+            // `::` is a literal colon in Fastify.
+            path += ':';
+            index++;
+            continue;
+        }
+        if (char === ':') {
+            const match = /^[A-Za-z0-9_]+/.exec(url.slice(index + 1));
+            if (!match) {
+                path += char;
+                continue;
+            }
+            names.push(match[0]);
+            path += `{${match[0]}}`;
+            index += match[0].length;
+            // A regular expression after the name: `(…)` with nested parentheses.
+            if (url[index + 1] === '(') {
+                let level = 0;
+                for (index++; index < url.length; index++) {
+                    if (url[index] === '\\')
+                        index++;
+                    else if (url[index] === '(')
+                        level++;
+                    else if (url[index] === ')' && --level === 0)
+                        break;
+                }
+            }
+            continue;
+        }
+        if (char === '*' && index === url.length - 1) {
+            names.push('*');
+            path += '{wildcard}';
+            continue;
+        }
+        path += char;
+    }
+    return { path, names };
+}
+/** `get_posts_id`: the deterministic name of a route without `config.id`. */
+export function operationName(method, url) {
+    const words = openApiPath(url)
+        .path.replace(/[{}]/g, '')
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map((word) => word.toLowerCase());
+    return `${method.toLowerCase()}_${words.join('_') || 'root'}`;
+}
+/** The app names of the project (dokebi-app), or one name for a project without apps. */
+function appNames(result) {
+    const apps = Array.isArray(result.app.apps) ? result.app.apps : [];
+    const names = apps
+        .map((app) => app.name)
+        .filter((name) => typeof name === 'string');
+    return names;
+}
+/** OpenAPI documents of the described project (one per app). */
+export function openApi(result, options = {}) {
+    const names = appNames(result);
+    const single = names.length === 0;
+    const projectName = typeof result.app.name === 'string' ? result.app.name : 'app';
+    if (options.app !== undefined &&
+        (single ? options.app !== projectName : !names.includes(options.app)))
+        throw new CliError('UNKNOWN_APP', `The project has no app ${options.app}`, {
+            details: {
+                app: options.app,
+                apps: single ? [projectName] : names,
+                fix: `Pass one of: ${(single ? [projectName] : names).join(', ')} (npx dokebi describe --json lists the apps)`,
+            },
+        });
+    if (single)
+        return document(result, undefined, projectName, options);
+    if (options.app !== undefined)
+        return document(result, options.app, options.app, options);
+    if (names.length === 1)
+        return document(result, names[0], names[0], options);
+    return {
+        apps: Object.fromEntries(names.map((name) => [name, document(result, name, name, options)])),
+    };
+}
+function servers(result, app) {
+    const web = record(result.app.web);
+    const port = typeof web.port === 'number' ? web.port : undefined;
+    const domains = (Array.isArray(result.app.domains) ? result.app.domains : []).filter((domain) => app === undefined || domain.app === app);
+    const hosts = domains.map((domain) => ({
+        host: String(domain.host),
+        seal: domain.seal === true,
+    }));
+    if (hosts.length === 0) {
+        const configured = typeof web.host === 'string' ? web.host : 'localhost';
+        hosts.push({
+            host: configured === '0.0.0.0' || configured === '::' ? 'localhost' : configured,
+            seal: false,
+        });
+    }
+    return hosts.map(({ host, seal }) => {
+        const local = LOOPBACK.test(host);
+        return {
+            url: local ? `http://${host}${port === undefined ? '' : `:${port}`}` : `https://${host}`,
+            description: local ? `${host} (this machine)` : host,
+            ...(seal ? { 'x-dokebi-seal': true } : {}),
+        };
+    });
+}
+/** The parameters of one schema part (`querystring`, `params`, `headers`). */
+function parameters(part, where, convert) {
+    const schema = record(part);
+    const properties = record(schema.properties);
+    const required = new Set(strings(schema.required));
+    if (Object.keys(properties).length === 0) {
+        if (where !== 'query' || Object.keys(schema).length === 0)
+            return [];
+        // An object query without properties (anyOf, a $ref): one form-style parameter.
+        return [{ name: 'query', in: 'query', style: 'form', explode: true, schema: convert(schema) }];
+    }
+    const list = [];
+    for (const [name, item] of Object.entries(properties)) {
+        if (where === 'header' && RESERVED_HEADERS.has(name.toLowerCase()))
+            continue;
+        const converted = record(convert(item));
+        list.push({
+            name,
+            in: where,
+            ...(where === 'path' || required.has(name) ? { required: true } : {}),
+            ...(typeof converted.description === 'string' ? { description: converted.description } : {}),
+            schema: converted,
+        });
+    }
+    return list;
+}
+/** A Fastify response map → OpenAPI responses (`2xx` → `2XX`); each code is its own schema root. */
+function responses(part, converterFor, prefix) {
+    const out = {};
+    for (const [code, value] of Object.entries(record(part))) {
+        const key = /^[1-5]xx$/i.test(code) ? code.toUpperCase() : code;
+        if (!/^(?:[1-5](?:\d\d|XX)|default)$/.test(key))
+            continue;
+        const given = record(value);
+        const description = typeof given.description === 'string' ? given.description : 'Response';
+        if (given.content !== undefined && given.type === undefined) {
+            const content = {};
+            for (const [media, entry] of Object.entries(record(given.content))) {
+                const schema = record(entry).schema;
+                content[media] = { schema: converterFor(schema, `${prefix}.${key}.${media}`)(schema) };
+            }
+            out[key] = { description, content };
+        }
+        else if (typeof value === 'boolean' || Object.keys(given).length > 0)
+            out[key] = {
+                description,
+                content: {
+                    'application/json': { schema: converterFor(value, `${prefix}.${key}`)(value) },
+                },
+            };
+        else
+            out[key] = { description };
+    }
+    return out;
+}
+function errorResponse(components, use) {
+    const responsesStore = components.responses;
+    const key = use.codes.join('_OR_');
+    if (!Object.hasOwn(responsesStore, key))
+        responsesStore[key] = {
+            description: use.description,
+            content: {
+                'application/json': {
+                    schema: {
+                        allOf: [
+                            { $ref: ERROR_SCHEMA },
+                            {
+                                properties: {
+                                    error: use.codes.length === 1 ? { const: use.codes[0] } : { enum: [...use.codes] },
+                                },
+                            },
+                        ],
+                    },
+                },
+            },
+        };
+    return { $ref: `#/components/responses/${key}` };
+}
+/** One app's document (`app` undefined: a project without dokebi-app, every route). */
+function document(result, app, title, options) {
+    const components = {
+        schemas: { DokebiError: ERROR_BODY_SCHEMA },
+        responses: {},
+        securitySchemes: {},
+    };
+    const schemas = components.schemas;
+    const schemes = components.securitySchemes;
+    const web = record(result.app.web);
+    const session = record(result.app.session);
+    const csrf = result.app.csrf === undefined ? undefined : record(result.app.csrf);
+    const authSection = record(result.app.auth);
+    const loginPath = typeof authSection.loginPath === 'string' ? authSection.loginPath : '/login';
+    const forms = web.formBody === true;
+    // Routes of this app and routes outside apps (Fastify serves those on every host).
+    const routes = result.routes.filter((route) => route.health !== true &&
+        !VITE_ROUTE.test(route.url) &&
+        (app === undefined || route.app === undefined || route.app === app));
+    const seen = new Set(routes.map((route) => `${route.method} ${route.url} ${route.id ?? ''}`));
+    const paths = {};
+    const taken = new Set();
+    const operations = [];
+    const skipped = [];
+    // Ids first (they are the names asked for), then the generated names, in route order. One rule
+    // for an id: it names one operation as it is; an id on several operations (a route of several
+    // methods, or several routes of one plugin route key, D-0142) gives each `<id>_<method>`; a
+    // name still taken gets `_2`, `_3`, … (two GET routes under one id).
+    const candidates = [];
+    for (const route of routes) {
+        // dokebi-app registers a module's root as /board and /board/: one operation.
+        if (route.url.length > 1 &&
+            route.url.endsWith('/') &&
+            seen.has(`${route.method} ${route.url.slice(0, -1)} ${route.id ?? ''}`))
+            continue;
+        const methods = route.method.split(',').map((method) => method.trim().toLowerCase());
+        for (const method of methods) {
+            if (!METHODS.has(method)) {
+                skipped.push(`${method.toUpperCase()} ${route.url}`);
+                continue;
+            }
+            candidates.push({ route, method });
+        }
+    }
+    const perId = new Map();
+    for (const { route } of candidates)
+        if (route.id !== undefined)
+            perId.set(route.id, (perId.get(route.id) ?? 0) + 1);
+    const planned = candidates.map(({ route, method }) => ({
+        route,
+        method,
+        wanted: route.id === undefined
+            ? operationName(method, route.url)
+            : (perId.get(route.id) ?? 0) > 1
+                ? `${route.id}_${method}`
+                : route.id,
+    }));
+    const unique = (wanted) => {
+        let name = wanted;
+        for (let index = 2; taken.has(name); index++)
+            name = `${wanted}_${index}`;
+        taken.add(name);
+        return name;
+    };
+    const names = new Map();
+    for (const item of planned)
+        if (item.route.id !== undefined)
+            names.set(item, unique(item.wanted));
+    for (const item of planned)
+        if (item.route.id === undefined)
+            names.set(item, unique(item.wanted));
+    for (const item of planned)
+        operations.push({ route: item.route, method: item.method, name: names.get(item) });
+    for (const { route, method, name } of operations) {
+        const { path, names: pathNames } = openApiPath(route.url);
+        const given = record(route.schema);
+        const converterFor = (root, prefix) => (schema) => new SchemaConverter(root, prefix, schemas).convert(schema);
+        const convert = (part) => converterFor(given[part], `${name}.${part}`);
+        const operation = { operationId: name };
+        const params = [];
+        const pathParams = parameters(given.params, 'path', convert('params'));
+        for (const param of pathNames) {
+            const declared = pathParams.find((item) => item.name === param);
+            params.push(declared
+                ? { ...declared, name: param === '*' ? 'wildcard' : param }
+                : {
+                    name: param === '*' ? 'wildcard' : param,
+                    in: 'path',
+                    required: true,
+                    ...(param === '*'
+                        ? { description: "The rest of the path (Fastify params['*'])" }
+                        : {}),
+                    schema: { type: 'string' },
+                });
+        }
+        params.push(...parameters(given.querystring, 'query', convert('querystring')));
+        params.push(...parameters(given.headers, 'header', convert('headers')));
+        const config = record(route.config);
+        const csrfChecked = csrf !== undefined &&
+            UNSAFE.has(method) &&
+            config.csrf !== false &&
+            !strings(csrf.exclude).some((prefix) => route.url.startsWith(prefix));
+        if (csrfChecked && typeof csrf.header === 'string')
+            params.push({
+                name: csrf.header,
+                in: 'header',
+                description: `The CSRF token (or the ${String(csrf.field)} form field); not needed with Authorization: Bearer and no session cookie`,
+                schema: { type: 'string' },
+            });
+        if (params.length)
+            operation.parameters = params;
+        if (given.body !== undefined) {
+            const body = record(given.body);
+            const content = {};
+            if (body.content !== undefined && body.type === undefined) {
+                for (const [media, entry] of Object.entries(record(body.content))) {
+                    const schema = record(entry).schema;
+                    content[media] = { schema: converterFor(schema, `${name}.body.${media}`)(schema) };
+                }
+            }
+            else {
+                const schema = convert('body')(given.body);
+                content['application/json'] = { schema };
+                if (forms)
+                    content['application/x-www-form-urlencoded'] = { schema };
+            }
+            operation.requestBody = { required: true, content };
+        }
+        const answers = { ...responses(given.response, converterFor, `${name}.response`) };
+        if (!Object.keys(answers).some((code) => /^2/.test(code)))
+            answers['200'] = { description: 'Success' };
+        if (given.body !== undefined || given.querystring !== undefined)
+            answers['422'] ??= errorResponse(components, {
+                codes: ['VALIDATION_FAILED'],
+                description: 'VALIDATION_FAILED: the route schema refused the body or the query (fields, errors)',
+            });
+        if (given.params !== undefined || given.headers !== undefined)
+            answers['400'] ??= errorResponse(components, {
+                codes: ['INVALID_REQUEST'],
+                description: 'INVALID_REQUEST: the route schema refused the path parameters or headers',
+            });
+        const auth = route.auth === undefined ? undefined : record(route.auth);
+        const mode = auth?.mode;
+        const via = typeof auth?.via === 'string' ? auth.via : 'session';
+        const roles = strings(auth?.roles ?? config.roles);
+        const can = typeof auth?.can === 'string' ? auth.can : undefined;
+        if (auth !== undefined) {
+            operation['x-dokebi-auth'] = {
+                mode,
+                realm: auth.realm,
+                via,
+                ...(roles.length ? { roles } : {}),
+                ...(can === undefined ? {} : { can }),
+            };
+            if (mode === 'required' || mode === 'optional') {
+                const choices = [];
+                if (via === 'token' || via === 'any') {
+                    schemes.bearerAuth = {
+                        type: 'http',
+                        scheme: 'bearer',
+                        description: 'An API token of @dokebi/auth (opaque, not a JWT)',
+                    };
+                    choices.push({ bearerAuth: [] });
+                }
+                if (via === 'session' || via === 'any') {
+                    schemes.cookieAuth = {
+                        type: 'apiKey',
+                        in: 'cookie',
+                        name: typeof record(session.cookie).name === 'string'
+                            ? record(session.cookie).name
+                            : 'dokebi.sid',
+                        description: 'The session cookie of @dokebi/session after a login',
+                    };
+                    choices.push({ cookieAuth: [] });
+                }
+                if (mode === 'optional')
+                    choices.push({});
+                operation.security = choices;
+            }
+            // Required, or a token that was presented and is not valid (optional token routes).
+            if (mode === 'required' || (mode === 'optional' && via !== 'session'))
+                answers['401'] ??= errorResponse(components, {
+                    codes: ['UNAUTHENTICATED'],
+                    description: `UNAUTHENTICATED: sign in first (JSON clients; a browser page or form gets 303 to ${loginPath})`,
+                });
+        }
+        const forbidden = [];
+        if (mode === 'required' && (roles.length > 0 || can !== undefined))
+            forbidden.push('FORBIDDEN');
+        if (csrfChecked)
+            forbidden.push('CSRF_FAILED');
+        if (forbidden.length)
+            answers['403'] ??= errorResponse(components, {
+                codes: forbidden,
+                description: forbidden
+                    .map((code) => code === 'FORBIDDEN'
+                    ? `FORBIDDEN: the user lacks ${roles.length ? `one of the roles ${roles.join(', ')}` : ''}${roles.length && can ? ' or ' : ''}${can ? `the ability ${can}` : ''}`
+                    : 'CSRF_FAILED: the CSRF token is missing or wrong')
+                    .join('; '),
+            });
+        operation.responses = answers;
+        if (paths[path] === undefined)
+            paths[path] = {};
+        const item = paths[path];
+        if (item[method] !== undefined) {
+            // Two routes on one path and method (other hosts): the first one is described.
+            skipped.push(`${method.toUpperCase()} ${route.url} (${name})`);
+            continue;
+        }
+        item[method] = operation;
+    }
+    for (const key of ['responses', 'securitySchemes'])
+        if (Object.keys(components[key]).length === 0)
+            delete components[key];
+    if (skipped.length)
+        debug('OpenAPI routes left out', { app: title, skipped });
+    return {
+        openapi: OPENAPI_VERSION,
+        info: {
+            title,
+            version: options.version ?? '0.0.0',
+            description: `Routes of ${app === undefined ? 'the project' : `the app ${app}`}${typeof result.app.name === 'string' && result.app.name !== title
+                ? ` of ${result.app.name}`
+                : ''}, generated by dokebi describe --openapi`,
+        },
+        servers: servers(result, app),
+        paths,
+        components,
+        'x-dokebi-errors': result.errors.map((item) => ({ ...item })),
+        ...(skipped.length ? { 'x-dokebi-skipped': skipped } : {}),
+    };
+}
+/** The project's package.json version, for `info.version`. */
+export function projectVersion(root) {
+    try {
+        const version = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version;
+        return typeof version === 'string' ? version : undefined;
+    }
+    catch (error) {
+        debug('Unable to read the project version for OpenAPI', { error: describeError(error) });
+        return undefined;
+    }
+}

package/dist/option-fixes.d.ts

@@ -0,0 +1,39 @@
+/** Issue shape of the options validator (@dokebi/config `ConfigIssue`). */
+export interface OptionIssueLike {
+    readonly instancePath: string;
+    readonly keyword: string;
+    /** For `additionalProperties`: the unknown key (a name from the configuration, not a value). */
+    readonly additionalProperty?: string;
+    /** For `required`: the missing key (config init, D-0163, generates it when it is a secret). */
+    readonly missingProperty?: string;
+}
+export interface MovedOption {
+    /** Plugin id and option path that no longer exist there. */
+    readonly plugin: string;
+    readonly path: readonly string[];
+    /** Where the settings live now (`<plugin>.<path>`), the package and the decision. */
+    readonly to: string;
+    readonly package: string;
+    readonly decision: string;
+    /** The commands that write the new settings, with placeholders for what the user decides. */
+    readonly set: string;
+}
+/** Options that moved to another plugin, newest last. */
+export declare const MOVED_OPTIONS: readonly MovedOption[];
+/** `<id>.<path>` of every key the plugin does not know, when the path can be unset. */
+export declare function unknownOptionPaths(id: string, issues: readonly OptionIssueLike[]): {
+    readonly paths: string[];
+    readonly unnamed: boolean;
+};
+/** The moved option a path is, or is inside of. */
+export declare function movedOption(id: string, path: readonly string[]): MovedOption | undefined;
+/**
+ * The fix of INVALID_PLUGIN_OPTIONS for plugin `id`: the moved keys first (where they went, then
+ * show, unset, add, set), then `npx dokebi config unset` for the other unknown keys, then
+ * `fallback` (how to correct the remaining issues), which is the whole fix when no key is unknown.
+ */
+export declare function optionsFix(id: string, issues: readonly OptionIssueLike[], fallback: string, 
+/** The section of dokebi.yaml the commands name (options.logging for the logger host). */
+section?: string, 
+/** The plugin's options schema: the fix then says what the refused field expects. */
+schema?: unknown): string;