previty-cli 0.1.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.
previty_cli/app.py ADDED
@@ -0,0 +1,156 @@
1
+ """Root Typer application, central error handler and entry point."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import sys
6
+ from typing import Annotated, Any
7
+
8
+ import typer
9
+ from typer.core import TyperGroup
10
+
11
+ from previty_cli import __version__, exit_codes
12
+ from previty_cli.commands import _common as c
13
+ from previty_cli.commands import agents as agents_cmd
14
+ from previty_cli.commands import apps, auth, checks, readiness, results, sources
15
+ from previty_cli.errors import PrevityError
16
+ from previty_cli.redact import scrub
17
+
18
+ EPILOG = (
19
+ "Exit codes: 0 ok, 1 error, 2 usage, 3 auth, 4 permission, 5 not found, "
20
+ "6 quota, 7 conflict/not ready, 8 wait timeout, 9 check failed, 10 --fail-on, "
21
+ "11 rate limited. See `previty agents`."
22
+ )
23
+
24
+
25
+ def _state_of(ctx: Any) -> c.State:
26
+ obj = ctx.obj
27
+ return obj if isinstance(obj, c.State) else c.State()
28
+
29
+
30
+ def report_error(err: PrevityError, state: c.State) -> None:
31
+ """Print an error to stderr (never to stdout, never with the key)."""
32
+ from previty_cli import output
33
+
34
+ if state.json or not output.is_stdout_tty():
35
+ from previty_cli.output import json as out_json
36
+
37
+ out_json.emit_error(err.to_dict())
38
+ return
39
+ lines = [f"Error: {output.clean(scrub(err.message))}"]
40
+ if err.hint:
41
+ lines.append(f"Hint: {output.clean(scrub(err.hint))}")
42
+ lines.append(
43
+ f"Code: {err.code}"
44
+ + (f" Request ID: {err.request_id}" if err.request_id else "")
45
+ )
46
+ print("\n".join(lines), file=sys.stderr)
47
+
48
+
49
+ _FRAMEWORK_EXCEPTIONS = {"ClickException", "TyperException", "Exit", "Abort"}
50
+
51
+
52
+ def _is_framework_exception(exc: BaseException) -> bool:
53
+ """Click/Typer control-flow exceptions, whichever Click copy Typer uses."""
54
+ return any(cls.__name__ in _FRAMEWORK_EXCEPTIONS for cls in type(exc).__mro__)
55
+
56
+
57
+ class PrevityGroup(TyperGroup):
58
+ """Maps every error to one message and one exit code; no tracebacks."""
59
+
60
+ def invoke(self, ctx: Any) -> Any:
61
+ try:
62
+ return super().invoke(ctx)
63
+ except PrevityError as err:
64
+ report_error(err, _state_of(ctx))
65
+ raise typer.Exit(err.exit_code) from None
66
+ except (typer.Exit, typer.Abort):
67
+ raise
68
+ except Exception as exc:
69
+ if _is_framework_exception(exc):
70
+ raise # usage errors etc.: the framework prints them, exit code 2
71
+ state = _state_of(ctx)
72
+ report_error(
73
+ PrevityError(
74
+ "UNEXPECTED_ERROR",
75
+ f"Unexpected error: {type(exc).__name__}: {exc}",
76
+ exit_code=exit_codes.GENERAL,
77
+ hint="Run with --verbose for a traceback and report the problem.",
78
+ ),
79
+ state,
80
+ )
81
+ if state.verbose:
82
+ import traceback
83
+
84
+ print(scrub(traceback.format_exc()), file=sys.stderr)
85
+ raise typer.Exit(exit_codes.GENERAL) from None
86
+ except KeyboardInterrupt:
87
+ print("Interrupted.", file=sys.stderr)
88
+ raise typer.Exit(130) from None
89
+
90
+
91
+ app = typer.Typer(
92
+ name="previty",
93
+ cls=PrevityGroup,
94
+ help="Previty command-line interface.",
95
+ epilog=EPILOG,
96
+ no_args_is_help=True,
97
+ pretty_exceptions_enable=False, # tracebacks would print locals, maybe the key
98
+ rich_markup_mode=None,
99
+ add_completion=False,
100
+ )
101
+
102
+
103
+ def _version(value: bool) -> None:
104
+ if value:
105
+ typer.echo(f"previty {__version__}")
106
+ raise typer.Exit()
107
+
108
+
109
+ @app.callback()
110
+ def root(
111
+ ctx: typer.Context,
112
+ json_flag: Annotated[
113
+ bool,
114
+ typer.Option(
115
+ "--json", help="Print JSON. Default when stdout is not a terminal."
116
+ ),
117
+ ] = False,
118
+ no_color: Annotated[
119
+ bool, typer.Option("--no-color", help="Disable colors (also: NO_COLOR).")
120
+ ] = False,
121
+ api_url: Annotated[
122
+ str | None,
123
+ typer.Option(
124
+ "--api-url",
125
+ help="API base URL (only api.previty.de and api.dev.previty.de).",
126
+ ),
127
+ ] = None,
128
+ verbose: Annotated[
129
+ bool,
130
+ typer.Option("--verbose", help="Print request IDs to stderr (never the key)."),
131
+ ] = False,
132
+ version: Annotated[
133
+ bool,
134
+ typer.Option(
135
+ "--version", callback=_version, is_eager=True, help="Show the version."
136
+ ),
137
+ ] = False,
138
+ ) -> None:
139
+ ctx.obj = c.State(
140
+ json=json_flag, no_color=no_color, api_url=api_url, verbose=verbose
141
+ )
142
+
143
+
144
+ app.command("login")(auth.login)
145
+ app.command("logout")(auth.logout)
146
+ app.command("whoami")(auth.whoami)
147
+ app.command("readiness")(readiness.readiness)
148
+ app.command("results")(results.results)
149
+ app.command("agents")(agents_cmd.agents)
150
+ app.add_typer(apps.app, name="apps")
151
+ app.add_typer(sources.app, name="sources")
152
+ app.add_typer(checks.app, name="check")
153
+
154
+
155
+ def main() -> None:
156
+ app()
previty_cli/clock.py ADDED
@@ -0,0 +1,13 @@
1
+ """Time source, replaceable in tests so retry loops do not really sleep."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import time
6
+
7
+
8
+ def sleep(seconds: float) -> None:
9
+ time.sleep(seconds)
10
+
11
+
12
+ def monotonic() -> float:
13
+ return time.monotonic()
File without changes
@@ -0,0 +1,117 @@
1
+ """Shared option types and helpers for the commands (light imports only)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ import sys
7
+ from dataclasses import dataclass
8
+ from enum import Enum
9
+ from typing import TYPE_CHECKING, Annotated, Any, TypeVar
10
+
11
+ import typer
12
+
13
+ from previty_cli import config, output
14
+ from previty_cli.errors import NotLoggedInError, PrevityError, UsageError
15
+
16
+ if TYPE_CHECKING:
17
+ from pydantic import BaseModel
18
+ from rich.console import Console
19
+
20
+ from previty_cli.api.client import ApiClient
21
+
22
+ M = TypeVar("M", bound="BaseModel")
23
+
24
+ JsonOpt = Annotated[
25
+ bool,
26
+ typer.Option(
27
+ "--json", help="Print JSON. This is the default when stdout is not a terminal."
28
+ ),
29
+ ]
30
+ AppOpt = Annotated[str, typer.Option("--app", help="Application ID (see `apps list`).")]
31
+
32
+
33
+ class FailOn(str, Enum):
34
+ fail = "fail"
35
+ unclear = "unclear"
36
+
37
+
38
+ @dataclass
39
+ class State:
40
+ json: bool = False
41
+ no_color: bool = False
42
+ api_url: str | None = None
43
+ verbose: bool = False
44
+
45
+
46
+ def get_state(ctx: typer.Context) -> State:
47
+ obj = ctx.find_root().obj
48
+ if not isinstance(obj, State):
49
+ obj = State()
50
+ ctx.find_root().obj = obj
51
+ return obj
52
+
53
+
54
+ def wants_json(ctx: typer.Context, flag: bool = False) -> bool:
55
+ """JSON if asked for (here or globally) or when stdout is not a terminal."""
56
+ state = get_state(ctx)
57
+ if flag:
58
+ state.json = True
59
+ return state.json or not output.is_stdout_tty()
60
+
61
+
62
+ def console(ctx: typer.Context) -> Console:
63
+ return output.make_console(no_color=get_state(ctx).no_color)
64
+
65
+
66
+ def err_console(ctx: typer.Context) -> Console:
67
+ return output.make_console(no_color=get_state(ctx).no_color, stderr=True)
68
+
69
+
70
+ def open_client(ctx: typer.Context) -> ApiClient:
71
+ """Resolve credentials and build the client. Never prompts."""
72
+ state = get_state(ctx)
73
+ settings = config.resolve_settings(state.api_url)
74
+ if not settings.api_key:
75
+ raise NotLoggedInError()
76
+ from previty_cli.api.client import ApiClient
77
+
78
+ return ApiClient(settings.api_url, settings.api_key, verbose=state.verbose)
79
+
80
+
81
+ def parse(model: type[M], raw: Any) -> M:
82
+ from pydantic import ValidationError
83
+
84
+ try:
85
+ return model.model_validate(raw)
86
+ except ValidationError:
87
+ raise PrevityError(
88
+ "UNEXPECTED_RESPONSE",
89
+ f"The API response did not match the expected {model.__name__} shape.",
90
+ exit_code=1,
91
+ hint="Use --json to see the raw response; the CLI may need an update.",
92
+ ) from None
93
+
94
+
95
+ _DURATION = re.compile(r"(\d+)([hms]?)")
96
+
97
+
98
+ def parse_duration(text: str) -> float:
99
+ """``30m``, ``90s``, ``1h30m`` or plain seconds."""
100
+ value = text.strip().lower()
101
+ total = 0
102
+ pos = 0
103
+ units = {"h": 3600, "m": 60, "s": 1, "": 1}
104
+ while pos < len(value):
105
+ match = _DURATION.match(value, pos)
106
+ if not match:
107
+ raise UsageError(f"Invalid duration {text!r}. Use e.g. 90s, 30m or 1h.")
108
+ total += int(match.group(1)) * units[match.group(2)]
109
+ pos = match.end()
110
+ if total <= 0:
111
+ raise UsageError(f"Invalid duration {text!r}. Use e.g. 90s, 30m or 1h.")
112
+ return float(total)
113
+
114
+
115
+ def note(message: str) -> None:
116
+ """Progress and hints go to stderr."""
117
+ print(output.clean(message), file=sys.stderr)
@@ -0,0 +1,25 @@
1
+ """agents: print the packaged usage guide for coding agents."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import sys
6
+ from importlib import resources
7
+
8
+ import typer
9
+
10
+ from previty_cli.commands import _common as c
11
+
12
+
13
+ def guide_text() -> str:
14
+ return resources.files("previty_cli").joinpath("AGENTS.md").read_text("utf-8")
15
+
16
+
17
+ def agents(ctx: typer.Context, json_flag: c.JsonOpt = False) -> None:
18
+ """Print AGENTS.md, the usage guide for coding agents and CI."""
19
+ text = guide_text()
20
+ if json_flag:
21
+ from previty_cli.output import json as out_json
22
+
23
+ out_json.emit({"agents": text})
24
+ return
25
+ sys.stdout.write(text)
@@ -0,0 +1,26 @@
1
+ """apps list (US-4)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import typer
6
+
7
+ from previty_cli.commands import _common as c
8
+
9
+ app = typer.Typer(help="Applications.", no_args_is_help=True)
10
+
11
+
12
+ @app.command("list")
13
+ def list_apps(ctx: typer.Context, json_flag: c.JsonOpt = False) -> None:
14
+ """List the applications you can access."""
15
+ as_json = c.wants_json(ctx, json_flag)
16
+ with c.open_client(ctx) as client:
17
+ data = client.list_applications()
18
+ if as_json:
19
+ from previty_cli.output import json as out_json
20
+
21
+ out_json.emit(data)
22
+ return
23
+ from previty_cli.api import models as m
24
+ from previty_cli.output import table
25
+
26
+ table.apps(c.console(ctx), c.parse(m.PublicApplicationList, data))
@@ -0,0 +1,101 @@
1
+ """login, logout, whoami (US-3)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import sys
7
+ from typing import Annotated
8
+
9
+ import typer
10
+
11
+ from previty_cli import config, output
12
+ from previty_cli.commands import _common as c
13
+ from previty_cli.errors import UsageError
14
+ from previty_cli.redact import register_secret
15
+
16
+
17
+ def _read_key(with_token: bool) -> str:
18
+ if with_token or not output.is_stdin_tty():
19
+ # Never prompt without a terminal: read the key from stdin.
20
+ raw = sys.stdin.read().strip()
21
+ if not raw:
22
+ raise UsageError(
23
+ "No API key on stdin.",
24
+ hint='Pipe the key in, e.g. `printf %s "$KEY" | previty login`.',
25
+ )
26
+ key = raw.splitlines()[0]
27
+ else:
28
+ key = typer.prompt("Previty API key (input hidden)", hide_input=True)
29
+ key = config.validate_key_format(key)
30
+ register_secret(key)
31
+ return key
32
+
33
+
34
+ def login(
35
+ ctx: typer.Context,
36
+ with_token: Annotated[
37
+ bool,
38
+ typer.Option(
39
+ "--with-token", help="Read the API key from stdin instead of prompting."
40
+ ),
41
+ ] = False,
42
+ json_flag: c.JsonOpt = False,
43
+ ) -> None:
44
+ """Store an API key. The key is never accepted as an argument."""
45
+ state = c.get_state(ctx)
46
+ key = _read_key(with_token)
47
+ url = config.resolve_api_url(state.api_url, config.read_credentials())
48
+ from previty_cli.api.client import ApiClient
49
+
50
+ with ApiClient(url, key, verbose=state.verbose) as client:
51
+ me = client.me()
52
+ path = config.write_credentials(url, key)
53
+
54
+ if os.environ.get(config.ENV_API_KEY):
55
+ c.note(
56
+ f"Note: {config.ENV_API_KEY} is set and takes precedence over the "
57
+ "stored key."
58
+ )
59
+ if c.wants_json(ctx, json_flag):
60
+ from previty_cli.output import json as out_json
61
+
62
+ out_json.emit({**me, "credentialsPath": str(path)})
63
+ return
64
+ from previty_cli.api import models as m
65
+ from previty_cli.output import table
66
+
67
+ console = c.console(ctx)
68
+ parsed = c.parse(m.PublicMe, me)
69
+ console.print(f"Logged in. Key {parsed.key.prefix} stored in {path}")
70
+ table.whoami(console, parsed)
71
+
72
+
73
+ def logout(ctx: typer.Context, json_flag: c.JsonOpt = False) -> None:
74
+ """Remove the stored API key (does nothing if there is none)."""
75
+ removed = config.delete_credentials()
76
+ env_set = bool(os.environ.get(config.ENV_API_KEY))
77
+ if c.wants_json(ctx, json_flag):
78
+ from previty_cli.output import json as out_json
79
+
80
+ out_json.emit({"loggedOut": removed, "environmentKeyStillSet": env_set})
81
+ return
82
+ console = c.console(ctx)
83
+ console.print("Logged out." if removed else "Not logged in (no stored key).")
84
+ if env_set:
85
+ console.print(f"{config.ENV_API_KEY} is still set in the environment.")
86
+
87
+
88
+ def whoami(ctx: typer.Context, json_flag: c.JsonOpt = False) -> None:
89
+ """Show user, organization, key prefix, permissions and expiry."""
90
+ as_json = c.wants_json(ctx, json_flag)
91
+ with c.open_client(ctx) as client:
92
+ me = client.me()
93
+ if as_json:
94
+ from previty_cli.output import json as out_json
95
+
96
+ out_json.emit(me)
97
+ return
98
+ from previty_cli.api import models as m
99
+ from previty_cli.output import table
100
+
101
+ table.whoami(c.console(ctx), c.parse(m.PublicMe, me))