@xyd-js/opencli2go 0.1.0-build.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) LiveSession Sp.z.o.o
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,63 @@
+# @xyd-js/opencli2go
+
+Generates a **buildable, functional Go CLI** ([urfave/cli v3](https://github.com/urfave/cli))
+from an OpenCLI document ([`@xyd-js/opencli`](../xyd-opencli)). It reads the `x-openapi`
+request binding (emitted by [`@xyd-js/openapi2opencli`](../xyd-openapi2opencli)) so the
+generated commands make **real API requests** — not stubs.
+
+```ts
+import { opencli2go, writeProject } from '@xyd-js/opencli2go';
+
+const files = opencli2go(opencliDoc, { binName: 'openai' }); // pure: { path -> contents }
+await writeProject(files, './out');                          // the only fs-touching step
+```
+
+## Output (mirrors openai-cli's layout)
+
+```
+go.mod
+cmd/<bin>/main.go            # root cli.Command{ Commands: [...] } + app.Run
+pkg/cmd/<resource>.go        # one per top-level command; New<Resource>Command() + handlers
+internal/runtime/runtime.go  # generic HTTP client (vendored verbatim)
+internal/runtime/config.go   # generated: base URL + auth from x-openapi
+```
+
+## How it works
+
+A **templated emitter** (fern's CLI-generator pattern), not a Go AST:
+
+- The recursive `cli.Command` tree + typed flags are rendered with small Go-literal string
+  helpers; imports are a fixed/known set per file.
+- Each leaf **handler is generated from `x-openapi`**: positional path params → `url.PathEscape`,
+  query params → `url.Values`, body flags → a `map[string]any` marshalled to JSON (encodings:
+  `int`/`float`/`bool`/`[]string`/nested-`json`), then `runtime.Do(ctx, req)`.
+- Flag types follow the encoding: `cli.StringFlag` / `IntFlag` / `FloatFlag` / `BoolFlag` /
+  `StringSliceFlag`.
+- `internal/runtime` is a small generic HTTP client; `config.go` bakes the base URL
+  (overridable via `<BIN>_BASE_URL`) and `applyAuth` (bearer / apiKey-header / apiKey-query /
+  apiKey-cookie / basic), reading credentials from the env var named in `x-openapi.security`.
+
+`opencli2go` is pure (returns a file map); `writeProject` does the disk IO.
+
+## Options
+
+`binName` (default `slug(info.title)`), `modulePath` (default `example.com/<binName>`),
+`goVersion` (default `1.22`), `baseURL` (default first `x-openapi.servers`).
+
+## Tests
+
+Golden multi-file fixtures under `__fixtures__/<n>/` (`input.json` OpenCLI → `output/` Go tree):
+
+```bash
+pnpm --filter @xyd-js/opencli2go test                      # assert against committed goldens (no Go needed)
+REGEN=1 pnpm --filter @xyd-js/opencli2go test               # regenerate the output/ trees
+O2G_GO_SMOKE=1 pnpm --filter @xyd-js/opencli2go test        # opt-in: go mod tidy && go build ./... && go vet ./...
+```
+
+## Known limits (v1)
+
+- Positional args are read via `cmd.Args().Get(i)` (functional) rather than declared
+  `cli.Argument`s; declaring typed args (for `--help` surface parity with openai-cli) is a
+  Milestone-3 refinement validated against the oracle.
+- `multipart/form-data` file uploads pass the file path through (not yet streamed).
+- The runtime is generic (untyped JSON in/out); typed response models are future work.

package/__fixtures__/-2.complex.openai/admin__organization__admin-api-keys__create/input.json

@@ -0,0 +1,73 @@
+{
+  "opencli": "1.0.0",
+  "info": {
+    "title": "openai",
+    "version": "2.3.0"
+  },
+  "x-openapi": {
+    "servers": [
+      "https://api.openai.com/v1"
+    ],
+    "security": [
+      {
+        "type": "http",
+        "kind": "bearer",
+        "envVar": "OPENAI_API_KEY",
+        "scheme": "bearer"
+      },
+      {
+        "type": "http",
+        "kind": "bearer",
+        "envVar": "OPENAI_API_KEY",
+        "scheme": "bearer"
+      }
+    ]
+  },
+  "commands": [
+    {
+      "name": "organization",
+      "commands": [
+        {
+          "name": "admin-api-keys",
+          "commands": [
+            {
+              "name": "create",
+              "description": "Create an organization admin API key",
+              "options": [
+                {
+                  "name": "name",
+                  "group": "body",
+                  "required": true,
+                  "arguments": [
+                    {
+                      "name": "string"
+                    }
+                  ]
+                }
+              ],
+              "x-openapi": {
+                "method": "post",
+                "path": "/organization/admin_api_keys",
+                "operationId": "admin-api-keys-create",
+                "contentType": "application/json",
+                "body": {
+                  "style": "flatten",
+                  "contentType": "application/json",
+                  "properties": [
+                    {
+                      "name": "name",
+                      "from": "option:name",
+                      "jsonPath": "name",
+                      "encoding": "string",
+                      "required": true
+                    }
+                  ]
+                }
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/__fixtures__/-2.complex.openai/admin__organization__admin-api-keys__create/output.go

@@ -0,0 +1,51 @@
+package cmd
+
+import (
+	"context"
+	"encoding/json"
+
+	"example.com/openai/internal/runtime"
+	"github.com/urfave/cli/v3"
+)
+
+func NewOrganizationCommand() *cli.Command {
+	return &cli.Command{
+		Name: "organization",
+		Commands: []*cli.Command{
+			&cli.Command{
+				Name: "admin-api-keys",
+				Commands: []*cli.Command{
+					&cli.Command{
+						Name: "create",
+						Usage: "Create an organization admin API key",
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name: "name",
+								Required: true,
+							},
+						},
+						Action: handleOrganizationAdminApiKeysCreate,
+					},
+				},
+			},
+		},
+	}
+}
+
+func handleOrganizationAdminApiKeysCreate(ctx context.Context, cmd *cli.Command) error {
+	path := "/organization/admin_api_keys"
+	body := map[string]any{}
+	if cmd.IsSet("name") {
+		body["name"] = cmd.String("name")
+	}
+	bodyBytes, err := json.Marshal(body)
+	if err != nil {
+		return err
+	}
+	req := runtime.Request{
+		Method: "POST",
+		Path: path,
+		Body: bodyBytes,
+	}
+	return runtime.Do(ctx, req)
+}

package/__fixtures__/-2.complex.openai/admin__organization__admin-api-keys__create/recorded.json

@@ -0,0 +1,19 @@
+{
+  "args": [
+    "organization",
+    "admin-api-keys",
+    "create",
+    "--name",
+    "EXAMPLE"
+  ],
+  "request": {
+    "method": "post",
+    "path": "/organization/admin_api_keys",
+    "query": [],
+    "bodyFields": [
+      "name"
+    ],
+    "auth": "bearer",
+    "contentType": "application/json"
+  }
+}

package/__fixtures__/-2.complex.openai/admin__organization__admin-api-keys__delete/input.json

@@ -0,0 +1,61 @@
+{
+  "opencli": "1.0.0",
+  "info": {
+    "title": "openai",
+    "version": "2.3.0"
+  },
+  "x-openapi": {
+    "servers": [
+      "https://api.openai.com/v1"
+    ],
+    "security": [
+      {
+        "type": "http",
+        "kind": "bearer",
+        "envVar": "OPENAI_API_KEY",
+        "scheme": "bearer"
+      },
+      {
+        "type": "http",
+        "kind": "bearer",
+        "envVar": "OPENAI_API_KEY",
+        "scheme": "bearer"
+      }
+    ]
+  },
+  "commands": [
+    {
+      "name": "organization",
+      "commands": [
+        {
+          "name": "admin-api-keys",
+          "commands": [
+            {
+              "name": "delete",
+              "description": "Delete an organization admin API key",
+              "arguments": [
+                {
+                  "name": "key-id",
+                  "required": true
+                }
+              ],
+              "x-openapi": {
+                "method": "delete",
+                "path": "/organization/admin_api_keys/{key_id}",
+                "operationId": "admin-api-keys-delete",
+                "params": [
+                  {
+                    "in": "path",
+                    "name": "key_id",
+                    "from": "argument:key-id",
+                    "required": true
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/__fixtures__/-2.complex.openai/admin__organization__admin-api-keys__delete/output.go

@@ -0,0 +1,37 @@
+package cmd
+
+import (
+	"context"
+	"net/url"
+
+	"example.com/openai/internal/runtime"
+	"github.com/urfave/cli/v3"
+)
+
+func NewOrganizationCommand() *cli.Command {
+	return &cli.Command{
+		Name: "organization",
+		Commands: []*cli.Command{
+			&cli.Command{
+				Name: "admin-api-keys",
+				Commands: []*cli.Command{
+					&cli.Command{
+						Name: "delete",
+						Usage: "Delete an organization admin API key",
+						Action: handleOrganizationAdminApiKeysDelete,
+					},
+				},
+			},
+		},
+	}
+}
+
+func handleOrganizationAdminApiKeysDelete(ctx context.Context, cmd *cli.Command) error {
+	keyID := cmd.Args().Get(0)
+	path := "/organization/admin_api_keys/" + url.PathEscape(keyID)
+	req := runtime.Request{
+		Method: "DELETE",
+		Path: path,
+	}
+	return runtime.Do(ctx, req)
+}

package/__fixtures__/-2.complex.openai/admin__organization__admin-api-keys__delete/recorded.json

@@ -0,0 +1,15 @@
+{
+  "args": [
+    "organization",
+    "admin-api-keys",
+    "delete",
+    "EXAMPLE"
+  ],
+  "request": {
+    "method": "delete",
+    "path": "/organization/admin_api_keys/{key_id}",
+    "query": [],
+    "bodyFields": [],
+    "auth": "bearer"
+  }
+}

package/__fixtures__/-2.complex.openai/admin__organization__admin-api-keys__list/input.json

@@ -0,0 +1,97 @@
+{
+  "opencli": "1.0.0",
+  "info": {
+    "title": "openai",
+    "version": "2.3.0"
+  },
+  "x-openapi": {
+    "servers": [
+      "https://api.openai.com/v1"
+    ],
+    "security": [
+      {
+        "type": "http",
+        "kind": "bearer",
+        "envVar": "OPENAI_API_KEY",
+        "scheme": "bearer"
+      },
+      {
+        "type": "http",
+        "kind": "bearer",
+        "envVar": "OPENAI_API_KEY",
+        "scheme": "bearer"
+      }
+    ]
+  },
+  "commands": [
+    {
+      "name": "organization",
+      "commands": [
+        {
+          "name": "admin-api-keys",
+          "commands": [
+            {
+              "name": "list",
+              "description": "List organization API keys",
+              "options": [
+                {
+                  "name": "after",
+                  "group": "query",
+                  "arguments": [
+                    {
+                      "name": "string"
+                    }
+                  ]
+                },
+                {
+                  "name": "order",
+                  "group": "query",
+                  "arguments": [
+                    {
+                      "name": "string",
+                      "acceptedValues": [
+                        "asc",
+                        "desc"
+                      ]
+                    }
+                  ]
+                },
+                {
+                  "name": "limit",
+                  "group": "query",
+                  "arguments": [
+                    {
+                      "name": "integer"
+                    }
+                  ]
+                }
+              ],
+              "x-openapi": {
+                "method": "get",
+                "path": "/organization/admin_api_keys",
+                "operationId": "admin-api-keys-list",
+                "params": [
+                  {
+                    "in": "query",
+                    "name": "after",
+                    "from": "option:after"
+                  },
+                  {
+                    "in": "query",
+                    "name": "order",
+                    "from": "option:order"
+                  },
+                  {
+                    "in": "query",
+                    "name": "limit",
+                    "from": "option:limit"
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/__fixtures__/-2.complex.openai/admin__organization__admin-api-keys__list/output.go

@@ -0,0 +1,59 @@
+package cmd
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+
+	"example.com/openai/internal/runtime"
+	"github.com/urfave/cli/v3"
+)
+
+func NewOrganizationCommand() *cli.Command {
+	return &cli.Command{
+		Name: "organization",
+		Commands: []*cli.Command{
+			&cli.Command{
+				Name: "admin-api-keys",
+				Commands: []*cli.Command{
+					&cli.Command{
+						Name: "list",
+						Usage: "List organization API keys",
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name: "after",
+							},
+							&cli.StringFlag{
+								Name: "order",
+							},
+							&cli.IntFlag{
+								Name: "limit",
+							},
+						},
+						Action: handleOrganizationAdminApiKeysList,
+					},
+				},
+			},
+		},
+	}
+}
+
+func handleOrganizationAdminApiKeysList(ctx context.Context, cmd *cli.Command) error {
+	path := "/organization/admin_api_keys"
+	query := url.Values{}
+	if cmd.IsSet("after") {
+		query.Set("after", cmd.String("after"))
+	}
+	if cmd.IsSet("order") {
+		query.Set("order", cmd.String("order"))
+	}
+	if cmd.IsSet("limit") {
+		query.Set("limit", fmt.Sprint(cmd.Int("limit")))
+	}
+	req := runtime.Request{
+		Method: "GET",
+		Path: path,
+		Query: query,
+	}
+	return runtime.Do(ctx, req)
+}

package/__fixtures__/-2.complex.openai/admin__organization__admin-api-keys__list/recorded.json

@@ -0,0 +1,14 @@
+{
+  "args": [
+    "organization",
+    "admin-api-keys",
+    "list"
+  ],
+  "request": {
+    "method": "get",
+    "path": "/organization/admin_api_keys",
+    "query": [],
+    "bodyFields": [],
+    "auth": "bearer"
+  }
+}

package/__fixtures__/-2.complex.openai/admin__organization__admin-api-keys__retrieve/input.json

@@ -0,0 +1,97 @@
+{
+  "opencli": "1.0.0",
+  "info": {
+    "title": "openai",
+    "version": "2.3.0"
+  },
+  "x-openapi": {
+    "servers": [
+      "https://api.openai.com/v1"
+    ],
+    "security": [
+      {
+        "type": "http",
+        "kind": "bearer",
+        "envVar": "OPENAI_API_KEY",
+        "scheme": "bearer"
+      },
+      {
+        "type": "http",
+        "kind": "bearer",
+        "envVar": "OPENAI_API_KEY",
+        "scheme": "bearer"
+      }
+    ]
+  },
+  "commands": [
+    {
+      "name": "organization",
+      "commands": [
+        {
+          "name": "admin-api-keys",
+          "commands": [
+            {
+              "name": "list",
+              "description": "List organization API keys",
+              "options": [
+                {
+                  "name": "after",
+                  "group": "query",
+                  "arguments": [
+                    {
+                      "name": "string"
+                    }
+                  ]
+                },
+                {
+                  "name": "order",
+                  "group": "query",
+                  "arguments": [
+                    {
+                      "name": "string",
+                      "acceptedValues": [
+                        "asc",
+                        "desc"
+                      ]
+                    }
+                  ]
+                },
+                {
+                  "name": "limit",
+                  "group": "query",
+                  "arguments": [
+                    {
+                      "name": "integer"
+                    }
+                  ]
+                }
+              ],
+              "x-openapi": {
+                "method": "get",
+                "path": "/organization/admin_api_keys",
+                "operationId": "admin-api-keys-list",
+                "params": [
+                  {
+                    "in": "query",
+                    "name": "after",
+                    "from": "option:after"
+                  },
+                  {
+                    "in": "query",
+                    "name": "order",
+                    "from": "option:order"
+                  },
+                  {
+                    "in": "query",
+                    "name": "limit",
+                    "from": "option:limit"
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/__fixtures__/-2.complex.openai/admin__organization__admin-api-keys__retrieve/output.go

@@ -0,0 +1,59 @@
+package cmd
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+
+	"example.com/openai/internal/runtime"
+	"github.com/urfave/cli/v3"
+)
+
+func NewOrganizationCommand() *cli.Command {
+	return &cli.Command{
+		Name: "organization",
+		Commands: []*cli.Command{
+			&cli.Command{
+				Name: "admin-api-keys",
+				Commands: []*cli.Command{
+					&cli.Command{
+						Name: "list",
+						Usage: "List organization API keys",
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name: "after",
+							},
+							&cli.StringFlag{
+								Name: "order",
+							},
+							&cli.IntFlag{
+								Name: "limit",
+							},
+						},
+						Action: handleOrganizationAdminApiKeysList,
+					},
+				},
+			},
+		},
+	}
+}
+
+func handleOrganizationAdminApiKeysList(ctx context.Context, cmd *cli.Command) error {
+	path := "/organization/admin_api_keys"
+	query := url.Values{}
+	if cmd.IsSet("after") {
+		query.Set("after", cmd.String("after"))
+	}
+	if cmd.IsSet("order") {
+		query.Set("order", cmd.String("order"))
+	}
+	if cmd.IsSet("limit") {
+		query.Set("limit", fmt.Sprint(cmd.Int("limit")))
+	}
+	req := runtime.Request{
+		Method: "GET",
+		Path: path,
+		Query: query,
+	}
+	return runtime.Do(ctx, req)
+}

package/__fixtures__/-2.complex.openai/admin__organization__admin-api-keys__retrieve/recorded.json

@@ -0,0 +1,14 @@
+{
+  "args": [
+    "organization",
+    "admin-api-keys",
+    "list"
+  ],
+  "request": {
+    "method": "get",
+    "path": "/organization/admin_api_keys",
+    "query": [],
+    "bodyFields": [],
+    "auth": "bearer"
+  }
+}