dsh-env-manager-plugin 0.1.0 → 0.1.2

package/docs/01-architecture/decisions/ADR-0010-environment-plane-model.md

@@ -1,87 +1,87 @@
-# ADR-0010: Environment as one network, planes as role views
-
-- **Status:** Accepted
-- **Date:** 2026-11-01
-- **Supersedes:** the one-step "environment + first host + password" creation flow
-  described in earlier V1 UI notes
-
-## Context
-
-Operators describe an environment as a complete network set: management nodes, business
-nodes, database nodes (sometimes many), expansion nodes, and 1–100 IPs. They need to work
-one network at a time and switch between planes inside it.
-
-The original V1 panel treated the environment as a flat list of hosts plus accounts, and
-its **New environment** form created the environment, first host, account and SSH endpoint
-in one save. That mixed three concerns (network identity, node topology, credentials),
-made every new environment inherit a node it might not need, and hid the plane structure
-inside a generic host table.
-
-Two alternatives were considered:
-
-1. **A separate environment per plane.** Easy filtering, but duplicates the network,
-   breaks shared nodes and forces the operator to maintain several YAML documents for one
-   network.
-2. **One environment with a flat host list.** Already supported by the schema, but the UI
-   had no way to work plane-by-plane, so it did not match the operator's mental model.
-
-## Decision
-
-1. **One environment = one complete network = one YAML document = one configuration
-   page.** Management, business, database and expansion are **logical roles**, not
-   separate environments.
-2. **Planes are views over the same `Environment.hosts[]`.** The detail page renders one
-   tab per declared role by filtering `hosts[]`. A node serving two planes is one `Host`
-   with two role ids and appears in both tabs; it is never copied per plane.
-3. **`New environment` creates only the shell.** The form collects name, optional id,
-   category and description, seeds the four standard roles (`management`, `business`,
-   `database`, `extension`) and creates empty `hosts`, `clusters`, `endpoints` and
-   `loginRecords`. Nodes are added inside the environment.
-4. **Roles are mandatory where they carry meaning.**
-   - `Environment.roles` must contain at least one entry.
-   - Every `Host.roles` must contain at least one entry.
-   - Every host role must reference a declared logical role.
-   - A plane with zero nodes is valid; a node with zero roles is not.
-5. **A node supports multiple roles.** Add/edit node uses role checkboxes; opening the form
-   from a plane preselects that role. Co-location is represented once.
-6. **Nodes are first-class in the panel.** Add/edit node, optional account creation,
-   expandable account tables, a shared search across id/name/IP/platform/admin/role, and
-   batch import in the form `IP,name,roles,port,user` (multiple roles separated by `|` or
-   `/`). Batch import never accepts passwords.
-7. **Credentials remain transient and namespaced.** The add/edit node form may collect a
-   login username and password; the password is sent once to `ctx.credentials.set`, the
-   record keeps `credentialRef` only. Shell creation and batch import collect no secrets.
-8. **Database topology is deferred.** Phase 1 treats `database` as a role and keeps
-   primary/replica/sharding detail in node notes. Modeling it now would add a schema the
-   rest of the UI does not consume.
-
-## Consequences
-
-Positive:
-
-- One network has one YAML document, one backup unit and one atomic write.
-- A shared management/business/database host is represented once, avoiding duplicate-IP
-  errors and split audit context.
-- The UI matches the operator's vocabulary: open the network, switch planes, add nodes.
-- New environments are cheap: four empty plane tabs are immediately usable.
-- Schema validation prevents a node from disappearing from every plane because it has no
-  role.
-
-Costs / limits:
-
-- Every plane view is a filter, so large environments need search and a future
-  virtualization strategy; V1 assumes up to a few hundred nodes.
-- Deleting a plane role would affect every node that references it; the panel currently
-  edits the role catalog through YAML, not a dedicated role editor.
-- Phase 1 cannot express primary/replica/sharding relationships, read/write split or
-  shard ranges; those remain Phase 2.
-- A node with no accounts is valid, but the panel shows `0 accounts` and no credential
-  reference until one is added.
-
-## Follow-up
-
-- Phase 2: database topology metadata and plane-aware expansion modeling.
-- Add row-level delete for nodes/accounts/login records and credential rotation.
-- Consider an optional JumpServer/PAM import adapter for accounts and login observations.
-- Keep `docs/01-architecture/data-model.md` §3 and `ui-design.md` §6.3 as the normative
-  references for this decision.
+# ADR-0010: Environment as one network, planes as role views
+
+- **Status:** Accepted
+- **Date:** 2026-11-01
+- **Supersedes:** the one-step "environment + first host + password" creation flow
+  described in earlier V1 UI notes
+
+## Context
+
+Operators describe an environment as a complete network set: management nodes, business
+nodes, database nodes (sometimes many), expansion nodes, and 1–100 IPs. They need to work
+one network at a time and switch between planes inside it.
+
+The original V1 panel treated the environment as a flat list of hosts plus accounts, and
+its **New environment** form created the environment, first host, account and SSH endpoint
+in one save. That mixed three concerns (network identity, node topology, credentials),
+made every new environment inherit a node it might not need, and hid the plane structure
+inside a generic host table.
+
+Two alternatives were considered:
+
+1. **A separate environment per plane.** Easy filtering, but duplicates the network,
+   breaks shared nodes and forces the operator to maintain several YAML documents for one
+   network.
+2. **One environment with a flat host list.** Already supported by the schema, but the UI
+   had no way to work plane-by-plane, so it did not match the operator's mental model.
+
+## Decision
+
+1. **One environment = one complete network = one YAML document = one configuration
+   page.** Management, business, database and expansion are **logical roles**, not
+   separate environments.
+2. **Planes are views over the same `Environment.hosts[]`.** The detail page renders one
+   tab per declared role by filtering `hosts[]`. A node serving two planes is one `Host`
+   with two role ids and appears in both tabs; it is never copied per plane.
+3. **`New environment` creates only the shell.** The form collects name, optional id,
+   category and description, seeds the four standard roles (`management`, `business`,
+   `database`, `extension`) and creates empty `hosts`, `clusters`, `endpoints` and
+   `loginRecords`. Nodes are added inside the environment.
+4. **Roles are mandatory where they carry meaning.**
+   - `Environment.roles` must contain at least one entry.
+   - Every `Host.roles` must contain at least one entry.
+   - Every host role must reference a declared logical role.
+   - A plane with zero nodes is valid; a node with zero roles is not.
+5. **A node supports multiple roles.** Add/edit node uses role checkboxes; opening the form
+   from a plane preselects that role. Co-location is represented once.
+6. **Nodes are first-class in the panel.** Add/edit node, optional account creation,
+   expandable account tables, a shared search across id/name/IP/platform/admin/role, and
+   batch import in the form `IP,name,roles,port,user` (multiple roles separated by `|` or
+   `/`). Batch import never accepts passwords.
+7. **Credentials remain transient and namespaced.** The add/edit node form may collect a
+   login username and password; the password is sent once to `ctx.credentials.set`, the
+   record keeps `credentialRef` only. Shell creation and batch import collect no secrets.
+8. **Database topology is deferred.** Phase 1 treats `database` as a role and keeps
+   primary/replica/sharding detail in node notes. Modeling it now would add a schema the
+   rest of the UI does not consume.
+
+## Consequences
+
+Positive:
+
+- One network has one YAML document, one backup unit and one atomic write.
+- A shared management/business/database host is represented once, avoiding duplicate-IP
+  errors and split audit context.
+- The UI matches the operator's vocabulary: open the network, switch planes, add nodes.
+- New environments are cheap: four empty plane tabs are immediately usable.
+- Schema validation prevents a node from disappearing from every plane because it has no
+  role.
+
+Costs / limits:
+
+- Every plane view is a filter, so large environments need search and a future
+  virtualization strategy; V1 assumes up to a few hundred nodes.
+- Deleting a plane role would affect every node that references it; the panel currently
+  edits the role catalog through YAML, not a dedicated role editor.
+- Phase 1 cannot express primary/replica/sharding relationships, read/write split or
+  shard ranges; those remain Phase 2.
+- A node with no accounts is valid, but the panel shows `0 accounts` and no credential
+  reference until one is added.
+
+## Follow-up
+
+- Phase 2: database topology metadata and plane-aware expansion modeling.
+- Add row-level delete for nodes/accounts/login records and credential rotation.
+- Consider an optional JumpServer/PAM import adapter for accounts and login observations.
+- Keep `docs/01-architecture/data-model.md` §3 and `ui-design.md` §6.3 as the normative
+  references for this decision.

package/docs/01-architecture/decisions/ADR-0011-k8s-node-execution-model.md

@@ -1,92 +1,92 @@
-# ADR-0011: Model Kubernetes nodes and Pod hosts as machines with command surfaces
-
-- **Status:** Accepted
-- **Date:** 2026-11-01
-- **Related:** ADR-0010 (environment plane model), ADR-0006 (credentials as references)
-
-## Context
-
-Operators use three Kubernetes-adjacent deployment shapes in the same business:
-
-1. **K8s all-in-one.** The control plane and a worker run on the same machine. Operators
-   can run `kubectl` there and, when the runtime is Docker, may also use `docker`.
-2. **K8s + Pod hosts.** A Kubernetes cluster exists, but business Pods run on separate
-   machines. Our team operates those machines with `docker exec`, not by treating each Pod
-   as an inventory node. Other departments use standard worker nodes in the same cluster.
-3. **Generic machines.** VMs and physical machines that are not Kubernetes nodes.
-
-The Phase 1 environment model had only generic `Host` records. It could store an IP and a
-role, but it could not say whether a node is an all-in-one control plane, a worker, or a
-Pod-hosting machine, nor whether operators reach it with SSH, `kubectl`, or `docker`.
-Adding a new logical plane was the wrong fix: a node's Kubernetes role is a property of the
-machine and its runtime, while planes remain management/business/database/extension views.
-
-## Decision
-
-1. **A node is a machine, not a Pod.** `Host` represents a VM, physical machine, Kubernetes
-   node or Pod-hosting machine. A Pod is a workload; it stays in the deployment model
-   (`location.kind: kubernetes`) and is not added to `hosts[]`.
-2. **Add `Host.kind`.** Allowed values:
-   - `vm`
-   - `physical`
-   - `k8s-all-in-one` — control plane and worker on the same machine
-   - `k8s-worker` — worker node in a cluster
-   - `pod-host` — machine running Pods, operated through `docker exec`
-
-   The schema defaults a missing value to `vm` so existing environment YAML remains
-   readable. The kind is a classification, not a new logical role.
-3. **Add `Host.access`.** Allowed values are `ssh`, `kubectl` and `docker`. This records the
-   command surfaces that exist on the machine. It is metadata, not an authorization grant
-   and not a credential. The registry stores no passwords, kubeconfigs or Docker
-   credentials; those remain behind `credentialRef`.
-4. **Add `Host.clusterRef`.** Kubernetes nodes and Pod hosts may reference a `Cluster` in
-   the same environment. `k8s-all-in-one` and `k8s-worker` require an existing cluster
-   reference; `pod-host` may omit it for a Docker-only machine outside the cluster.
-5. **Add `Cluster.topology`.** Allowed values are `all-in-one`, `separate` and `external`.
-   Topology is a descriptive cluster hint. Per-host `kind` remains authoritative; the schema
-   does not force a particular mix of node kinds while an environment is being migrated.
-6. **Keep access methods independent of kind.** A worker may have Docker; a VM may have
-   `kubectl`; an all-in-one node may have all three. The UI pre-fills defaults but never
-   hides an access method based on the kind.
-7. **Model the operational entry point, not the Pod.** A `pod-host` tells an operator that
-   the machine is reached with `docker exec`; it intentionally has no `podName` or
-   `containerName` field in V1. Adding Pod/container inventory is a separate future model.
-8. **Expose the model in the panel.** The node form has kind, cluster and access controls;
-   node cards show kind/access badges and cluster references; search covers kind, access and
-   cluster name/reference; the detail page has a Kubernetes/clusters tab for adding and
-   editing cluster metadata. Batch import still creates generic `vm`/`ssh` nodes and never
-   accepts secrets.
-
-## Consequences
-
-Positive:
-
-- The three deployment shapes operators actually use are representable without inventing a
-  Kubernetes plane or duplicating a machine per Pod.
-- The command surface is explicit, so a future execution skill can choose SSH, `kubectl` or
-  `docker exec` from declared metadata instead of guessing from the node name.
-- Cluster references and topology make the relationship between all-in-one, worker and Pod
-  hosts visible in one environment document.
-- Existing YAML remains valid: missing `kind` reads as `vm`, missing `access` is unknown,
-  and missing topology is displayed as `—`.
-
-Costs / limits:
-
-- `access` states what is available, not whether the current operator is allowed to use it.
-  Approval and execution policy remain outside this model.
-- The schema does not prove that a host really has `kubectl` or Docker, nor that a cluster's
-  topology matches its nodes. The values are operator-maintained facts.
-- A Pod host is still one record even when it runs many Pods; per-Pod inventory, container
-  ids and restart counts are out of scope for V1.
-- Batch import does not yet accept kind/access/cluster columns; those nodes are created as
-  generic VMs and must be edited, or imported through YAML.
-
-## Follow-up
-
-- Add a future Pod/container inventory only if operations need per-workload targeting; keep
-  it separate from `Host`.
-- Add batch-import columns for kind/access/cluster when bulk Kubernetes onboarding becomes a
-  real workflow.
-- Consider validating cluster topology consistency as a warning, not a hard error.
-- Keep `docs/01-architecture/data-model.md` §3.2 and `docs/01-architecture/ui-design.md`
-  synchronized with this decision.
+# ADR-0011: Model Kubernetes nodes and Pod hosts as machines with command surfaces
+
+- **Status:** Accepted
+- **Date:** 2026-11-01
+- **Related:** ADR-0010 (environment plane model), ADR-0006 (credentials as references)
+
+## Context
+
+Operators use three Kubernetes-adjacent deployment shapes in the same business:
+
+1. **K8s all-in-one.** The control plane and a worker run on the same machine. Operators
+   can run `kubectl` there and, when the runtime is Docker, may also use `docker`.
+2. **K8s + Pod hosts.** A Kubernetes cluster exists, but business Pods run on separate
+   machines. Our team operates those machines with `docker exec`, not by treating each Pod
+   as an inventory node. Other departments use standard worker nodes in the same cluster.
+3. **Generic machines.** VMs and physical machines that are not Kubernetes nodes.
+
+The Phase 1 environment model had only generic `Host` records. It could store an IP and a
+role, but it could not say whether a node is an all-in-one control plane, a worker, or a
+Pod-hosting machine, nor whether operators reach it with SSH, `kubectl`, or `docker`.
+Adding a new logical plane was the wrong fix: a node's Kubernetes role is a property of the
+machine and its runtime, while planes remain management/business/database/extension views.
+
+## Decision
+
+1. **A node is a machine, not a Pod.** `Host` represents a VM, physical machine, Kubernetes
+   node or Pod-hosting machine. A Pod is a workload; it stays in the deployment model
+   (`location.kind: kubernetes`) and is not added to `hosts[]`.
+2. **Add `Host.kind`.** Allowed values:
+   - `vm`
+   - `physical`
+   - `k8s-all-in-one` — control plane and worker on the same machine
+   - `k8s-worker` — worker node in a cluster
+   - `pod-host` — machine running Pods, operated through `docker exec`
+
+   The schema defaults a missing value to `vm` so existing environment YAML remains
+   readable. The kind is a classification, not a new logical role.
+3. **Add `Host.access`.** Allowed values are `ssh`, `kubectl` and `docker`. This records the
+   command surfaces that exist on the machine. It is metadata, not an authorization grant
+   and not a credential. The registry stores no passwords, kubeconfigs or Docker
+   credentials; those remain behind `credentialRef`.
+4. **Add `Host.clusterRef`.** Kubernetes nodes and Pod hosts may reference a `Cluster` in
+   the same environment. `k8s-all-in-one` and `k8s-worker` require an existing cluster
+   reference; `pod-host` may omit it for a Docker-only machine outside the cluster.
+5. **Add `Cluster.topology`.** Allowed values are `all-in-one`, `separate` and `external`.
+   Topology is a descriptive cluster hint. Per-host `kind` remains authoritative; the schema
+   does not force a particular mix of node kinds while an environment is being migrated.
+6. **Keep access methods independent of kind.** A worker may have Docker; a VM may have
+   `kubectl`; an all-in-one node may have all three. The UI pre-fills defaults but never
+   hides an access method based on the kind.
+7. **Model the operational entry point, not the Pod.** A `pod-host` tells an operator that
+   the machine is reached with `docker exec`; it intentionally has no `podName` or
+   `containerName` field in V1. Adding Pod/container inventory is a separate future model.
+8. **Expose the model in the panel.** The node form has kind, cluster and access controls;
+   node cards show kind/access badges and cluster references; search covers kind, access and
+   cluster name/reference; the detail page has a Kubernetes/clusters tab for adding and
+   editing cluster metadata. Batch import still creates generic `vm`/`ssh` nodes and never
+   accepts secrets.
+
+## Consequences
+
+Positive:
+
+- The three deployment shapes operators actually use are representable without inventing a
+  Kubernetes plane or duplicating a machine per Pod.
+- The command surface is explicit, so a future execution skill can choose SSH, `kubectl` or
+  `docker exec` from declared metadata instead of guessing from the node name.
+- Cluster references and topology make the relationship between all-in-one, worker and Pod
+  hosts visible in one environment document.
+- Existing YAML remains valid: missing `kind` reads as `vm`, missing `access` is unknown,
+  and missing topology is displayed as `—`.
+
+Costs / limits:
+
+- `access` states what is available, not whether the current operator is allowed to use it.
+  Approval and execution policy remain outside this model.
+- The schema does not prove that a host really has `kubectl` or Docker, nor that a cluster's
+  topology matches its nodes. The values are operator-maintained facts.
+- A Pod host is still one record even when it runs many Pods; per-Pod inventory, container
+  ids and restart counts are out of scope for V1.
+- Batch import does not yet accept kind/access/cluster columns; those nodes are created as
+  generic VMs and must be edited, or imported through YAML.
+
+## Follow-up
+
+- Add a future Pod/container inventory only if operations need per-workload targeting; keep
+  it separate from `Host`.
+- Add batch-import columns for kind/access/cluster when bulk Kubernetes onboarding becomes a
+  real workflow.
+- Consider validating cluster topology consistency as a warning, not a hard error.
+- Keep `docs/01-architecture/data-model.md` §3.2 and `docs/01-architecture/ui-design.md`
+  synchronized with this decision.