dsh-env-manager-plugin 0.1.0 → 0.1.1

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

@@ -1,165 +1,165 @@
-# Environment Template
-
-Copy into `<dataDir>/environments/<id>.yaml` and replace the example values.
-
-```yaml
-id: test-a
-schemaVersion: 1
-name: Test Environment A
-aliases: [ta, test-a]
-category: test          # dev | test | staging | production | custom
-description: Main test environment for aicoservice
-
-roles:
-  - id: management
-    name: Management Plane
-    description: Admin plane and control entry points
-  - id: business
-    name: Business Plane
-    description: Business traffic and workloads
-  - id: database
-    name: Database
-    description: Database tier (primary/replica/sharding detail is Phase 2)
-  - id: extension
-    name: Expansion / other
-    description: Expansion nodes and unclassified workloads
-
-hosts:
-  - id: host-001
-    name: test-a-node-01
-    kind: vm
-    os: ubuntu-22.04
-    platform: Linux / x86_64
-    ip: 10.0.1.10
-    sshPort: 22
-    roles: [management, business]     # co-location: one host, two roles
-    access: [ssh]
-    adminUser: root
-    isActive: true
-    credentialRef: cred-test-a-root
-    accounts:
-      - id: root
-        username: root
-        purpose: system administration
-        protocol: ssh
-        port: 22
-        authType: private-key
-        credentialRef: cred-test-a-root
-        lastLoginAt: 2026-10-31T08:12:00.000Z
-        lastLoginFrom: 10.0.8.21
-      - id: console
-        username: ops
-        purpose: business web console
-        protocol: web
-        loginUrl: https://test-a.example.internal/login
-        authType: password
-        credentialRef: env-manager/test-a/console
-  - id: db-01
-    name: test-a-db-01
-    kind: physical
-    platform: Linux / x86_64
-    ip: 10.0.1.30
-    sshPort: 22
-    roles: [database]
-    access: [ssh]
-    adminUser: root
-    isActive: true
-    note: primary placeholder; topology is Phase 2
-  - id: k8s-aio-01
-    name: test-a-k8s-aio-01
-    kind: k8s-all-in-one             # control plane + worker on one machine
-    platform: Linux / x86_64
-    ip: 10.0.1.20
-    sshPort: 22
-    roles: [management, business]
-    access: [ssh, kubectl, docker]
-    clusterRef: k8s-01
-    adminUser: root
-    isActive: true
-    note: kubeconfig stays behind the cluster credentialRef
-  - id: pod-host-01
-    name: test-a-pod-host-01
-    kind: pod-host                   # machine running Pods; operate with docker exec
-    platform: Linux / x86_64
-    ip: 10.0.1.21
-    sshPort: 22
-    roles: [business]
-    access: [ssh, docker]
-    clusterRef: k8s-01
-    adminUser: root
-    isActive: true
-    note: Pods are workloads; this record is the host, not an individual Pod
-
-clusters:
-  - id: k8s-01
-    name: test-a-k8s
-    kind: kubernetes
-    topology: all-in-one             # all-in-one | separate | external
-    apiEndpoint: https://10.0.1.20:6443
-    namespaces: [dv-sop]
-    credentialRef: cred-test-a-kubeconfig
-
-endpoints:
-  - id: ep-ssh-01
-    kind: ssh
-    hostRef: host-001
-    port: 22
-    credentialRef: cred-test-a-root
-  - id: ep-web-01
-    kind: web
-    url: https://test-a.example.internal
-
-loginRecords:
-  - id: login-0001
-    at: 2026-10-31T08:12:00.000Z
-    username: root
-    hostRef: host-001
-    accountId: root
-    protocol: ssh
-    sourceIp: 10.0.8.21
-    result: success             # success | failure
-    note: jump-host session
-
-createdAt: 2026-11-01T03:00:00.000Z
-updatedAt: 2026-11-01T03:00:00.000Z
-```
-
-## Notes
-
-- `id` must match the file name.
-- One environment is one network and one configuration page. Its management, business,
-  database and expansion planes are role views over the same `hosts[]`, not separate
-  environments. The UI shows a node in every plane it serves.
-- `roles` must contain at least one entry, and every `hosts[].roles` value must reference a
-  declared `roles[].id`. A host must declare at least one role. The standard ids are
-  `management`, `business`, `database` and `extension`; custom ids are allowed.
-- A host that serves two planes is one entry with two roles; do not duplicate it.
-- `hosts[].kind` is one of `vm`, `physical`, `k8s-all-in-one`, `k8s-worker` or `pod-host`;
-  missing means `vm`. `k8s-all-in-one` means the control plane and worker share a machine.
-  `pod-host` means the machine runs Pods and is operated with `docker exec`; it is still one
-  host, not one entry per Pod.
-- `hosts[].access` records the command surfaces present on the machine: `ssh`, `kubectl`,
-  `docker`. It is metadata, not an authorization grant. The form pre-fills defaults; the
-  values in YAML are authoritative.
-- `k8s-all-in-one` and `k8s-worker` require `clusterRef` to an existing cluster.
-  `pod-host` may omit it for a Docker-only machine outside the cluster. Any `clusterRef`
-  must resolve within this environment.
-- `clusters[].topology` is `all-in-one`, `separate` or `external`; it is descriptive and
-  optional. Per-host `kind` is authoritative.
-- `endpoints[].hostRef` / `clusterRef` must resolve within this environment.
-- `credentialRef` is a reference only; never put a value here. The same rule applies to
-  every `accounts[].credentialRef`.
-- `category: production` triggers the approval gate on management writes.
-- `accounts[]` is capped at 50 per host; `loginRecords[]` is capped at 200 per
-  environment. Login records may reference a host and an account on that host.
-- `accounts[].loginUrl` is the web console entry URL for a management or business login;
-  `username` is the login name. It must be an absolute `http(s)` URL. The password is never
-  stored here: the UI writes it to the DSH credential service and keeps only `credentialRef`.
-- `loginRecords` are audit context, not a replacement for a PAM/SIEM system. Keep only
-  the fields needed by DSH; do not copy session recordings or credentials into YAML.
-- The panel's batch import writes one node per line as
-  `IP,name,roles,port,user`; use `|` or `/` between roles. It creates generic `vm` nodes
-  with `access: [ssh]`, never accepts passwords, and leaves Kubernetes/Pod-host
-  classification to the node form or YAML.
-- Database primary/replica/sharding topology is not modeled in Phase 1. Use the
-  `database` role plus a node note; a later schema may add topology metadata.
+# Environment Template
+
+Copy into `<dataDir>/environments/<id>.yaml` and replace the example values.
+
+```yaml
+id: test-a
+schemaVersion: 1
+name: Test Environment A
+aliases: [ta, test-a]
+category: test          # dev | test | staging | production | custom
+description: Main test environment for aicoservice
+
+roles:
+  - id: management
+    name: Management Plane
+    description: Admin plane and control entry points
+  - id: business
+    name: Business Plane
+    description: Business traffic and workloads
+  - id: database
+    name: Database
+    description: Database tier (primary/replica/sharding detail is Phase 2)
+  - id: extension
+    name: Expansion / other
+    description: Expansion nodes and unclassified workloads
+
+hosts:
+  - id: host-001
+    name: test-a-node-01
+    kind: vm
+    os: ubuntu-22.04
+    platform: Linux / x86_64
+    ip: 10.0.1.10
+    sshPort: 22
+    roles: [management, business]     # co-location: one host, two roles
+    access: [ssh]
+    adminUser: root
+    isActive: true
+    credentialRef: cred-test-a-root
+    accounts:
+      - id: root
+        username: root
+        purpose: system administration
+        protocol: ssh
+        port: 22
+        authType: private-key
+        credentialRef: cred-test-a-root
+        lastLoginAt: 2026-10-31T08:12:00.000Z
+        lastLoginFrom: 10.0.8.21
+      - id: console
+        username: ops
+        purpose: business web console
+        protocol: web
+        loginUrl: https://test-a.example.internal/login
+        authType: password
+        credentialRef: env-manager/test-a/console
+  - id: db-01
+    name: test-a-db-01
+    kind: physical
+    platform: Linux / x86_64
+    ip: 10.0.1.30
+    sshPort: 22
+    roles: [database]
+    access: [ssh]
+    adminUser: root
+    isActive: true
+    note: primary placeholder; topology is Phase 2
+  - id: k8s-aio-01
+    name: test-a-k8s-aio-01
+    kind: k8s-all-in-one             # control plane + worker on one machine
+    platform: Linux / x86_64
+    ip: 10.0.1.20
+    sshPort: 22
+    roles: [management, business]
+    access: [ssh, kubectl, docker]
+    clusterRef: k8s-01
+    adminUser: root
+    isActive: true
+    note: kubeconfig stays behind the cluster credentialRef
+  - id: pod-host-01
+    name: test-a-pod-host-01
+    kind: pod-host                   # machine running Pods; operate with docker exec
+    platform: Linux / x86_64
+    ip: 10.0.1.21
+    sshPort: 22
+    roles: [business]
+    access: [ssh, docker]
+    clusterRef: k8s-01
+    adminUser: root
+    isActive: true
+    note: Pods are workloads; this record is the host, not an individual Pod
+
+clusters:
+  - id: k8s-01
+    name: test-a-k8s
+    kind: kubernetes
+    topology: all-in-one             # all-in-one | separate | external
+    apiEndpoint: https://10.0.1.20:6443
+    namespaces: [dv-sop]
+    credentialRef: cred-test-a-kubeconfig
+
+endpoints:
+  - id: ep-ssh-01
+    kind: ssh
+    hostRef: host-001
+    port: 22
+    credentialRef: cred-test-a-root
+  - id: ep-web-01
+    kind: web
+    url: https://test-a.example.internal
+
+loginRecords:
+  - id: login-0001
+    at: 2026-10-31T08:12:00.000Z
+    username: root
+    hostRef: host-001
+    accountId: root
+    protocol: ssh
+    sourceIp: 10.0.8.21
+    result: success             # success | failure
+    note: jump-host session
+
+createdAt: 2026-11-01T03:00:00.000Z
+updatedAt: 2026-11-01T03:00:00.000Z
+```
+
+## Notes
+
+- `id` must match the file name.
+- One environment is one network and one configuration page. Its management, business,
+  database and expansion planes are role views over the same `hosts[]`, not separate
+  environments. The UI shows a node in every plane it serves.
+- `roles` must contain at least one entry, and every `hosts[].roles` value must reference a
+  declared `roles[].id`. A host must declare at least one role. The standard ids are
+  `management`, `business`, `database` and `extension`; custom ids are allowed.
+- A host that serves two planes is one entry with two roles; do not duplicate it.
+- `hosts[].kind` is one of `vm`, `physical`, `k8s-all-in-one`, `k8s-worker` or `pod-host`;
+  missing means `vm`. `k8s-all-in-one` means the control plane and worker share a machine.
+  `pod-host` means the machine runs Pods and is operated with `docker exec`; it is still one
+  host, not one entry per Pod.
+- `hosts[].access` records the command surfaces present on the machine: `ssh`, `kubectl`,
+  `docker`. It is metadata, not an authorization grant. The form pre-fills defaults; the
+  values in YAML are authoritative.
+- `k8s-all-in-one` and `k8s-worker` require `clusterRef` to an existing cluster.
+  `pod-host` may omit it for a Docker-only machine outside the cluster. Any `clusterRef`
+  must resolve within this environment.
+- `clusters[].topology` is `all-in-one`, `separate` or `external`; it is descriptive and
+  optional. Per-host `kind` is authoritative.
+- `endpoints[].hostRef` / `clusterRef` must resolve within this environment.
+- `credentialRef` is a reference only; never put a value here. The same rule applies to
+  every `accounts[].credentialRef`.
+- `category: production` triggers the approval gate on management writes.
+- `accounts[]` is capped at 50 per host; `loginRecords[]` is capped at 200 per
+  environment. Login records may reference a host and an account on that host.
+- `accounts[].loginUrl` is the web console entry URL for a management or business login;
+  `username` is the login name. It must be an absolute `http(s)` URL. The password is never
+  stored here: the UI writes it to the DSH credential service and keeps only `credentialRef`.
+- `loginRecords` are audit context, not a replacement for a PAM/SIEM system. Keep only
+  the fields needed by DSH; do not copy session recordings or credentials into YAML.
+- The panel's batch import writes one node per line as
+  `IP,name,roles,port,user`; use `|` or `/` between roles. It creates generic `vm` nodes
+  with `access: [ssh]`, never accepts passwords, and leaves Kubernetes/Pod-host
+  classification to the node form or YAML.
+- Database primary/replica/sharding topology is not modeled in Phase 1. Use the
+  `database` role plus a node note; a later schema may add topology metadata.

package/docs/05-domain/operation-binding-template.md

@@ -1,55 +1,55 @@
-# Operation Binding Template
-
-Copy into `<dataDir>/operations/<id>.yaml`.
-
-```yaml
-id: binding-001
-schemaVersion: 1
-operation: redeploy          # standard id or custom id
-match:
-  environmentId: test-a
-  serviceId: aicoservice
-skill:
-  name: redeploy-k8s-service
-  expectedSource: null       # optional SkillSummary.source constraint
-  expectedProvider: null     # optional SkillSummary.provider constraint
-parameters:
-  namespace: ${deployment.location.namespace}
-  workload: ${deployment.location.workload.name}
-  cluster: ${deployment.location.clusterRef}
-policy:
-  requiresApproval: true
-  allowProduction: false
-enabled: true
-createdAt: 2026-11-01T03:00:00.000Z
-updatedAt: 2026-11-01T03:00:00.000Z
-```
-
-## Match levels
-
-| Level | Selectors present |
-|---|---|
-| `deployment` | `deploymentId` |
-| `environment-service` | `environmentId` + `serviceId` |
-| `service` | `serviceId` |
-| `category-mode` | `serviceCategory` + `deploymentMode` |
-| `global` | none (empty `match: {}`) |
-
-Every declared selector must match. The highest eligible level wins. Two eligible bindings at the same level are a conflict, never a coin flip.
-
-A `match` must be exactly one of these five shapes. For example `environmentId` alone, or `environmentId` + `deploymentMode`, is invalid (`RECORD_INVALID`).
-
-## Standard operations
-
-```text
-install, deploy, redeploy, replace, restart, upgrade, rollback, uninstall,
-collect-logs, health-check, inspect, upload, download
-```
-
-Custom operations are allowed but must be bound explicitly.
-
-## Policy
-
-- Write operations default to `requiresApproval: true`.
-- `allowProduction` defaults to `false`.
-- A binding is discovery information. It does not execute anything.
+# Operation Binding Template
+
+Copy into `<dataDir>/operations/<id>.yaml`.
+
+```yaml
+id: binding-001
+schemaVersion: 1
+operation: redeploy          # standard id or custom id
+match:
+  environmentId: test-a
+  serviceId: aicoservice
+skill:
+  name: redeploy-k8s-service
+  expectedSource: null       # optional SkillSummary.source constraint
+  expectedProvider: null     # optional SkillSummary.provider constraint
+parameters:
+  namespace: ${deployment.location.namespace}
+  workload: ${deployment.location.workload.name}
+  cluster: ${deployment.location.clusterRef}
+policy:
+  requiresApproval: true
+  allowProduction: false
+enabled: true
+createdAt: 2026-11-01T03:00:00.000Z
+updatedAt: 2026-11-01T03:00:00.000Z
+```
+
+## Match levels
+
+| Level | Selectors present |
+|---|---|
+| `deployment` | `deploymentId` |
+| `environment-service` | `environmentId` + `serviceId` |
+| `service` | `serviceId` |
+| `category-mode` | `serviceCategory` + `deploymentMode` |
+| `global` | none (empty `match: {}`) |
+
+Every declared selector must match. The highest eligible level wins. Two eligible bindings at the same level are a conflict, never a coin flip.
+
+A `match` must be exactly one of these five shapes. For example `environmentId` alone, or `environmentId` + `deploymentMode`, is invalid (`RECORD_INVALID`).
+
+## Standard operations
+
+```text
+install, deploy, redeploy, replace, restart, upgrade, rollback, uninstall,
+collect-logs, health-check, inspect, upload, download
+```
+
+Custom operations are allowed but must be bound explicitly.
+
+## Policy
+
+- Write operations default to `requiresApproval: true`.
+- `allowProduction` defaults to `false`.
+- A binding is discovery information. It does not execute anything.

package/docs/05-domain/operation-record-template.md

@@ -1,55 +1,55 @@
-# Operation Record Template
-
-P1 artifact. V1 defines the type and a null bridge; it does not persist records.
-
-```ts
-interface OperationRecord {
-  id: string;
-  sessionId: string;
-  environmentId: string;
-  serviceId?: string;
-  deploymentId?: string;
-  operation: string;
-  skillRef?: string;
-  startedAt: string;
-  finishedAt?: string;
-  outcome: 'success' | 'failure' | 'unknown';
-  evidenceRefs: string[];
-  summary: string;
-}
-```
-
-## JSON example
-
-```json
-{
-  "id": "op-20261101-0001",
-  "sessionId": "session-abc",
-  "environmentId": "test-a",
-  "serviceId": "aicoservice",
-  "deploymentId": "deploy-001",
-  "operation": "redeploy",
-  "skillRef": "redeploy-k8s-service",
-  "startedAt": "2026-11-01T03:00:00.000Z",
-  "finishedAt": "2026-11-01T03:04:12.000Z",
-  "outcome": "success",
-  "evidenceRefs": ["evidence:test-a/deploy-001/log-20261101"],
-  "summary": "Redeploy completed; pod rollout finished with 2/2 ready"
-}
-```
-
-## Rules
-
-- `evidenceRefs` are opaque and sanitized; never embed raw logs or secrets.
-- `summary` is redacted and bounded (default 500 characters).
-- The record carries scope ids so memory queries stay scoped.
-- Records are append-only from the plugin's perspective.
-- A record is not an audit replacement for the executing tool's own logging.
-
-## Evidence reference format
-
-```text
-evidence:{environmentId}/{deploymentId}/{kind}-{timestamp}
-```
-
-`kind` is a short token such as `log`, `config` or `check`. The content lives outside the record.
+# Operation Record Template
+
+P1 artifact. V1 defines the type and a null bridge; it does not persist records.
+
+```ts
+interface OperationRecord {
+  id: string;
+  sessionId: string;
+  environmentId: string;
+  serviceId?: string;
+  deploymentId?: string;
+  operation: string;
+  skillRef?: string;
+  startedAt: string;
+  finishedAt?: string;
+  outcome: 'success' | 'failure' | 'unknown';
+  evidenceRefs: string[];
+  summary: string;
+}
+```
+
+## JSON example
+
+```json
+{
+  "id": "op-20261101-0001",
+  "sessionId": "session-abc",
+  "environmentId": "test-a",
+  "serviceId": "aicoservice",
+  "deploymentId": "deploy-001",
+  "operation": "redeploy",
+  "skillRef": "redeploy-k8s-service",
+  "startedAt": "2026-11-01T03:00:00.000Z",
+  "finishedAt": "2026-11-01T03:04:12.000Z",
+  "outcome": "success",
+  "evidenceRefs": ["evidence:test-a/deploy-001/log-20261101"],
+  "summary": "Redeploy completed; pod rollout finished with 2/2 ready"
+}
+```
+
+## Rules
+
+- `evidenceRefs` are opaque and sanitized; never embed raw logs or secrets.
+- `summary` is redacted and bounded (default 500 characters).
+- The record carries scope ids so memory queries stay scoped.
+- Records are append-only from the plugin's perspective.
+- A record is not an audit replacement for the executing tool's own logging.
+
+## Evidence reference format
+
+```text
+evidence:{environmentId}/{deploymentId}/{kind}-{timestamp}
+```
+
+`kind` is a short token such as `log`, `config` or `check`. The content lives outside the record.