octopize.deploy_tool 3.2.0__tar.gz → 3.4.0__tar.gz

{octopize_deploy_tool-3.2.0 → octopize_deploy_tool-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: octopize.deploy_tool
-Version: 3.2.0
+Version: 3.4.0
 Summary: Deployment configuration tool for Octopize Avatar platform
 Project-URL: Homepage, https://octopize.io
 Project-URL: Documentation, https://docs.octopize.io/docs/deploying/self-hosted/self_installation
@@ -96,21 +96,30 @@ to be up, and `provision-admin` must run before `verify`. Both hold once `start`
 
 ## Command reference
 
-`--app-root` defaults to the current directory everywhere it is accepted. Every command takes
-`--verbosity {1,2}` (`2` is verbose) except `tasks create-self-signed-cert`. The older
-`--verbose` flag is deprecated in favour of `--verbosity 2` and is unavailable on `verify` and on
-all `tasks` sub-commands. Every command's `--help` lists its full option set.
+`--app-root` defaults to the current directory everywhere it is accepted, and must be a directory
+the invoking user can read, write and enter — every command refuses a root-owned or otherwise
+inaccessible root up front rather than failing part-way through. It does not have to exist yet, as
+long as its parent is writable. Every command and `tasks` sub-command takes `--verbosity {1,2}`,
+where `1` is essential (the default) and `2` is verbose. Every command's `--help` lists its full
+option set.
 
 ### Everyday commands
 
-| Command     | Use when                                                                    |
-| ----------- | --------------------------------------------------------------------------- |
-| `install`   | Setting up a new Avatar deployment for the first time                       |
-| `update`    | Upgrading to a newer Avatar release, or changing a configuration value      |
-| `start`     | Bringing a configured deployment live, or restarting it after a host reboot |
-| `stop`      | Suspending the stack temporarily — containers and volumes are preserved     |
-| `uninstall` | Permanently destroying the deployment and all of its data                   |
-| `migrate`   | Importing a deployment created by hand or by an older version of this tool  |
+Which of `install`, `update` and `migrate` you need is decided by what your deployment
+directory already contains, so the table names that rather than a term only this tool uses:
+
+| Command     | Use when                                                                                                                                                                             |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `install`   | Setting up a new Avatar deployment for the first time, in an empty directory                                                                                                         |
+| `update`    | Upgrading to a newer Avatar release, or changing a configuration value, on a deployment that already has a `.deployment_states/` directory                                           |
+| `migrate`   | Adopting a deployment that has `.env` and `.secrets/` at its top level and no `.deployment_states/` — anything set up by hand, or by the `deploy` command of a tool older than 2.7.0 |
+| `start`     | Bringing a configured deployment live, or restarting it after a host reboot                                                                                                          |
+| `stop`      | Suspending the stack temporarily — containers and volumes are preserved                                                                                                              |
+| `uninstall` | Permanently destroying the deployment and all of its data                                                                                                                            |
+
+If you point `update` or `install` at a directory of the second shape they stop and tell you to
+run `migrate` — running `install` there would generate a fresh configuration instead of adopting
+the one you already have.
 
 #### `install`
 
@@ -124,7 +133,22 @@ start. It starts nothing — run `start` afterwards.
 --verbosity {1,2}      1 = essential (default), 2 = verbose
 ```
 
-Before doing anything, `install` looks for Avatar Docker volumes left over from an earlier
+Before doing anything, `install` checks the app root itself. If it holds `.env` and `.secrets/`
+at the top level and no `.deployment_states/`, that is a deployment predating the versioned
+layout, and installing over it would generate a fresh configuration rather than adopt it, so the
+run stops:
+
+```text
+✗ /app/avatar looks like a pre-versioned deployment (.env and .secrets/ at the top level, no
+  .deployment_states/). Import it once with:
+
+      octopize-deploy-tool migrate --app-root <new-app-root> --from-legacy /app/avatar
+
+  then use 'update' for subsequent releases.
+⚠ Install aborted during pre-flight checks.
+```
+
+Next, `install` looks for Avatar Docker volumes left over from an earlier
 deployment. If it finds any it refuses to run, in both interactive and non-interactive mode:
 
 ```text
@@ -152,7 +176,9 @@ Re-runs the configuration from your current state, re-renders every file with th
 bundled in the installed version of this tool, shows a diff, and applies it. Values you already
 answered are carried forward, so you are not asked again. `--from-config PATH` layers a YAML file
 over the current state (see [Changing a configuration
-value](#changing-a-configuration-value)).
+value](#changing-a-configuration-value)). It needs a `.deployment_states/` directory to read that
+state from; against a directory that has `.env` and `.secrets/` at the top level instead, it stops
+and points you at `migrate`.
 
 ```bash
 octopize-deploy-tool update --app-root ./app/avatar
@@ -177,6 +203,34 @@ Merge your edits into the rendered copy in `.deployment_states/<vX>/generated/`,
 `apply --version <vX>`. Anything that should survive future updates belongs in a config file, not
 in `generated_files/`.
 
+Two files never come from a render, so `apply` carries them across untouched rather than
+replacing them with the copy: the API key and the two JWTs that `tasks provision-admin` writes to
+`generated_files/.secrets/avatar_api_key`, `avatar_access_token` and `avatar_refresh_token`.
+Anything else you leave in `generated_files/` is replaced.
+
+#### Python client compatibility
+
+`install`, `update` and `migrate` each deploy a specific Avatar API version, and no single python
+client works with every one of them — so an update can break the notebooks and scripts your users
+already have. Each of those commands ends by naming the clients that work with the version it just
+deployed:
+
+```text
+Python client compatibility
+  This deployment now runs Avatar API 3.2.3.
+  Latest compatible python client: 1.28.0   (pip install 'octopize.avatar==1.28.0')
+  Clients older than 1.26.0 will stop working — tell your users before they next run a job.
+```
+
+When an `update` does not move the API version at all — a tool-only bump — this collapses to a
+single reassuring line instead.
+
+The table is fetched from `COMPATIBILITY_MAPPING_URL` (see
+[`config.example.yaml`](#changing-a-configuration-value); point it at your own mirror if you are
+air-gapped). This is advisory output: if the URL cannot be reached the command warns once and
+carries on — a deployment never fails because a version table was unavailable. To check
+compatibility as a hard gate, use `verify`.
+
 #### `start` and `stop`
 
 `start` creates any missing Docker volumes and brings all services up. It is idempotent, so it is
@@ -200,21 +254,47 @@ octopize-deploy-tool uninstall --app-root ./app/avatar
 
 #### `migrate`
 
-Imports a deployment set up manually or with an older version of this tool. Point
-`--from-legacy` at the directory holding the existing `.env` and `.secrets/`; values readable
-from there are carried over and you are prompted for the rest. If `--from-legacy` is omitted the
-tool asks for it interactively.
+Adopts a deployment whose directory holds `.env` and `.secrets/` at the top level and has no
+`.deployment_states/` — anything set up by hand, or by the `deploy` command of a tool older than
+2.7.0. Point `--from-legacy` at that directory; values readable from there are carried over and
+you are prompted for the rest. If `--from-legacy` is omitted the tool asks for it interactively.
 
 ```bash
 octopize-deploy-tool migrate --app-root ./app/avatar-new --from-legacy ./app/avatar-old
 octopize-deploy-tool start   --app-root ./app/avatar-new
 ```
 
-> **Before migrating non-interactively**, make sure the legacy `.env` sets
+Before applying anything, `migrate` shows you the diff between your existing directory and the new
+render, led by the service versions that change:
+
+```text
+Service versions (5 changing):
+  AVATAR_API_VERSION           2.55.0  → 3.2.3
+  AVATAR_PDFGENERATOR_VERSION  0.2.0   → (removed)
+  AVATAR_WEB_VERSION           0.38.0  → 0.65.1
+```
+
+Expect a large first diff — the layout itself changes, `pdfgenerator` goes away (the report
+generator is now embedded in the API), and the services jump every release at once. Conflicts
+default to accepting the new render, since the legacy directory is what `migrate` replaces;
+answering "keep" for a file is still honoured and still blocks the apply.
+
+`migrate` also creates `user_config/` under the new app root, so a migrated deployment is shaped
+exactly like an installed one and `update --from-config` works the same way on both.
+
+> **Before migrating non-interactively**, make sure the legacy `.env` sets `SMTP_HOST` (or pass
+> `USE_AWS_SMTP_PRESET: true`), and sets
 > `NGINX_SSL_CERTIFICATE_PATH` and `NGINX_SSL_CERTIFICATE_KEY_PATH` to paths that exist.
-> Otherwise the run falls back to a relative built-in default and fails with
-> `Invalid default value for 'NGINX_SSL_CERTIFICATE_PATH'`, and `--non-interactive` offers no way
-> to supply one.
+> Otherwise the run falls back to a relative built-in default and keeps it with a warning that
+> the path is "not usable yet" — the migration completes, but nginx will not start until a
+> certificate and key exist at those paths, and `--non-interactive` offers no way to supply one.
+> A path _you_ set that does not exist is a hard error instead.
+>
+> A relative path in that `.env` — `./tls/server.fullchain.crt` — is read relative to the
+> `--from-legacy` directory it was written for, whichever directory you run `migrate` from, and is
+> recorded as an absolute path in the new deployment. The exception is running the tool from the
+> Docker image, where those paths belong to the host and are recorded exactly as written; see
+> [Running via Docker](#running-via-docker).
 
 See [Upgrading from a pre-SSO deployment](#upgrading-from-a-pre-sso-deployment) for what happens
 to existing user accounts.
@@ -349,6 +429,9 @@ Two things the example does not tell you:
 - **`ORGANIZATION_NAME` is missing from it** and is required. A `--non-interactive` run without it
   stops at `ORGANIZATION_NAME is required but not provided in configuration file`. Add it
   yourself, as below.
+- **`SMTP_HOST` is required too**, unless you set `USE_AWS_SMTP_PRESET: true` to take the AWS SES
+  settings Octopize provides. The example sets it; a `--non-interactive` run with neither stops at
+  `'SMTP_HOST' is required and no value was provided`.
 - **The TLS keys the tool reads are `NGINX_SSL_CERTIFICATE_PATH` and
   `NGINX_SSL_CERTIFICATE_KEY_PATH`.** Use those spellings.
 
@@ -515,8 +598,11 @@ Notes:
 
 Older Avatar deployments kept users in the Avatar API database. `migrate` records that they still
 need importing into Authentik, and **the first `start` after a `migrate` offers to do it for
-you**: it previews every operation, asks for confirmation, and runs the import. Nothing has to be
-run by hand.
+you**: it asks `Run it now?` and runs the import. Nothing has to be run by hand.
+
+Add `--verbosity 2` to review before committing: the plan — every group and every user the import
+would create — is printed, and a second prompt asks whether to go ahead with it. At the default
+`--verbosity 1` nothing is printed beforehand, so `Run it now?` is the only question asked.
 
 If you decline, the same import is available later:
 
@@ -527,8 +613,10 @@ octopize-deploy-tool tasks authentik-migrate --from-docker --app-root ./app/avat
 `--from-docker` reads users, organizations and licenses straight from the running api container's
 database, so there is no CSV export to produce; **the extracted data is held in memory and never
 written to disk**. The Authentik URL and token come from `generated_files/.env`. `--dry-run`
-previews without changing anything. Users that already carry an `authentik_id` are skipped, so the
-import is safe to re-run.
+prints the plan — every group and every user that would be created — and writes nothing to
+Authentik (with `--from-docker` it still brings the stack up to read the database); a real run
+prints that plan only under `--verbosity 2`. Users that already carry an `authentik_id` are
+skipped, so the import is safe to re-run.
 
 Every run that is not a `--dry-run` does write an operation log — `migration_log.jsonl` unless
 `--log PATH` says otherwise — recording what was attempted and how it ended.

{octopize_deploy_tool-3.2.0 → octopize_deploy_tool-3.4.0}/README.md

@@ -63,21 +63,30 @@ to be up, and `provision-admin` must run before `verify`. Both hold once `start`
 
 ## Command reference
 
-`--app-root` defaults to the current directory everywhere it is accepted. Every command takes
-`--verbosity {1,2}` (`2` is verbose) except `tasks create-self-signed-cert`. The older
-`--verbose` flag is deprecated in favour of `--verbosity 2` and is unavailable on `verify` and on
-all `tasks` sub-commands. Every command's `--help` lists its full option set.
+`--app-root` defaults to the current directory everywhere it is accepted, and must be a directory
+the invoking user can read, write and enter — every command refuses a root-owned or otherwise
+inaccessible root up front rather than failing part-way through. It does not have to exist yet, as
+long as its parent is writable. Every command and `tasks` sub-command takes `--verbosity {1,2}`,
+where `1` is essential (the default) and `2` is verbose. Every command's `--help` lists its full
+option set.
 
 ### Everyday commands
 
-| Command     | Use when                                                                    |
-| ----------- | --------------------------------------------------------------------------- |
-| `install`   | Setting up a new Avatar deployment for the first time                       |
-| `update`    | Upgrading to a newer Avatar release, or changing a configuration value      |
-| `start`     | Bringing a configured deployment live, or restarting it after a host reboot |
-| `stop`      | Suspending the stack temporarily — containers and volumes are preserved     |
-| `uninstall` | Permanently destroying the deployment and all of its data                   |
-| `migrate`   | Importing a deployment created by hand or by an older version of this tool  |
+Which of `install`, `update` and `migrate` you need is decided by what your deployment
+directory already contains, so the table names that rather than a term only this tool uses:
+
+| Command     | Use when                                                                                                                                                                             |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `install`   | Setting up a new Avatar deployment for the first time, in an empty directory                                                                                                         |
+| `update`    | Upgrading to a newer Avatar release, or changing a configuration value, on a deployment that already has a `.deployment_states/` directory                                           |
+| `migrate`   | Adopting a deployment that has `.env` and `.secrets/` at its top level and no `.deployment_states/` — anything set up by hand, or by the `deploy` command of a tool older than 2.7.0 |
+| `start`     | Bringing a configured deployment live, or restarting it after a host reboot                                                                                                          |
+| `stop`      | Suspending the stack temporarily — containers and volumes are preserved                                                                                                              |
+| `uninstall` | Permanently destroying the deployment and all of its data                                                                                                                            |
+
+If you point `update` or `install` at a directory of the second shape they stop and tell you to
+run `migrate` — running `install` there would generate a fresh configuration instead of adopting
+the one you already have.
 
 #### `install`
 
@@ -91,7 +100,22 @@ start. It starts nothing — run `start` afterwards.
 --verbosity {1,2}      1 = essential (default), 2 = verbose
 ```
 
-Before doing anything, `install` looks for Avatar Docker volumes left over from an earlier
+Before doing anything, `install` checks the app root itself. If it holds `.env` and `.secrets/`
+at the top level and no `.deployment_states/`, that is a deployment predating the versioned
+layout, and installing over it would generate a fresh configuration rather than adopt it, so the
+run stops:
+
+```text
+✗ /app/avatar looks like a pre-versioned deployment (.env and .secrets/ at the top level, no
+  .deployment_states/). Import it once with:
+
+      octopize-deploy-tool migrate --app-root <new-app-root> --from-legacy /app/avatar
+
+  then use 'update' for subsequent releases.
+⚠ Install aborted during pre-flight checks.
+```
+
+Next, `install` looks for Avatar Docker volumes left over from an earlier
 deployment. If it finds any it refuses to run, in both interactive and non-interactive mode:
 
 ```text
@@ -119,7 +143,9 @@ Re-runs the configuration from your current state, re-renders every file with th
 bundled in the installed version of this tool, shows a diff, and applies it. Values you already
 answered are carried forward, so you are not asked again. `--from-config PATH` layers a YAML file
 over the current state (see [Changing a configuration
-value](#changing-a-configuration-value)).
+value](#changing-a-configuration-value)). It needs a `.deployment_states/` directory to read that
+state from; against a directory that has `.env` and `.secrets/` at the top level instead, it stops
+and points you at `migrate`.
 
 ```bash
 octopize-deploy-tool update --app-root ./app/avatar
@@ -144,6 +170,34 @@ Merge your edits into the rendered copy in `.deployment_states/<vX>/generated/`,
 `apply --version <vX>`. Anything that should survive future updates belongs in a config file, not
 in `generated_files/`.
 
+Two files never come from a render, so `apply` carries them across untouched rather than
+replacing them with the copy: the API key and the two JWTs that `tasks provision-admin` writes to
+`generated_files/.secrets/avatar_api_key`, `avatar_access_token` and `avatar_refresh_token`.
+Anything else you leave in `generated_files/` is replaced.
+
+#### Python client compatibility
+
+`install`, `update` and `migrate` each deploy a specific Avatar API version, and no single python
+client works with every one of them — so an update can break the notebooks and scripts your users
+already have. Each of those commands ends by naming the clients that work with the version it just
+deployed:
+
+```text
+Python client compatibility
+  This deployment now runs Avatar API 3.2.3.
+  Latest compatible python client: 1.28.0   (pip install 'octopize.avatar==1.28.0')
+  Clients older than 1.26.0 will stop working — tell your users before they next run a job.
+```
+
+When an `update` does not move the API version at all — a tool-only bump — this collapses to a
+single reassuring line instead.
+
+The table is fetched from `COMPATIBILITY_MAPPING_URL` (see
+[`config.example.yaml`](#changing-a-configuration-value); point it at your own mirror if you are
+air-gapped). This is advisory output: if the URL cannot be reached the command warns once and
+carries on — a deployment never fails because a version table was unavailable. To check
+compatibility as a hard gate, use `verify`.
+
 #### `start` and `stop`
 
 `start` creates any missing Docker volumes and brings all services up. It is idempotent, so it is
@@ -167,21 +221,47 @@ octopize-deploy-tool uninstall --app-root ./app/avatar
 
 #### `migrate`
 
-Imports a deployment set up manually or with an older version of this tool. Point
-`--from-legacy` at the directory holding the existing `.env` and `.secrets/`; values readable
-from there are carried over and you are prompted for the rest. If `--from-legacy` is omitted the
-tool asks for it interactively.
+Adopts a deployment whose directory holds `.env` and `.secrets/` at the top level and has no
+`.deployment_states/` — anything set up by hand, or by the `deploy` command of a tool older than
+2.7.0. Point `--from-legacy` at that directory; values readable from there are carried over and
+you are prompted for the rest. If `--from-legacy` is omitted the tool asks for it interactively.
 
 ```bash
 octopize-deploy-tool migrate --app-root ./app/avatar-new --from-legacy ./app/avatar-old
 octopize-deploy-tool start   --app-root ./app/avatar-new
 ```
 
-> **Before migrating non-interactively**, make sure the legacy `.env` sets
+Before applying anything, `migrate` shows you the diff between your existing directory and the new
+render, led by the service versions that change:
+
+```text
+Service versions (5 changing):
+  AVATAR_API_VERSION           2.55.0  → 3.2.3
+  AVATAR_PDFGENERATOR_VERSION  0.2.0   → (removed)
+  AVATAR_WEB_VERSION           0.38.0  → 0.65.1
+```
+
+Expect a large first diff — the layout itself changes, `pdfgenerator` goes away (the report
+generator is now embedded in the API), and the services jump every release at once. Conflicts
+default to accepting the new render, since the legacy directory is what `migrate` replaces;
+answering "keep" for a file is still honoured and still blocks the apply.
+
+`migrate` also creates `user_config/` under the new app root, so a migrated deployment is shaped
+exactly like an installed one and `update --from-config` works the same way on both.
+
+> **Before migrating non-interactively**, make sure the legacy `.env` sets `SMTP_HOST` (or pass
+> `USE_AWS_SMTP_PRESET: true`), and sets
 > `NGINX_SSL_CERTIFICATE_PATH` and `NGINX_SSL_CERTIFICATE_KEY_PATH` to paths that exist.
-> Otherwise the run falls back to a relative built-in default and fails with
-> `Invalid default value for 'NGINX_SSL_CERTIFICATE_PATH'`, and `--non-interactive` offers no way
-> to supply one.
+> Otherwise the run falls back to a relative built-in default and keeps it with a warning that
+> the path is "not usable yet" — the migration completes, but nginx will not start until a
+> certificate and key exist at those paths, and `--non-interactive` offers no way to supply one.
+> A path _you_ set that does not exist is a hard error instead.
+>
+> A relative path in that `.env` — `./tls/server.fullchain.crt` — is read relative to the
+> `--from-legacy` directory it was written for, whichever directory you run `migrate` from, and is
+> recorded as an absolute path in the new deployment. The exception is running the tool from the
+> Docker image, where those paths belong to the host and are recorded exactly as written; see
+> [Running via Docker](#running-via-docker).
 
 See [Upgrading from a pre-SSO deployment](#upgrading-from-a-pre-sso-deployment) for what happens
 to existing user accounts.
@@ -316,6 +396,9 @@ Two things the example does not tell you:
 - **`ORGANIZATION_NAME` is missing from it** and is required. A `--non-interactive` run without it
   stops at `ORGANIZATION_NAME is required but not provided in configuration file`. Add it
   yourself, as below.
+- **`SMTP_HOST` is required too**, unless you set `USE_AWS_SMTP_PRESET: true` to take the AWS SES
+  settings Octopize provides. The example sets it; a `--non-interactive` run with neither stops at
+  `'SMTP_HOST' is required and no value was provided`.
 - **The TLS keys the tool reads are `NGINX_SSL_CERTIFICATE_PATH` and
   `NGINX_SSL_CERTIFICATE_KEY_PATH`.** Use those spellings.
 
@@ -482,8 +565,11 @@ Notes:
 
 Older Avatar deployments kept users in the Avatar API database. `migrate` records that they still
 need importing into Authentik, and **the first `start` after a `migrate` offers to do it for
-you**: it previews every operation, asks for confirmation, and runs the import. Nothing has to be
-run by hand.
+you**: it asks `Run it now?` and runs the import. Nothing has to be run by hand.
+
+Add `--verbosity 2` to review before committing: the plan — every group and every user the import
+would create — is printed, and a second prompt asks whether to go ahead with it. At the default
+`--verbosity 1` nothing is printed beforehand, so `Run it now?` is the only question asked.
 
 If you decline, the same import is available later:
 
@@ -494,8 +580,10 @@ octopize-deploy-tool tasks authentik-migrate --from-docker --app-root ./app/avat
 `--from-docker` reads users, organizations and licenses straight from the running api container's
 database, so there is no CSV export to produce; **the extracted data is held in memory and never
 written to disk**. The Authentik URL and token come from `generated_files/.env`. `--dry-run`
-previews without changing anything. Users that already carry an `authentik_id` are skipped, so the
-import is safe to re-run.
+prints the plan — every group and every user that would be created — and writes nothing to
+Authentik (with `--from-docker` it still brings the stack up to read the database); a real run
+prints that plan only under `--verbosity 2`. Users that already carry an `authentik_id` are
+skipped, so the import is safe to re-run.
 
 Every run that is not a `--dry-run` does write an operation log — `migration_log.jsonl` unless
 `--log PATH` says otherwise — recording what was attempted and how it ended.

{octopize_deploy_tool-3.2.0 → octopize_deploy_tool-3.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "octopize.deploy_tool"
-version = "3.2.0"
+version = "3.4.0"
 description = "Deployment configuration tool for Octopize Avatar platform"
 readme = "README.md"
 requires-python = ">=3.13"

{octopize_deploy_tool-3.2.0 → octopize_deploy_tool-3.4.0}/src/octopize_avatar_deploy/__init__.py

@@ -9,7 +9,7 @@ from .version_compat import (
     validate_template_version,
 )
 
-__version__ = "3.2.0"
+__version__ = "3.4.0"
 __all__ = [
     "SCRIPT_VERSION",
     "ConsolePrinter",

octopize_deploy_tool-3.4.0/src/octopize_avatar_deploy/app_root.py

@@ -0,0 +1,123 @@
+"""Validation of the deployment root supplied on the command line.
+
+Every command reads and writes under ``--app-root``: the versioned state
+documents, the rendered versions, ``generated_files/``, the secrets. A path the
+invoking user cannot enter, read or write is a dead end, and the failure
+otherwise surfaces deep inside a command as a bare ``PermissionError`` on some
+individual file — after secrets have already been generated. Checking it at the
+CLI boundary turns that into one actionable message before any work starts.
+
+Write access is only demanded of the commands that write: a deployment root left
+read-only can still be stopped, diffed and verified.
+"""
+
+from __future__ import annotations
+
+import getpass
+import os
+from pathlib import Path
+
+from octopize_avatar_deploy.application._guards import CommandError
+
+_EXAMPLE_ROOT = "./app/avatar"
+
+
+class AppRootError(CommandError):
+    """Raised when the deployment root cannot be used by the current user."""
+
+
+def validate_app_root(app_root: Path, *, require_write: bool = True) -> Path:
+    """Return *app_root* with ``~`` expanded, once it is usable by this user.
+
+    A root that does not exist yet is fine — commands create it — provided the
+    nearest existing ancestor is a directory this user can write into.
+
+    Args:
+        app_root: The path the operator passed to ``--app-root``.
+        require_write: Whether this command writes under the root.
+
+    Raises:
+        AppRootError: If the path (or the directory it would be created in) is
+            not a directory, or lacks the access this command needs.
+
+    """
+    expanded = app_root.expanduser()
+
+    if expanded.is_symlink() and not expanded.exists():
+        raise AppRootError(
+            f"{expanded} is a broken symlink. Point --app-root at a real directory, "
+            f"e.g. {_EXAMPLE_ROOT}."
+        )
+
+    target = expanded
+    while not target.exists():
+        parent = target.parent
+        if parent == target:
+            break
+        target = parent
+
+    if not target.is_dir():
+        raise AppRootError(
+            f"{target} is not a directory. Point --app-root at a directory you own, "
+            f"e.g. {_EXAMPLE_ROOT}."
+        )
+
+    missing = [
+        label for mode, label in _required_access(require_write) if not os.access(target, mode)
+    ]
+    if not missing:
+        return expanded
+
+    user = _current_user()
+    owner = _owner(target)
+    subject = (
+        f"Deployment root {expanded}"
+        if target == expanded
+        else f"{expanded} cannot be created: {target}"
+    )
+    raise AppRootError(
+        f"{subject} is not {_join(missing)} by user {user!r} (owner: {owner!r}).\n"
+        f"Point --app-root at a directory your user owns, e.g. {_EXAMPLE_ROOT}, or fix "
+        f"this one:\n  {_remedy(target, expanded, user, owner)}"
+    )
+
+
+def _required_access(require_write: bool) -> list[tuple[int, str]]:
+    """The access modes the command needs, each paired with how to name it."""
+    if require_write:
+        return [(os.R_OK, "readable"), (os.W_OK, "writable"), (os.X_OK, "traversable")]
+    return [(os.R_OK, "readable"), (os.X_OK, "traversable")]
+
+
+def _remedy(target: Path, expanded: Path, user: str, owner: str) -> str:
+    """The one command that gets this user the access they are missing."""
+    if owner == user:
+        # Already theirs, so the mode bits are what stand in the way.
+        return f"chmod u+rwx {target}"
+    if target == expanded:
+        return f"sudo chown -R {user} {target}"
+    return f"sudo install -d -o {user} {expanded}"
+
+
+def _join(labels: list[str]) -> str:
+    if len(labels) == 1:
+        return labels[0]
+    return f"{', '.join(labels[:-1])} or {labels[-1]}"
+
+
+def _current_user() -> str:
+    try:
+        return getpass.getuser()
+    except OSError:
+        return f"uid {os.getuid()}"
+
+
+def _owner(path: Path) -> str:
+    try:
+        return path.owner()
+    except (KeyError, NotImplementedError, OSError):
+        pass
+    try:
+        return f"uid {path.stat().st_uid}"
+    except OSError:
+        return "unknown"

{octopize_deploy_tool-3.2.0 → octopize_deploy_tool-3.4.0}/src/octopize_avatar_deploy/application/apply_command.py

@@ -17,6 +17,10 @@ from pathlib import Path
 from octopize_avatar_deploy.application._guards import CommandError, run_guarded
 from octopize_avatar_deploy.application.deployment_markers import DeploymentMarker
 from octopize_avatar_deploy.application.deployment_paths import DeploymentPaths
+from octopize_avatar_deploy.application.operator_owned_files import (
+    capture_operator_owned_files,
+    restore_operator_owned_files,
+)
 from octopize_avatar_deploy.application.ports import DirectoryCopier, FileWriter, SymlinkUpdater
 from octopize_avatar_deploy.application.secret_files import relax_deployed_secrets
 from octopize_avatar_deploy.domain.version_id import VersionId
@@ -75,8 +79,9 @@ class ApplyCommand:
             versioned ``generated/`` directory to ``generated_files/``.
         symlink_updater: Port that creates or replaces the
             ``currently_deployed`` symlink.
-        file_writer: Port used to write the marker files requested via
-            ``args.markers``.
+        file_writer: Port used to carry the operator-owned files across the copy
+            (see :mod:`~application.operator_owned_files`) and to write the
+            marker files requested via ``args.markers``.
 
     """
 
@@ -100,12 +105,15 @@ class ApplyCommand:
         2. Parse the target version label.
         3. Confirm that ``render`` has been run for this version (the
            ``generated/`` directory exists).
-        4. Copy ``.deployment_states/vX/generated/`` → ``generated_files/``
+        4. Read the operator-owned files under ``generated_files/`` that no
+           version slot contains (see :mod:`~application.operator_owned_files`).
+        5. Copy ``.deployment_states/vX/generated/`` → ``generated_files/``
            (full recursive copy — not a symlink — so operator edits in
-           ``generated_files/`` never affect the versioned reference).
-        5. Update ``.deployment_states/currently_deployed`` symlink → ``vX``.
-        6. Write the requested marker files, if any.
-        7. Return a result.
+           ``generated_files/`` never affect the versioned reference), then
+           write the operator-owned files back.
+        6. Update ``.deployment_states/currently_deployed`` symlink → ``vX``.
+        7. Write the requested marker files, if any.
+        8. Return a result.
 
         Args:
             args: Apply command arguments.
@@ -135,15 +143,22 @@ class ApplyCommand:
                 f"Run 'render --version {version.label}' first."
             )
 
-        # 3. Copy generated/ → generated_files/.
+        # 3. Read the files no version slot contains, so the copy cannot destroy
+        #    them (see application.operator_owned_files).
+        preserved = capture_operator_owned_files(self._file_writer, paths.generated_files_dir)
+
+        # 4. Copy generated/ → generated_files/, then put those files back.
         self._directory_copier.copy(paths.generated_dir, paths.generated_files_dir)
+        restore_operator_owned_files(self._file_writer, paths.generated_files_dir, preserved)
         # Relax deployed secrets so Docker Compose can read them as the container UID.
         relax_deployed_secrets(self._directory_copier, paths.generated_files_dir)
 
-        # 4. Update currently_deployed symlink.
+        # 5. Update currently_deployed symlink.
         self._symlink_updater.update_symlink(paths.currently_deployed_symlink, paths.version_dir)
 
-        # 5. Write the markers handed to `start`, opt-in only (see docs/adr/0002).
+        # 6. Write the markers handed to `start`, opt-in only (see docs/adr/0002).
+        # After the copy, like the operator-owned files above and for the same
+        # reason: the copy would otherwise wipe them.
         if args.markers:
             self._file_writer.write(
                 paths.generated_files_dir, {marker.value: b"" for marker in args.markers}