@xyd-js/openapi2opencli 0.0.0-canary-4287eee-20260630010340

package/src/schema.ts

@@ -0,0 +1,110 @@
+import type { OpenAPIV3 } from 'openapi-types';
+
+export type Schema = OpenAPIV3.SchemaObject;
+
+const SCALAR_TYPES = new Set(['string', 'number', 'integer', 'boolean']);
+
+/** The scalar type of a schema, or null if it isn't a scalar. */
+export function scalarType(schema: Schema | undefined): string | null {
+  if (!schema) return null;
+  const t = typeof schema.type === 'string' ? schema.type : undefined;
+  if (t && SCALAR_TYPES.has(t)) return t;
+  return null;
+}
+
+export function isScalar(schema: Schema | undefined): boolean {
+  return scalarType(schema) !== null;
+}
+
+export function isBoolean(schema: Schema | undefined): boolean {
+  return scalarType(schema) === 'boolean';
+}
+
+export function isArray(schema: Schema | undefined): boolean {
+  return !!schema && schema.type === 'array';
+}
+
+export function arrayItems(schema: Schema | undefined): Schema | undefined {
+  if (!schema || schema.type !== 'array') return undefined;
+  return schema.items as Schema | undefined;
+}
+
+/** True when the schema is an object (explicit type or has properties). */
+export function isObjectSchema(schema: Schema | undefined): boolean {
+  if (!schema) return false;
+  if (schema.type === 'object') return true;
+  if (schema.properties && Object.keys(schema.properties).length > 0) return true;
+  return false;
+}
+
+/** Enum values rendered as strings (undefined when not an enum). */
+export function getEnum(schema: Schema | undefined): string[] | undefined {
+  if (!schema || !Array.isArray(schema.enum) || schema.enum.length === 0) return undefined;
+  return schema.enum.map((v) => String(v));
+}
+
+export function getDefault(schema: Schema | undefined): unknown {
+  if (!schema) return undefined;
+  return (schema as { default?: unknown }).default;
+}
+
+export function getDescription(schema: Schema | undefined): string | undefined {
+  return schema?.description;
+}
+
+/**
+ * Merge an `allOf` chain into a single object schema (properties + required).
+ * Non-allOf schemas are returned unchanged.
+ */
+export function mergeAllOf(schema: Schema | undefined): Schema | undefined {
+  if (!schema || !Array.isArray(schema.allOf) || schema.allOf.length === 0) return schema;
+
+  const merged: Schema = { type: 'object', properties: {}, required: [] };
+  const required = new Set<string>(Array.isArray(schema.required) ? schema.required : []);
+
+  for (const sub of schema.allOf as Schema[]) {
+    const resolved = mergeAllOf(sub) ?? sub;
+    if (resolved.properties) {
+      Object.assign(merged.properties as Record<string, unknown>, resolved.properties);
+    }
+    if (Array.isArray(resolved.required)) {
+      for (const r of resolved.required) required.add(r);
+    }
+  }
+  // Properties declared directly alongside allOf
+  if (schema.properties) {
+    Object.assign(merged.properties as Record<string, unknown>, schema.properties);
+  }
+  merged.required = [...required];
+  if (schema.description) merged.description = schema.description;
+  return merged;
+}
+
+/**
+ * Resolve a body schema to the object schema we can flatten, plus a flag telling
+ * whether the original was a non-trivial composition (oneOf/anyOf) we only
+ * partially captured.
+ */
+export function resolveObjectSchema(schema: Schema | undefined): { object?: Schema; complex: boolean } {
+  if (!schema) return { complex: false };
+
+  const merged = mergeAllOf(schema) ?? schema;
+  if (isObjectSchema(merged)) return { object: merged, complex: false };
+
+  // oneOf / anyOf at the body root: take the first object branch, mark complex.
+  const branches = (merged.oneOf || merged.anyOf) as Schema[] | undefined;
+  if (Array.isArray(branches)) {
+    for (const branch of branches) {
+      const b = mergeAllOf(branch) ?? branch;
+      if (isObjectSchema(b)) return { object: b, complex: true };
+    }
+    return { complex: true };
+  }
+
+  return { complex: false };
+}
+
+/** True for a binary/file string property (multipart uploads). */
+export function isBinary(schema: Schema | undefined): boolean {
+  return !!schema && schema.type === 'string' && schema.format === 'binary';
+}

package/src/security.ts

@@ -0,0 +1,43 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { XOpenApiSecurity } from '@xyd-js/opencli';
+
+import { screamingSnakeCase } from './naming';
+
+/**
+ * Map the document's `components.securitySchemes` to the OpenCLI `x-openapi`
+ * security shape, attaching a best-guess env var name a generated CLI reads
+ * the credential from.
+ */
+export function securitySchemesToXOpenApi(
+  doc: OpenAPIV3.Document,
+  cliName: string,
+  authEnvVar?: string,
+): XOpenApiSecurity[] {
+  const schemes = doc.components?.securitySchemes;
+  if (!schemes) return [];
+
+  const defaultEnv = authEnvVar || `${screamingSnakeCase(cliName)}_API_KEY`;
+  const out: XOpenApiSecurity[] = [];
+
+  for (const value of Object.values(schemes)) {
+    const scheme = value as OpenAPIV3.SecuritySchemeObject;
+    if (!scheme || typeof scheme !== 'object' || !('type' in scheme)) continue;
+
+    const entry: XOpenApiSecurity = { type: scheme.type, kind: 'other', envVar: defaultEnv };
+
+    if (scheme.type === 'http') {
+      entry.scheme = scheme.scheme;
+      if ('bearerFormat' in scheme && scheme.bearerFormat) entry.bearerFormat = scheme.bearerFormat;
+      const s = (scheme.scheme || '').toLowerCase();
+      entry.kind = s === 'basic' ? 'basic' : 'bearer';
+    } else if (scheme.type === 'apiKey') {
+      entry.in = scheme.in;
+      entry.name = scheme.name;
+      entry.kind = scheme.in === 'query' ? 'apiKey-query' : scheme.in === 'cookie' ? 'apiKey-cookie' : 'apiKey-header';
+    }
+
+    out.push(entry);
+  }
+
+  return out;
+}

package/src/surface.ts

@@ -0,0 +1,165 @@
+import type { Command, OpencliSpecJson, XOpenApiCommand } from '@xyd-js/opencli';
+
+// A canonical, language-agnostic "CLI surface" both our OpenCLI output and the
+// openai-cli Go source reduce to, so they can be diffed command-by-command.
+
+export type FlagKind = 'path' | 'query' | 'body' | 'header' | 'global' | 'unknown';
+
+export interface SurfaceFlag {
+  name: string; // kebab CLI flag name
+  required: boolean;
+  kind: FlagKind;
+}
+
+export interface SurfaceCommand {
+  path: string[]; // e.g. ["chat","completions","create"]
+  flags: SurfaceFlag[];
+}
+
+export interface CliSurface {
+  commands: SurfaceCommand[];
+}
+
+function locationToKind(location: string): FlagKind {
+  switch (location) {
+    case 'query':
+      return 'query';
+    case 'body':
+      return 'body';
+    case 'header':
+      return 'header';
+    case 'cookie':
+      return 'header';
+    default:
+      return 'unknown';
+  }
+}
+
+function sortFlags(flags: SurfaceFlag[]): SurfaceFlag[] {
+  return [...flags].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+const fromOption = (from: string | undefined): string | undefined =>
+  from && from.startsWith('option:') ? from.slice('option:'.length) : undefined;
+
+/** Classify an OpenCLI option's flag kind from the command's x-openapi binding. */
+function optionKind(optName: string, x: XOpenApiCommand | undefined): FlagKind {
+  const param = (x?.params || []).find((p) => fromOption(p.from) === optName && p.in !== 'path');
+  if (param) return locationToKind(param.in);
+  const inBody =
+    (x?.body?.properties || []).some((p) => fromOption(p.from) === optName) ||
+    fromOption(x?.body?.from) === optName;
+  return inBody ? 'body' : 'query';
+}
+
+/** Flatten an OpenCLI document to the canonical surface (path params become `path` flags). */
+export function opencliToSurface(spec: OpencliSpecJson): CliSurface {
+  const commands: SurfaceCommand[] = [];
+
+  const walk = (cmds: Command[], prefix: string[]) => {
+    for (const c of cmds) {
+      const path = [...prefix, c.name];
+      if (c.commands?.length) {
+        walk(c.commands, path);
+      } else if (c['x-openapi']) {
+        const x = c['x-openapi'] as XOpenApiCommand;
+        const flags: SurfaceFlag[] = [];
+        for (const a of c.arguments || []) {
+          flags.push({ name: a.name, required: a.required === true, kind: 'path' });
+        }
+        for (const opt of c.options || []) {
+          flags.push({ name: opt.name, required: opt.required === true, kind: optionKind(opt.name, x) });
+        }
+        commands.push({ path, flags: sortFlags(flags) });
+      }
+    }
+  };
+
+  walk(spec.commands || [], []);
+  return commands.length ? { commands } : { commands: [] };
+}
+
+const key = (path: string[]) => path.join(' ');
+
+export interface CommandDiff {
+  path: string[];
+  flagsOnlyOurs: string[];
+  flagsOnlyOracle: string[];
+  pathKindMismatch: string[]; // flags present on both but path-vs-non-path differs
+}
+
+export interface SurfaceDiff {
+  oracleCommandCount: number;
+  oursCommandCount: number;
+  commandsMatched: string[]; // present in both
+  commandsOnlyOracle: string[];
+  commandsOnlyOurs: string[];
+  perCommand: CommandDiff[]; // for matched commands with flag differences
+  l0Coverage: number; // |matched| / oracleCount
+  l1Coverage: number; // matched commands whose flags fully agree / oracleCount
+}
+
+export interface Allowlist {
+  /** Command paths (space-joined) to skip entirely. */
+  skipCommands?: string[];
+  /** Flag names that are expected extras on the oracle side for any command (e.g. pagination). */
+  oracleOnlyFlags?: string[];
+  /** Flag names that are expected extras on our side for any command. */
+  oursOnlyFlags?: string[];
+}
+
+/** Diff two surfaces command-by-command, applying an allowlist of known divergences. */
+export function diffSurfaces(ours: CliSurface, oracle: CliSurface, allow: Allowlist = {}): SurfaceDiff {
+  const skip = new Set(allow.skipCommands || []);
+  const oracleOnlyOk = new Set(allow.oracleOnlyFlags || []);
+  const oursOnlyOk = new Set(allow.oursOnlyFlags || []);
+
+  const oursByKey = new Map(ours.commands.map((c) => [key(c.path), c]));
+  const oracleByKey = new Map(oracle.commands.map((c) => [key(c.path), c]));
+
+  const oracleKeys = [...oracleByKey.keys()].filter((k) => !skip.has(k));
+  const matched: string[] = [];
+  const onlyOracle: string[] = [];
+  const onlyOurs: string[] = [];
+  const perCommand: CommandDiff[] = [];
+  let l1Clean = 0;
+
+  for (const k of oracleKeys) {
+    if (oursByKey.has(k)) matched.push(k);
+    else onlyOracle.push(k);
+  }
+  for (const k of oursByKey.keys()) {
+    if (!skip.has(k) && !oracleByKey.has(k)) onlyOurs.push(k);
+  }
+
+  for (const k of matched) {
+    const o = oursByKey.get(k)!;
+    const r = oracleByKey.get(k)!;
+    const oNames = new Map(o.flags.map((f) => [f.name, f]));
+    const rNames = new Map(r.flags.map((f) => [f.name, f]));
+
+    const flagsOnlyOurs = [...oNames.keys()].filter((n) => !rNames.has(n) && !oursOnlyOk.has(n));
+    const flagsOnlyOracle = [...rNames.keys()].filter((n) => !oNames.has(n) && !oracleOnlyOk.has(n));
+    const pathKindMismatch = [...oNames.keys()]
+      .filter((n) => rNames.has(n))
+      .filter((n) => (oNames.get(n)!.kind === 'path') !== (rNames.get(n)!.kind === 'path'));
+
+    if (flagsOnlyOurs.length || flagsOnlyOracle.length || pathKindMismatch.length) {
+      perCommand.push({ path: o.path, flagsOnlyOurs, flagsOnlyOracle, pathKindMismatch });
+    } else {
+      l1Clean++;
+    }
+  }
+
+  const oracleCount = oracleKeys.length || 1;
+  return {
+    oracleCommandCount: oracleKeys.length,
+    oursCommandCount: ours.commands.length,
+    commandsMatched: matched.sort(),
+    commandsOnlyOracle: onlyOracle.sort(),
+    commandsOnlyOurs: onlyOurs.sort(),
+    perCommand: perCommand.sort((a, b) => key(a.path).localeCompare(key(b.path))),
+    l0Coverage: matched.length / oracleCount,
+    l1Coverage: l1Clean / oracleCount,
+  };
+}

package/src/tree.ts

@@ -0,0 +1,78 @@
+import type { Command } from '@xyd-js/opencli';
+
+const ACTION_RANK: Record<string, number> = {
+  list: 0,
+  create: 1,
+  retrieve: 2,
+  get: 2,
+  update: 3,
+  modify: 3,
+  replace: 3,
+  delete: 4,
+};
+
+function leafRank(name: string): number {
+  return name in ACTION_RANK ? ACTION_RANK[name] : 100;
+}
+
+interface TreeNode {
+  name: string;
+  children: Map<string, TreeNode>;
+  leaves: Command[];
+  usedLeafNames: Set<string>;
+}
+
+function newNode(name: string): TreeNode {
+  return { name, children: new Map(), leaves: [], usedLeafNames: new Set() };
+}
+
+/**
+ * Builds the OpenCLI command tree from operations. Static path segments become
+ * nested resource nodes; leaf actions are attached to their resource node.
+ */
+export class CommandTree {
+  private root = newNode('');
+
+  insert(resourcePath: string[], leaf: Command): void {
+    let node = this.root;
+    for (const seg of resourcePath) {
+      let child = node.children.get(seg);
+      if (!child) {
+        child = newNode(seg);
+        node.children.set(seg, child);
+      }
+      node = child;
+    }
+    // Deduplicate leaf action names within the resource node.
+    let name = leaf.name;
+    if (node.usedLeafNames.has(name)) {
+      let i = 2;
+      while (node.usedLeafNames.has(`${name}-${i}`)) i++;
+      name = `${name}-${i}`;
+      leaf.name = name;
+    }
+    node.usedLeafNames.add(name);
+    node.leaves.push(leaf);
+  }
+
+  emit(): Command[] {
+    return this.emitChildren(this.root);
+  }
+
+  private emitChildren(node: TreeNode): Command[] {
+    const children = [...node.children.values()]
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .map((child) => this.emitNode(child));
+    const leaves = [...node.leaves].sort(
+      (a, b) => leafRank(a.name) - leafRank(b.name) || a.name.localeCompare(b.name),
+    );
+    return [...children, ...leaves];
+  }
+
+  private emitNode(node: TreeNode): Command {
+    const cmd: Command = { name: node.name };
+    const subs = this.emitChildren(node);
+    if (subs.length) cmd.commands = subs;
+    return cmd;
+  }
+}

package/src/types.ts

@@ -0,0 +1,86 @@
+export type Grouping = 'path' | 'tag' | 'operationId';
+export type BodyStrategy = 'flatten' | 'json' | 'hybrid';
+export type FlagCase = 'kebab' | 'camel';
+
+/**
+ * The five canonical action buckets derived from HTTP method + path shape.
+ * Override any of them via {@link OpenApi2OpenCliOptions.verbMap}.
+ */
+export interface VerbMap {
+  /** GET on a collection (path ends in a static segment). Default: "list". */
+  listCollection?: string;
+  /** GET on an item (path ends in `{param}`). Default: "retrieve". */
+  getItem?: string;
+  /** POST on a collection. Default: "create". */
+  createCollection?: string;
+  /** PUT/PATCH (and PUT on collection) on an item. Default: "update". */
+  updateItem?: string;
+  /** DELETE on an item. Default: "delete". */
+  deleteItem?: string;
+}
+
+export interface OpenApi2OpenCliOptions {
+  /** CLI name → `info.title`. Default: slug(doc.info.title). */
+  cliName?: string;
+  /** CLI version → `info.version`. Default: doc.info.version. */
+  version?: string;
+  /** Primary grouping signal. Only "path" is implemented in Stage A. Default: "path". */
+  grouping?: Grouping;
+  /** How request bodies become flags. Default: "hybrid". */
+  bodyStrategy?: BodyStrategy;
+  /** HTTP methods to include. Default: SUPPORTED_HTTP_METHODS from @xyd-js/openapi. */
+  includeMethods?: string[];
+  /** Map header (and cookie) params to options. Default: false. */
+  includeHeaders?: boolean;
+  /** Flag name casing. Default: "kebab". */
+  flagCase?: FlagCase;
+  /** Emit action aliases (e.g. "get" for "retrieve"). Default: true. */
+  actionAliases?: boolean;
+  /** Override the canonical action verbs. */
+  verbMap?: VerbMap;
+  /**
+   * Trailing static path segments (after a `{param}`) treated as custom actions
+   * rather than sub-resources, e.g. `/batches/{id}/cancel` → `batches cancel`.
+   * Provided as wire segments (matched case-insensitively, before kebab-casing).
+   * Defaults to a common set (see DEFAULT_CUSTOM_ACTION_VERBS).
+   */
+  customActionVerbs?: string[];
+  /** Only include operations whose path starts with one of these prefixes (test scoping). */
+  includePaths?: string[];
+  /**
+   * How deep to flatten nested body objects before falling back to a JSON-string flag.
+   * Default: 1 (only top-level scalar properties flatten).
+   */
+  maxBodyDepth?: number;
+  /**
+   * Environment variable a generated CLI reads the API credential from.
+   * Default: `${SCREAMING_SNAKE(cliName)}_API_KEY` (e.g. OPENAI_API_KEY).
+   */
+  authEnvVar?: string;
+}
+
+export const DEFAULT_CUSTOM_ACTION_VERBS = [
+  'cancel',
+  'submit',
+  'complete',
+  'expire',
+  'archive',
+  'unarchive',
+  'restore',
+  'validate',
+  'verify',
+  'refund',
+  'capture',
+  'void',
+  'pause',
+  'resume',
+  'start',
+  'stop',
+  'retry',
+  'finalize',
+  'confirm',
+  'approve',
+  'reject',
+  'publish',
+  'unpublish',
+];

package/src/unique.ts

@@ -0,0 +1,11 @@
+/** Allocate a unique name within `used`, suffixing `-2`, `-3`, … on collision. */
+export function uniqueName(base: string, used: Set<string>): string {
+  let name = base;
+  let i = 2;
+  while (used.has(name)) {
+    name = `${base}-${i}`;
+    i++;
+  }
+  used.add(name);
+  return name;
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "incremental": true,
+    "tsBuildInfoFile": "./dist/tsconfig.tsbuildinfo"
+  },
+  "include": ["index.ts", "src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+    entry: ['index.ts'],
+    format: ['esm', 'cjs'], // Output both ESM and CJS formats
+    target: 'node16', // Ensure compatibility with Node.js 16
+    dts: {
+        entry: 'index.ts', // Specify the entry for DTS
+        resolve: true, // Resolve external types
+    },
+    splitting: false, // Disable code splitting
+    sourcemap: true, // Generate source maps
+    clean: true, // Clean the output directory before each build
+    esbuildOptions: (options) => {
+        options.platform = 'node'; // Ensure the platform is set to Node.js
+        options.external = ['node:fs/promises']; // Mark 'node:fs/promises' as external
+        options.loader = { '.js': 'jsx' }; // Ensure proper handling of .js files
+    },
+});

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+    test: {
+        globals: true,
+        environment: 'node',
+    },
+})