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

package/docs/01-architecture/implementation-plan.md

@@ -0,0 +1,323 @@
+# Implementation Plan (V1)
+
+> Status: ordered, executable plan for the V1 scope defined in
+> [`design.md`](design.md) and [`detailed-design.md`](detailed-design.md).
+> Every task ends with a build, its tests, and a documentation touch where behavior
+> changed. Do not reorder P1–P4: each later phase imports the previous one's types.
+>
+> Implementation snapshot (2026-11-01): T01, T03–T22 are implemented; `npm run build` and
+> 34 Vitest tests pass. The bundle is installed in the `desktop` profile and live-verified
+> for tools, HTTP API and slot registration. T02 live approval/credential probes, visual
+> panel QA and the final smoke checklist remain. See
+> [`current-state.md`](../00-project/current-state.md).
+
+## 1. Deliverable
+
+A DSH bundle that:
+
+1. registers ten `env_*` tools;
+2. stores an environment/service/deployment/rule/binding registry as YAML files;
+3. resolves layered rules with provenance;
+4. routes operations to Skills without executing them;
+5. exposes a same-origin HTTP API and a Web/Desktop management panel;
+6. keeps session defaults isolated per session.
+
+## 2. Foundations
+
+### T01 — Build skeleton
+
+Files:
+
+- `package.json`: scripts, dependencies, `files`, `exports`, `dsh`.
+- `tsconfig.json`: `target ES2022`, `module NodeNext`, `moduleResolution NodeNext`,
+  `strict`, `declaration`, `outDir lib`, `rootDir src`, `sourceMap false`.
+- `.gitignore`: add `data/`, `lib/`, `*.tsbuildinfo`.
+- `index.js`: `export * from './lib/index.js'`.
+- `src/index.ts`: minimal `apply` that logs the resolved data dir.
+
+Scripts:
+
+```json
+{
+  "build": "tsc -p tsconfig.json",
+  "build:watch": "tsc -p tsconfig.json --watch",
+  "test": "vitest run",
+  "test:watch": "vitest",
+  "check:client": "node --check client.js"
+}
+```
+
+Dependencies:
+
+| Package | Kind | Version |
+|---|---|---|
+| `@deepseek-ai/dsh-tools` | peer + dev | `0.2.1-rc.5` |
+| `@deepseek-ai/dsh-llm` | peer + dev | `0.2.1-rc.5` |
+| `@deepseek-ai/cordis` | peer + dev (type-only) | `~4.0.5` |
+| `@deepseek-ai/schemastery` | dependency | `^3.18.5` |
+| `zod` | dependency | `^4` |
+| `yaml` | dependency | `^2` |
+| `typescript`, `vitest`, `@types/node` | dev | latest compatible |
+
+Acceptance: `npm install && npm run build && node --check client.js` succeeds; `lib/index.js`
+exists; no `data/` is tracked.
+
+Risk: npm publishes `0.2.1-rc.5` under a non-`latest` tag (verify with
+`npm view <pkg> versions`). If a peer cannot be resolved, fall back to local ambient
+declarations in `src/types/dsh.d.ts` and keep runtime imports unchanged.
+
+### T02 — Runtime probes
+
+Verify `api-verification.md` §4 V1–V8 against a live profile, in this order:
+
+1. `profileContext.dir` and write permission.
+2. `slots.register` with `main`/`key`.
+3. `fetch('/env-manager/api')` from the panel (after T18).
+4. `approval.request` from a tool body.
+5. Output schema with `additionalProperties: true`.
+6. `CredentialRef` accepting a plain string.
+7. Windows directory behavior (no watcher required in V1).
+8. `/env-manager/api` prefix not claimed by the shell.
+
+Record the outcome in `api-verification.md` §4 (replace "verify" with the result).
+Acceptance: each item has a pass/fail note and, on failure, the fallback is applied.
+
+## 3. Domain and storage
+
+### T03 — Domain model
+
+Files: `src/domain/types.ts`, `src/domain/schemas.ts`, `src/domain/constants.ts`,
+`src/domain/errors.ts`.
+
+Include: enums, record interfaces, Zod schemas, `parseRecord`, `ErrorCode` union,
+`EnvManagerError`, `normalizeId`, `nowIso`.
+
+Tests (`tests/domain/schemas.test.ts`): valid records from the docs; unknown keys
+(rejected on save, preserved on read); bad id; bad timestamp; `location.kind` mismatch;
+empty `deployModes`.
+
+Acceptance: every YAML example in `docs/05-domain/*.md` parses.
+
+### T04 — Storage
+
+Files: `src/storage/paths.ts`, `atomic.ts`, `records.ts`, `sessions.ts`, `layout.ts`.
+
+Behavior: data dir resolution (§4.1), id/path guards, atomic write with backup
+rotation, read with diagnostics, delete, session read/write, startup `.tmp` cleanup.
+
+Tests (`tests/storage/*.test.ts`): round trip; missing file; invalid YAML; traversal
+rejection; backup cap; concurrent writes serialize; session corrupt fallback.
+
+Acceptance: no write leaves a partial file; a killed write leaves only a `.tmp`.
+
+## 4. Registry
+
+### T05 — Loader and snapshot
+
+Files: `src/registry/registry.ts`, `src/registry/aliases.ts`.
+
+Behavior: scan five directories, parse, skip invalid with diagnostics, duplicate id,
+alias map, deterministic ordering, in-flight dedupe, reload per request.
+
+Tests: empty dirs; mixed valid/invalid; duplicate id; alias collision; reload after
+write.
+
+### T06 — Integrity
+
+Files: `src/registry/integrity.ts`.
+
+Behavior: table in `detailed-design.md` §6.3, diagnostics only.
+
+Tests: each reference kind missing; a completely consistent fixture yields zero
+errors.
+
+## 5. Resolver
+
+### T07 — Template engine
+
+Files: `src/resolver/template.ts`, `src/resolver/graph.ts`.
+
+Behavior: scanner (§7.1), ref graph, iterative DFS, cycle path, undefined refs.
+
+Tests: literals; multiple refs; malformed `${`; `}` alone; cycle A→B→A; self-cycle;
+undefined; 2048-char cap.
+
+### T08 — Layers, merge, context
+
+Files: `src/resolver/layers.ts`, `merge.ts`, `context.ts`, `provenance.ts`.
+
+Behavior: ordered layers, field-level merge, shadowed list, eager field selection,
+runtime-specific log source and class location, path traversal check, provenance.
+
+Tests: the worked example from `design.md` §6.9; environment override changes a
+dependent path while `definedBy` stays at the service layer; deployment variables win;
+missing optional deployment.
+
+Acceptance: AC-03 and AC-04 pass.
+
+## 6. Router
+
+### T09 — Matching and selection
+
+Files: `src/router/match.ts`, `src/router/router.ts`.
+
+Behavior: eligibility, level derivation, top-level selection, same-level conflict with
+all candidates.
+
+Tests: each level; higher level wins; disabled binding ignored; conflict; no binding.
+
+### T10 — Skills, policy, parameters
+
+Files: `src/router/skills.ts`, `policy.ts`, `parameters.ts`.
+
+Behavior: `SkillDirectory` adapter over `ctx.skills` (`snapshot`, `complete`), source
+and provider checks, write-operation approval defaults, production denial, template
+parameters.
+
+Tests: fake directory for present/missing/incomplete/source mismatch/provider
+mismatch; production denial; parameter failure on unresolved ref; 50-parameter cap.
+
+Acceptance: AC-05…AC-07 pass.
+
+## 7. Session and application
+
+### T11 — Session store
+
+Files: `src/session/session-context.ts`.
+
+Tests: set/get/clear; two sessions isolated; corrupt file; unwritable dir →
+`persisted: false`.
+
+### T12 — Application service
+
+Files: `src/app/app.ts`, `src/app/actor.ts`.
+
+Behavior: `meta/list/get/find/save/saveYaml/remove/validate/resolve/route` and context
+access, actor policy, dry-run validation, record cap.
+
+Tests: save→get; delete referenced; dry-run writes nothing; UI production denial;
+`find` by alias.
+
+Acceptance: AC-01, AC-02, AC-08 pass at this layer.
+
+## 8. Tools
+
+### T13 — Tool scaffolding
+
+Files: `src/tools/define.ts`, `src/tools/envelope.ts`, `src/tools/approval.ts`.
+
+Shared schemas, `render` helpers, `EnvManagerError` mapping, approval helper.
+
+### T14 — Read tools
+
+Files: `src/tools/read.ts` (`env_list`, `env_get`, `env_find`, `env_get_context`).
+
+Tests: output matches schema for each; invalid id code; empty registry; context with
+and without a default.
+
+### T15 — Resolve and route tools
+
+Files: `src/tools/resolve.ts` (`env_resolve`, `env_resolve_operation`).
+
+Tests: session default fallback; ambiguous deployment; conflict; skill unavailable;
+production denial.
+
+### T16 — Write tools
+
+Files: `src/tools/write.ts` (`env_set_context`, `env_save`, `env_delete`).
+
+Tests: create/update; dry-run; approval grant and denial; production save approval;
+delete referenced → `RECORD_IN_USE`; delete approved removes the file.
+
+### T17 — Validate tool
+
+Files: `src/tools/validate.ts`.
+
+Tests: clean fixture → `ok: true`; broken reference appears with file and code.
+
+Acceptance: all ten tools are visible and match `tool-contract.md`.
+
+## 9. HTTP transport
+
+### T18 — Route
+
+Files: `src/transport/route.ts`, `src/transport/auth.ts`, `src/transport/ops.ts`,
+`src/transport/envelope.ts`.
+
+Behavior: registration, header and origin checks, body limit, op table, status map,
+actor `'ui'`, logging.
+
+Tests (node http mocks): missing header 403; wrong origin 403; GET 405; oversize 413;
+unknown op 400; not found 404; conflict 409; production write 403; happy path 200.
+
+Acceptance: `curl` with the header returns `meta`; without it returns 403.
+
+## 10. Client
+
+### T19 — Module shell
+
+Files: `client.js`.
+
+Behavior: module loader wrapper, `inject`, locale registration (`en`/`zh`), sidebar
+registration, `main` panel registration, `call()` helper, shared UI atoms.
+
+Acceptance: panel appears; empty state renders; no console error.
+
+### T20 — Lists and editor
+
+Behavior: Overview, record lists with search, YAML editor with validate/save/delete,
+dirty guard, production banner.
+
+Acceptance: manual QA items 1–8 in `ui-design.md` §12.
+
+### T21 — Context, operation, diagnostics
+
+Behavior: provenance tables with expansion, binding selection with conflict card,
+diagnostics table, bundle config page.
+
+Acceptance: manual QA items 9–12.
+
+### T22 — Manual QA pass
+
+Run the full checklist in `ui-design.md` §12 in Web and Desktop, light and dark, `en`
+and `zh`. Record results in `current-state.md`.
+
+## 11. Packaging and release
+
+### T23 — Docs and state
+
+Update `docs/00-project/current-state.md`, `docs/README.md` index if files moved, and
+`README.md` status. No architecture change without an ADR.
+
+### T24 — Install smoke test
+
+Install with `plugin_manager` (`install_bundle`, target = repository path), restart
+DSH, run:
+
+1. `env_validate` → clean;
+2. `env_list` → includes a fixture created by `env_save`;
+3. open the panel → Overview counts match;
+4. set a session default with `env_set_context`, reopen the session, `env_get_context`
+   returns it;
+5. remove the fixture with `env_delete` (approval), confirm the file is gone.
+
+## 12. Cut line
+
+If time runs short, ship in this order and stop at a green build:
+
+1. P0–P7 (Host complete, tools work through the agent).
+2. T18 + T19–T20 (read/write UI for environments and services).
+3. T21 (context/operation preview and diagnostics).
+4. T22 full QA.
+
+Never cut: storage atomicity, resolver provenance, router conflict handling, approval
+on delete, credential redaction.
+
+## 13. Definition of done
+
+- [ ] `npm run build` clean.
+- [ ] `npm test` green with the coverage in `detailed-design.md` §16.
+- [ ] Ten tools registered and documented.
+- [ ] Manual QA checklist complete.
+- [ ] No plain-text credential; no `..` path escape; no auto-apply.
+- [ ] `current-state.md` reflects what shipped and what did not.

package/docs/01-architecture/module-boundaries.md

@@ -0,0 +1,306 @@
+# Module Boundaries
+
+Status: normative for V1.
+
+Modules are directories under `src/` (Host, TypeScript). The Client half is a single `client.js` module at the repository root.
+
+Related: [design.md](./design.md) §3, [detailed-design.md](./detailed-design.md) §2, [storage-contract.md](./storage-contract.md), [tool-contract.md](./tool-contract.md).
+
+---
+
+## 1. Dependency direction
+
+```text
+tools ────────┐
+              ├──▶ app ──▶ resolver ──▶ registry ──▶ storage ──▶ fs
+transport ────┘      │          │            │
+                     │          └──▶ domain ◀┘
+                     ├──▶ router ──▶ resolver (context only)
+                     ├──▶ session ──▶ storage
+                     └──▶ memory-bridge ──▶ (external contract)
+
+client ──▶ transport (HTTP) ──▶ app
+```
+
+Rules:
+
+- `domain` has no dependencies.
+- `storage` depends on `domain`.
+- `registry` depends on `storage` and `domain`.
+- `resolver` and `router` depend on `domain` and `registry` types, never on `storage` or `tools`.
+- `app` composes storage, registry, resolver, router, session and config; it is the only
+  module that knows all of them.
+- `tools` and `transport` depend on `app` and `domain`; neither contains business logic
+  and neither imports the other.
+- No module imports `tools` or `transport` except the Host entry point (`src/index.ts`).
+- `client.js` depends on the HTTP API, never on `src/` modules.
+
+Cycles are forbidden. A cycle means the boundary is wrong.
+
+---
+
+## 2. `domain`
+
+Owns the shapes.
+
+Allowed:
+
+- TypeScript interfaces and type guards for all records, results and diagnostics.
+- Zod schemas that mirror the interfaces.
+- Enums and constants (operation ids, categories, runtime modes).
+- Pure helpers that operate on the types.
+
+Forbidden:
+
+- File I/O.
+- Tool registration.
+- Resolution or routing logic.
+- Importing any other project module.
+
+---
+
+## 3. `storage`
+
+Owns bytes on disk.
+
+Responsibilities:
+
+- Resolve `dataDir` and create directories.
+- Read, parse, validate and write one record file.
+- Atomic write protocol.
+- Rolling backups.
+- Session state files.
+- Surface storage errors as typed errors with codes.
+
+Forbidden:
+
+- Cross-record validation (registry owns it).
+- Template resolution.
+- Skill matching.
+- Credential access.
+
+---
+
+## 4. `registry`
+
+Owns the in-memory view.
+
+Responsibilities:
+
+- Load all record directories into maps.
+- Reload affected entries after writes.
+- Enforce id uniqueness and filename/id agreement.
+- Enforce referential integrity (data-model §12).
+- Provide lookups: by id, by alias, list by category, deployments by service, deployments by environment.
+- Produce load diagnostics.
+
+Forbidden:
+
+- Writing files (uses `storage`).
+- Running templates.
+- Registering tools.
+- Holding mutable session state.
+
+---
+
+## 5. `resolver`
+
+Owns context and rule resolution.
+
+Responsibilities:
+
+- Select the deployment binding (explicit id or unique match).
+- Merge rule layers with field-level precedence.
+- Resolve templates with cycle detection and undefined-variable detection.
+- Validate resolved paths.
+- Build `ServiceContext` with provenance.
+- Build `ProvenanceEntry[]`.
+
+Forbidden:
+
+- File I/O.
+- Tool registration.
+- Credential resolution (status is injected by the caller).
+- Skill matching.
+
+Purity is required: all inputs are passed in, no globals, no clocks, no randomness.
+
+---
+
+## 6. `router`
+
+Owns operation-to-Skill matching.
+
+Responsibilities:
+
+- Classify each binding's match level.
+- Filter by eligibility.
+- Detect same-level conflicts.
+- Verify Skill references through an injected `SkillDirectory` interface.
+- Evaluate approval and production policy.
+- Map parameters with the resolver's template engine.
+- Build `OperationResolution` with diagnostics.
+
+Forbidden:
+
+- Executing Skills.
+- Reading files.
+- Accessing credentials.
+- Choosing a fallback binding.
+
+`SkillDirectory` is an interface, so tests use a fake and the Host adapter uses the real registry when available.
+
+---
+
+## 7. `session`
+
+Owns per-session default environment.
+
+Responsibilities:
+
+- `get(sessionId)`, `set(sessionId, environmentId | null)`.
+- Persist through `storage` (or the DSH session API when available).
+- Expose `{ environmentId, persisted }` to tools.
+
+Forbidden:
+
+- Mutating registry records.
+- Reading other sessions' state.
+- Deciding policy.
+
+---
+
+## 8. `app`
+
+Owns the use cases. One function per tool and per HTTP operation.
+
+Responsibilities:
+
+- Compose storage, registry, resolver, router and session for a request.
+- Apply the record cap, actor policy and dry-run.
+- Reload the registry after a successful write.
+- Return domain results or throw `EnvManagerError`.
+
+Forbidden:
+
+- Tool registration or HTTP parsing.
+- Rendering text for the model or the UI.
+- Re-implementing resolution, routing or persistence.
+
+`app` is the only module both `tools` and `transport` call, so the two surfaces cannot
+drift.
+
+---
+
+## 9. `memory-bridge`
+
+Owns the optional P1 integration.
+
+Responsibilities:
+
+- Define `MemoryBridge`, `MemoryScope`, `OperationRecord`, proposal types.
+- Provide a null adapter that reports `MEMORY_BRIDGE_UNAVAILABLE`.
+- Redact and bound records before emission.
+
+Forbidden:
+
+- Writing registry files.
+- Auto-applying proposals.
+- Owning a second copy of environment facts.
+
+---
+
+## 10. `tools`
+
+Owns the Agent-facing surface.
+
+Responsibilities:
+
+- Register `defineTool` definitions with `ctx.tools.register`.
+- Declare parameter and output schemas.
+- Apply approval gates for management writes.
+- Map `app` results to the declared JSON value and `render` text.
+- Throw `EnvManagerError` for expected failures.
+
+Forbidden:
+
+- Business logic beyond orchestration.
+- Direct file access.
+- Re-implementing resolution, routing or persistence.
+
+---
+
+## 11. `transport`
+
+Owns the Client-facing HTTP surface.
+
+Responsibilities:
+
+- Register and dispose the `/env-manager/api` route.
+- Enforce method, content type, request header, origin and body limits.
+- Map `{ op, payload }` to `app` calls.
+- Map `EnvManagerError` codes to status codes.
+- Log writes with actor, op, kind, id and outcome.
+
+Forbidden:
+
+- Business logic.
+- Reading credentials.
+- CORS headers or cookie handling.
+- Serving files or static assets.
+
+---
+
+## 12. `config`
+
+Owns plugin configuration.
+
+Responsibilities:
+
+- Define the config schema (`dataDir`, limits).
+- Validate at activation.
+- Provide resolved defaults.
+
+Forbidden:
+
+- Reading registry files at config-validation time.
+- Network access.
+
+---
+
+## 13. `client.js`
+
+Owns the Web/Desktop surface.
+
+Allowed:
+
+- Render panels and forms.
+- Call the plugin HTTP API.
+- Use the client locale, slots and theme services.
+- Register slots and clean up on unmount.
+
+Forbidden:
+
+- Reading or writing registry files.
+- Re-implementing rule resolution or routing.
+- Holding durable state outside the Host.
+- Global side effects at module load.
+
+---
+
+## 14. Host entry
+
+`src/index.ts` is the only place that wires modules together.
+
+Responsibilities:
+
+- Read config, build storage/registry/resolver/router/session/app.
+- Register tools and their cleanup.
+- Register the HTTP route and its cleanup.
+- Register the Client module metadata.
+- Log the resolved data directory once.
+
+Forbidden:
+
+- Business logic.
+- Direct tool or transport implementations.