@xyd-js/opencli2go 0.1.0-build.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@xyd-js/opencli2go",
+  "version": "0.1.0-build.0",
+  "description": "Generate a buildable Go CLI (urfave/cli v3) from an OpenCLI document with the x-openapi request binding",
+  "main": "./dist/index.js",
+  "type": "module",
+  "dependencies": {
+    "@xyd-js/opencli": "0.1.0-build.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.9.0",
+    "rimraf": "^3.0.2",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1",
+    "@xyd-js/openapi": "0.0.0-canary-4287eee-20260630010340",
+    "@xyd-js/openapi2opencli": "0.0.0-canary-4287eee-20260630010340"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "prebuild": "pnpm clean",
+    "build": "tsup",
+    "test": "vitest",
+    "ci:test": "vitest run",
+    "format": "bunx biome check --write src"
+  }
+}

package/src/command.ts

@@ -0,0 +1,58 @@
+import type { Command } from '@xyd-js/opencli';
+
+import { Imports, goBool, goFile, goSlice, goStr, goStruct, lit, type GoVal } from './golit';
+import { renderFlags } from './flags';
+import { renderHandler } from './handler';
+import { buildLeafModel } from './model';
+import { pascalCase, splitWords } from './naming';
+
+const CLI = 'github.com/urfave/cli/v3';
+
+function renderCommand(
+  command: Command,
+  pathNames: string[],
+  module: string,
+  imports: Imports,
+  handlers: string[],
+): GoVal {
+  imports.add(CLI);
+  const fields: [string, GoVal][] = [['Name', goStr(command.name)]];
+  if (command.aliases?.length) fields.push(['Aliases', goSlice('string', command.aliases.map(goStr))]);
+  if (command.description) fields.push(['Usage', goStr(command.description)]);
+  if (command.hidden) fields.push(['Hidden', goBool(true)]);
+
+  if (command.commands?.length) {
+    const subs = command.commands.map((sub) =>
+      renderCommand(sub, [...pathNames, sub.name], module, imports, handlers),
+    );
+    fields.push(['Commands', goSlice('*cli.Command', subs)]);
+  } else if (command['x-openapi']) {
+    const flags = renderFlags(buildLeafModel(command).flags);
+    if (flags.length) fields.push(['Flags', goSlice('cli.Flag', flags)]);
+    const handler = renderHandler(pathNames, command, module, imports);
+    fields.push(['Action', lit(handler.name)]);
+    handlers.push(handler.code);
+  }
+
+  return goStruct('cli.Command', fields, true);
+}
+
+export interface ResourceFile {
+  path: string;
+  content: string;
+  constructor: string;
+}
+
+/** Render one `pkg/cmd/<resource>.go` file for a top-level command + its subtree. */
+export function renderResourceFile(topCommand: Command, module: string): ResourceFile {
+  const imports = new Imports();
+  const handlers: string[] = [];
+  const struct = renderCommand(topCommand, [topCommand.name], module, imports, handlers);
+
+  const ctorName = `New${pascalCase(topCommand.name)}Command`;
+  const ctor = `func ${ctorName}() *cli.Command {\n\treturn ${struct(1)}\n}`;
+  const content = goFile('cmd', imports, [ctor, ...handlers]);
+
+  const fileBase = splitWords(topCommand.name).join('') || 'command';
+  return { path: `pkg/cmd/${fileBase}.go`, content, constructor: ctorName };
+}

package/src/flags.ts

@@ -0,0 +1,26 @@
+import { goBool, goSlice, goStr, goStruct, type GoVal } from './golit';
+import type { FlagModel, GoType } from './model';
+
+const FLAG_TYPE: Record<GoType, string> = {
+  bool: 'BoolFlag',
+  int: 'IntFlag',
+  float: 'FloatFlag',
+  slice: 'StringSliceFlag',
+  string: 'StringFlag',
+  json: 'StringFlag',
+  file: 'StringFlag',
+};
+
+export function renderFlag(f: FlagModel): GoVal {
+  const type = `cli.${FLAG_TYPE[f.goType]}`;
+  const fields: [string, GoVal][] = [['Name', goStr(f.flagName)]];
+  if (f.aliases.length) fields.push(['Aliases', goSlice('string', f.aliases.map(goStr))]);
+  if (f.description) fields.push(['Usage', goStr(f.description)]);
+  if (f.required) fields.push(['Required', goBool(true)]);
+  if (f.hidden) fields.push(['Hidden', goBool(true)]);
+  return goStruct(type, fields, true);
+}
+
+export function renderFlags(flags: FlagModel[]): GoVal[] {
+  return flags.map(renderFlag);
+}

package/src/golit.ts

@@ -0,0 +1,81 @@
+// Tiny Go-source string helpers (fern's CLI-generator style): just enough to
+// render struct/slice literals with correct indentation — not a full AST.
+
+const TAB = '\t';
+const pad = (n: number) => TAB.repeat(n);
+
+/** A value renderer: its first line is emitted inline; nested lines indent to `indent`. */
+export type GoVal = (indent: number) => string;
+
+/** A pre-rendered scalar (identifier, number, bool, expression). */
+export const lit = (s: string): GoVal => () => s;
+
+/** A Go double-quoted string literal (JSON escaping is valid Go for our content). */
+export const goStr = (s: string): GoVal => () => JSON.stringify(s);
+
+export const goBool = (b: boolean): GoVal => () => String(b);
+export const goInt = (n: number): GoVal => () => String(n);
+
+/** A struct literal: `Type{ Field: value, ... }` (prefix `&` when pointer). */
+export function goStruct(type: string, fields: [string, GoVal][], pointer = false): GoVal {
+  return (indent: number) => {
+    const head = `${pointer ? '&' : ''}${type}{`;
+    if (fields.length === 0) return `${head}}`;
+    let out = `${head}\n`;
+    for (const [k, v] of fields) {
+      out += `${pad(indent + 1)}${k}: ${v(indent + 1)},\n`;
+    }
+    out += `${pad(indent)}}`;
+    return out;
+  };
+}
+
+/** A slice literal: `[]Elem{ a, b, ... }`. */
+export function goSlice(elemType: string, elems: GoVal[]): GoVal {
+  return (indent: number) => {
+    if (elems.length === 0) return `[]${elemType}{}`;
+    let out = `[]${elemType}{\n`;
+    for (const e of elems) {
+      out += `${pad(indent + 1)}${e(indent + 1)},\n`;
+    }
+    out += `${pad(indent)}}`;
+    return out;
+  };
+}
+
+/** Render a top-level declaration value (indent 0). */
+export function render(v: GoVal): string {
+  return v(0);
+}
+
+/** Tracks the import paths a file needs. Qualifiers are implied by the emitted code. */
+export class Imports {
+  private paths = new Set<string>();
+
+  add(...importPaths: string[]): this {
+    for (const p of importPaths) this.paths.add(p);
+    return this;
+  }
+
+  get size(): number {
+    return this.paths.size;
+  }
+
+  render(): string {
+    if (this.paths.size === 0) return '';
+    const all = [...this.paths];
+    const std = all.filter((p) => !p.split('/')[0].includes('.')).sort();
+    const ext = all.filter((p) => p.split('/')[0].includes('.')).sort();
+    const groups = [std, ext].filter((g) => g.length > 0);
+    const block = groups.map((g) => g.map((p) => `${TAB}${JSON.stringify(p)}`).join('\n')).join('\n\n');
+    return `import (\n${block}\n)`;
+  }
+}
+
+/** Assemble a complete Go file: package clause + imports + declarations. */
+export function goFile(pkg: string, imports: Imports, decls: string[]): string {
+  const parts = [`package ${pkg}`];
+  if (imports.size > 0) parts.push(imports.render());
+  parts.push(...decls);
+  return `${parts.join('\n\n')}\n`;
+}

package/src/handler.ts

@@ -0,0 +1,151 @@
+import type { Command } from '@xyd-js/opencli';
+
+import type { Imports } from './golit';
+import { buildLeafModel, type GoType, type LeafModel } from './model';
+import { pascalCase } from './naming';
+
+const CLI = 'github.com/urfave/cli/v3';
+const q = (s: string) => JSON.stringify(s);
+
+function readExpr(flagName: string, t: GoType): string {
+  switch (t) {
+    case 'bool':
+      return `cmd.Bool(${q(flagName)})`;
+    case 'int':
+      return `cmd.Int(${q(flagName)})`;
+    case 'float':
+      return `cmd.Float(${q(flagName)})`;
+    case 'slice':
+      return `cmd.StringSlice(${q(flagName)})`;
+    default:
+      return `cmd.String(${q(flagName)})`; // string | json | file
+  }
+}
+
+function pathExpr(model: LeafModel, imports: Imports): string {
+  const segs = model.path.split(/(\{[^}]+\})/).filter((s) => s !== '');
+  const parts: string[] = [];
+  let lit = '';
+  for (const seg of segs) {
+    const m = seg.match(/^\{(.+)\}$/);
+    if (m) {
+      if (lit) {
+        parts.push(q(lit));
+        lit = '';
+      }
+      const a = model.pathArgs.find((p) => p.wireName === m[1]);
+      parts.push(`url.PathEscape(${a ? a.goVar : '""'})`);
+      imports.add('net/url');
+    } else {
+      lit += seg;
+    }
+  }
+  if (lit) parts.push(q(lit));
+  return parts.length ? parts.join(' + ') : '""';
+}
+
+/** Render the handler func for a leaf command from its x-openapi binding. */
+export function renderHandler(
+  pathNames: string[],
+  command: Command,
+  module: string,
+  imports: Imports,
+): { name: string; code: string } {
+  const model = buildLeafModel(command);
+  const name = `handle${pathNames.map(pascalCase).join('')}`;
+  imports.add('context', CLI, `${module}/internal/runtime`);
+
+  const lines: string[] = [];
+  const push = (s = '') => lines.push(s);
+
+  // Path params (positional args) — only declare the ones the path actually uses.
+  const pe = pathExpr(model, imports);
+  for (const a of model.pathArgs) {
+    if (pe.includes(`url.PathEscape(${a.goVar})`)) push(`${a.goVar} := cmd.Args().Get(${a.idx})`);
+  }
+  push(`path := ${pe}`);
+
+  // Query params.
+  const queryFlags = model.flags.filter((f) => f.location === 'query');
+  if (queryFlags.length) {
+    imports.add('net/url');
+    push('query := url.Values{}');
+    for (const f of queryFlags) {
+      const read = readExpr(f.flagName, f.goType);
+      let val = read;
+      if (f.goType !== 'string') {
+        val = `fmt.Sprint(${read})`;
+        imports.add('fmt');
+      }
+      push(`if cmd.IsSet(${q(f.flagName)}) {`);
+      push(`\tquery.Set(${q(f.wireName)}, ${val})`);
+      push('}');
+    }
+  }
+
+  // Header / cookie params.
+  const headerFlags = model.flags.filter((f) => f.location === 'header' || f.location === 'cookie');
+  if (headerFlags.length) {
+    imports.add('net/http');
+    push('headers := http.Header{}');
+    for (const f of headerFlags) {
+      const read = readExpr(f.flagName, f.goType);
+      let val = read;
+      if (f.goType !== 'string') {
+        val = `fmt.Sprint(${read})`;
+        imports.add('fmt');
+      }
+      push(`if cmd.IsSet(${q(f.flagName)}) {`);
+      push(`\theaders.Set(${q(f.wireName)}, ${val})`);
+      push('}');
+    }
+  }
+
+  // Body.
+  if (model.hasBody) {
+    imports.add('encoding/json');
+    if (model.bodyStyle === 'json' && model.bodyJsonOption) {
+      push('var bodyBytes []byte');
+      push(`if cmd.IsSet(${q(model.bodyJsonOption)}) {`);
+      push(`\tbodyBytes = []byte(cmd.String(${q(model.bodyJsonOption)}))`);
+      push('}');
+    } else {
+      push('body := map[string]any{}');
+      for (const f of model.flags.filter((x) => x.location === 'body')) {
+        push(`if cmd.IsSet(${q(f.flagName)}) {`);
+        if (f.goType === 'json') {
+          // Accept either JSON (objects/arrays) or a bare scalar: a string|object
+          // union field is commonly given a plain value, and an unparseable value
+          // must not abort the whole request.
+          push(`\traw := cmd.String(${q(f.flagName)})`);
+          push('\tvar v any');
+          push('\tif err := json.Unmarshal([]byte(raw), &v); err != nil {');
+          push('\t\tv = raw');
+          push('\t}');
+          push(`\tbody[${q(f.wireName)}] = v`);
+        } else {
+          push(`\tbody[${q(f.wireName)}] = ${readExpr(f.flagName, f.goType)}`);
+        }
+        push('}');
+      }
+      push('bodyBytes, err := json.Marshal(body)');
+      push('if err != nil {');
+      push('\treturn err');
+      push('}');
+    }
+  }
+
+  // Assemble the request.
+  push('req := runtime.Request{');
+  push(`\tMethod: ${q(model.method)},`);
+  push('\tPath: path,');
+  if (queryFlags.length) push('\tQuery: query,');
+  if (headerFlags.length) push('\tHeaders: headers,');
+  if (model.hasBody) push('\tBody: bodyBytes,');
+  push('}');
+  push('return runtime.Do(ctx, req)');
+
+  const body = lines.map((l) => `\t${l}`).join('\n');
+  const code = `func ${name}(ctx context.Context, cmd *cli.Command) error {\n${body}\n}`;
+  return { name, code };
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { opencli2go } from './project';
+export { writeProject } from './write';
+export type { Opencli2GoOptions } from './types';

package/src/main.ts

@@ -0,0 +1,30 @@
+import type { OpencliSpecJson } from '@xyd-js/opencli';
+
+import { Imports, goFile, goSlice, goStr, goStruct, lit, type GoVal } from './golit';
+
+const CLI = 'github.com/urfave/cli/v3';
+
+/** Render `cmd/<bin>/main.go`. */
+export function renderMain(
+  spec: OpencliSpecJson,
+  binName: string,
+  module: string,
+  constructors: string[],
+): string {
+  const imports = new Imports().add('context', 'log', 'os', CLI, `${module}/pkg/cmd`);
+
+  const fields: [string, GoVal][] = [['Name', goStr(binName)]];
+  const usage = spec.info?.summary || spec.info?.description;
+  if (usage) fields.push(['Usage', goStr(usage)]);
+  if (spec.info?.version) fields.push(['Version', goStr(spec.info.version)]);
+  fields.push(['Commands', goSlice('*cli.Command', constructors.map((c) => lit(`cmd.${c}()`)))]);
+
+  const app = goStruct('cli.Command', fields, true);
+  const body = `\tapp := ${app(1)}
+\tif err := app.Run(context.Background(), os.Args); err != nil {
+\t\tlog.Fatal(err)
+\t}`;
+  const fn = `func main() {\n${body}\n}`;
+
+  return goFile('main', imports, [fn]);
+}

package/src/model.ts

@@ -0,0 +1,147 @@
+import type { Command, Option, XOpenApiCommand } from '@xyd-js/opencli';
+
+import { goVar } from './naming';
+
+export type GoType = 'string' | 'int' | 'float' | 'bool' | 'slice' | 'json' | 'file';
+
+export interface PathArg {
+  goVar: string;
+  wireName: string;
+  idx: number;
+}
+
+export interface FlagModel {
+  flagName: string;
+  wireName: string;
+  location: 'query' | 'header' | 'cookie' | 'body';
+  goType: GoType;
+  required: boolean;
+  hidden: boolean;
+  aliases: string[];
+  description?: string;
+}
+
+export interface LeafModel {
+  method: string; // uppercase HTTP method
+  path: string;
+  pathArgs: PathArg[];
+  flags: FlagModel[];
+  hasBody: boolean;
+  bodyStyle?: string; // 'flatten' | 'json' | 'multipart'
+  bodyJsonOption?: string; // flag name when the whole body is one JSON option (style=json)
+}
+
+function fromToken(from: string | undefined, kind: 'option' | 'argument'): string | undefined {
+  if (!from) return undefined;
+  const [k, ...rest] = from.split(':');
+  return k === kind ? rest.join(':') : undefined;
+}
+
+function encodingToGoType(encoding: string | undefined): GoType | undefined {
+  switch (encoding) {
+    case 'integer':
+      return 'int';
+    case 'number':
+      return 'float';
+    case 'boolean':
+      return 'bool';
+    case 'array':
+      return 'slice';
+    case 'json':
+      return 'json';
+    case 'file':
+      return 'file';
+    case 'string':
+      return 'string';
+    default:
+      return undefined;
+  }
+}
+
+function optionGoType(opt: Option, encoding?: string): GoType {
+  if (!opt.arguments || opt.arguments.length === 0) return 'bool';
+  const fromEncoding = encodingToGoType(encoding);
+  if (fromEncoding) return fromEncoding;
+  const arg = opt.arguments[0];
+  if (arg.arity) return 'slice';
+  switch (arg.name) {
+    case 'integer':
+      return 'int';
+    case 'number':
+      return 'float';
+    case 'boolean':
+      return 'bool';
+    case 'json':
+      return 'json';
+    default:
+      return 'string';
+  }
+}
+
+/** Build the normalized request model for a leaf command from its x-openapi binding. */
+export function buildLeafModel(command: Command): LeafModel {
+  const x = command['x-openapi'] as XOpenApiCommand;
+  const params = x.params || [];
+  const body = x.body;
+
+  const pathArgs: PathArg[] = (command.arguments || []).map((arg, idx) => {
+    const param = params.find((p) => p.in === 'path' && fromToken(p.from, 'argument') === arg.name);
+    return { goVar: goVar(arg.name), wireName: param?.name ?? arg.name, idx };
+  });
+
+  const bodyPropByOption = new Map<string, string>(); // flagName -> encoding
+  const bodyWireByOption = new Map<string, string>(); // flagName -> wire name
+  for (const prop of body?.properties || []) {
+    const flag = fromToken(prop.from, 'option');
+    if (flag) {
+      bodyPropByOption.set(flag, prop.encoding || 'string');
+      bodyWireByOption.set(flag, prop.name);
+    }
+  }
+
+  const flags: FlagModel[] = [];
+  for (const opt of command.options || []) {
+    const paramEntry = params.find((p) => fromToken(p.from, 'option') === opt.name && p.in !== 'path');
+    let location: FlagModel['location'];
+    let wireName: string;
+    let encoding: string | undefined;
+
+    if (paramEntry) {
+      location = paramEntry.in as FlagModel['location'];
+      wireName = paramEntry.name;
+    } else if (bodyPropByOption.has(opt.name)) {
+      location = 'body';
+      wireName = bodyWireByOption.get(opt.name) ?? opt.name;
+      encoding = bodyPropByOption.get(opt.name);
+    } else {
+      location = 'query';
+      wireName = opt.name;
+    }
+
+    flags.push({
+      flagName: opt.name,
+      wireName,
+      location,
+      goType: optionGoType(opt, encoding),
+      required: opt.required === true,
+      hidden: opt.hidden === true,
+      aliases: opt.aliases || [],
+      description: opt.description,
+    });
+  }
+
+  const bodyStyle = body?.style;
+  const bodyJsonOption =
+    bodyStyle === 'json' ? fromToken(body?.from, 'option') ?? flags.find((f) => f.location === 'body')?.flagName : undefined;
+  const hasBody = !!body && (bodyStyle === 'json' || flags.some((f) => f.location === 'body'));
+
+  return {
+    method: (x.method || 'get').toUpperCase(),
+    path: x.path,
+    pathArgs,
+    flags,
+    hasBody,
+    bodyStyle,
+    bodyJsonOption,
+  };
+}

package/src/naming.ts

@@ -0,0 +1,44 @@
+/** Split an identifier (camel/snake/kebab/space) into lowercase words. */
+export function splitWords(input: string): string[] {
+  return input
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .split(/[\s_\-./]+/)
+    .map((w) => w.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+/** PascalCase, e.g. "chat-completions" → "ChatCompletions". */
+export function pascalCase(input: string): string {
+  return splitWords(input)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join('');
+}
+
+/** lowerCamelCase Go variable name, e.g. "store-id" → "storeID". */
+export function goVar(input: string): string {
+  const pascal = pascalCase(input);
+  if (!pascal) return 'arg';
+  let name = pascal.charAt(0).toLowerCase() + pascal.slice(1);
+  // Common Go initialism cleanup for ergonomics.
+  name = name.replace(/Id\b/g, 'ID').replace(/Url\b/g, 'URL').replace(/Api\b/g, 'API');
+  // Avoid Go keywords.
+  if (GO_KEYWORDS.has(name)) name = `${name}_`;
+  return name;
+}
+
+/** Slug for a binary / module name. */
+export function slug(input: string): string {
+  return splitWords(input).join('-').replace(/[^a-z0-9-]/g, '');
+}
+
+/** SCREAMING_SNAKE_CASE env-var prefix. */
+export function screamingSnakeCase(input: string): string {
+  return splitWords(input).join('_').toUpperCase().replace(/[^A-Z0-9_]/g, '');
+}
+
+const GO_KEYWORDS = new Set([
+  'break', 'case', 'chan', 'const', 'continue', 'default', 'defer', 'else', 'fallthrough',
+  'for', 'func', 'go', 'goto', 'if', 'import', 'interface', 'map', 'package', 'range',
+  'return', 'select', 'struct', 'switch', 'type', 'var',
+]);

package/src/project.ts

@@ -0,0 +1,36 @@
+import type { OpencliSpecJson } from '@xyd-js/opencli';
+
+import { renderResourceFile } from './command';
+import { renderMain } from './main';
+import { slug } from './naming';
+import { configGo, runtimeGo } from './runtime';
+import type { Opencli2GoOptions } from './types';
+
+/**
+ * Generate a buildable Go CLI project (urfave/cli v3) from an OpenCLI document.
+ * Pure: returns a virtual file map `{ relativePath: contents }`.
+ */
+export function opencli2go(spec: OpencliSpecJson, options: Opencli2GoOptions = {}): Record<string, string> {
+  const binName = options.binName ?? (slug(spec.info?.title || 'cli') || 'cli');
+  const module = options.modulePath ?? `example.com/${binName}`;
+  const goVersion = options.goVersion ?? '1.22';
+  const baseURL = options.baseURL ?? spec['x-openapi']?.servers?.[0] ?? '';
+
+  const files: Record<string, string> = {};
+
+  files['go.mod'] = `module ${module}\n\ngo ${goVersion}\n`;
+
+  const constructors: string[] = [];
+  for (const top of spec.commands || []) {
+    const resource = renderResourceFile(top, module);
+    files[resource.path] = resource.content;
+    constructors.push(resource.constructor);
+  }
+
+  files[`cmd/${binName}/main.go`] = renderMain(spec, binName, module, constructors);
+
+  files['internal/runtime/runtime.go'] = runtimeGo();
+  files['internal/runtime/config.go'] = configGo(spec, binName, baseURL);
+
+  return files;
+}