# uitive

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](https://uitive.dev/docs/coding-agents).

- [Running the CLI](https://uitive.dev/docs/api/cli#running-the-cli): [`run`](https://uitive.dev/docs/api/cli#run), [`RunContext`](https://uitive.dev/docs/api/cli#runcontext), [`Writable`](https://uitive.dev/docs/api/cli#writable)
- [Setting up](https://uitive.dev/docs/api/cli#setting-up): [`detect`](https://uitive.dev/docs/api/cli#detect), [`detectText`](https://uitive.dev/docs/api/cli#detecttext), [`FOLDER`](https://uitive.dev/docs/api/cli#folder), [`folderOf`](https://uitive.dev/docs/api/cli#folderof), [`init`](https://uitive.dev/docs/api/cli#init), [`initText`](https://uitive.dev/docs/api/cli#inittext), [`SKILL`](https://uitive.dev/docs/api/cli#skill), [`within`](https://uitive.dev/docs/api/cli#within), [`Detected`](https://uitive.dev/docs/api/cli#detected), [`Detection`](https://uitive.dev/docs/api/cli#detection), [`DetectOptions`](https://uitive.dev/docs/api/cli#detectoptions), [`InitOptions`](https://uitive.dev/docs/api/cli#initoptions), [`InitResult`](https://uitive.dev/docs/api/cli#initresult)
- [API descriptions](https://uitive.dev/docs/api/cli#api-descriptions): [`curate`](https://uitive.dev/docs/api/cli#curate), [`CURATE_ACTIONS`](https://uitive.dev/docs/api/cli#curate_actions), [`CURATE_SOURCES`](https://uitive.dev/docs/api/cli#curate_sources), [`CURATION`](https://uitive.dev/docs/api/cli#curation), [`curationSchema`](https://uitive.dev/docs/api/cli#curationschema), [`emit`](https://uitive.dev/docs/api/cli#emit), [`GENERATED`](https://uitive.dev/docs/api/cli#generated), [`generateSources`](https://uitive.dev/docs/api/cli#generatesources), [`inventory`](https://uitive.dev/docs/api/cli#inventory), [`kebab`](https://uitive.dev/docs/api/cli#kebab), [`parseCuration`](https://uitive.dev/docs/api/cli#parsecuration), [`picksOf`](https://uitive.dev/docs/api/cli#picksof), [`plain`](https://uitive.dev/docs/api/cli#plain), [`readSpec`](https://uitive.dev/docs/api/cli#readspec), [`singular`](https://uitive.dev/docs/api/cli#singular), [`survey`](https://uitive.dev/docs/api/cli#survey), [`surveySpec`](https://uitive.dev/docs/api/cli#surveyspec), [`surveyText`](https://uitive.dev/docs/api/cli#surveytext), [`ApiAction`](https://uitive.dev/docs/api/cli#apiaction), [`ApiField`](https://uitive.dev/docs/api/cli#apifield), [`ApiInventory`](https://uitive.dev/docs/api/cli#apiinventory), [`ApiParam`](https://uitive.dev/docs/api/cli#apiparam), [`ApiSource`](https://uitive.dev/docs/api/cli#apisource), [`Curation`](https://uitive.dev/docs/api/cli#curation-type), [`CurationInput`](https://uitive.dev/docs/api/cli#curationinput), [`EmitOptions`](https://uitive.dev/docs/api/cli#emitoptions), [`GenerateSourcesOptions`](https://uitive.dev/docs/api/cli#generatesourcesoptions), [`GenerateSourcesResult`](https://uitive.dev/docs/api/cli#generatesourcesresult), [`InventoryOptions`](https://uitive.dev/docs/api/cli#inventoryoptions), [`Skipped`](https://uitive.dev/docs/api/cli#skipped), [`SpecOptions`](https://uitive.dev/docs/api/cli#specoptions), [`Survey`](https://uitive.dev/docs/api/cli#survey-type), [`SurveySource`](https://uitive.dev/docs/api/cli#surveysource)
- [Native blocks](https://uitive.dev/docs/api/cli#native-blocks): [`BLOCKS`](https://uitive.dev/docs/api/cli#blocks), [`emitBlocks`](https://uitive.dev/docs/api/cli#emitblocks), [`generateBlocks`](https://uitive.dev/docs/api/cli#generateblocks), [`readBlocks`](https://uitive.dev/docs/api/cli#readblocks), [`BlockProp`](https://uitive.dev/docs/api/cli#blockprop), [`BlocksResult`](https://uitive.dev/docs/api/cli#blocksresult), [`ComponentBlock`](https://uitive.dev/docs/api/cli#componentblock), [`GenerateBlocksOptions`](https://uitive.dev/docs/api/cli#generateblocksoptions)
- [Discovering an application](https://uitive.dev/docs/api/cli#discovering-an-application): [`discover`](https://uitive.dev/docs/api/cli#discover), [`DISCOVERY`](https://uitive.dev/docs/api/cli#discovery), [`DiscoverOptions`](https://uitive.dev/docs/api/cli#discoveroptions), [`DiscoverResult`](https://uitive.dev/docs/api/cli#discoverresult)
- [Checking](https://uitive.dev/docs/api/cli#checking): [`BINDINGS`](https://uitive.dev/docs/api/cli#bindings), [`check`](https://uitive.dev/docs/api/cli#check), [`checkText`](https://uitive.dev/docs/api/cli#checktext), [`CONTRACT`](https://uitive.dev/docs/api/cli#contract), [`contractIn`](https://uitive.dev/docs/api/cli#contractin), [`loadModule`](https://uitive.dev/docs/api/cli#loadmodule), [`SCHEMA_LIMITS`](https://uitive.dev/docs/api/cli#schema_limits), [`Check`](https://uitive.dev/docs/api/cli#check-type), [`CheckOptions`](https://uitive.dev/docs/api/cli#checkoptions), [`CheckResult`](https://uitive.dev/docs/api/cli#checkresult), [`Coverage`](https://uitive.dev/docs/api/cli#coverage)

## Running the CLI

Source: [`commands.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/cli/src/commands.ts)

### run

Runs the CLI; returns the exit code.

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

Uses: [`RunContext`](https://uitive.dev/docs/api/cli#runcontext).

### RunContext

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

Uses: [`Writable`](https://uitive.dev/docs/api/cli#writable).

| Property | Type | Description |
| - | - | - |
| `version` | `string` | The version `--version` prints. |
| `out` | `Writable` | Where results go. |
| `err` | `Writable` | Where problems go. |

### Writable

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

| Property | Type | Description |
| - | - | - |
| `write()` | `(text: string) => unknown` | Writes the text. |

## Setting up

Source: [`detect.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/cli/src/detect.ts), [`folder.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/cli/src/folder.ts), [`init.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/cli/src/init.ts), [`templates.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/cli/src/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`](https://uitive.dev/docs/api/cli#detection), [`DetectOptions`](https://uitive.dev/docs/api/cli#detectoptions).

### detectText

A detection as text, one line per finding.

```ts
function detectText(found: Detection): string;
```

Uses: [`Detection`](https://uitive.dev/docs/api/cli#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`](https://uitive.dev/docs/api/cli#initoptions), [`InitResult`](https://uitive.dev/docs/api/cli#initresult).

### initText

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

```ts
function initText(result: InitResult): string;
```

Uses: [`InitResult`](https://uitive.dev/docs/api/cli#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.

| Property | Type | Description |
| - | - | - |
| `name` | `string` | The package or tool, such as `next`. |
| `version?` | `string` | Its 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`](https://uitive.dev/docs/api/cli#detected).

| Property | Type | Description |
| - | - | - |
| `root` | `string` | The package's folder, where Uitive is set up. |
| `name` | `string` | The package's name. |
| `packageManager` | `'pnpm' \| 'yarn' \| 'npm' \| 'bun'` | The package manager its lockfile shows. |
| `typescript` | `boolean` | Whether it uses TypeScript. |
| `ui` | `Detected \| null` | Its interface library, such as React. |
| `framework` | `Detected \| null` | Its framework, such as Next.js or Vite. |
| `router` | `Detected \| null` | Its router, such as React Router. |
| `designSystems` | `Detected[]` | Component libraries and styling, such as `@medusajs/ui` or `shadcn`. |
| `openapi` | `string[]` | 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. |
| `uitive` | `boolean` | Whether Uitive is already set up. |
| `packageManagerPin` | `string \| null` | The pinned package manager, such as `yarn@1.22.22`, from `packageManager`; nothing unless it names npm, pnpm, yarn or bun and a version. |
| `repository` | `string` | The 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. |
| `server` | `boolean` | Whether the application has its own server, where the model planner can run. |

### DetectOptions

What detection takes besides the folder.

| Property | Type | Description |
| - | - | - |
| `boundary?` | `string` | A 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.

| Property | Type | Default | Description |
| - | - | - | - |
| `cwd?` | `string` | `process.cwd()` | The project's root. |
| `openapi?` | `string` | | The API description to generate from; else the first one found. |
| `install?` | `boolean` | `true` | Installs the packages with the project's package manager. |
| `agents?` | `boolean` | `true` | Configures the coding agents found: MCP servers and the integration skill. |
| `mcp?` | `string` | 'npx -y | How agents start the MCP server: a command quoted as a shell would read it, or a JSON array of its words. |
| `packages?` | `string` | | A folder of package tarballs (`pnpm pack`) to install from, such as a local build. |
| `dir?` | `string` | the 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?` | `string` | | A 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`](https://uitive.dev/docs/api/cli#detection).

| Property | Type | Description |
| - | - | - |
| `detection` | `Detection` | What the project uses. |
| `written` | `string[]` | Files written, relative to the project. |
| `kept` | `string[]` | 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. |
| `next` | `string[]` | What to do next, in order. |

## API descriptions

Source: [`curation.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/cli/src/curation.ts), [`emit.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/cli/src/emit.ts), [`generate.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/cli/src/generate.ts), [`openapi.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/cli/src/openapi.ts), [`survey.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/cli/src/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`](https://uitive.dev/docs/api/cli#apiinventory), [`Curation`](https://uitive.dev/docs/api/cli#curation-type).

### 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`](https://uitive.dev/docs/api/cli#apiinventory), [`EmitOptions`](https://uitive.dev/docs/api/cli#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`](https://uitive.dev/docs/api/cli#generatesourcesoptions), [`GenerateSourcesResult`](https://uitive.dev/docs/api/cli#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`](https://uitive.dev/docs/api/cli#apiinventory), [`InventoryOptions`](https://uitive.dev/docs/api/cli#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`](https://uitive.dev/docs/api/cli#curation-type).

### picksOf

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

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

Uses: [`Curation`](https://uitive.dev/docs/api/cli#curation-type).

### 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`](https://uitive.dev/docs/api/cli#apiinventory), [`Survey`](https://uitive.dev/docs/api/cli#survey-type).

### surveySpec

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

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

Uses: [`SpecOptions`](https://uitive.dev/docs/api/cli#specoptions), [`Survey`](https://uitive.dev/docs/api/cli#survey-type).

### surveyText

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

```ts
function surveyText(value: Survey): string;
```

Uses: [`Survey`](https://uitive.dev/docs/api/cli#survey-type).

### ApiAction

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

Uses: [`ApiParam`](https://uitive.dev/docs/api/cli#apiparam), [`Effect`](https://uitive.dev/docs/api/core#effect), [`Op`](https://uitive.dev/docs/api/core#op), [`RestAction`](https://uitive.dev/docs/api/core#restaction), [`Skipped`](https://uitive.dev/docs/api/cli#skipped).

| Property | Type | Description |
| - | - | - |
| `id` | `string` | The action's ID, which the curation uses. |
| `label` | `string` | What people call it. |
| `description` | `string` | What it does, for people and models. |
| `operation` | `string` | The operation it runs, such as `POST /v1/refunds`. |
| `resource` | `string \| null` | The source the action works on, when there is one. |
| `effect` | `Effect` | What a run does to data: `read`, `write` or `destructive`. |
| `reason` | `string` | Why the effect was chosen. |
| `params` | `ApiParam[]` | What a run takes, besides the path's own params. |
| `skipped` | `Skipped[]` | Params left out, and why. |
| `invalidates` | `string[]` | Sources a run changes, so results that read them refresh. |
| `rest` | `RestAction` | How `restPerform` runs it. |
| `confirm?` | `string` | For 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`](https://uitive.dev/docs/api/core#fieldtype).

| Property | Type | Description |
| - | - | - |
| `name` | `string` | The field's name in the contract. |
| `type` | `FieldType` | What the value means, which decides how it shows and filters. |
| `nullable` | `boolean` | Whether rows may lack a value. |
| `description` | `string` | What the field holds, from the API description. |
| `values` | `string[]` | For enums. |
| `unit?` | `'iso' \| 's' \| 'ms'` | For times: an ISO string, or seconds or milliseconds since 1970. |
| `currency?` | `string` | For money: the field holding the currency. |
| `minor?` | `boolean` | For 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?` | `string` | For refs: the source referred to. |
| `pointer?` | `string` | For a value lifted from a nested object or renamed: where it is in a row. |
| `label?` | `string` | What 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`](https://uitive.dev/docs/api/cli#apiaction), [`ApiSource`](https://uitive.dev/docs/api/cli#apisource).

| Property | Type | Description |
| - | - | - |
| `title` | `string` | The API's title, from its description. |
| `version` | `string` | The API's version, from its description. |
| `server` | `string` | The base URL requests go to. |
| `sources` | `ApiSource[]` | Every source read. |
| `actions` | `ApiAction[]` | 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.

| Property | Type | Description |
| - | - | - |
| `required` | `boolean` | Whether a run needs it. |
| `name` | `string` | The field's name in the contract. |
| `type` | `FieldType` | What the value means, which decides how it shows and filters. |
| `nullable` | `boolean` | Whether rows may lack a value. |
| `description` | `string` | What the field holds, from the API description. |
| `values` | `string[]` | For enums. |
| `unit?` | `'iso' \| 's' \| 'ms'` | For times: an ISO string, or seconds or milliseconds since 1970. |
| `currency?` | `string` | For money: the field holding the currency. |
| `minor?` | `boolean` | For 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?` | `string` | For refs: the source referred to. |
| `pointer?` | `string` | For a value lifted from a nested object or renamed: where it is in a row. |
| `label?` | `string` | What 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`](https://uitive.dev/docs/api/cli#apifield), [`Op`](https://uitive.dev/docs/api/core#op), [`RestSource`](https://uitive.dev/docs/api/core#restsource), [`Skipped`](https://uitive.dev/docs/api/cli#skipped).

| Property | Description |
| - | - |
| `id` | The source's ID, which the curation uses. |
| `label` | What people call it. |
| `description` | What its rows are, for people and models. |
| `keywords` | Other words people use for it, so requests find it. |
| `schema` | The row schema's component name, when it has one. |
| `operation` | The operation that lists its rows, such as `GET /v1/charges`. |
| `key` | The field that identifies a row. |
| `title` | The field that names a row. |
| `summary` | The fields that sum a row up. |
| `fields` | The fields kept. |
| `extra` | Fields understood but left out to keep the source small; the curation can bring them back. |
| `skipped` | Fields left out, and why. |
| `capabilities` | What the endpoint does by itself: filters by field, sorting, search and paging. |
| `rest` | How `restFetch` reads it. |
| `notes` | Guesses 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`](https://uitive.dev/docs/api/cli#curationschema).

### CurationInput

A curation as written in `curation.json`.

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

Uses: [`curationSchema`](https://uitive.dev/docs/api/cli#curationschema).

### EmitOptions

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

| Property | Type | Default | Description |
| - | - | - | - |
| `from` | `string` | | Where 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.

| Property | Type | Default | Description |
| - | - | - | - |
| `out?` | `string` | 'api.generated.ts' in the project's Uitive folder | Where to write. |
| `dryRun?` | `boolean` | `false` | Reports without writing. |
| `spec` | `string` | | A path or URL to an OpenAPI 2.0, 3.0 or 3.1 description. |
| `cwd?` | `string` | `process.cwd()` | The project's root. |
| `curation?` | `string` | 'curation.json' in the project's Uitive folder | The 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.

| Property | Type | Description |
| - | - | - |
| `file` | `string` | The generated module. |
| `written` | `boolean` | Whether it was written; not on a dry run, or when something blocked it. |
| `sources` | `string[]` | The IDs of the sources generated. |
| `actions` | `string[]` | The IDs of the actions generated. |
| `problems` | `string[]` | What blocks generation: fix these first. |
| `notes` | `string[]` | Guesses worth checking. |

### InventoryOptions

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

| Property | Type | Description |
| - | - | - |
| `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.

| Property | Type | Description |
| - | - | - |
| `name` | `string` | What was left out, such as a field or an operation. |
| `reason` | `string` | Why, in a few words. |

### SpecOptions

Where an API description is, and its curation.

| Property | Type | Default | Description |
| - | - | - | - |
| `spec` | `string` | | A path or URL to an OpenAPI 2.0, 3.0 or 3.1 description. |
| `cwd?` | `string` | `process.cwd()` | The project's root. |
| `curation?` | `string` | 'curation.json' in the project's Uitive folder | The 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`](https://uitive.dev/docs/api/cli#surveysource).

| Property | Type | Description |
| - | - | - |
| `title` | `string` | The API's title. |
| `version` | `string` | The API's version. |
| `server` | `string` | The 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. |
| `advice` | `string[]` | What to do next, such as curating a large description. |
| `sources` | `SurveySource[]` | One line per source. |
| `unattached` | `string[]` | Actions on no source, such as `/v1/tokens`. |
| `skipped` | `Record<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.

| Property | Type | Description |
| - | - | - |
| `id` | `string` | The source's ID, as the curation names it. |
| `label` | `string` | What people call it. |
| `path` | `string` | The path that lists its rows. |
| `fields` | `number` | Fields kept, and fields understood but left out. |
| `extra` | `number` | How many fields were understood but left out. |
| `names` | `{ kept: string[]; extra: string[] }` | Their names, for the curation's `fields`, `labels` and `title`. |
| `filters` | `string[]` | Fields the endpoint filters by. |
| `search` | `boolean` | Whether the endpoint searches text. |
| `sort` | `string[]` | Fields the endpoint sorts by. |
| `pagination` | `string` | How the endpoint pages: `cursor`, `offset` or `none`. |
| `item` | `boolean` | Whether rows can be read one by key. |
| `actions` | `string[]` | The IDs of the actions on its rows. |
| `notes` | `string[]` | Guesses worth checking against the running API. |
| `included?` | `boolean` | Whether the curation keeps it, when there is one. |

## Native blocks

Source: [`blocks.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/cli/src/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`](https://uitive.dev/docs/api/cli#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`](https://uitive.dev/docs/api/cli#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`](https://uitive.dev/docs/api/cli#blocksresult).

### BlockProp

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

| Property | Type | Description |
| - | - | - |
| `name` | `string` | The prop's name. |
| `schema` | `string` | The zod schema, as code. |
| `description` | `string` | What the prop is, from its JSDoc. |
| `fallback?` | `string` | The 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`](https://uitive.dev/docs/api/cli#componentblock).

| Property | Type | Description |
| - | - | - |
| `blocks` | `ComponentBlock[]` | Each component, as a block. |
| `problems` | `string[]` | 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`](https://uitive.dev/docs/api/cli#blockprop).

| Property | Type | Description |
| - | - | - |
| `name` | `string` | The block's name in the contract, such as `orderSummary`. |
| `component` | `string` | The component's export name. |
| `file` | `string` | The file it comes from. |
| `label` | `string` | What people call it. |
| `description` | `string` | What it shows, for people and models. |
| `props` | `BlockProp[]` | 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.

| Property | Type | Default | Description |
| - | - | - | - |
| `components` | `readonly string[]` | | `file#Component` for each component. |
| `cwd?` | `string` | `process.cwd()` | The project's root. |
| `out?` | `string` | 'blocks.generated.ts' in the project's Uitive folder | Where to write. |
| `check?` | `boolean` | `false` | Reports whether the file is up to date, without writing it. |

## Discovering an application

Source: [`discover.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/cli/src/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`](https://uitive.dev/docs/api/cli#discoveroptions), [`DiscoverResult`](https://uitive.dev/docs/api/cli#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.

| Property | Type | Default | Description |
| - | - | - | - |
| `url` | `string` | | Where to start, such as `http://localhost:5173/`. |
| `cwd?` | `string` | `process.cwd()` | The project's root. |
| `pages?` | `number` | `30` | Most pages visited. |
| `perRoute?` | `number` | `2` | Most visits per route, such as two orders. |
| `storageState?` | `string` | | A Playwright storage state file holding a signed-in session. |
| `chrome?` | `boolean` | `false` | Uses the installed Chrome instead of Playwright's Chromium. |
| `out?` | `string` | 'discovery.json' in the project's Uitive folder | Where to write the discovery. |
| `contract?` | `string` | 'contract.ts' in the project's Uitive folder | Matches 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`](https://uitive.dev/docs/api/adapter#discovery).

| Property | Type | Description |
| - | - | - |
| `file` | `string` | Where the discovery was written. |
| `visited` | `string[]` | 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. |
| `discovery` | `Discovery` | What the pages suggest. |

## Checking

Source: [`check.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/cli/src/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`](https://uitive.dev/docs/api/cli#checkoptions), [`CheckResult`](https://uitive.dev/docs/api/cli#checkresult).

### checkText

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

```ts
function checkText(result: CheckResult): string;
```

Uses: [`CheckResult`](https://uitive.dev/docs/api/cli#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`](https://uitive.dev/docs/api/core#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.

| Property | Type | Description |
| - | - | - |
| `name` | `string` | The check: `contract`, `json`, `schemas` or `bindings`. |
| `ok` | `boolean` | Whether it passed. |
| `detail` | `string` | What 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.

| Property | Type | Default | Description |
| - | - | - | - |
| `cwd?` | `string` | `process.cwd()` | The project's root. |
| `contract?` | `string` | 'contract.ts' in the project's Uitive folder | The contract module. |
| `bindings?` | `string` | 'bindings.ts' in the project's Uitive folder | The bindings module. |

### CheckResult

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

Uses: [`Check`](https://uitive.dev/docs/api/cli#check-type), [`Coverage`](https://uitive.dev/docs/api/cli#coverage).

| Property | Type | Description |
| - | - | - |
| `ok` | `boolean` | Whether every check passed. |
| `checks` | `Check[]` | Each check, in order. |
| `warnings` | `string[]` | Worth fixing, but nothing breaks. |
| `coverage?` | `Coverage` | What the contract covers, once it loads. |

### Coverage

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

| Property | Type | Description |
| - | - | - |
| `sources` | `number` | Sources declared. |
| `actions` | `number` | Actions declared. |
| `runnable` | `number` | Actions with an effect, which run through `perform` after confirmation. |
| `performs` | `boolean` | Whether the bindings export `perform`, which interface actions may use too. |
| `routes` | `number` | Routes declared. |
| `pages` | `number` | Pages people can redesign. |
| `regions` | `number` | Regions: parts of the application as it already is. |
| `lists` | `number` | Lists, such as toolbars and menus. |
| `choices` | `number` | Choices, such as a theme. |
