fix: correct OpenAPI generated commands

[0xpolarzero]

Overview

Fix correctness bugs in commands generated from OpenAPI specs.

generateCommands() turns OpenAPI operations into incur commands: path parameters become positional args, query parameters and JSON object body properties become options, and run() calls the provided fetch handler. Several edge cases did not preserve that contract.

Issue

Generated commands could differ from the spec in these user-visible ways:

• path item metadata was treated as fake commands, and path-level parameters were ignored by real operations;
• OpenAPI 3.2 additionalOperations commands were not generated;
• path parameter values were interpolated without URL encoding;
• positional path args followed parameter-array order instead of URL-template order;
• optional JSON object bodies still required body fields even when the body was omitted;
• required JSON object bodies sent no body when no body fields were provided;
• generated boolean parameters used JavaScript truthiness instead of strict boolean parsing.

Tests failing before fix

Path-level parameters

src/Openapi.test.ts

const spec = {
  paths: {
    '/orgs/{orgId}/users': {
      parameters: [{ name: 'orgId', in: 'path', required: true, schema: { type: 'string' } }],
      get: { operationId: 'listOrgUsers' },
    },
  },
}

expect(commands.has('parameters__orgs__orgId__users')).toBe(false)
// Before: true

expect(commands.has('summary__orgs__orgId__users')).toBe(false)
// Before: true for path item metadata like summary

expect(commands.get('listOrgUsers')!.args!.safeParse({ orgId: 'acme' }).success).toBe(true)
// Before: commands.get('listOrgUsers')!.args was undefined

Path item metadata such as parameters and summary should not become commands, and the real get operation should inherit orgId.

OpenAPI 3.2 additional operations

src/Openapi.test.ts

const spec = {
  paths: {
    '/widgets/{id}/actions': {
      parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
      additionalOperations: {
        Search: {
          operationId: 'searchWidgetActions',
          parameters: [{ name: 'cursor', in: 'query', schema: { type: 'string' } }],
        },
      },
    },
  },
}

expect(commands.has('searchWidgetActions')).toBe(true)
// Before: false

await commands.get('searchWidgetActions')!.run({
  args: { id: 'a b' },
  options: { cursor: 'next' },
})
expect(calls[0]).toEqual({
  method: 'Search',
  path: '/widgets/a%20b/actions',
  query: { cursor: 'next' },
})
// Before: no command existed, so this run was impossible.

OpenAPI 3.2 uses additionalOperations for custom operation methods. The generated command should exist, inherit path-level parameters, preserve the custom method key, and build the request URL normally.

Path parameter encoding

src/Openapi.test.ts

await commands.get('getUser')!.run({
  args: { id: 'a/b' },
  options: {},
})

expect(calls).toEqual(['/users/a%2Fb'])
// Before: ['/users/a/b']

Path parameter values are data, not path structure. A slash inside a parameter value must be encoded.

Path arg order

src/Openapi.test.ts

const spec = {
  paths: {
    '/users/{userId}/repos/{repoId}': {
      get: {
        operationId: 'getRepo',
        // Intentionally reversed compared to the URL template.
        parameters: [
          { name: 'repoId', in: 'path', required: true, schema: { type: 'string' } },
          { name: 'userId', in: 'path', required: true, schema: { type: 'string' } },
        ],
      },
    },
  },
}

expect(help).toContain('Usage: test api getRepo <userId> <repoId>')
// Before: 'Usage: test api getRepo <repoId> <userId>'

expect(json(output)).toEqual({ path: '/users/alice/repos/toolkit' })
// Command: test api getRepo alice toolkit --format json
// Before: { path: '/users/toolkit/repos/alice' }

Users type positional path args in URL order. The parameter array order can differ from the path template, so generated args must follow the template.

Optional JSON object bodies

src/Openapi.test.ts

const requestBody = {
  required: false,
  content: {
    'application/json': {
      schema: {
        type: 'object',
        required: ['name'],
        properties: { name: { type: 'string' }, age: { type: 'number' } },
      },
    },
  },
}

expect(options.safeParse({}).success).toBe(true)
// Before: false

expect(options.safeParse({ age: 42 }).success).toBe(false)

If the request body is optional, omitting every body field should be valid. But if any body field is provided, the body schema's required properties still apply.

src/Openapi.test.ts

expect(options.safeParse({}).success).toBe(true)
// Before: false

expect(options.safeParse({ dryRun: false }).success).toBe(false)

A defaulted property should not make an omitted optional body count as provided. Explicitly providing that property should still count as providing the body.

Required JSON object bodies with no provided fields

src/Openapi.test.ts

await commands.get('updateProfile')!.run({ options: {} })
await commands.get('createEmpty')!.run({ options: {} })

expect(bodies).toEqual(['{}', '{}'])
// Before: ['', '']

If the object body itself is required, the generated request still needs to send {} when no body fields are provided.

Strict OpenAPI booleans

src/Openapi.test.ts

const spec = {
  paths: {
    '/users': {
      get: {
        operationId: 'listUsers',
        parameters: [{ name: 'active', in: 'query', schema: { type: 'boolean' } }],
      },
    },
  },
}

expect(options.parse({ active: 'false' }).active).toBe(false)
// Before: true

expect(options.safeParse({ active: 'yes' }).success).toBe(false)
// Before: true

OpenAPI boolean parameters should accept only real booleans and the CLI strings "true" and "false". They should not use JavaScript truthiness.

Boolean enum parameters

src/Openapi.test.ts

const schema = { type: 'boolean', enum: [true, false] }

expect(Parser.parse(['--active'], { options }).options).toEqual({ active: true })
// Before: throws "Missing value for flag: --active"

expect(Parser.parse(['--active=false'], { options }).options).toEqual({ active: false })
// Before: validation failed because "false" was still a string

z.fromJSONSchema() represents boolean enums as a union of boolean literals, not as ZodBoolean. The generator recognizes the common [true, false] enum as a normal strict boolean option.

Regression guards

These tests cover behavior that could regress while fixing the bugs above:

• src/Openapi.test.ts: OpenAPI 3.2 query operations inherit path-level parameters.
• src/Openapi.test.ts: operation-level parameters override path-level parameters with the same in:name.
• src/Openapi.test.ts: query options do not make an optional request body count as provided.
• src/Openapi.test.ts: required body properties still fail validation when omitted from a required JSON object body.
• src/Openapi.test.ts: unsupported non-object request bodies do not get a fake {} body.
• src/Openapi.test.ts: a single-value boolean enum is not treated as a general boolean flag.
• src/Openapi.test.ts: mixed literal enums are not collapsed into booleans.
• src/Openapi.test.ts: transformed generated booleans render as flags in help.
• src/Openapi.test.ts: transformed generated booleans do not consume the next completion word.
• src/Openapi.test.ts: generated boolean schemas do not leak an internal metadata marker.
• src/Parser.test.ts, src/Help.test.ts, and src/Completions.test.ts: generated-style transformed booleans are classified without executing transforms during parser/help/completion introspection.
• src/Parser.test.ts, src/Help.test.ts, and src/Completions.test.ts: arbitrary boolean preprocessors are not treated as bare flags.
• src/Parser.test.ts, src/Help.test.ts, and src/Completions.test.ts: boolean-output schemas such as z.literal(false) and z.stringbool() are not treated as bare flags.

Fix

generateCommands() now:

• filters path item fields to real OpenAPI operations;
• supports OpenAPI 3.2 query and additionalOperations;
• merges path-level and operation-level parameters by in:name;
• orders path args by path-template order;
• URL-encodes interpolated path params;
• tracks which generated options came from JSON object bodies;
• enforces optional body schemas only after a body field is provided;
• sends {} for required JSON object bodies when no body field is present;
• parses generated booleans strictly while preserving CLI flag behavior.

Generated OpenAPI booleans are represented as schemas that accept real booleans plus the CLI strings "true" and "false", then output booleans. Parser/help/completions detect that public input/output shape instead of calling safeParse(true) and safeParse(false), so introspection does not execute user validation code.

[0xpolarzero]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• fix(typegen): render schema edge cases #11
• fix: correct OpenAPI generated commands #10 👈 (View in Graphite)
• [TypeScript client] feat: RPC & in-memory clients #9
• [TypeScript client] feat: RPC & in-memory transports #8
• fix: reuse CLI skill projection #13
• fix(cli): preserve stream terminal records #12
• fix: normalize object validation errors #3
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.