dsh-env-manager-plugin 0.0.0-stage → 0.1.0

package/docs/01-architecture/decisions/ADR-0001-plugin-as-bundle.md

@@ -0,0 +1,29 @@
+# ADR-0001: Distribute as a DSH Bundle
+
+## Status
+
+Accepted
+
+## Context
+
+The Environment Manager must be installable into DSH and share state across sessions in the same profile. We considered several distribution models:
+
+1. Standalone Node.js service
+2. DSH plugin bundle
+3. External CLI tool
+
+## Decision
+
+We will distribute Environment Manager as a DSH bundle with both Host and Client entries.
+
+## Consequences
+
+- Users install the bundle through DSH's `plugin_manager`.
+- Host-side code runs in the DSH host process and can register tools and services.
+- Client-side code runs in the Web/Desktop UI and can provide configuration panels.
+- State is scoped to a DSH profile; all sessions in the profile share the registry.
+
+## Alternatives Considered
+
+- **Standalone service**: Adds operational overhead and is not idiomatic for DSH.
+- **External CLI tool**: Loses integration with DSH session context and UI.

package/docs/01-architecture/decisions/ADR-0002-file-based-storage.md

@@ -0,0 +1,25 @@
+# ADR-0002: File-based Storage as Source of Truth
+
+## Status
+
+Accepted
+
+## Context
+
+We need durable storage for registry records. Options include a local JSON/YAML file tree, SQLite, or a database.
+
+## Decision
+
+Registry data is stored as YAML files in a directory tree under the plugin workspace.
+
+## Consequences
+
+- Human-readable and version-control friendly.
+- Easy to inspect and edit.
+- No external database dependency.
+- Concurrent writes are last-write-wins; higher-level locking may be added later.
+
+## Alternatives Considered
+
+- **SQLite**: Adds complexity and a binary artifact; not necessary for V1 scale.
+- **DSH memory plugin**: Memory plugin is for historical knowledge, not authoritative configuration.

package/docs/01-architecture/decisions/ADR-0003-skill-router-over-search.md

@@ -0,0 +1,25 @@
+# ADR-0003: Explicit Operation-to-Skill Binding over Search
+
+## Status
+
+Accepted
+
+## Context
+
+When an Agent asks to perform an operation (e.g. redeploy a service), the system could either search for a relevant Skill or use an explicit binding.
+
+## Decision
+
+We will use explicit Operation Bindings with deterministic scope-based matching.
+
+## Consequences
+
+- Predictable routing: the same context always resolves to the same Skill.
+- Conflicts are explicit and fail safely.
+- Parameters are mapped declaratively.
+- Approval policies are attached to bindings.
+
+## Alternatives Considered
+
+- **Semantic search over skill descriptions**: Non-deterministic and hard to audit for production operations.
+- **Convention-based naming**: Brittle and does not support fine-grained policy.

package/docs/01-architecture/decisions/ADR-0004-typescript-host-js-client.md

@@ -0,0 +1,31 @@
+# ADR-0004: TypeScript Host, Plain-JavaScript Client
+
+## Status
+
+Accepted
+
+## Context
+
+The Host half contains the domain logic: schemas, layered rule resolution, provenance, conflict detection and policy evaluation. These benefit from static types and exhaustive checks.
+
+The Client half is a DSH module-loader artifact. It has no build step today and uses `React.createElement` rather than JSX.
+
+The alternative was TypeScript everywhere with a client bundler, or plain JavaScript everywhere.
+
+## Decision
+
+- Host: TypeScript compiled to ESM (`src/` → `lib/`).
+- Client: plain JavaScript module at the repository root (`client.js`), no bundler.
+- The current JavaScript host skeleton is replaced during V1 implementation; the bundle entry becomes a thin shim over `lib/index.js`.
+
+## Consequences
+
+- Domain invariants are checked at compile time.
+- No client build pipeline in V1; UI code is more verbose.
+- Two languages in one repository; the boundary is explicit: `src/` is Host-only.
+- If the UI later needs TypeScript or JSX, that change gets its own ADR and a bundling step.
+
+## Alternatives Considered
+
+- **TypeScript everywhere now**: a bundler and a module-loader wrapper are needed immediately; delays the core value.
+- **JavaScript everywhere**: loses compile-time guarantees exactly where the domain is most intricate.

package/docs/01-architecture/decisions/ADR-0005-layered-rule-resolution.md

@@ -0,0 +1,36 @@
+# ADR-0005: Layered Rule Resolution with Provenance
+
+## Status
+
+Accepted
+
+## Context
+
+Rule profiles define paths, log sources and class locations that differ by service and by environment. Users need to override one field without copying an entire profile, and they need to understand why a resolved value is what it is.
+
+Alternatives: a single flat profile per deployment, whole-object replacement, or embedding script hooks.
+
+## Decision
+
+Resolve rules in four ordered layers:
+
+1. global defaults
+2. service `ruleProfileRefs`, in list order
+3. environment `ruleOverrides`
+4. deployment `variables` and `ruleOverrides`
+
+Merging is field-level. Every returned field carries provenance: the winning layer, the referenced inputs with their own sources, and the shadowed definitions.
+
+Templates support `${...}` interpolation only. No functions, operators or code.
+
+## Consequences
+
+- An environment can override `paths.logDir` without touching `paths.jar`.
+- A field defined at the service layer can still change because an input was overridden; provenance makes that visible.
+- Validation must detect cycles and undefined references before returning anything.
+- Users see derived values as derived; they are not implied to exist.
+
+## Alternatives Considered
+
+- **Whole-object replacement**: simple but forces duplication and hides intent.
+- **Script hooks**: powerful but unreviewable in production and outside the safety model.

package/docs/01-architecture/decisions/ADR-0006-credentials-as-references.md

@@ -0,0 +1,30 @@
+# ADR-0006: Credentials Are References
+
+## Status
+
+Accepted
+
+## Context
+
+The registry describes production hosts, clusters and services. Operators will want the Agent to "log in" or "use the credential for test-a".
+
+Storing values in the registry would make the YAML files a secret store, would leak through tool output and Git history, and would duplicate the DSH credential service.
+
+## Decision
+
+1. Registry records store only `credentialRef` strings.
+2. Credential status is obtained with `ctx.credentials.describe(ref)` and reduced to
+   `{ configured, source? }`.
+3. The plugin never calls `ctx.credentials.resolve(ref)` and never forwards a credential value.
+4. Tool and HTTP output expose `{ ref, configured, source? }` only.
+
+## Consequences
+
+- Secrets stay in the DSH credential service or an external vault.
+- The plugin cannot authenticate anything itself; execution adapters (future) must obtain credentials through the proper service.
+- A wrong reference cannot be detected beyond `configured: true/false`; operational review remains necessary.
+
+## Alternatives Considered
+
+- **Store values in YAML**: unacceptable for Git history and tool output.
+- **Skip references entirely**: loses the link between a host and its credential, which users need.

package/docs/01-architecture/decisions/ADR-0007-session-scoped-default-environment.md

@@ -0,0 +1,28 @@
+# ADR-0007: Session-Scoped Default Environment
+
+## Status
+
+Accepted
+
+## Context
+
+Users work in one environment at a time and do not want to repeat "test-a" in every request. A shared global default would let one session silently change another session's target, which is unsafe.
+
+## Decision
+
+- The default environment is stored per session.
+- `env_set_context` writes only the current session's value.
+- Tools accept an explicit `environmentId` first; the session default is a fallback.
+- The default is advisory: it never mutates registry records and never changes routing policy.
+
+## Consequences
+
+- Two sessions can target different environments concurrently (AC-07).
+- Storage is a small JSON file per session under `<dataDir>/sessions/`; the DSH
+  projection store is not usable from a standalone bundle (`api-verification.md` F11).
+- A session without a default must pass `environmentId` explicitly; the error names both options.
+
+## Alternatives Considered
+
+- **Profile-global default**: convenient but violates session isolation.
+- **No default at all**: safe but adds friction to every call.

package/docs/01-architecture/decisions/ADR-0008-memory-bridge-not-second-store.md

@@ -0,0 +1,31 @@
+# ADR-0008: Memory Bridge Instead of a Second Memory Store
+
+## Status
+
+Accepted
+
+## Context
+
+The brainstorm originally considered a standalone memory plugin with structured categories. The project already depends on a memory plugin for durable knowledge, decisions, playbooks and open questions.
+
+Building a second store would duplicate environment facts and split the place where lessons live.
+
+## Decision
+
+- DSH Environment Manager owns environment facts, service catalog, deployment bindings, rules and operation bindings.
+- The memory plugin owns durable knowledge: observations, playbooks, decisions and proposals.
+- The bridge exchanges scoped references, never copies of registry data.
+- V1 ships the contract and a null adapter; P1 implements the adapter.
+- Nothing in the bridge auto-applies a change.
+
+## Consequences
+
+- One place for facts, one place for knowledge.
+- Memory entries must carry `environmentId`/`serviceId`/`deploymentId` scope.
+- A single-environment conclusion cannot silently become a global rule.
+- The bridge contract must be versioned when the memory plugin changes.
+
+## Alternatives Considered
+
+- **Own memory store**: duplicates scope, evidence and review logic.
+- **No integration**: the improvement loop from the brainstorm cannot close.

package/docs/01-architecture/decisions/ADR-0009-client-host-http-transport.md

@@ -0,0 +1,87 @@
+# ADR-0009: Client–Host transport via a plugin-owned HTTP route
+
+- Status: accepted
+- Date: 2026-11-01
+- Supersedes: none
+- Related: ADR-0004 (TypeScript Host, plain-JS Client), `api-verification.md` F9–F14
+
+## Context
+
+The V1 panel must list, edit and validate registry records. The data lives in the Host
+process; the Client half runs in the browser page. A transport is therefore required.
+
+DSH's native mechanism is the Typert Remote system:
+
+- the Host defines a service extending `TypertRemoteService` and marks methods with
+  `@Remote` / `@RemoteScope`;
+- a build-time Typert loader emits an `InvocationDescriptor` and a `/remote` artifact;
+- the Client imports that artifact, mounts it through `ctx.remote.$mount()`, and calls
+  generated methods;
+- the Gateway rejects Client-supplied fields that lack a strict generated codec.
+
+That pipeline assumes the DSH monorepo build toolchain and a matching DSH release.
+This repository is a standalone bundle compiled with plain `tsc`, and the runtime
+provides no API for registering a Remote namespace from plain JavaScript.
+
+## Decision
+
+The plugin registers one same-origin HTTP route and the Client calls it:
+
+```text
+POST /env-manager/api
+headers: content-type: application/json
+         x-env-manager-request: 1
+body:    { "op": "...", "payload": { ... } }
+```
+
+- The route is registered with `ctx.webServer.register({ kind: 'prefix', ... })` and
+  disposed with the plugin fiber.
+- The route handler is a thin adapter over the same application service the tools use;
+  there is no second business path.
+- Authentication is a required custom header plus an `Origin` equality check against
+  `ctx.webServer.getOrigin()`. No cookie or credential is read. No CORS headers are
+  sent, so a cross-origin page cannot preflight the custom header.
+- Every request is validated server-side; the Client's TypeScript-free code is never
+  trusted for shape.
+- Writes from this route run with actor `'ui'` and are subject to
+  `writePolicy.allowUiProductionWrites`; deletes require an explicit `confirm: true`.
+
+## Consequences
+
+Positive:
+
+- No dependency on the Typert codegen toolchain or on a matching DSH release.
+- One transport for tools and UI, so behavior cannot drift.
+- Simple to test with Node's `http` mocks and `curl`.
+- No streaming requirement in V1, so request/response is sufficient.
+
+Negative:
+
+- The Client has no generated type contract; shared shapes are maintained by hand and
+  checked by tests.
+- A new local HTTP surface exists. It is header-gated, origin-checked, read-only for
+  credentials, and cannot be reached cross-origin without a preflight the server
+  refuses.
+- No streaming or subscriptions; the UI refreshes explicitly.
+- Session-scoped operations are not exposed to the UI in V1, because the UI has no
+  trustworthy session identity.
+
+## Alternatives
+
+| Alternative | Why rejected |
+|---|---|
+| Typert Remote namespace | Requires build-time descriptors and DSH monorepo tooling; impossible from plain JS |
+| Client reads registry files directly | The browser has no filesystem access, and it would bypass Host validation |
+| Agent-mediated UI (buttons insert prompts) | Poor UX; every inspection would consume a turn |
+| WebSocket / streaming | V1 has no live-update requirement |
+| `window.__DSH_BOOT__` global injection of data | One-shot snapshot, no writes, stale immediately |
+
+## Review trigger
+
+Revisit when either becomes true:
+
+1. DSH exposes a runtime API to register an `InvocationDescriptor` from a bundle, or
+2. this repository adopts the DSH build toolchain and can emit `/remote` artifacts.
+
+At that point the HTTP adapter can be replaced without changing the application service
+or the tools.

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

@@ -0,0 +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.

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

@@ -0,0 +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.