codapact 0.7.0__tar.gz → 0.9.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 (171) hide show
  1. codapact-0.9.0/.release-please-manifest.json +1 -0
  2. {codapact-0.7.0 → codapact-0.9.0}/CHANGELOG.md +15 -0
  3. {codapact-0.7.0 → codapact-0.9.0}/PKG-INFO +4 -1
  4. {codapact-0.7.0 → codapact-0.9.0}/README.md +3 -0
  5. {codapact-0.7.0 → codapact-0.9.0}/docs/configuration.md +20 -5
  6. {codapact-0.7.0 → codapact-0.9.0}/pyproject.toml +1 -1
  7. {codapact-0.7.0 → codapact-0.9.0}/pyproject.toml.orig +1 -1
  8. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/__init__.py +1 -1
  9. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/pipeline/pipeline.py +19 -2
  10. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/cli.py +117 -13
  11. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/cli_tools.py +28 -2
  12. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/oauth.py +61 -3
  13. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/targets/python/cli.py +24 -3
  14. {codapact-0.7.0 → codapact-0.9.0}/tests/integration/test_cli_conformance.py +25 -1
  15. {codapact-0.7.0 → codapact-0.9.0}/tests/integration/test_cli_conventions.py +1 -1
  16. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_auth_sources.py +55 -0
  17. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_cli_builtins.py +22 -0
  18. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_cli_options.py +1 -1
  19. codapact-0.9.0/tests/unit/test_program_rename.py +147 -0
  20. {codapact-0.7.0 → codapact-0.9.0}/uv.lock +1 -1
  21. codapact-0.7.0/.release-please-manifest.json +0 -1
  22. {codapact-0.7.0 → codapact-0.9.0}/.github/workflows/ci.yml +0 -0
  23. {codapact-0.7.0 → codapact-0.9.0}/.github/workflows/codeql.yml +0 -0
  24. {codapact-0.7.0 → codapact-0.9.0}/.github/workflows/mutation.yml +0 -0
  25. {codapact-0.7.0 → codapact-0.9.0}/.github/workflows/nightly.yml +0 -0
  26. {codapact-0.7.0 → codapact-0.9.0}/.github/workflows/release.yml +0 -0
  27. {codapact-0.7.0 → codapact-0.9.0}/LICENSE +0 -0
  28. {codapact-0.7.0 → codapact-0.9.0}/docs/architecture.md +0 -0
  29. {codapact-0.7.0 → codapact-0.9.0}/docs/branding/README.md +0 -0
  30. {codapact-0.7.0 → codapact-0.9.0}/docs/branding/mark.svg +0 -0
  31. {codapact-0.7.0 → codapact-0.9.0}/docs/branding/wordmark.svg +0 -0
  32. {codapact-0.7.0 → codapact-0.9.0}/docs/testing.md +0 -0
  33. {codapact-0.7.0 → codapact-0.9.0}/examples/library/codapact.yaml +0 -0
  34. {codapact-0.7.0 → codapact-0.9.0}/examples/library/operations.graphql +0 -0
  35. {codapact-0.7.0 → codapact-0.9.0}/examples/library/schema.graphql +0 -0
  36. {codapact-0.7.0 → codapact-0.9.0}/examples/petstore/codapact.yaml +0 -0
  37. {codapact-0.7.0 → codapact-0.9.0}/examples/petstore/openapi.yaml +0 -0
  38. {codapact-0.7.0 → codapact-0.9.0}/release-please-config.json +0 -0
  39. {codapact-0.7.0 → codapact-0.9.0}/scripts/extract_openapi_subset.py +0 -0
  40. {codapact-0.7.0 → codapact-0.9.0}/scripts/mutation_score.py +0 -0
  41. {codapact-0.7.0 → codapact-0.9.0}/scripts/verify_dist.py +0 -0
  42. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/__main__.py +0 -0
  43. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/commands/__init__.py +0 -0
  44. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/commands/derive.py +0 -0
  45. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/commands/model.py +0 -0
  46. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/core/__init__.py +0 -0
  47. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/core/diagnostics.py +0 -0
  48. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/core/errors.py +0 -0
  49. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/core/naming.py +0 -0
  50. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/core/net.py +0 -0
  51. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/model/__init__.py +0 -0
  52. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/model/api.py +0 -0
  53. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/model/authspec.py +0 -0
  54. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/model/migrations.py +0 -0
  55. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/model/rewrite.py +0 -0
  56. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/model/serialize.py +0 -0
  57. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/model/types.py +0 -0
  58. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/model/validate.py +0 -0
  59. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/model/values.py +0 -0
  60. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/pipeline/__init__.py +0 -0
  61. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/pipeline/cli.py +0 -0
  62. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/pipeline/config.py +0 -0
  63. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/pipeline/defaults.py +0 -0
  64. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/pipeline/sync.py +0 -0
  65. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/pipeline/writer.py +0 -0
  66. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/plugins/__init__.py +0 -0
  67. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/plugins/external.py +0 -0
  68. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/plugins/protocol.py +0 -0
  69. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/plugins/registry.py +0 -0
  70. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/py.typed +0 -0
  71. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/__init__.py +0 -0
  72. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/abstractions.py +0 -0
  73. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/arguments.py +0 -0
  74. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/auth.py +0 -0
  75. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/cli_auth.py +0 -0
  76. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/client.py +0 -0
  77. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/codec.py +0 -0
  78. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/credentials.py +0 -0
  79. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/errors.py +0 -0
  80. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/middleware.py +0 -0
  81. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/profiles.py +0 -0
  82. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/protocols/__init__.py +0 -0
  83. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/protocols/base.py +0 -0
  84. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/protocols/graphql.py +0 -0
  85. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/protocols/http.py +0 -0
  86. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/runtime/selftest.py +0 -0
  87. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/shaping/__init__.py +0 -0
  88. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/shaping/base.py +0 -0
  89. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/shaping/engine.py +0 -0
  90. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/shaping/transforms.py +0 -0
  91. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/sources/__init__.py +0 -0
  92. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/sources/base.py +0 -0
  93. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/sources/graphql/__init__.py +0 -0
  94. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/sources/graphql/translator.py +0 -0
  95. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/sources/loader.py +0 -0
  96. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/sources/openapi/__init__.py +0 -0
  97. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/sources/openapi/translator.py +0 -0
  98. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/surface/__init__.py +0 -0
  99. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/surface/derive.py +0 -0
  100. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/surface/model.py +0 -0
  101. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/targets/__init__.py +0 -0
  102. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/targets/python/__init__.py +0 -0
  103. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/targets/python/e2e.py +0 -0
  104. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/targets/python/library.py +0 -0
  105. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/targets/python/naming.py +0 -0
  106. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/targets/typescript/__init__.py +0 -0
  107. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/targets/typescript/library.py +0 -0
  108. {codapact-0.7.0 → codapact-0.9.0}/src/codapact/targets/typescript/runtime.ts +0 -0
  109. {codapact-0.7.0 → codapact-0.9.0}/tests/authlab.py +0 -0
  110. {codapact-0.7.0 → codapact-0.9.0}/tests/conftest.py +0 -0
  111. {codapact-0.7.0 → codapact-0.9.0}/tests/e2e/test_auth_e2e.py +0 -0
  112. {codapact-0.7.0 → codapact-0.9.0}/tests/e2e/test_cli_e2e.py +0 -0
  113. {codapact-0.7.0 → codapact-0.9.0}/tests/e2e/test_public_apis.py +0 -0
  114. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/authlab/authlab_plugin.py +0 -0
  115. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/authlab/codapact.yaml +0 -0
  116. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/authlab/fake_browser.py +0 -0
  117. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/authlab/openapi.yaml +0 -0
  118. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/authlab_smoke.ts +0 -0
  119. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/contracts/wire.yaml +0 -0
  120. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/corpus/README.md +0 -0
  121. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/corpus/countries/codapact.yaml +0 -0
  122. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/corpus/countries/operations.graphql +0 -0
  123. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/corpus/countries/schema.graphql +0 -0
  124. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/corpus/github/codapact.yaml +0 -0
  125. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/corpus/github/openapi.json +0 -0
  126. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/corpus/pokeapi/codapact.yaml +0 -0
  127. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/corpus/pokeapi/openapi.yml +0 -0
  128. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/corpus/ynab/README.md +0 -0
  129. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/corpus/ynab/codapact.yaml +0 -0
  130. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/corpus/ynab/openapi.yaml +0 -0
  131. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/library_smoke.ts +0 -0
  132. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/outline_plugin.py +0 -0
  133. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/petstore_smoke.ts +0 -0
  134. {codapact-0.7.0 → codapact-0.9.0}/tests/fixtures/wire_parity.ts +0 -0
  135. {codapact-0.7.0 → codapact-0.9.0}/tests/integration/test_contract_properties.py +0 -0
  136. {codapact-0.7.0 → codapact-0.9.0}/tests/integration/test_corpus.py +0 -0
  137. {codapact-0.7.0 → codapact-0.9.0}/tests/integration/test_generated_code_properties.py +0 -0
  138. {codapact-0.7.0 → codapact-0.9.0}/tests/integration/test_generation.py +0 -0
  139. {codapact-0.7.0 → codapact-0.9.0}/tests/integration/test_public_api_cli.py +0 -0
  140. {codapact-0.7.0 → codapact-0.9.0}/tests/integration/test_wire_parity.py +0 -0
  141. {codapact-0.7.0 → codapact-0.9.0}/tests/integration/test_ynab_contract.py +0 -0
  142. {codapact-0.7.0 → codapact-0.9.0}/tests/perf/test_scaling.py +0 -0
  143. {codapact-0.7.0 → codapact-0.9.0}/tests/public_api_contract.py +0 -0
  144. {codapact-0.7.0 → codapact-0.9.0}/tests/strategies.py +0 -0
  145. {codapact-0.7.0 → codapact-0.9.0}/tests/support.py +0 -0
  146. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_architecture.py +0 -0
  147. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_auth_and_graphql_sources.py +0 -0
  148. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_bundle_e2e.py +0 -0
  149. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_cli_auth.py +0 -0
  150. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_codec_serialize.py +0 -0
  151. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_core.py +0 -0
  152. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_credential_fields.py +0 -0
  153. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_env_prefix.py +0 -0
  154. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_guards.py +0 -0
  155. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_live_ynab_findings.py +0 -0
  156. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_model.py +0 -0
  157. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_mutation_score.py +0 -0
  158. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_oauth.py +0 -0
  159. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_openapi_edges.py +0 -0
  160. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_openapi_translator_units.py +0 -0
  161. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_plugins_pipeline.py +0 -0
  162. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_profiles.py +0 -0
  163. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_public_api_findings.py +0 -0
  164. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_runtime.py +0 -0
  165. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_runtime_edges.py +0 -0
  166. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_runtime_pagination.py +0 -0
  167. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_shaping_surface_commands.py +0 -0
  168. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_sources.py +0 -0
  169. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_sync.py +0 -0
  170. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_target_rendering.py +0 -0
  171. {codapact-0.7.0 → codapact-0.9.0}/tests/unit/test_usability.py +0 -0
@@ -0,0 +1 @@
1
+ {".":"0.9.0"}
@@ -2,6 +2,21 @@
2
2
 
3
3
  <!-- markdownlint-configure-file { "MD024": { "siblings_only": true } } -->
4
4
 
5
+ ## [0.9.0](https://github.com/mikejhill/codapact/compare/v0.8.0...v0.9.0) (2026-11-15)
6
+
7
+
8
+ ### Features
9
+
10
+ * **cli:** agent start-up path in describe; create-coda-skill skill ([#51](https://github.com/mikejhill/codapact/issues/51)) ([aecf023](https://github.com/mikejhill/codapact/commit/aecf02313d171ce644619ea6fa3a6b45cc38b040))
11
+ * **cli:** name the command after its distribution; carry logins across renames ([#52](https://github.com/mikejhill/codapact/issues/52)) ([019c6d8](https://github.com/mikejhill/codapact/commit/019c6d8b395032d7a0b3946df790d1253cbade61))
12
+
13
+ ## [0.8.0](https://github.com/mikejhill/codapact/compare/v0.7.0...v0.8.0) (2026-11-14)
14
+
15
+
16
+ ### Features
17
+
18
+ * **cli:** report the installed distribution's version ([#49](https://github.com/mikejhill/codapact/issues/49)) ([d7d663d](https://github.com/mikejhill/codapact/commit/d7d663d611548534e3657b1ffc6ec8a048ebc96d))
19
+
5
20
  ## [0.7.0](https://github.com/mikejhill/codapact/compare/v0.6.1...v0.7.0) (2026-11-14)
6
21
 
7
22
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: codapact
3
- Version: 0.7.0
3
+ Version: 0.9.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
@@ -86,4 +86,7 @@ pagination live in one tested place and improve without regenerating.
86
86
  and restish.
87
87
  - [Configuration](docs/configuration.md): `codapact.yaml`, shaping transforms, target
88
88
  options, and generated CLI settings.
89
+ - [Agent skills](skills/README.md): `create-coda-skill` writes the thin skill that lets an
90
+ agent use a coda's CLI. Install in Claude Code with
91
+ `/plugin marketplace add mikejhill/codapact`, then `/plugin install codapact@codapact`.
89
92
  - [Contributing](CONTRIBUTING.md)
@@ -69,4 +69,7 @@ pagination live in one tested place and improve without regenerating.
69
69
  and restish.
70
70
  - [Configuration](docs/configuration.md): `codapact.yaml`, shaping transforms, target
71
71
  options, and generated CLI settings.
72
+ - [Agent skills](skills/README.md): `create-coda-skill` writes the thin skill that lets an
73
+ agent use a coda's CLI. Install in Claude Code with
74
+ `/plugin marketplace add mikejhill/codapact`, then `/plugin install codapact@codapact`.
72
75
  - [Contributing](CONTRIBUTING.md)
@@ -24,8 +24,9 @@ shape: # ordered transforms; the model is re-validated aft
24
24
  - paginate: {operations: [list_pets], next: next_cursor, items: items}
25
25
  surface: {flatten_body: true, trim_namespace: true}
26
26
  cli:
27
- program: petstore
27
+ program: petstore # optional; default: the Python distribution that ships the CLI
28
28
  env_prefix: PETSTORE # optional; environment variable prefix (default: program)
29
+ previous_programs: [pets] # optional; earlier names whose logins and settings carry over
29
30
  auth_plugin: my_auth:provider # optional; see Authentication
30
31
  auth: {sso: {client_id: petstore-cli, scopes: [read]}}
31
32
  e2e: # optional; tests shipped with the generated CLI
@@ -159,14 +160,26 @@ result is the item list, so `[].name`; a path that matches nothing fails with ex
159
160
  `jsonl` prints one JSON value per line, unwrapping the same envelopes as `table`, and streams
160
161
  `--all` results page by page. Output to a pipe or file is UTF-8 on every platform.
161
162
 
163
+ ### Program name
164
+
165
+ The command is named after the Python distribution that ships it (`distribution`, else
166
+ `package` with `-` for `_`), so `uvx acme-api --help` runs it with no `--from`. When no
167
+ Python target names one, it is the API's name. `cli.program` overrides both.
168
+
169
+ Renaming a CLI moves its keyring entries and settings directory to the new name. List
170
+ the old names in `cli.previous_programs`: a saved login found only under an old name
171
+ moves to the new one the first time it is read, `auth logout` removes every copy, and
172
+ the settings file and profiles are read from the old directory until the new one
173
+ exists. Set `cli.env_prefix` too if the environment variables should keep their names.
174
+
162
175
  ### Conventions every generated CLI follows
163
176
 
164
177
  | Need | How |
165
178
  | --- | --- |
166
179
  | 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. |
167
- | Version | `-V`/`--version`: `poke 0.1.0 (PokéAPI 2.10.0; codapact 0.4.0)` |
168
- | 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 |
169
- | 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 |
180
+ | Version | `-V`/`--version`: `poke 0.1.0 (PokéAPI 2.10.0; codapact 0.4.0)`; the installed distribution's version when it differs from the generated `version` option (so a release tool can bump packaging alone) |
181
+ | 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, `start` (the steps an agent follows: doctor, credentials, describe, dry run) and `auth` (per scheme: environment variables, `auth login` commands, `docs` on how to get the credential, and whether every command or only some need it). `describe --brief` keeps those plus names, summaries, and usage lines, so one call is enough to start; agent skills for a coda point here instead of repeating it (see [Agent skills for codas](../skills/README.md)). Naming one command (or passing `--schemas`) adds the JSON Schema of its output and of each JSON-valued argument |
182
+ | Diagnosis | `<program> doctor [--offline]`: version, settings file, base URL and its source, credentials (set or missing, never printed), proxy, connectivity. Missing credentials fail only when every command needs them. Table on a terminal, JSON otherwise; exit `0` ready, `3` credentials missing or rejected, `4` API unreachable, `1` any other failed check |
170
183
  | Completion | `<program> completion bash\|zsh\|fish\|powershell` prints a script that asks the program for candidates |
171
184
  | 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 |
172
185
  | Tracing | `-v`/`--verbose` logs each request line and response status, size, and time to stderr, masking credential values |
@@ -246,7 +259,9 @@ The first source that has a credential wins, per scheme:
246
259
  5. Saved login from `<program> auth login`.
247
260
 
248
261
  `cli.auth: {SCHEME: {client_id, scopes, flow, audience}}` bakes public OAuth settings into
249
- the CLI (no secrets); `fields` declares [credential fields](#credential-fields).
262
+ the CLI (no secrets); `fields` declares [credential fields](#credential-fields); `docs` tells a
263
+ person how to get the credential (shown in `describe` under `auth`, e.g. "Create a personal
264
+ access token under Account Settings > Developer Settings").
250
265
  `auth login` picks a flow in this order: `--flow`, then client credentials when a secret is
251
266
  set, then device code, then authorization code with PKCE.
252
267
  `--with-token` reads a static token from stdin; `--username` saves basic credentials.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "codapact"
3
- version = "0.7.0"
3
+ version = "0.9.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.7.0"
3
+ version = "0.9.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.7.0"
8
+ __version__ = "0.9.0"
@@ -96,7 +96,7 @@ class Pipeline:
96
96
  result.surface = derive_surface(
97
97
  api, SurfaceOptions.from_config(config.surface), result.diagnostics
98
98
  )
99
- program = config.cli.get("program")
99
+ program = config.cli.get("program") or _distribution_program(config)
100
100
  prefix = config.cli.get("env_prefix")
101
101
  result.commands = derive_commands(
102
102
  api,
@@ -134,7 +134,7 @@ class Pipeline:
134
134
  "env_prefix", result.commands.env_prefix if result.commands else None
135
135
  )
136
136
  if target.needs_commands:
137
- for key in ("auth_plugin", "auth"):
137
+ for key in ("auth_plugin", "auth", "previous_programs"):
138
138
  if key in config.cli:
139
139
  options.setdefault(key, config.cli[key])
140
140
  if config.e2e:
@@ -200,6 +200,23 @@ def _selects_first(shape: tuple[Any, ...]) -> bool:
200
200
  return bool(shape) and isinstance(shape[0], dict) and set(shape[0]) == {"select"}
201
201
 
202
202
 
203
+ def _distribution_program(config: ProjectConfig) -> str | None:
204
+ """Default program name: the distribution of the Python package that ships the CLI.
205
+
206
+ A CLI installed as ``acme-api`` is then also run as ``acme-api``, so
207
+ ``uvx acme-api`` works without ``--from``. Falls back to the API name when no
208
+ Python target names a distribution or package.
209
+ """
210
+ outputs = {t.output for t in config.targets if t.name == "python-cli"}
211
+ shared = _shared_options(config)
212
+ for output in outputs:
213
+ options = shared.get(output, {})
214
+ name = options.get("distribution") or options.get("package")
215
+ if name:
216
+ return str(name).replace("_", "-")
217
+ return None
218
+
219
+
203
220
  def _shared_options(config: ProjectConfig) -> dict[Path, dict[str, Any]]:
204
221
  """Targets sharing an output directory share options (e.g. the package name)."""
205
222
  shared: dict[Path, dict[str, Any]] = {}
@@ -9,6 +9,7 @@ from __future__ import annotations
9
9
 
10
10
  import argparse
11
11
  import difflib
12
+ import importlib.metadata
12
13
  import json
13
14
  import os
14
15
  import re
@@ -45,7 +46,7 @@ from codapact.runtime.errors import (
45
46
  )
46
47
  from codapact.runtime.middleware import Retry
47
48
  from codapact.runtime.oauth import TokenStore, default_store
48
- from codapact.runtime.profiles import ProfileIndex, ProfileStore, check_profile_name, profiles_path
49
+ from codapact.runtime.profiles import ProfileIndex, ProfileStore, check_profile_name
49
50
 
50
51
  EXIT_OK = 0
51
52
  EXIT_API = 1
@@ -290,6 +291,26 @@ class CliRuntime:
290
291
  """Default ``package.module:factory`` auth plugin (``cli.auth_plugin`` in codapact.yaml)."""
291
292
  auth_config: Mapping[str, Mapping[str, Any]] | None = None
292
293
  """Per-scheme OAuth defaults baked in at generation (``cli.auth`` in codapact.yaml)."""
294
+ distribution: str = ""
295
+ """Installed distribution name; its metadata version wins over ``version``."""
296
+ previous_programs: tuple[str, ...] = ()
297
+ """Earlier program names (``cli.previous_programs``): their saved logins, settings
298
+ file, and profiles keep working after a rename."""
299
+
300
+ @property
301
+ def program_version(self) -> str:
302
+ """Return the installed distribution's version, else the generated ``version``.
303
+
304
+ Packaging may set the release version outside the generated code (for example a
305
+ hand-written ``pyproject.toml`` that release tooling bumps), so the installed
306
+ metadata is the source of truth when it exists.
307
+ """
308
+ if self.distribution:
309
+ try:
310
+ return importlib.metadata.version(self.distribution)
311
+ except importlib.metadata.PackageNotFoundError:
312
+ pass
313
+ return self.version
293
314
 
294
315
  @property
295
316
  def env(self) -> dict[str, str]:
@@ -326,7 +347,7 @@ class CliRuntime:
326
347
  """Return ``program version (API version; codapact version)``."""
327
348
  api = f"{self.api_name} {self.api_version}".strip()
328
349
  parts = [p for p in (api, f"codapact {__version__}") if p]
329
- return f"{self.program} {self.version or '0.0.0'} ({'; '.join(parts)})"
350
+ return f"{self.program} {self.program_version or '0.0.0'} ({'; '.join(parts)})"
330
351
 
331
352
  def epilog(self, credentials: str = "", examples: Sequence[str] = ()) -> str:
332
353
  """Return the root help epilog: examples, credentials, settings, exit codes."""
@@ -503,7 +524,9 @@ class CliRuntime:
503
524
  sub = commands.add_parser(
504
525
  "doctor",
505
526
  help="check version, settings, credentials, and connectivity",
506
- description="Diagnose configuration problems. Exits 1 when a check fails.",
527
+ description="Diagnose configuration problems. Exits 0 when ready, 3 when "
528
+ "credentials are missing or rejected, 4 when the API is unreachable, and 1 "
529
+ "when another check fails.",
507
530
  )
508
531
  sub.add_argument("--offline", action="store_true", help="skip the network check")
509
532
  self.add_global_options(sub, hidden=True)
@@ -606,7 +629,7 @@ class CliRuntime:
606
629
  def profiles(self) -> ProfileIndex:
607
630
  """Return the list of saved-login profiles and the default one."""
608
631
  memory = self.env.get(f"{self.env_prefix}_CREDENTIAL_STORE", "").lower() == "memory"
609
- return ProfileIndex(None if memory else profiles_path(self.program, self.env))
632
+ return ProfileIndex(None if memory else self._state_path("profiles.json"))
610
633
 
611
634
  def profile(self, args: argparse.Namespace, file_settings: dict[str, Any]) -> tuple[str, str]:
612
635
  """Return the profile in effect and where it came from.
@@ -628,7 +651,7 @@ class CliRuntime:
628
651
  The OS keyring or a 0600 file, with keys scoped to the profile.
629
652
  """
630
653
  index = self.profiles()
631
- inner = default_store(self.program, self.env, self.env_prefix)
654
+ inner = default_store(self.program, self.env, self.env_prefix, self.previous_programs)
632
655
  return ProfileStore(inner, profile or index.default, on_save=index.add)
633
656
 
634
657
  @staticmethod
@@ -689,8 +712,18 @@ class CliRuntime:
689
712
  def _config_path(self, explicit: str | None) -> Path:
690
713
  if explicit:
691
714
  return Path(explicit)
692
- root = self.env.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
693
- return Path(root) / self.program / "config.json"
715
+ return self._state_path("config.json")
716
+
717
+ def _state_path(self, name: str) -> Path:
718
+ """``$XDG_CONFIG_HOME/<program>/<name>``, or a previous name's copy when only it exists."""
719
+ root = Path(self.env.get("XDG_CONFIG_HOME") or str(Path.home() / ".config"))
720
+ current = root / self.program / name
721
+ if current.exists():
722
+ return current
723
+ for old in self.previous_programs:
724
+ if (root / old / name).is_file():
725
+ return root / old / name
726
+ return current
694
727
 
695
728
  def _file_settings(self, explicit: str | None) -> dict[str, Any]:
696
729
  path = self._config_path(explicit)
@@ -865,25 +898,30 @@ class CliRuntime:
865
898
  if name == "auth":
866
899
  return self._auth(args, load_model(), fmt, out, err)
867
900
  if name == "describe":
901
+ api = load_model()
868
902
  header = {
869
903
  "program": self.program,
870
- "version": self.version,
904
+ "version": self.program_version,
871
905
  "api": {"name": self.api_name, "version": self.api_version},
872
906
  "usage": f"{self.program} [global options] COMMAND [arguments]",
873
907
  "global_options": _global_options(parser),
874
- "environment": self._environment(load_model()),
908
+ "environment": self._environment(api),
875
909
  "exit_codes": {str(k): v for k, v in EXIT_CODES.items()},
910
+ "start": self._start_steps(api),
876
911
  "notes": [
877
912
  f"{self.program} describe COMMAND adds the output JSON Schema.",
913
+ "Commands with the read_only trait only read; others change data.",
878
914
  "Results print to stdout as JSON unless --output says otherwise.",
879
915
  "Errors print to stderr; --error-format json makes them one JSON object.",
880
916
  "JSON arguments accept inline JSON, @file, or @- for stdin.",
881
917
  "--dry-run prints the HTTP request without sending it.",
882
918
  ],
883
919
  }
884
- api = load_model()
920
+ if api.auth_schemes:
921
+ header["auth"] = self._auth_summary(api)
885
922
  if getattr(args, "brief", False):
886
- header = {k: header[k] for k in ("program", "version", "api", "usage", "notes")}
923
+ keep = ("program", "version", "api", "usage", "start", "auth", "exit_codes")
924
+ header = {k: header[k] for k in (*keep, "notes") if k in header}
887
925
  result = cli_tools.describe(
888
926
  parser,
889
927
  args.words,
@@ -896,7 +934,7 @@ class CliRuntime:
896
934
  return EXIT_OK
897
935
  doctor = cli_tools.Doctor(
898
936
  program=self.program,
899
- version=self.version,
937
+ version=self.program_version,
900
938
  env_prefix=self.env_prefix,
901
939
  env=self.env,
902
940
  load_model=load_model,
@@ -906,7 +944,7 @@ class CliRuntime:
906
944
  checks = doctor.run(offline=args.offline)
907
945
  rows = [c.as_dict() for c in checks]
908
946
  render(rows, self.output_format(args, "table" if out.isatty() else "json"), out)
909
- return EXIT_API if any(c.status == "fail" for c in checks) else EXIT_OK
947
+ return cli_tools.doctor_exit_code(checks)
910
948
  except CodapactError as error:
911
949
  return emit_error(self.program, "usage", str(error), EXIT_USAGE, err)
912
950
  finally:
@@ -942,6 +980,72 @@ class CliRuntime:
942
980
  render(result, fmt if fmt != "table" else "json", out)
943
981
  return EXIT_OK
944
982
 
983
+ def _start_steps(self, api: Api) -> list[str]:
984
+ """Return the steps an agent or script follows to start using this CLI."""
985
+ p = self.program
986
+ steps = [
987
+ f"Run {p} doctor once per session. Exit 0 means ready; 3 means credentials are "
988
+ "missing or rejected; 4 means the API is unreachable; 1 means another check "
989
+ "failed. Each row's detail says how to fix it.",
990
+ ]
991
+ if api.auth_schemes:
992
+ steps.append(
993
+ "Credentials come from a person: never invent one. auth lists where each is "
994
+ f"read from. {p} auth status shows what is configured; "
995
+ f"{p} auth profiles lists saved accounts (choose one with --profile NAME)."
996
+ )
997
+ steps += [
998
+ f"Find a command with {p} describe --brief, then read its arguments and output "
999
+ f"JSON Schema with {p} describe COMMAND. {p} COMMAND --help shows the same "
1000
+ "with examples.",
1001
+ "Pass --dry-run to see the HTTP request a command would send without sending it.",
1002
+ ]
1003
+ return steps
1004
+
1005
+ def _auth_summary(self, api: Api) -> dict[str, Any]:
1006
+ """Describe each credential scheme: where it is read from and how to save one."""
1007
+ p = self.program
1008
+ env = EnvAuth(self.env_prefix, {})
1009
+ many = len(api.auth_schemes) > 1
1010
+ schemes = []
1011
+ for scheme in api.auth_schemes:
1012
+ variable = env.variable(scheme)
1013
+ login = f"{p} auth login" + (f" --scheme {scheme.name}" if many else "")
1014
+ fields = field_specs((self.auth_config or {}).get(scheme.name))
1015
+ entry: dict[str, Any] = {"scheme": scheme.name, "kind": scheme.kind.value}
1016
+ docs = (self.auth_config or {}).get(scheme.name, {}).get("docs") or scheme.docs
1017
+ if docs:
1018
+ entry["docs"] = docs
1019
+ if fields:
1020
+ entry["environment"] = [f"{variable}_{name.upper()}" for name in fields]
1021
+ entry["login"] = login
1022
+ elif scheme.kind is AuthKind.CUSTOM:
1023
+ entry["environment"] = [f"{self.env_prefix}_AUTH_PLUGIN"]
1024
+ elif scheme.kind is AuthKind.BASIC:
1025
+ entry["environment"] = [f"{variable}_USERNAME", f"{variable}_PASSWORD"]
1026
+ entry["login"] = login
1027
+ entry["login_stdin"] = f"{login} --username USER --with-token"
1028
+ else:
1029
+ entry["environment"] = [variable, f"{variable}_COMMAND"]
1030
+ entry["login"] = login
1031
+ entry["login_stdin"] = f"{login} --with-token"
1032
+ if scheme.kind is AuthKind.OAUTH2 and (scheme.flows or scheme.discovery_url):
1033
+ flows = sorted({f.kind.value for f in scheme.flows})
1034
+ if flows:
1035
+ entry["flows"] = flows
1036
+ schemes.append(entry)
1037
+ summary: dict[str, Any] = {}
1038
+ required = cli_tools.auth_required(api)
1039
+ if required:
1040
+ summary["required_for"] = required
1041
+ summary["schemes"] = schemes
1042
+ summary["note"] = (
1043
+ f"{p} auth login prompts without echo (or runs an OAuth sign-in) and saves to the "
1044
+ "OS keyring; a person runs it in their own terminal. login_stdin reads the secret "
1045
+ "from stdin. Environment variables take precedence over saved logins."
1046
+ )
1047
+ return summary
1048
+
945
1049
  def _environment(self, api: Api) -> dict[str, str]:
946
1050
  e = self.env_prefix
947
1051
  found = {
@@ -461,6 +461,26 @@ def _proxy_check(proxy: str) -> Check:
461
461
  return Check("proxy", "fail", "proxy address in the environment is malformed")
462
462
 
463
463
 
464
+ def auth_required(api: Api) -> str | None:
465
+ """Say which commands need credentials: ``every command``, ``some commands``, or None."""
466
+ if not api.auth_schemes or not api.operations:
467
+ return None
468
+ anonymous = [op.auth.anonymous_allowed for op in api.operations]
469
+ if not any(anonymous):
470
+ return "every command"
471
+ return None if all(anonymous) else "some commands"
472
+
473
+
474
+ def doctor_exit_code(checks: Sequence[Check]) -> int:
475
+ """Map failed checks to the CLI exit codes: 3 credentials, 4 network, 1 anything else."""
476
+ failed = {c.check.split(":")[0] for c in checks if c.status == "fail"}
477
+ if not failed:
478
+ return 0
479
+ if failed - {"credentials", "connectivity"}:
480
+ return 1
481
+ return 3 if "credentials" in failed else 4
482
+
483
+
464
484
  @dataclass(frozen=True, slots=True)
465
485
  class Doctor:
466
486
  """Inputs the doctor needs; ``settings`` resolves client options and their sources."""
@@ -539,13 +559,19 @@ class Doctor:
539
559
  return [Check("credentials", "info", "the contract declares no credentials")]
540
560
  if not isinstance(chain, ChainAuth):
541
561
  chain = ChainAuth((EnvAuth(self.env_prefix, self.env),))
562
+ sources = {scheme.name: describe_source(chain, scheme) for scheme in api.auth_schemes}
563
+ # Missing credentials only fail when nothing can run without them.
564
+ blocking = auth_required(api) == "every command" and all(
565
+ source is None for source in sources.values()
566
+ )
542
567
  found = []
543
568
  for scheme in api.auth_schemes:
544
- source = describe_source(chain, scheme)
569
+ source = sources[scheme.name]
545
570
  label = f"credentials: {scheme.name}"
546
571
  if source is None:
547
572
  hint = chain.hint(scheme) or "not configured"
548
- found.append(Check(label, "warn", f"missing ({scheme.kind.value}); {hint}"))
573
+ status = "fail" if blocking else "warn"
574
+ found.append(Check(label, status, f"missing ({scheme.kind.value}); {hint}"))
549
575
  elif source.startswith("error"):
550
576
  found.append(Check(label, "fail", f"{source} ({scheme.kind.value})"))
551
577
  else:
@@ -316,20 +316,77 @@ def store_location(store: TokenStore, key: str | None = None) -> str:
316
316
  return str(getattr(store, "location", type(store).__name__))
317
317
 
318
318
 
319
- def default_store(program: str, env: Mapping[str, str], prefix: str) -> TokenStore:
319
+ @dataclass(frozen=True, slots=True)
320
+ class RenamedStore:
321
+ """A store that takes over secrets saved under the program's previous names.
322
+
323
+ A key missing from ``current`` is looked up in each of ``previous`` in order; the
324
+ first hit is saved to ``current`` and removed from where it was. ``delete`` clears
325
+ every copy, so ``auth logout`` after a rename leaves nothing behind.
326
+ """
327
+
328
+ current: TokenStore
329
+ previous: tuple[TokenStore, ...]
330
+
331
+ @property
332
+ def location(self) -> str:
333
+ """Describe where secrets live."""
334
+ return store_location(self.current)
335
+
336
+ def where(self, key: str) -> str:
337
+ """Describe where ``key`` lives."""
338
+ return store_location(self.current, key)
339
+
340
+ def load(self, key: str) -> dict[str, Any] | None:
341
+ """Return ``key``, moving it from a previous name when only that has it."""
342
+ data = self.current.load(key)
343
+ if data is not None:
344
+ return data
345
+ for old in self.previous:
346
+ data = old.load(key)
347
+ if data is not None:
348
+ self.current.save(key, data)
349
+ old.delete(key)
350
+ return data
351
+ return None
352
+
353
+ def save(self, key: str, data: dict[str, Any]) -> None:
354
+ """Store ``data`` under ``key``."""
355
+ self.current.save(key, data)
356
+
357
+ def delete(self, key: str) -> bool:
358
+ """Remove ``key`` under the current and every previous name."""
359
+ removed = self.current.delete(key)
360
+ for old in self.previous:
361
+ removed = old.delete(key) or removed
362
+ return removed
363
+
364
+
365
+ def default_store(
366
+ program: str, env: Mapping[str, str], prefix: str, previous: Sequence[str] = ()
367
+ ) -> TokenStore:
320
368
  """Pick the credential store for a CLI.
321
369
 
322
370
  ``<PREFIX>_CREDENTIAL_STORE`` chooses ``keyring``, ``file``, or ``memory``;
323
371
  by default the keyring is used when the ``keyring`` package is installed and
324
372
  has a usable backend, and a 0600 file in the config directory otherwise.
373
+ ``previous`` lists names the program had before: logins saved under them move
374
+ to the current name the first time they are read.
325
375
  """
326
376
  choice = env.get(f"{prefix}_CREDENTIAL_STORE", "").lower()
377
+ if choice == "memory":
378
+ return MemoryTokenStore()
379
+ current = _named_store(program, env, choice)
380
+ if not previous:
381
+ return current
382
+ return RenamedStore(current, tuple(_named_store(name, env, choice) for name in previous))
383
+
384
+
385
+ def _named_store(program: str, env: Mapping[str, str], choice: str) -> TokenStore:
327
386
  root = env.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
328
387
  file_store = FileTokenStore(Path(root) / program / "credentials.json")
329
388
  if choice == "file":
330
389
  return file_store
331
- if choice == "memory":
332
- return MemoryTokenStore()
333
390
  keyring = _usable_keyring()
334
391
  if keyring is not None:
335
392
  return KeyringTokenStore(keyring_service(program), keyring, legacy_service=program)
@@ -904,6 +961,7 @@ __all__ = [
904
961
  "Grant",
905
962
  "KeyringTokenStore",
906
963
  "keyring_service",
964
+ "RenamedStore",
907
965
  "store_location",
908
966
  "MemoryTokenStore",
909
967
  "OAuth2",
@@ -48,10 +48,12 @@ class PythonCliTarget:
48
48
  request.api.docs or request.api.name,
49
49
  _auth_help(request),
50
50
  version=options.version,
51
+ distribution=options.distribution,
51
52
  api_name=request.api.name,
52
53
  api_version=request.api.version,
53
54
  auth_plugin=str(request.options.get("auth_plugin") or ""),
54
55
  auth_config=_auth_config(request),
56
+ previous_programs=_previous_programs(request),
55
57
  ),
56
58
  ),
57
59
  *(
@@ -97,6 +99,18 @@ def _auth_help(request: GenerationRequest) -> str:
97
99
  return "\n".join(lines)
98
100
 
99
101
 
102
+ def _previous_programs(request: GenerationRequest) -> tuple[str, ...]:
103
+ """``cli.previous_programs``: names whose saved logins and settings carry over."""
104
+ raw = request.options.get("previous_programs") or ()
105
+ if isinstance(raw, str):
106
+ raw = (raw,)
107
+ names = tuple(str(name) for name in raw)
108
+ for name in names:
109
+ if not re.fullmatch(r"[a-z0-9][a-z0-9._-]*", name):
110
+ raise PluginError(f"cli.previous_programs: invalid program name {name!r}")
111
+ return names
112
+
113
+
100
114
  def _auth_config(request: GenerationRequest) -> dict[str, dict[str, object]]:
101
115
  """Validate ``cli.auth``: per-scheme OAuth defaults (client id, scopes, flow)."""
102
116
  raw = request.options.get("auth") or {}
@@ -107,10 +121,12 @@ def _auth_config(request: GenerationRequest) -> dict[str, dict[str, object]]:
107
121
  for name, value in raw.items():
108
122
  if name not in known:
109
123
  raise PluginError(f"cli.auth: unknown scheme {name!r}")
110
- allowed = ("client_id", "scopes", "flow", "audience", "fields")
124
+ allowed = ("client_id", "scopes", "flow", "audience", "fields", "docs")
111
125
  if not isinstance(value, dict) or set(value) - set(allowed):
112
126
  # No client_secret: secrets must never be baked into generated code.
113
127
  raise PluginError(f"cli.auth.{name} allows {', '.join(allowed)}")
128
+ if not isinstance(value.get("docs", ""), str):
129
+ raise PluginError(f"cli.auth.{name}.docs must be a string")
114
130
  config[str(name)] = dict(value)
115
131
  if "fields" in value:
116
132
  config[str(name)]["fields"] = _fields(str(name), value["fields"])
@@ -144,10 +160,12 @@ def render_cli(
144
160
  auth_help: str = "",
145
161
  *,
146
162
  version: str = "0.1.0",
163
+ distribution: str = "",
147
164
  api_name: str = "",
148
165
  api_version: str = "",
149
166
  auth_plugin: str = "",
150
167
  auth_config: dict[str, dict[str, object]] | None = None,
168
+ previous_programs: tuple[str, ...] = (),
151
169
  ) -> str:
152
170
  """Render the argparse module."""
153
171
  handlers: list[str] = []
@@ -157,8 +175,11 @@ def render_cli(
157
175
  credentials = f"credentials:\n{auth_help}" if auth_help else ""
158
176
  runtime = (
159
177
  f"CliRuntime(program={program!r}, env_prefix={tree.env_prefix!r}, "
160
- f"version={version!r}, api_name={api_name!r}, api_version={api_version!r}, "
161
- f"model=_api_model, auth_plugin={auth_plugin!r}, auth_config={auth_config or {}!r})"
178
+ f"version={version!r}, distribution={distribution!r}, "
179
+ f"api_name={api_name!r}, api_version={api_version!r}, "
180
+ f"model=_api_model, auth_plugin={auth_plugin!r}, auth_config={auth_config or {}!r}"
181
+ + (f", previous_programs={previous_programs!r}" if previous_programs else "")
182
+ + ")"
162
183
  )
163
184
  head = [
164
185
  '"""Command line interface generated from the command model. Do not edit."""\n',
@@ -181,6 +181,26 @@ def test_describe_brief_is_smaller(cli: Cli) -> None:
181
181
  assert all(set(c) <= {"command", "summary", "usage", "traits"} for c in commands)
182
182
 
183
183
 
184
+ def test_describe_brief_tells_an_agent_how_to_start(cli: Cli) -> None:
185
+ """Skills only point at the CLI, so the brief catalog must carry setup and auth."""
186
+ program = cli.example.program
187
+ brief = cli.json("describe", "--brief")
188
+ assert {"start", "exit_codes", "notes"} <= set(brief)
189
+ start = " ".join(brief["start"])
190
+ for text in (f"{program} doctor", f"{program} describe COMMAND", "--dry-run"):
191
+ assert text in start
192
+ assert set(brief["exit_codes"]) >= {"0", "1", "2", "3", "4"}
193
+ catalog = cli.json("describe")
194
+ if "auth" not in catalog:
195
+ return
196
+ assert brief["auth"] == catalog["auth"]
197
+ for scheme in catalog["auth"]["schemes"]:
198
+ assert scheme["environment"]
199
+ if "login" in scheme:
200
+ assert scheme["login"].startswith(f"{program} auth login")
201
+ assert f"{program} auth status" in start
202
+
203
+
184
204
  def test_describe_one_command_has_a_valid_output_schema(cli: Cli) -> None:
185
205
  commands = cli.json("describe")["commands"]
186
206
  with_schema = 0
@@ -200,7 +220,11 @@ def test_describe_one_command_has_a_valid_output_schema(cli: Cli) -> None:
200
220
  def test_doctor_offline(cli: Cli) -> None:
201
221
  code, out, _ = cli("doctor", "--offline")
202
222
  checks = {c["check"]: c for c in json.loads(out)}
203
- assert code in (0, 1)
223
+ assert code in (0, 1, 3)
224
+ if code == 3:
225
+ assert any(
226
+ c.startswith("credentials:") and v["status"] == "fail" for c, v in checks.items()
227
+ )
204
228
  assert checks["cli"]["status"] == "ok" and checks["connectivity"]["status"] == "skip"
205
229
  assert "base url" in checks and "settings file" in checks
206
230