hop3-cli 0.5.0.dev3__tar.gz → 0.6.1__tar.gz

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

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: hop3-cli
-Version: 0.5.0.dev3
+Version: 0.6.1
 Summary: 
 Author: Stefane Fermigier
 Author-email: Stefane Fermigier <sf@abilian.com>
 License-Expression: Apache-2.0
 Requires-Dist: toml>=0.10.2,<1.0.0
+Requires-Dist: tomlkit>=0.13.0
 Requires-Dist: jsonrpcclient>=4.0.3,<5.0.0
 Requires-Dist: requests>=2.32.3,<3.0.0
 Requires-Dist: tabulate>=0.9.0,<1.0.0
@@ -57,29 +58,27 @@ hop3 apps
 hop3 use myapp
 
 # From here on, app-scoped commands resolve myapp automatically:
-hop3 logs
+hop3 app logs
 hop3 config set KEY=value
-hop3 restart
+hop3 app 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 042 §Resolution chains; supersedes 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; 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. `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.
+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. Trusted only when the context was selected CWD-rooted (`--context` or in-tree `.hop3-local.toml`); an ambiently-selected context still resolves but trips the project-mismatch guard.
+6. `hop3.toml [metadata].id` — the project's canonical name. The "I'm physically standing in this project" source, so being inside a project always wins over a sticky binding from elsewhere.
 
 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 app logs --app myapp
 hop3 config set --app myapp KEY=value
 
 # Per-shell:
@@ -98,12 +97,12 @@ echo myapp > .hop3-app
 hop3 --why logs
 ```
 
-The ADR 042 model splits the old "context" noun into two concepts:
+The ADR 042 model has a single managed noun — the **context** — and a single selector, `--context <name>`, for every command (app-bound or not).
 
-- **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).
+- **Contexts** — a named target at two scopes. A **project** context (dev / staging / prod) is declared as a `[contexts.<name>]` block inside the committed `hop3.toml`: a non-secret bundle of server address + app + domains + env. A **global** context is a name bound to a server address in the per-developer `config.toml` (`[contexts.<name>].server`), so project-less commands (`hop3 apps --context prod`) can target a server by name. `--context` resolves project-first, then global; there is no `--server` flag. Managed with `hop3 context` (`add` / `use` / `list` / `show` / `remove` / `rename`) — project scope inside a project tree, global scope outside one (or with `--global`). The per-checkout project selection is recorded in `.hop3-local.toml` (gitignored automatically).
+- **Credentials are invisible plumbing** — there is no "server" noun to manage. `hop3 login` stores a bearer token in the per-server credential store (`~/.config/hop3-cli/credentials.toml`, mode `0600`), keyed by the server's canonical address, and records that server as the default target; `hop3 login --context <name>` also names it as a global context and the default. `config.toml` stays secret-free (local preferences, global contexts, `[cli].default_context`).
 
-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.
+A `hop3 deploy` from a project tree resolves the context (which environment of this project, and therefore which server and app), 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.
 
@@ -131,7 +130,7 @@ hop3-cli/
 │   ├── rpc/
 │   │   └── client.py        # JSON-RPC client with SSH tunnel
 │   ├── commands/
-│   │   ├── local.py         # Local commands (init, login, settings)
+│   │   ├── local/           # Local commands (init, login, settings, context)
 │   │   ├── flags.py         # CLI flag parsing (--app, --why, --json, -y, …)
 │   │   └── destructive.py   # Confirmation prompts
 │   └── ui/

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

@@ -37,29 +37,27 @@ hop3 apps
 hop3 use myapp
 
 # From here on, app-scoped commands resolve myapp automatically:
-hop3 logs
+hop3 app logs
 hop3 config set KEY=value
-hop3 restart
+hop3 app 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 042 §Resolution chains; supersedes 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; 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. `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.
+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. Trusted only when the context was selected CWD-rooted (`--context` or in-tree `.hop3-local.toml`); an ambiently-selected context still resolves but trips the project-mismatch guard.
+6. `hop3.toml [metadata].id` — the project's canonical name. The "I'm physically standing in this project" source, so being inside a project always wins over a sticky binding from elsewhere.
 
 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 app logs --app myapp
 hop3 config set --app myapp KEY=value
 
 # Per-shell:
@@ -78,12 +76,12 @@ echo myapp > .hop3-app
 hop3 --why logs
 ```
 
-The ADR 042 model splits the old "context" noun into two concepts:
+The ADR 042 model has a single managed noun — the **context** — and a single selector, `--context <name>`, for every command (app-bound or not).
 
-- **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).
+- **Contexts** — a named target at two scopes. A **project** context (dev / staging / prod) is declared as a `[contexts.<name>]` block inside the committed `hop3.toml`: a non-secret bundle of server address + app + domains + env. A **global** context is a name bound to a server address in the per-developer `config.toml` (`[contexts.<name>].server`), so project-less commands (`hop3 apps --context prod`) can target a server by name. `--context` resolves project-first, then global; there is no `--server` flag. Managed with `hop3 context` (`add` / `use` / `list` / `show` / `remove` / `rename`) — project scope inside a project tree, global scope outside one (or with `--global`). The per-checkout project selection is recorded in `.hop3-local.toml` (gitignored automatically).
+- **Credentials are invisible plumbing** — there is no "server" noun to manage. `hop3 login` stores a bearer token in the per-server credential store (`~/.config/hop3-cli/credentials.toml`, mode `0600`), keyed by the server's canonical address, and records that server as the default target; `hop3 login --context <name>` also names it as a global context and the default. `config.toml` stays secret-free (local preferences, global contexts, `[cli].default_context`).
 
-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.
+A `hop3 deploy` from a project tree resolves the context (which environment of this project, and therefore which server and app), 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.
 
@@ -111,7 +109,7 @@ hop3-cli/
 │   ├── rpc/
 │   │   └── client.py        # JSON-RPC client with SSH tunnel
 │   ├── commands/
-│   │   ├── local.py         # Local commands (init, login, settings)
+│   │   ├── local/           # Local commands (init, login, settings, context)
 │   │   ├── flags.py         # CLI flag parsing (--app, --why, --json, -y, …)
 │   │   └── destructive.py   # Confirmation prompts
 │   └── ui/

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

@@ -1,6 +1,6 @@
 [project]
 name = "hop3-cli"
-version = "0.5.0.dev3"
+version = "0.6.1"
 authors = [
     {name = "Stefane Fermigier", email = "sf@abilian.com"},
 ]
@@ -9,6 +9,7 @@ requires-python = "<4.0,>=3.10"
 dependencies = [
     # Configuration
     "toml<1.0.0,>=0.10.2",
+    "tomlkit>=0.13.0",  # comment-preserving TOML round-trip for hop3.toml edits
     # Communication
     "jsonrpcclient<5.0.0,>=4.0.3",
     "requests<3.0.0,>=2.32.3",

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

@@ -19,6 +19,7 @@ from .destructive import confirm_destructive_action, is_destructive_command
 from .flags import CliFlags, parse_flags
 from .help import (
     append_feedback_footer,
+    append_local_commands_full_help,
     emit_status_line,
     handle_help_flags,
     inject_local_commands_into_help,
@@ -36,6 +37,7 @@ __all__ = [
     "LOCAL_COMMANDS_INFO",
     "CliFlags",
     "append_feedback_footer",
+    "append_local_commands_full_help",
     "confirm_destructive_action",
     "emit_status_line",
     "generate_archive",