api_binding_ui 2.0.2 → 3.1.0

package/dist/vite/plugin.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Vite plugin: the binding studio inside the app's dev server, never in a build.
+ *
+ *   // vite.config.ts
+ *   import { bindingStudio } from "api_binding_ui/vite";
+ *   plugins: [bindingStudio()]
+ *
+ * Serves the studio under /__binding/ and injects a floating button into the app's HTML pages
+ * (SPA and server-rendered alike). `vite build` never runs it (apply: "serve").
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+export interface BindingStudioOptions {
+    /** bindings.json, relative to the Vite root. Default "bindings.json". */
+    file?: string;
+    /** Path the studio is served under. Default "/__binding". */
+    base?: string;
+}
+type Next = (err?: unknown) => void;
+/** The parts of Vite's plugin API this uses; typed here so the package does not depend on Vite. */
+export interface VitePluginLike {
+    name: string;
+    apply: "serve";
+    configResolved: (config: {
+        root: string;
+    }) => void;
+    transformIndexHtml: (html: string) => string;
+    configureServer: (server: {
+        middlewares: {
+            use: (fn: (req: IncomingMessage, res: ServerResponse, next: Next) => void) => void;
+        };
+    }) => void;
+}
+/** Adds the overlay script before the last </body> of HTML chunks; leaves everything else as it is. */
+export declare function injectOverlay(res: ServerResponse, tag: string): void;
+export declare function bindingStudio(options?: BindingStudioOptions): VitePluginLike;
+export {};

package/dist/vite.js

@@ -0,0 +1,201 @@
+// src/vite/plugin.ts
+import path2 from "node:path";
+
+// src/server/handler.ts
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/framework/file.ts
+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;
+}
+
+// src/server/handler.ts
+var TYPES = { ".html": "text/html; charset=utf-8", ".js": "text/javascript", ".css": "text/css", ".svg": "image/svg+xml", ".map": "application/json", ".woff2": "font/woff2" };
+var DIST = fileURLToPath(new URL(".", import.meta.url));
+var APP_DIR = path.join(DIST, "app");
+var OVERLAY_FILE = path.join(DIST, "overlay.js");
+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 fs.readFile(path.resolve(base, src), "utf8");
+}
+async function writeFileAtomic(file, text) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  await fs.writeFile(tmp, text, "utf8");
+  await fs.rename(tmp, file);
+}
+async function readBody(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");
+}
+function send(res, status, body, type = "text/plain; charset=utf-8") {
+  res.writeHead(status, { "Content-Type": type, "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" }).end(body);
+}
+function createStudioHandler({ file, prefix, allowed }) {
+  const base = path.dirname(file);
+  return async (req, res) => {
+    const url = new URL(req.url ?? "/", "http://local");
+    if (prefix && url.pathname !== prefix && !url.pathname.startsWith(prefix + "/"))
+      return false;
+    const rel = url.pathname.slice(prefix.length) || "/";
+    try {
+      if (prefix && url.pathname === prefix) {
+        res.writeHead(302, { Location: prefix + "/" + url.search }).end();
+        return true;
+      }
+      if (rel.startsWith("/api/") && !allowed(req)) {
+        send(res, 403, "Forbidden.");
+        return true;
+      }
+      if (rel === "/api/bindings") {
+        if (req.method === "GET")
+          send(res, 200, await fs.readFile(file, "utf8"), "application/json");
+        else if (req.method === "PUT") {
+          const text = await readBody(req);
+          try {
+            parseBindingsFile(text);
+          } catch (e) {
+            send(res, 400, e.message);
+            return true;
+          }
+          await writeFileAtomic(file, text);
+          send(res, 204, "");
+        } else
+          send(res, 405, "Method not allowed.");
+        return true;
+      }
+      if (rel === "/api/openapi" && req.method === "GET") {
+        const src = url.searchParams.get("src") ?? "";
+        try {
+          send(res, 200, await readDocs(src, base), src.endsWith(".json") ? "application/json" : "text/yaml; charset=utf-8");
+        } catch (e) {
+          send(res, 502, e.message);
+        }
+        return true;
+      }
+      if (req.method !== "GET" && req.method !== "HEAD") {
+        send(res, 405, "Method not allowed.");
+        return true;
+      }
+      if (rel === "/overlay.js") {
+        send(res, 200, await fs.readFile(OVERLAY_FILE), TYPES[".js"]);
+        return true;
+      }
+      const target = path.resolve(APP_DIR, rel === "/" ? "index.html" : decodeURIComponent(rel.slice(1)));
+      if (!target.startsWith(APP_DIR + path.sep)) {
+        send(res, 404, "Not found.");
+        return true;
+      }
+      const data = await fs.readFile(target).catch(() => null);
+      if (!data) {
+        send(res, 404, "Not found.");
+        return true;
+      }
+      send(res, 200, data, TYPES[path.extname(target)] ?? "application/octet-stream");
+    } catch (e) {
+      send(res, 500, e.message);
+    }
+    return true;
+  };
+}
+
+// src/vite/plugin.ts
+function injectOverlay(res, tag) {
+  let done = false;
+  const isHtml = () => String(res.getHeader("content-type") ?? "").includes("text/html");
+  const patch = (chunk) => {
+    if (done || !isHtml())
+      return chunk;
+    const text = typeof chunk === "string" ? chunk : chunk instanceof Uint8Array ? Buffer.from(chunk).toString("utf8") : null;
+    if (text === null)
+      return chunk;
+    if (text.includes(tag)) {
+      done = true;
+      return chunk;
+    }
+    const i = text.lastIndexOf("</body>");
+    if (i < 0)
+      return chunk;
+    done = true;
+    if (!res.headersSent)
+      res.removeHeader("content-length");
+    return text.slice(0, i) + tag + text.slice(i);
+  };
+  const write = res.write.bind(res);
+  const end = res.end.bind(res);
+  res.write = (chunk, ...rest) => write(patch(chunk), ...rest);
+  res.end = (chunk, ...rest) => chunk == null || typeof chunk === "function" ? end(chunk, ...rest) : end(patch(chunk), ...rest);
+}
+function bindingStudio(options = {}) {
+  const base = (options.base ?? "/__binding").replace(/\/+$/, "");
+  const tag = `<script type="module" src="${base}/overlay.js"></script>`;
+  let file = "";
+  return {
+    name: "api-binding-studio",
+    apply: "serve",
+    configResolved(config) {
+      file = path2.resolve(config.root, options.file ?? "bindings.json");
+    },
+    transformIndexHtml: (html) => html.includes(tag) ? html : html.replace(/<\/body>/i, `${tag}</body>`),
+    configureServer(server) {
+      const allowed = (req) => {
+        const origin = req.headers.origin;
+        return req.method === "GET" || !origin || new URL(origin).host === req.headers.host;
+      };
+      const handle = createStudioHandler({ file, prefix: base, allowed });
+      server.middlewares.use((req, res, next) => {
+        handle(req, res).then((handled) => {
+          if (handled)
+            return;
+          if ((req.headers.accept ?? "").includes("text/html"))
+            injectOverlay(res, tag);
+          next();
+        }, next);
+      });
+    }
+  };
+}
+export {
+  bindingStudio,
+  injectOverlay
+};

package/package.json

@@ -1,53 +1,69 @@
-{
-  "name": "api_binding_ui",
-  "version": "2.0.2",
-  "description": "API binding framework: bind any UI component to documented APIs at design time, run the bindings in production.",
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./studio": {
-      "types": "./dist/studio/index.d.ts",
-      "import": "./dist/studio/index.js"
-    },
-    "./studio.css": "./dist/studio/index.css",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "dist",
-    "spec/FRAMEWORK.md",
-    "README.md",
-    "SKILL.md"
-  ],
-  "sideEffects": [
-    "**/*.css"
-  ],
-  "scripts": {
-    "dev": "bun --port=5174 ./index.html",
-    "build": "rm -rf dist && bun build src/index.ts src/studio/index.ts --outdir dist --root src --target browser --splitting --sourcemap=linked --external react --external react-dom --external react/jsx-runtime --external yaml && node ./node_modules/typescript/bin/tsc -p tsconfig.build.json",
-    "typecheck": "node ./node_modules/typescript/bin/tsc --noEmit -p tsconfig.json",
-    "test": "bun test",
-    "prepublishOnly": "bun run typecheck && bun test && bun run build"
-  },
-  "peerDependencies": {
-    "react": ">=18.0.0",
-    "react-dom": ">=18.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.13.0",
-    "@types/react": "^19.2.0",
-    "@types/react-dom": "^19.2.0",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "typescript": "^5.8.0",
-    "vitest": "^3.0.0"
-  },
-  "dependencies": {
-    "yaml": "^2.8.1"
-  }
+{
+  "name": "api_binding_ui",
+  "version": "3.1.0",
+  "description": "Design-time API binding: register screen components, bind them to documented APIs in a studio, and generate plain React Query hooks over an Orval client. Nothing ships in the app.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./studio": {
+      "types": "./dist/studio/index.d.ts",
+      "import": "./dist/studio/index.js"
+    },
+    "./studio.css": "./dist/studio/index.css",
+    "./package.json": "./package.json",
+    "./vite": {
+      "types": "./dist/vite/plugin.d.ts",
+      "import": "./dist/vite.js"
+    }
+  },
+  "files": [
+    "dist",
+    "spec/FRAMEWORK.md",
+    "README.md",
+    "SKILL.md"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "dev": "bun run build:app && node dist/cli.js studio src/dev/sample/bindings.json",
+    "build:app": "rm -rf dist/app && bun build ./index.html --outdir dist/app --minify",
+    "build": "rm -rf dist && bun build src/index.ts src/studio/index.ts --outdir dist --root src --target browser --splitting --sourcemap=linked --external react --external react-dom --external react/jsx-runtime --external yaml && bun build src/cli/cli.ts --outfile dist/cli.js --target node --external yaml --banner '#!/usr/bin/env node' && bun build src/vite/plugin.ts --outfile dist/vite.js --target node --external yaml && bun build src/overlay/main.ts --outfile dist/overlay.js --target browser --minify && bun run build:app && node ./node_modules/typescript/bin/tsc -p tsconfig.build.json",
+    "typecheck": "node ./node_modules/typescript/bin/tsc --noEmit -p tsconfig.json",
+    "test": "bun test",
+    "prepublishOnly": "bun run typecheck && bun test && bun run build"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "yaml": "^2.8.1"
+  },
+  "bin": {
+    "api-binding": "dist/cli.js"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  }
 }