octopize.deploy_tool 3.2.0__tar.gz → 3.3.0__tar.gz

{octopize_deploy_tool-3.2.0 → octopize_deploy_tool-3.3.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.3.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,27 @@ 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. 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 +130,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 +173,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 +200,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 +251,46 @@ 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 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
 > `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.
@@ -515,8 +591,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 +606,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.3.0}/README.md

@@ -63,21 +63,27 @@ 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. 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 +97,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 +140,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 +167,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 +218,46 @@ 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 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
 > `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.
@@ -482,8 +558,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 +573,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.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "octopize.deploy_tool"
-version = "3.2.0"
+version = "3.3.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.3.0}/src/octopize_avatar_deploy/__init__.py

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

{octopize_deploy_tool-3.2.0 → octopize_deploy_tool-3.3.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}

{octopize_deploy_tool-3.2.0 → octopize_deploy_tool-3.3.0}/src/octopize_avatar_deploy/application/checks.py

@@ -22,6 +22,13 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Literal, Protocol
 
+from octopize_avatar_deploy.application.legacy_layout import (
+    PathProbe,
+    deployed_working_copy_message,
+    is_deployed_working_copy,
+    is_legacy_layout,
+    legacy_layout_message,
+)
 from octopize_avatar_deploy.application.ports import (
     DeploymentStateRepository,
     DockerClient,
@@ -85,6 +92,68 @@ class Check(Protocol):
         ...
 
 
+# ---------------------------------------------------------------------------
+# LegacyLayoutCheck
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class LegacyLayoutCheckResult:
+    """Result of the pre-versioned layout pre-flight check.
+
+    Attributes:
+        aborted: ``True`` if *app_root* holds a pre-versioned deployment, which
+            ``install`` must never write over.
+
+    """
+
+    aborted: bool
+
+
+class LegacyLayoutCheck:
+    """Refuse to install over a directory that is already somebody's deployment.
+
+    Two shapes are refused.  A pre-versioned deployment, where ``install``
+    would generate a fresh configuration rather than adopt the existing one, is
+    pointed at ``migrate --from-legacy``.  A modern deployment's own
+    ``generated_files/`` — which has the same flat shape and is where operators
+    spend their time, since it holds ``docker-compose.yml`` — is pointed one
+    level up at its real root.  Runs before :class:`VolumeCheck` so the
+    directory the operator can see is reported before the Docker state.
+
+    Args:
+        path_probe: Port answering :meth:`exists` (the ``Filesystem`` adapter in
+            production, a stub in tests).
+        printer: Port for error output.
+
+    """
+
+    def __init__(self, path_probe: PathProbe, printer: Printer) -> None:
+        self._path_probe = path_probe
+        self._printer = printer
+
+    def run(self, app_root: Path) -> LegacyLayoutCheckResult:
+        """Abort when *app_root* is a legacy flat deployment.
+
+        Args:
+            app_root: Operator's working directory (the deployment root).
+
+        Returns:
+            :class:`LegacyLayoutCheckResult` with the abort flag set when the
+            directory must be migrated rather than installed over.
+
+        """
+        if is_deployed_working_copy(self._path_probe, app_root):
+            self._printer.print_error(deployed_working_copy_message(app_root))
+            return LegacyLayoutCheckResult(aborted=True)
+
+        if not is_legacy_layout(self._path_probe, app_root):
+            return LegacyLayoutCheckResult(aborted=False)
+
+        self._printer.print_error(legacy_layout_message(app_root))
+        return LegacyLayoutCheckResult(aborted=True)
+
+
 # ---------------------------------------------------------------------------
 # VolumeCheck
 # ---------------------------------------------------------------------------