gemstack-contract 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 464059a0e986382b8df8437de79a21a93a1ec1bfe78bb7031d4f19d8d7d64096
-  data.tar.gz: 6afde6c7d3331e6d0dfca5ad6b6cbb124a1adbf21b30fc0b98277d857d9bece0
+  metadata.gz: a9e7d41b09fe8059a601c23c23530ac5c506048e0f09d731c1f2ddf6b8a58c14
+  data.tar.gz: 9b92665afcbf394cb38966cd55c2813b52d653fb8d27d948ab2500bcd30c91b5
 SHA512:
-  metadata.gz: c51286be801007a60b6b84d057c4d94156d2a266d10df8372053e0e04bf26ca354eea43304477d82d2b4f2afdeb415698b13433a47cb12495f5a10a7d1c517e2
-  data.tar.gz: 6fe47b65dc2bbb4dded311fe36dfd733f434f175baa5c0e8a25541ac100cdfda5b182b343375ca71e8ea3983bdf59027074b21995962d8e94c2c4a8bdc405b8f
+  metadata.gz: e74e8bf84277d7aaa98432101bcdbfef6ca89ef7412435c58379a0d947a9ae288a8985f8e20a7d2dcada1ce5042a035626903c354b9fd55b7748731059f2a926
+  data.tar.gz: 157597e572caf21b5f55dec855c567e69e8d6949b8d624ad0cd33cf758327a2f55111fe85b9cebec9e380f2f4c3f553d63bca30f5a13cbb929df1827f67fe0e6

data/CHANGELOG.md

@@ -1,29 +1,5 @@
 # Changelog
 
-## 0.2.5
+## 0.3.0
 
-See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
-
-## 0.2.4
-
-See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
-
-## 0.2.3
-
-See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
-
-## 0.2.2
-
-See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
-
-## 0.2.1
-
-See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
-
-## 0.2.0
-
-See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
-
-## 0.1.0
-
-First release. See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
+Merged into the gemstack gem; this version is a transition shim. See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).

data/README.md

@@ -1,23 +1,13 @@
 # gemstack-contract
 
-GemStack contract: TypeScript types, API clients and OpenAPI from the backend.
+**Merged into [`gemstack`](https://rubygems.org/gems/gemstack) in GemStack 0.3.0.**
 
-Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby API framework for Next.js
-applications by [Adware Technologies](https://www.adwaretech.com). All GemStack gems are developed together in that repository and released with the same
-version.
+This version is a transition shim: it depends on `gemstack` and loads `gemstack/contract`, so
+Gemfiles that still list `gemstack-contract` keep working. To finish upgrading, remove `gem "gemstack-contract"`
+from your Gemfile (it's loaded by `require "gemstack"`).
 
-## 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`).
+GemStack is a modular Ruby API framework for Next.js applications by
+[Adware Technologies](https://www.adwaretech.com) — [gemstack-rb/gemstack](https://github.com/gemstack-rb/gemstack).
 
 ## License
 

data/lib/gemstack-contract.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# gemstack-contract is part of the gemstack gem since 0.3.0. This shim keeps Gemfiles
+# that still list gemstack-contract working; remove the line from your Gemfile.
+require "gemstack/contract"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gemstack-contract
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.0
 platform: ruby
 authors:
 - Adware Technologies
@@ -11,47 +11,28 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: gemstack-core
+  name: gemstack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.5
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: 0.2.5
-- !ruby/object:Gem::Dependency
-  name: gemstack-http
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
+        version: 0.3.0
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 0.2.5
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.5
-- !ruby/object:Gem::Dependency
-  name: gemstack-schema
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: 0.2.5
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
+        version: 0.3.0
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 0.2.5
+        version: '1.0'
+description: Since GemStack 0.3.0, gemstack-contract is part of the gemstack gem.
+  This version only depends on gemstack and loads gemstack/contract, so Gemfiles that
+  still list it keep working.
 email:
 - gemstack26@gmail.com
 executables: []
@@ -61,21 +42,18 @@ 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
+- lib/gemstack-contract.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
+  source_code_uri: https://github.com/gemstack-rb/gemstack
+  changelog_uri: https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/gemstack-rb/gemstack/issues
   documentation_uri: https://github.com/gemstack-rb/gemstack/tree/main/docs
+post_install_message: gemstack-contract is now part of the gemstack gem. Remove `gem
+  "gemstack-contract"` from your Gemfile (it's loaded by `require "gemstack"`).
 rdoc_options: []
 require_paths:
 - lib
@@ -92,5 +70,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.20
 specification_version: 4
-summary: 'GemStack contract: TypeScript types, API clients and OpenAPI from the backend'
+summary: Merged into the gemstack gem — remove gemstack-contract from your Gemfile
 test_files: []

data/lib/gemstack/contract/builder.rb

@@ -1,168 +0,0 @@
-# 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

@@ -1,264 +0,0 @@
-<!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

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module GemStack
-  module Contract
-    # Development API docs:
-    #   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

@@ -1,123 +0,0 @@
-# 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

@@ -1,162 +0,0 @@
-# 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?
-        # No types yet (a new app): still a module, or `export type * from "./types"` fails to compile.
-        body << "export {};\n" if body.empty?
-        "#{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

@@ -1,93 +0,0 @@
-# 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).
-  #
-  #   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