api_binding_ui 2.0.2 → 3.0.0

package/dist/cli.js

@@ -0,0 +1,969 @@
+#!/usr/bin/env node
+
+// src/cli/cli.ts
+import { createServer } from "node:http";
+import { promises as fs2 } from "node:fs";
+import path2 from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/framework/names.ts
+function humanize(id) {
+  const s = id.replace(/^\$\.?/, "").replace(/\[\*\]/g, "").split(/[./]/).filter(Boolean).pop() ?? id;
+  const w = s.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").toLowerCase().trim();
+  return w ? w[0].toUpperCase() + w.slice(1) : id;
+}
+
+// src/framework/file.ts
+var ID = /^[a-z][a-z0-9-]*(\.[a-z0-9-]+)+$/;
+var BINDING_TYPES = new Set(["operation", "expression", "steps", "none"]);
+function parseBindingsFile(text) {
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    throw new Error("The bindings file is not valid JSON.");
+  }
+  const f = data;
+  if (!f || typeof f !== "object")
+    throw new Error("The bindings file must be a JSON object.");
+  if (f.version !== 3)
+    throw new Error(`The bindings file must have "version": 3.`);
+  if (typeof f.openapi !== "string" || !f.openapi)
+    throw new Error(`The bindings file needs "openapi": the docs URL or a path.`);
+  for (const k of ["kinds", "screens", "components", "bindings"])
+    if (!Array.isArray(f[k]))
+      throw new Error(`"${k}" must be a list.`);
+  f.bindings.forEach((b, i) => {
+    const x = b;
+    if (!x || typeof x.component !== "string" || typeof x.slot !== "string" || !BINDING_TYPES.has(x.type))
+      throw new Error(`Binding ${i + 1} needs "component", "slot" and a known "type".`);
+  });
+  if (f.output && (typeof f.output.dir !== "string" || typeof f.output.client !== "string"))
+    throw new Error(`"output" needs "dir" and "client".`);
+  return f;
+}
+function screenOf(id, screens) {
+  let best;
+  for (const s of screens)
+    if (id.startsWith(s + ".") && (!best || s.length > best.length))
+      best = s;
+  return best;
+}
+function productLabel(seg, catalog) {
+  const names = new Set(catalog.operations.map((o) => o.product).filter((p) => !!p));
+  return [...names].find((n) => n.toLowerCase().replace(/[^a-z0-9]+/g, "-") === seg) ?? humanize(seg);
+}
+function fromFile(file, catalog) {
+  const issues = [];
+  const ids = file.screens.map((s) => s.id);
+  const screens = file.screens.map((s) => ({
+    id: s.id,
+    label: s.label,
+    description: s.description,
+    context: s.context ?? [],
+    components: [],
+    path: [productLabel(s.id.split(".")[0], catalog)],
+    parent: screenOf(s.id, ids)
+  }));
+  const byId = new Map(screens.map((s) => [s.id, s]));
+  const screenIds = new Set(ids);
+  for (const c of file.components) {
+    if (screenIds.has(c.id)) {
+      issues.push({ severity: "error", screen: c.id, component: c.id, code: "registry.id-clash", message: `"${c.id}" is both a screen and a component id.` });
+      continue;
+    }
+    const s = screenOf(c.id, ids);
+    if (!s) {
+      issues.push({ severity: "error", screen: "", component: c.id, code: "registry.no-screen", message: `"${c.id}" starts with no registered screen id.` });
+      continue;
+    }
+    byId.get(s).components.push({ bindId: c.id, kind: c.kind, label: c.label, parent: c.parent, info: c.info });
+  }
+  const index = {};
+  for (const b of file.bindings) {
+    const s = screenOf(b.component, ids);
+    if (!s) {
+      issues.push({ severity: "error", screen: "", component: b.component, slot: b.slot, code: "binding.no-screen", message: `Binding for "${b.component}" fits no screen.` });
+      continue;
+    }
+    (index[s] ??= []).push(b);
+  }
+  return {
+    fw: { descriptors: file.kinds, registry: { registryVersion: 1, screens }, catalog, glossaries: file.glossaries },
+    index,
+    issues
+  };
+}
+
+// src/framework/loadCatalog.ts
+import { parse } from "yaml";
+
+// src/framework/openapi.ts
+var METHODS = ["get", "put", "post", "delete", "patch", "head", "options", "trace", "query"];
+function hashString(s) {
+  let h = 2166136261;
+  for (let i = 0;i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+function pointerGet(doc, ref) {
+  if (!ref.startsWith("#/"))
+    return;
+  return ref.slice(2).split("/").map((k) => k.replace(/~1/g, "/").replace(/~0/g, "~")).reduce((o, k) => o == null ? undefined : o[k], doc);
+}
+function deref(doc, node, seen = []) {
+  if (Array.isArray(node))
+    return node.map((n) => deref(doc, n, seen));
+  if (!node || typeof node !== "object")
+    return node;
+  const n = node;
+  if (typeof n.$ref === "string") {
+    if (seen.includes(n.$ref) || seen.length > 24)
+      return { $ref: n.$ref };
+    const { $ref, ...rest } = n;
+    const target = deref(doc, pointerGet(doc, $ref), [...seen, $ref]);
+    return Object.keys(rest).length ? { ...target, ...deref(doc, rest, seen) } : target;
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(n))
+    out[k] = deref(doc, v, seen);
+  return out;
+}
+function jsonContent(content) {
+  if (!content)
+    return;
+  const key = Object.keys(content).find((k) => /json/i.test(k)) ?? Object.keys(content)[0];
+  return key ? content[key]?.schema : undefined;
+}
+function intentOf(method, op) {
+  if (typeof op["x-binding-intent"] === "string")
+    return op["x-binding-intent"];
+  if (method === "get" || method === "head" || method === "query")
+    return "read";
+  if (["put", "patch", "delete"].includes(method))
+    return "write";
+  return;
+}
+function catalogFromOpenApi(input, source = {}) {
+  const doc = input;
+  if (!doc || typeof doc !== "object" || !doc.paths)
+    throw new Error("This file is not an OpenAPI document: it has no paths.");
+  const operations = [];
+  const productOf = new Map;
+  for (const g of doc["x-tagGroups"] ?? [])
+    g.tags?.forEach((t) => {
+      if (g.name)
+        productOf.set(t, g.name);
+    });
+  for (const [path, rawItem] of Object.entries(doc.paths)) {
+    const item = deref(doc, rawItem);
+    for (const method of METHODS) {
+      const op = item?.[method];
+      if (!op || !op.operationId)
+        continue;
+      const params = [];
+      for (const p of [...item.parameters ?? [], ...op.parameters ?? []]) {
+        if (!p?.name || !p?.in)
+          continue;
+        const pointer = `/${p.in}/${p.name}`;
+        const at = params.findIndex((x) => x.pointer === pointer);
+        const entry = { pointer, name: p.name, required: !!p.required || p.in === "path", schema: p.schema ?? {}, description: p.description };
+        if (at >= 0)
+          params[at] = entry;
+        else
+          params.push(entry);
+      }
+      for (const m of path.matchAll(/\{([^}]+)\}/g)) {
+        if (!params.some((x) => x.pointer === `/path/${m[1]}`))
+          params.unshift({ pointer: `/path/${m[1]}`, name: m[1], required: true, schema: { type: "string" } });
+      }
+      const bodySchema = jsonContent(op.requestBody?.content);
+      const responses = Object.entries(op.responses ?? {}).map(([status, r]) => ({ status, schema: jsonContent(r?.content) }));
+      const extensions = {};
+      for (const [k, v] of Object.entries(op))
+        if (k.startsWith("x-"))
+          extensions[k] = v;
+      operations.push({
+        id: op.operationId,
+        method: method.toUpperCase(),
+        path,
+        summary: op.summary,
+        description: op.description,
+        tags: op.tags ?? [],
+        product: op.tags?.map((t) => productOf.get(t)).find(Boolean),
+        intent: intentOf(method, op),
+        parameters: params,
+        body: bodySchema ? { required: !!op.requestBody?.required, schema: bodySchema } : undefined,
+        responses,
+        extensions
+      });
+    }
+  }
+  const body = JSON.stringify(operations);
+  return {
+    catalogVersion: 1,
+    source: { title: doc.info?.title ?? "API", version: doc.info?.version ?? "", url: source.url },
+    hash: hashString(body),
+    operations,
+    schemas: {}
+  };
+}
+
+// src/framework/loadCatalog.ts
+class CatalogLoadError extends Error {
+  source;
+  constructor(message, source) {
+    super(message);
+    this.source = source;
+    this.name = "CatalogLoadError";
+  }
+}
+function catalogFromText(text, source) {
+  const body = text.trim();
+  if (!body)
+    throw new CatalogLoadError("Nothing to read: the text is empty.", source);
+  let doc;
+  try {
+    doc = body.startsWith("{") ? JSON.parse(body) : parse(body);
+  } catch {
+    throw new CatalogLoadError("The text is not valid JSON or YAML.", source);
+  }
+  try {
+    return catalogFromOpenApi(doc, source.includes("://") ? { url: source } : {});
+  } catch (e) {
+    throw new CatalogLoadError(e instanceof Error ? e.message : "The text is not an OpenAPI document.", source);
+  }
+}
+
+// src/framework/expr.ts
+var cache = new Map;
+function segments(path) {
+  return path.replace(/\[(\*|\d+)\]/g, ".$1").split(".").filter(Boolean);
+}
+function parse2(expr) {
+  const hit = cache.get(expr);
+  if (hit)
+    return hit;
+  const e = expr.trim();
+  let parsed;
+  if (e.startsWith("$")) {
+    const segs = segments(e);
+    const [h, id] = segs;
+    if (h === "$item")
+      parsed = { head: { type: "item" }, path: segs.slice(1) };
+    else if ((h === "$context" || h === "$steps") && id)
+      parsed = { head: { type: h === "$context" ? "context" : "steps", id }, path: segs.slice(2) };
+    else
+      throw new Error(`Unknown source "${h}" in "${expr}".`);
+  } else {
+    const colon = e.indexOf(":");
+    if (colon < 1)
+      throw new Error(`"${expr}" must read "<componentId>:<slot>".`);
+    const [slot, ...path] = segments(e.slice(colon + 1));
+    if (!slot)
+      throw new Error(`"${expr}" names no slot.`);
+    parsed = { head: { type: "slot", component: e.slice(0, colon), slot }, path };
+  }
+  cache.set(expr, parsed);
+  return parsed;
+}
+
+// src/framework/schema.ts
+var obj = (s) => s && typeof s === "object" ? s : {};
+function flat(s) {
+  const o = obj(s);
+  const parts = [o, ...(o.allOf ?? []).map(flat)];
+  if (parts.length === 1 && !o.oneOf && !o.anyOf)
+    return o;
+  const props = {};
+  const required = [];
+  parts.forEach((p) => {
+    Object.assign(props, p.properties ?? {});
+    required.push(...p.required ?? []);
+  });
+  const alt = (o.oneOf ?? o.anyOf)?.map(flat).find((x) => x.type !== "null");
+  return { ...alt ?? {}, ...o, properties: Object.keys(props).length ? props : alt?.properties, required };
+}
+var views = new WeakMap;
+
+// src/framework/validate.ts
+function validateRegistry(fw) {
+  const kinds = new Set(fw.descriptors.map((d) => d.kind));
+  const issues = [];
+  const ids = new Set(fw.registry.screens.map((s) => s.id));
+  const seen = new Set;
+  const screens = fw.registry.screens.map((S) => {
+    if (!ID.test(S.id)) {
+      issues.push({ severity: "error", screen: S.id, code: "registry.invalid-id", message: `Screen id "${S.id}" must be lowercase kebab-case segments joined by dots.` });
+      return { ...S, components: [] };
+    }
+    const components = S.components.filter((c) => {
+      if (!ID.test(c.bindId)) {
+        issues.push({ severity: "error", screen: S.id, component: c.bindId, code: "registry.invalid-id", message: `Component id "${c.bindId}" must be lowercase kebab-case segments joined by dots.` });
+        return false;
+      }
+      if (!kinds.has(c.kind)) {
+        issues.push({ severity: "error", screen: S.id, component: c.bindId, code: "registry.unknown-kind", message: `"${c.label}" uses ${c.kind}, which has no descriptor.` });
+        return false;
+      }
+      if (seen.has(c.bindId)) {
+        issues.push({ severity: "error", screen: S.id, component: c.bindId, code: "registry.duplicate-id", message: `Component id "${c.bindId}" is used twice.` });
+        return false;
+      }
+      seen.add(c.bindId);
+      return true;
+    }).filter((c) => !c.parent || seen.has(c.parent) || (issues.push({ severity: "error", screen: S.id, component: c.bindId, code: "registry.missing-parent", message: `"${c.label}" names a parent that is not on the screen.` }), false));
+    const parent = S.parent && ids.has(S.parent) ? S.parent : undefined;
+    return { ...S, components, parent };
+  });
+  return { registry: { ...fw.registry, screens }, issues };
+}
+
+// src/codegen/helpers.ts
+var HELPERS = `import { useMutation, useQuery } from "@tanstack/react-query";
+
+/** Data for a slot. \`bound\` is false when no API feeds it; keep the UI's own value then. */
+export interface Data<T> { bound: boolean; data: T | undefined; loading: boolean; error: unknown }
+/** An action. \`run\` rejects when a call fails; it resolves at once when no API is connected. */
+export interface Action { bound: boolean; run: (payload?: any) => Promise<void>; running: boolean; error: unknown }
+/** A per-item value, such as a cell in a row. */
+export interface Cell<T> { bound: boolean; read: (item: any) => T | undefined }
+
+export const UNBOUND_DATA: Data<never> = { bound: false, data: undefined, loading: false, error: undefined };
+export const UNBOUND_ACTION: Action = { bound: false, run: async () => {}, running: false, error: undefined };
+export const UNBOUND_CELL: Cell<never> = { bound: false, read: () => undefined };
+
+export class ApiError extends Error {
+  constructor(readonly status: number, readonly data: unknown) { super(\`API call failed (\${status})\`); this.name = "ApiError"; }
+}
+
+/** Reads a path; "*" maps the rest of the path over a list. */
+export function at(value: unknown, path: readonly string[]): any {
+  let v: any = value;
+  for (let i = 0; i < path.length; i++) {
+    if (v == null) return undefined;
+    if (path[i] === "*") return Array.isArray(v) ? v.map(x => at(x, path.slice(i + 1))) : undefined;
+    v = v[path[i]];
+  }
+  return v;
+}
+
+/** The body of a client response; throws on a non-2xx status. Passes through clients that return the body. */
+export function ok(res: any): any {
+  if (res && typeof res === "object" && typeof res.status === "number" && "data" in res && "headers" in res) {
+    if (res.status < 200 || res.status >= 300) throw new ApiError(res.status, res.data);
+    return res.data;
+  }
+  return res;
+}
+
+/** True when every required input has a value. */
+export const has = (inputs: Record<string, unknown>) => Object.values(inputs).every(v => v !== undefined);
+
+/** Throws when a required input has no value. */
+export function need(operation: string, inputs: Record<string, unknown>) {
+  const missing = Object.keys(inputs).filter(k => inputs[k] === undefined);
+  if (missing.length) throw new Error(\`\${operation}: missing \${missing.join(", ")}\`);
+}
+
+/** Drops undefined values. */
+export const defined = (o: Record<string, unknown>): any => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+
+export const path = (v: unknown): any => (v === undefined ? undefined : encodeURIComponent(String(v)));
+
+/** A body from a base value and [keys, value] entries; undefined values are skipped. */
+export function assemble(base: unknown, entries: Array<[string[], unknown]>): any {
+  const out: any = base && typeof base === "object" ? { ...base } : {};
+  for (const [keys, value] of entries) {
+    if (value === undefined) continue;
+    let node = out;
+    keys.slice(0, -1).forEach(k => { node = node[k] = node[k] && typeof node[k] === "object" ? { ...node[k] } : {}; });
+    node[keys[keys.length - 1]] = value;
+  }
+  return out;
+}
+
+/** Adds mapped fields to each item, keeping the fields the API returned. */
+export function mapItems(data: any, map: (item: any) => Record<string, unknown>): any {
+  const one = (item: any) => ({ ...(item && typeof item === "object" ? item : {}), ...map(item) });
+  return Array.isArray(data) ? data.map(one) : data == null ? data : one(data);
+}
+
+export const list = (v: unknown): unknown[] => (Array.isArray(v) ? v : v === undefined ? [] : [v]);
+
+export function finish(failed: unknown[]) {
+  if (failed.length === 1) throw failed[0];
+  if (failed.length) throw new AggregateError(failed, \`\${failed.length} API calls failed\`);
+}
+
+export function useData<T>(key: readonly unknown[], fetch: () => Promise<unknown>, select: (data: any) => T, options: { enabled: boolean; everySeconds?: number }): Data<T> {
+  const q = useQuery({ queryKey: key, queryFn: fetch, select, enabled: options.enabled, refetchInterval: options.everySeconds ? options.everySeconds * 1000 : false });
+  return { bound: true, data: q.data, loading: q.isLoading, error: q.error ?? undefined };
+}
+
+export function useAction(run: (payload?: any) => Promise<void>): Action {
+  const m = useMutation({ mutationFn: run });
+  return { bound: true, run: payload => m.mutateAsync(payload), running: m.isPending, error: m.error ?? undefined };
+}
+`;
+
+// src/codegen/generate.ts
+var GENERATED_MARK = "@generated";
+var HEADER = `// ${GENERATED_MARK} Do not edit: change the bindings and regenerate.
+`;
+var words = (s) => s.split(/[.\-_]+/).filter(Boolean);
+var pascal = (s) => words(s).map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+var camel = (s) => {
+  const p = pascal(s);
+  return p[0].toLowerCase() + p.slice(1);
+};
+var str = (v) => JSON.stringify(v);
+var IDENT = /^[A-Za-z_$][\w$]*$/;
+var prop = (k) => IDENT.test(k) ? k : str(k);
+var orvalName = (id) => IDENT.test(id) ? id[0].toLowerCase() + id.slice(1) : camel(id);
+function tsType(schema, many = false, depth = 0) {
+  const one = () => {
+    if (!schema || typeof schema !== "object" || depth > 3)
+      return "any";
+    const s = schema;
+    if (Array.isArray(s.enum) && s.enum.length && s.enum.every((v) => typeof v === "string"))
+      return s.enum.map(str).join(" | ");
+    switch (s.type) {
+      case "string":
+        return "string";
+      case "integer":
+      case "number":
+        return "number";
+      case "boolean":
+        return "boolean";
+      case "array":
+        return `Array<${tsType(s.items, false, depth + 1)}>`;
+      case "object": {
+        const props = Object.entries(s.properties ?? {});
+        if (!props.length)
+          return "Record<string, any>";
+        return `{ ${props.map(([k, v]) => `${prop(k)}?: ${tsType(v, false, depth + 1)}`).join("; ")}; [key: string]: any }`;
+      }
+      default:
+        return "any";
+    }
+  };
+  return many ? `Array<${one()}>` : one();
+}
+function compileExpr(expr, cx, scope, at) {
+  let p;
+  try {
+    p = parse2(expr);
+  } catch (e) {
+    cx.issue("expr.invalid", e.message, at);
+    return "undefined";
+  }
+  const path = p.path.map(str);
+  const h = p.head;
+  const read = (root, keys) => {
+    cx.use.add("at");
+    return `at(${root}, [${keys.join(", ")}])`;
+  };
+  if (h.type === "item") {
+    if (!scope.item) {
+      cx.issue("expr.no-item", `"${expr}" reads $item, which this slot does not have.`, at);
+      return "undefined";
+    }
+    return path.length ? read("item", path) : "item";
+  }
+  if (h.type === "context") {
+    if (!cx.screen.context.some((c) => c.id === h.id)) {
+      cx.issue("expr.unknown-context", `"${expr}": ${cx.screen.id} declares no context "${h.id}".`, at);
+      return "undefined";
+    }
+    return read("state.context", [str(h.id), ...path]);
+  }
+  if (h.type === "steps") {
+    if (!scope.steps?.has(h.id)) {
+      cx.issue("expr.unknown-step", `"${expr}" reads step "${h.id}", which does not run before it.`, at);
+      return "undefined";
+    }
+    return read("steps", [str(h.id), ...path]);
+  }
+  if (!cx.produces.get(h.component)?.has(h.slot)) {
+    cx.issue("expr.unknown-slot", `"${expr}" reads a value that is not produced on ${cx.screen.id}.`, at);
+    return "undefined";
+  }
+  return read("state", [str(cx.keys.get(h.component)), str(h.slot), ...path]);
+}
+var decode = (k) => k.replace(/~1/g, "/").replace(/~0/g, "~");
+function compileCall(op, request, cx, scope, at) {
+  const e = (x) => compileExpr(x, cx, scope, at);
+  const known = new Set(op.parameters.map((p) => p.pointer));
+  const body = [];
+  let whole;
+  const query = [];
+  const headers = [];
+  for (const [pointer, x] of Object.entries(request)) {
+    const [, where, ...rest] = pointer.split("/");
+    const keys = rest.map(decode);
+    if (where === "body") {
+      if (!op.body) {
+        cx.issue("request.no-body", `${op.id} takes no body, but "${pointer}" is set.`, at);
+        continue;
+      }
+      if (!keys.length)
+        whole = e(x);
+      else
+        body.push(`[[${keys.map(str).join(", ")}], ${e(x)}]`);
+    } else if (!known.has(pointer))
+      cx.issue("request.unknown-input", `${op.id} has no input "${pointer}".`, at);
+    else if (where === "query")
+      query.push(`${prop(keys[0])}: ${e(x)}`);
+    else if (where === "header")
+      headers.push(`${str(keys[0])}: ${e(x)}`);
+  }
+  const args = [...op.path.matchAll(/\{([^}]+)\}/g)].map((m) => {
+    const x = request[`/path/${m[1]}`];
+    if (x === undefined) {
+      cx.issue("request.missing-path", `${op.id} needs "${m[1]}" in its path; it is not connected.`, at);
+      return "undefined";
+    }
+    cx.use.add("path");
+    return `path(${e(x)})`;
+  });
+  if (op.body) {
+    const set = new Set(Object.keys(request).filter((k) => k.startsWith("/body/")).map((k) => decode(k.split("/")[2])));
+    const gaps = whole ? [] : (flat(op.body.schema).required ?? []).filter((f) => !set.has(f));
+    if (gaps.length)
+      cx.warn("request.required-body", `${op.id} requires ${gaps.join(", ")} in its body; not connected.`, at);
+    cx.use.add("assemble");
+    args.push(`assemble(${whole ?? "undefined"}, [${body.join(", ")}])`);
+  }
+  if (op.parameters.some((p) => p.pointer.startsWith("/query/"))) {
+    cx.use.add("defined");
+    args.push(`defined({ ${query.join(", ")} })`);
+  }
+  const key = `[${[str(op.id), ...args].join(", ")}]`;
+  if (headers.length) {
+    cx.use.add("defined");
+    args.push(`{ headers: defined({ ${headers.join(", ")} }) }`);
+  }
+  const required = op.parameters.filter((p) => p.required).map((p) => `${prop(p.name)}: ${request[p.pointer] === undefined ? "undefined" : e(request[p.pointer])}`);
+  return { fn: orvalName(op.id), call: `${orvalName(op.id)}(${args.join(", ")})`, key, required: required.length ? `{ ${required.join(", ")} }` : "" };
+}
+var selectPath = (selector) => segments(selector.replace(/^\$\.?/, "").replace(/\[\*\]$/, ""));
+function compileSteps(steps, cx, at, ops, imports) {
+  const done = new Set;
+  const blocks = [];
+  let usesPayload = false;
+  cx.use.add("ok");
+  cx.use.add("finish");
+  for (const st of steps) {
+    const op = ops.get(st.operation);
+    if (!op) {
+      cx.issue("catalog.operation-missing", `${st.operation} is not in the API docs.`, at);
+      continue;
+    }
+    const scope = { item: true, steps: done };
+    const call = compileCall(op, st.request, cx, scope, at);
+    imports.add(call.fn);
+    const each = st.forEach ? compileExpr(st.forEach, cx, scope, at) : undefined;
+    if (each)
+      cx.use.add("list");
+    else
+      usesPayload = true;
+    if (call.required)
+      cx.use.add("need");
+    const readsItem = /\bitem\b/.test(call.call + call.required);
+    blocks.push([
+      `    {`,
+      `      const responses: unknown[] = [];`,
+      `      for (const item of ${each ? `list(${each})` : "[payload]"}) {`,
+      readsItem ? "" : `        void item;`,
+      `        try {`,
+      call.required ? `          need(${str(op.id)}, ${call.required});` : "",
+      `          responses.push(ok(await ${call.call}));`,
+      `        } catch (error) {`,
+      st.onError === "stop" ? `          throw error;` : `          failed.push(error);`,
+      `        }`,
+      `      }`,
+      `      steps[${str(st.id)}] = { response: ${each ? "responses" : "responses[0]"} };`,
+      `    }`
+    ].filter(Boolean).join(`
+`));
+    done.add(st.id);
+  }
+  return [
+    `async (${usesPayload ? "payload" : "_payload"}?: any) => {`,
+    `    const steps: Record<string, unknown> = {};`,
+    `    const failed: unknown[] = [];`,
+    ...blocks,
+    `    finish(failed);`,
+    `  }`
+  ].join(`
+`);
+}
+function generate(file, catalog) {
+  const issues = [];
+  const { fw, index, issues: fileIssues } = fromFile(file, catalog);
+  const valid = validateRegistry(fw);
+  issues.push(...fileIssues, ...valid.issues);
+  const ops = new Map(catalog.operations.map((o) => [o.id, o]));
+  const DESC = new Map(fw.descriptors.map((d) => [d.kind, d]));
+  const client = file.output?.client;
+  if (!client)
+    issues.push({ severity: "error", screen: "", code: "output.missing", message: `Set "output": { "dir", "client" } in the bindings file.` });
+  const files = [{ path: "screen-helpers.ts", content: HEADER + HELPERS }];
+  const exports = [];
+  for (const screen of valid.registry.screens) {
+    const name = pascal(screen.id);
+    const keys = new Map;
+    const taken = new Map;
+    for (const c of screen.components) {
+      const k = camel(c.bindId.slice(screen.id.length + 1));
+      if (taken.has(k))
+        issues.push({ severity: "error", screen: screen.id, component: c.bindId, code: "codegen.name-clash", message: `"${c.bindId}" and "${taken.get(k)}" both become "${k}".` });
+      taken.set(k, c.bindId);
+      keys.set(c.bindId, k);
+    }
+    const cx = {
+      screen,
+      keys,
+      use: new Set,
+      produces: new Map(screen.components.map((c) => [c.bindId, new Set(DESC.get(c.kind).slots.filter((s) => s.role === "produce").map((s) => s.id))])),
+      issue: (code, message, at) => issues.push({ severity: "error", screen: screen.id, code, message, ...at }),
+      warn: (code, message, at) => issues.push({ severity: "warning", screen: screen.id, code, message, ...at })
+    };
+    const bindings = new Map;
+    for (const b of index[screen.id] ?? []) {
+      if (!keys.has(b.component)) {
+        cx.issue("binding.unknown-component", `A binding names "${b.component}", which is not registered.`, b);
+        continue;
+      }
+      if (b.state !== "confirmed") {
+        issues.push({ severity: "warning", screen: screen.id, component: b.component, slot: b.slot, code: "binding.draft", message: `${b.component} · ${b.slot} is a draft; it is not generated.` });
+        continue;
+      }
+      bindings.set(`${b.component}|${b.slot}`, b);
+    }
+    const imports = new Set;
+    const types = new Set;
+    const body = [];
+    const ret = [];
+    const apiType = [];
+    const stateType = [];
+    for (const c of screen.components) {
+      const d = DESC.get(c.kind);
+      const k = keys.get(c.bindId);
+      const produce = d.slots.filter((s) => s.role === "produce");
+      if (produce.length)
+        stateType.push(`  ${prop(k)}?: { ${produce.map((s) => `${prop(s.id)}?: ${tsType(s.schema, s.many)}`).join("; ")} };`);
+      const out = [];
+      const outT = [];
+      const unbound = (slot, v) => {
+        cx.use.add(v);
+        out.push(`${prop(slot)}: ${v}`);
+      };
+      for (const s of d.slots.filter((x) => x.role !== "produce")) {
+        const b = bindings.get(`${c.bindId}|${s.id}`);
+        const at = { component: c.bindId, slot: s.id };
+        const v = `${k}${pascal(s.id)}`;
+        if (s.role === "trigger") {
+          types.add("Action");
+          outT.push(`${prop(s.id)}: Action`);
+          if (b?.type !== "steps") {
+            unbound(s.id, "UNBOUND_ACTION");
+            continue;
+          }
+          cx.use.add("useAction");
+          body.push(`  const ${v} = useAction(${compileSteps(b.steps, cx, at, ops, imports)});`);
+          out.push(`${prop(s.id)}: ${v}`);
+          continue;
+        }
+        const T = tsType(s.schema, s.many);
+        if (s.scope) {
+          types.add("Cell");
+          outT.push(`${prop(s.id)}: Cell<${T}>`);
+          if (b?.type !== "expression") {
+            unbound(s.id, "UNBOUND_CELL");
+            continue;
+          }
+          out.push(`${prop(s.id)}: { bound: true, read: (item: any) => ${compileExpr(b.value, cx, { item: true }, at)} }`);
+          continue;
+        }
+        types.add("Data");
+        outT.push(`${prop(s.id)}: Data<${T}>`);
+        if (b?.type === "expression") {
+          out.push(`${prop(s.id)}: { bound: true, data: ${compileExpr(b.value, cx, { item: false }, at)}, loading: false, error: undefined }`);
+          continue;
+        }
+        const op = b?.type === "operation" ? ops.get(b.operation) : undefined;
+        if (b?.type === "operation" && !op)
+          cx.issue("catalog.operation-missing", `${b.operation} is not in the API docs.`, at);
+        if (b?.type !== "operation" || !op) {
+          unbound(s.id, "UNBOUND_DATA");
+          continue;
+        }
+        const call = compileCall(op, b.request, cx, { item: false }, at);
+        imports.add(call.fn);
+        ["useData", "ok"].forEach((h) => cx.use.add(h));
+        if (call.required)
+          cx.use.add("has");
+        const sel = selectPath(b.select).map(str);
+        if (sel.length)
+          cx.use.add("at");
+        const picked = sel.length ? `at(data, [${sel.join(", ")}])` : "data";
+        const map = Object.entries(b.map ?? {});
+        if (map.length)
+          cx.use.add("mapItems");
+        const select = map.length ? `mapItems(${picked}, (item: any) => ({ ${map.map(([f, x]) => `${prop(f)}: ${compileExpr(x, cx, { item: true }, at)}`).join(", ")} }))` : picked;
+        const every = typeof b.load === "object" ? `, everySeconds: ${b.load.everySeconds}` : "";
+        body.push(`  const ${v} = useData<${T}>(${call.key}, async () => ok(await ${call.call}), (data: any) => ${select}, { enabled: ${call.required ? `has(${call.required})` : "true"}${every} });`);
+        out.push(`${prop(s.id)}: ${v}`);
+      }
+      if (out.length) {
+        ret.push(`    ${prop(k)}: { ${out.join(", ")} },`);
+        apiType.push(`  ${prop(k)}: { ${outT.join("; ")} };`);
+      }
+    }
+    if (screen.context.length)
+      stateType.push(`  context?: { ${screen.context.map((c) => `${prop(c.id)}?: ${"schema" in c.shape ? tsType(c.shape.schema, c.many) : c.many ? "Array<any>" : "any"}`).join("; ")} };`);
+    const usesState = [...body, ...ret].some((l) => /\bstate\b/.test(l));
+    const lines = [
+      HEADER.trimEnd(),
+      imports.size ? `import { ${[...imports].sort().join(", ")} } from ${str(client ?? "")};` : null,
+      cx.use.size ? `import { ${[...cx.use].sort().join(", ")} } from "./screen-helpers";` : null,
+      types.size ? `import type { ${[...types].sort().join(", ")} } from "./screen-helpers";` : null,
+      "",
+      `/** ${screen.label}: values its components produce, and what it was opened with. */`,
+      stateType.length ? `export interface ${name}State {
+${stateType.join(`
+`)}
+}` : `export type ${name}State = Record<string, never>;`,
+      "",
+      `export interface ${name}Api {
+${apiType.join(`
+`)}
+}`,
+      "",
+      `/** API data and actions for ${screen.label} (${screen.id}). */`,
+      `export function use${name}Api(${usesState ? "state" : "_state"}: ${name}State = {}): ${name}Api {`,
+      ...body,
+      `  return {`,
+      ...ret,
+      `  };`,
+      `}`,
+      ""
+    ].filter((l) => l !== null);
+    files.push({ path: `${screen.id}.ts`, content: lines.join(`
+`) });
+    exports.push(`export * from "./${screen.id}";`);
+  }
+  files.push({ path: "index.ts", content: HEADER + exports.join(`
+`) + `
+` });
+  return { files, issues };
+}
+
+// src/cli/scan.ts
+import { promises as fs } from "node:fs";
+import path from "node:path";
+var LITERAL = /componentId\s*(?:=\s*\{?\s*|:\s*)(["'`])([a-z0-9.-]+)\1/g;
+var SKIP = new Set(["node_modules", "dist", "build", ".git", ".next", ".output"]);
+async function* sources(dir) {
+  for (const e of await fs.readdir(dir, { withFileTypes: true })) {
+    if (SKIP.has(e.name))
+      continue;
+    const p = path.join(dir, e.name);
+    if (e.isDirectory())
+      yield* sources(p);
+    else if (/\.(tsx?|jsx?)$/.test(e.name))
+      yield p;
+  }
+}
+async function scanIds(dir, file) {
+  const found = new Map;
+  for await (const p of sources(dir))
+    for (const m of (await fs.readFile(p, "utf8")).matchAll(LITERAL))
+      if (!found.has(m[2]))
+        found.set(m[2], path.relative(dir, p));
+  const registered = new Set(file.components.map((c) => c.id));
+  const issues = [];
+  for (const [id, where] of found)
+    if (!registered.has(id))
+      issues.push({ severity: "warning", screen: "", component: id, code: "scan.unregistered", message: `In ${where}, but not registered.` });
+  for (const id of registered)
+    if (!found.has(id))
+      issues.push({ severity: "warning", screen: "", component: id, code: "scan.not-found", message: "Registered, but no componentId literal in the source (fine if the id is built from config)." });
+  return issues;
+}
+
+// src/cli/cli.ts
+var HELP = `Usage:
+  api-binding studio   [bindings.json] [--port 5180]
+  api-binding generate [bindings.json] [--check] [--src <dir>]
+
+  studio    Opens the binding studio on http://localhost:<port>. Edits are saved to the file.
+  generate  Writes one React Query hook per screen into output.dir, calling the Orval client.
+            --check  writes nothing; exits 1 when the files are out of date (for CI).
+            --src    also checks that every registered id appears in the app's source, and the reverse.`;
+function args(argv) {
+  const flags = {};
+  const rest = [];
+  for (let i = 0;i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) {
+      rest.push(a);
+      continue;
+    }
+    const next = argv[i + 1];
+    flags[a.slice(2)] = next && !next.startsWith("--") ? (i++, next) : true;
+  }
+  return { rest, flags };
+}
+var isUrl = (s) => /^https?:\/\//i.test(s);
+async function readDocs(src, base) {
+  if (isUrl(src)) {
+    const res = await fetch(src);
+    if (!res.ok)
+      throw new Error(`${src} returned HTTP ${res.status}.`);
+    return res.text();
+  }
+  if (!/\.(ya?ml|json)$/i.test(src))
+    throw new Error(`"${src}" is not a .yaml, .yml or .json file.`);
+  return fs2.readFile(path2.resolve(base, src), "utf8");
+}
+function report(issues) {
+  for (const i of issues)
+    console.log(`${i.severity === "error" ? "error  " : "warning"} ${[i.component ?? i.screen, i.slot].filter(Boolean).join(" · ")}: ${i.message}`);
+}
+async function writeFile(file, text) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  await fs2.writeFile(tmp, text, "utf8");
+  await fs2.rename(tmp, file);
+}
+async function runGenerate(filePath, flags) {
+  const base = path2.dirname(filePath);
+  const file = parseBindingsFile(await fs2.readFile(filePath, "utf8"));
+  const catalog = catalogFromText(await readDocs(file.openapi, base), file.openapi);
+  const { files, issues } = generate(file, catalog);
+  if (typeof flags.src === "string")
+    issues.push(...await scanIds(path2.resolve(flags.src), file));
+  report(issues);
+  const errors = issues.filter((i) => i.severity === "error").length;
+  if (errors) {
+    console.log(`
+${errors} error(s). Nothing was written.`);
+    return 1;
+  }
+  const out = path2.resolve(base, file.output.dir);
+  await fs2.mkdir(out, { recursive: true });
+  const wanted = new Map(files.map((f) => [path2.join(out, f.path), f.content]));
+  const existing = (await fs2.readdir(out)).filter((n) => n.endsWith(".ts")).map((n) => path2.join(out, n));
+  const changed = [];
+  const stale = [];
+  for (const [p, content] of wanted)
+    if (await fs2.readFile(p, "utf8").catch(() => null) !== content)
+      changed.push(p);
+  for (const p of existing)
+    if (!wanted.has(p) && (await fs2.readFile(p, "utf8")).startsWith(`// ${GENERATED_MARK}`))
+      stale.push(p);
+  if (flags.check) {
+    if (changed.length || stale.length) {
+      console.log(`Out of date: ${[...changed, ...stale].map((p) => path2.relative(process.cwd(), p)).join(", ")}`);
+      return 1;
+    }
+    console.log("Generated files are up to date.");
+    return 0;
+  }
+  for (const p of changed)
+    await writeFile(p, wanted.get(p));
+  for (const p of stale)
+    await fs2.unlink(p);
+  console.log(`${files.length - 2} screen hook(s) in ${path2.relative(process.cwd(), out) || "."}: ${changed.length} written, ${stale.length} removed.`);
+  return 0;
+}
+var TYPES = { ".html": "text/html; charset=utf-8", ".js": "text/javascript", ".css": "text/css", ".svg": "image/svg+xml", ".map": "application/json", ".woff2": "font/woff2" };
+async function body(req, limit = 20 * 1024 * 1024) {
+  const chunks = [];
+  let size = 0;
+  for await (const c of req) {
+    size += c.length;
+    if (size > limit)
+      throw new Error("Body too large.");
+    chunks.push(c);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function runStudio(filePath, flags) {
+  const port = Number(flags.port ?? 5180);
+  const base = path2.dirname(filePath);
+  parseBindingsFile(await fs2.readFile(filePath, "utf8"));
+  const app = fileURLToPath(new URL("./app/", import.meta.url));
+  const origins = new Set([`http://localhost:${port}`, `http://127.0.0.1:${port}`]);
+  const send = (res, status, text, type = "text/plain; charset=utf-8") => {
+    res.writeHead(status, { "Content-Type": type, "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" }).end(text);
+  };
+  const server = createServer(async (req, res) => {
+    try {
+      const host = req.headers.host ?? "";
+      if (!origins.has(`http://${host}`))
+        return send(res, 403, "Forbidden host.");
+      if (req.headers.origin && !origins.has(req.headers.origin))
+        return send(res, 403, "Forbidden origin.");
+      const url = new URL(req.url ?? "/", `http://${host}`);
+      if (url.pathname === "/api/bindings") {
+        if (req.method === "GET")
+          return send(res, 200, await fs2.readFile(filePath, "utf8"), "application/json");
+        if (req.method === "PUT") {
+          const text = await body(req);
+          try {
+            parseBindingsFile(text);
+          } catch (e) {
+            return send(res, 400, e.message);
+          }
+          await writeFile(filePath, text);
+          return send(res, 204, "");
+        }
+        return send(res, 405, "Method not allowed.");
+      }
+      if (url.pathname === "/api/openapi" && req.method === "GET") {
+        const src = url.searchParams.get("src") ?? "";
+        try {
+          return send(res, 200, await readDocs(src, base), src.endsWith(".json") ? "application/json" : "text/yaml; charset=utf-8");
+        } catch (e) {
+          return send(res, 502, e.message);
+        }
+      }
+      if (req.method !== "GET")
+        return send(res, 405, "Method not allowed.");
+      const rel = url.pathname === "/" ? "index.html" : decodeURIComponent(url.pathname.slice(1));
+      const target = path2.resolve(app, rel);
+      if (!target.startsWith(app))
+        return send(res, 404, "Not found.");
+      const data = await fs2.readFile(target).catch(() => null);
+      if (!data)
+        return send(res, 404, "Not found.");
+      res.writeHead(200, { "Content-Type": TYPES[path2.extname(target)] ?? "application/octet-stream", "X-Content-Type-Options": "nosniff" }).end(data);
+    } catch (e) {
+      send(res, 500, e.message);
+    }
+  });
+  server.listen(port, "127.0.0.1", () => console.log(`Binding studio: http://localhost:${port}
+Editing ${filePath}. Ctrl+C to stop.`));
+}
+async function main() {
+  const [cmd, ...argv] = process.argv.slice(2);
+  const { rest, flags } = args(argv);
+  const filePath = path2.resolve(rest[0] ?? "bindings.json");
+  if (cmd === "studio")
+    return runStudio(filePath, flags);
+  if (cmd === "generate")
+    process.exitCode = await runGenerate(filePath, flags);
+  else {
+    console.log(HELP);
+    process.exitCode = cmd && cmd !== "help" && cmd !== "--help" ? 1 : 0;
+  }
+}
+main().catch((e) => {
+  console.error(e instanceof Error ? e.message : e);
+  process.exitCode = 1;
+});