codapact 0.8.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.
- codapact-0.9.0/.release-please-manifest.json +1 -0
- {codapact-0.8.0 → codapact-0.9.0}/CHANGELOG.md +8 -0
- {codapact-0.8.0 → codapact-0.9.0}/PKG-INFO +4 -1
- {codapact-0.8.0 → codapact-0.9.0}/README.md +3 -0
- {codapact-0.8.0 → codapact-0.9.0}/docs/configuration.md +19 -4
- {codapact-0.8.0 → codapact-0.9.0}/pyproject.toml +1 -1
- {codapact-0.8.0 → codapact-0.9.0}/pyproject.toml.orig +1 -1
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/__init__.py +1 -1
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/pipeline/pipeline.py +19 -2
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/cli.py +96 -10
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/cli_tools.py +28 -2
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/oauth.py +61 -3
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/targets/python/cli.py +20 -2
- {codapact-0.8.0 → codapact-0.9.0}/tests/integration/test_cli_conformance.py +25 -1
- {codapact-0.8.0 → codapact-0.9.0}/tests/integration/test_cli_conventions.py +1 -1
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_auth_sources.py +55 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_cli_builtins.py +11 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_cli_options.py +1 -1
- codapact-0.9.0/tests/unit/test_program_rename.py +147 -0
- {codapact-0.8.0 → codapact-0.9.0}/uv.lock +1 -1
- codapact-0.8.0/.release-please-manifest.json +0 -1
- {codapact-0.8.0 → codapact-0.9.0}/.github/workflows/ci.yml +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/.github/workflows/codeql.yml +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/.github/workflows/mutation.yml +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/.github/workflows/nightly.yml +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/.github/workflows/release.yml +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/LICENSE +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/docs/architecture.md +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/docs/branding/README.md +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/docs/branding/mark.svg +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/docs/branding/wordmark.svg +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/docs/testing.md +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/examples/library/codapact.yaml +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/examples/library/operations.graphql +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/examples/library/schema.graphql +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/examples/petstore/codapact.yaml +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/examples/petstore/openapi.yaml +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/release-please-config.json +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/scripts/extract_openapi_subset.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/scripts/mutation_score.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/scripts/verify_dist.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/__main__.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/commands/__init__.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/commands/derive.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/commands/model.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/core/__init__.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/core/diagnostics.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/core/errors.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/core/naming.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/core/net.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/model/__init__.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/model/api.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/model/authspec.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/model/migrations.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/model/rewrite.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/model/serialize.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/model/types.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/model/validate.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/model/values.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/pipeline/__init__.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/pipeline/cli.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/pipeline/config.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/pipeline/defaults.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/pipeline/sync.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/pipeline/writer.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/plugins/__init__.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/plugins/external.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/plugins/protocol.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/plugins/registry.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/py.typed +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/__init__.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/abstractions.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/arguments.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/auth.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/cli_auth.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/client.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/codec.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/credentials.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/errors.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/middleware.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/profiles.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/protocols/__init__.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/protocols/base.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/protocols/graphql.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/protocols/http.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/runtime/selftest.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/shaping/__init__.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/shaping/base.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/shaping/engine.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/shaping/transforms.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/sources/__init__.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/sources/base.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/sources/graphql/__init__.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/sources/graphql/translator.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/sources/loader.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/sources/openapi/__init__.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/sources/openapi/translator.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/surface/__init__.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/surface/derive.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/surface/model.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/targets/__init__.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/targets/python/__init__.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/targets/python/e2e.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/targets/python/library.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/targets/python/naming.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/targets/typescript/__init__.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/targets/typescript/library.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/src/codapact/targets/typescript/runtime.ts +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/authlab.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/conftest.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/e2e/test_auth_e2e.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/e2e/test_cli_e2e.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/e2e/test_public_apis.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/authlab/authlab_plugin.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/authlab/codapact.yaml +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/authlab/fake_browser.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/authlab/openapi.yaml +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/authlab_smoke.ts +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/contracts/wire.yaml +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/corpus/README.md +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/corpus/countries/codapact.yaml +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/corpus/countries/operations.graphql +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/corpus/countries/schema.graphql +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/corpus/github/codapact.yaml +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/corpus/github/openapi.json +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/corpus/pokeapi/codapact.yaml +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/corpus/pokeapi/openapi.yml +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/corpus/ynab/README.md +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/corpus/ynab/codapact.yaml +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/corpus/ynab/openapi.yaml +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/library_smoke.ts +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/outline_plugin.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/petstore_smoke.ts +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/fixtures/wire_parity.ts +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/integration/test_contract_properties.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/integration/test_corpus.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/integration/test_generated_code_properties.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/integration/test_generation.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/integration/test_public_api_cli.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/integration/test_wire_parity.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/integration/test_ynab_contract.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/perf/test_scaling.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/public_api_contract.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/strategies.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/support.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_architecture.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_auth_and_graphql_sources.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_bundle_e2e.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_cli_auth.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_codec_serialize.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_core.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_credential_fields.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_env_prefix.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_guards.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_live_ynab_findings.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_model.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_mutation_score.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_oauth.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_openapi_edges.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_openapi_translator_units.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_plugins_pipeline.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_profiles.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_public_api_findings.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_runtime.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_runtime_edges.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_runtime_pagination.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_shaping_surface_commands.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_sources.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_sync.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_target_rendering.py +0 -0
- {codapact-0.8.0 → codapact-0.9.0}/tests/unit/test_usability.py +0 -0
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{".":"0.9.0"}
|
|
@@ -2,6 +2,14 @@
|
|
|
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
|
+
|
|
5
13
|
## [0.8.0](https://github.com/mikejhill/codapact/compare/v0.7.0...v0.8.0) (2026-11-14)
|
|
6
14
|
|
|
7
15
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: codapact
|
|
3
|
-
Version: 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
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) |
|
|
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
|
|
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`
|
|
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.
|
|
@@ -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]] = {}
|
|
@@ -46,7 +46,7 @@ from codapact.runtime.errors import (
|
|
|
46
46
|
)
|
|
47
47
|
from codapact.runtime.middleware import Retry
|
|
48
48
|
from codapact.runtime.oauth import TokenStore, default_store
|
|
49
|
-
from codapact.runtime.profiles import ProfileIndex, ProfileStore, check_profile_name
|
|
49
|
+
from codapact.runtime.profiles import ProfileIndex, ProfileStore, check_profile_name
|
|
50
50
|
|
|
51
51
|
EXIT_OK = 0
|
|
52
52
|
EXIT_API = 1
|
|
@@ -293,6 +293,9 @@ class CliRuntime:
|
|
|
293
293
|
"""Per-scheme OAuth defaults baked in at generation (``cli.auth`` in codapact.yaml)."""
|
|
294
294
|
distribution: str = ""
|
|
295
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."""
|
|
296
299
|
|
|
297
300
|
@property
|
|
298
301
|
def program_version(self) -> str:
|
|
@@ -521,7 +524,9 @@ class CliRuntime:
|
|
|
521
524
|
sub = commands.add_parser(
|
|
522
525
|
"doctor",
|
|
523
526
|
help="check version, settings, credentials, and connectivity",
|
|
524
|
-
description="Diagnose configuration problems. Exits
|
|
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.",
|
|
525
530
|
)
|
|
526
531
|
sub.add_argument("--offline", action="store_true", help="skip the network check")
|
|
527
532
|
self.add_global_options(sub, hidden=True)
|
|
@@ -624,7 +629,7 @@ class CliRuntime:
|
|
|
624
629
|
def profiles(self) -> ProfileIndex:
|
|
625
630
|
"""Return the list of saved-login profiles and the default one."""
|
|
626
631
|
memory = self.env.get(f"{self.env_prefix}_CREDENTIAL_STORE", "").lower() == "memory"
|
|
627
|
-
return ProfileIndex(None if memory else
|
|
632
|
+
return ProfileIndex(None if memory else self._state_path("profiles.json"))
|
|
628
633
|
|
|
629
634
|
def profile(self, args: argparse.Namespace, file_settings: dict[str, Any]) -> tuple[str, str]:
|
|
630
635
|
"""Return the profile in effect and where it came from.
|
|
@@ -646,7 +651,7 @@ class CliRuntime:
|
|
|
646
651
|
The OS keyring or a 0600 file, with keys scoped to the profile.
|
|
647
652
|
"""
|
|
648
653
|
index = self.profiles()
|
|
649
|
-
inner = default_store(self.program, self.env, self.env_prefix)
|
|
654
|
+
inner = default_store(self.program, self.env, self.env_prefix, self.previous_programs)
|
|
650
655
|
return ProfileStore(inner, profile or index.default, on_save=index.add)
|
|
651
656
|
|
|
652
657
|
@staticmethod
|
|
@@ -707,8 +712,18 @@ class CliRuntime:
|
|
|
707
712
|
def _config_path(self, explicit: str | None) -> Path:
|
|
708
713
|
if explicit:
|
|
709
714
|
return Path(explicit)
|
|
710
|
-
|
|
711
|
-
|
|
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
|
|
712
727
|
|
|
713
728
|
def _file_settings(self, explicit: str | None) -> dict[str, Any]:
|
|
714
729
|
path = self._config_path(explicit)
|
|
@@ -883,25 +898,30 @@ class CliRuntime:
|
|
|
883
898
|
if name == "auth":
|
|
884
899
|
return self._auth(args, load_model(), fmt, out, err)
|
|
885
900
|
if name == "describe":
|
|
901
|
+
api = load_model()
|
|
886
902
|
header = {
|
|
887
903
|
"program": self.program,
|
|
888
904
|
"version": self.program_version,
|
|
889
905
|
"api": {"name": self.api_name, "version": self.api_version},
|
|
890
906
|
"usage": f"{self.program} [global options] COMMAND [arguments]",
|
|
891
907
|
"global_options": _global_options(parser),
|
|
892
|
-
"environment": self._environment(
|
|
908
|
+
"environment": self._environment(api),
|
|
893
909
|
"exit_codes": {str(k): v for k, v in EXIT_CODES.items()},
|
|
910
|
+
"start": self._start_steps(api),
|
|
894
911
|
"notes": [
|
|
895
912
|
f"{self.program} describe COMMAND adds the output JSON Schema.",
|
|
913
|
+
"Commands with the read_only trait only read; others change data.",
|
|
896
914
|
"Results print to stdout as JSON unless --output says otherwise.",
|
|
897
915
|
"Errors print to stderr; --error-format json makes them one JSON object.",
|
|
898
916
|
"JSON arguments accept inline JSON, @file, or @- for stdin.",
|
|
899
917
|
"--dry-run prints the HTTP request without sending it.",
|
|
900
918
|
],
|
|
901
919
|
}
|
|
902
|
-
api
|
|
920
|
+
if api.auth_schemes:
|
|
921
|
+
header["auth"] = self._auth_summary(api)
|
|
903
922
|
if getattr(args, "brief", False):
|
|
904
|
-
|
|
923
|
+
keep = ("program", "version", "api", "usage", "start", "auth", "exit_codes")
|
|
924
|
+
header = {k: header[k] for k in (*keep, "notes") if k in header}
|
|
905
925
|
result = cli_tools.describe(
|
|
906
926
|
parser,
|
|
907
927
|
args.words,
|
|
@@ -924,7 +944,7 @@ class CliRuntime:
|
|
|
924
944
|
checks = doctor.run(offline=args.offline)
|
|
925
945
|
rows = [c.as_dict() for c in checks]
|
|
926
946
|
render(rows, self.output_format(args, "table" if out.isatty() else "json"), out)
|
|
927
|
-
return
|
|
947
|
+
return cli_tools.doctor_exit_code(checks)
|
|
928
948
|
except CodapactError as error:
|
|
929
949
|
return emit_error(self.program, "usage", str(error), EXIT_USAGE, err)
|
|
930
950
|
finally:
|
|
@@ -960,6 +980,72 @@ class CliRuntime:
|
|
|
960
980
|
render(result, fmt if fmt != "table" else "json", out)
|
|
961
981
|
return EXIT_OK
|
|
962
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
|
+
|
|
963
1049
|
def _environment(self, api: Api) -> dict[str, str]:
|
|
964
1050
|
e = self.env_prefix
|
|
965
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 =
|
|
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
|
-
|
|
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
|
-
|
|
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",
|
|
@@ -53,6 +53,7 @@ class PythonCliTarget:
|
|
|
53
53
|
api_version=request.api.version,
|
|
54
54
|
auth_plugin=str(request.options.get("auth_plugin") or ""),
|
|
55
55
|
auth_config=_auth_config(request),
|
|
56
|
+
previous_programs=_previous_programs(request),
|
|
56
57
|
),
|
|
57
58
|
),
|
|
58
59
|
*(
|
|
@@ -98,6 +99,18 @@ def _auth_help(request: GenerationRequest) -> str:
|
|
|
98
99
|
return "\n".join(lines)
|
|
99
100
|
|
|
100
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
|
+
|
|
101
114
|
def _auth_config(request: GenerationRequest) -> dict[str, dict[str, object]]:
|
|
102
115
|
"""Validate ``cli.auth``: per-scheme OAuth defaults (client id, scopes, flow)."""
|
|
103
116
|
raw = request.options.get("auth") or {}
|
|
@@ -108,10 +121,12 @@ def _auth_config(request: GenerationRequest) -> dict[str, dict[str, object]]:
|
|
|
108
121
|
for name, value in raw.items():
|
|
109
122
|
if name not in known:
|
|
110
123
|
raise PluginError(f"cli.auth: unknown scheme {name!r}")
|
|
111
|
-
allowed = ("client_id", "scopes", "flow", "audience", "fields")
|
|
124
|
+
allowed = ("client_id", "scopes", "flow", "audience", "fields", "docs")
|
|
112
125
|
if not isinstance(value, dict) or set(value) - set(allowed):
|
|
113
126
|
# No client_secret: secrets must never be baked into generated code.
|
|
114
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")
|
|
115
130
|
config[str(name)] = dict(value)
|
|
116
131
|
if "fields" in value:
|
|
117
132
|
config[str(name)]["fields"] = _fields(str(name), value["fields"])
|
|
@@ -150,6 +165,7 @@ def render_cli(
|
|
|
150
165
|
api_version: str = "",
|
|
151
166
|
auth_plugin: str = "",
|
|
152
167
|
auth_config: dict[str, dict[str, object]] | None = None,
|
|
168
|
+
previous_programs: tuple[str, ...] = (),
|
|
153
169
|
) -> str:
|
|
154
170
|
"""Render the argparse module."""
|
|
155
171
|
handlers: list[str] = []
|
|
@@ -161,7 +177,9 @@ def render_cli(
|
|
|
161
177
|
f"CliRuntime(program={program!r}, env_prefix={tree.env_prefix!r}, "
|
|
162
178
|
f"version={version!r}, distribution={distribution!r}, "
|
|
163
179
|
f"api_name={api_name!r}, api_version={api_version!r}, "
|
|
164
|
-
f"model=_api_model, auth_plugin={auth_plugin!r}, auth_config={auth_config or {}!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
|
+
+ ")"
|
|
165
183
|
)
|
|
166
184
|
head = [
|
|
167
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
|
|
|
@@ -111,7 +111,7 @@ def test_doctor(cli, monkeypatch, server, tmp_path: Path) -> None:
|
|
|
111
111
|
cli, ["doctor", "--base-url", "http://127.0.0.1:1/v1"], monkeypatch, PETSTORE_TOKEN=""
|
|
112
112
|
)
|
|
113
113
|
checks = {c["check"]: c for c in json.loads(out)}
|
|
114
|
-
assert code ==
|
|
114
|
+
assert code == 4 and checks["connectivity"]["status"] == "fail"
|
|
115
115
|
assert checks["credentials: token"]["status"] == "warn"
|
|
116
116
|
monkeypatch.delenv("PETSTORE_ALLOW_PRIVATE")
|
|
117
117
|
code, out, _ = run_cli(cli, ["doctor", "--base-url", "http://x.test"], monkeypatch)
|