gemstack-contract 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cd1483984acde6e1833b4f5ff84b1e17f95f5aa89a9776faa4f1e55fa05f0512
+  data.tar.gz: 0da7d6e82afe251ffe35d34d4f003cab646c0fe51c75642961c15ca1dc777f31
+SHA512:
+  metadata.gz: 61586112c4732b9cb92e14b99e194de7f3d53ad9f57cdcecf56eb5214e7540ec643e75ceef29f852780fa9365f66742f28b741e94bf544d7d2520e6342a5d858
+  data.tar.gz: 9136268c95709be9d483e7ee14b9181b0ca96f2221e33746fb0e06d486aef50c54111f50960ea2f86aff0497fba9ccef320eb0449b4924575e2fc7d46ba75c12

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+First release. See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shoaib Malik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,24 @@
+# gemstack-contract
+
+GemStack contract: TypeScript types, API clients and OpenAPI from the backend.
+
+Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby API framework for Next.js
+applications. All GemStack gems are developed together in that repository and released with the same
+version.
+
+## Installation
+
+Installed with the `gemstack` gem; you rarely need to add it yourself.
+
+## Documentation
+
+- [Guide](https://github.com/gemstack-rb/gemstack/blob/main/docs/typescript.md)
+- [All guides](https://github.com/gemstack-rb/gemstack/tree/main/docs) ·
+  [Architecture](https://github.com/gemstack-rb/gemstack/blob/main/ARCHITECTURE.md)
+
+Source, issues and pull requests: [gemstack-rb/gemstack](https://github.com/gemstack-rb/gemstack)
+(this gem lives in `gems/gemstack-contract`).
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/gemstack/contract/builder.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Contract
+    # Turns the route table into a language-neutral contract (IR):
+    #
+    #   {
+    #     api_path: "/api",
+    #     types: { "Product" => { fields: [{ name:, type:, nullable:, optional: }] }, ... },
+    #     resources: [{ name: "products", endpoints: [{ name: "list", verb: "GET", path: "/products",
+    #                   params: [], body: nil, query: nil, response: { array: { ref: "Product" } } }] }],
+    #     warnings: [...]
+    #   }
+    #
+    # A type reference is { scalar: :string }, { ref: "Product" }, { array: ref },
+    # { object: [fields] } (anonymous nested object) or { unknown: true }.
+    #
+    # Response conventions (overridable with `returns` in the controller):
+    #   index → [<Resource>Serializer], show/create/update → <Resource>Serializer,
+    #   destroy → no body, anything else → unknown (with a warning).
+    class Builder
+      # Names the generated TypeScript defines itself.
+      RESERVED_TYPES = %w[Paginated PaginationMeta PaginationQuery RequestOptions].freeze
+
+      METHOD_NAMES = { "index" => "list", "show" => "get", "create" => "create", "update" => "update",
+                       "destroy" => "delete" }.freeze
+      VERB_PREFERENCE = %w[GET POST PATCH PUT DELETE].freeze
+
+      def initialize(routes:, api_path:)
+        @routes = routes
+        @api_path = api_path.to_s
+        @types = {}
+        @warnings = []
+      end
+
+      def build
+        result = build_contract
+        clash = result[:types].keys & RESERVED_TYPES
+        unless clash.empty?
+          raise ConfigurationError, "API type name(s) #{clash.join(", ")} are reserved by the generated TypeScript; " \
+                                    "rename the serializer/schema or set its type_name"
+        end
+        result
+      end
+
+      def build_contract
+        resources = @routes.select(&:controller).group_by(&:controller).sort.filter_map do |controller_name, routes|
+          controller = resolve(controller_name) or next
+          endpoints = routes.group_by(&:action).map do |action, action_routes|
+            endpoint(controller, action, action_routes)
+          end
+          { name: controller_name, endpoints: endpoints.compact.sort_by { |e| [e[:path], e[:name]] } }
+        end
+        { api_path: @api_path, types: @types.sort.to_h, resources: resources, warnings: @warnings }
+      end
+
+      private
+
+      def resolve(controller_name)
+        const = "#{Inflector.camelize(controller_name)}Controller"
+        Object.const_get(const)
+      rescue NameError
+        @warnings << "#{const} is not defined; its routes are left out of the contract"
+        nil
+      end
+
+      def endpoint(controller, action, routes)
+        route = routes.min_by { |r| VERB_PREFERENCE.index(r.verb) || 99 }
+        path = route.path.delete_prefix(@api_path)
+        path = "/" if path.empty?
+        schema = controller.input_schemas[action]
+        input = schema && schema_ref(schema, "#{resource_name(controller)}#{Inflector.camelize(action)}Input")
+        get = %w[GET HEAD].include?(route.verb)
+        response = response_ref(controller, action)
+        {
+          name: METHOD_NAMES.fetch(action) { lower_camel(action) }, action: action, verb: route.verb, path: path,
+          params: route.param_names.dup, body: get ? nil : input, query: get ? input : nil,
+          response: response, paginated: response.is_a?(Hash) && response.key?(:page)
+        }
+      end
+
+      def response_ref(controller, action)
+        if controller.response_types.key?(action)
+          type = controller.response_types[action]
+          return type.nil? ? nil : type_ref(type)
+        end
+
+        serializer = conventional_serializer(controller)
+        case action
+        when "index" then serializer ? { array: serializer_ref(serializer) } : unknown(controller, action)
+        when "show", "create", "update" then serializer ? serializer_ref(serializer) : unknown(controller, action)
+        when "destroy" then nil
+        else unknown(controller, action)
+        end
+      end
+
+      def unknown(controller, action)
+        @warnings << "#{controller.name}##{action}: response type unknown (add `returns :#{action}, SomeSerializer`)"
+        { unknown: true }
+      end
+
+      # ProductsController → ProductSerializer (Admin::ProductsController tries Admin::ProductSerializer first).
+      def conventional_serializer(controller)
+        parts = controller.name.delete_suffix("Controller").split("::")
+        singular = Inflector.singularize(parts.last)
+        candidates = ["#{(parts[0...-1] + [singular]).join("::")}Serializer", "#{singular}Serializer"].uniq
+        candidates.each do |name|
+          klass = Object.const_get(name) if Object.const_defined?(name)
+          return klass if klass.is_a?(Class) && klass <= Serializer
+        rescue NameError
+          next
+        end
+        nil
+      end
+
+      def resource_name(controller)
+        Inflector.singularize(controller.name.delete_suffix("Controller").split("::").join)
+      end
+
+      def type_ref(type)
+        case type
+        when HTTP::Page::Type then { page: type_ref(type.item) }
+        when Array then { array: type_ref(type.first) }
+        when Class
+          return serializer_ref(type) if type <= Serializer
+          return schema_ref(type, type.name.to_s.split("::").join) if type <= Schema
+
+          { scalar: Types.fetch(type).name }
+        else { scalar: Types.fetch(type).name }
+        end
+      end
+
+      def serializer_ref(serializer)
+        name = serializer.type_name
+        unless @types.key?(name)
+          @types[name] = :pending # guards against recursive serializers
+          fields = serializer.resolved_attributes.map do |attr|
+            if attr[:type] == :json && !serializer.attributes_list[attr[:name]].type
+              @warnings << "#{serializer.name}##{attr[:name]}: type unknown, emitted as unknown"
+            end
+            { name: attr[:name].to_s, type: type_ref(attr[:type]), nullable: attr[:nullable], optional: false }
+          end
+          @types[name] = { fields: fields }
+        end
+        { ref: name }
+      end
+
+      def schema_ref(schema, fallback_name)
+        name = schema.type_name || fallback_name
+        @types[name] ||= { fields: schema_fields(schema) }
+        { ref: name }
+      end
+
+      def schema_fields(schema)
+        schema.fields.values.map do |field|
+          type = field.schema ? { object: schema_fields(field.schema) } : { scalar: field.type }
+          type = { array: type } if field.array
+          { name: field.name.to_s, type: type, nullable: field.nullable, optional: field.ts_optional? }
+        end
+      end
+
+      def lower_camel(name)
+        camel = Inflector.camelize(name)
+        camel[0].downcase + camel[1..]
+      end
+    end
+  end
+end

data/lib/gemstack/contract/docs/index.html

@@ -0,0 +1,264 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>__TITLE__ API · GemStack</title>
+<style>
+  :root { color-scheme: light dark; --bg: #fff; --fg: #16181d; --muted: #5b6170; --panel: #f4f5f8; --line: #e3e5ea;
+    --get: #1f7a4d; --post: #2b59c3; --patch: #9a6700; --put: #7a3fb0; --delete: #c53030; --focus: #2b59c3; }
+  @media (prefers-color-scheme: dark) { :root { --bg: #0f1115; --fg: #e6e8ee; --muted: #9aa0ad; --panel: #181c26;
+    --line: #262b38; --get: #4cc38a; --post: #7ea2ff; --patch: #e0b44c; --put: #c49bf0; --delete: #ff7b7b; --focus: #7ea2ff; } }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--fg); font: 15px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
+  header { position: sticky; top: 0; z-index: 2; display: flex; gap: 1rem; align-items: center; padding: .7rem 1rem;
+    background: var(--bg); border-bottom: 1px solid var(--line); flex-wrap: wrap; }
+  header h1 { font-size: 1.05rem; margin: 0; } header .muted { font-size: .85rem; }
+  header input { flex: 1; min-width: 10rem; max-width: 24rem; }
+  .layout { display: grid; grid-template-columns: 15rem minmax(0, 1fr); }
+  nav { position: sticky; top: 3.3rem; align-self: start; max-height: calc(100vh - 3.3rem); overflow-y: auto; padding: 1rem;
+    border-right: 1px solid var(--line); font-size: .9rem; }
+  nav h2 { font-size: .75rem; text-transform: uppercase; letter-spacing: .05em; color: var(--muted); margin: 1rem 0 .3rem; }
+  nav a { display: flex; gap: .4rem; padding: .15rem 0; color: inherit; text-decoration: none; overflow-wrap: anywhere; }
+  nav a:hover { text-decoration: underline; }
+  main { padding: 1rem 1.5rem 4rem; min-width: 0; }
+  section.op { border: 1px solid var(--line); border-radius: 10px; margin: 0 0 1rem; overflow: hidden; }
+  section.op > summary { list-style: none; } details > summary::-webkit-details-marker { display: none; }
+  summary { display: flex; gap: .7rem; align-items: center; padding: .6rem .9rem; cursor: pointer; flex-wrap: wrap; }
+  summary code { font-size: .95rem; overflow-wrap: anywhere; }
+  .body { padding: .2rem 1rem 1rem; border-top: 1px solid var(--line); }
+  .verb { font: 700 .72rem/1 ui-monospace, Menlo, monospace; padding: .3rem .45rem; border-radius: 5px; color: #fff; min-width: 3.9rem; text-align: center; }
+  .GET { background: var(--get); } .POST { background: var(--post); } .PATCH { background: var(--patch); }
+  .PUT { background: var(--put); } .DELETE { background: var(--delete); }
+  nav .verb { min-width: 3.2rem; font-size: .62rem; padding: .22rem .3rem; }
+  h3 { font-size: .8rem; text-transform: uppercase; letter-spacing: .05em; color: var(--muted); margin: 1rem 0 .35rem; }
+  pre, textarea, input, select, button { font: 13px/1.5 ui-monospace, Menlo, monospace; }
+  pre { background: var(--panel); border-radius: 8px; padding: .7rem .9rem; margin: 0; overflow-x: auto; white-space: pre; }
+  table { border-collapse: collapse; width: 100%; font-size: .9rem; } td, th { text-align: left; padding: .3rem .5rem; border-bottom: 1px solid var(--line); vertical-align: top; }
+  th { color: var(--muted); font-weight: 600; }
+  input, textarea, select { width: 100%; padding: .4rem .5rem; border: 1px solid var(--line); border-radius: 6px; background: var(--bg); color: var(--fg); }
+  input:focus, textarea:focus, button:focus-visible { outline: 2px solid var(--focus); outline-offset: 1px; }
+  textarea { min-height: 7rem; resize: vertical; }
+  button { padding: .45rem .9rem; border-radius: 6px; border: 1px solid var(--fg); background: var(--fg); color: var(--bg); cursor: pointer; }
+  button:disabled { opacity: .6; cursor: default; }
+  .row { display: flex; gap: .6rem; align-items: center; margin-top: .6rem; flex-wrap: wrap; }
+  .muted { color: var(--muted); } .warn { border-left: 3px solid var(--patch); padding: .4rem .8rem; background: var(--panel); border-radius: 4px; margin: 0 0 1rem; font-size: .9rem; }
+  a.ref { color: var(--focus); }
+  .status { font-weight: 700; } .ok { color: var(--get); } .bad { color: var(--delete); }
+  @media (max-width: 760px) { .layout { grid-template-columns: 1fr; } nav { position: static; max-height: none; border-right: 0; border-bottom: 1px solid var(--line); } main { padding: 1rem; } }
+</style>
+</head>
+<body>
+<header>
+  <h1>__TITLE__ API</h1>
+  <input id="filter" type="search" placeholder="Filter endpoints…" aria-label="Filter endpoints">
+  <span class="muted">Development only · <a class="ref" href="__OPENAPI_URL__">openapi.json</a></span>
+</header>
+<div class="layout">
+  <nav id="nav" aria-label="Endpoints"></nav>
+  <main id="main"><p class="muted">Loading…</p></main>
+</div>
+<script>
+"use strict";
+const OPENAPI_URL = "__OPENAPI_URL__";
+const VERBS = ["get", "post", "put", "patch", "delete"];
+let doc;
+
+function el(tag, attrs, ...children) {
+  const node = document.createElement(tag);
+  for (const [key, value] of Object.entries(attrs || {})) {
+    if (value === undefined || value === null || value === false) continue;
+    if (key === "class") node.className = value;
+    else if (key.startsWith("on")) node.addEventListener(key.slice(2), value);
+    else node.setAttribute(key, value === true ? "" : value);
+  }
+  for (const child of children.flat(Infinity)) {
+    if (child === null || child === undefined || child === false) continue;
+    node.append(child instanceof Node ? child : String(child));
+  }
+  return node;
+}
+
+const refName = (ref) => ref.split("/").pop();
+const resolve = (schema) => (schema && schema.$ref ? doc.components.schemas[refName(schema.$ref)] : schema);
+
+// JSON Schema → a TypeScript-like description (matches the generated client types).
+function typeText(schema, indent = "") {
+  if (!schema) return "unknown";
+  if (schema.$ref) return refName(schema.$ref);
+  const variants = schema.anyOf || schema.oneOf;
+  if (variants) return variants.map((s) => typeText(s, indent)).join(" | ");
+  if (schema.enum) return schema.enum.map((v) => JSON.stringify(v)).join(" | ");
+  const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+  const nullable = types.includes("null");
+  const type = types.find((t) => t !== "null");
+  let text;
+  if (type === "array") text = `${wrap(typeText(schema.items, indent))}[]`;
+  else if (type === "object" && schema.properties) {
+    const required = new Set(schema.required || []);
+    const inner = indent + "  ";
+    const lines = Object.entries(schema.properties).map(
+      ([name, prop]) => `${inner}${name}${required.has(name) ? "" : "?"}: ${typeText(prop, inner)};`,
+    );
+    text = `{\n${lines.join("\n")}\n${indent}}`;
+  } else if (type === "object") text = schema.additionalProperties ? `Record<string, ${typeText(schema.additionalProperties, indent)}>` : "Record<string, unknown>";
+  else if (type === "integer" || type === "number") text = "number";
+  else if (type === "string") text = schema.format ? `string /* ${schema.format} */` : "string";
+  else text = type || "unknown";
+  return nullable ? `${text} | null` : text;
+}
+const wrap = (t) => (t.includes("|") ? `(${t})` : t);
+
+function example(schema, depth = 0) {
+  schema = resolve(schema);
+  if (!schema || depth > 4) return null;
+  if (schema.example !== undefined) return schema.example;
+  if (schema.enum) return schema.enum[0];
+  if (schema.anyOf || schema.oneOf) return example((schema.anyOf || schema.oneOf)[0], depth + 1);
+  const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+  const type = types.find((t) => t !== "null");
+  if (type === "object") {
+    const out = {};
+    for (const [name, prop] of Object.entries(schema.properties || {})) out[name] = example(prop, depth + 1);
+    return out;
+  }
+  if (type === "array") return [example(schema.items, depth + 1)];
+  if (type === "integer" || type === "number") return 0;
+  if (type === "boolean") return false;
+  if (type === "string") return { "date-time": new Date().toISOString(), date: new Date().toISOString().slice(0, 10), uuid: crypto.randomUUID() }[schema.format] || "";
+  return null;
+}
+
+// Types mentioned by a schema, linked below the signature.
+function refsIn(schema, found = new Set()) {
+  if (!schema || typeof schema !== "object") return found;
+  if (schema.$ref) {
+    const name = refName(schema.$ref);
+    if (!found.has(name)) { found.add(name); refsIn(doc.components.schemas[name], found); }
+    return found;
+  }
+  for (const value of Object.values(schema)) if (typeof value === "object") refsIn(value, found);
+  return found;
+}
+
+function schemaBlock(schema) {
+  const refs = [...refsIn(schema)].filter((name) => name !== "Error");
+  return [
+    el("pre", {}, typeText(schema)),
+    refs.length ? el("p", { class: "muted" }, "Types: ", refs.flatMap((name, i) => [i ? ", " : "", el("a", { class: "ref", href: `#type-${name}` }, name)])) : null,
+  ];
+}
+
+function operationSection(path, verb, op) {
+  const method = verb.toUpperCase();
+  const id = `op-${op.operationId || method + path}`.replace(/[^\w.-]/g, "-");
+  const params = op.parameters || [];
+  const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
+  const [status, response] = Object.entries(op.responses || {}).find(([code]) => code !== "default") || [];
+  const responseSchema = response?.content?.["application/json"]?.schema;
+
+  const inputs = {};
+  const paramRows = params.map((p) => {
+    inputs[p.name] = el("input", { name: p.name, placeholder: p.required ? "required" : "optional", "aria-label": p.name });
+    return el("tr", {}, el("td", {}, el("code", {}, p.name)), el("td", {}, p.in), el("td", {}, typeText(p.schema)), el("td", {}, inputs[p.name]));
+  });
+  const bodyInput = bodySchema ? el("textarea", { "aria-label": "Request body (JSON)", spellcheck: "false" }, JSON.stringify(example(bodySchema), null, 2)) : null;
+  const output = el("div");
+  const send = el("button", { type: "button" }, "Send request");
+  send.addEventListener("click", async () => {
+    send.disabled = true;
+    output.replaceChildren(el("p", { class: "muted" }, "Sending…"));
+    try {
+      let url = path;
+      const query = new URLSearchParams();
+      for (const p of params) {
+        const value = inputs[p.name].value;
+        if (p.in === "path") url = url.replace(`{${p.name}}`, encodeURIComponent(value));
+        else if (p.in === "query" && value !== "") query.append(p.name, value);
+      }
+      if (query.toString()) url += `?${query}`;
+      const init = { method, headers: { accept: "application/json" }, credentials: "same-origin" };
+      if (bodyInput) {
+        JSON.parse(bodyInput.value || "null"); // fail early on invalid JSON
+        init.body = bodyInput.value;
+        init.headers["content-type"] = "application/json";
+      }
+      const started = performance.now();
+      const res = await fetch(url, init);
+      const ms = Math.round(performance.now() - started);
+      const text = await res.text();
+      let shown = text;
+      try { shown = JSON.stringify(JSON.parse(text), null, 2); } catch { /* not JSON */ }
+      output.replaceChildren(
+        el("p", {}, el("span", { class: `status ${res.ok ? "ok" : "bad"}` }, `${res.status} ${res.statusText}`), el("span", { class: "muted" }, ` · ${ms} ms · ${method} ${url}`)),
+        text ? el("pre", {}, shown) : el("p", { class: "muted" }, "(no body)"),
+      );
+    } catch (error) {
+      output.replaceChildren(el("p", { class: "bad" }, String(error.message || error)));
+    } finally {
+      send.disabled = false;
+    }
+  });
+
+  return el("details", { class: "op", id, "data-search": `${method} ${path} ${op.operationId || ""}`.toLowerCase() },
+    el("summary", {}, el("span", { class: `verb ${method}` }, method), el("code", {}, path), el("span", { class: "muted" }, op.operationId || "")),
+    el("div", { class: "body" },
+      params.length ? [el("h3", {}, "Parameters"), el("table", {}, el("tr", {}, el("th", {}, "Name"), el("th", {}, "In"), el("th", {}, "Type"), el("th", {}, "Value")), paramRows)] : null,
+      bodySchema ? [el("h3", {}, "Request body"), schemaBlock(bodySchema)] : null,
+      el("h3", {}, `Response ${status || ""}`), responseSchema ? schemaBlock(responseSchema) : el("p", { class: "muted" }, "No body"),
+      el("h3", {}, "Try it"),
+      el("p", { class: "muted" }, "Sent from this page with your session cookie (sign in through the app first for protected endpoints)."),
+      bodyInput, el("div", { class: "row" }, send), output,
+    ),
+  );
+}
+
+function render() {
+  const main = document.getElementById("main");
+  const nav = document.getElementById("nav");
+  const groups = new Map();
+  for (const [path, item] of Object.entries(doc.paths || {})) {
+    for (const verb of VERBS) {
+      const op = item[verb];
+      if (!op) continue;
+      const tag = (op.tags && op.tags[0]) || "other";
+      if (!groups.has(tag)) groups.set(tag, []);
+      groups.get(tag).push({ path, verb, op });
+    }
+  }
+  const content = [];
+  const warnings = doc["x-gemstack-warnings"] || [];
+  if (warnings.length) content.push(el("div", { class: "warn" }, el("strong", {}, "Contract warnings"), el("ul", {}, warnings.map((w) => el("li", {}, w)))));
+  const navItems = [];
+  for (const [tag, ops] of [...groups.entries()].sort()) {
+    content.push(el("h2", { id: `tag-${tag}` }, tag));
+    navItems.push(el("h2", {}, tag));
+    for (const { path, verb, op } of ops) {
+      const section = operationSection(path, verb, op);
+      content.push(section);
+      navItems.push(el("a", { href: `#${section.id}`, "data-search": section.dataset.search, onclick: () => (section.open = true) },
+        el("span", { class: `verb ${verb.toUpperCase()}` }, verb.toUpperCase()), path));
+    }
+  }
+  const schemas = Object.entries(doc.components?.schemas || {}).sort(([a], [b]) => a.localeCompare(b));
+  content.push(el("h2", { id: "types" }, "Types"));
+  for (const [name, schema] of schemas) content.push(el("div", { id: `type-${name}` }, el("h3", {}, name), el("pre", {}, typeText(schema))));
+  if (!groups.size) content.unshift(el("p", { class: "muted" }, "No routes yet. Add some in config/routes.rb — this page rebuilds on every load."));
+  main.replaceChildren(...content);
+  nav.replaceChildren(...navItems, el("h2", {}, el("a", { href: "#types" }, "Types")));
+  const hash = decodeURIComponent(location.hash.slice(1));
+  if (hash) { const target = document.getElementById(hash); if (target) { if (target.tagName === "DETAILS") target.open = true; target.scrollIntoView(); } }
+}
+
+document.getElementById("filter").addEventListener("input", (event) => {
+  const q = event.target.value.trim().toLowerCase();
+  for (const node of document.querySelectorAll("[data-search]")) node.hidden = q !== "" && !node.dataset.search.includes(q);
+});
+
+fetch(OPENAPI_URL, { headers: { accept: "application/json" } })
+  .then((res) => (res.ok ? res.json() : Promise.reject(new Error(`HTTP ${res.status} loading ${OPENAPI_URL}`))))
+  .then((json) => { doc = json; render(); })
+  .catch((error) => document.getElementById("main").replaceChildren(el("p", { class: "bad" }, String(error.message || error))));
+</script>
+</body>
+</html>

data/lib/gemstack/contract/docs.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Contract
+    # Development API docs (DECISIONS D-056):
+    #   GET <api_path>/docs               interactive page (self-contained, no CDN)
+    #   GET <api_path>/docs/openapi.json  OpenAPI 3.1 built from the current routes
+    # Rebuilt on every request, so it always matches the code after a reload.
+    class Docs
+      PAGE = File.read(File.join(__dir__, "docs", "index.html")).freeze
+      CSP = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'; " \
+            "img-src data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
+
+      def initialize(app, application)
+        @app = app
+        @application = application
+      end
+
+      def call(env)
+        path = env[Rack::PATH_INFO]
+        base = "#{@application.config.http.api_path}/docs"
+        return @app.call(env) unless env[Rack::REQUEST_METHOD] == "GET" && [base, "#{base}/",
+                                                                            "#{base}/openapi.json"].include?(path)
+
+        path.end_with?(".json") ? openapi : page(base)
+      end
+
+      private
+
+      def openapi
+        contract = Builder.new(routes: @application.routes, api_path: @application.config.http.api_path).build
+        body = JSON.generate(OpenAPI.new(contract).document.merge("x-gemstack-warnings" => contract[:warnings]))
+        [200, { "content-type" => "application/json; charset=utf-8", "cache-control" => "no-store" }, [body]]
+      end
+
+      def page(base)
+        title = Rack::Utils.escape_html(GemStack.config.name.to_s)
+        html = PAGE.gsub("__OPENAPI_URL__", "#{base}/openapi.json").gsub("__TITLE__", title)
+        headers = { "content-type" => "text/html; charset=utf-8", "cache-control" => "no-store",
+                    "content-security-policy" => CSP }
+        [200, headers, [html]]
+      end
+    end
+  end
+end

data/lib/gemstack/contract/openapi.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Contract
+    # OpenAPI 3.1 document from the contract IR.
+    class OpenAPI
+      ERROR_SCHEMA = {
+        type: "object",
+        required: ["error"],
+        properties: {
+          error: {
+            type: "object", required: %w[code message],
+            properties: { code: { type: "string" }, message: { type: "string" }, request_id: { type: "string" } }
+          },
+          errors: { type: "object", additionalProperties: { type: "array", items: { type: "string" } } }
+        }
+      }.freeze
+
+      def initialize(contract, title: GemStack.config.name, version: GemStack::VERSION)
+        @contract = contract
+        @title = title
+        @version = version
+      end
+
+      def document
+        {
+          openapi: "3.1.0",
+          info: { title: @title, version: @version },
+          paths: paths,
+          components: { schemas: schemas.merge("Error" => ERROR_SCHEMA) }
+        }
+      end
+
+      PAGE_PARAMETERS = %w[page per_page].map do |name|
+        { name: name, in: "query", required: false, schema: { type: "integer", minimum: 1 } }
+      end.freeze
+
+      private
+
+      def paths
+        @contract[:resources].flat_map { |resource| resource[:endpoints].map { |e| [resource, e] } }
+                             .group_by { |_, e| openapi_path(e[:path]) }
+                             .transform_values do |pairs|
+          pairs.to_h do |resource, e|
+            [e[:verb].downcase, operation(resource, e)]
+          end
+        end
+      end
+
+      def operation(resource, endpoint)
+        op = {
+          operationId: "#{resource[:name].tr("/", "_")}.#{endpoint[:name]}",
+          tags: [resource[:name]],
+          parameters: endpoint[:params].map { |p| { name: p, in: "path", required: true, schema: { type: "string" } } },
+          responses: responses(endpoint)
+        }
+        op[:parameters].concat(query_parameters(endpoint[:query])) if endpoint[:query]
+        op[:parameters].concat(PAGE_PARAMETERS) if endpoint[:paginated]
+        if endpoint[:body]
+          op[:requestBody] =
+            { required: true, content: { "application/json" => { schema: schema_for(endpoint[:body]) } } }
+        end
+        op
+      end
+
+      def responses(endpoint)
+        success = endpoint[:verb] == "POST" ? "201" : "200"
+        ok = if endpoint[:response]
+               { success => { description: "OK",
+                              content: { "application/json" => { schema: schema_for(endpoint[:response]) } } } }
+             else
+               { "204" => { description: "No Content" } }
+             end
+        error = { description: "Error",
+                  content: { "application/json" => { schema: { "$ref": "#/components/schemas/Error" } } } }
+        ok.merge("default" => error)
+      end
+
+      def query_parameters(ref)
+        fields = ref[:ref] ? @contract[:types].dig(ref[:ref], :fields) : []
+        Array(fields).map do |field|
+          { name: field[:name], in: "query", required: !field[:optional], schema: schema_for(field[:type]) }
+        end
+      end
+
+      def schemas
+        @contract[:types].transform_values { |type| object_schema(type[:fields]) }
+      end
+
+      def object_schema(fields)
+        properties = fields.to_h do |field|
+          schema = schema_for(field[:type])
+          schema = { oneOf: [schema, { type: "null" }] } if field[:nullable]
+          [field[:name], schema]
+        end
+        { type: "object", properties: properties, required: fields.reject { |f| f[:optional] }.map { |f| f[:name] } }
+      end
+
+      def schema_for(ref)
+        if ref[:scalar] then Types.fetch(ref[:scalar]).openapi.dup
+        elsif ref[:ref] then { "$ref": "#/components/schemas/#{ref[:ref]}" }
+        elsif ref[:array] then { type: "array", items: schema_for(ref[:array]) }
+        elsif ref[:page] then page_schema(ref[:page])
+        elsif ref[:object] then object_schema(ref[:object])
+        else {}
+        end
+      end
+
+      def page_schema(item)
+        meta = %w[page per_page total total_pages].to_h { |key| [key, { type: "integer" }] }
+        {
+          type: "object", required: %w[data meta],
+          properties: {
+            data: { type: "array", items: schema_for(item) },
+            meta: { type: "object", required: meta.keys, properties: meta }
+          }
+        }
+      end
+
+      def openapi_path(path) = "#{@contract[:api_path]}#{path.gsub(/[:*](\w+)/, '{\1}')}"
+    end
+  end
+end

data/lib/gemstack/contract/typescript.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Contract
+    # Emits TypeScript from the contract IR:
+    #   types.ts          one `export type` per serializer / input schema
+    #   <resource>.ts     a typed client object per controller
+    #   index.ts          re-exports everything
+    #
+    # Shapes are type aliases (not interfaces) so they are assignable to the
+    # client's Query record type.
+    class TypeScript
+      def initialize(contract, client_import: "@/lib/gemstack/client")
+        @contract = contract
+        @client_import = client_import
+      end
+
+      def files
+        files = { "types.ts" => types_file }
+        @contract[:resources].each { |resource| files["#{file_base(resource)}.ts"] = resource_file(resource) }
+        files["index.ts"] = index_file
+        files
+      end
+
+      PAGE_TYPES = <<~TS
+        /** The pagination envelope returned by `paginate` in controllers. */
+        export type PaginationMeta = {
+          page: number;
+          per_page: number;
+          total: number;
+          total_pages: number;
+        };
+
+        export type Paginated<T> = {
+          data: T[];
+          meta: PaginationMeta;
+        };
+
+        export type PaginationQuery = {
+          page?: number;
+          per_page?: number;
+        };
+      TS
+
+      private
+
+      def header = "// #{HEADER}\n"
+
+      def types_file
+        body = @contract[:types].map do |name, type|
+          "export type #{name} = #{object_type(type[:fields], 0)};\n"
+        end
+        body.unshift(PAGE_TYPES) if paginated?
+        "#{header}\n#{body.join("\n")}"
+      end
+
+      def paginated? = @contract[:resources].any? { |r| r[:endpoints].any? { |e| e[:paginated] } }
+
+      def object_type(fields, depth)
+        return "Record<string, never>" if fields.empty?
+
+        pad = "  " * (depth + 1)
+        lines = fields.map do |field|
+          type = ts_type(field[:type], depth + 1)
+          type = "#{type} | null" if field[:nullable]
+          "#{pad}#{property(field[:name])}#{"?" if field[:optional]}: #{type};"
+        end
+        "{\n#{lines.join("\n")}\n#{"  " * depth}}"
+      end
+
+      def ts_type(ref, depth = 0)
+        if ref[:scalar] then Types.fetch(ref[:scalar]).ts
+        elsif ref[:ref] then ref[:ref]
+        elsif ref[:array]
+          inner = ts_type(ref[:array], depth)
+          inner.match?(/\A[\w.]+\z/) ? "#{inner}[]" : "Array<#{inner}>"
+        elsif ref[:page] then "Paginated<#{ts_type(ref[:page], depth)}>"
+        elsif ref[:object] then object_type(ref[:object], depth)
+        else "unknown"
+        end
+      end
+
+      def property(name) = name.match?(/\A[A-Za-z_$][\w$]*\z/) ? name : name.inspect
+
+      def resource_file(resource)
+        refs = []
+        methods = resource[:endpoints].map { |endpoint| client_method(endpoint, refs) }
+        imports = refs.uniq.sort
+        lines = [header]
+        lines << %(import { api, type RequestOptions } from "#{@client_import}";)
+        lines << %(import type { #{imports.join(", ")} } from "./types";) unless imports.empty?
+        lines << ""
+        lines << "const segment = (value: string | number) => encodeURIComponent(String(value));"
+        lines << ""
+        lines << "export const #{export_name(resource)} = {"
+        lines.concat(methods)
+        lines << "};"
+        "#{lines.join("\n")}\n"
+      end
+
+      def client_method(endpoint, refs)
+        args = endpoint[:params].map { |param| "#{camel(param)}: string | number" }
+        collect_refs(endpoint[:body], refs)
+        collect_refs(endpoint[:query], refs)
+        collect_refs(endpoint[:response], refs)
+        args << "data: #{ts_type(endpoint[:body])}" if endpoint[:body]
+        args << query_arg(endpoint) if endpoint[:query] || endpoint[:paginated]
+        refs << "PaginationQuery" if endpoint[:paginated]
+        args << "options?: RequestOptions"
+        response = endpoint[:response] ? ts_type(endpoint[:response]) : "void"
+        call = "api.#{client_verb(endpoint[:verb])}<#{response}>(#{call_args(endpoint)})"
+        "  /** #{endpoint[:verb]} #{@contract[:api_path]}#{endpoint[:path]} */\n  " \
+          "#{endpoint[:name]}: (#{args.join(", ")}) => #{call},"
+      end
+
+      # Paginated lists take an optional { page, per_page } query, combined
+      # with the action's own query schema when there is one.
+      def query_arg(endpoint)
+        return "query: #{ts_type(endpoint[:query])}" unless endpoint[:paginated]
+        return "query?: PaginationQuery" unless endpoint[:query]
+
+        "query: #{ts_type(endpoint[:query])} & PaginationQuery"
+      end
+
+      def call_args(endpoint)
+        path = endpoint[:path].gsub(/[:*](\w+)/) { "${segment(#{camel(::Regexp.last_match(1))})}" }
+        path = path.include?("${") ? "`#{path}`" : path.inspect
+        options = endpoint[:query] || endpoint[:paginated] ? "{ ...options, query }" : "options"
+        case client_verb(endpoint[:verb])
+        when "get", "delete" then "#{path}, #{options}"
+        else "#{path}, #{endpoint[:body] ? "data" : "undefined"}, #{options}"
+        end
+      end
+
+      def client_verb(verb) = { "HEAD" => "get", "OPTIONS" => "get" }.fetch(verb, verb.downcase)
+
+      def collect_refs(ref, refs)
+        return unless ref
+
+        refs << ref[:ref] if ref[:ref]
+        refs << "Paginated" if ref[:page]
+        collect_refs(ref[:array], refs) if ref[:array]
+        collect_refs(ref[:page], refs) if ref[:page]
+      end
+
+      def index_file
+        exports = @contract[:resources].map { |r| %(export { #{export_name(r)} } from "./#{file_base(r)}";) }
+        "#{header}\nexport type * from \"./types\";\n#{exports.join("\n")}\n"
+      end
+
+      def file_base(resource) = resource[:name].tr("/", "_")
+      def export_name(resource) = camel(resource[:name].tr("/", "_"))
+
+      def camel(name)
+        camel = Inflector.camelize(name)
+        camel[0].downcase + camel[1..]
+      end
+    end
+  end
+end

data/lib/gemstack/contract.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "gemstack/core"
+require "gemstack/schema"
+require "gemstack/http"
+
+module GemStack
+  # The API contract: derived from the backend (routes + controller `accepts`
+  # schemas + serializers) and emitted as TypeScript types, a typed client
+  # per resource, and OpenAPI 3.1 (ARCHITECTURE §8, DECISIONS D-023).
+  #
+  #   contract = GemStack::Contract.build(GemStack.boot!)
+  #   GemStack::Contract.write(contract, root: GemStack.root)
+  module Contract
+    class Config < Settings
+      setting :output_dir, default: "frontend/lib/api/generated"
+      setting :openapi_path, default: "openapi.json"
+      # Import path of the client runtime from generated files.
+      setting :client_import, default: "@/lib/gemstack/client"
+      # Interactive API docs at <api_path>/docs, built from the live routes (development only by default).
+      setting :docs, default: -> { GemStack.env.development? }
+    end
+
+    HEADER = "Generated by GemStack from the backend — do not edit. Run `gemstack contract` to regenerate."
+
+    class << self
+      def config = GemStack.config.contract
+
+      # Builds the contract IR from a booted application (eager-loads code).
+      def build(app)
+        app.eager_load!
+        Builder.new(routes: app.routes, api_path: app.config.http.api_path).build
+      end
+
+      # Writes TypeScript and OpenAPI files, touching only files whose content
+      # changed (so Next.js doesn't hot-reload needlessly) and removing
+      # generated files for resources that no longer exist. Returns
+      # { written: [...], removed: [...], unchanged: [...] }. dry_run: true
+      # reports what would change without touching anything (`gemstack doctor`).
+      def write(contract, root:, output_dir: config.output_dir, openapi_path: config.openapi_path, typescript: true,
+                dry_run: false)
+        dir = File.expand_path(output_dir, root)
+        files = typescript ? TypeScript.new(contract, client_import: config.client_import).files : {}
+        report = { written: [], removed: [], unchanged: [] }
+        files.each { |name, content| write_file(File.join(dir, name), content, report, dry_run: dry_run) }
+        stale = typescript ? Dir.glob(File.join(dir, "*.ts")) : []
+        stale = stale.reject { |path| files.key?(File.basename(path)) }
+        stale.each do |path|
+          next unless File.read(path).include?(HEADER)
+
+          File.delete(path) unless dry_run
+          report[:removed] << path
+        end
+        if openapi_path
+          write_file(File.expand_path(openapi_path, root), "#{JSON.pretty_generate(OpenAPI.new(contract).document)}\n",
+                     report, dry_run: dry_run)
+        end
+        report
+      end
+
+      private
+
+      def write_file(path, content, report, dry_run: false)
+        if File.exist?(path) && File.read(path) == content
+          report[:unchanged] << path
+          return
+        end
+        return report[:written] << path if dry_run
+
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, content)
+        report[:written] << path
+      end
+    end
+  end
+
+  Config.namespace(:contract, Contract::Config)
+end
+
+require_relative "contract/builder"
+require_relative "contract/typescript"
+require_relative "contract/openapi"
+require_relative "contract/docs"
+
+GemStack::Plugins.register(:contract_docs) do |app|
+  next unless app.respond_to?(:routes) && app.config.contract.docs
+
+  stack = app.config.http.middleware
+  stack.insert_before(GemStack::HTTP::Middleware::HealthCheck, GemStack::Contract::Docs, app) unless
+    stack.include?(GemStack::Contract::Docs)
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: gemstack-contract
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shoaib Malik
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gemstack-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: gemstack-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: gemstack-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+email:
+- gemstack26@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/gemstack/contract.rb
+- lib/gemstack/contract/builder.rb
+- lib/gemstack/contract/docs.rb
+- lib/gemstack/contract/docs/index.html
+- lib/gemstack/contract/openapi.rb
+- lib/gemstack/contract/typescript.rb
+homepage: https://github.com/gemstack-rb/gemstack
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/gemstack-rb/gemstack/tree/main/gems/gemstack-contract
+  changelog_uri: https://github.com/gemstack-rb/gemstack/blob/main/gems/gemstack-contract/CHANGELOG.md
+  bug_tracker_uri: https://github.com/gemstack-rb/gemstack/issues
+  documentation_uri: https://github.com/gemstack-rb/gemstack/tree/main/docs
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'GemStack contract: TypeScript types, API clients and OpenAPI from the backend'
+test_files: []