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

package/docs/04-development/dependency-policy.md

@@ -0,0 +1,43 @@
+# Dependency Policy
+
+## Runtime dependencies
+
+Keep the set minimal and justified:
+
+| Package | Why |
+|---|---|
+| `zod` | schema validation for records and tool inputs |
+| `yaml` | YAML parse/serialize with typed results |
+| `@deepseek-ai/schemastery` | `Config` schema for the Host plugin |
+
+Anything else needs a proposal that explains why the standard library and the three
+packages above are insufficient.
+
+DSH-provided packages (`@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-llm`, `@deepseek-ai/cordis`) are
+peers, supplied by the profile; never bundle them.
+
+## Development dependencies
+
+| Package | Why |
+|---|---|
+| `typescript` | Host build |
+| `vitest` | tests |
+
+Optional, with justification: `@types/node`, a linter, a formatter.
+
+## Rules
+
+1. No dependency that duplicates DSH-provided services (fs, credentials, approval, storage).
+2. No database driver.
+3. No client bundler unless a new ADR accepts it.
+4. No native modules unless there is no alternative.
+5. Check the license before adding.
+6. Prefer a small maintained package over a large framework.
+
+## Adding a dependency
+
+1. Write an OpenSpec proposal or a task entry.
+2. State the capability gap.
+3. State alternatives considered.
+4. Add it to `package.json` and the lockfile.
+5. Mention it in `docs/01-architecture/design.md` §15.4 if it changes the build.

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

@@ -0,0 +1,85 @@
+# Development Guide
+
+> Status: this guide describes the V1 target. The repository currently ships the JavaScript skeleton; `src/`, `lib/`, `tsconfig.json` and the npm scripts are added during V1 implementation. See `docs/00-project/current-state.md`.
+
+## Prerequisites
+
+- Node.js matching the DSH runtime
+- npm
+
+## First Run
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## Project Layout
+
+```text
+dsh-env-manager/
+├── index.js          # Host entry shim over lib/index.js
+├── client.js         # Client module (plain JS)
+├── cordis.patch.yml  # Cordis patch
+├── package.json      # Bundle manifest
+├── tsconfig.json     # Host build config
+├── src/              # TypeScript host sources
+├── lib/              # Build output (git-ignored)
+├── locale/           # Display metadata
+├── docs/             # Project documentation
+├── data/             # Runtime registry data (git-ignored)
+└── tests/            # Vitest tests
+```
+
+## Build
+
+```bash
+npm run build          # tsc -p tsconfig.json
+npm run build:watch    # optional watch mode
+```
+
+The Host entry `index.js` re-exports `lib/index.js`. Do not edit `lib/` by hand.
+
+## Test
+
+```bash
+npm test               # vitest run
+npm run test:watch     # vitest
+```
+
+## Install in a DSH Profile
+
+In a DSH session, call the `plugin_manager` tool with `action: install_bundle` and the absolute repository path as `target`. Restart DSH if the bundle was already installed.
+
+Do not use `dsh plugin add` for bundle selection; that forwards to pnpm only.
+
+## Development Loop
+
+1. Read the relevant docs (`docs/README.md` decides which).
+2. Change `src/` or `client.js`.
+3. Build and test.
+4. Reinstall the bundle to see Host/Client changes.
+5. Update `docs/00-project/current-state.md`.
+
+## Client Changes
+
+`client.js` is plain JavaScript and needs no build. The Host serves it as the bundle's `./client` export.
+
+Keep the module-loader wrapper intact:
+
+```js
+window.__ModuleLoader__.load({ id: 'dsh-env-manager', factory(require) { ... } })
+```
+
+## Data Directory
+
+Do not commit `data/`. It is created on first run at the resolved `dataDir`; the startup log reports the path.
+
+## Updating Docs
+
+After every meaningful change update:
+
+- `docs/00-project/current-state.md`
+- the matching architecture document when behavior or schemas changed
+- OpenSpec artifacts when used

package/docs/04-development/directory-convention.md

@@ -0,0 +1,105 @@
+# Directory Convention
+
+> Status: target layout for V1. Directories marked as V1 are created during implementation; see `docs/00-project/current-state.md`.
+
+## Root
+
+| Path | Purpose |
+|---|---|
+| `index.js` | Host entry shim; re-exports `lib/index.js` |
+| `client.js` | Client module (plain JS, module-loader format) |
+| `cordis.patch.yml` | Cordis bundle patch |
+| `package.json` | Bundle manifest, scripts, dependencies |
+| `tsconfig.json` | Host build configuration |
+| `lib/` | Build output; git-ignored |
+| `src/` | TypeScript Host sources |
+| `tests/` | Vitest tests and fixtures |
+| `data/` | Runtime registry data; git-ignored |
+| `locale/` | `en.json`, `zh.json` |
+| `docs/` | Project documentation |
+| `icon.svg` | Plugin icon |
+
+## `src/`
+
+```text
+src/
+├── index.ts            # apply(): wiring, tools, HTTP route
+├── config.ts           # schemastery Config
+├── logger.ts           # ctx logger wrapper
+├── domain/
+│   ├── types.ts        # interfaces and enums
+│   ├── schemas.ts      # Zod schemas, parseRecord
+│   ├── constants.ts    # operation ids, limits, patterns
+│   └── errors.ts       # EnvManagerError, codes
+├── storage/
+│   ├── paths.ts        # dataDir resolution, id/path guards
+│   ├── atomic.ts       # temp+fsync+rename write, backups
+│   ├── records.ts      # read/write/delete one record
+│   ├── sessions.ts     # session state files
+│   └── layout.ts       # directory creation, tmp cleanup
+├── registry/
+│   ├── registry.ts     # load, snapshot, lookup, reload
+│   ├── aliases.ts      # alias index
+│   └── integrity.ts    # referential integrity diagnostics
+├── resolver/
+│   ├── template.ts     # ${...} parsing and substitution
+│   ├── graph.ts        # reference graph, cycles
+│   ├── layers.ts       # build ordered layers
+│   ├── merge.ts        # field-level merge
+│   ├── context.ts      # ServiceContext assembly
+│   └── provenance.ts   # provenance construction
+├── router/
+│   ├── match.ts        # match level classification
+│   ├── router.ts       # selection, conflicts
+│   ├── skills.ts       # SkillDirectory adapter
+│   ├── policy.ts       # approval and production rules
+│   └── parameters.ts   # parameter mapping
+├── session/
+│   └── session-context.ts
+├── app/
+│   ├── app.ts          # use cases shared by tools and HTTP
+│   └── actor.ts        # 'agent' | 'ui' policy
+├── tools/
+│   ├── define.ts       # shared schemas and render helpers
+│   ├── approval.ts     # ctx.approval wrapper
+│   ├── read.ts         # env_list/get/find/get_context
+│   ├── resolve.ts      # env_resolve/resolve_operation
+│   ├── write.ts        # env_save/delete/set_context
+│   └── validate.ts     # env_validate
+├── transport/
+│   ├── route.ts        # webServer registration, body handling
+│   ├── auth.ts         # header, origin, size checks
+│   ├── ops.ts          # op table → app calls
+│   └── envelope.ts     # { ok, data } / { ok:false, error }
+└── memory-bridge/
+    ├── contract.ts
+    └── null-adapter.ts
+```
+
+`logger.ts` sits at the root because every module may log; it must not import them.
+
+## `tests/`
+
+```text
+tests/
+├── domain/
+├── storage/
+├── registry/
+├── resolver/
+├── router/
+├── session/
+├── app/
+├── tools/
+├── http/
+└── fixtures/
+```
+
+- One test file per module: `<module>.test.ts`.
+- Fixtures are small YAML files with obviously fake values.
+- Never commit real hostnames, IPs, URLs or credentials.
+
+## Adding a module
+
+1. It must fit an existing boundary in `module-boundaries.md`.
+2. A new boundary needs an ADR.
+3. Update the tree in this document and in `AGENTS.md`.

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

@@ -0,0 +1,55 @@
+# 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`.

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

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

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

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

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

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

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

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