sinapsis_cli 1.0.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.
Files changed (46) hide show
  1. sinapsis_cli/__init__.py +13 -0
  2. sinapsis_cli/commands/__init__.py +0 -0
  3. sinapsis_cli/commands/cloud/__init__.py +0 -0
  4. sinapsis_cli/commands/cloud/_agent_selection.py +112 -0
  5. sinapsis_cli/commands/cloud/_secrets_render.py +15 -0
  6. sinapsis_cli/commands/cloud/_webhook_render.py +19 -0
  7. sinapsis_cli/commands/cloud/agents.py +137 -0
  8. sinapsis_cli/commands/cloud/api_keys.py +155 -0
  9. sinapsis_cli/commands/cloud/files.py +135 -0
  10. sinapsis_cli/commands/cloud/jobs.py +532 -0
  11. sinapsis_cli/commands/cloud/packages.py +164 -0
  12. sinapsis_cli/commands/cloud/schedules.py +392 -0
  13. sinapsis_cli/commands/cloud/secrets.py +96 -0
  14. sinapsis_cli/commands/cloud/templates.py +95 -0
  15. sinapsis_cli/commands/cloud/webhooks.py +156 -0
  16. sinapsis_cli/commands/common/__init__.py +0 -0
  17. sinapsis_cli/commands/common/auth.py +219 -0
  18. sinapsis_cli/commands/common/profiles.py +156 -0
  19. sinapsis_cli/commands/common/telemetry.py +150 -0
  20. sinapsis_cli/commands/local_api/__init__.py +0 -0
  21. sinapsis_cli/commands/local_api/jobs.py +284 -0
  22. sinapsis_cli/commands/local_venv/__init__.py +0 -0
  23. sinapsis_cli/commands/local_venv/_templates_render.py +56 -0
  24. sinapsis_cli/commands/local_venv/jobs.py +76 -0
  25. sinapsis_cli/commands/local_venv/templates.py +47 -0
  26. sinapsis_cli/composition.py +215 -0
  27. sinapsis_cli/config.py +446 -0
  28. sinapsis_cli/execution.py +77 -0
  29. sinapsis_cli/main.py +185 -0
  30. sinapsis_cli/main_multi.py +152 -0
  31. sinapsis_cli/shared/__init__.py +3 -0
  32. sinapsis_cli/shared/jobs.py +134 -0
  33. sinapsis_cli/shared/terminal.py +8 -0
  34. sinapsis_cli/shared/writer.py +427 -0
  35. sinapsis_cli/state.py +310 -0
  36. sinapsis_cli/telemetry/__init__.py +7 -0
  37. sinapsis_cli/telemetry/collector.py +84 -0
  38. sinapsis_cli/telemetry/core.py +331 -0
  39. sinapsis_cli/telemetry/scheduler.py +234 -0
  40. sinapsis_cli/telemetry/transport.py +150 -0
  41. sinapsis_cli-1.0.0.dist-info/METADATA +386 -0
  42. sinapsis_cli-1.0.0.dist-info/RECORD +46 -0
  43. sinapsis_cli-1.0.0.dist-info/WHEEL +4 -0
  44. sinapsis_cli-1.0.0.dist-info/entry_points.txt +5 -0
  45. sinapsis_cli-1.0.0.dist-info/licenses/LICENSE-APACHE +202 -0
  46. sinapsis_cli-1.0.0.dist-info/licenses/LICENSE-MIT +21 -0
@@ -0,0 +1,532 @@
1
+ """Cloud API job backend for the Sinapsis CLI."""
2
+
3
+ import asyncio
4
+ from pathlib import Path
5
+
6
+ import typer
7
+ from sinapsis.agent import load_yaml_config
8
+ from sinapsis.sentinels import SinapsisSentinel
9
+ from sinapsis_contracts.common.sentinels import SINAPSIS_AGENT_FINISHED, SINAPSIS_END_OF_STREAM
10
+ from sinapsis_deserialization.schemas import SSEMessage
11
+ from sinapsis_sdk.cloud_api.models import JobResult, JobStatus
12
+ from sinapsis_sdk.common.exceptions import APIError, NotFoundError
13
+
14
+ from sinapsis_cli.execution import ExecutionContext, build_api_config, create_api_client
15
+ from sinapsis_cli.shared.jobs import register_history_commands, require_job_target, resolve_job_id
16
+ from sinapsis_cli.shared.terminal import divider
17
+ from sinapsis_cli.shared.writer import ResultWriter
18
+ from sinapsis_cli.state import record_job
19
+
20
+ from .files import _get_staging_file
21
+
22
+
23
+ def create_app(execution: ExecutionContext) -> typer.Typer:
24
+ """Create the cloud jobs command tree.
25
+
26
+ Args:
27
+ execution: Resolved execution context for the current invocation.
28
+
29
+ Returns:
30
+ Typer application containing cloud job commands.
31
+ """
32
+ app = typer.Typer(name="jobs", help="Manage Sinapsis Cloud jobs.", no_args_is_help=True)
33
+
34
+ @app.command()
35
+ def run(
36
+ agent_definition: Path = typer.Argument(
37
+ ...,
38
+ exists=True,
39
+ file_okay=True,
40
+ dir_okay=False,
41
+ readable=True,
42
+ help="Path to the agent definition.",
43
+ ),
44
+ wait: bool = typer.Option(False, "--wait", help="Wait for the job to finish and retrieve its result."),
45
+ result: bool = typer.Option(False, "--result", help="Retrieve the result after submission."),
46
+ stream: bool = typer.Option(False, "--stream", help="Stream results until the job finishes."),
47
+ refresh: bool = typer.Option(
48
+ False,
49
+ "--refresh",
50
+ help="Refresh the result from the API instead of using a local result.",
51
+ ),
52
+ save_dir: Path = typer.Option(
53
+ Path("results"),
54
+ "--save-dir",
55
+ "-o",
56
+ help="Directory where results and artifacts are saved.",
57
+ ),
58
+ print_only: bool = typer.Option(False, "--print-only", help="Print results instead of saving artifacts."),
59
+ ) -> None:
60
+ """Submit an agent as a cloud job."""
61
+ selected = sum(bool(value) for value in (wait, result, stream))
62
+
63
+ if selected > 1:
64
+ typer.echo("Options --wait, --result, and --stream are mutually exclusive.", err=True)
65
+ raise typer.Exit(code=1)
66
+
67
+ if refresh and not result:
68
+ typer.echo("--refresh can only be used with --result.", err=True)
69
+ raise typer.Exit(code=1)
70
+
71
+ asyncio.run(
72
+ run_cloud_job(
73
+ execution,
74
+ agent_definition,
75
+ wait=wait,
76
+ result=result,
77
+ stream=stream,
78
+ refresh=refresh,
79
+ save_dir=save_dir,
80
+ print_only=print_only,
81
+ )
82
+ )
83
+
84
+ @app.command()
85
+ def status(
86
+ job_id: str | None = typer.Argument(None, help="ID of the job. Defaults to this profile's most recent job."),
87
+ verbose: bool = typer.Option(False, "--verbose", "-v", help="Include the full agent definition."),
88
+ ) -> None:
89
+ """Show the current status of a cloud job."""
90
+ resolved_job_id = resolve_job_id(job_id, profile_name=execution.profile_name)
91
+ asyncio.run(get_cloud_status(execution, resolved_job_id, verbose=verbose))
92
+
93
+ @app.command("result")
94
+ def result_command(
95
+ job_id: str | None = typer.Argument(None, help="ID of the job. Defaults to this profile's most recent job."),
96
+ refresh: bool = typer.Option(False, "--refresh", help="Always retrieve the result from the API."),
97
+ save_dir: Path = typer.Option(
98
+ Path("results"),
99
+ "--save-dir",
100
+ "-o",
101
+ help="Directory where results and artifacts are saved.",
102
+ ),
103
+ print_only: bool = typer.Option(False, "--print-only", help="Print results instead of saving artifacts."),
104
+ ) -> None:
105
+ """Retrieve a cloud job result."""
106
+ resolved_job_id = resolve_job_id(job_id, profile_name=execution.profile_name)
107
+ asyncio.run(
108
+ get_cloud_result(
109
+ execution,
110
+ resolved_job_id,
111
+ refresh=refresh,
112
+ save_dir=save_dir,
113
+ print_only=print_only,
114
+ )
115
+ )
116
+
117
+ @app.command("stream")
118
+ def stream_command(
119
+ job_id: str | None = typer.Argument(None, help="ID of the job. Defaults to this profile's most recent job."),
120
+ save_dir: Path = typer.Option(
121
+ Path("results"),
122
+ "--save-dir",
123
+ "-o",
124
+ help="Directory where streamed results and artifacts are saved.",
125
+ ),
126
+ print_only: bool = typer.Option(
127
+ False, "--print-only", help="Print streamed results instead of saving artifacts."
128
+ ),
129
+ ) -> None:
130
+ """Stream results from a running cloud job."""
131
+ resolved_job_id = resolve_job_id(job_id, profile_name=execution.profile_name)
132
+ asyncio.run(stream_cloud_job(execution, resolved_job_id, save_dir=save_dir, print_only=print_only))
133
+
134
+ @app.command()
135
+ def cancel(
136
+ job_id: str | None = typer.Argument(None, help="ID of the job. Defaults to this profile's most recent job."),
137
+ ) -> None:
138
+ """Cancel a running cloud job."""
139
+ resolved_job_id = resolve_job_id(job_id, profile_name=execution.profile_name)
140
+ asyncio.run(cancel_cloud_job(execution, resolved_job_id))
141
+
142
+ from sinapsis_cli.commands.cloud.schedules import create_app as create_schedules_app
143
+
144
+ app.add_typer(create_schedules_app(execution), name="schedule")
145
+ register_history_commands(app, execution)
146
+ return app
147
+
148
+
149
+ def _get_api_config(execution: ExecutionContext, *, job_id: str | None = None):
150
+ """Build SDK API configuration for the selected profile or recorded job."""
151
+ api_url = execution.api_url
152
+
153
+ if job_id is not None:
154
+ api_url = require_job_target(job_id, profile_name=execution.profile_name, default_target=execution.api_url)
155
+
156
+ return build_api_config(execution, api_url=api_url)
157
+
158
+
159
+ async def run_cloud_job(
160
+ execution: ExecutionContext,
161
+ agent_definition: Path,
162
+ *,
163
+ wait: bool,
164
+ result: bool,
165
+ stream: bool,
166
+ refresh: bool,
167
+ save_dir: Path,
168
+ print_only: bool,
169
+ ) -> None:
170
+ """Submit and optionally follow a cloud API job."""
171
+ config = _get_api_config(execution)
172
+
173
+ async with create_api_client(execution, api_url=config.api_url) as client:
174
+ definition = load_yaml_config(agent_definition)
175
+ submission = await client.jobs.submit(definition)
176
+ job_id = submission.job_id
177
+
178
+ record_job(
179
+ job_id,
180
+ source=agent_definition,
181
+ target=config.api_url,
182
+ profile=execution.profile_name,
183
+ backend=execution.profile.backend.value,
184
+ )
185
+
186
+ typer.echo(f"Job ID: {job_id}")
187
+
188
+ if stream:
189
+ await _stream_cloud_job(execution, job_id, api_url=config.api_url, save_dir=save_dir, print_only=print_only)
190
+ return
191
+
192
+ if wait:
193
+ await _wait_for_cloud_job(execution, job_id, api_url=config.api_url, save_dir=save_dir, print_only=print_only)
194
+ return
195
+
196
+ if result:
197
+ await _get_cloud_result(
198
+ execution,
199
+ job_id,
200
+ api_url=config.api_url,
201
+ refresh=refresh,
202
+ save_dir=save_dir,
203
+ print_only=print_only,
204
+ )
205
+
206
+
207
+ async def _wait_for_cloud_job(
208
+ execution: ExecutionContext, job_id: str, *, api_url: str, save_dir: Path, print_only: bool
209
+ ) -> None:
210
+ """Poll a cloud job until completion and retrieve its result."""
211
+ typer.echo("Waiting for job to finish...")
212
+
213
+ async with create_api_client(execution, api_url=api_url) as client:
214
+ while True:
215
+ status = await client.jobs.get_status(job_id)
216
+ _print_status(status)
217
+
218
+ if _is_done(status):
219
+ break
220
+
221
+ await asyncio.sleep(1.0)
222
+
223
+ if getattr(status, "error", None):
224
+ return
225
+
226
+ await _get_cloud_result(execution, job_id, api_url=api_url, refresh=True, save_dir=save_dir, print_only=print_only)
227
+
228
+
229
+ def _archival_fallback_error(exc: Exception) -> bool:
230
+ """Only missing/expired Redis results trigger archive recovery."""
231
+ return isinstance(exc, NotFoundError) or (
232
+ isinstance(exc, APIError) and exc.status_code == 503 and "Job state unavailable" in str(exc)
233
+ )
234
+
235
+
236
+ async def _replay_archived_results(
237
+ client,
238
+ execution: ExecutionContext,
239
+ job_id: str,
240
+ *,
241
+ api_url: str,
242
+ save_dir: Path,
243
+ print_only: bool,
244
+ ) -> int:
245
+ """Replay archived stream frames as normal streaming output."""
246
+ count = 0
247
+ writer = None if print_only else ResultWriter(save_dir)
248
+
249
+ async for message in client.jobs.archived_stream_results(job_id):
250
+ if isinstance(message, SinapsisSentinel):
251
+ continue
252
+ if not count:
253
+ typer.echo("Replaying archived stream frames from the database.")
254
+ count += 1
255
+ if print_only:
256
+ _print_result(message)
257
+ else:
258
+ assert writer is not None
259
+ written = writer.write(message)
260
+ if written:
261
+ typer.echo(f"Saved {len(written)} file(s) to {save_dir}")
262
+ try:
263
+ await _fetch_content_files(execution, message, save_dir, api_url=api_url)
264
+ except NotFoundError:
265
+ typer.echo("Note: a staged file referenced by archived output has expired.", err=True)
266
+ return count
267
+
268
+
269
+ async def _get_cloud_result(
270
+ execution: ExecutionContext,
271
+ job_id: str,
272
+ *,
273
+ api_url: str,
274
+ refresh: bool,
275
+ save_dir: Path,
276
+ print_only: bool,
277
+ ) -> None:
278
+ """Get the Redis result or replay the last one/two archived output frames."""
279
+ del refresh
280
+ async with create_api_client(execution, api_url=api_url) as client:
281
+ try:
282
+ results = [await client.jobs.get_result(job_id)]
283
+ except (NotFoundError, APIError) as exc:
284
+ if not _archival_fallback_error(exc):
285
+ raise
286
+ results = await client.jobs.archived_recent_results(job_id)
287
+ if not results:
288
+ typer.echo(
289
+ f"No result frames are available for job {job_id} in Redis or the database archive.",
290
+ err=True,
291
+ )
292
+ raise typer.Exit(code=1) from exc
293
+ typer.echo(f"Recovered {len(results)} recent result frame(s) from the database archive.")
294
+
295
+ for message in results:
296
+ if isinstance(message, SinapsisSentinel):
297
+ continue
298
+ _handle_result(message, save_dir=save_dir, print_only=print_only)
299
+ await _fetch_content_files(execution, message, save_dir, api_url=api_url)
300
+
301
+
302
+ async def _stream_cloud_job(
303
+ execution: ExecutionContext, job_id: str, *, api_url: str, save_dir: Path, print_only: bool
304
+ ) -> None:
305
+ """Stream running jobs, or replay durable output for finished/expired jobs."""
306
+ writer = None if print_only else ResultWriter(save_dir)
307
+
308
+ async with create_api_client(execution, api_url=api_url) as client:
309
+ try:
310
+ job_status = await client.jobs.get_status(job_id)
311
+ except (NotFoundError, APIError) as exc:
312
+ if not _archival_fallback_error(exc):
313
+ raise
314
+ # A fully expired Redis job still has a separately authorized
315
+ # Management archive that can be replayed without Redis metadata.
316
+ job_status = None
317
+
318
+ if job_status is None or _is_done(job_status):
319
+ count = await _replay_archived_results(
320
+ client, execution, job_id, api_url=api_url, save_dir=save_dir, print_only=print_only
321
+ )
322
+ if count:
323
+ typer.echo(f"Replayed {count} archived stream frame(s).")
324
+ return
325
+ if job_status is not None and str(job_status.state).upper() == "COMPLETED":
326
+ # Archive can be empty while the final Redis frame remains.
327
+ try:
328
+ final = await client.jobs.get_result(job_id)
329
+ except (NotFoundError, APIError) as exc:
330
+ if not _archival_fallback_error(exc):
331
+ raise
332
+ else:
333
+ typer.echo("No archived stream frames; displaying the final Redis output frame.")
334
+ _handle_result(final, save_dir=save_dir, print_only=print_only)
335
+ await _fetch_content_files(execution, final, save_dir, api_url=api_url)
336
+ return
337
+ typer.echo(f"Job {job_id} is not streaming, and no archived stream output is available.")
338
+ return
339
+
340
+ try:
341
+ async for message in client.jobs.stream_results(job_id):
342
+ if isinstance(message, SinapsisSentinel):
343
+ if message in (SINAPSIS_AGENT_FINISHED, SINAPSIS_END_OF_STREAM):
344
+ if print_only:
345
+ typer.echo("Agent has finished.")
346
+ break
347
+ continue
348
+
349
+ if print_only:
350
+ _print_result(message)
351
+ else:
352
+ assert writer is not None
353
+ written = writer.write(message)
354
+ if written:
355
+ typer.echo(f"Saved {len(written)} file(s) to {save_dir}")
356
+
357
+ await _fetch_content_files(execution, message, save_dir, api_url=api_url)
358
+ except (NotFoundError, APIError) as exc:
359
+ if not _archival_fallback_error(exc) and not (isinstance(exc, APIError) and exc.status_code == 410):
360
+ raise
361
+ count = await _replay_archived_results(
362
+ client, execution, job_id, api_url=api_url, save_dir=save_dir, print_only=print_only
363
+ )
364
+ if not count:
365
+ raise
366
+ typer.echo(f"Replayed {count} archived stream frame(s).")
367
+
368
+
369
+ async def get_cloud_status(execution: ExecutionContext, job_id: str, *, verbose: bool) -> None:
370
+ """Show the current status of a cloud API job."""
371
+ config = _get_api_config(execution, job_id=job_id)
372
+
373
+ async with create_api_client(execution, api_url=config.api_url) as client:
374
+ job_status = await client.jobs.get_status(job_id, verbose=verbose)
375
+
376
+ _print_status(job_status)
377
+
378
+
379
+ async def get_cloud_result(
380
+ execution: ExecutionContext, job_id: str, *, refresh: bool, save_dir: Path, print_only: bool
381
+ ) -> None:
382
+ """Retrieve a cloud API job result."""
383
+ config = _get_api_config(execution, job_id=job_id)
384
+
385
+ await _get_cloud_result(
386
+ execution,
387
+ job_id,
388
+ api_url=config.api_url,
389
+ refresh=refresh,
390
+ save_dir=save_dir,
391
+ print_only=print_only,
392
+ )
393
+
394
+
395
+ async def stream_cloud_job(execution: ExecutionContext, job_id: str, *, save_dir: Path, print_only: bool) -> None:
396
+ """Stream results from a cloud API job."""
397
+ config = _get_api_config(execution, job_id=job_id)
398
+
399
+ await _stream_cloud_job(execution, job_id, api_url=config.api_url, save_dir=save_dir, print_only=print_only)
400
+
401
+
402
+ async def cancel_cloud_job(execution: ExecutionContext, job_id: str) -> None:
403
+ """Cancel a cloud API job."""
404
+ config = _get_api_config(execution, job_id=job_id)
405
+
406
+ async with create_api_client(execution, api_url=config.api_url) as client:
407
+ await client.jobs.cancel(job_id)
408
+
409
+ typer.echo(f"Cancelled job {job_id}.")
410
+
411
+
412
+ def _handle_result(result: JobResult, *, save_dir: Path, print_only: bool) -> None:
413
+ """Print or persist a cloud job result, never a control sentinel."""
414
+ if isinstance(result, SinapsisSentinel):
415
+ return
416
+ if print_only:
417
+ _print_result(result)
418
+ return
419
+
420
+ writer = ResultWriter(save_dir)
421
+ written = writer.write(result)
422
+
423
+ if not written:
424
+ typer.echo("Result contained no output data.")
425
+ return
426
+
427
+ typer.echo(f"Saved {len(written)} file(s) to {save_dir}")
428
+
429
+
430
+ def _is_done(status: JobStatus) -> bool:
431
+ """Return whether the authoritative job state is terminal.
432
+
433
+ Accept both string values and enum-valued states from older SDKs.
434
+ """
435
+ value = getattr(status.state, "value", status.state)
436
+ state = str(value).rsplit(".", 1)[-1].strip().lower()
437
+ return state in {"done", "completed", "complete", "failed", "error", "cancelled", "canceled"}
438
+
439
+
440
+ def _print_status(status: JobStatus) -> None:
441
+ """Print a cloud job status."""
442
+ typer.echo(f"Job ID: {status.job_id}")
443
+ typer.echo(f"State: {status.state}")
444
+ typer.echo(f"Agent: {status.agent_name or '-'}")
445
+ typer.echo(f"Updated: {status.updated_at or '-'}")
446
+ typer.echo(f"Heartbeat: {status.heartbeat or '-'}")
447
+ typer.echo(f"Result URL: {status.result_url or '-'}")
448
+ typer.echo(f"Error: {status.error or '-'}")
449
+
450
+ if status.agent_def is not None:
451
+ typer.echo()
452
+ typer.echo("Agent definition:")
453
+ typer.echo(status.agent_def)
454
+
455
+
456
+ def _print_result(result: SSEMessage) -> None:
457
+ """Print a human-readable representation of a cloud job result."""
458
+ if isinstance(result, SinapsisSentinel):
459
+ return
460
+ typer.echo(f"Agent: {result.agent_id}")
461
+ typer.echo(f"Status: {result.agent_status}")
462
+ typer.echo(f"Timestamp: {result.timestamp.isoformat()}")
463
+
464
+ if result.agent_error:
465
+ typer.echo(f"Error: {result.agent_error}")
466
+
467
+ for entry in result.template_data:
468
+ typer.echo()
469
+ typer.echo(f"Template: {entry.template_name}")
470
+ typer.echo(f"Status: {entry.status}")
471
+ typer.echo(f"Timestamp: {entry.timestamp.isoformat()}")
472
+
473
+ if entry.error:
474
+ typer.echo(f"Error: {entry.error}")
475
+
476
+ output = entry.output
477
+
478
+ if output is None:
479
+ continue
480
+
481
+ typer.echo()
482
+ typer.echo(f"Container: {output.container_id}")
483
+ typer.echo(f"Images: {len(output.images)}")
484
+ typer.echo(f"Audios: {len(output.audios)}")
485
+ typer.echo(f"Texts: {len(output.texts)}")
486
+ typer.echo(f"Conversations: {len(output.llm_conversations)}")
487
+ typer.echo(f"Files: {len(output.files)}")
488
+ typer.echo(f"Time series: {len(output.time_series)}")
489
+ typer.echo(f"Data frames: {len(output.data_frames)}")
490
+ typer.echo(f"Binary data: {len(output.binary_data)}")
491
+ typer.echo(f"Generic data: {len(output.generic_data)}")
492
+
493
+ divider(0)
494
+
495
+
496
+ async def _fetch_content_files(execution: ExecutionContext, sse_message, save_dir: Path, *, api_url: str) -> None:
497
+ """Fetch cloud-staged content referenced by an SSE message."""
498
+ if isinstance(sse_message, SinapsisSentinel):
499
+ return
500
+ for agent_response in sse_message.template_data:
501
+ for packet_name in {"images", "texts"}:
502
+ output = agent_response.output
503
+ if output is None:
504
+ continue
505
+
506
+ for data_packet in getattr(output, packet_name):
507
+ if not isinstance(data_packet.content, dict):
508
+ continue
509
+
510
+ file_path = data_packet.content.get("content", {}).get("original")
511
+
512
+ if file_path is None:
513
+ continue
514
+
515
+ file_path = file_path.split("/")[-1]
516
+
517
+ destination = (
518
+ Path(save_dir)
519
+ / agent_response.agent_id.replace("/", "_")
520
+ / agent_response.template_name
521
+ / file_path
522
+ )
523
+
524
+ agent_id = agent_response.agent_id.split("/")[-1]
525
+
526
+ await _get_staging_file(
527
+ agent_id,
528
+ file_path.strip("/"),
529
+ destination,
530
+ execution=execution,
531
+ api_url=api_url,
532
+ )
@@ -0,0 +1,164 @@
1
+ """Configure native uv authentication for Sinapsis-managed package indexes.
2
+
3
+ No package secrets are placed in Sinapsis profiles, pyproject.toml, command
4
+ arguments, or logs. Login validates the scoped token against Cloud first and
5
+ then passes it to uv via stdin using the OS-native credential storage preview.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import asyncio
11
+ import json
12
+ import os
13
+ import re
14
+ import subprocess
15
+ import urllib.error
16
+ import urllib.request
17
+ from urllib.parse import urlsplit
18
+
19
+ import typer
20
+
21
+ from sinapsis_contracts.cloud_api.paths import PACKAGE_PATHS
22
+
23
+
24
+ app = typer.Typer(name="packages", help="Sinapsis package-index authentication and setup.", no_args_is_help=True)
25
+
26
+ _HOSTS: dict[str, str] = {
27
+ "sinapsis-dependencies": "https://pypi.sinapsis.tech",
28
+ "sinapsis-community": "https://community.pypi.sinapsis.tech",
29
+ "sinapsis-internal": "https://internal.pypi.sinapsis.tech",
30
+ }
31
+
32
+
33
+ def _index_endpoint(registry: str) -> str:
34
+ """Resolve only allowlisted index destinations; prevent secret exfiltration."""
35
+ endpoint = _HOSTS.get(registry)
36
+ if endpoint is None:
37
+ raise typer.BadParameter("Unknown Sinapsis registry")
38
+ parsed = urlsplit(endpoint)
39
+ if parsed.scheme != "https" or not parsed.hostname or parsed.port not in (None, 443):
40
+ raise typer.BadParameter("Invalid configured package-index hostname")
41
+ return endpoint
42
+
43
+
44
+ def _verify_key(registry: str, key: str, cloud_url: str) -> None:
45
+ """Validate read scope and account status before passing a token to uv."""
46
+ parsed = urlsplit(cloud_url)
47
+ if (
48
+ parsed.scheme != "https"
49
+ or not parsed.hostname
50
+ or parsed.port not in (None, 443)
51
+ or parsed.username
52
+ or parsed.password
53
+ or parsed.query
54
+ or parsed.fragment
55
+ ):
56
+ raise typer.BadParameter("The Cloud API must use a credential-free HTTPS origin")
57
+ if not re.fullmatch(r"sk_[A-Za-z0-9_-]{8,192}", key):
58
+ raise typer.BadParameter("A scoped Sinapsis API key is required")
59
+ request = urllib.request.Request(
60
+ cloud_url.rstrip("/") + PACKAGE_PATHS.index_list,
61
+ data=json.dumps({"registry": registry}).encode(),
62
+ headers={"Authorization": "Bearer " + key, "Content-Type": "application/json"},
63
+ method="POST",
64
+ )
65
+ try:
66
+ with urllib.request.urlopen(request, timeout=8) as response:
67
+ if response.status != 200:
68
+ raise typer.BadParameter("The key was not authorized for package reads")
69
+ except urllib.error.HTTPError as error:
70
+ raise typer.BadParameter(f"Package read permission was denied (HTTP {error.code})") from None
71
+ except (OSError, urllib.error.URLError):
72
+ raise typer.BadParameter("The Sinapsis Cloud API is unavailable") from None
73
+
74
+
75
+ async def _issue_read_key(ctx: typer.Context, registry: str) -> str:
76
+ """Use the existing Cloud session to provision a narrowly scoped index key."""
77
+ from sinapsis_cli.execution import create_api_client, get_execution_context
78
+
79
+ try:
80
+ async with create_api_client(get_execution_context(ctx)) as client:
81
+ response = await client.api_keys.generate(
82
+ f"uv:{registry}",
83
+ scopes=["packages:read"],
84
+ agent_ids=[],
85
+ all_user_agents=False,
86
+ )
87
+ except Exception as error:
88
+ # SDK exceptions can include request context; do not display them.
89
+ raise typer.BadParameter("Unable to issue package key; run sinx-cloud configure first") from None
90
+ return response.api_key
91
+
92
+
93
+ @app.command("login")
94
+ def login(
95
+ ctx: typer.Context,
96
+ registry: str = typer.Option("sinapsis-community", "--registry", help="Named Sinapsis index."),
97
+ key_environment: str | None = typer.Option(
98
+ None, "--key-env", help="Existing environment variable with a packages:read key."
99
+ ),
100
+ cloud_url: str = typer.Option("https://api.sinapsis.tech", "--cloud-url", help="Cloud API HTTPS origin."),
101
+ ) -> None:
102
+ """Validate a scoped key and install it into uv native secure credentials."""
103
+ endpoint = _index_endpoint(registry)
104
+ if key_environment is not None:
105
+ if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]{0,127}", key_environment):
106
+ raise typer.BadParameter("Invalid environment-variable name")
107
+ key = os.environ.get(key_environment, "")
108
+ else:
109
+ key = asyncio.run(_issue_read_key(ctx, registry))
110
+ if not key:
111
+ raise typer.BadParameter("No API key supplied")
112
+ _verify_key(registry, key, cloud_url)
113
+ # uv currently defaults to a plaintext store. Never silently fall back to
114
+ # plaintext when the secure OS backend is unavailable. The token is stdin,
115
+ # never shell history or argv. uv auth login itself does not check validity.
116
+ env = dict(os.environ)
117
+ env["UV_PREVIEW_FEATURES"] = ",".join(part for part in [env.get("UV_PREVIEW_FEATURES", ""), "native-auth"] if part)
118
+ try:
119
+ result = subprocess.run(
120
+ ["uv", "auth", "login", urlsplit(endpoint).hostname or "", "--token", "-"],
121
+ input=key + "\n",
122
+ text=True,
123
+ capture_output=True,
124
+ env=env,
125
+ timeout=30,
126
+ check=False,
127
+ )
128
+ except (OSError, subprocess.TimeoutExpired) as error:
129
+ raise typer.BadParameter("Unable to invoke uv native credential storage") from error
130
+ if result.returncode:
131
+ # uv stderr could contain sensitive diagnostics; never echo it.
132
+ raise typer.BadParameter("uv native credential storage failed; no plaintext fallback was used")
133
+ typer.echo(f"Authenticated uv for {registry}. The key was stored by uv, not Sinapsis.")
134
+ typer.echo("For subsequent uv commands, enable UV_PREVIEW_FEATURES=native-auth in your shell or CI environment.")
135
+ typer.echo("For a project, use a named explicit index and pin the distribution in [tool.uv.sources].")
136
+
137
+
138
+ @app.command("logout")
139
+ def logout(registry: str = typer.Option("sinapsis-community", "--registry")) -> None:
140
+ """Remove a locally stored uv credential; remote API key revocation is separate."""
141
+ endpoint = _index_endpoint(registry)
142
+ env = dict(os.environ)
143
+ env["UV_PREVIEW_FEATURES"] = ",".join(part for part in [env.get("UV_PREVIEW_FEATURES", ""), "native-auth"] if part)
144
+ result = subprocess.run(
145
+ ["uv", "auth", "logout", urlsplit(endpoint).hostname or ""],
146
+ env=env,
147
+ check=False,
148
+ capture_output=True,
149
+ timeout=20,
150
+ )
151
+ if result.returncode:
152
+ raise typer.BadParameter("uv could not remove the native credential")
153
+ typer.echo(f"Removed uv credential for {registry}; revoke the API key separately if required.")
154
+
155
+
156
+ @app.command("indexes")
157
+ def indexes() -> None:
158
+ """Display credential-free index URLs and the required explicit uv mapping."""
159
+ for name, url in _HOSTS.items():
160
+ typer.echo(f"{name}: {url}/simple/")
161
+ typer.echo(
162
+ "Example: uv add sinapsis-sub-agents --index sinapsis-community=https://community.pypi.sinapsis.tech/simple/"
163
+ )
164
+ typer.echo("Use explicit index/source pinning for private packages and third-party patches.")