dsh-env-manager-plugin 0.1.0 → 0.1.2

package/docs/04-development/local-run-guide.md

@@ -1,55 +1,61 @@
-# Local Run Guide
-
-## Build
-
-```bash
-npm install
-npm run build
-```
-
-## Install in a DSH Profile
-
-In a DSH session, call the `plugin_manager` tool:
-
-```text
-action: install_bundle
-target: <absolute path to this repository>
-```
-
-Restart DSH if the bundle was already installed before this change.
-
-## Verify Installation
-
-Ask `plugin_manager` for `action: list_bundles`, then confirm the bundle appears.
-
-Then check that the tools are available: ask the Agent to call `env_list`; it should return an empty list rather than an unknown-tool error.
-
-## Where the data lives
-
-The Host reports the resolved `dataDir` once at startup. On first run the directories are created:
-
-```text
-<dataDir>/environments  services  deployments  rules  operations  sessions
-```
-
-Put a sample environment there or use `env_save`.
-
-## Development loop
-
-1. Edit `src/`.
-2. `npm run build`.
-3. Reinstall the bundle.
-4. Restart DSH (Host code changes need a fresh module generation).
-5. Call the tool again.
-
-`client.js` changes need the same reinstall; they do not require a build.
-
-## Uninstall
-
-Call `plugin_manager` with `action: remove_bundle` and `target: dsh-env-manager-plugin`.
-
-Registry data under `dataDir` is not removed automatically. Back it up before deleting the profile.
-
-## Troubleshooting
-
-See `06-operations/troubleshooting.md`.
+# Local Run Guide
+
+## Build
+
+The repository commits the compiled `lib/` directory, so a fresh checkout is installable
+without a build. Rebuild only after changing `src/`:
+
+```bash
+npm install
+npm run build
+```
+
+## Install in a DSH Profile
+
+In a DSH session, call the `plugin_manager` tool:
+
+```text
+action: install_bundle
+target: <absolute path to this repository>
+```
+
+The install is one bundle entry. Do not also edit `dsh.profile.bundles` by hand; a second
+entry loads the plugin twice and prevents DSH from starting.
+
+Restart DSH if the bundle was already installed before this change.
+
+## Verify Installation
+
+Ask `plugin_manager` for `action: list_bundles`, then confirm the bundle appears.
+
+Then check that the tools are available: ask the Agent to call `env_list`; it should return an empty list rather than an unknown-tool error.
+
+## Where the data lives
+
+The Host reports the resolved `dataDir` once at startup. On first run the directories are created:
+
+```text
+<dataDir>/environments  services  deployments  rules  operations  sessions
+```
+
+Put a sample environment there or use `env_save`.
+
+## Development loop
+
+1. Edit `src/`.
+2. `npm run build`.
+3. Reinstall the bundle.
+4. Restart DSH (Host code changes need a fresh module generation).
+5. Call the tool again.
+
+`client.js` changes need the same reinstall; they do not require a build.
+
+## Uninstall
+
+Call `plugin_manager` with `action: remove_bundle` and `target: dsh-env-manager-plugin`.
+
+Registry data under `dataDir` is not removed automatically. Back it up before deleting the profile.
+
+## Troubleshooting
+
+See `06-operations/troubleshooting.md`.

package/docs/04-development/testing-guide.md

@@ -1,102 +1,102 @@
-# Testing Guide
-
-## Framework
-
-Vitest, with TypeScript sources tested directly (no build required for tests).
-
-## Commands
-
-```bash
-npm test             # run once
-npm run test:watch   # watch mode
-```
-
-## Test Organization
-
-```text
-tests/
-├── domain/schemas.test.ts
-├── storage/records.test.ts
-├── storage/atomic.test.ts
-├── registry/registry.test.ts
-├── resolver/template.test.ts
-├── resolver/layers.test.ts
-├── resolver/context.test.ts
-├── router/match.test.ts
-├── router/router.test.ts
-├── session/session-context.test.ts
-├── app/app.test.ts
-├── tools/read.test.ts
-├── tools/write.test.ts
-└── http/route.test.ts
-```
-
-## What to test
-
-### `domain`
-- Valid record passes; unknown field fails.
-- Id pattern and `schemaVersion` enforcement.
-- Discriminated unions reject mismatched `runtimeMode`/`location.kind`.
-
-### `storage`
-- Atomic write leaves no temp file.
-- Read tolerates missing directory and invalid YAML.
-- Backup pruning keeps at most 5.
-- Concurrent writes serialize in-process.
-
-### `registry`
-- Load, lookup by id and alias.
-- Duplicate id detection.
-- Referential integrity: missing environment/service/host/cluster/rule profile.
-- Invalid file is skipped, not deleted.
-
-### `resolver`
-- Layer precedence: service < environment < deployment.
-- Field-level merge keeps unrelated fields.
-- Provenance: `definedBy`, `inputs`, `shadowed` for the worked example in design §6.9.
-- Undefined variable, cycle, path traversal, type mismatch.
-- Only the runtime's log source and class location are resolved.
-
-### `router`
-- Each match level, in isolation and in combination.
-- Highest level wins; lower levels ignored.
-- Same-level conflict lists all candidates and selects none.
-- Missing skill, source mismatch, provider mismatch.
-- Unknown/incomplete skill registry degrades to `'unknown'` plus warning.
-- Production denial and `requiresApproval` defaults.
-- Parameter mapping, including failure on unresolved reference.
-
-### `session`
-- Set, get, clear.
-- Two sessions do not interfere.
-- Corrupt file is treated as "no default" with `persisted: false`.
-
-### `app`
-- Save→get round trip; `created` flag.
-- Delete refused when referenced (`RECORD_IN_USE`).
-- Dry-run writes nothing.
-- UI actor cannot write production by default.
-- `find` matches id, name and alias.
-
-### `tools`
-- Success value matches the declared `output.schema`.
-- Failures throw `EnvManagerError` with the expected code.
-- No credential value ever appears in output (assert on serialized JSON).
-- Invalid id error code.
-- `env_validate` does not write.
-- Approval denial produces `POLICY_DENIED` and no file change.
-
-### `http`
-- Missing header → 403; foreign origin → 403; GET → 405; oversize → 413.
-- Unknown op → 400; not found → 404; conflict → 409; production UI write → 403.
-- Success envelope is `{ ok: true, data }` and never leaks a stack.
-
-## Fixtures
-
-- Under `tests/fixtures/`, one directory per scenario.
-- Fake values only: `test-a`, `10.0.0.x`, `example.internal`, `cred-test-*`.
-- A fixture that needs a secret-like string must use an obvious placeholder and must not be a real credential.
-
-## Coverage expectations
-
-No numeric gate in V1. The resolver, router and storage modules are expected to be near-complete because they are pure and cheap to test. The Client UI is verified manually.
+# Testing Guide
+
+## Framework
+
+Vitest, with TypeScript sources tested directly (no build required for tests).
+
+## Commands
+
+```bash
+npm test             # run once
+npm run test:watch   # watch mode
+```
+
+## Test Organization
+
+```text
+tests/
+├── domain/schemas.test.ts
+├── storage/records.test.ts
+├── storage/atomic.test.ts
+├── registry/registry.test.ts
+├── resolver/template.test.ts
+├── resolver/layers.test.ts
+├── resolver/context.test.ts
+├── router/match.test.ts
+├── router/router.test.ts
+├── session/session-context.test.ts
+├── app/app.test.ts
+├── tools/read.test.ts
+├── tools/write.test.ts
+└── http/route.test.ts
+```
+
+## What to test
+
+### `domain`
+- Valid record passes; unknown field fails.
+- Id pattern and `schemaVersion` enforcement.
+- Discriminated unions reject mismatched `runtimeMode`/`location.kind`.
+
+### `storage`
+- Atomic write leaves no temp file.
+- Read tolerates missing directory and invalid YAML.
+- Backup pruning keeps at most 5.
+- Concurrent writes serialize in-process.
+
+### `registry`
+- Load, lookup by id and alias.
+- Duplicate id detection.
+- Referential integrity: missing environment/service/host/cluster/rule profile.
+- Invalid file is skipped, not deleted.
+
+### `resolver`
+- Layer precedence: service < environment < deployment.
+- Field-level merge keeps unrelated fields.
+- Provenance: `definedBy`, `inputs`, `shadowed` for the worked example in design §6.9.
+- Undefined variable, cycle, path traversal, type mismatch.
+- Only the runtime's log source and class location are resolved.
+
+### `router`
+- Each match level, in isolation and in combination.
+- Highest level wins; lower levels ignored.
+- Same-level conflict lists all candidates and selects none.
+- Missing skill, source mismatch, provider mismatch.
+- Unknown/incomplete skill registry degrades to `'unknown'` plus warning.
+- Production denial and `requiresApproval` defaults.
+- Parameter mapping, including failure on unresolved reference.
+
+### `session`
+- Set, get, clear.
+- Two sessions do not interfere.
+- Corrupt file is treated as "no default" with `persisted: false`.
+
+### `app`
+- Save→get round trip; `created` flag.
+- Delete refused when referenced (`RECORD_IN_USE`).
+- Dry-run writes nothing.
+- UI actor cannot write production by default.
+- `find` matches id, name and alias.
+
+### `tools`
+- Success value matches the declared `output.schema`.
+- Failures throw `EnvManagerError` with the expected code.
+- No credential value ever appears in output (assert on serialized JSON).
+- Invalid id error code.
+- `env_validate` does not write.
+- Approval denial produces `POLICY_DENIED` and no file change.
+
+### `http`
+- Missing header → 403; foreign origin → 403; GET → 405; oversize → 413.
+- Unknown op → 400; not found → 404; conflict → 409; production UI write → 403.
+- Success envelope is `{ ok: true, data }` and never leaks a stack.
+
+## Fixtures
+
+- Under `tests/fixtures/`, one directory per scenario.
+- Fake values only: `test-a`, `10.0.0.x`, `example.internal`, `cred-test-*`.
+- A fixture that needs a secret-like string must use an obvious placeholder and must not be a real credential.
+
+## Coverage expectations
+
+No numeric gate in V1. The resolver, router and storage modules are expected to be near-complete because they are pure and cheap to test. The Client UI is verified manually.

package/docs/05-domain/deployment-template.md

@@ -1,76 +1,76 @@
-# Deployment Binding Template
-
-Copy into `<dataDir>/deployments/<id>.yaml`.
-
-A service may have several bindings in one environment. Use distinct ids and a `name` to tell them apart.
-
-## Kubernetes
-
-```yaml
-id: deploy-001
-schemaVersion: 1
-name: aicoservice-test-a
-environmentId: test-a
-serviceId: aicoservice
-runtimeMode: kubernetes
-location:
-  kind: kubernetes
-  clusterRef: k8s-01
-  namespace: dv-sop
-  workload:
-    kind: Deployment
-    name: aicoservice
-  container: aicoservice
-variables:
-  replicaCount: 2
-ruleOverrides:
-  logSources:
-    kubernetes:
-      kind: pod-logs
-      namespace: dv-sop
-      workload: aicoservice
-createdAt: 2026-11-01T03:00:00.000Z
-updatedAt: 2026-11-01T03:00:00.000Z
-```
-
-## Native
-
-```yaml
-id: deploy-002
-schemaVersion: 1
-environmentId: test-a
-serviceId: aicoservice
-runtimeMode: native
-location:
-  kind: native
-  hostRef: host-001
-  installDir: /opt/company/services/aicoservice
-  serviceName: aicoservice.service
-createdAt: 2026-11-01T03:00:00.000Z
-updatedAt: 2026-11-01T03:00:00.000Z
-```
-
-## Docker
-
-```yaml
-id: deploy-003
-schemaVersion: 1
-environmentId: test-a
-serviceId: aicoservice
-runtimeMode: docker
-location:
-  kind: docker
-  hostRef: host-001
-  containerName: aicoservice
-  image: registry.example.internal/team/aicoservice:latest
-createdAt: 2026-11-01T03:00:00.000Z
-updatedAt: 2026-11-01T03:00:00.000Z
-```
-
-## Notes
-
-- `runtimeMode` must equal `location.kind`.
-- `hostRef` and `clusterRef` resolve inside the referenced environment only.
-- `variables` are deployment-level user variables; they win over environment-level variables for that field.
-- `ruleOverrides` is field-level: overriding `logSources` does not erase `paths`.
-- If a service has several bindings and the caller omits `deploymentId`, the resolver fails with `DEPLOYMENT_AMBIGUOUS` rather than guessing.
+# Deployment Binding Template
+
+Copy into `<dataDir>/deployments/<id>.yaml`.
+
+A service may have several bindings in one environment. Use distinct ids and a `name` to tell them apart.
+
+## Kubernetes
+
+```yaml
+id: deploy-001
+schemaVersion: 1
+name: aicoservice-test-a
+environmentId: test-a
+serviceId: aicoservice
+runtimeMode: kubernetes
+location:
+  kind: kubernetes
+  clusterRef: k8s-01
+  namespace: dv-sop
+  workload:
+    kind: Deployment
+    name: aicoservice
+  container: aicoservice
+variables:
+  replicaCount: 2
+ruleOverrides:
+  logSources:
+    kubernetes:
+      kind: pod-logs
+      namespace: dv-sop
+      workload: aicoservice
+createdAt: 2026-11-01T03:00:00.000Z
+updatedAt: 2026-11-01T03:00:00.000Z
+```
+
+## Native
+
+```yaml
+id: deploy-002
+schemaVersion: 1
+environmentId: test-a
+serviceId: aicoservice
+runtimeMode: native
+location:
+  kind: native
+  hostRef: host-001
+  installDir: /opt/company/services/aicoservice
+  serviceName: aicoservice.service
+createdAt: 2026-11-01T03:00:00.000Z
+updatedAt: 2026-11-01T03:00:00.000Z
+```
+
+## Docker
+
+```yaml
+id: deploy-003
+schemaVersion: 1
+environmentId: test-a
+serviceId: aicoservice
+runtimeMode: docker
+location:
+  kind: docker
+  hostRef: host-001
+  containerName: aicoservice
+  image: registry.example.internal/team/aicoservice:latest
+createdAt: 2026-11-01T03:00:00.000Z
+updatedAt: 2026-11-01T03:00:00.000Z
+```
+
+## Notes
+
+- `runtimeMode` must equal `location.kind`.
+- `hostRef` and `clusterRef` resolve inside the referenced environment only.
+- `variables` are deployment-level user variables; they win over environment-level variables for that field.
+- `ruleOverrides` is field-level: overriding `logSources` does not erase `paths`.
+- If a service has several bindings and the caller omits `deploymentId`, the resolver fails with `DEPLOYMENT_AMBIGUOUS` rather than guessing.