dsh-env-manager-plugin 0.1.0 → 0.1.1

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

@@ -1,29 +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.
+# 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

@@ -1,25 +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.
+# 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

@@ -1,25 +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.
+# 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

@@ -1,31 +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.
+# 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

@@ -1,36 +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.
+# 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

@@ -1,30 +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.
+# 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

@@ -1,28 +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.
+# 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

@@ -1,31 +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.
+# 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

@@ -1,87 +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.
+# 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.