codapact 0.5.1__tar.gz → 0.6.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 (168) hide show
  1. codapact-0.6.0/.release-please-manifest.json +1 -0
  2. {codapact-0.5.1 → codapact-0.6.0}/CHANGELOG.md +16 -0
  3. {codapact-0.5.1 → codapact-0.6.0}/PKG-INFO +1 -1
  4. {codapact-0.5.1 → codapact-0.6.0}/docs/configuration.md +71 -5
  5. {codapact-0.5.1 → codapact-0.6.0}/pyproject.toml +1 -1
  6. {codapact-0.5.1 → codapact-0.6.0}/pyproject.toml.orig +1 -1
  7. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/__init__.py +1 -1
  8. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/commands/derive.py +9 -2
  9. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/pipeline/cli.py +34 -1
  10. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/pipeline/config.py +32 -4
  11. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/pipeline/pipeline.py +32 -1
  12. codapact-0.6.0/src/codapact/pipeline/sync.py +162 -0
  13. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/pipeline/writer.py +37 -3
  14. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/runtime/cli.py +46 -12
  15. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/runtime/cli_auth.py +80 -4
  16. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/runtime/credentials.py +62 -1
  17. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/targets/python/cli.py +34 -2
  18. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/targets/python/library.py +3 -1
  19. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_cli_auth.py +7 -0
  20. codapact-0.6.0/tests/unit/test_credential_fields.py +264 -0
  21. codapact-0.6.0/tests/unit/test_env_prefix.py +66 -0
  22. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_live_ynab_findings.py +61 -1
  23. codapact-0.6.0/tests/unit/test_sync.py +290 -0
  24. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_usability.py +1 -1
  25. {codapact-0.5.1 → codapact-0.6.0}/uv.lock +1 -1
  26. codapact-0.5.1/.release-please-manifest.json +0 -1
  27. {codapact-0.5.1 → codapact-0.6.0}/.github/workflows/ci.yml +0 -0
  28. {codapact-0.5.1 → codapact-0.6.0}/.github/workflows/codeql.yml +0 -0
  29. {codapact-0.5.1 → codapact-0.6.0}/.github/workflows/mutation.yml +0 -0
  30. {codapact-0.5.1 → codapact-0.6.0}/.github/workflows/nightly.yml +0 -0
  31. {codapact-0.5.1 → codapact-0.6.0}/.github/workflows/release.yml +0 -0
  32. {codapact-0.5.1 → codapact-0.6.0}/LICENSE +0 -0
  33. {codapact-0.5.1 → codapact-0.6.0}/README.md +0 -0
  34. {codapact-0.5.1 → codapact-0.6.0}/docs/architecture.md +0 -0
  35. {codapact-0.5.1 → codapact-0.6.0}/docs/branding/README.md +0 -0
  36. {codapact-0.5.1 → codapact-0.6.0}/docs/branding/mark.svg +0 -0
  37. {codapact-0.5.1 → codapact-0.6.0}/docs/branding/wordmark.svg +0 -0
  38. {codapact-0.5.1 → codapact-0.6.0}/docs/testing.md +0 -0
  39. {codapact-0.5.1 → codapact-0.6.0}/examples/library/codapact.yaml +0 -0
  40. {codapact-0.5.1 → codapact-0.6.0}/examples/library/operations.graphql +0 -0
  41. {codapact-0.5.1 → codapact-0.6.0}/examples/library/schema.graphql +0 -0
  42. {codapact-0.5.1 → codapact-0.6.0}/examples/petstore/codapact.yaml +0 -0
  43. {codapact-0.5.1 → codapact-0.6.0}/examples/petstore/openapi.yaml +0 -0
  44. {codapact-0.5.1 → codapact-0.6.0}/release-please-config.json +0 -0
  45. {codapact-0.5.1 → codapact-0.6.0}/scripts/extract_openapi_subset.py +0 -0
  46. {codapact-0.5.1 → codapact-0.6.0}/scripts/mutation_score.py +0 -0
  47. {codapact-0.5.1 → codapact-0.6.0}/scripts/verify_dist.py +0 -0
  48. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/__main__.py +0 -0
  49. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/commands/__init__.py +0 -0
  50. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/commands/model.py +0 -0
  51. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/core/__init__.py +0 -0
  52. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/core/diagnostics.py +0 -0
  53. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/core/errors.py +0 -0
  54. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/core/naming.py +0 -0
  55. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/core/net.py +0 -0
  56. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/model/__init__.py +0 -0
  57. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/model/api.py +0 -0
  58. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/model/authspec.py +0 -0
  59. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/model/migrations.py +0 -0
  60. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/model/rewrite.py +0 -0
  61. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/model/serialize.py +0 -0
  62. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/model/types.py +0 -0
  63. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/model/validate.py +0 -0
  64. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/model/values.py +0 -0
  65. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/pipeline/__init__.py +0 -0
  66. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/pipeline/defaults.py +0 -0
  67. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/plugins/__init__.py +0 -0
  68. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/plugins/external.py +0 -0
  69. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/plugins/protocol.py +0 -0
  70. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/plugins/registry.py +0 -0
  71. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/py.typed +0 -0
  72. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/runtime/__init__.py +0 -0
  73. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/runtime/abstractions.py +0 -0
  74. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/runtime/arguments.py +0 -0
  75. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/runtime/auth.py +0 -0
  76. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/runtime/cli_tools.py +0 -0
  77. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/runtime/client.py +0 -0
  78. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/runtime/codec.py +0 -0
  79. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/runtime/errors.py +0 -0
  80. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/runtime/middleware.py +0 -0
  81. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/runtime/oauth.py +0 -0
  82. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/runtime/protocols/__init__.py +0 -0
  83. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/runtime/protocols/base.py +0 -0
  84. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/runtime/protocols/graphql.py +0 -0
  85. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/runtime/protocols/http.py +0 -0
  86. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/runtime/selftest.py +0 -0
  87. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/shaping/__init__.py +0 -0
  88. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/shaping/base.py +0 -0
  89. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/shaping/engine.py +0 -0
  90. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/shaping/transforms.py +0 -0
  91. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/sources/__init__.py +0 -0
  92. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/sources/base.py +0 -0
  93. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/sources/graphql/__init__.py +0 -0
  94. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/sources/graphql/translator.py +0 -0
  95. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/sources/loader.py +0 -0
  96. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/sources/openapi/__init__.py +0 -0
  97. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/sources/openapi/translator.py +0 -0
  98. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/surface/__init__.py +0 -0
  99. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/surface/derive.py +0 -0
  100. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/surface/model.py +0 -0
  101. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/targets/__init__.py +0 -0
  102. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/targets/python/__init__.py +0 -0
  103. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/targets/python/e2e.py +0 -0
  104. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/targets/python/naming.py +0 -0
  105. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/targets/typescript/__init__.py +0 -0
  106. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/targets/typescript/library.py +0 -0
  107. {codapact-0.5.1 → codapact-0.6.0}/src/codapact/targets/typescript/runtime.ts +0 -0
  108. {codapact-0.5.1 → codapact-0.6.0}/tests/authlab.py +0 -0
  109. {codapact-0.5.1 → codapact-0.6.0}/tests/conftest.py +0 -0
  110. {codapact-0.5.1 → codapact-0.6.0}/tests/e2e/test_auth_e2e.py +0 -0
  111. {codapact-0.5.1 → codapact-0.6.0}/tests/e2e/test_cli_e2e.py +0 -0
  112. {codapact-0.5.1 → codapact-0.6.0}/tests/e2e/test_public_apis.py +0 -0
  113. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/authlab/authlab_plugin.py +0 -0
  114. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/authlab/codapact.yaml +0 -0
  115. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/authlab/fake_browser.py +0 -0
  116. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/authlab/openapi.yaml +0 -0
  117. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/authlab_smoke.ts +0 -0
  118. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/contracts/wire.yaml +0 -0
  119. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/corpus/README.md +0 -0
  120. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/corpus/countries/codapact.yaml +0 -0
  121. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/corpus/countries/operations.graphql +0 -0
  122. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/corpus/countries/schema.graphql +0 -0
  123. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/corpus/github/codapact.yaml +0 -0
  124. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/corpus/github/openapi.json +0 -0
  125. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/corpus/pokeapi/codapact.yaml +0 -0
  126. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/corpus/pokeapi/openapi.yml +0 -0
  127. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/corpus/ynab/README.md +0 -0
  128. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/corpus/ynab/codapact.yaml +0 -0
  129. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/corpus/ynab/openapi.yaml +0 -0
  130. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/library_smoke.ts +0 -0
  131. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/outline_plugin.py +0 -0
  132. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/petstore_smoke.ts +0 -0
  133. {codapact-0.5.1 → codapact-0.6.0}/tests/fixtures/wire_parity.ts +0 -0
  134. {codapact-0.5.1 → codapact-0.6.0}/tests/integration/test_cli_conformance.py +0 -0
  135. {codapact-0.5.1 → codapact-0.6.0}/tests/integration/test_cli_conventions.py +0 -0
  136. {codapact-0.5.1 → codapact-0.6.0}/tests/integration/test_contract_properties.py +0 -0
  137. {codapact-0.5.1 → codapact-0.6.0}/tests/integration/test_corpus.py +0 -0
  138. {codapact-0.5.1 → codapact-0.6.0}/tests/integration/test_generated_code_properties.py +0 -0
  139. {codapact-0.5.1 → codapact-0.6.0}/tests/integration/test_generation.py +0 -0
  140. {codapact-0.5.1 → codapact-0.6.0}/tests/integration/test_public_api_cli.py +0 -0
  141. {codapact-0.5.1 → codapact-0.6.0}/tests/integration/test_wire_parity.py +0 -0
  142. {codapact-0.5.1 → codapact-0.6.0}/tests/integration/test_ynab_contract.py +0 -0
  143. {codapact-0.5.1 → codapact-0.6.0}/tests/perf/test_scaling.py +0 -0
  144. {codapact-0.5.1 → codapact-0.6.0}/tests/public_api_contract.py +0 -0
  145. {codapact-0.5.1 → codapact-0.6.0}/tests/strategies.py +0 -0
  146. {codapact-0.5.1 → codapact-0.6.0}/tests/support.py +0 -0
  147. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_architecture.py +0 -0
  148. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_auth_and_graphql_sources.py +0 -0
  149. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_auth_sources.py +0 -0
  150. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_bundle_e2e.py +0 -0
  151. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_cli_builtins.py +0 -0
  152. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_cli_options.py +0 -0
  153. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_codec_serialize.py +0 -0
  154. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_core.py +0 -0
  155. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_guards.py +0 -0
  156. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_model.py +0 -0
  157. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_mutation_score.py +0 -0
  158. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_oauth.py +0 -0
  159. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_openapi_edges.py +0 -0
  160. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_openapi_translator_units.py +0 -0
  161. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_plugins_pipeline.py +0 -0
  162. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_public_api_findings.py +0 -0
  163. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_runtime.py +0 -0
  164. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_runtime_edges.py +0 -0
  165. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_runtime_pagination.py +0 -0
  166. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_shaping_surface_commands.py +0 -0
  167. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_sources.py +0 -0
  168. {codapact-0.5.1 → codapact-0.6.0}/tests/unit/test_target_rendering.py +0 -0
@@ -0,0 +1 @@
1
+ {".":"0.6.0"}
@@ -2,6 +2,22 @@
2
2
 
3
3
  <!-- markdownlint-configure-file { "MD024": { "siblings_only": true } } -->
4
4
 
5
+ ## [0.6.0](https://github.com/mikejhill/codapact/compare/v0.5.2...v0.6.0) (2026-11-14)
6
+
7
+
8
+ ### Features
9
+
10
+ * **auth:** credential fields for schemes that need several values ([#43](https://github.com/mikejhill/codapact/issues/43)) ([9472a7f](https://github.com/mikejhill/codapact/commit/9472a7f1ba351ad06e2b65b038b4b0fa8e45b9f3))
11
+ * **cli:** cli.env_prefix names environment variables independently of the program ([#42](https://github.com/mikejhill/codapact/issues/42)) ([f7b5041](https://github.com/mikejhill/codapact/commit/f7b504196c478d266ab0f8a3bd2ee8aea9661991))
12
+ * codapact sync and generation metadata in manifests ([#41](https://github.com/mikejhill/codapact/issues/41)) ([fc2a27c](https://github.com/mikejhill/codapact/commit/fc2a27c518790cde6f06cf95a95dd582622a6ffd))
13
+
14
+ ## [0.5.2](https://github.com/mikejhill/codapact/compare/v0.5.1...v0.5.2) (2026-11-14)
15
+
16
+
17
+ ### Bug Fixes
18
+
19
+ * **cli:** fail when --query matches nothing ([#39](https://github.com/mikejhill/codapact/issues/39)) ([08bd3aa](https://github.com/mikejhill/codapact/commit/08bd3aa5a3e45192461633c084feb7d9438cb193))
20
+
5
21
  ## [0.5.1](https://github.com/mikejhill/codapact/compare/v0.5.0...v0.5.1) (2026-11-14)
6
22
 
7
23
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: codapact
3
- Version: 0.5.1
3
+ Version: 0.6.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
@@ -16,6 +16,7 @@ version: 1
16
16
  source:
17
17
  type: openapi # openapi | graphql
18
18
  path: openapi.yaml # local path (relative to this file) or https URL
19
+ upstream: https://api.example.com/openapi.yaml # optional; remote copy `codapact sync` tracks
19
20
  documents: [] # companion documents, e.g. GraphQL operations
20
21
  options: {strict: true}
21
22
  shape: # ordered transforms; the model is re-validated after each
@@ -24,6 +25,7 @@ shape: # ordered transforms; the model is re-validated aft
24
25
  surface: {flatten_body: true, trim_namespace: true}
25
26
  cli:
26
27
  program: petstore
28
+ env_prefix: PETSTORE # optional; environment variable prefix (default: program)
27
29
  auth_plugin: my_auth:provider # optional; see Authentication
28
30
  auth: {sso: {client_id: petstore-cli, scopes: [read]}}
29
31
  e2e: # optional; tests shipped with the generated CLI
@@ -36,6 +38,12 @@ targets:
36
38
  - {plugin: [python, my_plugin.py], output: out/custom}
37
39
  ```
38
40
 
41
+ Each output directory gets a `.codapact-manifest.json`: the SHA-256 of every generated file
42
+ (used to refuse overwriting edits), the `generator` (`codapact/<version>`), `source` (type,
43
+ location, upstream, and SHA-256 of the contract and each document), `config_sha256` of the
44
+ project file, and `generated_at` (UTC). The timestamp only changes when anything else in the
45
+ manifest changes, so regenerating identical output leaves every file untouched.
46
+
39
47
  Targets that share an `output` directory share options. When `python-cli` shares the
40
48
  `python` directory, the library's `pyproject.toml` gains the CLI script entry.
41
49
 
@@ -55,6 +63,32 @@ document; the default is 64 MB. Remote contracts and generated clients honour
55
63
  `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY`. Proxy URLs must use `http://` without
56
64
  credentials; HTTPS traffic is tunnelled with `CONNECT`.
57
65
 
66
+ ### Pinned contracts and `codapact sync`
67
+
68
+ Generating from a remote `path` always uses the remote's current version. To pin a local copy
69
+ instead and still notice when the provider changes it, set `source.path` to the local file
70
+ and `source.upstream` to its URL:
71
+
72
+ | Command | Effect | Exit code |
73
+ | --- | --- | --- |
74
+ | `codapact sync` | Replaces the local file with the upstream bytes when they differ | 0, or 1 on error |
75
+ | `codapact sync --check` | Reports drift without writing (for CI) | 0 current, 3 out of date, 1 error |
76
+ | `--from URL` | Overrides `source.upstream` for one run | |
77
+
78
+ A copy that differs only in line endings is current. A copy that parses to the same JSON or YAML
79
+ as upstream (formatting only) passes `--check` and is rewritten by `codapact sync`. Drift
80
+ reports `info.version` old and new plus changed line counts, e.g.
81
+ `out of date (version 1.88.0 -> 1.89.0, +120 -30 lines): openapi.yaml vs https://...`.
82
+ `source.documents` are not synced.
83
+
84
+ `--check` also reads each target's `.codapact-manifest.json` and reports output generated from an
85
+ older local contract (`generated output is behind openapi.yaml: gen/python`), also exit 3. A CI
86
+ step that warns but does not fail:
87
+
88
+ ```yaml
89
+ - run: codapact sync --check || { [ $? -eq 3 ] && echo "::warning::contract is out of date"; }
90
+ ```
91
+
58
92
  GraphQL with `documents` generates one operation per document operation with exact result
59
93
  types. Without documents, it generates one operation per root field. A `#` comment block
60
94
  directly above a document operation becomes its description; variable defaults
@@ -111,12 +145,13 @@ Precedence: flag, then environment, then settings file.
111
145
  | Option defaults | the option itself | none | `defaults: {plan_id: "…"}` (option names, `_` or `-`) |
112
146
 
113
147
  The settings file is `--config PATH` or `$XDG_CONFIG_HOME/<program>/config.json`.
114
- `<PREFIX>` is the program name in upper snake case. `<program> --help` lists the
115
- credential variables for the contract's auth schemes.
148
+ `<PREFIX>` is `cli.env_prefix` when set (upper snake case, e.g. `ACME`), else the program
149
+ name in upper snake case (`cli.program: my-tool` gives `MY_TOOL`). `<program> --help` lists
150
+ the credential variables for the contract's auth schemes.
116
151
 
117
152
  Global options work before or after the command: `--base-url`, `--timeout`, `--config`,
118
153
  `-o/--output`, `--query PATH` (`data.items[].name`, `data.items[0]`; with `--all` the
119
- result is the item list, so `[].name`), `--dry-run`, `-v/--verbose`, `--error-format`,
154
+ result is the item list, so `[].name`; a path that matches nothing fails with exit 2 and lists the keys that exist), `--dry-run`, `-v/--verbose`, `--error-format`,
120
155
  `--allow-private`, and `--response-validation`. Command help lists them in one line;
121
156
  `<program> --help` describes each.
122
157
  `table` renders a list of objects, unwrapping single-list envelopes such as `{"data": {"items": [...]}}`.
@@ -210,12 +245,43 @@ The first source that has a credential wins, per scheme:
210
245
  5. Saved login from `<program> auth login`.
211
246
 
212
247
  `cli.auth: {SCHEME: {client_id, scopes, flow, audience}}` bakes public OAuth settings into
213
- the CLI (no secrets). `auth login` picks a flow in this order: `--flow`, then client
214
- credentials when a secret is set, then device code, then authorization code with PKCE.
248
+ the CLI (no secrets); `fields` declares [credential fields](#credential-fields).
249
+ `auth login` picks a flow in this order: `--flow`, then client credentials when a secret is
250
+ set, then device code, then authorization code with PKCE.
215
251
  `--with-token` reads a static token from stdin; `--username` saves basic credentials.
216
252
  `auth status` shows each scheme's source; `auth token` prints what a command would send;
217
253
  `doctor` reports the same, never printing secrets.
218
254
 
255
+ ### Credential fields
256
+
257
+ When a scheme needs several values that belong together (a login URL, username, password and
258
+ cookie name for a browser sign-in; a key ID and secret for request signing; an API key plus a
259
+ tenant), declare them as fields and let an auth plugin use them:
260
+
261
+ ```yaml
262
+ cli:
263
+ auth_plugin: browser_cookie_auth:provider
264
+ auth:
265
+ portal:
266
+ fields:
267
+ login_url: {help: page that sets the cookie}
268
+ username: {}
269
+ password: {secret: true}
270
+ cookie_domain: {optional: true}
271
+ ```
272
+
273
+ | Piece | Behaviour |
274
+ | --- | --- |
275
+ | `auth login --scheme portal` | Prompts for each field (secret ones hidden, saved values offered as defaults) and saves them together; `--field NAME=VALUE` sets a non-secret field without prompting |
276
+ | Environment | `<PREFIX>_<SCHEME>_<FIELD>` (e.g. `ACME_PORTAL_PASSWORD`) wins over a saved value |
277
+ | Plugin | `context.fields("portal")` returns `{name: value}`; missing required fields raise an error naming the variables and `auth login`. `context.session_key("portal")` is a store key for what the plugin obtains (e.g. a session cookie) |
278
+ | `auth status` | Shows where each field comes from (`set (VAR)`, `saved`, `missing`), never the value |
279
+ | `auth logout` | Forgets the fields and the plugin's cached session |
280
+
281
+ The sign-in itself (multi-step forms, SSO, redirects, MFA) stays in the plugin; fields only
282
+ supply and store its inputs. Field names are lower snake case; `secret`, `optional` and `help`
283
+ are the only keys.
284
+
219
285
  Saved credentials and tokens go to the OS keyring when one is usable, otherwise to a
220
286
  `0600` JSON file at `$XDG_CONFIG_HOME/<program>/credentials.json`.
221
287
  `<PREFIX>_CREDENTIAL_STORE=keyring|file|memory` forces one.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "codapact"
3
- version = "0.5.1"
3
+ version = "0.6.0"
4
4
  description = "Contracts into callable tools: generate libraries, then CLIs, from OpenAPI, GraphQL, and other API contracts."
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "codapact"
3
- version = "0.5.1"
3
+ version = "0.6.0"
4
4
  description = "Contracts into callable tools: generate libraries, then CLIs, from OpenAPI, GraphQL, and other API contracts."
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -5,4 +5,4 @@ from importlib.metadata import PackageNotFoundError, version
5
5
  try:
6
6
  __version__ = version("codapact")
7
7
  except PackageNotFoundError: # pragma: no cover - running from an unbuilt tree
8
- __version__ = "0.5.1"
8
+ __version__ = "0.6.0"
@@ -52,12 +52,19 @@ def derive_commands(
52
52
  surface: Surface,
53
53
  *,
54
54
  program: str | None = None,
55
+ env_prefix: str | None = None,
55
56
  diagnostics: Diagnostics | None = None,
56
57
  ) -> CommandTree:
57
- """Build the command tree for ``surface``; ``api`` resolves type references only."""
58
+ """Build the command tree for ``surface``; ``api`` resolves type references only.
59
+
60
+ Environment variables are named ``<env_prefix>_*``; the default is the program
61
+ name in upper snake case.
62
+ """
58
63
  diagnostics = diagnostics if diagnostics is not None else Diagnostics()
59
64
  name = Name.parse(program) if program else surface.name
60
- return CommandTree(name, _group(api, surface.root, (), diagnostics), name.screaming)
65
+ return CommandTree(
66
+ name, _group(api, surface.root, (), diagnostics), env_prefix or name.screaming
67
+ )
61
68
 
62
69
 
63
70
  def _group(
@@ -17,8 +17,11 @@ from codapact.pipeline import writer
17
17
  from codapact.pipeline.config import ProjectConfig
18
18
  from codapact.pipeline.defaults import default_registry
19
19
  from codapact.pipeline.pipeline import Pipeline, PipelineResult
20
+ from codapact.pipeline.sync import sync
20
21
 
21
22
  DEFAULT_CONFIG = "codapact.yaml"
23
+ EXIT_STALE = 3
24
+ """``codapact sync --check``: the local contract differs from upstream (errors exit 1)."""
22
25
 
23
26
 
24
27
  def build_parser() -> argparse.ArgumentParser:
@@ -37,6 +40,20 @@ def build_parser() -> argparse.ArgumentParser:
37
40
  inspect = commands.add_parser("inspect", help="print an intermediate artifact as JSON")
38
41
  inspect.add_argument("artifact", choices=("model", "surface", "commands", "report"))
39
42
  _config_options(inspect)
43
+
44
+ sync = commands.add_parser(
45
+ "sync",
46
+ help="update the local contract from source.upstream (--check: only report drift)",
47
+ description=(
48
+ "Compare the local contract (source.path) with the remote copy it tracks "
49
+ "(source.upstream or --from) and replace it when it differs. With --check, "
50
+ f"nothing is written and the exit code is {EXIT_STALE} when the local copy is "
51
+ "out of date, so CI can warn."
52
+ ),
53
+ )
54
+ sync.add_argument("-c", "--config", help=f"project file (default: ./{DEFAULT_CONFIG})")
55
+ sync.add_argument("--from", dest="upstream", metavar="URL", help="override source.upstream")
56
+ sync.add_argument("--check", action="store_true", help="report drift without writing")
40
57
  return parser
41
58
 
42
59
 
@@ -54,7 +71,7 @@ def _config_options(parser: argparse.ArgumentParser) -> None:
54
71
 
55
72
  def load_config(args: argparse.Namespace) -> ProjectConfig:
56
73
  """Build configuration from a project file or quick-mode flags."""
57
- if args.source:
74
+ if getattr(args, "source", None):
58
75
  if not args.out or not args.target:
59
76
  raise CodapactError("quick mode needs --source, --target, and --out")
60
77
  options = {"package": args.package} if args.package else {}
@@ -94,6 +111,20 @@ def _report_unchanged(config: ProjectConfig, err: TextIO) -> None:
94
111
  print(f"codapact: {root} still holds output from an earlier run", file=err)
95
112
 
96
113
 
114
+ def _sync(config: ProjectConfig, args: argparse.Namespace, out: TextIO) -> int:
115
+ result = sync(config, upstream=args.upstream, write=not args.check)
116
+ if result.written:
117
+ print(f"updated {result.local} from {result.upstream} ({result.describe()})", file=out)
118
+ print("codapact: run 'codapact generate' to regenerate", file=out)
119
+ return 0
120
+ print(result.describe(), file=out)
121
+ for line in result.describe_outputs():
122
+ print(line, file=out)
123
+ if result.behind:
124
+ print("codapact: run 'codapact generate' to regenerate", file=out)
125
+ return EXIT_STALE if args.check and (result.stale or result.behind) else 0
126
+
127
+
97
128
  def main(
98
129
  argv: Sequence[str] | None = None, *, out: TextIO | None = None, err: TextIO | None = None
99
130
  ) -> int:
@@ -103,6 +134,8 @@ def main(
103
134
  args = build_parser().parse_args(argv)
104
135
  try:
105
136
  config = load_config(args)
137
+ if args.command == "sync":
138
+ return _sync(config, args, out)
106
139
  pipeline = Pipeline(default_registry())
107
140
  if args.command == "inspect":
108
141
  result = PipelineResult()
@@ -25,6 +25,9 @@ targets:
25
25
 
26
26
  from __future__ import annotations
27
27
 
28
+ import dataclasses
29
+ import hashlib
30
+ import re
28
31
  from collections.abc import Mapping
29
32
  from dataclasses import dataclass, field
30
33
  from pathlib import Path
@@ -45,6 +48,7 @@ class SourceConfig:
45
48
  documents: tuple[str, ...] = ()
46
49
  options: Mapping[str, Any] = field(default_factory=dict)
47
50
  max_bytes: int | None = None
51
+ upstream: str | None = None
48
52
 
49
53
 
50
54
  @dataclass(frozen=True, slots=True)
@@ -68,12 +72,15 @@ class ProjectConfig:
68
72
  cli: Mapping[str, Any] = field(default_factory=dict)
69
73
  e2e: Mapping[str, Any] = field(default_factory=dict)
70
74
  base: Path = field(default_factory=Path.cwd)
75
+ digest: str | None = None
76
+ """SHA-256 of the project file, when loaded from one (recorded in output manifests)."""
71
77
 
72
78
  @classmethod
73
79
  def load(cls, path: Path) -> ProjectConfig:
74
80
  """Read and validate a configuration file."""
75
- data = parse_structured(Fetcher().fetch(str(path)))
76
- return cls.from_data(data, base=path.parent)
81
+ document = Fetcher().fetch(str(path))
82
+ config = cls.from_data(parse_structured(document), base=path.parent)
83
+ return dataclasses.replace(config, digest=hashlib.sha256(document.content).hexdigest())
77
84
 
78
85
  @classmethod
79
86
  def from_data(cls, data: Mapping[str, Any], *, base: Path) -> ProjectConfig:
@@ -90,7 +97,15 @@ class ProjectConfig:
90
97
  documents = source.get("documents", [])
91
98
  if not isinstance(documents, list) or not all(isinstance(d, str) for d in documents):
92
99
  raise ConfigError("source.documents must be a list of paths")
93
- extra_source = set(source) - {"type", "path", "url", "documents", "options", "max_bytes"}
100
+ extra_source = set(source) - {
101
+ "type",
102
+ "path",
103
+ "url",
104
+ "documents",
105
+ "options",
106
+ "max_bytes",
107
+ "upstream",
108
+ }
94
109
  if extra_source:
95
110
  raise ConfigError(f"source: unknown keys {sorted(extra_source)}")
96
111
  max_bytes = source.get("max_bytes")
@@ -98,6 +113,11 @@ class ProjectConfig:
98
113
  not isinstance(max_bytes, int) or isinstance(max_bytes, bool) or max_bytes <= 0
99
114
  ):
100
115
  raise ConfigError("source.max_bytes must be a positive integer")
116
+ upstream = source.get("upstream")
117
+ if upstream is not None and (
118
+ not isinstance(upstream, str) or not upstream.startswith(("https://", "http://"))
119
+ ):
120
+ raise ConfigError("source.upstream must be an http(s) URL")
101
121
  shape = data.get("shape", [])
102
122
  if not isinstance(shape, list):
103
123
  raise ConfigError("shape must be a list of steps")
@@ -128,6 +148,13 @@ class ProjectConfig:
128
148
  )
129
149
  if not targets:
130
150
  raise ConfigError("at least one target is required")
151
+ cli = _mapping(data.get("cli", {}), "cli")
152
+ prefix = cli.get("env_prefix")
153
+ if prefix is not None and (
154
+ not isinstance(prefix, str)
155
+ or not re.fullmatch(r"[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*", prefix)
156
+ ):
157
+ raise ConfigError("cli.env_prefix must be upper snake case, e.g. ACME or MY_TOOL")
131
158
  return cls(
132
159
  source=SourceConfig(
133
160
  type=source["type"],
@@ -135,11 +162,12 @@ class ProjectConfig:
135
162
  documents=tuple(documents),
136
163
  options=_mapping(source.get("options", {}), "source.options"),
137
164
  max_bytes=max_bytes,
165
+ upstream=upstream,
138
166
  ),
139
167
  targets=tuple(targets),
140
168
  shape=tuple(shape),
141
169
  surface=_mapping(data.get("surface", {}), "surface"),
142
- cli=_mapping(data.get("cli", {}), "cli"),
170
+ cli=cli,
143
171
  e2e=_mapping(data.get("e2e", {}), "e2e"),
144
172
  base=base,
145
173
  )
@@ -8,6 +8,7 @@ acquire → translate → validate → shape → surface → commands → genera
8
8
 
9
9
  from __future__ import annotations
10
10
 
11
+ import hashlib
11
12
  from dataclasses import dataclass, field
12
13
  from pathlib import Path
13
14
  from typing import Any
@@ -42,6 +43,8 @@ class PipelineResult:
42
43
  shape_report: list[dict[str, Any]] = field(default_factory=list)
43
44
  outputs: dict[Path, tuple[GeneratedFile, ...]] = field(default_factory=dict)
44
45
  plans: dict[Path, writer.WritePlan] = field(default_factory=dict)
46
+ source: dict[str, Any] = field(default_factory=dict)
47
+ """What was generated from: contract location, upstream and SHA-256 digests."""
45
48
 
46
49
 
47
50
  class Pipeline:
@@ -61,6 +64,7 @@ class Pipeline:
61
64
  self.fetcher.fetch(d, base=config.base, max_bytes=limit)
62
65
  for d in config.source.documents
63
66
  )
67
+ result.source = source_metadata(config, document.content, [c.content for c in companions])
64
68
  translated = source.parse(SourceInput(document, companions, config.source.options))
65
69
  result.diagnostics.extend(translated.diagnostics)
66
70
  if translated.api is None:
@@ -93,10 +97,12 @@ class Pipeline:
93
97
  api, SurfaceOptions.from_config(config.surface), result.diagnostics
94
98
  )
95
99
  program = config.cli.get("program")
100
+ prefix = config.cli.get("env_prefix")
96
101
  result.commands = derive_commands(
97
102
  api,
98
103
  result.surface,
99
104
  program=str(program) if program else None,
105
+ env_prefix=str(prefix) if prefix else None,
100
106
  diagnostics=result.diagnostics,
101
107
  )
102
108
 
@@ -124,6 +130,9 @@ class Pipeline:
124
130
  options.setdefault(
125
131
  "command", result.commands.program.kebab if result.commands else None
126
132
  )
133
+ options.setdefault(
134
+ "env_prefix", result.commands.env_prefix if result.commands else None
135
+ )
127
136
  if target.needs_commands:
128
137
  for key in ("auth_plugin", "auth"):
129
138
  if key in config.cli:
@@ -160,10 +169,32 @@ class Pipeline:
160
169
  result.plans[root] = writer.plan(root, files)
161
170
  if not dry_run:
162
171
  for plan in result.plans.values():
163
- writer.write(plan, generator=f"codapact/{__version__}")
172
+ metadata: dict[str, Any] = {"source": result.source}
173
+ if config.digest:
174
+ metadata["config_sha256"] = config.digest
175
+ writer.write(plan, generator=f"codapact/{__version__}", metadata=metadata)
164
176
  return result
165
177
 
166
178
 
179
+ def source_metadata(
180
+ config: ProjectConfig, content: bytes, companions: list[bytes]
181
+ ) -> dict[str, Any]:
182
+ """Describe the contract an output was generated from, for the manifest."""
183
+ metadata: dict[str, Any] = {
184
+ "type": config.source.type,
185
+ "location": config.source.location,
186
+ "sha256": hashlib.sha256(content).hexdigest(),
187
+ }
188
+ if config.source.upstream:
189
+ metadata["upstream"] = config.source.upstream
190
+ if config.source.documents:
191
+ metadata["documents"] = {
192
+ name: hashlib.sha256(data).hexdigest()
193
+ for name, data in zip(config.source.documents, companions, strict=True)
194
+ }
195
+ return metadata
196
+
197
+
167
198
  def _selects_first(shape: tuple[Any, ...]) -> bool:
168
199
  """Return whether shaping starts with ``select``, which may drop invalid parts."""
169
200
  return bool(shape) and isinstance(shape[0], dict) and set(shape[0]) == {"select"}
@@ -0,0 +1,162 @@
1
+ """Keep a pinned local contract in step with the remote copy it was taken from."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import difflib
6
+ import hashlib
7
+ import os
8
+ import tempfile
9
+ from dataclasses import dataclass
10
+ from enum import Enum
11
+ from pathlib import Path
12
+ from typing import Any
13
+
14
+ from codapact.core.errors import CodapactError
15
+ from codapact.pipeline.config import ProjectConfig
16
+ from codapact.pipeline.writer import read_manifest
17
+ from codapact.sources.loader import Fetcher, SourceDocument, parse_structured
18
+
19
+
20
+ class SyncState(Enum):
21
+ """How the local contract compares with upstream."""
22
+
23
+ CURRENT = "current" # same bytes (line endings aside)
24
+ FORMATTING = "formatting" # same content, different text: generation is unaffected
25
+ CHANGED = "changed"
26
+ MISSING = "missing" # no local copy yet
27
+
28
+
29
+ @dataclass(frozen=True, slots=True)
30
+ class SyncResult:
31
+ """The comparison, and whether the local file was rewritten."""
32
+
33
+ state: SyncState
34
+ local: Path
35
+ upstream: str
36
+ old_version: str | None = None
37
+ new_version: str | None = None
38
+ added: int = 0
39
+ removed: int = 0
40
+ written: bool = False
41
+ behind: tuple[Path, ...] = ()
42
+ """Output directories whose manifest records a different local contract."""
43
+
44
+ @property
45
+ def stale(self) -> bool:
46
+ """Whether generating from the local copy would differ from upstream."""
47
+ return self.state in (SyncState.CHANGED, SyncState.MISSING)
48
+
49
+ def describe_outputs(self) -> list[str]:
50
+ """One line per output directory generated from an older local contract."""
51
+ return [f"generated output is behind {self.local.name}: {root}" for root in self.behind]
52
+
53
+ def describe(self) -> str:
54
+ """One line for people and CI logs."""
55
+ where = f"{self.local} vs {self.upstream}"
56
+ if self.state is SyncState.CURRENT:
57
+ return f"up to date: {where}"
58
+ if self.state is SyncState.FORMATTING:
59
+ return f"up to date (formatting differs only): {where}"
60
+ if self.state is SyncState.MISSING:
61
+ return f"missing local copy: {where}"
62
+ details = [f"+{self.added} -{self.removed} lines"]
63
+ if self.old_version != self.new_version:
64
+ details.insert(0, f"version {self.old_version or '?'} -> {self.new_version or '?'}")
65
+ return f"out of date ({', '.join(details)}): {where}"
66
+
67
+
68
+ def sync(
69
+ config: ProjectConfig,
70
+ *,
71
+ upstream: str | None = None,
72
+ write: bool,
73
+ fetcher: Fetcher | None = None,
74
+ ) -> SyncResult:
75
+ """Compare ``source.path`` with ``upstream`` (default ``source.upstream``).
76
+
77
+ With ``write``, a stale or reformatted local copy is replaced by the upstream bytes.
78
+ """
79
+ source = config.source
80
+ url = upstream or source.upstream
81
+ if not url:
82
+ raise CodapactError("no upstream: set source.upstream or pass --from URL")
83
+ if not url.startswith(("https://", "http://")):
84
+ raise CodapactError(f"upstream must be an http(s) URL, not {url!r}")
85
+ if source.location.startswith(("https://", "http://")):
86
+ raise CodapactError("source.path is already a URL; sync needs a local copy to update")
87
+ fetcher = fetcher or Fetcher()
88
+ remote = fetcher.fetch(url, max_bytes=source.max_bytes)
89
+ local = Path(source.location)
90
+ if not local.is_absolute():
91
+ local = config.base / local
92
+ if not local.is_file():
93
+ state, current = SyncState.MISSING, None
94
+ else:
95
+ current = fetcher.fetch(str(local), max_bytes=source.max_bytes)
96
+ state = _compare(current, remote)
97
+ old, new = _version(current), _version(remote)
98
+ added = removed = 0
99
+ if state is SyncState.CHANGED and current is not None:
100
+ added, removed = _line_changes(current.text, remote.text)
101
+ written = write and state is not SyncState.CURRENT
102
+ if written:
103
+ _atomic(local, remote.content)
104
+ digest = hashlib.sha256(local.read_bytes()).hexdigest() if local.is_file() else None
105
+ behind = tuple(root for root in _outputs(config) if _generated_from(root) not in (None, digest))
106
+ return SyncResult(state, local, url, old, new, added, removed, written, behind)
107
+
108
+
109
+ def _outputs(config: ProjectConfig) -> list[Path]:
110
+ return list(dict.fromkeys(t.output for t in config.targets))
111
+
112
+
113
+ def _generated_from(root: Path) -> str | None:
114
+ """The contract digest an output directory's manifest records, if any."""
115
+ manifest = read_manifest(root) or {}
116
+ source = manifest.get("source")
117
+ digest = source.get("sha256") if isinstance(source, dict) else None
118
+ return digest if isinstance(digest, str) else None
119
+
120
+
121
+ def _compare(local: SourceDocument, remote: SourceDocument) -> SyncState:
122
+ if local.content.replace(b"\r\n", b"\n") == remote.content.replace(b"\r\n", b"\n"):
123
+ return SyncState.CURRENT
124
+ try:
125
+ same = parse_structured(local) == parse_structured(remote)
126
+ except CodapactError:
127
+ same = False # not JSON/YAML (e.g. GraphQL SDL): text decides
128
+ return SyncState.FORMATTING if same else SyncState.CHANGED
129
+
130
+
131
+ def _version(document: SourceDocument | None) -> str | None:
132
+ """The contract's ``info.version`` when it has one (OpenAPI)."""
133
+ if document is None:
134
+ return None
135
+ try:
136
+ data: Any = parse_structured(document)
137
+ except CodapactError:
138
+ return None
139
+ info = data.get("info") if isinstance(data, dict) else None
140
+ version = info.get("version") if isinstance(info, dict) else None
141
+ return str(version) if version is not None else None
142
+
143
+
144
+ def _line_changes(old: str, new: str) -> tuple[int, int]:
145
+ added = removed = 0
146
+ for line in difflib.unified_diff(old.splitlines(), new.splitlines(), lineterm="", n=0):
147
+ if line.startswith("+") and not line.startswith("+++"):
148
+ added += 1
149
+ elif line.startswith("-") and not line.startswith("---"):
150
+ removed += 1
151
+ return added, removed
152
+
153
+
154
+ def _atomic(path: Path, data: bytes) -> None:
155
+ path.parent.mkdir(parents=True, exist_ok=True)
156
+ fd, temporary = tempfile.mkstemp(prefix=".codapact-", dir=path.parent)
157
+ try:
158
+ with os.fdopen(fd, "wb") as handle:
159
+ handle.write(data)
160
+ os.replace(temporary, path)
161
+ finally:
162
+ Path(temporary).unlink(missing_ok=True)