dsh-env-manager-plugin 0.1.0 → 0.1.1

package/docs/03-openspec/tasks-rule.md

@@ -1,31 +1,31 @@
-# Tasks Rule
-
-Tasks must be small and verifiable.
-
-## Task Format
-
-```markdown
-- [ ] Task name
-  - Files:
-  - Behavior:
-  - Tests:
-  - Verification:
-```
-
-## Rules
-
-- Do not combine unrelated modules in one task.
-- Do not add broad refactoring tasks.
-- Every implementation task must include tests or manual verification.
-- Docs must be updated when behavior or storage contract changes.
-- `docs/00-project/current-state.md` must be updated at the end.
-
-## Good Task Example
-
-```markdown
-- [ ] Implement environment registry storage
-  - Files: src/storage/environment.js, tests/storage/environment.test.js
-  - Behavior: read/write environment records atomically
-  - Tests: create, read, update, missing file
-  - Verification: npm test tests/storage/environment.test.js
-```
+# Tasks Rule
+
+Tasks must be small and verifiable.
+
+## Task Format
+
+```markdown
+- [ ] Task name
+  - Files:
+  - Behavior:
+  - Tests:
+  - Verification:
+```
+
+## Rules
+
+- Do not combine unrelated modules in one task.
+- Do not add broad refactoring tasks.
+- Every implementation task must include tests or manual verification.
+- Docs must be updated when behavior or storage contract changes.
+- `docs/00-project/current-state.md` must be updated at the end.
+
+## Good Task Example
+
+```markdown
+- [ ] Implement environment registry storage
+  - Files: src/storage/environment.js, tests/storage/environment.test.js
+  - Behavior: read/write environment records atomically
+  - Tests: create, read, update, missing file
+  - Verification: npm test tests/storage/environment.test.js
+```

package/docs/04-development/coding-style.md

@@ -1,67 +1,67 @@
-# Coding Style
-
-## TypeScript (Host)
-
-- `strict: true`; do not disable it locally.
-- Prefer `interface` for records, `type` for unions and aliases.
-- No `any` at module boundaries. Use `unknown` and validate.
-- Validate all external input (YAML, tool arguments) with Zod.
-- Prefer `readonly` for data that must not be mutated.
-- Pure functions (`resolver`, `router`, `domain`) return discriminated unions for
-  expected failures:
-
-```ts
-type ResolveResult =
-  | { ok: true; context: ServiceContext }
-  | { ok: false; diagnostics: Diagnostic[] };
-```
-
-- Tool and HTTP boundaries throw `EnvManagerError extends HarnessError`; they never
-  return an `{ ok: false }` value. Catch unexpected errors and wrap them as
-  `INTERNAL_ERROR` with a redacted message.
-- No floating promises. Await or return them.
-
-## Purity
-
-- `resolver` and `router` are pure: no I/O, no clock, no randomness, no globals.
-- Inject dependencies (`SkillDirectory`, `CredentialDirectory`) as parameters.
-- Storage and registry may hold state; keep it inside instances, not module scope.
-
-## Naming
-
-| Kind | Style | Example |
-|---|---|---|
-| files | kebab-case | `service-context.ts` |
-| types/interfaces | PascalCase | `DeploymentBinding` |
-| functions | camelCase | `resolveContext` |
-| constants | UPPER_SNAKE_CASE | `WRITE_OPERATIONS` |
-| record ids | kebab-case | `deploy-001` |
-
-## Error handling
-
-- Every failure carries a `code` from the diagnostics catalogue.
-- Messages are user-facing and must not include secrets.
-- Never swallow an error silently. If it is expected, convert it to a diagnostic.
-
-## JavaScript (Client)
-
-- ES modules; the artifact is the module-loader wrapper.
-- `React.createElement` (`h(...)`), no JSX.
-- No global side effects at module load beyond `load({...})`.
-- Register slots with `ctx.slots.inject` (it owns cleanup); wrap any other listener or
-  disposable in `ctx.effect` and return its cleanup.
-- Route visible text through the client locale service.
-
-## Formatting
-
-- 2 spaces
-- single quotes
-- no semicolons
-- trailing commas in multi-line literals
-- LF line endings
-
-## Comments
-
-- JSDoc on exported functions and non-obvious invariants.
-- Explain why, not what.
-- Reference the design section when implementing a non-trivial rule, e.g. `// design §6.4`.
+# Coding Style
+
+## TypeScript (Host)
+
+- `strict: true`; do not disable it locally.
+- Prefer `interface` for records, `type` for unions and aliases.
+- No `any` at module boundaries. Use `unknown` and validate.
+- Validate all external input (YAML, tool arguments) with Zod.
+- Prefer `readonly` for data that must not be mutated.
+- Pure functions (`resolver`, `router`, `domain`) return discriminated unions for
+  expected failures:
+
+```ts
+type ResolveResult =
+  | { ok: true; context: ServiceContext }
+  | { ok: false; diagnostics: Diagnostic[] };
+```
+
+- Tool and HTTP boundaries throw `EnvManagerError extends HarnessError`; they never
+  return an `{ ok: false }` value. Catch unexpected errors and wrap them as
+  `INTERNAL_ERROR` with a redacted message.
+- No floating promises. Await or return them.
+
+## Purity
+
+- `resolver` and `router` are pure: no I/O, no clock, no randomness, no globals.
+- Inject dependencies (`SkillDirectory`, `CredentialDirectory`) as parameters.
+- Storage and registry may hold state; keep it inside instances, not module scope.
+
+## Naming
+
+| Kind | Style | Example |
+|---|---|---|
+| files | kebab-case | `service-context.ts` |
+| types/interfaces | PascalCase | `DeploymentBinding` |
+| functions | camelCase | `resolveContext` |
+| constants | UPPER_SNAKE_CASE | `WRITE_OPERATIONS` |
+| record ids | kebab-case | `deploy-001` |
+
+## Error handling
+
+- Every failure carries a `code` from the diagnostics catalogue.
+- Messages are user-facing and must not include secrets.
+- Never swallow an error silently. If it is expected, convert it to a diagnostic.
+
+## JavaScript (Client)
+
+- ES modules; the artifact is the module-loader wrapper.
+- `React.createElement` (`h(...)`), no JSX.
+- No global side effects at module load beyond `load({...})`.
+- Register slots with `ctx.slots.inject` (it owns cleanup); wrap any other listener or
+  disposable in `ctx.effect` and return its cleanup.
+- Route visible text through the client locale service.
+
+## Formatting
+
+- 2 spaces
+- single quotes
+- no semicolons
+- trailing commas in multi-line literals
+- LF line endings
+
+## Comments
+
+- JSDoc on exported functions and non-obvious invariants.
+- Explain why, not what.
+- Reference the design section when implementing a non-trivial rule, e.g. `// design §6.4`.

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

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

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

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