codapact 0.3.0__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (169) hide show
  1. codapact-0.4.0/.github/workflows/ci.yml +148 -0
  2. codapact-0.4.0/.github/workflows/mutation.yml +67 -0
  3. codapact-0.4.0/.github/workflows/nightly.yml +50 -0
  4. codapact-0.4.0/.release-please-manifest.json +1 -0
  5. {codapact-0.3.0 → codapact-0.4.0}/CHANGELOG.md +15 -0
  6. {codapact-0.3.0 → codapact-0.4.0}/PKG-INFO +2 -2
  7. {codapact-0.3.0 → codapact-0.4.0}/README.md +1 -1
  8. {codapact-0.3.0 → codapact-0.4.0}/docs/architecture.md +16 -7
  9. codapact-0.4.0/docs/configuration.md +276 -0
  10. codapact-0.4.0/docs/testing.md +90 -0
  11. {codapact-0.3.0 → codapact-0.4.0}/pyproject.toml +64 -3
  12. codapact-0.4.0/pyproject.toml.orig +122 -0
  13. codapact-0.4.0/scripts/extract_openapi_subset.py +93 -0
  14. codapact-0.4.0/scripts/mutation_score.py +86 -0
  15. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/__init__.py +1 -1
  16. codapact-0.4.0/src/codapact/__main__.py +5 -0
  17. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/commands/derive.py +90 -2
  18. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/commands/model.py +11 -0
  19. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/core/naming.py +5 -0
  20. codapact-0.4.0/src/codapact/core/net.py +254 -0
  21. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/model/__init__.py +6 -0
  22. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/model/api.py +70 -6
  23. codapact-0.4.0/src/codapact/model/authspec.py +98 -0
  24. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/model/migrations.py +22 -1
  25. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/model/rewrite.py +25 -1
  26. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/model/serialize.py +1 -0
  27. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/model/validate.py +1 -3
  28. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/pipeline/cli.py +10 -0
  29. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/pipeline/config.py +17 -1
  30. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/pipeline/pipeline.py +31 -5
  31. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/plugins/protocol.py +3 -0
  32. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/__init__.py +27 -1
  33. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/abstractions.py +28 -2
  34. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/arguments.py +5 -0
  35. codapact-0.4.0/src/codapact/runtime/auth.py +256 -0
  36. codapact-0.4.0/src/codapact/runtime/cli.py +1321 -0
  37. codapact-0.4.0/src/codapact/runtime/cli_auth.py +241 -0
  38. codapact-0.4.0/src/codapact/runtime/cli_tools.py +563 -0
  39. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/client.py +28 -4
  40. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/codec.py +88 -0
  41. codapact-0.4.0/src/codapact/runtime/credentials.py +331 -0
  42. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/errors.py +22 -0
  43. codapact-0.4.0/src/codapact/runtime/oauth.py +849 -0
  44. codapact-0.4.0/src/codapact/runtime/protocols/base.py +113 -0
  45. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/protocols/graphql.py +3 -1
  46. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/protocols/http.py +31 -8
  47. codapact-0.4.0/src/codapact/runtime/selftest.py +339 -0
  48. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/shaping/transforms.py +236 -44
  49. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/sources/graphql/translator.py +108 -15
  50. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/sources/loader.py +58 -19
  51. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/sources/openapi/translator.py +179 -26
  52. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/surface/derive.py +126 -23
  53. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/surface/model.py +19 -1
  54. codapact-0.4.0/src/codapact/targets/python/cli.py +423 -0
  55. codapact-0.4.0/src/codapact/targets/python/e2e.py +373 -0
  56. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/targets/python/library.py +57 -13
  57. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/targets/typescript/library.py +60 -9
  58. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/targets/typescript/runtime.ts +201 -23
  59. codapact-0.4.0/tests/authlab.py +288 -0
  60. codapact-0.4.0/tests/conftest.py +53 -0
  61. codapact-0.4.0/tests/e2e/test_auth_e2e.py +308 -0
  62. codapact-0.4.0/tests/e2e/test_cli_e2e.py +251 -0
  63. codapact-0.4.0/tests/e2e/test_public_apis.py +214 -0
  64. codapact-0.4.0/tests/fixtures/authlab/authlab_plugin.py +41 -0
  65. codapact-0.4.0/tests/fixtures/authlab/codapact.yaml +21 -0
  66. codapact-0.4.0/tests/fixtures/authlab/fake_browser.py +26 -0
  67. codapact-0.4.0/tests/fixtures/authlab/openapi.yaml +82 -0
  68. codapact-0.4.0/tests/fixtures/authlab_smoke.ts +63 -0
  69. codapact-0.4.0/tests/fixtures/contracts/wire.yaml +50 -0
  70. codapact-0.4.0/tests/fixtures/corpus/README.md +15 -0
  71. codapact-0.4.0/tests/fixtures/corpus/countries/codapact.yaml +12 -0
  72. codapact-0.4.0/tests/fixtures/corpus/countries/operations.graphql +15 -0
  73. codapact-0.4.0/tests/fixtures/corpus/countries/schema.graphql +24 -0
  74. codapact-0.4.0/tests/fixtures/corpus/github/codapact.yaml +41 -0
  75. codapact-0.4.0/tests/fixtures/corpus/github/openapi.json +4724 -0
  76. codapact-0.4.0/tests/fixtures/corpus/pokeapi/codapact.yaml +66 -0
  77. codapact-0.4.0/tests/fixtures/corpus/pokeapi/openapi.yml +10450 -0
  78. codapact-0.4.0/tests/fixtures/corpus/ynab/README.md +6 -0
  79. codapact-0.4.0/tests/fixtures/corpus/ynab/codapact.yaml +13 -0
  80. codapact-0.4.0/tests/fixtures/corpus/ynab/openapi.yaml +4027 -0
  81. codapact-0.4.0/tests/fixtures/wire_parity.ts +17 -0
  82. codapact-0.4.0/tests/integration/test_cli_conformance.py +268 -0
  83. codapact-0.4.0/tests/integration/test_cli_conventions.py +188 -0
  84. codapact-0.4.0/tests/integration/test_contract_properties.py +123 -0
  85. codapact-0.4.0/tests/integration/test_corpus.py +118 -0
  86. codapact-0.4.0/tests/integration/test_generated_code_properties.py +85 -0
  87. {codapact-0.3.0/tests → codapact-0.4.0/tests/integration}/test_generation.py +10 -39
  88. codapact-0.4.0/tests/integration/test_public_api_cli.py +106 -0
  89. codapact-0.4.0/tests/integration/test_wire_parity.py +104 -0
  90. codapact-0.4.0/tests/integration/test_ynab_contract.py +275 -0
  91. codapact-0.4.0/tests/perf/test_scaling.py +166 -0
  92. codapact-0.4.0/tests/public_api_contract.py +122 -0
  93. codapact-0.4.0/tests/strategies.py +204 -0
  94. {codapact-0.3.0 → codapact-0.4.0}/tests/support.py +204 -1
  95. {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_architecture.py +3 -1
  96. codapact-0.4.0/tests/unit/test_auth_and_graphql_sources.py +126 -0
  97. codapact-0.4.0/tests/unit/test_auth_sources.py +529 -0
  98. codapact-0.4.0/tests/unit/test_bundle_e2e.py +474 -0
  99. codapact-0.4.0/tests/unit/test_cli_builtins.py +532 -0
  100. codapact-0.4.0/tests/unit/test_guards.py +233 -0
  101. {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_model.py +28 -1
  102. codapact-0.4.0/tests/unit/test_mutation_score.py +60 -0
  103. codapact-0.4.0/tests/unit/test_oauth.py +590 -0
  104. {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_openapi_edges.py +164 -3
  105. codapact-0.4.0/tests/unit/test_openapi_translator_units.py +388 -0
  106. {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_plugins_pipeline.py +3 -3
  107. codapact-0.4.0/tests/unit/test_public_api_findings.py +932 -0
  108. {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_runtime_edges.py +22 -3
  109. codapact-0.4.0/tests/unit/test_runtime_pagination.py +116 -0
  110. {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_sources.py +42 -2
  111. codapact-0.4.0/tests/unit/test_target_rendering.py +332 -0
  112. codapact-0.4.0/tests/unit/test_usability.py +291 -0
  113. {codapact-0.3.0 → codapact-0.4.0}/uv.lock +516 -1
  114. codapact-0.3.0/.github/workflows/ci.yml +0 -53
  115. codapact-0.3.0/.release-please-manifest.json +0 -1
  116. codapact-0.3.0/docs/configuration.md +0 -91
  117. codapact-0.3.0/pyproject.toml.orig +0 -79
  118. codapact-0.3.0/src/codapact/core/net.py +0 -121
  119. codapact-0.3.0/src/codapact/runtime/auth.py +0 -113
  120. codapact-0.3.0/src/codapact/runtime/cli.py +0 -196
  121. codapact-0.3.0/src/codapact/runtime/protocols/base.py +0 -59
  122. codapact-0.3.0/src/codapact/targets/python/cli.py +0 -189
  123. {codapact-0.3.0 → codapact-0.4.0}/.github/workflows/codeql.yml +0 -0
  124. {codapact-0.3.0 → codapact-0.4.0}/.github/workflows/release.yml +0 -0
  125. {codapact-0.3.0 → codapact-0.4.0}/LICENSE +0 -0
  126. {codapact-0.3.0 → codapact-0.4.0}/docs/branding/README.md +0 -0
  127. {codapact-0.3.0 → codapact-0.4.0}/docs/branding/mark.svg +0 -0
  128. {codapact-0.3.0 → codapact-0.4.0}/docs/branding/wordmark.svg +0 -0
  129. {codapact-0.3.0 → codapact-0.4.0}/examples/library/codapact.yaml +0 -0
  130. {codapact-0.3.0 → codapact-0.4.0}/examples/library/operations.graphql +0 -0
  131. {codapact-0.3.0 → codapact-0.4.0}/examples/library/schema.graphql +0 -0
  132. {codapact-0.3.0 → codapact-0.4.0}/examples/petstore/codapact.yaml +0 -0
  133. {codapact-0.3.0 → codapact-0.4.0}/examples/petstore/openapi.yaml +0 -0
  134. {codapact-0.3.0 → codapact-0.4.0}/release-please-config.json +0 -0
  135. {codapact-0.3.0 → codapact-0.4.0}/scripts/verify_dist.py +0 -0
  136. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/commands/__init__.py +0 -0
  137. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/core/__init__.py +0 -0
  138. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/core/diagnostics.py +0 -0
  139. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/core/errors.py +0 -0
  140. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/model/types.py +0 -0
  141. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/model/values.py +0 -0
  142. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/pipeline/__init__.py +0 -0
  143. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/pipeline/defaults.py +0 -0
  144. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/pipeline/writer.py +0 -0
  145. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/plugins/__init__.py +0 -0
  146. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/plugins/external.py +0 -0
  147. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/plugins/registry.py +0 -0
  148. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/py.typed +0 -0
  149. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/middleware.py +0 -0
  150. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/runtime/protocols/__init__.py +0 -0
  151. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/shaping/__init__.py +0 -0
  152. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/shaping/base.py +0 -0
  153. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/shaping/engine.py +0 -0
  154. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/sources/__init__.py +0 -0
  155. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/sources/base.py +0 -0
  156. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/sources/graphql/__init__.py +0 -0
  157. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/sources/openapi/__init__.py +0 -0
  158. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/surface/__init__.py +0 -0
  159. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/targets/__init__.py +0 -0
  160. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/targets/python/__init__.py +0 -0
  161. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/targets/python/naming.py +0 -0
  162. {codapact-0.3.0 → codapact-0.4.0}/src/codapact/targets/typescript/__init__.py +0 -0
  163. {codapact-0.3.0 → codapact-0.4.0}/tests/fixtures/library_smoke.ts +0 -0
  164. {codapact-0.3.0 → codapact-0.4.0}/tests/fixtures/outline_plugin.py +0 -0
  165. {codapact-0.3.0 → codapact-0.4.0}/tests/fixtures/petstore_smoke.ts +0 -0
  166. {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_codec_serialize.py +0 -0
  167. {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_core.py +0 -0
  168. {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_runtime.py +0 -0
  169. {codapact-0.3.0/tests → codapact-0.4.0/tests/unit}/test_shaping_surface_commands.py +0 -0
@@ -0,0 +1,148 @@
1
+ name: CI
2
+ on:
3
+ pull_request:
4
+ push:
5
+ branches: [main]
6
+ workflow_dispatch:
7
+ workflow_call:
8
+ permissions:
9
+ contents: read
10
+ jobs:
11
+ title:
12
+ name: Conventional PR title
13
+ if: github.event_name == 'pull_request'
14
+ runs-on: ubuntu-latest
15
+ steps:
16
+ - name: Check title
17
+ env:
18
+ TITLE: ${{ github.event.pull_request.title }}
19
+ run: |
20
+ pattern='^(feat|fix|perf|docs|build|ci|refactor|test|chore|style|revert)(\([^)]+\))?!?: .+'
21
+ [[ "$TITLE" =~ $pattern ]]
22
+ check:
23
+ name: Python ${{ matrix.python }} on ${{ matrix.os }}
24
+ runs-on: ${{ matrix.os }}
25
+ strategy:
26
+ fail-fast: false
27
+ matrix:
28
+ os: [ubuntu-latest, windows-latest]
29
+ python: ['3.13', '3.14']
30
+ env:
31
+ # TypeScript runtime tests must run, not skip, in CI.
32
+ CODAPACT_REQUIRE_NODE: '1'
33
+ steps:
34
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
35
+ with:
36
+ persist-credentials: false
37
+ - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
38
+ with:
39
+ python-version: ${{ matrix.python }}
40
+ enable-cache: false
41
+ - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
42
+ with:
43
+ node-version: '24'
44
+ - name: Install TypeScript compiler
45
+ shell: bash
46
+ run: |
47
+ npm install --no-save --no-package-lock --prefix "$RUNNER_TEMP/tools" typescript@6.0.2
48
+ echo "$RUNNER_TEMP/tools/node_modules/.bin" >> "$GITHUB_PATH"
49
+ - run: uv sync --locked
50
+ - run: uv run poe check
51
+ - run: uv build
52
+ - run: uv run twine check --strict dist/*
53
+
54
+ coverage:
55
+ name: Coverage of changed lines
56
+ if: github.event_name == 'pull_request'
57
+ runs-on: ubuntu-latest
58
+ env:
59
+ CODAPACT_REQUIRE_NODE: '1'
60
+ HYPOTHESIS_PROFILE: ci
61
+ steps:
62
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
63
+ with:
64
+ persist-credentials: false
65
+ fetch-depth: 0
66
+ - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
67
+ with:
68
+ python-version: '3.13'
69
+ enable-cache: false
70
+ - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
71
+ with:
72
+ node-version: '24'
73
+ - run: |
74
+ npm install --no-save --no-package-lock --prefix "$RUNNER_TEMP/tools" typescript@6.0.2
75
+ echo "$RUNNER_TEMP/tools/node_modules/.bin" >> "$GITHUB_PATH"
76
+ - run: uv sync --locked
77
+ - name: Full suite with more property examples
78
+ run: uv run poe test
79
+ - name: Every changed source line is covered
80
+ env:
81
+ BASE_REF: ${{ github.base_ref }}
82
+ run: |
83
+ git fetch --no-tags origin "$BASE_REF"
84
+ uv run diff-cover coverage.xml --compare-branch="origin/$BASE_REF" --fail-under=100 \
85
+ --markdown-report diff-coverage.md
86
+ cat diff-coverage.md >> "$GITHUB_STEP_SUMMARY"
87
+
88
+ prism:
89
+ name: E2E against Prism mock (PokeAPI)
90
+ runs-on: ubuntu-latest
91
+ steps:
92
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
93
+ with:
94
+ persist-credentials: false
95
+ - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
96
+ with:
97
+ python-version: '3.13'
98
+ enable-cache: false
99
+ - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
100
+ with:
101
+ node-version: '24'
102
+ - run: npm install --no-save --no-package-lock --prefix "$RUNNER_TEMP/tools" @stoplight/prism-cli@5.16.0
103
+ - run: uv sync --locked
104
+ - name: Start Prism (validates every request against the pinned spec)
105
+ run: |
106
+ "$RUNNER_TEMP/tools/node_modules/.bin/prism" mock --errors -p 4010 \
107
+ tests/fixtures/corpus/pokeapi/openapi.yml > "$RUNNER_TEMP/prism.log" 2>&1 &
108
+ for _ in $(seq 60); do curl -s -o /dev/null http://127.0.0.1:4010/ && break; sleep 1; done
109
+ - run: uv run pytest tests/e2e/test_public_apis.py -v
110
+ env:
111
+ CODAPACT_PRISM_URL: http://127.0.0.1:4010
112
+ - if: always()
113
+ run: cat "$RUNNER_TEMP/prism.log"
114
+
115
+ perf:
116
+ name: Performance budgets
117
+ runs-on: ubuntu-latest
118
+ steps:
119
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
120
+ with:
121
+ persist-credentials: false
122
+ - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
123
+ with:
124
+ python-version: '3.13'
125
+ enable-cache: false
126
+ - run: uv sync --locked
127
+ - run: uv run poe test-perf
128
+ env:
129
+ CODAPACT_PERF_REPORT: perf-report.json
130
+ - if: always()
131
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
132
+ with:
133
+ name: perf-report
134
+ path: perf-report.json
135
+ if-no-files-found: warn
136
+ retention-days: 30
137
+
138
+ passed:
139
+ name: CI passed
140
+ if: always()
141
+ needs: [check, coverage, prism, perf, title]
142
+ runs-on: ubuntu-latest
143
+ steps:
144
+ - name: Require all checks
145
+ env:
146
+ RESULTS: ${{ toJSON(needs) }}
147
+ run: |
148
+ echo "$RESULTS" | jq -e 'to_entries | all(.value.result == "success" or .value.result == "skipped")'
@@ -0,0 +1,67 @@
1
+ name: Mutation
2
+ # Mutation testing measures whether the tests notice behavior changes. It is slow
3
+ # (~9k mutants), so it runs in parallel shards after merges to main, weekly, and on
4
+ # demand; it never gates a PR. Each shard must finish and meet the score floor.
5
+ on:
6
+ push:
7
+ branches: [main]
8
+ schedule:
9
+ - cron: '23 6 * * 1'
10
+ workflow_dispatch:
11
+ permissions:
12
+ contents: read
13
+ concurrency:
14
+ group: mutation-${{ github.ref }}
15
+ cancel-in-progress: true
16
+ jobs:
17
+ mutmut:
18
+ name: mutmut ${{ matrix.shard.name }}
19
+ runs-on: ubuntu-latest
20
+ timeout-minutes: 75
21
+ strategy:
22
+ fail-fast: false
23
+ matrix:
24
+ shard:
25
+ - {name: openapi, patterns: 'codapact.sources.openapi.*'}
26
+ - {name: sources, patterns: 'codapact.sources.graphql.* codapact.sources.loader.* codapact.sources.base.*'}
27
+ - {name: targets, patterns: 'codapact.targets.*'}
28
+ - {name: runtime, patterns: 'codapact.runtime.*'}
29
+ - {name: pipeline, patterns: 'codapact.pipeline.* codapact.plugins.* codapact.commands.*'}
30
+ - {name: model, patterns: 'codapact.model.* codapact.shaping.* codapact.surface.* codapact.core.*'}
31
+ env:
32
+ # Baseline 2026-11-11: ~74% overall. Raise as survivors are fixed; never lower.
33
+ MUTATION_FLOOR: '70'
34
+ steps:
35
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
36
+ with:
37
+ persist-credentials: false
38
+ - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
39
+ with:
40
+ python-version: '3.13'
41
+ enable-cache: false
42
+ - run: uv sync --locked --group mutation
43
+ - name: Run mutmut
44
+ env:
45
+ PATTERNS: ${{ matrix.shard.patterns }}
46
+ run: |
47
+ set +e
48
+ read -ra patterns <<< "$PATTERNS"
49
+ timeout --signal=TERM --kill-after=30s 65m uv run mutmut run --max-children 4 "${patterns[@]}"
50
+ echo "run_exit=$?" >> "$GITHUB_ENV"
51
+ mkdir -p mutation-report
52
+ uv run mutmut results --all true > mutation-report/results.txt
53
+ - name: Enforce mutation score floor
54
+ env:
55
+ PATTERNS: ${{ matrix.shard.patterns }}
56
+ run: |
57
+ test "$run_exit" = 0 || { echo "mutmut did not finish (exit $run_exit)"; exit 1; }
58
+ args=()
59
+ for pattern in $PATTERNS; do args+=(--prefix "${pattern%\*}"); done
60
+ uv run python scripts/mutation_score.py --results mutation-report/results.txt "${args[@]}"
61
+ - if: always()
62
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
63
+ with:
64
+ name: mutation-report-${{ matrix.shard.name }}
65
+ path: mutation-report/
66
+ if-no-files-found: warn
67
+ retention-days: 30
@@ -0,0 +1,50 @@
1
+ name: Nightly
2
+ # Slow and networked suites that should not gate every PR:
3
+ # live public APIs, deep property-based fuzzing, and the full TypeScript fuzz.
4
+ on:
5
+ schedule:
6
+ - cron: '17 5 * * *'
7
+ workflow_dispatch:
8
+ permissions:
9
+ contents: read
10
+ jobs:
11
+ live:
12
+ name: Live public APIs (PokeAPI, Countries, GitHub with auth)
13
+ runs-on: ubuntu-latest
14
+ timeout-minutes: 20
15
+ steps:
16
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
17
+ with:
18
+ persist-credentials: false
19
+ - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
20
+ with:
21
+ python-version: '3.13'
22
+ enable-cache: false
23
+ - run: uv sync --locked
24
+ - run: uv run poe test-live -v
25
+ env:
26
+ # The generated GitHub CLI's live e2e suite proves the token is sent
27
+ # (authenticated rate limit) and that GitHub rejects a bad one.
28
+ GHX_TOKEN: ${{ secrets.GITHUB_TOKEN }}
29
+ deep:
30
+ name: Deep property-based fuzzing
31
+ runs-on: ubuntu-latest
32
+ timeout-minutes: 60
33
+ env:
34
+ CODAPACT_REQUIRE_NODE: '1'
35
+ steps:
36
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
37
+ with:
38
+ persist-credentials: false
39
+ - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
40
+ with:
41
+ python-version: '3.13'
42
+ enable-cache: false
43
+ - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
44
+ with:
45
+ node-version: '24'
46
+ - run: |
47
+ npm install --no-save --no-package-lock --prefix "$RUNNER_TEMP/tools" typescript@6.0.2
48
+ echo "$RUNNER_TEMP/tools/node_modules/.bin" >> "$GITHUB_PATH"
49
+ - run: uv sync --locked
50
+ - run: uv run poe test-deep
@@ -0,0 +1 @@
1
+ {".":"0.4.0"}
@@ -2,6 +2,21 @@
2
2
 
3
3
  <!-- markdownlint-configure-file { "MD024": { "siblings_only": true } } -->
4
4
 
5
+ ## [0.4.0](https://github.com/mikejhill/codapact/compare/v0.3.0...v0.4.0) (2026-11-12)
6
+
7
+
8
+ ### Features
9
+
10
+ * **auth:** pluggable auth (OAuth 2.0 flows, bespoke authenticators) and generated bundle e2e suites ([#27](https://github.com/mikejhill/codapact/issues/27)) ([b42cb61](https://github.com/mikejhill/codapact/commit/b42cb61165c58895893c1a50a5515d5dc39a88aa))
11
+ * **cli:** conventional help, version, describe, doctor, completion, dry-run, JSON errors ([#25](https://github.com/mikejhill/codapact/issues/25)) ([809c9da](https://github.com/mikejhill/codapact/commit/809c9da83102ebaa5ae41a0cd0d60177e10c286f))
12
+ * **cli:** name commands in errors, describe --brief and schemas, CLI conformance suite ([#26](https://github.com/mikejhill/codapact/issues/26)) ([8780dfc](https://github.com/mikejhill/codapact/commit/8780dfcf1607f267cf59c9d39e8dd4c61a895da7))
13
+ * fix YNAB-evaluation findings (nullability, allOf, naming, CLI usability) ([#22](https://github.com/mikejhill/codapact/issues/22)) ([d8caaf3](https://github.com/mikejhill/codapact/commit/d8caaf33d084770993a5ad45d7bfb3d01d5d7cf9))
14
+
15
+
16
+ ### Bug Fixes
17
+
18
+ * address defects found by generating clients for PokeAPI and GitHub ([#23](https://github.com/mikejhill/codapact/issues/23)) ([b0693c3](https://github.com/mikejhill/codapact/commit/b0693c370d0fbfc6483cdc82adc4015c375a05a1))
19
+
5
20
  ## [0.3.0](https://github.com/mikejhill/codapact/compare/v0.2.0...v0.3.0) (2026-11-10)
6
21
 
7
22
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: codapact
3
- Version: 0.3.0
3
+ Version: 0.4.0
4
4
  Summary: Contracts into callable tools: generate libraries, then CLIs, from OpenAPI, GraphQL, and other API contracts.
5
5
  License-Expression: MIT
6
6
  License-File: LICENSE
@@ -70,7 +70,7 @@ uv run codapact inspect commands -c examples/library/codapact.yaml
70
70
  | Output | Contents |
71
71
  | --- | --- |
72
72
  | `python` | Installable package: `TypedDict` types, a resource-per-namespace client, paging iterators, `py.typed` |
73
- | `python-cli` | argparse CLI calling the Python library; JSON/YAML/raw output; env + XDG settings |
73
+ | `python-cli` | argparse CLI calling the Python library: `--help` with examples, `--version`, `describe` (JSON catalog for agents), `doctor`, shell `completion`, `--dry-run`, JSON/JSONL/YAML/table output, JSON errors, documented exit codes; env + XDG settings |
74
74
  | `typescript` | Fetch-based client with bundled runtime; strict `tsc` clean |
75
75
  | external plugin | Any executable speaking the JSON plugin protocol |
76
76
 
@@ -55,7 +55,7 @@ uv run codapact inspect commands -c examples/library/codapact.yaml
55
55
  | Output | Contents |
56
56
  | --- | --- |
57
57
  | `python` | Installable package: `TypedDict` types, a resource-per-namespace client, paging iterators, `py.typed` |
58
- | `python-cli` | argparse CLI calling the Python library; JSON/YAML/raw output; env + XDG settings |
58
+ | `python-cli` | argparse CLI calling the Python library: `--help` with examples, `--version`, `describe` (JSON catalog for agents), `doctor`, shell `completion`, `--dry-run`, JSON/JSONL/YAML/table output, JSON errors, documented exit codes; env + XDG settings |
59
59
  | `typescript` | Fetch-based client with bundled runtime; strict `tsc` clean |
60
60
  | external plugin | Any executable speaking the JSON plugin protocol |
61
61
 
@@ -51,7 +51,7 @@ place that names concrete implementations.
51
51
 
52
52
  ### Dependency rules
53
53
 
54
- Enforced by `tests/test_architecture.py` (AST import scan):
54
+ Enforced by `tests/unit/test_architecture.py` (AST import scan):
55
55
 
56
56
  - `core` depends on nothing in the package.
57
57
  - `model` depends only on `core`.
@@ -87,6 +87,7 @@ Enforced by `tests/test_architecture.py` (AST import scan):
87
87
  | HTTP sending | `Transport.send(HttpRequest)` | `RuntimeClient(transport=…)` |
88
88
  | Cross-cutting | `Middleware(request, context, next)` | `RuntimeClient(middleware=…)` |
89
89
  | Credentials | `AuthProvider.credential(scheme)` | `RuntimeClient(auth=…)` |
90
+ | Bespoke auth | `Authenticator.authenticate(request, scheme)`, optional `refresh` | returned by an `AuthProvider`; CLI `auth_plugin` |
90
91
  | Protocol | `ProtocolAdapter.supports/call` | `RuntimeClient(adapters=…)` |
91
92
 
92
93
  ### Plugin protocol
@@ -113,8 +114,12 @@ that silently mishandles the feature.
113
114
  rebinding, private and plaintext addresses only with explicit opt-in.
114
115
  - `Retry` middleware: idempotent operations only, exponential backoff, honors
115
116
  `Retry-After`.
116
- - Auth: `StaticAuth`, `EnvAuth` (`<PREFIX>_<SCHEME>`), `ChainAuth`. `Credential.__repr__`
117
- never renders secrets.
117
+ - Auth: sources (`StaticAuth`, `EnvAuth`, `ChainAuth`, `CommandAuth`, `StoreAuth`) return a
118
+ `Credential` or an `Authenticator`. `OAuth2` (in `runtime.oauth`) is an `Authenticator`
119
+ over a grant (client credentials, password, device code, authorization code + PKCE) and a
120
+ `TokenStore` (memory, file, keyring). Authenticators run after middleware; a 401 triggers
121
+ one `refresh()` and resend. `Credential.__repr__` never renders secrets.
122
+ - `runtime.selftest`: the suite generated bundles ship (offline dry runs, live scenarios).
118
123
  - Errors: `ValidationError`, `AuthError`, `ApiError` (status, named error case, decoded
119
124
  payload), `GraphQLResponseError`, `TransportError`.
120
125
 
@@ -139,8 +144,12 @@ Deliberate differences:
139
144
 
140
145
  ## Testing strategy
141
146
 
147
+ Summary; the full strategy, suites, and gates are in [testing](testing.md).
148
+
142
149
  - Each layer has unit tests against hand-built inputs from the layer below.
143
- - `tests/support.py` provides in-memory petstore (REST) and library (GraphQL) servers and a
144
- `FakeTransport`; generated clients are also exercised over real loopback HTTP.
145
- - Generated Python is type checked with `ty`; generated TypeScript runs under Node.
146
- - The external plugin fixture uses only the public protocol helpers.
150
+ - Property tests check translation against an independent JSON Schema oracle, and fuzz
151
+ whole contracts through every target.
152
+ - Generated Python and TypeScript are compiled, type-checked, and run against loopback
153
+ servers; the two runtimes must put identical requests on the wire.
154
+ - Real contracts (PokeAPI, YNAB) are generated in strict mode on every PR; public APIs are
155
+ called nightly.
@@ -0,0 +1,276 @@
1
+ ---
2
+ type: reference
3
+ status: active
4
+ authority: normative
5
+ criticality: normal
6
+ review:
7
+ status: unreviewed
8
+ ---
9
+
10
+ # Configuration
11
+
12
+ ## `codapact.yaml`
13
+
14
+ ```yaml
15
+ version: 1
16
+ source:
17
+ type: openapi # openapi | graphql
18
+ path: openapi.yaml # local path (relative to this file) or https URL
19
+ documents: [] # companion documents, e.g. GraphQL operations
20
+ options: {strict: true}
21
+ shape: # ordered transforms; the model is re-validated after each
22
+ - group: {by: tag}
23
+ - paginate: {operations: [list_pets], next: next_cursor, items: items}
24
+ surface: {flatten_body: true, trim_namespace: true}
25
+ cli:
26
+ program: petstore
27
+ auth_plugin: my_auth:provider # optional; see Authentication
28
+ auth: {sso: {client_id: petstore-cli, scopes: [read]}}
29
+ e2e: # optional; tests shipped with the generated CLI
30
+ scenarios:
31
+ - {name: list pets, run: [pets, list], expect: {not_empty: ["$"]}}
32
+ targets:
33
+ - {name: python, output: out/python, options: {package: petstore}}
34
+ - {name: python-cli, output: out/python}
35
+ - {name: typescript, output: out/ts, options: {package: petstore}}
36
+ - {plugin: [python, my_plugin.py], output: out/custom}
37
+ ```
38
+
39
+ Targets that share an `output` directory share options. When `python-cli` shares the
40
+ `python` directory, the library's `pyproject.toml` gains the CLI script entry.
41
+
42
+ ## Sources
43
+
44
+ | Source | Option | Default | Meaning |
45
+ | --- | --- | --- | --- |
46
+ | both | `strict` | `true` | Unsupported features are errors; when `false`, they degrade with a warning. For GraphQL, `false` also builds schemas that break spec rules (as GitHub's does) and lists the problems as warnings |
47
+ | `graphql` | `name` | `GraphQL API` | API name |
48
+ | `graphql` | `version` | empty | API version |
49
+ | `graphql` | `url` | none | Endpoint; becomes the default server |
50
+ | `graphql` | `auth` | none | `bearer`, `basic`, `{api_key: HEADER}`, or `{schemes: {NAME: SPEC}}` with any [auth spec](#auth-specs); required on every operation |
51
+ | `graphql` | `depth` | `1` | Object nesting synthesized in schema mode (0–8) |
52
+
53
+ `source.max_bytes` (next to `type` and `path`, not under `options`) caps each contract
54
+ document; the default is 64 MB. Remote contracts and generated clients honour
55
+ `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY`. Proxy URLs must use `http://` without
56
+ credentials; HTTPS traffic is tunnelled with `CONNECT`.
57
+
58
+ GraphQL with `documents` generates one operation per document operation with exact result
59
+ types. Without documents, it generates one operation per root field. A `#` comment block
60
+ directly above a document operation becomes its description; variable defaults
61
+ (`$first: Int = 5`) become parameter defaults.
62
+
63
+ When the first shaping step is `select`, model errors in operations it removes are reported
64
+ as one warning instead of blocking generation.
65
+
66
+ ## Shaping transforms
67
+
68
+ | Transform | Config |
69
+ | --- | --- |
70
+ | `select` | `include`, `exclude`: lists of globs or `{name, tag, kind, namespace, read_only}` selectors |
71
+ | `rename` | `operations`, `types`, `fields` (`Type.field`), `params` (`op.param`), `patterns` (`[{match: regex, replace: template}]` over operation names; explicit `operations` entries win); wire names are kept |
72
+ | `group` | `by: tag` or `by: path`, and/or `operations: {glob: dotted.namespace}` |
73
+ | `paginate` | `operations`, `style: cursor` (`param`, `next`), `offset` (`param`, `limit_param`), or `page` (`param`, default `page`; `start`, default `1`), and `items` (`$` when the result itself is the list). Operations matched only by a pattern that lack the param or items are skipped with a warning; operations named exactly are errors |
74
+ | `defaults` | `params: {"op_glob.param": value}`; the param becomes optional and the runtime sends `value` when it is omitted |
75
+ | `auth` | `schemes: {name: SPEC}` ([auth specs](#auth-specs)), `operations` (default all), `optional` (send credentials when set, call anonymously otherwise). For contracts that omit or under-declare `securitySchemes`; re-declaring an identical scheme is allowed |
76
+ | `prune` | none; removes unreachable types (also run by `select`) |
77
+
78
+ ## Surface options
79
+
80
+ | Option | Default | Meaning |
81
+ | --- | --- | --- |
82
+ | `flatten_body` | `true` | Expose record body fields as individual method params |
83
+ | `flatten_wrapper` | `true` | A required body `{"account": {...}}` with one record field exposes that record's fields |
84
+ | `trim_namespace` | `true` | `pets.list_pets` becomes `pets.list`; a noun phrase ending in the namespace is dropped (`months.get_plan_months` → `months.list`); a plural/singular clash yields `update` and `update_many`; names that would still collide are kept |
85
+ | `conventional_names` | `true` | `get_<plural>` becomes `list_<plural>`; a trailing `by_id` is dropped (`get_pet_by_id` → `get_pet`) |
86
+
87
+ ## Targets
88
+
89
+ | Target | Option | Default |
90
+ | --- | --- | --- |
91
+ | `python` | `package` | from API name |
92
+ | `python` | `distribution` | package with `-` |
93
+ | `python` | `version` | `0.1.0` |
94
+ | `typescript` | `package` | API name in kebab case |
95
+ | `typescript` | `version` | `0.1.0` |
96
+
97
+ ## Generated CLI settings
98
+
99
+ Precedence: flag, then environment, then settings file.
100
+
101
+ | Setting | Flag | Environment | File key |
102
+ | --- | --- | --- | --- |
103
+ | Base URL | `--base-url` | `<PREFIX>_BASE_URL` | `base_url` |
104
+ | Timeout | `--timeout` | `<PREFIX>_TIMEOUT` | `timeout` |
105
+ | Private network | `--allow-private` | `<PREFIX>_ALLOW_PRIVATE` | `allow_private` |
106
+ | Response validation | `--response-validation strict\|warn\|off` | `<PREFIX>_RESPONSE_VALIDATION` | `response_validation` |
107
+ | Output format | `-o`/`--output json\|jsonl\|yaml\|table\|raw` | `<PREFIX>_OUTPUT` | `output` |
108
+ | Error format | `--error-format text\|json` | `<PREFIX>_ERROR_FORMAT` | `error_format` |
109
+ | Credentials | none | `<PREFIX>_<SCHEME>`; basic uses `_USERNAME`/`_PASSWORD`; full chain under [Authentication](#authentication) | `auth_plugin`; secrets are never read from the file |
110
+ | Option defaults | the option itself | none | `defaults: {plan_id: "…"}` (option names, `_` or `-`) |
111
+
112
+ The settings file is `--config PATH` or `$XDG_CONFIG_HOME/<program>/config.json`.
113
+ `<PREFIX>` is the program name in upper snake case. `<program> --help` lists the
114
+ credential variables for the contract's auth schemes.
115
+
116
+ Global options work before or after the command: `--base-url`, `--timeout`, `--config`,
117
+ `-o/--output`, `--query PATH` (`data.items[].name`, `data.items[0]`; with `--all` the
118
+ result is the item list, so `[].name`), `--dry-run`, `-v/--verbose`, `--error-format`,
119
+ `--allow-private`, and `--response-validation`. Command help lists them in one line;
120
+ `<program> --help` describes each.
121
+ `table` renders a list of objects, unwrapping single-list envelopes such as `{"data": {"items": [...]}}`.
122
+ `jsonl` prints one JSON value per line and streams `--all` results page by page.
123
+
124
+ ### Conventions every generated CLI follows
125
+
126
+ | Need | How |
127
+ | --- | --- |
128
+ | Help | `-h`/`--help` on every level; bare `<program>` or `<program> GROUP` prints help (exit `0`). Command help has a usage line with positionals and required options, examples, and a global-options reminder. |
129
+ | Version | `-V`/`--version`: `poke 0.1.0 (PokéAPI 2.10.0; codapact 0.4.0)` |
130
+ | Discovery for agents | `<program> describe [COMMAND…]`: JSON with every command's arguments (type, required, positional, choices, repeated), `read_only`/`destructive`/`paginated`, `requires_one_of` option groups, environment variables, exit codes. `describe --brief` keeps only names, summaries, and usage lines. Naming one command (or passing `--schemas`) adds the JSON Schema of its output and of each JSON-valued argument |
131
+ | Diagnosis | `<program> doctor [--offline]`: version, settings file, base URL and its source, credentials (set or missing, never printed), proxy, connectivity. Table on a terminal, JSON otherwise; exit `1` when a check fails |
132
+ | Completion | `<program> completion bash\|zsh\|fish\|powershell` prints a script that asks the program for candidates |
133
+ | Preview | `--dry-run` prints the HTTP request (method, URL, headers, body) without sending it; credentials appear as `$VARIABLE` placeholders (optional credentials that are not set stay off the request), and destructive commands skip confirmation |
134
+ | Tracing | `-v`/`--verbose` logs each request line and response status, size, and time to stderr, masking credential values |
135
+ | Mistakes | unknown commands, choices, and options get "did you mean" hints; leftovers are reported by the command they were given to; API failures name the command typed (`pets get failed with HTTP 404`) |
136
+ | Machine-readable errors | `--error-format json` prints one `{"error": {"type", "message", "exit_code", "status", "hint", "details"}}` object on stderr; contract warnings become `{"warning": …}` lines |
137
+
138
+ | Credentials | `<program> auth login\|logout\|status\|token`; see [Authentication](#authentication) |
139
+
140
+ `describe`, `doctor`, `completion`, and `auth` are skipped when the API has a top-level command
141
+ of the same name; `--version`, `--dry-run`, `--verbose`, and `--error-format` are reserved, so
142
+ API parameters with those names become `--arg-version` and so on.
143
+
144
+ `tests/integration/test_cli_conformance.py` checks these conventions for every example
145
+ contract (Petstore, Library, PokéAPI, YNAB, Countries), including a `--dry-run` of every
146
+ command built from its own `describe` entry.
147
+
148
+ Commands for HTTP `DELETE` operations, or operations named `delete_*`/`remove_*`/`destroy_*`/`purge_*`,
149
+ ask for confirmation on a terminal and require `--yes` otherwise.
150
+
151
+ Validation errors name the command-line option (`--amount: expected an integer`).
152
+
153
+ Required path parameters without a default are positional, in URL order
154
+ (`repos get OWNER REPO`); the `--owner` form still works.
155
+
156
+ Responses that break the contract (a `null` where the contract promises a string) print
157
+ a warning and the data by default (`warn`). `strict` fails with exit `1`; `off` skips
158
+ response checks. Generated libraries default to `strict` and raise
159
+ `ResponseValidationError`, whose `data` holds the response.
160
+
161
+ Exit codes: `0` success, `1` API error or contract break, `2` usage or validation, `3` auth
162
+ (missing credentials or HTTP 401/403), `4` transport, `130` interrupted. Root help and
163
+ `describe` list them.
164
+
165
+ ## Authentication
166
+
167
+ Three layers, each usable without the next:
168
+
169
+ | Layer | What it is | Use it for |
170
+ | --- | --- | --- |
171
+ | Source | `AuthProvider.credential(scheme) -> Credential \| Authenticator \| None` | Where a secret comes from: environment, a command, the OS keyring, a vault |
172
+ | Built-in flow | `OAuth2(grant, store)` with `ClientCredentials`, `PasswordGrant`, `DeviceCode` (RFC 8628), `AuthorizationCodePKCE` (loopback redirect); refresh tokens; OIDC discovery | Standard OAuth 2.0 / OpenID Connect without code |
173
+ | Bespoke | `Authenticator.authenticate(request, scheme) -> request`, optional `refresh(scheme) -> bool` | Request signing (HMAC, AWS SigV4), token exchange, anything else |
174
+
175
+ An `Authenticator` runs last, after middleware, so a retried request is signed again. On
176
+ HTTP 401 the runtime calls `refresh()` and, if it returns true, sends the request once more.
177
+
178
+ ### Auth specs
179
+
180
+ Used by the `auth` transform, the GraphQL `auth` option, and `cli.auth`:
181
+
182
+ | Spec | Meaning |
183
+ | --- | --- |
184
+ | `bearer`, `basic` | `Authorization` header |
185
+ | `{api_key: NAME, in: header\|query\|cookie}` | key sent under `NAME` |
186
+ | `oauth2` | bearer token; flows come from settings or `auth login` |
187
+ | `{oauth2: {client_credentials\|authorization_code\|device_code\|password: {token_url, authorization_url, device_authorization_url, refresh_url, scopes}}}` | OAuth 2.0 with known endpoints |
188
+ | `{openid: DISCOVERY_URL}` | OAuth 2.0 whose endpoints come from `.well-known/openid-configuration` |
189
+ | `custom` or `{custom: DESCRIPTION}` | needs an `Authenticator` (plugin or library code) |
190
+
191
+ Any spec map also takes `docs`. OpenAPI `oauth2` (including 3.2 `deviceAuthorization`) and
192
+ `openIdConnect` map to the same model; other schemes (`mutualTLS`, `http` with an unknown
193
+ scheme) become `custom` with an info diagnostic.
194
+
195
+ ### CLI credential chain
196
+
197
+ The first source that has a credential wins, per scheme:
198
+
199
+ 1. Plugin: `<PREFIX>_AUTH_PLUGIN`, settings file `auth_plugin`, or `cli.auth_plugin`,
200
+ as `module:function`. The function takes an `AuthContext` (`api`, `program`,
201
+ `env_prefix`, `environ`, `store`, `http`) and returns an `AuthProvider` or a
202
+ `{scheme: Credential | Authenticator | str}` map.
203
+ 2. Environment: `<PREFIX>_<SCHEME>` (basic: `_USERNAME`, `_PASSWORD`).
204
+ 3. Command: `<PREFIX>_<SCHEME>_COMMAND`, run without a shell; stdout is the secret
205
+ (`op read …`, `vault kv get …`, `gh auth token`).
206
+ 4. OAuth client: `<PREFIX>_<SCHEME>_CLIENT_ID` + `_CLIENT_SECRET` (optional `_SCOPES`)
207
+ runs the client-credentials grant and caches the token.
208
+ 5. Saved login from `<program> auth login`.
209
+
210
+ `cli.auth: {SCHEME: {client_id, scopes, flow, audience}}` bakes public OAuth settings into
211
+ the CLI (no secrets). `auth login` picks a flow in this order: `--flow`, then client
212
+ credentials when a secret is set, then device code, then authorization code with PKCE.
213
+ `--with-token` reads a static token from stdin; `--username` saves basic credentials.
214
+ `auth status` shows each scheme's source; `auth token` prints what a command would send;
215
+ `doctor` reports the same, never printing secrets.
216
+
217
+ Saved credentials and tokens go to the OS keyring when one is usable, otherwise to a
218
+ `0600` JSON file at `$XDG_CONFIG_HOME/<program>/credentials.json`.
219
+ `<PREFIX>_CREDENTIAL_STORE=keyring|file|memory` forces one.
220
+
221
+ Libraries take the same objects directly:
222
+
223
+ ```python
224
+ from codapact.runtime import ClientCredentials, OAuth2, StaticAuth
225
+
226
+ client = Client(
227
+ auth=StaticAuth(
228
+ {
229
+ "token": "…", # bearer / api key
230
+ "sso": OAuth2(ClientCredentials(token_url, client_id, secret)),
231
+ "signed": HmacSigner(key_id, secret), # your Authenticator
232
+ }
233
+ )
234
+ )
235
+ ```
236
+
237
+ The TypeScript client accepts a string, `{username, password}`, a token function, an
238
+ `Authenticator` object, or `clientCredentials({tokenUrl, clientId, clientSecret})`.
239
+
240
+ ## Generated bundle tests
241
+
242
+ `python-cli` writes `tests/test_e2e.py` and `tests/e2e.json` into the bundle
243
+ (`options: {tests: false}` turns this off). Run them with `uv run pytest` in the bundle.
244
+
245
+ | Tier | Runs | Checks |
246
+ | --- | --- | --- |
247
+ | Offline | always | `--help` of every command; a `--dry-run` of every command with sampled arguments: method, path, and where each credential goes |
248
+ | Live | `<PREFIX>_E2E_LIVE=1` (or `CODAPACT_LIVE=1`) | `e2e.scenarios`, then a smoke call of each read-only command that needs no arguments |
249
+
250
+ A live case whose credentials are not configured is skipped;
251
+ `<PREFIX>_E2E_REQUIRE_AUTH=1` makes it fail instead.
252
+
253
+ | `e2e` key | Meaning |
254
+ | --- | --- |
255
+ | `scenarios` | list of `{name, run, auth, expect, env, response_validation, stdin}`; `run` is the argument list after the program name |
256
+ | `scenarios[].auth` | `any` (default), `required` (skip without credentials), `none` (run with every credential removed) |
257
+ | `scenarios[].expect` | `exit` (default `0`), `contains: {PATH: value}` (subset match), `not_empty: [PATH]`, `at_least: {PATH: n}`, `length_at_least: {PATH: n}`, `stderr_contains`; `PATH` uses the `--query` syntax, `$` is the whole result |
258
+ | `smoke` | `true` (default), `false`, or `{limit: 25, exclude: [glob]}` over command paths |
259
+ | `response_validation` | mode for every live case (default `strict`) |
260
+
261
+ ## Generated names by target
262
+
263
+ | Target | Method params | Record fields |
264
+ | --- | --- | --- |
265
+ | Python | `snake_case` (keywords get a trailing `_`) | model names; the runtime codec maps them to wire names |
266
+ | TypeScript | `camelCase` | wire names; the bundled runtime sends values as typed, without a codec |
267
+
268
+ So `rename.fields` renames a Python `TypedDict` key but not a TypeScript type key. Method
269
+ parameters follow each language's convention in both targets.
270
+
271
+ ## Formats
272
+
273
+ `format` values (`date`, `date-time`, `uuid`, …) are annotations, as in JSON Schema 2020-12:
274
+ the client does not reject values that do not match them, because real APIs accept extra
275
+ forms (YNAB's `month` path param is `format: date` but also takes `current`). CLIs show
276
+ `YYYY-MM-DD` / `DATETIME` as the option placeholder.