cli: noun-verb grammar on the kernel, output formats, JMESPath, CRUD, api escape hatch

qqq <noun> <verb> for table (list, describe, query, count, get, create, update, delete, export),
process (list, describe, run) and job (list, get, logs, cancel, retry), with the 0.1 flat
commands kept as hidden aliases. Global --output json|table|text|csv|yaml, --json, --query
(JMESPath), --fields, --yes and --trace work before or after the subcommand. Filters take
--where, --group (AND/OR with parentheses), --or, --order, --filter-json, --print-filter and
--count; queries page with --limit, --skip and --all. qqq api <operationId> calls any
operation from the generated index (--path, --param, --body-json, --form, --bytes, --out).
Exit codes: 2 usage and bad filters, 3 auth, 4 unreachable or rate limited, 5 not found,
6 validation, 70 server error. The realtime stream can carry a session cookie for tail.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
james.maesandClaude Fable 5.1 committed 2026-10-31 17:03:18 -05:00
1 parent a0cc4d8be2
commit 8ed694cd2f
25 files changed
+1273 -407

No files matched your search

+73
View File
@@ -0,0 +1,73 @@
/*
* Copyright 2026 QRun.IO, Inc.
* Licensed under the Apache License, Version 2.0 (see LICENSE).
*/
/**
* Writes packages/core/src/api/operations.ts from the merged OpenAPI document: one entry per
* operation (id, method, path, path and query parameters, body content types), so the kernel can
* call any operation by id without the generated types, and the CLI can complete operation ids.
*
* Usage: node scripts/gen-operations.mjs [spec.json] [out.ts]
*/
import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
import { dirname } from 'node:path'
const [specPath = 'packages/ui-api-client/openapi/qqq-v1.json', outPath = 'packages/core/src/api/operations.ts'] = process.argv.slice(2)
const spec = JSON.parse(readFileSync(specPath, 'utf8'))
const operations = []
for (const [path, item] of Object.entries(spec.paths)) {
for (const method of ['get', 'post', 'put', 'patch', 'delete']) {
const op = item[method]
if (!op) continue
const params = [...(item.parameters ?? []), ...(op.parameters ?? [])]
operations.push({
id: op.operationId,
method: method.toUpperCase(),
path,
summary: (op.summary ?? op.description ?? '').split('\n')[0].slice(0, 120),
tag: (op.tags ?? [])[0] ?? '',
pathParams: params.filter((p) => p.in === 'path').map((p) => p.name),
queryParams: params.filter((p) => p.in === 'query').map((p) => p.name),
bodyTypes: Object.keys(op.requestBody?.content ?? {}),
})
}
}
operations.sort((a, b) => a.id.localeCompare(b.id))
const lines = [
'/*',
' * Copyright 2026 QRun.IO, Inc.',
' * Licensed under the Apache License, Version 2.0 (see LICENSE).',
' */',
'',
`// Generated by scripts/gen-operations.mjs from the UI API ${spec.info.version} document. Do not edit.`,
'',
'export interface OperationInfo {',
' id: string',
" method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'",
' path: string',
' summary: string',
' tag: string',
' pathParams: string[]',
' queryParams: string[]',
' bodyTypes: string[]',
'}',
'',
`export const UI_API_DOCUMENT_VERSION = ${JSON.stringify(spec.info.version)}`,
'',
'export const OPERATIONS: OperationInfo[] = [',
...operations.map((o) => ` ${JSON.stringify(o)},`),
']',
'',
'const byId = new Map(OPERATIONS.map((o) => [o.id, o]))',
'',
'/** The operation with this id, or undefined. */',
'export function operation(id: string): OperationInfo | undefined {',
' return byId.get(id)',
'}',
'',
]
mkdirSync(dirname(outPath), { recursive: true })
writeFileSync(outPath, lines.join('\n'))
console.log(`${operations.length} operations -> ${outPath}`)