developer-platform-cli 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

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.
@@ -1,9 +1,11 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: developer-platform-cli
3
- Version: 0.1.0
3
+ Version: 0.2.0
4
4
  Summary: Command-line client for the Developer Platform API
5
5
  Requires-Python: >=3.12
6
6
  Requires-Dist: httpx<1,>=0.28
7
+ Requires-Dist: keyring<26,>=25
8
+ Requires-Dist: platformdirs<5,>=4
7
9
  Requires-Dist: pydantic<3,>=2.10
8
10
  Requires-Dist: rich<14,>=13.9
9
11
  Requires-Dist: typer<1,>=0.15
@@ -14,9 +16,13 @@ Description-Content-Type: text/markdown
14
16
 
15
17
  # Developer Platform CLI
16
18
 
17
- `devplat` is the command-line client for the Developer Platform API. Its first
18
- supported workflow is CI-style deployment using a project-scoped deployment
19
- credential supplied only through environment variables.
19
+ This source-adjacent README provides the minimal development example. The
20
+ canonical user documentation is the [CLI guide](../../docs/developers/cli.md);
21
+ implementation ownership is in the [maintainer guide](../../docs/maintainers/cli.md).
22
+
23
+ `devplat` is the command-line client for the Developer Platform API. It supports
24
+ CI deployments and project administration, including hosted application access.
25
+ Use `devplat --help` and `devplat access --help` to inspect commands.
20
26
 
21
27
  Install an editable development copy:
22
28
 
@@ -37,4 +43,7 @@ devplat deploy apply --project hello --file examples/project.json --wait
37
43
 
38
44
  `PLATFORM_ACCESS_TOKEN` may be used instead of the deployment-credential variables
39
45
  for a short-lived, externally obtained token. The CLI never persists either form of
40
- authentication material.
46
+ authentication material. Deployment credentials authorize deployment and observation
47
+ only; access administration requires a human project-administrator login or an
48
+ externally supplied administrator token. See the [CLI guide](../../docs/developers/cli.md)
49
+ for profiles, login, access commands, and versioned updates.
@@ -0,0 +1,15 @@
1
+ platform_cli/__init__.py,sha256=3pnCImon2ZJc0V_dh8ESALZOalenXMwbD0ftP4lo2cM,69
2
+ platform_cli/__main__.py,sha256=3zCs59mHyp4lx_xTf51HuRNkHRAOoxTSIZ1AOB_WK7E,17876
3
+ platform_cli/api_contract.json,sha256=NUkTwF3MbFnfwInAFfu2LN3FLg67lLWgt-gAOFkpA30,148032
4
+ platform_cli/authentication.py,sha256=zMXky1tj2zi5WddkUtwZC0UE32BDGcAtY1VqlH40D8M,7071
5
+ platform_cli/client.py,sha256=c6fiK6KcAjpdS-Zorv_a4vLFRUiDM3R-8u6askEEkDM,10484
6
+ platform_cli/commands.py,sha256=QZYJx6cKkREe5KZSWj27y4S7fzMTypkdjgAn6r-466o,22934
7
+ platform_cli/config.py,sha256=5bnFRT4Z_qgQ6WWa4mODvidUuqzwsxwCKj1mMOhJOYA,3776
8
+ platform_cli/errors.py,sha256=jc8COhzP0KKYu93w9ZaVMLfXy5FT5bfSUvuKeOrhcZM,1188
9
+ platform_cli/models.py,sha256=DeUjuS0ma8dXPDHch8xnj0dQrtvq7PvOe_Bu4EIukUQ,1756
10
+ platform_cli/profiles.py,sha256=KMaiKFxf3NTc0bfSDa4E5kNs_Mby4BuXtBc9VG_G1Nc,6263
11
+ platform_cli/registry.py,sha256=jT6OK5s1_HM0VYoVGw8sgvZq9IkZG3ap9RQQcOnfkss,11464
12
+ developer_platform_cli-0.2.0.dist-info/METADATA,sha256=GpwyKeDsrpVkRmt9rjNTHB7_uayfkny3j1fGK07UxxU,2045
13
+ developer_platform_cli-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
14
+ developer_platform_cli-0.2.0.dist-info/entry_points.txt,sha256=M7MpiSzj86vx01JPP3zjnrykkQuxJjTnS9o5Rs0CAkI,55
15
+ developer_platform_cli-0.2.0.dist-info/RECORD,,
platform_cli/__main__.py CHANGED
@@ -3,6 +3,8 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  import json
6
+ from dataclasses import asdict, dataclass
7
+ import os
6
8
  from pathlib import Path
7
9
  import sys
8
10
  import time
@@ -10,19 +12,71 @@ from typing import Annotated
10
12
 
11
13
  import typer
12
14
 
13
- from .client import OperationFailed, OperationTimeout, PlatformClient, wait_for_operation
15
+ from .client import PlatformClient, wait_for_operation
14
16
  from .config import ConfigurationError, authentication_source, runtime_config
15
17
  from .errors import ApiError
16
18
  from .models import OperationStatus, application_body
19
+ from .commands import context_state as _state, emit, fail, register, watch_access
20
+ from .profiles import Profile, ProfileStore, SessionStore
21
+ from .registry import COMMANDS
17
22
 
18
23
 
19
24
  app = typer.Typer(no_args_is_help=True, add_completion=False, help="Developer Platform command-line client.")
20
25
  deploy_app = typer.Typer(no_args_is_help=True, help="Deploy versioned application specifications.")
21
- auth_app = typer.Typer(no_args_is_help=True, help="Inspect the active non-persistent authentication source.")
26
+ auth_app = typer.Typer(no_args_is_help=True, help="Inspect, create, or clear human login sessions.")
22
27
  app.add_typer(deploy_app, name="deploy")
23
28
  app.add_typer(auth_app, name="auth")
24
29
 
25
30
 
31
+ def _version_callback(value: bool):
32
+ if value:
33
+ from importlib.metadata import version
34
+ typer.echo(version("developer-platform-cli"))
35
+ raise typer.Exit()
36
+
37
+
38
+ @dataclass(frozen=True)
39
+ class Settings:
40
+ profile: str | None = None
41
+ api_url: str | None = None
42
+ output: str | None = None
43
+ insecure: bool = False
44
+ quiet: bool = False
45
+ debug: bool = False
46
+
47
+
48
+ @app.callback()
49
+ def root(ctx: typer.Context,
50
+ version: Annotated[bool, typer.Option("--version", callback=_version_callback, is_eager=True,
51
+ help="Show the installed CLI version.")] = False,
52
+ profile: Annotated[str | None, typer.Option("--profile")] = None,
53
+ api_url: Annotated[str | None, typer.Option("--api-url")] = None,
54
+ output: Annotated[str | None, typer.Option("--output")] = None,
55
+ no_color: Annotated[bool, typer.Option("--no-color")] = False,
56
+ quiet: Annotated[bool, typer.Option("--quiet")] = False,
57
+ debug: Annotated[bool, typer.Option("--debug")] = False,
58
+ insecure: Annotated[bool, typer.Option("--insecure")] = False):
59
+ if output and output not in {"table", "plain", "json"}:
60
+ raise typer.BadParameter("Use table, plain, or json.", param_hint="--output")
61
+ if no_color:
62
+ import os
63
+ os.environ["NO_COLOR"] = "1"
64
+ if insecure:
65
+ typer.echo("TLS verification disabled for this invocation.", err=True)
66
+ ctx.obj = Settings(profile, api_url, output, insecure, quiet, debug)
67
+
68
+
69
+ def _effective_output(ctx: typer.Context, output: str | None) -> str:
70
+ if output or _state(ctx).output:
71
+ return output or _state(ctx).output
72
+ if not _state(ctx).profile and os.environ.get("PLATFORM_API_URL") and any(
73
+ os.environ.get(key) for key in ("PLATFORM_ACCESS_TOKEN", "PLATFORM_TOKEN_ENDPOINT",
74
+ "PLATFORM_CLIENT_ID", "PLATFORM_CLIENT_SECRET")):
75
+ return "table"
76
+ _, selected = ProfileStore().selected(_state(ctx).profile)
77
+ return selected.output if selected else "table"
78
+
79
+
26
80
  def _read_json(path: str) -> dict[str, object]:
27
81
  try:
28
82
  contents = sys.stdin.read() if path == "-" else Path(path).read_text(encoding="utf-8")
@@ -41,56 +95,47 @@ def _emit(value: object, output: str) -> None:
41
95
  typer.echo(str(value))
42
96
 
43
97
 
44
- def _failure(error: Exception, output: str) -> typer.Exit:
45
- if isinstance(error, ApiError):
46
- payload = {"status": error.status_code, "detail": error.detail, "code": error.code, "request_id": error.request_id}
47
- if output == "json":
48
- typer.echo(json.dumps(payload, separators=(",", ":")), err=True)
49
- else:
50
- typer.echo(error.detail, err=True)
51
- return typer.Exit(error.exit_code)
52
- if isinstance(error, ConfigurationError):
53
- typer.echo(str(error), err=True)
54
- return typer.Exit(2)
55
- if isinstance(error, OperationFailed):
56
- typer.echo(f"Operation {error.status.operation_id} failed: {error}", err=True)
57
- return typer.Exit(9)
58
- if isinstance(error, OperationTimeout):
59
- typer.echo(f"{error} Resume with devplat operations watch {error.operation_id} when available.", err=True)
60
- return typer.Exit(10)
61
- typer.echo(str(error), err=True)
62
- return typer.Exit(8)
63
-
64
-
65
98
  @auth_app.command("status")
66
99
  def auth_status(
67
- output: Annotated[str, typer.Option("--output", case_sensitive=False)] = "table",
100
+ ctx: typer.Context,
101
+ output: Annotated[str | None, typer.Option("--output", case_sensitive=False)] = None,
68
102
  ) -> None:
69
103
  """Show the active authentication source without disclosing credentials."""
70
104
  try:
71
- source = authentication_source(runtime_config())
72
- _emit({"source": source, "persistent": False}, output)
105
+ config = runtime_config(profile_name=_state(ctx).profile, api_url_override=_state(ctx).api_url,
106
+ insecure=_state(ctx).insecure)
107
+ source = authentication_source(config)
108
+ result = {"source": source, "persistent": False}
109
+ if source == "human-profile-session":
110
+ session = SessionStore(config.profile_name, config.profile).get()
111
+ result = {"source": source, "persistent": bool(session), "profile": config.profile_name,
112
+ "subject": session["subject"] if session else None}
113
+ _emit(result, _effective_output(ctx, output))
73
114
  except Exception as error:
74
- raise _failure(error, output) from None
115
+ raise fail(error, output or _state(ctx).output or "table") from None
75
116
 
76
117
 
77
118
  @deploy_app.command("apply")
78
119
  def deploy_apply(
120
+ ctx: typer.Context,
79
121
  project: Annotated[str, typer.Option("--project", min=1, help="Target project name.")],
80
122
  file: Annotated[str, typer.Option("--file", help="JSON specification file, or - for stdin.")],
81
123
  wait: Annotated[bool, typer.Option("--wait", help="Wait for durable operation success and readiness.")] = False,
82
124
  timeout: Annotated[float, typer.Option("--timeout", min=1.0, help="Maximum wait time in seconds.")] = 300.0,
83
125
  poll_interval: Annotated[float, typer.Option("--poll-interval", min=0.1, help="Operation poll interval in seconds.")] = 2.0,
84
126
  if_match: Annotated[str | None, typer.Option("--if-match", help="Expected current revision.")] = None,
85
- output: Annotated[str, typer.Option("--output", case_sensitive=False)] = "table",
127
+ output: Annotated[str | None, typer.Option("--output", case_sensitive=False)] = None,
86
128
  ) -> None:
87
129
  """Apply one JSON application specification using environment authentication."""
130
+ output = _effective_output(ctx, output)
88
131
  if output not in {"table", "json", "plain"}:
89
132
  raise typer.BadParameter("must be table, json, or plain", param_hint="--output")
90
133
  try:
91
134
  body = _read_json(file)
92
- config = runtime_config()
135
+ config = runtime_config(profile_name=_state(ctx).profile, api_url_override=_state(ctx).api_url,
136
+ insecure=_state(ctx).insecure)
93
137
  client = PlatformClient(config)
138
+ client.debug = _state(ctx).debug
94
139
  try:
95
140
  token = client.access_token()
96
141
  accepted = client.deploy(project, body, token, if_match)
@@ -117,7 +162,241 @@ def deploy_apply(
117
162
  typer.echo("Waiting interrupted; the durable platform operation continues.", err=True)
118
163
  raise typer.Exit(10) from None
119
164
  except Exception as error:
120
- raise _failure(error, output) from None
165
+ raise fail(error, output) from None
166
+
167
+
168
+ profiles_app = typer.Typer(no_args_is_help=True, help="Named non-secret connection profiles.")
169
+ app.add_typer(profiles_app, name="profiles")
170
+
171
+
172
+ @profiles_app.command("create")
173
+ def profile_create(name: str, api_url: Annotated[str, typer.Option("--api-url")],
174
+ issuer: Annotated[str, typer.Option("--issuer")],
175
+ client_id: Annotated[str, typer.Option("--client-id")] = "platform-cli",
176
+ ca_bundle: Annotated[str | None, typer.Option("--ca-bundle")] = None,
177
+ project: Annotated[str | None, typer.Option("--project")] = None,
178
+ output: Annotated[str, typer.Option("--output")] = "table"):
179
+ """Save only API and OIDC connection settings."""
180
+ try:
181
+ store = ProfileStore()
182
+ store.create(name, Profile(api_url, issuer, client_id, ca_bundle, project, output))
183
+ emit({"profile": name, "active": store.read().get("active") == name}, output)
184
+ except Exception as error:
185
+ raise fail(error, output) from None
186
+
187
+
188
+ @profiles_app.command("show")
189
+ def profile_show(ctx: typer.Context, name: str | None = None,
190
+ output: Annotated[str | None, typer.Option("--output")] = None):
191
+ """Display a profile without credentials."""
192
+ try:
193
+ selected, profile = ProfileStore().selected(name or _state(ctx).profile)
194
+ if profile is None:
195
+ raise ConfigurationError("No profile selected.")
196
+ emit({"name": selected, **asdict(profile)}, _effective_output(ctx, output))
197
+ except Exception as error:
198
+ raise fail(error, output or _state(ctx).output or "table") from None
199
+
200
+
201
+ @profiles_app.command("use")
202
+ def profile_use(name: str):
203
+ """Select the default profile."""
204
+ try:
205
+ ProfileStore().use(name)
206
+ emit({"active": name}, "table")
207
+ except Exception as error:
208
+ raise fail(error) from None
209
+
210
+
211
+ @profiles_app.command("delete")
212
+ def profile_delete(name: str):
213
+ """Remove a profile and its bound keyring session."""
214
+ try:
215
+ _, profile = ProfileStore().selected(name)
216
+ SessionStore(name, profile).delete()
217
+ ProfileStore().delete(name)
218
+ emit({"deleted": name}, "table")
219
+ except Exception as error:
220
+ raise fail(error) from None
221
+
222
+
223
+ @auth_app.command("login")
224
+ def auth_login(ctx: typer.Context,
225
+ timeout: Annotated[float, typer.Option("--timeout", min=1)] = 300,
226
+ open_browser: Annotated[bool, typer.Option("--open-browser")] = False,
227
+ output: Annotated[str | None, typer.Option("--output")] = None):
228
+ """Sign in with OIDC Device Authorization and PKCE."""
229
+ selected_output = _effective_output(ctx, output)
230
+ try:
231
+ client = PlatformClient(runtime_config(profile_name=_state(ctx).profile,
232
+ api_url_override=_state(ctx).api_url, insecure=_state(ctx).insecure))
233
+ try:
234
+ def notify(uri: str, code: str):
235
+ typer.echo("Open " + uri + " and enter code " + code, err=True)
236
+ if open_browser:
237
+ import webbrowser
238
+ webbrowser.open(uri)
239
+ subject = client.human_authentication().login(notify, timeout=timeout)
240
+ emit({"profile": client.config.profile_name, "subject": subject}, selected_output)
241
+ finally:
242
+ client.close()
243
+ except KeyboardInterrupt:
244
+ raise typer.Exit(10) from None
245
+ except Exception as error:
246
+ raise fail(error, selected_output) from None
247
+
248
+
249
+ @auth_app.command("logout")
250
+ def auth_logout(ctx: typer.Context,
251
+ output: Annotated[str | None, typer.Option("--output")] = None):
252
+ """Clear the human session and request provider revocation."""
253
+ selected_output = _effective_output(ctx, output)
254
+ try:
255
+ client = PlatformClient(runtime_config(profile_name=_state(ctx).profile,
256
+ api_url_override=_state(ctx).api_url, insecure=_state(ctx).insecure))
257
+ try:
258
+ client.human_authentication().logout()
259
+ emit({"profile": client.config.profile_name, "logged_out": True}, selected_output)
260
+ finally:
261
+ client.close()
262
+ except Exception as error:
263
+ raise fail(error, selected_output) from None
264
+
265
+
266
+ def _tree(parent: typer.Typer, names: tuple[str, ...]) -> typer.Typer:
267
+ for name in names:
268
+ children = getattr(parent, "_devplat_children", None)
269
+ if children is None:
270
+ children = {}
271
+ setattr(parent, "_devplat_children", children)
272
+ if name not in children:
273
+ child = typer.Typer(no_args_is_help=True, help=name.replace("-", " ").capitalize() + " commands.")
274
+ parent.add_typer(child, name=name)
275
+ children[name] = child
276
+ parent = children[name]
277
+ return parent
278
+
279
+
280
+ for specification in COMMANDS:
281
+ if specification.command == "deploy apply":
282
+ continue
283
+ if specification.command == "logs":
284
+ register(_tree(app, ("logs",)), specification)
285
+ continue
286
+ parts = specification.command.split()
287
+ register(_tree(app, tuple(parts[:-1])), specification)
288
+
289
+
290
+ def _client(ctx: typer.Context) -> PlatformClient:
291
+ client = PlatformClient(runtime_config(profile_name=_state(ctx).profile,
292
+ api_url_override=_state(ctx).api_url, insecure=_state(ctx).insecure))
293
+ client.debug = _state(ctx).debug
294
+ return client
295
+
296
+
297
+ @app.command("status")
298
+ def status(ctx: typer.Context, project: Annotated[str | None, typer.Option("--project")] = None,
299
+ output: Annotated[str | None, typer.Option("--output")] = None):
300
+ """Inspect project metadata and component state."""
301
+ selected_output = _effective_output(ctx, output)
302
+ try:
303
+ client = _client(ctx)
304
+ try:
305
+ project = project or (client.config.profile.project if client.config.profile else None)
306
+ if not project:
307
+ raise ConfigurationError("Supply --project or select a profile with a default project.")
308
+ projects, _ = client.request_json("GET", "/projects")
309
+ row = next((item for item in projects if item.get("name") == project), None)
310
+ if row is None:
311
+ raise ApiError(404, "Project not found in authorized project list.")
312
+ components, _ = client.request_json("GET", "/projects/" + project + "/components")
313
+ emit({"project": row, "components": components}, selected_output)
314
+ finally:
315
+ client.close()
316
+ except Exception as error:
317
+ raise fail(error, selected_output) from None
318
+
319
+
320
+ @_tree(app, ("projects",)).command("show")
321
+ def projects_show(ctx: typer.Context, project: Annotated[str | None, typer.Option("--project")] = None,
322
+ output: Annotated[str | None, typer.Option("--output")] = None):
323
+ """Show an authorized project list entry."""
324
+ selected_output = _effective_output(ctx, output)
325
+ try:
326
+ client = _client(ctx)
327
+ try:
328
+ project = project or (client.config.profile.project if client.config.profile else None)
329
+ if not project:
330
+ raise ConfigurationError("Supply --project or select a profile with a default project.")
331
+ rows, _ = client.request_json("GET", "/projects")
332
+ row = next((item for item in rows if item.get("name") == project), None)
333
+ if row is None:
334
+ raise ApiError(404, "Project not found in authorized project list.")
335
+ emit(row, selected_output)
336
+ finally:
337
+ client.close()
338
+ except Exception as error:
339
+ raise fail(error, selected_output) from None
340
+
341
+
342
+ @_tree(app, ("operations",)).command("watch")
343
+ def operations_watch(ctx: typer.Context, operation_id: str,
344
+ timeout: Annotated[float, typer.Option("--timeout", min=1)] = 300,
345
+ poll_interval: Annotated[float, typer.Option("--poll-interval", min=0.1)] = 2,
346
+ output: Annotated[str | None, typer.Option("--output")] = None):
347
+ """Resume bounded deployment operation watching."""
348
+ selected_output = _effective_output(ctx, output)
349
+ try:
350
+ client = _client(ctx)
351
+ try:
352
+ token = client.access_token()
353
+ path = "/v1/operations/" + operation_id
354
+ first = client.operation(path, token)
355
+ accepted = OperationAccepted(operation_id=first.operation_id, state=first.state,
356
+ revision=first.revision, status_url=path)
357
+ result = wait_for_operation(client, accepted, token, timeout, poll_interval,
358
+ time.monotonic, time.sleep, lambda _: None)
359
+ emit(result.model_dump(), selected_output)
360
+ finally:
361
+ client.close()
362
+ except Exception as error:
363
+ raise fail(error, selected_output) from None
364
+
365
+
366
+ @_tree(app, ("access", "operations")).command("watch")
367
+ def access_operations_watch(ctx: typer.Context, operation_id: str,
368
+ timeout: Annotated[float, typer.Option("--timeout", min=1)] = 300,
369
+ poll_interval: Annotated[float, typer.Option("--poll-interval", min=0.1)] = 2,
370
+ output: Annotated[str | None, typer.Option("--output")] = None):
371
+ """Resume hosted access operation watching."""
372
+ selected_output = _effective_output(ctx, output)
373
+ try:
374
+ client = _client(ctx)
375
+ try:
376
+ emit(watch_access(client, operation_id, timeout, poll_interval,
377
+ lambda _: None), selected_output)
378
+ finally:
379
+ client.close()
380
+ except Exception as error:
381
+ raise fail(error, selected_output) from None
382
+
383
+
384
+ @_tree(app, ("contract",)).command("check")
385
+ def contract_check(ctx: typer.Context,
386
+ output: Annotated[str | None, typer.Option("--output")] = None):
387
+ """Report registry coverage of the packaged public API contract."""
388
+ selected_output = _effective_output(ctx, output)
389
+ from importlib.resources import files
390
+ from .registry import EXCLUSIONS
391
+ contract = json.loads(files("platform_cli").joinpath("api_contract.json").read_text())
392
+ expected = {(method.upper(), path) for path, methods in contract["paths"].items()
393
+ for method in methods if method.upper() in {"GET", "POST", "PUT", "PATCH", "DELETE"}}
394
+ actual = {(spec.method, spec.path) for spec in COMMANDS}
395
+ missing = sorted(expected - actual - EXCLUSIONS.keys())
396
+ extra = sorted(actual - expected)
397
+ emit({"covered": len(actual), "excluded": len(EXCLUSIONS), "missing": missing, "extra": extra}, selected_output)
398
+ if missing or extra:
399
+ raise typer.Exit(7)
121
400
 
122
401
 
123
402
  def main() -> None: