Skip to main content
Ouro UI

Ouro AX

ax-xray

The Ouro AX conformance checker: it calls a CLI, an HTTP API or an MCP server the way an agent would, and reports which claims hold on which surface, with the fix where a claim does not hold. It checks from outside, never by importing the interface's code. Reads run freely; what other people see is called only on paths that must refuse (a made-up target, no --why) or that act on nothing (--dry-run), and only against a target that proves it is a mock.

node xray.ts --cli "<command>" [--http <url> --routes <manifest.json>] [--mcp "<command>"] [options]
npx shadcn@latest add ourostack/ouro-ui/ax-xray#v1.3.10

It installs lib/ouro/ax/xray.ts, with ax-checks, ax-claims, ax-component, ax-dev-commands, ax-outcome, ax-precise-copy, ax-terminal, ax-wait, ax-work-event. Its tests are ax-xray-tests. Every item runs on Node 22.18 or later as it is copied: the files import each other as ./<file>.ts. The Ouro AX guide shows how they fit together.

Exports

audienceWho

An outcome's audience.who, or an empty string.

function audienceWho(value: unknown): string

CheckResult

interface CheckResult {
  claim: string;
  surface: string;
  verdict: Verdict;
  note: string;
}

checkSafety

Whether the X-ray may call what other people see, failing closed: every address it can see is loopback, the home is isolated, the target proves it is a mock (--mock "<url> <key>=<value>", or the adopter's --guard, which already passed), and no credential is passed to it. Any missing proof refuses those checks and says why.

function checkSafety(opts: XrayOptions, guardPassed: boolean): Promise<Safety>

claimSetHash

The SHA-256 of the claim set's canonical JSON: a report pins the exact standard it checked.

function claimSetHash(): string

compareInventory

Compares what the X-ray covered with the inventory: missing, unknown and listed twice on either side.

function compareInventory(expected: readonly string[], covered: readonly string[]): InventoryCompare

harvest

Collects sample refs from a JSON answer: the first ref (else id) of each array, keyed by its name, singular.

function harvest(value: unknown, samples: Record<string, string>, key?: string | null): Record<string, string>

Inventory

The surfaces an adopter generates from its own registration: CLI command names, HTTP METHOD /path routes, MCP tool names, and its components' bound reads and actions (ui, the entries bindAx returns), whose twins it checks.

interface Inventory {
  cli?: string[];
  http?: string[];
  mcp?: string[];
  ui?: UiEntry[];
}

InventoryCompare

interface InventoryCompare {
  expected: number;
  covered: number;
  missing: string[];
  unknown: string[];
  duplicate: string[];
}

main

The command: parses argv, runs, writes the reports; resolves the exit code.

function main(argv: readonly string[], io?: Io): Promise<number>

misspell

Drops one inner letter: --limit becomes --limt.

function misspell(flag: string): string

parseArgs

function parseArgs(argv: readonly string[]): XrayOptions

refsOf

The refs that a JSON answer's list items carry, as a read's text should show them (cli.text-refs).

function refsOf(value: unknown, out?: string[]): string[]

refusalVerdict

A refusal's footprint: nothing, or only records that say they were refused.

function refusalVerdict(delta: { same: boolean; added: string[]; removed: string[]; }): { ok: boolean; note: string; }

renderHtml

function renderHtml(report: Report): string

renderMarkdown

function renderMarkdown(report: Report): string

renderText

function renderText(report: Report, max?: number): string

Report

interface Report {
  tool: "ax-xray";
  checker: { version: string };
  claimSet: { version: string; hash: string };
  at: string;
  target: { commit: string | null; cli?: { name: string; calls: number; commands: number }; http?: { origin: string; routes: number; requests: number }; mcp?: { tools: number } };
  safety: Safety;
  inventory: { given: boolean; surfaces: ClaimSurface[] };
  effects: { surface: string; note: string }[];
  conformant: boolean;
  summary: { claims: number; holding: number; must: number; mustHolding: number; mustSkipped: number; checks: { pass: number; fail: number; skip: number }; score: number | null };
  claims: ClaimSummary[];
  results: CheckResult[];
}

requiredWords

Removes [...] groups (nested) from a usage line and splits it into words.

function requiredWords(usage: string): string[]

Safety

interface Safety {
  ok: boolean;
  checks: { name: string; ok: boolean; note: string }[];
}

splitCommand

Splits a command line into words, honouring single and double quotes.

function splitCommand(line: string): string[]

stateDelta

What changed between two state snapshots, element by element: arrays compare by their members.

function stateDelta(before: readonly string[], after: readonly string[]): { same: boolean; added: string[]; removed: string[]; }

summarize

The report from the results: per claim, how many surfaces hold it; overall, whether the interface conforms.

function summarize(results: readonly CheckResult[], parts: Pick<Report, "target" | "safety" | "inventory" | "effects">, at?: string): Report

usageWords

Splits a usage line into words, keeping a placeholder with spaces (<message id>) in one word.

function usageWords(usage: string): string[]

Verdict

type Verdict = "pass" | "fail" | "skip";

xray

Runs the X-ray: the guard, the safety proof, then the surfaces given; returns the report.

function xray(opts: XrayOptions): Promise<Report>

XRAY_VERSION

The Ouro AX conformance checker: it calls a CLI, an HTTP API or an MCP server the way an agent would, and reports which claims hold on which surface, with the fix where a claim does not hold. It checks from outside, never by importing the interface's code. Reads run freely; what other people see is called only on paths that must refuse (a made-up target, no --why) or that act on nothing (--dry-run), and only against a target that proves it is a mock.

node xray.ts --cli "<command>" [--http <url> --routes <manifest.json>] [--mcp "<command>"] [options]
const XRAY_VERSION: "1.5.0"

XrayOptions

interface XrayOptions {
  cli?: string | undefined;
  http?: string | undefined;
  routes?: string | undefined;
  mcp?: string | undefined;
  name?: string | undefined;
  env: Record<string, string>;
  guard?: string | undefined;
  mock?: string | undefined;
  home?: string | undefined;
  inventory?: string | undefined;
  events?: string | undefined;
  commit?: string | undefined;
  failureCopyAllow?: string | undefined;
  conformance: boolean;
  state: string[];
  volatile: string[];
  samples: Record<string, string>;
  width: number;
  timeoutMs: number;
  json: boolean;
  md?: string | undefined;
  html?: string | undefined;
  command: "claims" | "help" | null;
}
Source on GitHubThis page as Markdown