feat: reference CLI, generated UI API client, mock and conformance suite #1

2026-10-15T17:20:35Z

KofTwentyTwo commented

2026-10-15 17:20:35 +00:00

(Migrated from github.com)

Reference CLI, generated client, mock and conformance suite for the QQQ UI API

The first contents of this repo. They prove the QQQ UI API (/qqq/v1, 1.6.0: QRun-IO/qqq#1229) for CLI and TUI clients. Fixes QRun-IO/qqq#1039 (client-neutral contract suite).

@qrun-io/qqq-ui-api-client 1.6.0-rc.1:
- generated with openapi-typescript and openapi-fetch from the merged document: core 1.6.0, esb, health, alerts, assistant, collaboration, data-analysis, edi, quick-search, secured-data and sql-workbench. 190 operations, all with operationIds;
- device-authorization sign-in, refresh, UiApiError (BasicErrorResponseV1, with a fallback for pre-1.6.0 servers), and an SSE reader that sends a bearer token.
@qrun-io/qqq-cli 0.1.0-rc.1 (qqq): login (device code), logout, whoami, apps, tables [--app], query (criteria, --or, order, limit, fields), get, run (init/step/status loop), jobs, tail (realtime user:me plus channels). It talks only to /qqq/v1, with Authorization: Bearer and X-QQQ-Client: cli/....
@qrun-io/qqq-ui-api-conformance:
- a black-box, read-only suite: version vs document, operationIds, dangling refs, extension coverage, 401 for missing or forged tokens, the error schema, schema validation of metadata, table metadata, query, count, record and jobs, the realtime hello event, and traceId echo;
- qqq-dev-idp, a local OIDC provider (device grant, refresh, per-client issuers) for testing native clients.
scripts/merge-spec.mjs merges a core and extension documents (it fails on duplicate operations or ids and on conflicting schemas). npm run mock serves the merged document with Prism.
CI runs build, tests, the generated-client drift check and a Prism smoke test. Pushing a v* tag publishes the three packages to GitHub Packages.

Proven locally against the QQQ sample app built from #1229, with OAuth2 against qqq-dev-idp. login, whoami, apps, tables, filtered queries, get, an interactive process and tail all worked over Bearer JWTs. Against admin.kof22.com (UI API 1.5.0) the conformance suite already found real document bugs, which #1229 and the qbit updates fix: dangling collaboration refs, $ref: null, and the oneOf in the authentication values.

🤖 Generated with Claude Code

## Reference CLI, generated client, mock and conformance suite for the QQQ UI API The first contents of this repo. They prove the QQQ UI API (`/qqq/v1`, 1.6.0: QRun-IO/qqq#1229) for CLI and TUI clients. Fixes QRun-IO/qqq#1039 (client-neutral contract suite). - **`@qrun-io/qqq-ui-api-client` 1.6.0-rc.1**: - generated with openapi-typescript and openapi-fetch from the merged document: core 1.6.0, esb, health, alerts, assistant, collaboration, data-analysis, edi, quick-search, secured-data and sql-workbench. 190 operations, all with operationIds; - device-authorization sign-in, refresh, `UiApiError` (BasicErrorResponseV1, with a fallback for pre-1.6.0 servers), and an SSE reader that sends a bearer token. - **`@qrun-io/qqq-cli` 0.1.0-rc.1** (`qqq`): `login` (device code), `logout`, `whoami`, `apps`, `tables [--app]`, `query` (criteria, `--or`, order, limit, fields), `get`, `run` (init/step/status loop), `jobs`, `tail` (realtime `user:me` plus channels). It talks only to `/qqq/v1`, with `Authorization: Bearer` and `X-QQQ-Client: cli/...`. - **`@qrun-io/qqq-ui-api-conformance`**: - a black-box, read-only suite: version vs document, operationIds, dangling refs, extension coverage, 401 for missing or forged tokens, the error schema, schema validation of metadata, table metadata, query, count, record and jobs, the realtime hello event, and `traceId` echo; - `qqq-dev-idp`, a local OIDC provider (device grant, refresh, per-client issuers) for testing native clients. - `scripts/merge-spec.mjs` merges a core and extension documents (it fails on duplicate operations or ids and on conflicting schemas). `npm run mock` serves the merged document with Prism. - CI runs build, tests, the generated-client drift check and a Prism smoke test. Pushing a `v*` tag publishes the three packages to GitHub Packages. Proven locally against the QQQ sample app built from #1229, with OAuth2 against `qqq-dev-idp`. login, whoami, apps, tables, filtered queries, get, an interactive process and tail all worked over Bearer JWTs. Against admin.kof22.com (UI API 1.5.0) the conformance suite already found real document bugs, which #1229 and the qbit updates fix: dangling collaboration refs, `$ref: null`, and the `oneOf` in the authentication values. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: QRun-IO/qqq-cli#1