haveapi 0.29.9 → 0.30.0

data/lib/haveapi/server.rb

@@ -3,6 +3,7 @@ require 'redcarpet'
 require 'tilt'
 require 'cgi'
 require 'haveapi/hooks'
+require 'haveapi/documentation_clients'
 
 module HaveAPI
   class Server
@@ -250,6 +251,29 @@ module HaveAPI
         "#{scheme}://#{request.env['HTTP_HOST']}"
       end
 
+      def documentation_context(client = nil, **changes)
+        @documentation_context ||= HaveAPI::ClientExample::Context.new(
+          version: @v, host:, base_url: "#{base_url}#{root.end_with?('/') ? root : "#{root}/"}",
+          version_url: "#{base_url}#{root.end_with?('/') ? root : "#{root}/"}v#{@v}/",
+          description: @help
+        )
+        profile = if client
+                    settings.api_server.documentation_client_profiles(@v)[client.code&.to_sym]
+                  end
+        @documentation_context.with(profile:, **changes)
+      end
+
+      def documentation_clients
+        HaveAPI::ClientExample.clients.select { |client| client.available?(documentation_context(client)) }
+      end
+
+      def documentation_panels(kind, auth_method: nil, auth_description: nil, **changes)
+        documentation_clients.filter_map do |client|
+          result = client.render(kind, context: documentation_context(client, **changes), auth_method:, auth_description:)
+          [client, result] if result
+        end
+      end
+
       def host
         request.env['HTTP_HOST'].split(':').first
       end
@@ -312,11 +336,20 @@ module HaveAPI
       @extensions = []
       @action_state_auth = :backend
       @validation_error_http_status = nil
+      @documentation_clients = HaveAPI::ClientExample::Profiles.new
       @default_locale = :en
       self.available_locales = HaveAPI::I18n.available_locales
       self.locale_header = 'Accept-Language'
     end
 
+    def documentation_clients(version, **profiles)
+      @documentation_clients.register(version, **profiles)
+    end
+
+    def documentation_client_profiles(version)
+      @documentation_clients.for_version(version)
+    end
+
     def available_locales=(locales)
       @available_locales = Array(locales)
       allow_i18n_locales(@available_locales)
@@ -407,6 +440,7 @@ module HaveAPI
     # All routes are mounted under prefix `path`.
     # If no default version is set, the last included version is used.
     def mount(prefix = '/')
+      @documentation_clients.mount(@versions)
       @root = prefix
 
       @sinatra = Sinatra.new do

data/lib/haveapi/version.rb

@@ -1,4 +1,4 @@
 module HaveAPI
   PROTOCOL_VERSION = '2.0'.freeze
-  VERSION = '0.29.9'.freeze
+  VERSION = '0.30.0'.freeze
 end

data/lib/haveapi/views/main_layout.erb

@@ -54,6 +54,17 @@
     .tab-hidden {
       display: none;
     }
+    .nav-tabs {
+      display: flex;
+      flex-wrap: wrap;
+    }
+    .nav-tabs > li {
+      float: none;
+    }
+    .nav-tabs a:focus {
+      outline: 2px solid #337ab7;
+      outline-offset: -2px;
+    }
     pre {
       overflow: auto;
     }

data/lib/haveapi/views/version_page/auth_body.erb

@@ -32,9 +32,9 @@
 <div id="<%= baseid %>-tabbar"></div>
 
 <div id="<%= baseid %>-examples">
-  <% HaveAPI::ClientExample.clients.each_with_index do |client, i| %>
-    <div id="<%= "#{baseid}-#{i}" %>">
-      <%= erb :"version_page/client_auth", locals: {client: client, method: name, desc: info} %>
+  <% documentation_panels(:auth, auth_method: name, auth_description: info).each do |client, result| %>
+    <div id="<%= escape_html("#{baseid}-#{client.id}") %>">
+      <%= erb :"version_page/client_auth", locals: {client: client, result: result} %>
     </div>
   <% end %>
 </div>

data/lib/haveapi/views/version_page/client_auth.erb

@@ -1,2 +1,2 @@
-<h4><%= client.label %></h4>
-<pre><code class="<%= client.code %>"><%= escape_html(client.auth(host, base_url, api_version, method, desc)) %></code></pre>
+<h4><%= escape_html(client.label) %></h4>
+<%= erb :"version_page/client_result", locals: {client: client, result: result} %>

data/lib/haveapi/views/version_page/client_example.erb

@@ -1,11 +1,2 @@
-<h6><%= client.label %></h6>
-<% sample = client.new(host, base_url, api_version, r_name, resource, a_name, action) %>
-<% if sample.respond_to?(:example) %>
-  <pre><code class="<%= client.code %>"><%= escape_html(sample.example(example)) %></code></pre>
-
-<% else %>
-  <h6>Request</h6>
-  <pre><code class="<%= client.code %>"><%= escape_html(sample.request(example)) %></code></pre>
-  <h6>Response</h6>
-  <pre><code class="<%= client.code %>"><%= escape_html(sample.response(example)) %></code></pre>
-<% end %>
+<h6><%= escape_html(client.label) %></h6>
+<%= erb :"version_page/client_result", locals: {client: client, result: result} %>

data/lib/haveapi/views/version_page/client_init.erb

@@ -1,2 +1,2 @@
-<h4><%= client.label %></h4>
-<pre><code class="<%= client.code %>"><%= escape_html(client.init(host, base_url, api_version)) %></code></pre>
+<h4><%= escape_html(client.label) %></h4>
+<%= erb :"version_page/client_result", locals: {client: client, result: result} %>

data/lib/haveapi/views/version_page/client_result.erb

@@ -0,0 +1,5 @@
+<% if result[:status] == :limitation %>
+  <p class="client-limitation"><%= escape_html(result[:reason]) %></p>
+<% else %>
+  <pre><code class="<%= escape_html(client.code) %>"><%= escape_html(result[:code]) %></code></pre>
+<% end %>

data/lib/haveapi/views/version_page/resource_body.erb

@@ -104,16 +104,12 @@
               <div id="<%= "#{baseid}-tabbar" %>"></div>
 
               <div id="<%= "#{baseid}-examples" %>">
-                <% HaveAPI::ClientExample.clients.each_with_index do |client, j| %>
-                  <div id="<%= "#{baseid}-#{j}" %>">
+                <% documentation_panels(:example, resource_path: resource_path, resource: resource_info, action_name: action, action: info, sample: example).each do |client, result| %>
+                  <div id="<%= escape_html("#{baseid}-#{client.id}") %>">
                     <%=
                       erb :"version_page/client_example", locals: {
                         client: client,
-                        r_name: resource_path,
-                        resource: resource_info,
-                        a_name: action,
-                        action: info,
-                        example: example,
+                        result: result,
                       }
                     %>
                   </div>

data/lib/haveapi/views/version_page.erb

@@ -16,19 +16,23 @@
 </p>
 
 <ul>
-  <li><a href="https://github.com/vpsfreecz/haveapi-client" target="_blank">Ruby library and CLI</a></li>
-  <li><a href="https://github.com/vpsfreecz/haveapi-client-js" target="_blank">JavaScript</a></li>
-  <li><a href="https://github.com/vpsfreecz/haveapi-client-php" target="_blank">PHP</a></li>
+  <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/ruby" target="_blank" rel="noopener">Ruby library and CLI</a></li>
+  <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/js" target="_blank" rel="noopener">JavaScript and TypeScript (callback and async)</a></li>
+  <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/python" target="_blank" rel="noopener">Python (sync and async)</a></li>
+  <% settings.api_server.documentation_client_profiles(@v).each do |language, profile| %>
+    <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/<%= escape_html(language) %>" target="_blank" rel="noopener"><%= language == :go ? 'Go' : 'Rust (async and blocking)' %></a>: <code><%= escape_html(profile.package_name) %></code> <%= escape_html(profile.package_version) %></li>
+  <% end %>
+  <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/php" target="_blank" rel="noopener">PHP</a></li>
   <li>
     <a href="https://github.com/vpsfreecz/haveapi-webui" target="_blank">Generic web interface</a>
     (<a href="https://webui.haveapi.org/v<%= version %>/#<%= urlescape(base_url) %>" target="_blank">connect to this API</a>)
   </li>
-  <li><a href="https://github.com/vpsfreecz/haveapi-fs" target="_blank">FUSE-based file system</a></li>
 </ul>
 
 <p>
-  The code examples found on this page are for HaveAPI v<%= version %>, so be sure
-  to use clients of the same version.
+  These examples target API v<%= escape_html(@v) %>. The framework and dynamic
+  clients share HaveAPI package versions. Generated Go and Rust SDKs use their
+  own package versions and a saved description of the API.
 </p>
 
 <h2>Initialization</h2>
@@ -36,9 +40,9 @@
 <div id="init-tabbar"></div>
 
 <div id="init-examples">
-  <% HaveAPI::ClientExample.clients.each_with_index do |client, i| %>
-    <div id="<%= "init-#{i}" %>">
-      <%= erb :"version_page/client_init", locals: {client: client} %>
+  <% documentation_panels(:init).each do |client, result| %>
+    <div id="<%= escape_html("init-#{client.id}") %>">
+      <%= erb :"version_page/client_init", locals: {client: client, result: result} %>
     </div>
   <% end %>
 </div>

data/spec/client_examples/assets/highlighter_test.cjs

@@ -0,0 +1,26 @@
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+const root = path.resolve(__dirname, '../../../lib/haveapi/public/js');
+const context = vm.createContext({});
+vm.runInContext(fs.readFileSync(path.join(root, 'highlight.pack.js'), 'utf8'), context);
+for (const language of ['bash', 'http', 'xml', 'php', 'json', 'javascript', 'ruby', 'go', 'rust', 'python', 'typescript']) {
+  assert(context.hljs.getLanguage(language), language);
+  const result = context.hljs.highlight('const text = "<script>";', { language, ignoreIllegals: true });
+  assert(!result.value.includes('<script>'), language);
+}
+assert.equal(context.hljs.versionString, '11.12.0');
+const messages = [];
+context.importScripts = name => assert.equal(name, 'highlight.pack.js');
+context.postMessage = value => messages.push(value);
+vm.runInContext(fs.readFileSync(path.join(root, 'highlighter.js'), 'utf8'), context);
+context.onmessage({ data: { language: 'unknown', code: '<script>&"\'' } });
+assert.equal(messages.pop(), '&lt;script&gt;&amp;&quot;&#39;');
+context.onmessage({ data: { language: 'go', code: 'package main' } });
+assert(messages.pop().includes('hljs-keyword'));
+context.hljs.highlight = () => { throw new Error('fixture failure'); };
+context.onmessage({ data: { language: 'rust', code: '<unsafe>' } });
+assert.equal(messages.pop(), '&lt;unsafe&gt;');
+console.log('All bundled languages and safe worker fallbacks passed');

data/spec/client_examples/assets/tabs_test.cjs

@@ -0,0 +1,54 @@
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+class Element {
+  constructor(tag, document) {
+    this.tagName = tag.toUpperCase(); this.document = document;
+    this.children = []; this.attributes = {}; this.listeners = {};
+    const classes = new Set();
+    this.classList = { add: (...values) => values.forEach(value => classes.add(value)), remove: value => classes.delete(value), contains: value => classes.has(value) };
+    this.textContent = '';
+  }
+  setAttribute(name, value) { this.attributes[name] = String(value); }
+  getAttribute(name) { return this.attributes[name]; }
+  appendChild(child) { child.parentElement = this; this.children.push(child); return child; }
+  removeChild(child) { this.children.splice(this.children.indexOf(child), 1); }
+  addEventListener(name, handler) { this.listeners[name] = handler; }
+  querySelectorAll(selector) {
+    const matches = element => selector === '[role="tab"]' ? element.getAttribute('role') === 'tab' : selector[0] === '.' ? element.classList.contains(selector.slice(1)) : element.tagName === selector.toUpperCase();
+    return this.children.flatMap(child => [...(matches(child) ? [child] : []), ...child.querySelectorAll(selector)]);
+  }
+  querySelector(selector) { return this.querySelectorAll(selector)[0]; }
+  getElementsByTagName(name) { return this.querySelectorAll(name); }
+  focus() { this.document.activeElement = this; }
+}
+const document = { createElement: tag => new Element(tag, document), createTextNode: value => Object.assign(new Element('#text', document), { textContent: value }) };
+const page = document.createElement('main');
+document.getElementById = id => [page, ...page.querySelectorAll('div')].find(element => element.id === id);
+const tabs = page.appendChild(document.createElement('div')); tabs.id = 'examples';
+const bar = page.appendChild(document.createElement('div')); bar.id = 'bar';
+for (let index = 0; index < 3; index++) {
+  const panel = tabs.appendChild(document.createElement('div')); panel.id = 'example-' + index;
+  const heading = panel.appendChild(document.createElement('h4')); heading.textContent = 'Language ' + index;
+}
+const context = vm.createContext({ window: {}, document, history: { pushState() {} }, location: { hash: '' } });
+vm.runInContext(fs.readFileSync(path.resolve(__dirname, '../../../lib/haveapi/public/js/nojs-tabs.js'), 'utf8'), context);
+context.window.nojsTabs({ tabs, tabBar: bar, titleSelector: 'h4', hiddenClass: 'tab-hidden', activeClass: 'active' });
+const links = bar.querySelectorAll('[role="tab"]');
+assert.equal(links.length, 3);
+assert.equal(links[0].getAttribute('aria-selected'), 'true');
+assert.equal(links[1].getAttribute('tabindex'), '-1');
+for (const link of links) assert(!link.parentElement.classList.contains('tab-hidden'));
+const key = (index, value) => links[index].listeners.keydown({ key: value, preventDefault() {} });
+key(0, 'ArrowRight');
+assert.equal(document.activeElement, links[1]);
+assert.equal(tabs.children[1].getAttribute('aria-hidden'), 'false');
+assert.equal(tabs.children[0].getAttribute('aria-hidden'), 'true');
+key(1, 'End'); assert.equal(document.activeElement, links[2]);
+key(2, 'ArrowRight'); assert.equal(document.activeElement, links[0]);
+key(0, 'ArrowLeft'); assert.equal(document.activeElement, links[2]);
+key(2, 'Home'); assert.equal(document.activeElement, links[0]);
+context.window.nojsTabs({ tabs: document.createElement('div'), tabBar: document.createElement('div') });
+console.log('Keyboard tabs, accessible state and empty panels passed');

data/spec/client_examples/context_spec.rb

@@ -0,0 +1,68 @@
+require 'spec_helper'
+
+describe HaveAPI::ClientExample::Context do
+  let(:description) { { resources: { widget: { actions: {} } } } }
+  let(:context) do
+    described_class.new(version: '1', host: 'api.test', base_url: 'https://api.test/mount/',
+                        version_url: 'https://api.test/mount/v1/', description:)
+  end
+
+  it 'copies and freezes request data without freezing the source description' do
+    expect(context.description).to be_frozen
+    expect(context.description[:resources]).to be_frozen
+    expect(description[:resources]).not_to be_frozen
+    description[:resources][:secret] = {}
+    expect(context.description[:resources]).not_to have_key(:secret)
+  end
+
+  it 'keeps per-example state independent and leaves the original context intact' do
+    data = { request: { name: 'safe' } }
+    child = context.with(resource_path: ['widget'], action_name: 'show', sample: data)
+    data[:request][:name].replace('changed')
+    expect(child.sample[:request][:name]).to eq('safe')
+    expect(context.sample).to be_nil
+    expect(child.resource_path).to eq(['widget'])
+    expect(child).to be_frozen
+  end
+
+  it 'preserves legacy initialization constructors and wraps plain source' do
+    renderer = Class.new(HaveAPI::ClientExample) do
+      def initialize(host, base_url, version)
+        raise ArgumentError, 'expected API version 1' unless version == '1'
+
+        super
+      end
+
+      def init
+        "#{base_url}v#{version}/"
+      end
+    end
+    result = renderer.render(:init, context:)
+    expect(result).to eq(status: :code, code: 'https://api.test/mount/v1/')
+    expect(result).to be_frozen
+    expect(result[:code]).to be_frozen
+  end
+
+  it 'preserves request/response renderers and nil legacy authentication' do
+    renderer = Class.new(HaveAPI::ClientExample) do
+      def request(_sample)
+        'request'
+      end
+
+      def response(_sample)
+        'response'
+      end
+    end
+    expect(renderer.render(:example, context:)).to eq(status: :code, code: "request\n\nresponse")
+    expect(renderer.render(:auth, context:, auth_method: :basic, auth_description: {})).to be_nil
+  end
+
+  it 'wraps a limitation without allowing HTML or an invalid result contract' do
+    renderer = Class.new(HaveAPI::ClientExample) do
+      def init
+        { status: :limitation, reason: 'Cannot render <this>' }
+      end
+    end
+    expect(renderer.render(:init, context:)).to eq(status: :limitation, reason: 'Cannot render <this>')
+  end
+end

data/spec/client_examples/dynamic_acceptance.md

@@ -0,0 +1,83 @@
+# Dynamic example verification
+
+The six JavaScript, TypeScript and Python variants are ordinary server renderers.
+They require no generated-SDK profile. Their examples use exact public lookups,
+mounted base URLs and explicit API versions. Credentials come from environment
+variables in the example process; no example executes in a documentation request.
+
+Run the focused checks in the prepared top-level Nix environment:
+
+```sh
+cd servers/ruby
+bundle exec rspec spec/client_examples/dynamic_js_spec.rb \
+  spec/client_examples/dynamic_python_spec.rb \
+  spec/client_examples/dynamic_metadata_spec.rb \
+  spec/client_examples/dynamic_acceptance_spec.rb
+```
+
+The unit checks parse the actual generated source and compile both TypeScript
+variants against emitted public declarations. Prepare the JavaScript build and
+its declared development dependencies first. The Rack fixture check renders real
+mounted HTML and verifies the extraction boundary and request/result fixtures;
+it opens no listening socket and does not install packages.
+
+`make test-documentation-python` runs the supplemental native Python request
+builder checks in `test_support/dynamic_protocol_spec.rb` and
+`test_support/dynamic_python_login_spec.rb`. Prepare the locked Python
+component environment with `make release-deps` first; the check uses
+`clients/python/.venv/bin/python` and imports the checkout protocol implementation.
+It cross-checks GET limitations, JSON methods and required input metadata without
+transport. It installs nothing and is separate from ordinary Ruby spec discovery.
+The focused JavaScript specs cross-check the built callback and async query/body
+serializers with a mocked transport. The full `make test` includes both checks.
+
+Python token-login examples read required request fields from JSON values in
+`HAVEAPI_AUTH_*` environment variables. For example, an API that requires
+`lifetime` reads `HAVEAPI_AUTH_lifetime`. The examples omit optional lifetime and
+interval fields. The acceptance fixture explicitly chooses `"fixed"` from its
+advertised lifetime values and omits optional interval. The Python challenge
+object supplies the continuation token.
+
+`dynamic_acceptance.rb` checks the installed packages. Supply the built npm and
+Python artifacts, the compiler and Node declaration directories, and a directory
+for evidence. Paths are absolute because the harness changes to an
+isolated consumer:
+
+```sh
+cd servers/ruby
+bundle exec ruby spec/client_examples/dynamic_acceptance.rb \
+  --npm-artifact /absolute/path/dist/haveapi-client-0.30.0.tgz \
+  --python-artifact /absolute/path/dist/haveapi_client-0.30.0-py3-none-any.whl \
+  --typescript /absolute/path/clients/js/node_modules/typescript/bin/tsc \
+  --node-types /absolute/path/clients/js/node_modules/@types \
+  --output /absolute/path/session/dynamic-acceptance-wheel
+```
+
+Repeat with the retained Python sdist and a separate evidence directory. Replace
+artifact versions with the release being tested. The test installs the supplied
+packages without checkout imports, starts its disposable mounted fixture, extracts
+the code from the served HTML, compiles TypeScript with strict checking and runs
+the snippets with the installed clients. It checks discovery, Basic/existing
+token/OAuth credentials, a deterministic token challenge, success/failure and
+request receipts preserving exact names, path order, Unicode, nested Custom
+values, omission, null, empty strings, false and zero. Output and extracted
+programs remain in the evidence directory. The fixture stops and disposable
+consumer is removed when the operation exits.
+
+Each snippet's output is saved before completion checks, including nonzero
+exits. Token panels have separate `example-N-challenge.log` files for the login
+flow without an existing token. `fixture.log` records request method, path and
+HTTP status; the trace excludes headers, query strings and request bodies.
+
+JavaScript list input and nested GET/OPTIONS query values produce a visible
+limitation; HEAD input retains the client's JSON body behavior. Python GET
+examples use a conservative flat-scalar subset with nonempty, bracket-free
+parameter names and namespaces. Custom values must be strings or nullable nulls;
+structured GET values produce a limitation even when the client supports them.
+Python POST, PUT and DELETE retain supported object/list JSON input; unsupported
+methods produce a limitation. Required global or object input metadata also
+produces a limitation because the sample format has no metadata input channel.
+Optional metadata needs no invented values. Prose-only and incomplete samples do
+not become fabricated calls. Callback examples print the raw response; async
+examples use the actual invocation receipt. Operation waiting is shown only through the client's existing
+API, and a timeout is not a cancellation of the server operation.

data/spec/client_examples/dynamic_acceptance.rb

@@ -0,0 +1,151 @@
+# Run after committed-deliverable review, with built npm and Python artifacts.
+# The only code executed below comes from the real server's rendered HTML.
+require 'cgi'
+require 'fileutils'
+require 'json'
+require 'net/http'
+require 'open3'
+require 'tmpdir'
+require 'timeout'
+require_relative '../../test_support/dynamic_documentation_api'
+
+module DynamicDocumentationAcceptance
+  VARIANTS = %w[javascript-callback javascript-async typescript-callback typescript-async python-sync python-async].freeze
+
+  def self.run!(*command, chdir:, env: {}, log_path: nil)
+    output, status = Open3.capture2e(env, *command, chdir:)
+    File.write(log_path, output) if log_path
+    raise "#{command.first} failed (#{status.exitstatus}):\n#{output}" unless status.success?
+
+    output
+  end
+
+  def self.request(url)
+    uri = URI(url)
+    response = Net::HTTP.start(uri.host, uri.port, open_timeout: 10, read_timeout: 30) { |http| http.get(uri.request_uri) }
+    raise "Fixture HTTP #{response.code}: #{response.body[0, 200]}" unless response.is_a?(Net::HTTPSuccess)
+
+    response.body
+  end
+
+  def self.extract(html)
+    html.scan(%r{<div id="([^"]+)">\s*<h[46]>[^<]*</h[46]>\s*<pre><code class="([^"]+)">(.*?)</code></pre>}m).filter_map do |id, language, escaped|
+      variant = VARIANTS.find { |name| id.end_with?("-#{name}") }
+      next unless variant
+
+      { id:, variant:, language:, source: CGI.unescapeHTML(escaped) }
+    end
+  end
+
+  def self.run(npm_artifact:, python_artifact:, typescript:, node_types:, output:)
+    root = File.expand_path('../../../..', __dir__)
+    FileUtils.mkdir_p(output)
+    tools = { typescript: File.expand_path(typescript), node_types: File.expand_path(node_types) }
+    npm_artifact = File.expand_path(npm_artifact)
+    python_artifact = File.expand_path(python_artifact)
+    Dir.mktmpdir('haveapi-dynamic-acceptance-') do |consumer|
+      File.write(File.join(consumer, 'package.json'), JSON.generate({ private: true, type: 'module' }))
+      run!('npm', 'install', '--ignore-scripts', '--no-audit', '--no-fund', npm_artifact, chdir: consumer,
+                                                                                          env: { 'NODE_PATH' => nil })
+      run!('uv', 'venv', '--python', '3.11', 'venv', chdir: consumer)
+      python = File.join(consumer, 'venv/bin/python')
+      run!('uv', 'pip', 'install', '--python', python, python_artifact, chdir: consumer)
+      server_script = File.join(root, 'servers/ruby/test_support/dynamic_documentation_api.rb')
+      Open3.popen2e('ruby', server_script, chdir: File.join(root, 'servers/ruby')) do |stdin, server_output, wait|
+        stdin.close
+        reader = nil
+        begin
+          base = Timeout.timeout(30) do
+            loop do
+              line = server_output.gets
+              raise 'Documentation fixture exited before readiness' unless line
+              break line.split.last if line.start_with?('DYNAMIC_DOCUMENTATION_READY ')
+            end
+          end
+          reader = Thread.new { File.write(File.join(output, 'fixture.log'), server_output.read) }
+          html = request("#{base}/mount/v2/")
+          File.write(File.join(output, 'documentation.html'), html)
+          panels = extract(html)
+          raise 'No actual HTML code panels extracted' if panels.empty?
+
+          VARIANTS.each do |variant|
+            selected = panels.select { |panel| panel[:variant] == variant }
+            raise "Incomplete rendered coverage for #{variant}" unless selected.length >= 4 &&
+                                                                       selected.any? { |panel| panel[:id].start_with?('init-') } &&
+                                                                       selected.any? { |panel| panel[:id].start_with?('auth-basic-') } &&
+                                                                       selected.count { |panel| panel[:id].start_with?('example-') } >= 2
+          end
+          panels.each_with_index do |panel, index|
+            extension = { 'typescript' => '.ts', 'javascript' => '.mjs', 'python' => '.py' }.fetch(panel[:language])
+            name = "example-#{index}#{extension}"
+            path = File.join(consumer, name)
+            File.write(path, panel[:source])
+            File.write(File.join(output, name), panel[:source])
+            env = { 'NODE_PATH' => nil, 'PYTHONPATH' => nil, 'PYTHONHOME' => nil,
+                    'HAVEAPI_USER' => 'fixture-user', 'HAVEAPI_PASSWORD' => 'fixture-password',
+                    'HAVEAPI_TOKEN' => 'fixture-token', 'HAVEAPI_ACCESS_TOKEN' => 'fixture-access-token',
+                    'HAVEAPI_AUTH_user' => JSON.generate('fixture-user'),
+                    'HAVEAPI_AUTH_password' => JSON.generate('fixture-password'),
+                    'HAVEAPI_AUTH_lifetime' => JSON.generate('fixed'),
+                    'HAVEAPI_AUTH_scope' => JSON.generate('all'), 'HAVEAPI_CHALLENGE_code' => JSON.generate('123456') }
+            if extension == '.ts'
+              config = {
+                compilerOptions: { target: 'ES2022', module: 'NodeNext', moduleResolution: 'NodeNext', strict: true,
+                                   types: ['node'], typeRoots: [tools[:node_types]], outDir: 'compiled', skipLibCheck: false },
+                files: [name]
+              }
+              File.write(File.join(consumer, 'tsconfig.json'), JSON.generate(config))
+              file_list = run!('node', tools[:typescript], '-p', 'tsconfig.json', '--listFiles', chdir: consumer)
+              raise 'Checkout HaveAPI declarations leaked into installed-package check' if file_list.lines.any? do |line|
+                line.include?('/clients/js/src/') || (line.include?('haveapi.d.ts') && !line.start_with?(consumer))
+              end
+
+              path = File.join(consumer, 'compiled', "example-#{index}.js")
+            end
+            before = JSON.parse(request("#{base}/__acceptance_receipts"))
+            command = panel[:language] == 'python' ? [python, path] : ['node', path]
+            result = run!(*command, chdir: consumer, env:, log_path: File.join(output, "example-#{index}.log"))
+            if panel[:id].start_with?('auth-token-')
+              challenge_result = run!(*command, chdir: consumer, env: env.merge('HAVEAPI_TOKEN' => nil),
+                                                log_path: File.join(output, "example-#{index}-challenge.log"))
+              raise "Token challenge did not complete: #{panel[:id]}\n#{challenge_result}" unless challenge_result.include?('Authenticated')
+            end
+            after = JSON.parse(request("#{base}/__acceptance_receipts"))
+            if panel[:id].start_with?('example-')
+              raise "Rendered action did not execute: #{panel[:id]}\n#{result}" unless after.length == before.length + 1
+
+              receipt = after.last
+              expected = { 'name' => '', 'enabled' => false, 'nullable' => nil, 'payload' => DynamicDocumentationAPI::PAYLOAD }
+              raise "Changed request values: #{receipt.inspect}" unless receipt['input'].except('count') == expected
+              raise 'Changed mounted path arguments' unless receipt['path'].map(&:to_s) == ['7', 'name with space']
+
+              marker = receipt['input']['count'] < 0 ? 'DOC_FAILURE' : 'DOC_SUCCESS'
+              raise "Wrong result/error handling: #{panel[:id]}\n#{result}" unless result.include?(marker)
+            else
+              marker = panel[:id].start_with?('init-') ? 'Discovery complete' : 'Authenticated'
+              raise "Discovery/authentication did not complete: #{panel[:id]}\n#{result}" unless result.include?(marker)
+            end
+          end
+          File.write(File.join(output, 'result.json'), JSON.pretty_generate({ panels: panels.length, variants: VARIANTS, status: 'passed' }))
+        ensure
+          Process.kill('TERM', wait.pid) if wait.alive?
+          wait.value
+          reader&.join
+        end
+      end
+    end
+  end
+end
+
+if $0 == __FILE__
+  require 'optparse'
+  options = {}
+  OptionParser.new do |parser|
+    %i[npm_artifact python_artifact typescript node_types output].each do |key|
+      parser.on("--#{key.to_s.tr('_', '-')} PATH") { |path| options[key] = path }
+    end
+  end.parse!
+  raise 'Supply --npm-artifact, --python-artifact, --typescript, --node-types and --output' unless options.length == 5
+
+  DynamicDocumentationAcceptance.run(**options)
+end