uitive

On this page

The agent kit as a command-line tool and a library: detection, set-up, sources from OpenAPI, blocks, discovery and the check.

Install: pnpm add uitive. Guides: Coding agents.

Running the CLI

Source: commands.ts

run

Runs the CLI; returns the exit code.

ts
function run(argv: readonly string[], context: RunContext): Promise<number>;

Uses: RunContext.

RunContext

What the CLI writes to, and the version it reports.

Uses: Writable.

PropertyTypeDescription
versionstringThe version --version prints.
outWritableWhere results go.
errWritableWhere problems go.

Writable

Somewhere text can be written, such as process.stdout.

PropertyTypeDescription
write()(text: string) => unknownWrites the text.

Setting up

Source: detect.ts, folder.ts, init.ts, templates.ts

detect

What a project uses: everything init needs to set Uitive up to fit. With a boundary, nothing above or outside it is read.

ts
function detect(cwd?: string, options?: DetectOptions): Promise<Detection>;

Uses: Detection, DetectOptions.

detectText

A detection as text, one line per finding.

ts
function detectText(found: Detection): string;

Uses: Detection.

FOLDER

Where Uitive's files go unless the project says otherwise.

ts
const FOLDER = 'uitive';

folderOf

Where a project keeps Uitive's files: uitive.dir in its package.json, which init --dir writes, else uitive. Relative to the project, with forward slashes. A folder outside the project, absolute or through .., is refused.

ts
function folderOf(cwd: string): Promise<string>;

init

Sets Uitive up in a project: packages, a folder (src/uitive/ or uitive/) whose contract starts with every page as a region, sources generated from an API description when one is small enough, and the coding agents' MCP servers and skill, at the repository's root. Never overwrites a file. With a boundary, nothing above or outside it is read or written.

ts
function init(options?: InitOptions): Promise<InitResult>;

Uses: InitOptions, InitResult.

initText

What init did, as text: the files, the install and the next steps.

ts
function initText(result: InitResult): string;

Uses: InitResult.

SKILL

The integration playbook for coding agents, as init installs it: the same text as the Claude Code plugin's skill.

ts
const SKILL: string;

within

Whether a path stays inside a folder once symbolic links resolve, so that reading or writing it can't reach anything outside. A relative path is taken from the folder.

ts
function within(folder: string, path: string): Promise<boolean>;

Detected

Something detection found, such as a framework, with its version.

PropertyTypeDescription
namestringThe package or tool, such as next.
version?stringIts version, when the manifest says.

Detection

What a project uses: its package manager, interface, framework, router, design systems, API descriptions, coding agents and workspace.

Uses: Detected.

PropertyTypeDescription
rootstringThe package's folder, where Uitive is set up.
namestringThe package's name.
packageManager'pnpm' | 'yarn' | 'npm' | 'bun'The package manager its lockfile shows.
typescriptbooleanWhether it uses TypeScript.
uiDetected | nullIts interface library, such as React.
frameworkDetected | nullIts framework, such as Next.js or Vite.
routerDetected | nullIts router, such as React Router.
designSystemsDetected[]Component libraries and styling, such as @medusajs/ui or shadcn.
openapistring[]API descriptions found in the project, relative to its root.
agents('claude-code' | 'cursor' | 'vscode' | 'codex')[]Coding agents the project is set up for, so init can configure them.
uitivebooleanWhether Uitive is already set up.
packageManagerPinstring | nullThe pinned package manager, such as yarn@1.22.22, from packageManager; nothing unless it names npm, pnpm, yarn or bun and a version.
repositorystringThe repository's root, where coding agents run: the nearest folder with .git. With a boundary and no .git inside it, the boundary.
workspaces{ path: string; name: string; ui: Detected | null; framework: Detected | null }[]For a workspace root: its packages with an interface, where Uitive belongs.
serverbooleanWhether the application has its own server, where the model planner can run.

DetectOptions

What detection takes besides the folder.

PropertyTypeDescription
boundary?stringA folder detection never reads above or outside, such as the root an MCP server is confined to. Without one, it looks up to the repository's root.

InitOptions

What init takes: the project, where its files go, the API description, and how to install.

PropertyTypeDefaultDescription
cwd?stringprocess.cwd()The project's root.
openapi?stringThe API description to generate from; else the first one found.
install?booleantrueInstalls the packages with the project's package manager.
agents?booleantrueConfigures the coding agents found: MCP servers and the integration skill.
mcp?string'npx -yHow agents start the MCP server: a command quoted as a shell would read it, or a JSON array of its words.
packages?stringA folder of package tarballs (pnpm pack) to install from, such as a local build.
dir?stringthe recorded folder, else 'src/uitive' when there is a src folder, else 'uitive'Where Uitive's files go, relative to the project, such as app/uitive for a build that compiles only app. Recorded in package.json as uitive.dir, where every command reads it.
boundary?stringA folder init never reads or writes above or outside, such as the root an MCP server is confined to. The coding agents' configuration goes at the nearest repository root inside it, else at the boundary itself; anything that would land outside is reported in next instead of written.

InitResult

What init did: what it detected, the files it wrote and kept, the install, and what to do next.

Uses: Detection.

PropertyTypeDescription
detectionDetectionWhat the project uses.
writtenstring[]Files written, relative to the project.
keptstring[]Files that existed and were left alone.
install{ command: string; ran: boolean; ok?: boolean; output?: string }The install command, whether it ran, and how it went.
nextstring[]What to do next, in order.

API descriptions

Source: curation.ts, emit.ts, generate.ts, openapi.ts, survey.ts

curate

Applies a curation: keeps the sources it chooses and their actions, and its overrides. Effects may be raised freely and lowered only with a stated reason. Problems name every reference that doesn't resolve, so a typo never passes silently.

ts
function curate(
  inventory: ApiInventory,
  curation: Curation,
): {
  inventory: ApiInventory;
  problems: string[];
};

Uses: ApiInventory, Curation.

CURATE_ACTIONS

Actions past which models choose worse: curate down to what the interface offers.

ts
const CURATE_ACTIONS = 200;

CURATE_SOURCES

Past these, models choose worse: curate down to what the frontend shows.

ts
const CURATE_SOURCES = 40;

CURATION

Where the curation is, in a project that keeps Uitive's files in uitive/; commands use the project's own folder (folderOf).

ts
const CURATION = 'uitive/curation.json';

curationSchema

uitive/curation.json: what to keep from an API description, kept across regenerations.

ts
const curationSchema: ZodObject;

emit

The generated module: sources, actions and how each maps to the API.

ts
function emit(inventory: ApiInventory, options: EmitOptions): string;

Uses: ApiInventory, EmitOptions.

GENERATED

Where generate sources writes, in a project that keeps Uitive's files in uitive/; commands use the project's own folder (folderOf).

ts
const GENERATED = 'uitive/api.generated.ts';

generateSources

Generates sources, actions and endpoints from an API description and its curation.

ts
function generateSources(options: GenerateSourcesOptions): Promise<
  GenerateSourcesResult & {
    code: string;
  }
>;

Uses: GenerateSourcesOptions, GenerateSourcesResult.

inventory

Builds the inventory: every list endpoint a source, every write an action.

ts
function inventory(doc: Record<string, unknown>, options?: InventoryOptions): ApiInventory;

Uses: ApiInventory, InventoryOptions.

kebab

A name in kebab case, as IDs are written: OrderItems gives order-items.

ts
function kebab(value: string): string;

parseCuration

Reads a curation, or names every problem with it, such as a key that doesn't exist.

ts
function parseCuration(value: unknown):
  | {
      curation: Curation;
    }
  | {
      problems: string[];
    };

Uses: Curation.

picksOf

The picks a curation asks for, by source, for inventory.

ts
function picksOf(curation: Curation): Record<string, Record<string, string>>;

Uses: Curation.

plain

Plain text from a description: no HTML or Markdown, whole sentences, at most length characters.

ts
function plain(value: string, length?: number): string;

readSpec

Reads an OpenAPI 2.0, 3.0 or 3.1 document, JSON or YAML, as OpenAPI 3.1.

ts
function readSpec(source: string | Record<string, unknown>): Record<string, unknown>;

singular

An English word in the singular, as source IDs need for relations: orders gives order.

ts
function singular(word: string): string;

survey

Surveys what the mapper read, marking the sources a curation keeps.

ts
function survey(inventory: ApiInventory, included?: ReadonlySet<string>): Survey;

Uses: ApiInventory, Survey.

surveySpec

A compact inventory of an API description, marking what the curation keeps.

ts
function surveySpec(options: SpecOptions): Promise<
  Survey & {
    problems: string[];
  }
>;

Uses: SpecOptions, Survey.

surveyText

The survey as text: one line per source, sized for a coding agent's context.

ts
function surveyText(value: Survey): string;

Uses: Survey.

ApiAction

One action the mapper read from an API description: its params, effect, and REST endpoint.

Uses: ApiParam, Effect, Op, RestAction, Skipped.

PropertyTypeDescription
idstringThe action's ID, which the curation uses.
labelstringWhat people call it.
descriptionstringWhat it does, for people and models.
operationstringThe operation it runs, such as POST /v1/refunds.
resourcestring | nullThe source the action works on, when there is one.
effectEffectWhat a run does to data: read, write or destructive.
reasonstringWhy the effect was chosen.
paramsApiParam[]What a run takes, besides the path's own params.
skippedSkipped[]Params left out, and why.
invalidatesstring[]Sources a run changes, so results that read them refresh.
restRestActionHow restPerform runs it.
confirm?stringFor destructive actions: the phrase a run asks for.
when?{ field: string; op: Op; values: string[] }[]Qualified filters on the row's source, such as charges.status.

ApiField

One field of an API's rows, as the mapper reads it: its type, meaning and where it is in a row.

Uses: FieldType.

PropertyTypeDescription
namestringThe field's name in the contract.
typeFieldTypeWhat the value means, which decides how it shows and filters.
nullablebooleanWhether rows may lack a value.
descriptionstringWhat the field holds, from the API description.
valuesstring[]For enums.
unit?'iso' | 's' | 'ms'For times: an ISO string, or seconds or milliseconds since 1970.
currency?stringFor money: the field holding the currency.
minor?booleanFor money: whether amounts are in minor units, such as cents.
digits?Record<string, number>For money in minor units: decimal places by currency where the API's differ from ISO 4217's, such as { ISK: 2, MGA: 0 }, from the curation.
source?stringFor refs: the source referred to.
pointer?stringFor a value lifted from a nested object or renamed: where it is in a row.
label?stringWhat people call it, when its name doesn't say, such as "Order" for display_id.

ApiInventory

Everything the mapper read from an API description: sources, actions, and what it skipped.

Uses: ApiAction, ApiSource.

PropertyTypeDescription
titlestringThe API's title, from its description.
versionstringThe API's version, from its description.
serverstringThe base URL requests go to.
sourcesApiSource[]Every source read.
actionsApiAction[]Every action read.
skipped{ operation: string; reason: string }[]Operations that became neither, and why.

ApiParam

One param of an action, as the mapper reads it.

PropertyTypeDescription
requiredbooleanWhether a run needs it.
namestringThe field's name in the contract.
typeFieldTypeWhat the value means, which decides how it shows and filters.
nullablebooleanWhether rows may lack a value.
descriptionstringWhat the field holds, from the API description.
valuesstring[]For enums.
unit?'iso' | 's' | 'ms'For times: an ISO string, or seconds or milliseconds since 1970.
currency?stringFor money: the field holding the currency.
minor?booleanFor money: whether amounts are in minor units, such as cents.
digits?Record<string, number>For money in minor units: decimal places by currency where the API's differ from ISO 4217's, such as { ISK: 2, MGA: 0 }, from the curation.
source?stringFor refs: the source referred to.
pointer?stringFor a value lifted from a nested object or renamed: where it is in a row.
label?stringWhat people call it, when its name doesn't say, such as "Order" for display_id.

ApiSource

One source the mapper read from an API description: its fields, capabilities and REST endpoint.

ts
interface ApiSource {
  id: string;
  label: string;
  description: string;
  keywords: string[];
  schema: string;
  operation: string;
  key: string;
  title: string;
  summary: string[];
  fields: ApiField[];
  extra: ApiField[];
  skipped: Skipped[];
  capabilities: {
    filter: Record<string, Op[]>;
    sort: string[];
    search: boolean;
    pagination: 'cursor' | 'offset' | 'none';
  };
  rest: RestSource;
  notes: string[];
  scan?: number;
  ttl?: number;
}

Uses: ApiField, Op, RestSource, Skipped.

PropertyDescription
idThe source's ID, which the curation uses.
labelWhat people call it.
descriptionWhat its rows are, for people and models.
keywordsOther words people use for it, so requests find it.
schemaThe row schema's component name, when it has one.
operationThe operation that lists its rows, such as GET /v1/charges.
keyThe field that identifies a row.
titleThe field that names a row.
summaryThe fields that sum a row up.
fieldsThe fields kept.
extraFields understood but left out to keep the source small; the curation can bring them back.
skippedFields left out, and why.
capabilitiesWhat the endpoint does by itself: filters by field, sorting, search and paging.
restHow restFetch reads it.
notesGuesses worth checking against the running API.
scan?Most rows fetched to answer one query on the client, when the curation sets it.
ttl?Seconds a result stays fresh, when the curation sets it.

Curation type

A curation, read: what to keep from an API description, with defaults filled in.

ts
type Curation = z.infer<typeof curationSchema>;

Uses: curationSchema.

CurationInput

A curation as written in curation.json.

ts
type CurationInput = z.input<typeof curationSchema>;

Uses: curationSchema.

EmitOptions

How generated sources are written: where the description came from, and which modules the code imports.

PropertyTypeDefaultDescription
fromstringWhere the description came from, for the header, such as stripe.json.
core?string'@plurid/uitive-core'The module that exports the field helpers.
zod?string'zod'The module that exports z.
curation?string'uitive/curation.json'The curation file, named in the header.

GenerateSourcesOptions

What generate sources takes: the description, its curation, and where to write.

PropertyTypeDefaultDescription
out?string'api.generated.ts' in the project's Uitive folderWhere to write.
dryRun?booleanfalseReports without writing.
specstringA path or URL to an OpenAPI 2.0, 3.0 or 3.1 description.
cwd?stringprocess.cwd()The project's root.
curation?string'curation.json' in the project's Uitive folderThe curation file; used when it exists.

GenerateSourcesResult

What generate sources did: the file, whether it was written, the sources and actions, and what stopped it.

PropertyTypeDescription
filestringThe generated module.
writtenbooleanWhether it was written; not on a dry run, or when something blocked it.
sourcesstring[]The IDs of the sources generated.
actionsstring[]The IDs of the actions generated.
problemsstring[]What blocks generation: fix these first.
notesstring[]Guesses worth checking.

InventoryOptions

How the mapper reads a description: which nested values to lift into fields.

PropertyTypeDescription
picks?Readonly<Record<string, Readonly<Record<string, string>>>>Values lifted from nested objects, by source: field name to JSON pointer in a row.

Skipped

Something the mapper left out, and why.

PropertyTypeDescription
namestringWhat was left out, such as a field or an operation.
reasonstringWhy, in a few words.

SpecOptions

Where an API description is, and its curation.

PropertyTypeDefaultDescription
specstringA path or URL to an OpenAPI 2.0, 3.0 or 3.1 description.
cwd?stringprocess.cwd()The project's root.
curation?string'curation.json' in the project's Uitive folderThe curation file; used when it exists.

Survey type

A compact inventory of an API description, to curate from: counts, advice, one line per source, and what was skipped.

Uses: SurveySource.

PropertyTypeDescription
titlestringThe API's title.
versionstringThe API's version.
serverstringThe base URL requests go to.
counts{ sources: number; actions: number; skipped: number }How many sources and actions it yields, and how many operations were skipped.
advicestring[]What to do next, such as curating a large description.
sourcesSurveySource[]One line per source.
unattachedstring[]Actions on no source, such as /v1/tokens.
skippedRecord<string, string[]>Skipped operations, by reason.

SurveySource

One line of a survey: a source, its fields kept and left out, what its API can do, and its actions.

PropertyTypeDescription
idstringThe source's ID, as the curation names it.
labelstringWhat people call it.
pathstringThe path that lists its rows.
fieldsnumberFields kept, and fields understood but left out.
extranumberHow many fields were understood but left out.
names{ kept: string[]; extra: string[] }Their names, for the curation's fields, labels and title.
filtersstring[]Fields the endpoint filters by.
searchbooleanWhether the endpoint searches text.
sortstring[]Fields the endpoint sorts by.
paginationstringHow the endpoint pages: cursor, offset or none.
itembooleanWhether rows can be read one by key.
actionsstring[]The IDs of the actions on its rows.
notesstring[]Guesses worth checking against the running API.
included?booleanWhether the curation keeps it, when there is one.

Native blocks

Source: blocks.ts

BLOCKS

Where generate blocks writes, in a project that keeps Uitive's files in uitive/; commands use the project's own folder (folderOf).

ts
const BLOCKS = 'uitive/blocks.generated.ts';

emitBlocks

Writes blocks as a module of block specs, ready to spread into a contract's blocks.

ts
function emitBlocks(blocks: readonly ComponentBlock[], core?: string): string;

Uses: ComponentBlock.

generateBlocks

Generates block specs from components' TypeScript props and writes them, or reports drift with check.

ts
function generateBlocks(options: GenerateBlocksOptions): Promise<{
  file: string;
  written: boolean;
  drift: boolean;
  blocks: {
    name: string;
    component: string;
    props: string[];
    adapter: string[];
  }[];
  problems: string[];
}>;

Uses: GenerateBlocksOptions.

readBlocks

Reads file#Export specifiers into blocks, with the project's compiler settings.

ts
function readBlocks(specifiers: readonly string[], cwd: string): BlocksResult;

Uses: BlocksResult.

BlockProp

One prop of a component, as a block's schema holds it.

PropertyTypeDescription
namestringThe prop's name.
schemastringThe zod schema, as code.
descriptionstringWhat the prop is, from its JSDoc.
fallback?stringThe component's default, when it has one: the planner must now always give a value.

BlocksResult

What reading components gives: the blocks, and the components that couldn't become one.

Uses: ComponentBlock.

PropertyTypeDescription
blocksComponentBlock[]Each component, as a block.
problemsstring[]Components whose props can't become a schema: fix or wrap them.

ComponentBlock

A component read as a block: where it lives, what it is called, and its props.

Uses: BlockProp.

PropertyTypeDescription
namestringThe block's name in the contract, such as orderSummary.
componentstringThe component's export name.
filestringThe file it comes from.
labelstringWhat people call it.
descriptionstringWhat it shows, for people and models.
propsBlockProp[]The props a page may set, as data.
adapter{ name: string; reason: string }[]Props an adapter supplies, such as callbacks and children.

GenerateBlocksOptions

What generate blocks takes: the components, where to write, and whether only to check.

PropertyTypeDefaultDescription
componentsreadonly string[]file#Component for each component.
cwd?stringprocess.cwd()The project's root.
out?string'blocks.generated.ts' in the project's Uitive folderWhere to write.
check?booleanfalseReports whether the file is up to date, without writing it.

Discovering an application

Source: discover.ts

discover

Crawls a running application's pages, same origin only, following links but never pressing anything, and proposes routes, regions, lists and button-to-action matches from what assistive technology sees. Rows are never read, and the browser never navigates to another origin, not even through a redirect.

ts
function discover(options: DiscoverOptions): Promise<DiscoverResult>;

Uses: DiscoverOptions, DiscoverResult.

DISCOVERY

Where discover writes, in a project that keeps Uitive's files in uitive/; commands use the project's own folder (folderOf).

ts
const DISCOVERY = 'uitive/discovery.json';

DiscoverOptions

What discover takes: where the application runs, how much to crawl, and where to write.

PropertyTypeDefaultDescription
urlstringWhere to start, such as http://localhost:5173/.
cwd?stringprocess.cwd()The project's root.
pages?number30Most pages visited.
perRoute?number2Most visits per route, such as two orders.
storageState?stringA Playwright storage state file holding a signed-in session.
chrome?booleanfalseUses the installed Chrome instead of Playwright's Chromium.
out?string'discovery.json' in the project's Uitive folderWhere to write the discovery.
contract?string'contract.ts' in the project's Uitive folderMatches buttons against this contract's actions, when it exists.

DiscoverResult

What discover did: where it wrote, the pages it visited, and the discovery.

Uses: Discovery.

PropertyTypeDescription
filestringWhere the discovery was written.
visitedstring[]The URLs visited, in order.
skipped{ url: string; reason: string }[]Pages that couldn't be read, and why, such as a redirect to another site.
discoveryDiscoveryWhat the pages suggest.

Checking

Source: check.ts

BINDINGS

Where the bindings are, in a project that keeps Uitive's files in uitive/; commands use the project's own folder (folderOf).

ts
const BINDINGS = 'uitive/bindings.ts';

check

Checks an integration: the contract loads and validates, its JSON round-trips, every schema a request can need fits structured outputs, and bindings exist for what the contract declares. Labels that two actions share, or that don't find their source, are warnings.

ts
function check(options?: CheckOptions): Promise<CheckResult>;

Uses: CheckOptions, CheckResult.

checkText

A check's result as text, one line per check, with coverage and warnings.

ts
function checkText(result: CheckResult): string;

Uses: CheckResult.

CONTRACT

Where the contract is, in a project that keeps Uitive's files in uitive/; commands use the project's own folder (folderOf).

ts
const CONTRACT = 'uitive/contract.ts';

contractIn

The contract a module exports: contract, the default export, or the only contract.

ts
function contractIn(module: Record<string, unknown>): AnyContract | undefined;

Uses: AnyContract.

loadModule

Loads a TypeScript module from the project, as the project would, tsconfig paths included.

ts
function loadModule(path: string): Promise<Record<string, unknown>>;

SCHEMA_LIMITS

What one request's schema may hold, so Claude's structured outputs accept it.

ts
const SCHEMA_LIMITS: {
  readonly bytes: 60000;
  readonly optional: 0;
  readonly unions: 1;
  readonly enum: 400;
};

Check type

One check: its name, whether it passed, and what it found.

PropertyTypeDescription
namestringThe check: contract, json, schemas or bindings.
okbooleanWhether it passed.
detailstringWhat it found, or what to fix.

CheckOptions

What check reads: the project, and where its contract and bindings are when they aren't in the Uitive folder.

PropertyTypeDefaultDescription
cwd?stringprocess.cwd()The project's root.
contract?string'contract.ts' in the project's Uitive folderThe contract module.
bindings?string'bindings.ts' in the project's Uitive folderThe bindings module.

CheckResult

What check found: whether the integration holds, each check, warnings, and coverage.

Uses: Check, Coverage.

PropertyTypeDescription
okbooleanWhether every check passed.
checksCheck[]Each check, in order.
warningsstring[]Worth fixing, but nothing breaks.
coverage?CoverageWhat the contract covers, once it loads.

Coverage

How much of the application the contract covers: sources, actions, routes, pages, regions, lists and choices.

PropertyTypeDescription
sourcesnumberSources declared.
actionsnumberActions declared.
runnablenumberActions with an effect, which run through perform after confirmation.
performsbooleanWhether the bindings export perform, which interface actions may use too.
routesnumberRoutes declared.
pagesnumberPages people can redesign.
regionsnumberRegions: parts of the application as it already is.
listsnumberLists, such as toolbars and menus.
choicesnumberChoices, such as a theme.