@oriva/cli 0.1.0

package/dist/output.js

@@ -0,0 +1,36 @@
+export function renderEnvelope(result) {
+    const ok = result.status >= 200 && result.status < 300;
+    // Body may be a structured error object (e.g. { error: {...} }) or a success payload.
+    // Heuristic: if body has an `error` field AND we got a 4xx/5xx, surface that as `error`.
+    let data = null;
+    let error = null;
+    if (ok) {
+        data = result.body;
+    }
+    else {
+        error =
+            result.body &&
+                typeof result.body === 'object' &&
+                'error' in result.body
+                ? result.body.error
+                : result.body;
+    }
+    return {
+        ok,
+        status: result.status,
+        data,
+        error,
+        request_id: result.request_id,
+        url: result.url,
+        method: result.method,
+    };
+}
+export function renderOutput(result, opts) {
+    if (opts.json) {
+        return JSON.stringify(renderEnvelope(result), null, 2);
+    }
+    if (opts.raw) {
+        return typeof result.body === 'string' ? result.body : JSON.stringify(result.body);
+    }
+    return JSON.stringify(result.body, null, 2);
+}

package/dist/parseArgs.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Argv parser for the `oriva` CLI.
+ *
+ * Ported from ultra-cli (~/ultra-network/packages/ultra-cli/src/parseArgs.ts).
+ * Adds three new global flags: --json, --profile, --api-key.
+ *
+ * Grammar:
+ *   oriva                                     → { kind: 'help' }
+ *   oriva --help | -h                         → { kind: 'help' }
+ *   oriva --version | -V                      → { kind: 'version' }
+ *   oriva <command>                           → { kind: 'command', command, flags }
+ *   oriva <command> --help                    → { kind: 'command-help', command }
+ *   oriva <command> --flag=value …            → flags['flag'] = 'value'
+ *   oriva <command> --flag value …            → flags['flag'] = 'value'
+ *   oriva <command> --flag …                  → flags['flag'] = true (boolean)
+ *   oriva <command> --body=@path | -          → bodySource = { kind:'file', path } / { kind:'stdin' }
+ *   oriva <command> --body=<json>             → bodySource = { kind:'inline', text }
+ *   oriva <command> --repeated=a --repeated=b → flags['repeated'] = ['a','b']
+ *
+ * Global flags (apply before OR after the command — forgiving UX):
+ *   --spec=<url|path>     Override OpenAPI spec source
+ *   --base-url=<url>      Override server base URL
+ *   --show-status         Print HTTP status to stderr alongside body
+ *   --raw                 Print response body unchanged (no JSON pretty-print)
+ *   --json                Emit envelope { ok, status, data, error, request_id }
+ *   --quiet               Suppress progress lines on stderr
+ *   --profile=<name>      Select a config-file profile
+ *   --api-key=<key>       Override ORIVA_API_KEY for this invocation
+ */
+export interface ParsedArgs {
+    kind: 'help' | 'command-help' | 'command' | 'version';
+    command?: string;
+    flags: Record<string, string | string[] | boolean>;
+    bodySource?: {
+        kind: 'inline';
+        text: string;
+    } | {
+        kind: 'file';
+        path: string;
+    } | {
+        kind: 'stdin';
+    };
+    global: {
+        spec?: string;
+        baseUrl?: string;
+        showStatus?: boolean;
+        raw?: boolean;
+        json?: boolean;
+        quiet?: boolean;
+        profile?: string;
+        apiKey?: string;
+    };
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+//# sourceMappingURL=parseArgs.d.ts.map

package/dist/parseArgs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseArgs.d.ts","sourceRoot":"","sources":["../src/parseArgs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,GAAG,SAAS,CAAC;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC;IACnD,UAAU,CAAC,EACP;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAChC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAC9B;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;IACtB,MAAM,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,GAAG,CAAC,EAAE,OAAO,CAAC;QACd,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAaD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAiGpD"}

package/dist/parseArgs.js

@@ -0,0 +1,150 @@
+/**
+ * Argv parser for the `oriva` CLI.
+ *
+ * Ported from ultra-cli (~/ultra-network/packages/ultra-cli/src/parseArgs.ts).
+ * Adds three new global flags: --json, --profile, --api-key.
+ *
+ * Grammar:
+ *   oriva                                     → { kind: 'help' }
+ *   oriva --help | -h                         → { kind: 'help' }
+ *   oriva --version | -V                      → { kind: 'version' }
+ *   oriva <command>                           → { kind: 'command', command, flags }
+ *   oriva <command> --help                    → { kind: 'command-help', command }
+ *   oriva <command> --flag=value …            → flags['flag'] = 'value'
+ *   oriva <command> --flag value …            → flags['flag'] = 'value'
+ *   oriva <command> --flag …                  → flags['flag'] = true (boolean)
+ *   oriva <command> --body=@path | -          → bodySource = { kind:'file', path } / { kind:'stdin' }
+ *   oriva <command> --body=<json>             → bodySource = { kind:'inline', text }
+ *   oriva <command> --repeated=a --repeated=b → flags['repeated'] = ['a','b']
+ *
+ * Global flags (apply before OR after the command — forgiving UX):
+ *   --spec=<url|path>     Override OpenAPI spec source
+ *   --base-url=<url>      Override server base URL
+ *   --show-status         Print HTTP status to stderr alongside body
+ *   --raw                 Print response body unchanged (no JSON pretty-print)
+ *   --json                Emit envelope { ok, status, data, error, request_id }
+ *   --quiet               Suppress progress lines on stderr
+ *   --profile=<name>      Select a config-file profile
+ *   --api-key=<key>       Override ORIVA_API_KEY for this invocation
+ */
+const GLOBAL_FLAGS = new Set([
+    'spec',
+    'base-url',
+    'show-status',
+    'raw',
+    'json',
+    'quiet',
+    'profile',
+    'api-key',
+]);
+export function parseArgs(argv) {
+    const flags = {};
+    const global = {};
+    let command;
+    let bodySource;
+    let wantsHelp = false;
+    let wantsVersion = false;
+    const tokens = [...argv];
+    // Phase 1: peel off global flags + locate the command.
+    const remaining = [];
+    while (tokens.length) {
+        const t = tokens.shift();
+        if (t === '--help' || t === '-h') {
+            wantsHelp = true;
+            continue;
+        }
+        if (t === '--version' || t === '-V') {
+            wantsVersion = true;
+            continue;
+        }
+        const m = /^--([^=]+)(?:=(.*))?$/.exec(t);
+        if (m && GLOBAL_FLAGS.has(m[1])) {
+            const key = m[1];
+            // For boolean-style globals, allow `--status` (no value) → true.
+            // For value-style globals, consume the next token if not flag-shaped.
+            const isBooleanGlobal = ['show-status', 'raw', 'json', 'quiet'].includes(key);
+            let value;
+            if (m[2] !== undefined) {
+                value = m[2];
+            }
+            else if (!isBooleanGlobal && tokens[0] !== undefined && !tokens[0].startsWith('--')) {
+                value = tokens.shift();
+            }
+            else {
+                value = 'true';
+            }
+            if (key === 'spec')
+                global.spec = value;
+            else if (key === 'base-url')
+                global.baseUrl = value;
+            else if (key === 'show-status')
+                global.showStatus = value === 'true' || value === '';
+            else if (key === 'raw')
+                global.raw = value === 'true' || value === '';
+            else if (key === 'json')
+                global.json = value === 'true' || value === '';
+            else if (key === 'quiet')
+                global.quiet = value === 'true' || value === '';
+            else if (key === 'profile')
+                global.profile = value;
+            else if (key === 'api-key')
+                global.apiKey = value;
+            continue;
+        }
+        if (!command && !t.startsWith('-')) {
+            command = t;
+            continue;
+        }
+        remaining.push(t);
+    }
+    if (wantsVersion)
+        return { kind: 'version', flags, global };
+    if (!command)
+        return { kind: 'help', flags, global };
+    if (wantsHelp)
+        return { kind: 'command-help', command, flags, global };
+    // Phase 2: parse per-command flags from `remaining`.
+    while (remaining.length) {
+        const t = remaining.shift();
+        const m = /^--([^=]+)(?:=(.*))?$/.exec(t);
+        if (!m) {
+            throw new Error(`Unexpected positional argument: ${t}`);
+        }
+        const key = m[1];
+        let value = m[2];
+        if (value === undefined) {
+            if (remaining[0] !== undefined && !remaining[0].startsWith('--')) {
+                value = remaining.shift();
+            }
+        }
+        if (key === 'body') {
+            if (value === undefined)
+                throw new Error('--body requires a value');
+            if (value === '-')
+                bodySource = { kind: 'stdin' };
+            else if (value.startsWith('@'))
+                bodySource = { kind: 'file', path: value.slice(1) };
+            else
+                bodySource = { kind: 'inline', text: value };
+            continue;
+        }
+        if (value === undefined) {
+            flags[key] = true;
+            continue;
+        }
+        const existing = flags[key];
+        if (existing === undefined) {
+            flags[key] = value;
+        }
+        else if (Array.isArray(existing)) {
+            existing.push(value);
+        }
+        else if (typeof existing === 'string') {
+            flags[key] = [existing, value];
+        }
+        else {
+            flags[key] = value;
+        }
+    }
+    return { kind: 'command', command, flags, bodySource, global };
+}

package/dist/readBody.d.ts

@@ -0,0 +1,3 @@
+import type { ParsedArgs } from './parseArgs.js';
+export declare function readBody(bodySource: ParsedArgs['bodySource'], stdin?: NodeJS.ReadableStream): Promise<unknown>;
+//# sourceMappingURL=readBody.d.ts.map

package/dist/readBody.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readBody.d.ts","sourceRoot":"","sources":["../src/readBody.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,wBAAsB,QAAQ,CAC5B,UAAU,EAAE,UAAU,CAAC,YAAY,CAAC,EACpC,KAAK,GAAE,MAAM,CAAC,cAA8B,GAC3C,OAAO,CAAC,OAAO,CAAC,CAgBlB"}

package/dist/readBody.js

@@ -0,0 +1,35 @@
+/**
+ * Resolve a --body source (inline JSON, file path, stdin) to a parsed value.
+ * Returns undefined if no body was provided.
+ *
+ * Ported verbatim from ultra-cli (~/ultra-network/packages/ultra-cli/src/readBody.ts).
+ */
+import { readFile } from 'node:fs/promises';
+export async function readBody(bodySource, stdin = process.stdin) {
+    if (!bodySource)
+        return undefined;
+    let text;
+    if (bodySource.kind === 'inline') {
+        text = bodySource.text;
+    }
+    else if (bodySource.kind === 'file') {
+        text = await readFile(bodySource.path, 'utf8');
+    }
+    else {
+        text = await collectStream(stdin);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`--body is not valid JSON: ${msg}`);
+    }
+}
+async function collectStream(s) {
+    const chunks = [];
+    for await (const chunk of s) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}

package/dist/shared/httpExecutor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Execute an operation against the live HTTP API.
+ *
+ * Ported from ultra-api-client (~/ultra-network/packages/ultra-api-client/src/httpExecutor.ts);
+ * key deviation: API-key regex swapped to Oriva's `oriva_pk_(live|test)_*` format
+ * matching @oriva/sdk's documented convention.
+ */
+import type { ExtractedOperation } from './types.js';
+export interface ExecuteOptions {
+    baseUrl: string;
+    apiKey?: string;
+    userAgent?: string;
+}
+export interface ExecuteResult {
+    status: number;
+    body: unknown;
+    request_id?: string;
+    /** Reconstructed for envelope output. */
+    url: string;
+    method: string;
+}
+export declare function executeOperation(op: ExtractedOperation, args: Record<string, unknown>, opts: ExecuteOptions, fetchImpl?: typeof fetch): Promise<ExecuteResult>;
+//# sourceMappingURL=httpExecutor.d.ts.map

package/dist/shared/httpExecutor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpExecutor.d.ts","sourceRoot":"","sources":["../../src/shared/httpExecutor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,EAAE,cAAc,EACpB,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,aAAa,CAAC,CA4DxB"}

package/dist/shared/httpExecutor.js

@@ -0,0 +1,56 @@
+const ORIVA_KEY_PATTERN = /^oriva_pk_(live|test)_[A-Za-z0-9_-]+$/;
+export async function executeOperation(op, args, opts, fetchImpl = fetch) {
+    let path = op.pathTemplate;
+    for (const name of op.pathParams) {
+        const v = args[name];
+        if (v === undefined || v === null) {
+            throw new Error(`Missing required path parameter: ${name}`);
+        }
+        path = path.replace(`{${name}}`, encodeURIComponent(String(v)));
+    }
+    const url = new URL(opts.baseUrl.replace(/\/$/, '') + path);
+    for (const name of op.queryParams) {
+        const v = args[name];
+        if (v === undefined || v === null)
+            continue;
+        if (Array.isArray(v)) {
+            v.forEach((item) => url.searchParams.append(name, String(item)));
+        }
+        else {
+            url.searchParams.set(name, String(v));
+        }
+    }
+    const headers = {
+        Accept: 'application/json',
+        'User-Agent': opts.userAgent || 'oriva-cli/0.1.0',
+    };
+    if (opts.apiKey) {
+        // Reject malformed keys BEFORE handing to fetch — runtime Headers.append
+        // echoes invalid values in error messages, which leaks the key into logs/
+        // transcripts. Validate first; throw a sanitized error if bad.
+        if (!ORIVA_KEY_PATTERN.test(opts.apiKey)) {
+            throw new Error('Invalid API key format (expected `oriva_pk_live_…` or `oriva_pk_test_…`). ' +
+                'Check that ORIVA_API_KEY contains exactly one key value — ' +
+                'multi-line input or a grep with multiple matches will fail here.');
+        }
+        headers.Authorization = `Bearer ${opts.apiKey}`;
+    }
+    let body;
+    if (op.hasBody && args.body !== undefined) {
+        headers['Content-Type'] = op.bodyContentType || 'application/json';
+        body = typeof args.body === 'string' ? args.body : JSON.stringify(args.body);
+    }
+    const method = op.method.toUpperCase();
+    const res = await fetchImpl(url.toString(), { method, headers, body });
+    const contentType = res.headers.get('content-type') || '';
+    const parsed = contentType.includes('application/json')
+        ? await res.json().catch(() => null)
+        : await res.text();
+    return {
+        status: res.status,
+        body: parsed,
+        request_id: res.headers.get('x-request-id') ?? undefined,
+        url: url.toString(),
+        method,
+    };
+}

package/dist/shared/loadSpec.d.ts

@@ -0,0 +1,24 @@
+export interface MinimalOpenApiDoc {
+    openapi: string;
+    info?: {
+        title?: string;
+        version?: string;
+    };
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    paths?: Record<string, Record<string, unknown>>;
+    components?: {
+        schemas?: Record<string, unknown>;
+    };
+}
+/**
+ * Resolve the bundled-snapshot path. The snapshot lives at the package root.
+ * This function self-locates from its own module URL (dist/shared/loadSpec.js
+ * → ../../openapi-snapshot.json) so it doesn't depend on the caller's CWD or
+ * import-meta location.
+ */
+export declare function bundledSnapshotPath(): string;
+export declare function loadSpec(source: string): Promise<MinimalOpenApiDoc>;
+//# sourceMappingURL=loadSpec.d.ts.map

package/dist/shared/loadSpec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadSpec.d.ts","sourceRoot":"","sources":["../../src/shared/loadSpec.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAChD,UAAU,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;CACpD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAI5C;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAUzE"}

package/dist/shared/loadSpec.js

@@ -0,0 +1,33 @@
+/**
+ * Load an OpenAPI document from a URL, local file path, or the bundled
+ * snapshot that ships inside the CLI tarball.
+ *
+ * Ported from ultra-api-client (~/ultra-network/packages/ultra-api-client/src/loadSpec.ts);
+ * adds the bundled-snapshot default so `oriva <op>` has sub-second cold start
+ * with zero network — critical for agents calling in tight loops.
+ */
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Resolve the bundled-snapshot path. The snapshot lives at the package root.
+ * This function self-locates from its own module URL (dist/shared/loadSpec.js
+ * → ../../openapi-snapshot.json) so it doesn't depend on the caller's CWD or
+ * import-meta location.
+ */
+export function bundledSnapshotPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // dist/shared/loadSpec.js -> ../../openapi-snapshot.json
+    return resolve(here, '..', '..', 'openapi-snapshot.json');
+}
+export async function loadSpec(source) {
+    if (/^https?:\/\//.test(source)) {
+        const res = await fetch(source);
+        if (!res.ok) {
+            throw new Error(`Failed to fetch OpenAPI spec from ${source}: HTTP ${res.status}`);
+        }
+        return (await res.json());
+    }
+    const text = await readFile(source, 'utf8');
+    return JSON.parse(text);
+}

package/dist/shared/toolGenerator.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Walk an OpenAPI 3.1 document and emit one ExtractedOperation per
+ * (method, path) pair.
+ *
+ * Ported from ultra-api-client; key deviations:
+ *   - Drop `toSnake()` — keep `operationId` verbatim (camelCase) so command
+ *     names match SDK function names 1:1 (`oriva listProfiles`).
+ *   - Carry `tags` through onto ExtractedOperation for tag-grouped help.
+ */
+import type { MinimalOpenApiDoc } from './loadSpec.js';
+import type { ExtractedOperation } from './types.js';
+export declare function extractOperations(doc: MinimalOpenApiDoc, opts?: {
+    tagFilter?: string[];
+}): ExtractedOperation[];
+//# sourceMappingURL=toolGenerator.d.ts.map

package/dist/shared/toolGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolGenerator.d.ts","sourceRoot":"","sources":["../../src/shared/toolGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA8CrD,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,iBAAiB,EACtB,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,GAClC,kBAAkB,EAAE,CAqEtB"}

package/dist/shared/toolGenerator.js

@@ -0,0 +1,89 @@
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'];
+function deriveToolName(method, path) {
+    // Fallback for ops without operationId — derive camelCase verb + segments
+    // (e.g. `get /trips/{id}` -> `getTripsById`).
+    const segments = path
+        .replace(/^\/+/, '')
+        .split('/')
+        .map((seg, i) => {
+        const param = /^\{(.+)\}$/.exec(seg);
+        const word = param ? `By${capitalize(param[1])}` : seg;
+        return i === 0 ? word : capitalize(word.replace(/^by/i, 'By'));
+    });
+    return (method +
+        segments
+            .map(capitalize)
+            .join('')
+            .replace(/[^A-Za-z0-9]/g, ''));
+}
+function capitalize(s) {
+    return s ? s[0].toUpperCase() + s.slice(1) : s;
+}
+export function extractOperations(doc, opts = {}) {
+    const out = [];
+    const tagFilter = (opts.tagFilter ?? []).map((t) => t.toLowerCase());
+    for (const [pathTemplate, pathItem] of Object.entries(doc.paths ?? {})) {
+        for (const method of HTTP_METHODS) {
+            const op = pathItem[method];
+            if (!op)
+                continue;
+            const opTags = (op.tags ?? []).map((t) => t);
+            const lowerTags = opTags.map((t) => t.toLowerCase());
+            if (tagFilter.length && !lowerTags.some((t) => tagFilter.includes(t)))
+                continue;
+            const params = op.parameters ?? [];
+            const pathParams = params.filter((p) => p.in === 'path').map((p) => p.name);
+            const queryParams = params.filter((p) => p.in === 'query').map((p) => p.name);
+            const properties = {};
+            const required = [];
+            for (const p of params) {
+                if (p.in !== 'path' && p.in !== 'query')
+                    continue;
+                const schema = (p.schema ?? { type: 'string' });
+                properties[p.name] = p.description ? { ...schema, description: p.description } : schema;
+                if (p.required)
+                    required.push(p.name);
+            }
+            let hasBody = false;
+            let bodyContentType;
+            if (op.requestBody?.content) {
+                const ct = Object.keys(op.requestBody.content)[0];
+                if (ct) {
+                    bodyContentType = ct;
+                    const bodySchema = op.requestBody.content[ct].schema;
+                    if (bodySchema) {
+                        properties.body = bodySchema;
+                        hasBody = true;
+                        if (op.requestBody.required)
+                            required.push('body');
+                    }
+                }
+            }
+            const inputSchema = {
+                type: 'object',
+                properties,
+                ...(required.length ? { required } : {}),
+            };
+            out.push({
+                name: op.operationId ? op.operationId : deriveToolName(method, pathTemplate),
+                description: op.summary || op.description || `${method.toUpperCase()} ${pathTemplate}`,
+                method,
+                pathTemplate,
+                inputSchema,
+                pathParams,
+                queryParams,
+                hasBody,
+                bodyContentType,
+                tags: opTags,
+            });
+        }
+    }
+    // Defensive de-dup — operationId collisions silently shadow each other otherwise.
+    const seen = new Set();
+    return out.filter((o) => {
+        if (seen.has(o.name))
+            return false;
+        seen.add(o.name);
+        return true;
+    });
+}

package/dist/shared/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Internal shape for an operation extracted from OpenAPI.
+ *
+ * Ported from ultra-api-client (~/ultra-network/packages/ultra-api-client/src/types.ts).
+ * Adds `tags: string[]` so the CLI can group commands by OpenAPI tag rather than
+ * by path segment.
+ */
+export interface ExtractedOperation {
+    /** Tool/command name surfaced to the consumer. Matches SDK function names 1:1 (camelCase). */
+    name: string;
+    /** Human-readable summary. */
+    description: string;
+    /** HTTP method. */
+    method: 'get' | 'post' | 'put' | 'patch' | 'delete';
+    /** Path template with `{param}` placeholders. */
+    pathTemplate: string;
+    /** Combined JSON Schema for the operation's input. */
+    inputSchema: Record<string, unknown>;
+    /** Param-name buckets so the executor knows where each input goes. */
+    pathParams: string[];
+    queryParams: string[];
+    hasBody: boolean;
+    bodyContentType?: string;
+    /** OpenAPI tags. First tag drives help-grouping. */
+    tags: string[];
+}
+export interface ServerConfig {
+    spec: string;
+    baseUrl?: string;
+    apiKey?: string;
+    tagFilter?: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,8FAA8F;IAC9F,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB;IACnB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACpD,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,sEAAsE;IACtE,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB"}

package/dist/shared/types.js

@@ -0,0 +1 @@
+export {};