hop3-cli 0.5.0.dev1__tar.gz → 0.5.0.dev3__tar.gz

{hop3_cli-0.5.0.dev1 → hop3_cli-0.5.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hop3-cli
-Version: 0.5.0.dev1
+Version: 0.5.0.dev3
 Summary: 
 Author: Stefane Fermigier
 Author-email: Stefane Fermigier <sf@abilian.com>
@@ -64,36 +64,48 @@ hop3 restart
 
 ## App Resolution
 
-Commands that act on a single app (`logs`, `restart`, `config set`, `run`, …) no longer take the app name as a positional argument. Instead the CLI resolves it from a layered chain, walking sources until one supplies a value (ADR 036 D7):
+Commands that act on a single app (`logs`, `restart`, `config set`, `run`, …) no longer take the app name as a positional argument. Instead the CLI resolves it from a layered chain, walking sources until one supplies a value (ADR 042 §Resolution chains; supersedes ADR 036 §D7):
 
 1. `--app <name>` / `-a <name>` — explicit flag, wins over everything.
 2. `$HOP3_APP` — environment variable for the current shell.
 3. `.hop3-app` — one-line file in CWD or any ancestor up to `$HOME`. Drop it in a project repo and `hop3` from inside picks up the right app.
 4. `hop3.toml [cli].app` — same search path as `.hop3-app`, lower priority.
-5. Active context's `default_app` — set via `hop3 use <app>`.
+5. `hop3.toml [contexts.<resolved-context>].app` — when a project context resolves (see below), its `app` field becomes the source. Lets one project map per-environment to different apps.
+6. `hop3.toml [metadata].id` — the project's canonical name. The "I'm physically standing in this project" source; outranks any server-level default so being inside a project always wins over a sticky binding from elsewhere.
+7. Git remote `hop3-<env>` parsed for an app name — supports `git push hop3-prod main` style deploys.
+8. Active server's `default_app` from `~/.config/hop3-cli/servers.toml` — set via `hop3 server use --default-app <app>`. Lowest-priority fallback for single-app users.
 
-Use `hop3 --why <command>` to print the full trace and see which source won.
+Use `hop3 --why <command>` to print the full trace and see which source won. `--why` is diagnostic-only: the command itself is not executed (so `hop3 deploy --why` is safe to run).
 
 ```bash
 # Explicit (always works):
 hop3 logs --app myapp
 hop3 config set --app myapp KEY=value
 
-# Sticky app for the context:
-hop3 use myapp
-hop3 logs
-
 # Per-shell:
 export HOP3_APP=myapp
 
-# Per-directory:
+# Per-directory (legacy pin file):
 echo myapp > .hop3-app
 
+# Per-project, declared in hop3.toml:
+# [metadata]
+# id = "myapp"
+# [contexts.staging]
+# app = "myapp-staging"
+
 # Debug:
 hop3 --why logs
 ```
 
-See [CLI Reference: App Resolution](../../docs/src/reference/cli.md#app-resolution) for the full specification.
+The ADR 042 model splits the old "context" noun into two concepts:
+
+- **Server records** — credentialed bindings to a Hop3 server. Live in `~/.config/hop3-cli/servers.toml`. Managed with `hop3 server` (`add` / `list` / `show` / `use` / `login` / `remove`).
+- **Project contexts** — environment-shaped overlays on a single project. Declared as `[contexts.<name>]` blocks inside `hop3.toml`. Managed with `hop3 context` from inside a project tree (`init` / `use` / `list` / `show` / `add` / `remove`). The currently-selected one is recorded in `.hop3-local.toml` (gitignored automatically).
+
+A `hop3 deploy` from a project tree resolves: server (which Hop3 to talk to) + context (which environment of this project) + app (which app on that server) — and shows a preview-and-confirm prompt with the plan before invoking the deploy RPC. `--dry-run` exits after printing the plan; `--force` bypasses the project-mismatch safety guard.
+
+See [CLI Reference: App Resolution](../../docs/src/reference/cli.md#app-resolution) and [ADR 042](../../notes/adrs/042-cli-context-model.md) for the full specification.
 
 ## Configuration
 

{hop3_cli-0.5.0.dev1 → hop3_cli-0.5.0.dev3}/README.md

@@ -44,36 +44,48 @@ hop3 restart
 
 ## App Resolution
 
-Commands that act on a single app (`logs`, `restart`, `config set`, `run`, …) no longer take the app name as a positional argument. Instead the CLI resolves it from a layered chain, walking sources until one supplies a value (ADR 036 D7):
+Commands that act on a single app (`logs`, `restart`, `config set`, `run`, …) no longer take the app name as a positional argument. Instead the CLI resolves it from a layered chain, walking sources until one supplies a value (ADR 042 §Resolution chains; supersedes ADR 036 §D7):
 
 1. `--app <name>` / `-a <name>` — explicit flag, wins over everything.
 2. `$HOP3_APP` — environment variable for the current shell.
 3. `.hop3-app` — one-line file in CWD or any ancestor up to `$HOME`. Drop it in a project repo and `hop3` from inside picks up the right app.
 4. `hop3.toml [cli].app` — same search path as `.hop3-app`, lower priority.
-5. Active context's `default_app` — set via `hop3 use <app>`.
+5. `hop3.toml [contexts.<resolved-context>].app` — when a project context resolves (see below), its `app` field becomes the source. Lets one project map per-environment to different apps.
+6. `hop3.toml [metadata].id` — the project's canonical name. The "I'm physically standing in this project" source; outranks any server-level default so being inside a project always wins over a sticky binding from elsewhere.
+7. Git remote `hop3-<env>` parsed for an app name — supports `git push hop3-prod main` style deploys.
+8. Active server's `default_app` from `~/.config/hop3-cli/servers.toml` — set via `hop3 server use --default-app <app>`. Lowest-priority fallback for single-app users.
 
-Use `hop3 --why <command>` to print the full trace and see which source won.
+Use `hop3 --why <command>` to print the full trace and see which source won. `--why` is diagnostic-only: the command itself is not executed (so `hop3 deploy --why` is safe to run).
 
 ```bash
 # Explicit (always works):
 hop3 logs --app myapp
 hop3 config set --app myapp KEY=value
 
-# Sticky app for the context:
-hop3 use myapp
-hop3 logs
-
 # Per-shell:
 export HOP3_APP=myapp
 
-# Per-directory:
+# Per-directory (legacy pin file):
 echo myapp > .hop3-app
 
+# Per-project, declared in hop3.toml:
+# [metadata]
+# id = "myapp"
+# [contexts.staging]
+# app = "myapp-staging"
+
 # Debug:
 hop3 --why logs
 ```
 
-See [CLI Reference: App Resolution](../../docs/src/reference/cli.md#app-resolution) for the full specification.
+The ADR 042 model splits the old "context" noun into two concepts:
+
+- **Server records** — credentialed bindings to a Hop3 server. Live in `~/.config/hop3-cli/servers.toml`. Managed with `hop3 server` (`add` / `list` / `show` / `use` / `login` / `remove`).
+- **Project contexts** — environment-shaped overlays on a single project. Declared as `[contexts.<name>]` blocks inside `hop3.toml`. Managed with `hop3 context` from inside a project tree (`init` / `use` / `list` / `show` / `add` / `remove`). The currently-selected one is recorded in `.hop3-local.toml` (gitignored automatically).
+
+A `hop3 deploy` from a project tree resolves: server (which Hop3 to talk to) + context (which environment of this project) + app (which app on that server) — and shows a preview-and-confirm prompt with the plan before invoking the deploy RPC. `--dry-run` exits after printing the plan; `--force` bypasses the project-mismatch safety guard.
+
+See [CLI Reference: App Resolution](../../docs/src/reference/cli.md#app-resolution) and [ADR 042](../../notes/adrs/042-cli-context-model.md) for the full specification.
 
 ## Configuration
 

{hop3_cli-0.5.0.dev1 → hop3_cli-0.5.0.dev3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hop3-cli"
-version = "0.5.0.dev1"
+version = "0.5.0.dev3"
 authors = [
     {name = "Stefane Fermigier", email = "sf@abilian.com"},
 ]

{hop3_cli-0.5.0.dev1 → hop3_cli-0.5.0.dev3}/src/hop3_cli/commands/arguments.py

@@ -133,26 +133,43 @@ def _resolve_password_inputs(args: list[str]) -> None:
     the next positional after the command tokens. Server-side commands keep
     their existing positional contract — the CLI is the security boundary.
 
-    Applies only to the two commands that take a password:
+    Applies to the three commands that take a password:
       hop3 user add <username> <email> <password>
       hop3 user set-password <username> <password>
+      hop3 auth login <username> <password>
     """
-    if len(args) < 2 or args[0] != "user":
-        return
-    if args[1] not in {"add", "set-password"}:
+    insert_at = _password_insert_index(args)
+    if insert_at is None:
         return
 
     password = _extract_password_flag(args)
     if password is None:
         return
 
-    # Insertion index: after `user add <user> <email>` for add; after
-    # `user set-password <user>` for set-password.
-    insert_at = 4 if args[1] == "add" else 3
     insert_at = min(insert_at, len(args))
     args.insert(insert_at, password)
 
 
+def _password_insert_index(args: list[str]) -> int | None:
+    """Return the positional index where the resolved password should land.
+
+    Returns None if the current ``args`` does not target a command that
+    accepts a password.
+    """
+    if len(args) < 2:
+        return None
+    if args[0] == "user" and args[1] == "add":
+        # user add <username> <email> <password>
+        return 4
+    if args[0] == "user" and args[1] == "set-password":
+        # user set-password <username> <password>
+        return 3
+    if args[0] == "auth" and args[1] == "login":
+        # auth login <username> <password>
+        return 3
+    return None
+
+
 def _extract_password_flag(args: list[str]) -> str | None:
     """Pop --password-file / --stdin from args and return the resolved password.
 

{hop3_cli-0.5.0.dev1 → hop3_cli-0.5.0.dev3}/src/hop3_cli/commands/destructive.py

@@ -79,7 +79,7 @@ def _confirm_protected_context(config: Config | None) -> tuple[bool, str | None]
     return True, context_name
 
 
-def confirm_destructive_action(
+def confirm_destructive_action(  # noqa: PLR0911 — sequential decision tree, each return is a distinct escape hatch (json mode, no-match, missing-args, --confirm, --no-input, protected context, …) with its own side effects; flattening into a result var would obscure the safety story.
     cli_args: list[str],
     printer: RichPrinter,
     config: Config | None = None,

{hop3_cli-0.5.0.dev1 → hop3_cli-0.5.0.dev3}/src/hop3_cli/commands/flags.py

@@ -32,7 +32,15 @@ class CliFlags:
     """CLI flags that control output and behavior."""
 
     json_output: bool = False  # --json, -j: Machine-readable JSON output
-    skip_confirm: bool = False  # -y, --yes, --force: Skip confirmation prompts
+    skip_confirm: bool = False  # -y, --yes: Skip confirmation prompts
+
+    # ADR 042 §D14: --force is the dedicated bypass for the project-
+    # mismatch guard. It also implies skip_confirm (a --force user has
+    # already opted into "yes really do it"), but the converse is NOT
+    # true: -y/--yes alone must NOT silence the safety guard, or scripts
+    # running `hop3 deploy -y` from the wrong directory deploy to the
+    # wrong app — exactly the scenario the guard exists to prevent.
+    force: bool = False
 
     # Verbosity is now stored as a level (0=quiet, 1=normal, 2=verbose, 3=debug)
     # This allows -vv, -vvv, -qq, etc.
@@ -41,12 +49,18 @@ class CliFlags:
     # Context override for multi-server support
     context: str | None = None  # --context <name>: Use a specific context
 
+    # ADR 042: `--server` / `-s` selects a server from the global registry
+    # explicitly. Highest-priority source in the server resolution chain;
+    # bypasses any context-derived server.
+    server: str | None = None
+
     # ADR 036 D5: `--app` / `-a` is always a flag, never positional.
     # ADR 036 D7: if not set, the CLI will resolve one via the app-resolution
     # chain (env, .hop3-app file, hop3.toml, context default).
     app: str | None = None
 
-    # ADR 036: `--why` prints the resolution trace before running.
+    # ADR 036: `--why` prints the resolution trace and exits without running
+    # the command (diagnostic-only — avoids `hop3 deploy --why` deploying).
     why: bool = False
 
     # ADR 036: `--no-alias` bypasses alias resolution.
@@ -62,6 +76,11 @@ class CliFlags:
     # automation/CI; complements `--yes` (which says "yes, take action").
     no_input: bool = False
 
+    # ADR 042 §Deploy preview: `--dry-run` prints the deploy plan and
+    # exits without invoking the RPC. Analogous to `--why` but for the
+    # action plan rather than the resolution trace.
+    dry_run: bool = False
+
     @property
     def quiet(self) -> bool:
         """True if verbosity is 0 (quiet mode)."""
@@ -78,7 +97,7 @@ class CliFlags:
         return self.verbosity >= 3
 
 
-def _parse_verbosity_flag(arg: str, current: int) -> int | None:
+def _parse_verbosity_flag(arg: str, current: int) -> int | None:  # noqa: PLR0911 — mix of exact matches (--debug/--verbose/--quiet) and pattern matches (-v*/-d*/-q* with length-dependent verbosity); a unified table would have to encode the per-prefix length-to-level math and would read worse than the straight-line cascade.
     """Parse a verbosity-related flag; return the new verbosity or None if not one."""
     if arg == "--debug":
         return 3
@@ -135,12 +154,15 @@ def parse_flags(args: list[str]) -> tuple[CliFlags, list[str]]:
     state: dict[str, Any] = {
         "json_output": False,
         "skip_confirm": False,
+        "force": False,
         "context": None,
+        "server": None,
         "app": None,
         "why": False,
         "no_alias": False,
         "confirm_value": None,
         "no_input": False,
+        "dry_run": False,
         "verbosity": _get_env_verbosity() or 1,
     }
 
@@ -157,8 +179,30 @@ def parse_flags(args: list[str]) -> tuple[CliFlags, list[str]]:
     return CliFlags(**state), remaining_args
 
 
-_JSON_FLAGS = {"--json", "-j"}
-_YES_FLAGS = {"-y", "--yes", "--force"}
+# Boolean flags: token → state field to set True. One row per logical flag,
+# with aliases grouped in the tuple key.
+_BOOL_FLAGS: dict[tuple[str, ...], str] = {
+    ("--json", "-j"): "json_output",
+    ("-y", "--yes"): "skip_confirm",
+    ("--why",): "why",
+    ("--no-alias",): "no_alias",
+    ("--no-input",): "no_input",
+    ("--dry-run",): "dry_run",
+}
+
+
+# --force needs its own row because it sets two flags at once: the
+# §D14 bypass AND skip_confirm (a --force user has implicitly opted
+# into the prompt skip). Handled in _apply_flag.
+_FORCE_FLAG = "--force"
+
+# Two-token "--flag value" pairs.
+_PAIR_FLAGS: dict[tuple[str, ...], str] = {
+    ("--context", "-c"): "context",
+    ("--server", "-s"): "server",
+    ("--app", "-a"): "app",
+    ("--confirm",): "confirm_value",
+}
 
 
 def _apply_flag(args: list[str], i: int, state: dict[str, Any]) -> int:
@@ -169,32 +213,21 @@ def _apply_flag(args: list[str], i: int, state: dict[str, Any]) -> int:
     """
     arg = args[i]
 
-    if arg in _JSON_FLAGS:
-        state["json_output"] = True
-        return 1
-    if arg in _YES_FLAGS:
+    if arg == _FORCE_FLAG:
+        state["force"] = True
         state["skip_confirm"] = True
         return 1
-    if arg == "--why":
-        state["why"] = True
-        return 1
-    if arg == "--no-alias":
-        state["no_alias"] = True
-        return 1
-    if arg == "--no-input":
-        state["no_input"] = True
-        return 1
+
+    for keys, field_name in _BOOL_FLAGS.items():
+        if arg in keys:
+            state[field_name] = True
+            return 1
+
     if arg.startswith("--confirm="):
         state["confirm_value"] = arg.split("=", 1)[1]
         return 1
 
-    # Two-token forms: ``--flag value``.
-    pair_keys = {
-        ("--context", "-c"): "context",
-        ("--app", "-a"): "app",
-        ("--confirm",): "confirm_value",
-    }
-    for keys, field_name in pair_keys.items():
+    for keys, field_name in _PAIR_FLAGS.items():
         if arg in keys and i + 1 < len(args):
             state[field_name] = args[i + 1]
             return 2

{hop3_cli-0.5.0.dev1 → hop3_cli-0.5.0.dev3}/src/hop3_cli/commands/local/__init__.py

@@ -22,6 +22,7 @@ from .completion_cmd import handle_completion
 from .context_cmd import handle_context
 from .init_cmd import handle_init
 from .login_cmd import handle_login, handle_login_token
+from .server_cmd import handle_server
 from .settings_cmd import handle_settings, settings_get, settings_set, settings_show
 from .ssh_ops import BootstrapError, extract_token, infer_server_url
 from .use_cmd import handle_use
@@ -44,6 +45,7 @@ __all__ = [
     "handle_local_command",
     "handle_login",
     "handle_login_token",
+    "handle_server",
     "handle_settings",
     "handle_use",
     "handle_version",
@@ -59,9 +61,10 @@ __all__ = [
 LOCAL_COMMANDS_INFO = {
     "aliases": "List all effective aliases (built-in, plugin, user).",
     "completion": "Generate shell completion scripts.",
-    "context": "Manage multiple server contexts.",
+    "context": "Manage project deploy contexts (or legacy server contexts).",
     "init": "Initialize connection to a Hop3 server via SSH.",
     "login": "Authenticate to a server.",
+    "server": "Manage server bindings (ADR 042).",
     "settings": "Manage local CLI settings (server URL, token, SSL).",
     "use": "Set / show / clear the current context's default app.",
     "version": "Show CLI version.",
@@ -97,6 +100,23 @@ def is_local_command(args: list[str]) -> bool:
     return not (command == "auth" and len(args) > 1 and not args[1].startswith("-"))
 
 
+# Dispatch table for local commands. Each entry maps a CLI token to its
+# handler. Handlers that always claim the command return None; ``auth`` is
+# the one exception — it returns a bool to delegate back to the server when
+# the subcommand belongs in the server-side `auth` namespace.
+_LOCAL_HANDLERS = {
+    "completion": handle_completion,
+    "context": handle_context,
+    "init": handle_init,
+    "login": handle_login,
+    "server": handle_server,
+    "settings": handle_settings,
+    "aliases": handle_aliases,
+    "use": handle_use,
+}
+_VERSION_TOKENS = {"version", "--version", "-V"}
+
+
 def handle_local_command(args: list[str], config: Config, printer: RichPrinter) -> bool:
     """Handle a local command.
 
@@ -106,35 +126,18 @@ def handle_local_command(args: list[str], config: Config, printer: RichPrinter)
     if not args:
         return False
 
-    command = args[0]
-    cmd_args = args[1:]
+    command, cmd_args = args[0], args[1:]
 
-    if command == "completion":
-        handle_completion(cmd_args, config, printer)
-        return True
-    if command == "context":
-        handle_context(cmd_args, config, printer)
-        return True
-    if command == "init":
-        handle_init(cmd_args, config, printer)
-        return True
-    if command == "login":
-        handle_login(cmd_args, config, printer)
-        return True
-    if command == "settings":
-        handle_settings(cmd_args, config, printer)
-        return True
-    if command == "aliases":
-        handle_aliases(cmd_args, config, printer)
-        return True
-    if command == "use":
-        handle_use(cmd_args, config, printer)
-        return True
-    if command in {"version", "--version", "-V"}:
+    if command in _VERSION_TOKENS:
         handle_version(cmd_args, config, printer)
         return True
+
     if command == "auth":
-        # handle_auth returns False if command should go to server
+        # handle_auth returns False if command should go to server.
         return handle_auth(cmd_args, config, printer)
 
-    return False
+    handler = _LOCAL_HANDLERS.get(command)
+    if handler is None:
+        return False
+    handler(cmd_args, config, printer)
+    return True