@wirecat/cli-base 0.48.0 → 0.50.0

package/CHANGELOG.md

@@ -8,6 +8,48 @@ Versions before 0.8.0 are in the [git tags](https://github.com/WireCatLabs/cli-b
 Every entry says what changed as a caller sees it, why, and what to watch for — the rules are
 [`docs/dev/CONVENTIONS.md`](docs/dev/CONVENTIONS.md#the-changelog).
 
+## 0.50.0 — 22.10.2026
+
+### Changed — may break callers
+
+- **The shared scripts TypeScript configuration checks `vitest.config.ts`.** Consumers extending it now
+  catch type errors in their test-runner configuration alongside scripts; fix newly reported errors before upgrading.
+
+- **The handbook clarifies JSON previews and local release validation.** A dry-run preview uses the item
+  envelope; local releases must run coverage, engine, contract and security checks, with the npm token
+  available only to publishing. Command discovery remains a bare document.
+
+### Added
+
+- **`adaptOpenApi` reads an OpenAPI 3.0 or 3.1 document into the codegen model.** It moved here from max-cli because
+  whatsapp-cli needs it too for Meta's Cloud API file. Beyond what max-cli's copy did, it resolves `$ref` parameters,
+  drops the `Authorization`, `User-Agent`, `Content-Type` and `Accept` header parameters (the
+  HTTP client sets them), reads `oneOf` as a union, `const` and a typeless `enum` as their type, `type: [T, "null"]`
+  as nullable, and an array with no `items` as any item. A body that is multipart or a form keeps that in the new
+  `ApiBody.contentType` and manifest `request.contentType`; a multipart body with a file wins over a JSON one. A body
+  typed only from sample values gets `confidence: "example"`. A path with no `operationId` is skipped instead of
+  refused, since Meta uses one to describe its webhook payload. It still stops on anything else it does not
+  understand, now under the name `OpenApiError`. Parse YAML yourself and hand it the plain object.
+- **One subtype may belong to two discriminated schemas, or to one schema under two values.** The generated type and
+  schema accept each value that selects it (`"unsupported" | "unknown"`); before, generation stopped. Meta's sent and
+  received message unions share `TextMessage` this way.
+
+- **Release checks can audit Go dependencies for reachable vulnerabilities.** Set `govulncheck: true` and
+  `go-version-file` to the module's `go.mod` path. The audit uses that module's Go version and runs in its
+  directory; it stays off for existing callers.
+- **The weekly cross-CLI audit includes WhatsApp.** Its latest published command tree joins the checks for
+  required commands, shared option meanings, answer shapes and error reasons.
+
+## 0.49.0 — 21.10.2026
+
+### Added
+
+- **`parseLucene` can read a phrase's distance.** With `{ proximity: true }`, `"a b"~3` parses as a phrase predicate
+  with `slop: 3`, and `queryNodeSchema` accepts `slop`. Meeting search needs it for words spread over neighbouring
+  transcript lines, and a caller that turns it on says what the number counts. Without the option `~` is still
+  `query.unsupported-operator`, so messages and lists see no change. A distance that is not a whole number is
+  `query.invalid-syntax`; `word~2` (fuzzy) stays unsupported either way.
+
 ## 0.48.0 — 21.10.2026
 
 ### Changed — may break callers

package/README.md

@@ -171,6 +171,7 @@ unless you pass `isolated: true`; and a locked Linux keyring can block on a prom
 ### Generated API clients that never guess
 
 `/codegen` turns an API description into TypeScript types, Valibot schemas, an operation manifest and a coverage page.
+`adaptOpenApi` reads an OpenAPI 3.0 or 3.1 document; another format needs an adapter in the caller.
 Every operation is classified as a read, a write or destructive, with how far the source can be trusted. Generation
 stops, naming the problem, on a collision, an unclassified operation or a dangling reference — it never drops an
 operation and never falls back to `any`. 64-bit integers stay exact.

package/config/tsconfig.scripts.json

@@ -8,6 +8,6 @@
     "rootDir": "${configDir}",
     "allowImportingTsExtensions": true
   },
-  "include": ["${configDir}/scripts/**/*.ts"],
+  "include": ["${configDir}/scripts/**/*.ts", "${configDir}/vitest.config.ts"],
   "exclude": []
 }

package/dist/codegen/index.d.ts

@@ -1,11 +1,13 @@
 /**
  * Turns an official API description into committed code: types, Valibot schemas, an operation
  * manifest and a coverage page. Build-time only, and format-neutral: it parses no file format and
- * adds no dependency. The adapter from OpenAPI, Postman or anything else lives in the consumer.
+ * adds no dependency. `adaptOpenApi` reads an OpenAPI document the consumer has parsed; an adapter from
+ * Postman or anything else lives in the consumer.
  */
 export { type CoverageOptions, coverageGenerator, definitionsGenerator, type ManifestOperation, manifestGenerator, } from "./manifest.js";
 export type { ApiBody, ApiModel, ApiOperation, ApiParameter, ApiSchema, Binding, CodeGenerator, Confidence, Discriminator, Effect, GeneratedArtifact, HttpBinding, HttpMethod, Override, RpcBinding, SchemaNode, SourceInfo, SourceReference, } from "./model.js";
 export { identifier, kebab } from "./names.js";
+export { adaptOpenApi, OpenApiError } from "./openapi.js";
 export { applyOverrides, CodegenError, type GenerateOptions, generate, validateModel, type WriteOptions, writeArtifacts, } from "./pipeline.js";
 export { typesGenerator } from "./typescript.js";
 export { type ValibotOptions, valibotGenerator } from "./valibot.js";

package/dist/codegen/index.js

@@ -1,10 +1,12 @@
 /**
  * Turns an official API description into committed code: types, Valibot schemas, an operation
  * manifest and a coverage page. Build-time only, and format-neutral: it parses no file format and
- * adds no dependency. The adapter from OpenAPI, Postman or anything else lives in the consumer.
+ * adds no dependency. `adaptOpenApi` reads an OpenAPI document the consumer has parsed; an adapter from
+ * Postman or anything else lives in the consumer.
  */
 export { coverageGenerator, definitionsGenerator, manifestGenerator, } from "./manifest.js";
 export { identifier, kebab } from "./names.js";
+export { adaptOpenApi, OpenApiError } from "./openapi.js";
 export { applyOverrides, CodegenError, generate, validateModel, writeArtifacts, } from "./pipeline.js";
 export { typesGenerator } from "./typescript.js";
 export { valibotGenerator } from "./valibot.js";

package/dist/codegen/manifest.d.ts

@@ -21,6 +21,7 @@ export interface ManifestOperation {
         required: boolean;
         confidence: Confidence;
         schema?: string;
+        contentType?: string;
     };
     response?: {
         confidence: Confidence;

package/dist/codegen/manifest.js

@@ -16,6 +16,7 @@ const toManifest = (operation, tree) => withoutUndefined({
             required: operation.requestBody.required,
             confidence: operation.requestBody.confidence,
             schema: tree.requestName(operation.id),
+            contentType: operation.requestBody.contentType,
         })
         : undefined,
     response: operation.response

package/dist/codegen/model.d.ts

@@ -1,7 +1,7 @@
 /**
  * The model every generator reads, whatever the source was: an OpenAPI file, a Postman collection,
- * a scraped reference page. A source adapter lives in the consumer and produces this; nothing here
- * parses a file format.
+ * a scraped reference page. An adapter produces this from a document already parsed into plain
+ * values: `adaptOpenApi` for OpenAPI here, the rest in the consumer. Nothing here reads YAML or a file.
  */
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD";
 /** How much the source promises. A Postman example is not a contract and must never become one. */
@@ -100,6 +100,8 @@ export interface ApiParameter {
 export interface ApiBody {
     confidence: Confidence;
     required: boolean;
+    /** How the body travels when it is not JSON: `multipart/form-data` for a file upload, or a form. */
+    contentType?: string;
     schema?: SchemaNode;
     example?: unknown;
 }

package/dist/codegen/model.js

@@ -1,6 +1,6 @@
 /**
  * The model every generator reads, whatever the source was: an OpenAPI file, a Postman collection,
- * a scraped reference page. A source adapter lives in the consumer and produces this; nothing here
- * parses a file format.
+ * a scraped reference page. An adapter produces this from a document already parsed into plain
+ * values: `adaptOpenApi` for OpenAPI here, the rest in the consumer. Nothing here reads YAML or a file.
  */
 export {};

package/dist/codegen/openapi.d.ts

@@ -0,0 +1,16 @@
+/**
+ * An OpenAPI 3.0 or 3.1 document, already parsed from YAML or JSON → the format-neutral `ApiModel`.
+ *
+ * Strict on purpose: a keyword this does not understand stops generation and names the place,
+ * because a constraint dropped here is a request the server refuses at run time.
+ */
+import type { ApiModel } from "./model.js";
+export declare class OpenApiError extends Error {
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+/** Throws `OpenApiError` with every problem at once, so one run shows all a spec update broke. */
+export declare const adaptOpenApi: (document: unknown, source?: {
+    sourceUrl?: string;
+    sourceRevision?: string;
+}) => ApiModel;

package/dist/codegen/openapi.js

@@ -0,0 +1,446 @@
+const METHODS = ["get", "post", "put", "patch", "delete", "head"];
+/**
+ * Carried by the model, or harmless to lose. `not` only narrows what a payload may hold; losing it
+ * accepts more, never refuses a valid request.
+ */
+const IGNORED = new Set(["readOnly", "example", "examples", "externalDocs", "title", "xml", "writeOnly", "not"]);
+const KNOWN = new Set([
+    ...IGNORED,
+    "type",
+    "format",
+    "description",
+    "nullable",
+    "deprecated",
+    "default",
+    "enum",
+    "const",
+    "minLength",
+    "maxLength",
+    "pattern",
+    "minimum",
+    "maximum",
+    "items",
+    "minItems",
+    "maxItems",
+    "uniqueItems",
+    "properties",
+    "required",
+    "additionalProperties",
+    "allOf",
+    "oneOf",
+    "$ref",
+    "discriminator",
+]);
+const PRIMITIVE_CONSTRAINTS = ["pattern", "minLength", "maxLength", "minimum", "maximum", "enum"];
+/** What the HTTP client sets itself; as flags they would only invite a second, wrong value. */
+const TRANSPORT_HEADERS = new Set(["authorization", "user-agent", "content-type", "accept"]);
+/** What a body may be sent as, in the order an operation offering several is read. */
+const JSON_TYPE = "application/json";
+const MULTIPART = "multipart/form-data";
+const FORM = "application/x-www-form-urlencoded";
+/** Any of these anywhere in a body schema means someone wrote a contract, not a sample. */
+const CONTRACT_MARKS = [
+    "$ref",
+    "description",
+    "required",
+    "enum",
+    "const",
+    "pattern",
+    "minLength",
+    "maxLength",
+    "allOf",
+    "oneOf",
+];
+export class OpenApiError extends Error {
+    problems;
+    constructor(problems) {
+        super(`the OpenAPI document cannot be adapted:\n${problems.map((problem) => `  - ${problem}`).join("\n")}`);
+        this.name = "OpenApiError";
+        this.problems = problems;
+    }
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const EFFECT_BY_METHOD = {
+    GET: "read",
+    HEAD: "read",
+    POST: "write",
+    PUT: "write",
+    PATCH: "write",
+    DELETE: "destructive",
+};
+const pick = (source, keys) => Object.fromEntries(keys.map((key) => [key, source[key]]));
+const typeOfConst = (value) => typeof value === "string"
+    ? "string"
+    : typeof value === "boolean"
+        ? "boolean"
+        : Number.isInteger(value)
+            ? "integer"
+            : typeof value === "number"
+                ? "number"
+                : undefined;
+/**
+ * A body typed from a sample request: only `type` and `example` all the way down. Its field types
+ * are what one example happened to hold, so the model must never treat it as a contract.
+ */
+const typedFromExample = (schema) => {
+    const marked = (node) => {
+        if (Array.isArray(node))
+            return node.some(marked);
+        if (!isObject(node))
+            return false;
+        if (CONTRACT_MARKS.some((mark) => node[mark] !== undefined))
+            return true;
+        return Object.entries(node).some(([key, value]) => key !== "example" && marked(value));
+    };
+    return isObject(schema) && !marked(schema);
+};
+class Adapter {
+    problems = [];
+    document;
+    #components;
+    #parameters;
+    constructor(document) {
+        this.document = document;
+        const components = isObject(document.components) ? document.components : {};
+        this.#components = isObject(components.schemas) ? components.schemas : {};
+        this.#parameters = isObject(components.parameters) ? components.parameters : {};
+    }
+    refId(ref, where) {
+        const prefix = "#/components/schemas/";
+        if (typeof ref === "string" && ref.startsWith(prefix))
+            return ref.slice(prefix.length);
+        this.problems.push(`${where}: unsupported reference ${JSON.stringify(ref)}`);
+        return "Unknown";
+    }
+    /** A parameter given as a `$ref` into `components/parameters`, followed once. */
+    #parameterSource(source, where) {
+        if (!isObject(source) || source.$ref === undefined)
+            return source;
+        const prefix = "#/components/parameters/";
+        const ref = source.$ref;
+        if (typeof ref === "string" && ref.startsWith(prefix) && isObject(this.#parameters[ref.slice(prefix.length)]))
+            return this.#parameters[ref.slice(prefix.length)];
+        this.problems.push(`${where}: unsupported reference ${JSON.stringify(ref)}`);
+        return undefined;
+    }
+    #common(source) {
+        const common = {};
+        if (typeof source.description === "string" && source.description.trim())
+            common.description = source.description;
+        if (source.nullable === true)
+            common.nullable = true;
+        if (source.deprecated === true)
+            common.deprecated = true;
+        if (source.default !== undefined)
+            common.default = source.default;
+        return common;
+    }
+    /** OpenAPI 3.1 writes `nullable` as `type: [T, "null"]`. */
+    #type(source, common, where) {
+        if (Array.isArray(source.type)) {
+            const types = source.type.filter((type) => type !== "null");
+            if (types.length !== source.type.length)
+                common.nullable = true;
+            if (types.length === 1)
+                return types[0];
+            this.problems.push(`${where}: a schema of several types ${JSON.stringify(source.type)}`);
+            return null;
+        }
+        if (source.type !== undefined)
+            return source.type;
+        if (source.const !== undefined)
+            return typeOfConst(source.const);
+        if (Array.isArray(source.enum)) {
+            const types = new Set(source.enum.map(typeOfConst));
+            if (types.size === 1)
+                return [...types][0];
+        }
+        if (source.items !== undefined)
+            return "array";
+        if (source.properties !== undefined || source.required !== undefined || source.additionalProperties !== undefined)
+            return "object";
+        return undefined;
+    }
+    schema(source, where) {
+        if (!isObject(source)) {
+            this.problems.push(`${where}: a schema must be an object`);
+            return { type: "unknown" };
+        }
+        for (const keyword of Object.keys(source)) {
+            if (!KNOWN.has(keyword) && !keyword.startsWith("x-")) {
+                this.problems.push(`${where}: unsupported keyword "${keyword}"`);
+            }
+        }
+        const common = this.#common(source);
+        if (source.$ref !== undefined)
+            return { ...common, type: "ref", ref: this.refId(source.$ref, where) };
+        if (Array.isArray(source.allOf))
+            return this.#allOf(source, source.allOf, common, where);
+        if (Array.isArray(source.oneOf)) {
+            const of = source.oneOf.map((member, index) => this.schema(member, `${where}.oneOf[${index}]`));
+            return { ...common, type: "union", of };
+        }
+        const type = this.#type(source, common, where);
+        const values = source.const !== undefined ? [source.const] : Array.isArray(source.enum) ? source.enum : undefined;
+        switch (type) {
+            case "string": {
+                const node = { ...common, type: "string" };
+                if (values)
+                    node.enum = values.map(String);
+                if (source.format === "binary")
+                    node.format = "binary";
+                if (typeof source.minLength === "number")
+                    node.minLength = source.minLength;
+                if (typeof source.maxLength === "number")
+                    node.maxLength = source.maxLength;
+                if (typeof source.pattern === "string")
+                    node.pattern = source.pattern;
+                return node;
+            }
+            case "integer": {
+                const node = { ...common, type: "integer" };
+                if (source.format === "int32" || source.format === "int64")
+                    node.format = source.format;
+                else if (source.format !== undefined)
+                    this.problems.push(`${where}: unsupported integer format "${source.format}"`);
+                if (typeof source.minimum === "number")
+                    node.minimum = source.minimum;
+                if (typeof source.maximum === "number")
+                    node.maximum = source.maximum;
+                if (values)
+                    node.enum = values.map(Number);
+                return node;
+            }
+            case "number": {
+                const node = { ...common, type: "number" };
+                if (typeof source.minimum === "number")
+                    node.minimum = source.minimum;
+                if (typeof source.maximum === "number")
+                    node.maximum = source.maximum;
+                return node;
+            }
+            case "boolean": {
+                const node = { ...common, type: "boolean" };
+                if (values)
+                    node.enum = values.map((value) => value === true);
+                return node;
+            }
+            case "array": {
+                // JSON Schema reads a missing `items` as "any item".
+                const items = source.items === undefined ? { type: "unknown" } : this.schema(source.items, `${where}[]`);
+                const node = { ...common, type: "array", items };
+                if (typeof source.minItems === "number")
+                    node.minItems = source.minItems;
+                if (typeof source.maxItems === "number")
+                    node.maxItems = source.maxItems;
+                if (source.uniqueItems === true)
+                    node.uniqueItems = true;
+                return node;
+            }
+            case "object":
+                return this.#object(source, common, where);
+            case null:
+                return { type: "unknown" };
+            case undefined:
+                if (Object.keys(source).every((keyword) => IGNORED.has(keyword) || keyword === "description")) {
+                    return { ...common, type: "unknown" };
+                }
+                this.problems.push(`${where}: a schema with no type`);
+                return { type: "unknown" };
+            default:
+                this.problems.push(`${where}: unsupported type ${JSON.stringify(type)}`);
+                return { type: "unknown" };
+        }
+    }
+    #object(source, common, where) {
+        const properties = {};
+        for (const [name, property] of Object.entries(isObject(source.properties) ? source.properties : {})) {
+            properties[name] = this.schema(property, `${where}.${name}`);
+        }
+        const node = {
+            ...common,
+            type: "object",
+            properties,
+            required: Array.isArray(source.required) ? source.required.map(String) : [],
+        };
+        // `true` and `{}` say "anything else may appear", which a loose object already allows.
+        if (isObject(source.additionalProperties) && Object.keys(source.additionalProperties).length > 0) {
+            node.additionalProperties = this.schema(source.additionalProperties, `${where}.*`);
+        }
+        return node;
+    }
+    #allOf(source, members, common, where) {
+        const of = members.map((member, index) => this.schema(member, `${where}.allOf[${index}]`));
+        const [only] = of;
+        // `type: object` beside a one-member allOf is inheritance with no fields of its own; without it,
+        // the allOf only attaches a description or `nullable` to a reference.
+        if (of.length !== 1 || !only || source.type === "object")
+            return { ...common, type: "allOf", of };
+        const constraints = PRIMITIVE_CONSTRAINTS.filter((keyword) => source[keyword] !== undefined);
+        if (constraints.length === 0)
+            return { ...only, ...common };
+        if (only.type !== "ref") {
+            this.problems.push(`${where}: constraints beside a non-reference allOf member`);
+            return only;
+        }
+        const target = this.#components[only.ref];
+        const inlined = this.schema({ ...(isObject(target) ? target : {}), ...pick(source, constraints) }, where);
+        if (inlined.type === "object" || inlined.type === "allOf") {
+            this.problems.push(`${where}: constraints ${constraints.join(", ")} beside a reference to an object`);
+        }
+        return { ...inlined, ...common };
+    }
+    components() {
+        return Object.entries(this.#components).map(([id, source]) => {
+            const where = `#/components/schemas/${id}`;
+            const schema = { id, schema: this.schema(source, where) };
+            if (isObject(source) && isObject(source.discriminator)) {
+                const { propertyName, mapping } = source.discriminator;
+                if (typeof propertyName !== "string" || !isObject(mapping)) {
+                    this.problems.push(`${where}: a discriminator needs propertyName and an explicit mapping`);
+                }
+                else {
+                    schema.discriminator = {
+                        property: propertyName,
+                        mapping: Object.fromEntries(Object.entries(mapping).map(([value, ref]) => [value, this.refId(ref, `${where}.discriminator`)])),
+                    };
+                }
+            }
+            return schema;
+        });
+    }
+    #parameter(reference, where) {
+        const source = this.#parameterSource(reference, where);
+        if (source === undefined)
+            return undefined;
+        if (!isObject(source) || typeof source.name !== "string") {
+            this.problems.push(`${where}: a parameter needs a name`);
+            return undefined;
+        }
+        if (source.in === "header" && TRANSPORT_HEADERS.has(source.name.toLowerCase()))
+            return undefined;
+        if (source.in !== "path" && source.in !== "query" && source.in !== "header") {
+            this.problems.push(`${where}: parameter "${source.name}" is in ${JSON.stringify(source.in)}`);
+            return undefined;
+        }
+        const parameter = {
+            name: source.name,
+            in: source.in,
+            required: source.required === true || source.in === "path",
+            schema: this.schema(source.schema, `${where}.${source.name}`),
+        };
+        if (typeof source.description === "string" && source.description.trim())
+            parameter.description = source.description;
+        return parameter;
+    }
+    /**
+     * JSON when offered, unless a multipart body carries a file, which JSON cannot; then multipart,
+     * then a form. A content type outside these three refuses the operation.
+     */
+    #requestBody(source, where) {
+        const content = isObject(source.content) ? source.content : {};
+        const schemaOf = (type) => (isObject(content[type]) ? content[type].schema : undefined);
+        const carriesFile = JSON.stringify(schemaOf(MULTIPART) ?? {}).includes('"format":"binary"');
+        const offered = Object.keys(content);
+        const type = carriesFile ? MULTIPART : [JSON_TYPE, MULTIPART, FORM].find((candidate) => offered.includes(candidate));
+        const body = { confidence: "contract", required: source.required === true };
+        if (offered.length === 0)
+            return body;
+        if (!type) {
+            this.problems.push(`${where}: a body must be JSON, multipart or a form, found ${offered.join(", ")}`);
+            return body;
+        }
+        if (type !== JSON_TYPE)
+            body.contentType = type;
+        const schema = schemaOf(type);
+        if (schema === undefined)
+            return body;
+        if (typedFromExample(schema))
+            body.confidence = "example";
+        body.schema = this.schema(schema, `${where}.requestBody`);
+        return body;
+    }
+    /**
+     * Only an inline JSON answer has a shape to check; a file, plain text or a `$ref` to a shared response
+     * is passed through as it is. Nothing at run time validates an answer yet.
+     */
+    #response(source, where) {
+        const ok = isObject(source.responses) ? source.responses["200"] : undefined;
+        if (!isObject(ok) || !isObject(ok.content))
+            return undefined;
+        const json = ok.content[JSON_TYPE];
+        if (!isObject(json) || json.schema === undefined)
+            return undefined;
+        return this.schema(json.schema, `${where}.responses.200`);
+    }
+    operations() {
+        const operations = [];
+        const paths = isObject(this.document.paths) ? this.document.paths : {};
+        for (const [path, item] of Object.entries(paths)) {
+            if (!isObject(item))
+                continue;
+            const shared = Array.isArray(item.parameters) ? item.parameters : [];
+            for (const method of METHODS) {
+                const source = item[method];
+                if (!isObject(source))
+                    continue;
+                const pointer = `#/paths/${path.replaceAll("~", "~0").replaceAll("/", "~1")}/${method}`;
+                // A path without an id is a description, not a call: Meta models its webhook payload this way.
+                if (typeof source.operationId !== "string")
+                    continue;
+                const verb = method.toUpperCase();
+                const own = (Array.isArray(source.parameters) ? source.parameters : [])
+                    .map((parameter, index) => this.#parameter(parameter, `${pointer}.parameters[${index}]`))
+                    .filter((parameter) => parameter !== undefined);
+                const inherited = shared
+                    .map((parameter, index) => this.#parameter(parameter, `${pointer.replace(/\/[a-z]+$/, "")}.parameters[${index}]`))
+                    .filter((parameter) => parameter !== undefined && !own.some((mine) => mine.name === parameter.name && mine.in === parameter.in));
+                const parameters = [...inherited, ...own];
+                for (const [, name] of path.matchAll(/\{([^}]+)\}/g)) {
+                    if (!parameters.some((parameter) => parameter.in === "path" && parameter.name === name))
+                        this.problems.push(`${pointer}: path parameter "${name}" is not declared`);
+                }
+                const operation = {
+                    id: source.operationId,
+                    binding: { kind: "http", method: verb, path },
+                    tags: Array.isArray(source.tags) ? source.tags.map(String) : [],
+                    parameters,
+                    effect: EFFECT_BY_METHOD[verb],
+                    source: { location: pointer },
+                };
+                if (typeof source.summary === "string")
+                    operation.summary = source.summary;
+                if (typeof source.description === "string")
+                    operation.description = source.description;
+                if (source.deprecated === true)
+                    operation.deprecated = true;
+                if (isObject(source.requestBody))
+                    operation.requestBody = this.#requestBody(source.requestBody, pointer);
+                const response = this.#response(source, pointer);
+                if (response)
+                    operation.response = { confidence: "contract", required: true, schema: response };
+                operations.push(operation);
+            }
+        }
+        return operations;
+    }
+}
+/** Throws `OpenApiError` with every problem at once, so one run shows all a spec update broke. */
+export const adaptOpenApi = (document, source = {}) => {
+    if (!isObject(document) || typeof document.openapi !== "string" || !document.openapi.startsWith("3.")) {
+        throw new OpenApiError(["not an OpenAPI 3.x document"]);
+    }
+    const adapter = new Adapter(document);
+    const schemas = adapter.components();
+    const operations = adapter.operations();
+    if (operations.length === 0)
+        adapter.problems.push("the document has no operations");
+    if (adapter.problems.length > 0)
+        throw new OpenApiError(adapter.problems);
+    const info = isObject(document.info) ? document.info : {};
+    return {
+        source: { kind: "openapi", ...(typeof info.version === "string" ? { version: info.version } : {}), ...source },
+        schemas,
+        operations,
+    };
+};

package/dist/codegen/tree.d.ts

@@ -2,6 +2,11 @@ import type { ApiModel, ApiSchema, SchemaNode } from "./model.js";
 type ObjectNode = Extract<SchemaNode, {
     type: "object";
 }>;
+/** The values a subtype's discriminator property may hold: one per mapping entry that selects it. */
+export interface Literal {
+    property: string;
+    values: readonly string[];
+}
 export interface NamedSchema {
     name: string;
     schema: ApiSchema;
@@ -17,11 +22,8 @@ export declare class SchemaTree {
     schema(id: string): ApiSchema;
     requestName(operationId: string): string | undefined;
     responseName(operationId: string): string | undefined;
-    /** The value a subtype's discriminator property must hold, if the schema is a subtype. */
-    literalFor(id: string): {
-        property: string;
-        value: string;
-    } | undefined;
+    /** The values a subtype's discriminator property may hold, if the schema is a subtype. */
+    literalFor(id: string): Literal | undefined;
     /** Merges inheritance into one object. A member that is not an object stops generation. */
     flatten(node: SchemaNode, where: string): ObjectNode;
 }

package/dist/codegen/tree.js

@@ -36,10 +36,16 @@ export class SchemaTree {
         }
         for (const schema of model.schemas) {
             for (const [value, target] of Object.entries(schema.discriminator?.mapping ?? {})) {
-                if (this.#literals.has(target)) {
-                    throw new CodegenError([`schema "${target}" is a subtype of two discriminated schemas`]);
+                const property = schema.discriminator?.property ?? "";
+                const known = this.#literals.get(target);
+                // Two bases may share a subtype when both choose it by the same property, as Meta's sent and received messages do.
+                if (known && known.property !== property) {
+                    throw new CodegenError([
+                        `schema "${target}" is a subtype chosen by both "${known.property}" and "${property}"`,
+                    ]);
                 }
-                this.#literals.set(target, { property: schema.discriminator?.property ?? "", value });
+                const values = known?.values ?? [];
+                this.#literals.set(target, { property, values: values.includes(value) ? values : [...values, value] });
             }
         }
     }
@@ -55,7 +61,7 @@ export class SchemaTree {
     responseName(operationId) {
         return this.#responses.get(operationId);
     }
-    /** The value a subtype's discriminator property must hold, if the schema is a subtype. */
+    /** The values a subtype's discriminator property may hold, if the schema is a subtype. */
     literalFor(id) {
         return this.#literals.get(id);
     }

package/dist/codegen/typescript.js

@@ -55,7 +55,9 @@ class TypeWriter {
         const fields = names.map((name) => {
             const property = node.properties[name] ?? { type: "string" };
             const optional = node.required.includes(name) || literal?.property === name ? "" : "?";
-            const type = literal?.property === name ? JSON.stringify(literal.value) : this.node(property, `${where}.${name}`);
+            const type = literal?.property === name
+                ? literal.values.map((value) => JSON.stringify(value)).join(" | ")
+                : this.node(property, `${where}.${name}`);
             return `${doc(property.description, "  ")}  ${key(name)}${optional}: ${type}`;
         });
         const body = `{\n${fields.join("\n")}\n}`;

package/dist/codegen/valibot.js

@@ -97,8 +97,13 @@ class SchemaWriter {
         if (names.length === 0)
             return rest ? `v.record(v.string(), ${rest})` : "v.looseObject({})";
         const entries = names.map((name) => {
-            if (literal?.property === name)
-                return `  ${key(name)}: v.literal(${JSON.stringify(literal.value)}),`;
+            if (literal?.property === name) {
+                const [only] = literal.values;
+                const exact = literal.values.length === 1
+                    ? `v.literal(${JSON.stringify(only)})`
+                    : `v.picklist(${JSON.stringify(literal.values)})`;
+                return `  ${key(name)}: ${exact},`;
+            }
             const property = node.properties[name];
             const schema = this.node(property, `${where}.${name}`);
             return `  ${key(name)}: ${node.required.includes(name) ? schema : `v.optional(${schema})`},`;

package/dist/query/parser.d.ts

@@ -2,7 +2,9 @@ import { type QueryAst, type QueryContext } from "./types.js";
 export interface ParseOptions extends QueryContext {
     /** The field a bare word searches; `none` for a list, where a bare word is `query.bare-word`. */
     defaultField?: string;
+    /** Read `"a b"~N` as a phrase with `slop: N`; a caller that turns it on says what N counts. */
+    proximity?: boolean;
 }
-export declare const parseLucene: (text: string, { defaultField, ...context }?: ParseOptions) => QueryAst;
+export declare const parseLucene: (text: string, { defaultField, proximity, ...context }?: ParseOptions) => QueryAst;
 /** Bare terms eligible for forgiving retrieval; explicit syntax keeps strict semantics. */
 export declare const implicitTextTerms: (text: string) => Set<number>;

package/dist/query/parser.js

@@ -141,7 +141,7 @@ const regexHint = (text, at) => {
     const word = `${/[^\s()"]*$/u.exec(text.slice(0, at))?.[0] ?? ""}${/^[^\s()"]*/u.exec(text.slice(at))?.[0] ?? ""}`;
     return quoteHint(text, at) ?? `/ starts a regular expression; put the value in quotes: "${word}"`;
 };
-export const parseLucene = (text, { defaultField = "text", ...context } = {}) => {
+export const parseLucene = (text, { defaultField = "text", proximity = false, ...context } = {}) => {
     const fail = (reason, span, alternative) => queryError(reason, span, alternative ?? quoteHint(text, span.start), context);
     if (text.length > QUERY_LIMITS.bytes || new TextEncoder().encode(text).length > QUERY_LIMITS.bytes)
         fail("query.too-large", { start: 0, end: text.length });
@@ -290,6 +290,13 @@ export const parseLucene = (text, { defaultField = "text", ...context } = {}) =>
                 ...(implicit ? { implicit: true } : {}),
             });
         }
+        if (proximity && peek().kind === "~" && node.kind === "predicate" && node.operator === "phrase") {
+            take();
+            const distance = take();
+            if (distance.kind !== "number" || !/^\d+$/u.test(distance.raw))
+                fail("query.invalid-syntax", distance.span, 'write the distance as a whole number: "a b"~3');
+            node = { ...node, slop: Number(distance.raw), span: { start: node.span.start, end: distance.span.end } };
+        }
         if (peek().kind === "~")
             fail("query.unsupported-operator", peek().span, node.kind === "predicate" && node.operator === "phrase"
                 ? "proximity (~) is not supported — drop the ~ for the exact phrase, or join the words with AND"

package/dist/query/types.d.ts

@@ -21,6 +21,8 @@ export interface Predicate {
     span: Span;
     /** A bare word, under no field. */
     implicit?: true;
+    /** `"a b"~N`, read only when the parser is asked to: how far apart the phrase's words may be. */
+    slop?: number;
 }
 export type QueryNode = Predicate | {
     kind: "boolean";

package/dist/query/types.js

@@ -16,6 +16,7 @@ const predicateSchema = v.object({
     upper_inclusive: v.optional(v.boolean()),
     span: spanSchema,
     implicit: v.optional(v.literal(true)),
+    slop: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0))),
 });
 export const queryNodeSchema = v.variant("kind", [
     predicateSchema,

package/docs/standards/accounts.md

@@ -15,8 +15,9 @@ Rule ids on this page are `WC-ACCT-<n>`. How to read a rule, how ids work and wh
 
 cli-core resolves the profile for tg, max and wa. WC-ACCT-1 needs cli-core 0.319.0 or newer, and all three pin
 0.321.0. memo has no messenger profile: its shared commands run without one, and they pick accounts with `--provider`
-and `--account` (WC-ACCT-7). drive and zoom still have their own profile code: drive registers its own profiles, and
-zoom keeps one saved profile in its config file. These are known gaps, not exceptions.
+and `--account` (WC-ACCT-7). zoom resolves its own profile word by the same rules (`zm <profile> …`, `ZM_PROFILE`,
+`ZM_PROFILE_LOCK`) from zoom-cli 0.35.0, with cli-core's `liftProfile` and `usableProfileName`. drive still has its own
+profile code: it registers its own profiles. That is a known gap, not an exception.
 
 ## Rules
 

package/docs/standards/ci.md

@@ -96,7 +96,7 @@ cli-testing, cli-docs, plus community itself.
   cli-docs validates its site before each deployment instead, and community has no build. Third-party security apps
   may post their own checks.
 - **Applies to:** the CLIs, cli-base, cli-core and cli-testing. cli-base, whatsapp-cli, tg-cli, max-cli, cli-core
-  and cli-memo have `pr.yml`; drive-cli, zoom-cli and cli-testing do not have it yet. **Since:**
+  cli-memo and zoom-cli have `pr.yml`; drive-cli and cli-testing do not have it yet. **Since:**
   cli-base 0.41.0 (pull request validation since cli-base 0.44.6). **Rulings:** none.
 
 ### WC-CI-6 · Run the changelog guard on every pull request
@@ -169,8 +169,9 @@ cli-testing, cli-docs, plus community itself.
 - **Enforced by:** `whatsapp-cli: main ruleset required checks` · `cli-core: main ruleset required checks` ·
   `tg-cli: main ruleset required checks` · `max-cli: main ruleset required checks` ·
   `cli-memo: main ruleset required checks`, plus the main ruleset of cli-base itself. In each repository with pr.yml,
-  the ruleset requires the pull request validation jobs besides the standards job. drive-cli, zoom-cli, cli-testing
-  and cli-docs have no pr.yml, so their rulesets require only the standards job, and review covers the rest.
+  the ruleset requires the pull request validation jobs besides the standards job. drive-cli, cli-testing and cli-docs
+  have no pr.yml, so their rulesets require only the standards job, and review covers the rest. zoom-cli has pr.yml,
+  but its ruleset still requires only the standards job.
 - **Example:** `gh pr checks <number>` shows every line as pass before `gh pr merge`. Never merge with `--admin`. A
   release changes `main` the same way
   ([WC-REL-2](releases.md#wc-rel-2--main-changes-only-through-a-pull-request-also-during-a-release)).

package/docs/standards/mcp.md

@@ -20,9 +20,10 @@ Rule ids on this page are `WC-MCP-<n>`. How to read a rule, how ids work and whi
 ### Who follows these rules today
 
 tg, max and wa serve cli-core's personal server (`<cli> <profile> mcp`) and bot server (`<cli> <profile> bot mcp`).
-memo, drive and zoom have their own servers: memo has hand-written tools, drive builds one tool per command from its
-command tree and skips commands through its own list, and zoom's `serve --mcp` only reads. Those three are known gaps
-against these rules.
+zoom serves the three shared tools over its own commands from zoom-cli 0.35.0 (`zm <profile> mcp`, cli-core's
+`toolsFromCommands` and `runCommandForAgent`). memo and drive have their own servers: memo has hand-written tools, and
+drive builds one tool per command from its command tree and skips commands through its own list. Those two are known
+gaps against these rules.
 
 WC-MCP-2 and WC-MCP-8 need cli-core 0.321.0, which tg, max and wa pin.
 

package/docs/standards/output.md

@@ -52,9 +52,9 @@ JSON Schema 2020-12.
 - **Enforced by:** `cli-core: src/cli/envelope.test.ts` · `cli-core: src/mcp/output-schema.test.ts`.
 - **Example:** a list is `{ items, page, next?, missing?, meta }`. One thing is `{ item, next?, missing?, meta }`.
   cli-core builds them with `listOf` and `itemOf`, and its `renderAnswer` refuses any other shape. A list never
-  answers a bare array.
-- **Exceptions:** a document that is not about the owner's data is printed whole, with no envelope: `commands --json`
-  and a `--dry-run` preview.
+  answers a bare array. A `--dry-run` preview is one thing: `{ item: <preview>, meta }`, with the
+  preview's parsed arguments and declared effects inside `item`.
+- **Exceptions:** command discovery (`commands --json`) is printed whole, with no envelope.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-358 (its older list shape is replaced by
   this one), NEED-431.
 

package/docs/standards/permissions.md

@@ -18,8 +18,10 @@ Rule ids on this page are `WC-PERM-<n>`. How to read a rule, how ids work and wh
 ### Who follows these rules today
 
 tg, max and wa use cli-core's permissions and write guard in full. memo uses them for the shared commands only. drive
-has its own policy and guard, with its own `--read-only` flag; zoom only reads. Where this page says "every CLI that
-writes", drive is a known gap.
+has its own policy and guard, with its own `--read-only` flag. zoom has per-profile `permissions` from zoom-cli 0.35.0,
+read with cli-core's `levelFor`; its writes change Zoom meetings, its built-in default is `remote-meetings: ask`, and
+it has no send journal or recipient list, since it sends no messages. Where this page says "every CLI that writes",
+drive is a known gap.
 
 WC-PERM-10 and WC-PERM-11 need cli-core 0.321.0, which tg, max and wa pin. WC-PERM-12 as written needs cli-core
 0.337.0; before it, the lock let through some local writes that overwrite what the owner saved. A command other

package/docs/standards/releases.md

@@ -161,7 +161,11 @@ on the [CI](ci.md) page.
 - **Enforced by:** `tg-cli: bin/release` · `max-cli: bin/release` · `whatsapp-cli: bin/release` ·
   `cli-memo: bin/release`.
 - **Example:** `bin/release --local` runs the same checks on this machine and reads the npm token from the keyring
-  into the publish command's environment. Neither success nor an error prints it.
+  into the publish command's environment. The checks include the test suite with its coverage floor,
+  any shipped non-JavaScript engine's tests, offline contracts, leak and secret scans, and dependency
+  vulnerability audits for each shipped language. Build and validate before supplying the token to the
+  publish process; publishing must not run unchecked lifecycle scripts with it. Neither success nor an
+  error prints the token.
 - **Exceptions:** none. drive's and zoom's `bin/release` have no `--local` yet.
 - **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-base",
-  "version": "0.48.0",
+  "version": "0.50.0",
   "description": "The parts every command line tool needs: output modes, terminal rendering, error model, exit codes, credentials, clocks",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",
@@ -139,7 +139,8 @@
     "lefthook": "2.1.16",
     "markdownlint-cli2": "0.23.3",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.2"
+    "vitest": "^5.0.2",
+    "yaml": "^2.9.1"
   },
   "publishConfig": {
     "access": "public"