total-recall-brain 3.31.0 → 3.32.0

package/src/core/app-deploy/design-tokens.mjs

@@ -2,15 +2,33 @@
  * Total Recall — Design Token Parser & Validator
  *
  * Implements Phase 2B of CAPABILITY_DEPLOYMENT_PLUGINS:
- * - Parses `DESIGN.md` YAML frontmatter into canonical design tokens
- * - Resolves token references and compiles standard CSS variables (`:root { ... }`)
- * - Validates plugin UI elements to reject hardcoded brand values and enforce design token compliance
+ * - Parses `DESIGN.md` YAML frontmatter (google-labs-code/design.md format) into tokens
+ * - Resolves `{group.token}` references and compiles CSS custom properties (`:root { ... }`)
+ * - Validates plugin UI source: no hardcoded colors, and only declared token variables
+ *
+ * Variable names: colors → `--color-<name>`, spacing → `--spacing-<name>`,
+ * rounded → `--radius-<name>`, typography style props → `--typography-<style>-<prop>`,
+ * a `typography.fontFamily` map of families → `--font-family-<name>`, and primitive
+ * component props → `--component-<name>-<prop>`. Names are kebab-cased.
  */
 
 import fs from 'node:fs';
-import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+
+export class DesignTokenError extends Error {
+  constructor(errors) {
+    super(`Invalid design tokens:\n- ${errors.join('\n- ')}`);
+    this.name = 'DesignTokenError';
+    this.errors = errors;
+  }
+}
+
+const TOKEN_KEY = /^[A-Za-z0-9_-]+$/;
+// A value lands inside a generated stylesheet: nothing that can close the
+// declaration, the rule, or an enclosing <style> element.
+const UNSAFE_VALUE = /[;{}<>\\\r\n]/;
+const TYPOGRAPHY_PROPS = ['fontFamily', 'fontSize', 'fontWeight', 'lineHeight', 'letterSpacing', 'fontFeature', 'fontVariation'];
 
-// Matches kebab-case transformation
 function toKebabCase(str) {
   return str
     .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
@@ -18,55 +36,28 @@ function toKebabCase(str) {
     .toLowerCase();
 }
 
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+
 /**
  * Extracts YAML frontmatter from a markdown string.
  * @param {string} content
  * @returns {object}
  */
 export function extractFrontmatter(content) {
-  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  const match = String(content).match(/^?---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/);
   if (!match) return {};
-  const raw = match[1];
-
-  // Lightweight YAML parser for nested token structures
-  const result = {};
-  const lines = raw.split('\n');
-  const stack = [{ obj: result, indent: -1 }];
-
-  for (const line of lines) {
-    if (!line.trim() || line.trim().startsWith('#')) continue;
-    const indent = line.search(/\S/);
-    const trimmed = line.trim();
-    const colonIdx = trimmed.indexOf(':');
-    if (colonIdx === -1) continue;
-
-    const key = trimmed.slice(0, colonIdx).trim();
-    let val = trimmed.slice(colonIdx + 1).trim();
-
-    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
-      stack.pop();
-    }
-    const current = stack[stack.length - 1].obj;
-
-    if (val === '') {
-      current[key] = {};
-      stack.push({ obj: current[key], indent });
-    } else {
-      if (
-        (val.startsWith('"') && val.endsWith('"')) ||
-        (val.startsWith("'") && val.endsWith("'"))
-      ) {
-        val = val.slice(1, -1);
-      }
-      current[key] = val;
-    }
+  let parsed;
+  try {
+    parsed = parseYaml(match[1]);
+  } catch (err) {
+    throw new DesignTokenError([`frontmatter is not valid YAML: ${err.message}`]);
   }
-
-  return result;
+  return isPlainObject(parsed) ? parsed : {};
 }
 
 /**
  * Resolves token references like "{colors.primary}" within values.
+ * An unresolvable or circular reference is left as written.
  * @param {object} tokens
  * @returns {object}
  */
@@ -80,25 +71,28 @@ export function resolveTokenReferences(tokens) {
     return curr;
   }
 
-  function resolveVal(val) {
+  function resolveVal(val, seen) {
     if (typeof val !== 'string') return val;
+    const whole = val.match(/^\{([a-zA-Z0-9_.-]+)\}$/);
+    if (whole && !seen.has(whole[1])) {
+      const target = getNested(tokens, whole[1].split('.'));
+      // A whole-value reference may point at a composite (e.g. a typography style).
+      if (isPlainObject(target)) return walk(target, new Set([...seen, whole[1]]));
+    }
     return val.replace(/\{([a-zA-Z0-9_.-]+)\}/g, (match, tokenPath) => {
-      const parts = tokenPath.split('.');
-      const resolved = getNested(tokens, parts);
-      return resolved !== undefined ? resolveVal(resolved) : match;
+      if (seen.has(tokenPath)) return match;
+      const resolved = getNested(tokens, tokenPath.split('.'));
+      if (typeof resolved === 'string' || typeof resolved === 'number') {
+        return String(resolveVal(resolved, new Set([...seen, tokenPath])));
+      }
+      return match;
     });
   }
 
-  function walk(node) {
-    if (typeof node !== 'object' || node === null) return resolveVal(node);
+  function walk(node, seen = new Set()) {
+    if (!isPlainObject(node)) return resolveVal(node, seen);
     const out = {};
-    for (const [k, v] of Object.entries(node)) {
-      if (typeof v === 'object' && v !== null) {
-        out[k] = walk(v);
-      } else {
-        out[k] = resolveVal(v);
-      }
-    }
+    for (const [k, v] of Object.entries(node)) out[k] = walk(v, seen);
     return out;
   }
 
@@ -106,112 +100,158 @@ export function resolveTokenReferences(tokens) {
 }
 
 /**
- * Compiles parsed tokens into standard CSS custom properties.
- *
- * @param {object} tokens - Parsed design tokens
- * @returns {string} Compiled CSS block
+ * Lists the CSS custom properties a token set produces, in document order.
+ * @param {object} tokens - Parsed (resolved or not) design tokens
+ * @returns {Array<[string, string]>} [name without the leading `--`, value]
+ * @throws {DesignTokenError} on unsafe names or values, or unresolved references
  */
-export function generateCssVariables(tokens) {
+export function collectCssVariables(tokens) {
+  const resolved = resolveTokenReferences(tokens || {});
   const vars = [];
-  const resolved = resolveTokenReferences(tokens);
+  const errors = [];
+  const seen = new Map();
 
-  // 1. Colors
-  if (resolved.colors) {
-    for (const [name, val] of Object.entries(resolved.colors)) {
-      if (typeof val === 'string') {
-        vars.push(`  --color-${toKebabCase(name)}: ${val};`);
-      }
+  const add = (name, value, where) => {
+    if (typeof value !== 'string' && typeof value !== 'number') return;
+    const text = String(value).trim();
+    if (!text) return;
+    if (/\{[a-zA-Z0-9_.-]+\}/.test(text)) {
+      errors.push(`${where}: unresolved reference '${text}'`);
+      return;
     }
-  }
+    if (UNSAFE_VALUE.test(text)) {
+      errors.push(`${where}: value contains a character not allowed in a CSS value`);
+      return;
+    }
+    if (seen.has(name)) {
+      errors.push(`${where}: produces --${name}, already produced by ${seen.get(name)}`);
+      return;
+    }
+    seen.set(name, where);
+    vars.push([name, text]);
+  };
+  const keysOf = (group, where) => Object.entries(group).filter(([key]) => {
+    if (TOKEN_KEY.test(key)) return true;
+    errors.push(`${where}.${key}: token names may use letters, digits, '-' and '_' only`);
+    return false;
+  });
 
-  // 2. Typography
-  if (resolved.typography) {
-    if (resolved.typography.fontFamily) {
-      for (const [name, val] of Object.entries(resolved.typography.fontFamily)) {
-        if (typeof val === 'string') {
-          vars.push(`  --font-family-${toKebabCase(name)}: ${val};`);
+  if (isPlainObject(resolved.colors)) {
+    for (const [name, val] of keysOf(resolved.colors, 'colors')) add(`color-${toKebabCase(name)}`, val, `colors.${name}`);
+  }
+  if (isPlainObject(resolved.typography)) {
+    for (const [style, def] of keysOf(resolved.typography, 'typography')) {
+      if (!isPlainObject(def)) continue;
+      if (style === 'fontFamily') {
+        // A map of font families by role (heading, body, …), as some DESIGN.md files use.
+        for (const [name, val] of keysOf(def, 'typography.fontFamily')) {
+          add(`font-family-${toKebabCase(name)}`, val, `typography.fontFamily.${name}`);
         }
+        continue;
       }
-    }
-  }
-
-  // 3. Spacing
-  if (resolved.spacing) {
-    for (const [name, val] of Object.entries(resolved.spacing)) {
-      if (typeof val === 'string') {
-        vars.push(`  --spacing-${toKebabCase(name)}: ${val};`);
+      for (const prop of TYPOGRAPHY_PROPS) {
+        add(`typography-${toKebabCase(style)}-${toKebabCase(prop)}`, def[prop], `typography.${style}.${prop}`);
       }
     }
   }
-
-  // 4. Border Radius (rounded)
+  if (isPlainObject(resolved.spacing)) {
+    for (const [name, val] of keysOf(resolved.spacing, 'spacing')) add(`spacing-${toKebabCase(name)}`, val, `spacing.${name}`);
+  }
   const rounded = resolved.rounded || resolved.borderRadius;
-  if (rounded) {
-    for (const [name, val] of Object.entries(rounded)) {
-      if (typeof val === 'string') {
-        vars.push(`  --radius-${toKebabCase(name)}: ${val};`);
+  if (isPlainObject(rounded)) {
+    for (const [name, val] of keysOf(rounded, 'rounded')) add(`radius-${toKebabCase(name)}`, val, `rounded.${name}`);
+  }
+  if (isPlainObject(resolved.components)) {
+    for (const [component, def] of keysOf(resolved.components, 'components')) {
+      if (!isPlainObject(def)) continue;
+      for (const [prop, val] of keysOf(def, `components.${component}`)) {
+        add(`component-${toKebabCase(component)}-${toKebabCase(prop)}`, val, `components.${component}.${prop}`);
       }
     }
   }
 
+  if (errors.length) throw new DesignTokenError(errors);
+  return vars;
+}
+
+/**
+ * Compiles parsed tokens into standard CSS custom properties.
+ *
+ * @param {object} tokens - Parsed design tokens
+ * @returns {string} Compiled CSS block
+ */
+export function generateCssVariables(tokens) {
+  const vars = collectCssVariables(tokens).map(([name, value]) => `  --${name}: ${value};`);
   return `:root {\n${vars.join('\n')}\n}\n`;
 }
 
 /**
  * Parses DESIGN.md from a path or string and compiles to CSS variables.
  * @param {string} source - Path to DESIGN.md or raw content
- * @returns {{ tokens: object, css: string }}
+ * @returns {{ tokens: object, css: string, variables: string[] }}
  */
 export function parseDesignTokens(source) {
   let content = source;
-  if (fs.existsSync(source)) {
+  if (!/[\r\n]/.test(source) && fs.existsSync(source)) {
     content = fs.readFileSync(source, 'utf8');
   }
 
-  const rawTokens = extractFrontmatter(content);
-  const resolved = resolveTokenReferences(rawTokens);
-  const css = generateCssVariables(resolved);
+  const resolved = resolveTokenReferences(extractFrontmatter(content));
+  const entries = collectCssVariables(resolved);
+  const css = `:root {\n${entries.map(([name, value]) => `  --${name}: ${value};`).join('\n')}\n}\n`;
 
   return {
     tokens: resolved,
-    css
+    css,
+    variables: entries.map(([name]) => name)
   };
 }
 
-/**
- * Prohibited patterns: hardcoded hex colors, rgb/hsl, hardcoded px fonts in UI code
- * when design tokens should be referenced via var(--...).
- */
-const HARDCODED_COLOR_REGEX = /(?:color|background|border|fill|stroke)\s*:\s*(#[0-9a-fA-F]{3,8}|rgba?\(|hsla?\()/i;
+// A color-bearing declaration and the literal color forms that may not appear in its value.
+const COLOR_DECLARATION = /\b(color|background(?:-color)?|border(?:-(?:top|right|bottom|left|block|inline))?(?:-color)?|outline(?:-color)?|fill|stroke|box-shadow|text-shadow|caret-color|accent-color|text-decoration(?:-color)?)\s*:\s*([^;}\n]*)/gi;
+const LITERAL_COLOR = /#[0-9a-fA-F]{3,8}\b|\b(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color)\(/;
 
 /**
  * Validates plugin UI source code against design token compliance.
- * Rejects hardcoded brand values and ensures use of CSS custom properties.
+ * Rejects hardcoded colors in color-bearing declarations (including var()
+ * fallbacks), and, when `allowedTokens` is given, any `var(--name)` whose name is
+ * not declared. Custom properties starting with `--_` are element-private.
  *
  * @param {string} uiSource - Source code of UI component (HTML, JSX, CSS, Web Component)
- * @param {object} [options]
- * @returns {{ valid: boolean, violations: string[] }}
+ * @param {{ allowedTokens?: Iterable<string> }} [options]
+ * @returns {{ valid: boolean, violations: string[], usedTokens: string[] }}
  */
 export function validatePluginUiAgainstTokens(uiSource, options = {}) {
   const violations = [];
-  const lines = uiSource.split('\n');
+  const used = new Set();
+  const allowed = options.allowedTokens ? new Set(options.allowedTokens) : null;
+  const lines = String(uiSource).split('\n');
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
 
-    // Check for hardcoded color values in styles
-    if (HARDCODED_COLOR_REGEX.test(line)) {
-      // Allow var(--...) even if it has fallback or comments
-      if (!line.includes('var(--')) {
+    for (const match of line.matchAll(COLOR_DECLARATION)) {
+      if (LITERAL_COLOR.test(match[2])) {
         violations.push(
           `Line ${i + 1}: Hardcoded color value detected ('${line.trim()}'). Use design token CSS variable var(--color-...) instead.`
         );
+        break;
+      }
+    }
+
+    for (const match of line.matchAll(/var\(\s*--([A-Za-z0-9_-]+)/g)) {
+      const name = match[1];
+      if (name.startsWith('_')) continue;
+      used.add(name);
+      if (allowed && !allowed.has(name)) {
+        violations.push(`Line ${i + 1}: var(--${name}) is not a declared design token.`);
       }
     }
   }
 
   return {
     valid: violations.length === 0,
-    violations
+    violations,
+    usedTokens: [...used]
   };
 }

package/src/core/app-deploy/plan.mjs

@@ -14,7 +14,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { resolveCapabilitySource } from './source.mjs';
-import { resolveCapabilityGraph } from './resolve.mjs';
+import { resolveCapabilityGraph, detectSsssVersion } from './resolve.mjs';
 
 export const PROTECTED_APP_FILES = new Set([
   'package.json',
@@ -187,7 +187,7 @@ export async function createDeploymentPlan(source, options = {}) {
       targetApp: {
         dir: targetDir,
         framework: adapter,
-        ssssVersion: '0.9.6'
+        ssssVersion: detectSsssVersion(targetDir)
       },
       pluginResolver: options.pluginResolver
     });

package/src/core/app-deploy/resolve.mjs

@@ -10,7 +10,30 @@
  * - Access grant and resource requirement aggregation
  */
 
+import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SSSS_PACKAGES = ['@gregiteen/ssss-cli', '@ssss/cli'];
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+
+function installedSsssVersion(root) {
+  for (const name of SSSS_PACKAGES) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(root, 'node_modules', name, 'package.json'), 'utf8'));
+      if (pkg.version) return pkg.version;
+    } catch { /* not installed here */ }
+  }
+  return null;
+}
+
+/**
+ * The SSSS version a target app runs: its installed SSSS CLI package, else the
+ * one bundled with Total Recall (what `ssss new` would scaffold today).
+ */
+export function detectSsssVersion(targetDir) {
+  return (targetDir && installedSsssVersion(targetDir)) || installedSsssVersion(PACKAGE_ROOT);
+}
 
 /**
  * Custom error types for capability resolution
@@ -110,7 +133,12 @@ export function checkSsssVersionCompatibility(manifest, targetSsssVersion) {
   const req = manifest.deploy?.required_ssss_version;
   if (!req) return;
 
-  const currentVersion = targetSsssVersion || '0.9.6';
+  const currentVersion = targetSsssVersion || detectSsssVersion();
+  if (!currentVersion) {
+    throw new IncompatibleSsssVersionError(
+      `Plugin '${manifest.id}' requires SSSS version ${req}, but no SSSS CLI package is installed in the target app or Total Recall`
+    );
+  }
   if (!satisfiesVersionConstraint(currentVersion, req)) {
     throw new IncompatibleSsssVersionError(
       `Plugin '${manifest.id}' requires SSSS version ${req}, but target app environment provides ${currentVersion}`
@@ -138,7 +166,7 @@ export function checkSsssVersionCompatibility(manifest, targetSsssVersion) {
  */
 export async function resolveCapabilityGraph(rootDescriptor, options = {}) {
   const adapter = options.adapter || options.targetApp?.framework || 'ssss-app';
-  const targetSsssVersion = options.targetApp?.ssssVersion || '0.9.6';
+  const targetSsssVersion = options.targetApp?.ssssVersion || detectSsssVersion(options.targetApp?.dir);
   const pluginResolver = options.pluginResolver || (async () => null);
 
   const graph = new Map(); // id -> descriptor

package/src/core/app-deploy/runtime-cli/node.mjs.tmpl

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// __HEADER__
+//
+// Exit codes: 0 ok · 1 the app answered with an error · 2 usage · 3 the app is unreachable.
+
+const SPEC = __SPEC__;
+
+const EXIT = { OK: 0, HTTP: 1, USAGE: 2, UNREACHABLE: 3 };
+const flagOf = (name) => `--${name.replace(/_/g, '-')}`;
+
+class UsageError extends Error {}
+
+function usage(command) {
+  if (!command) {
+    const lines = [`Usage: ${SPEC.name} <command> [options]`, ''];
+    if (SPEC.description) lines.push(SPEC.description, '');
+    lines.push('Commands:');
+    for (const c of SPEC.commands) lines.push(`  ${c.name.padEnd(20)} ${c.description || ''}`);
+    lines.push(
+      '',
+      'Global options:',
+      '  --json               Print a JSON envelope: { ok, status, data | error }',
+      `  --base-url <url>     App API base URL (default: $${SPEC.api.base_url_env} or ${SPEC.api.default_base_url})`,
+      '  -h, --help           Show help; with a command, that command\'s options',
+    );
+    return lines.join('\n');
+  }
+  const positionals = command.args.filter((a) => a.positional).map((a) => `<${a.name}>`);
+  const lines = [`Usage: ${SPEC.name} ${[command.name, ...positionals].join(' ')} [options]`, ''];
+  if (command.description) lines.push(command.description, '');
+  for (const a of command.args) {
+    const label = a.positional ? `<${a.name}>` : a.type === 'boolean' ? flagOf(a.name) : `${flagOf(a.name)} <${a.type}>`;
+    const notes = [
+      a.required && !a.positional ? 'required' : '',
+      a.choices ? `one of: ${a.choices.join(', ')}` : '',
+      a.default !== undefined ? `default: ${a.default}` : '',
+    ].filter(Boolean).join('; ');
+    lines.push(`  ${label.padEnd(26)} ${a.description || ''}${notes ? ` (${notes})` : ''}`);
+  }
+  return lines.join('\n');
+}
+
+function coerce(arg, raw) {
+  let value = raw;
+  if (arg.type === 'integer') {
+    if (!/^[-+]?\d+$/.test(raw.trim())) throw new UsageError(`${arg.name} must be an integer, got '${raw}'`);
+    value = Number(raw);
+  } else if (arg.type === 'number') {
+    value = Number(raw);
+    if (raw.trim() === '' || !Number.isFinite(value)) throw new UsageError(`${arg.name} must be a number, got '${raw}'`);
+  }
+  if (arg.choices && !arg.choices.includes(value)) {
+    throw new UsageError(`${arg.name} must be one of: ${arg.choices.join(', ')}`);
+  }
+  return value;
+}
+
+function parse(argv) {
+  const global = { json: false, baseUrl: null, help: false };
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === '--json') global.json = true;
+    else if (token === '-h' || token === '--help') global.help = true;
+    else if (token.startsWith('--base-url=')) global.baseUrl = token.slice('--base-url='.length);
+    else if (token === '--base-url') {
+      if (argv[i + 1] === undefined) throw new UsageError('--base-url needs a value');
+      global.baseUrl = argv[++i];
+    } else rest.push(token);
+  }
+
+  const [name, ...tokens] = rest;
+  if (!name) return { global, command: null, values: {} };
+  const command = SPEC.commands.find((c) => c.name === name);
+  if (!command) throw new UsageError(`unknown command '${name}'`);
+  if (global.help) return { global, command, values: {} };
+
+  const values = {};
+  const positionals = command.args.filter((a) => a.positional);
+  let next = 0;
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token.startsWith('--')) {
+      const eq = token.indexOf('=');
+      const flag = eq === -1 ? token : token.slice(0, eq);
+      const inline = eq === -1 ? undefined : token.slice(eq + 1);
+      const arg = command.args.find((a) => !a.positional && flagOf(a.name) === flag);
+      if (!arg) throw new UsageError(`unknown option ${flag} for '${name}'`);
+      if (arg.type === 'boolean') {
+        if (inline !== undefined) throw new UsageError(`${flag} takes no value`);
+        values[arg.name] = true;
+        continue;
+      }
+      const raw = inline !== undefined ? inline : tokens[++i];
+      if (raw === undefined) throw new UsageError(`${flag} needs a value`);
+      values[arg.name] = coerce(arg, raw);
+    } else {
+      const arg = positionals[next++];
+      if (!arg) throw new UsageError(`unexpected argument '${token}'`);
+      values[arg.name] = coerce(arg, token);
+    }
+  }
+  for (const arg of command.args) {
+    if (values[arg.name] === undefined && arg.default !== undefined) values[arg.name] = arg.default;
+    if (values[arg.name] === undefined && (arg.required || arg.positional)) {
+      throw new UsageError(`missing ${arg.positional ? `<${arg.name}>` : flagOf(arg.name)}`);
+    }
+  }
+  return { global, command, values };
+}
+
+function buildRequest(command, values, baseUrl) {
+  let base;
+  try {
+    base = new URL(baseUrl);
+  } catch {
+    throw new UsageError(`invalid base URL '${baseUrl}'`);
+  }
+  if (base.protocol !== 'http:' && base.protocol !== 'https:') throw new UsageError(`base URL must be http(s): '${baseUrl}'`);
+
+  const used = new Set();
+  const pathname = command.path.replace(/\{([a-z][a-z0-9_]*)\}/g, (_, key) => {
+    used.add(key);
+    return encodeURIComponent(String(values[key]));
+  });
+  const url = new URL(base.href.replace(/\/+$/, '') + pathname);
+  const rest = Object.entries(values).filter(([key]) => !used.has(key));
+  const init = { method: command.method, headers: { accept: 'application/json', 'user-agent': `${SPEC.name}-cli` } };
+  if (command.method === 'GET' || command.method === 'DELETE') {
+    for (const [key, value] of rest) url.searchParams.append(key, String(value));
+  } else if (rest.length) {
+    init.headers['content-type'] = 'application/json';
+    init.body = JSON.stringify(Object.fromEntries(rest));
+  }
+  const token = SPEC.auth ? process.env[SPEC.auth.token_env] : undefined;
+  if (token) init.headers.authorization = `Bearer ${token}`;
+  return { url, init };
+}
+
+function errorText(data, response) {
+  if (data && typeof data === 'object') {
+    const detail = data.error ?? data.message;
+    if (detail !== undefined) return typeof detail === 'string' ? detail : JSON.stringify(detail);
+  }
+  if (typeof data === 'string' && data.trim()) return data.trim().slice(0, 500);
+  return response.statusText || `HTTP ${response.status}`;
+}
+
+function fail(json, status, error) {
+  if (json) console.log(JSON.stringify({ ok: false, status, error }));
+  else console.error(`${SPEC.name}: ${error}${status ? ` (HTTP ${status})` : ''}`);
+}
+
+async function main() {
+  let parsed;
+  try {
+    parsed = parse(process.argv.slice(2));
+  } catch (err) {
+    if (!(err instanceof UsageError)) throw err;
+    console.error(`${SPEC.name}: ${err.message}\nRun '${SPEC.name} --help' for usage.`);
+    return EXIT.USAGE;
+  }
+  const { global, command, values } = parsed;
+  if (!command) {
+    console.log(usage());
+    return global.help ? EXIT.OK : EXIT.USAGE;
+  }
+  if (global.help) {
+    console.log(usage(command));
+    return EXIT.OK;
+  }
+
+  const baseUrl = global.baseUrl || process.env[SPEC.api.base_url_env] || SPEC.api.default_base_url;
+  let request;
+  try {
+    request = buildRequest(command, values, baseUrl);
+  } catch (err) {
+    if (!(err instanceof UsageError)) throw err;
+    console.error(`${SPEC.name}: ${err.message}`);
+    return EXIT.USAGE;
+  }
+
+  let response;
+  try {
+    response = await fetch(request.url, { ...request.init, signal: AbortSignal.timeout(SPEC.api.timeout_seconds * 1000) });
+  } catch (err) {
+    const reason = err?.name === 'TimeoutError' ? `no answer within ${SPEC.api.timeout_seconds}s` : (err?.cause?.code || err?.message || String(err));
+    fail(global.json, null, `cannot reach ${request.url.origin}: ${reason}`);
+    return EXIT.UNREACHABLE;
+  }
+
+  const text = await response.text();
+  let data = text;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch { /* not JSON: keep the text */ }
+
+  if (!response.ok) {
+    fail(global.json, response.status, errorText(data, response));
+    return EXIT.HTTP;
+  }
+  if (global.json) console.log(JSON.stringify({ ok: true, status: response.status, data }));
+  else if (typeof data === 'string') console.log(data);
+  else if (data !== null) console.log(JSON.stringify(data, null, 2));
+  return EXIT.OK;
+}
+
+main().then(
+  (code) => { process.exitCode = code; },
+  (err) => { console.error(err?.stack || String(err)); process.exitCode = 1; },
+);