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

package/docs/02-harness/client-ui-integration.md

@@ -0,0 +1,110 @@
+# Client UI Integration
+
+This note records the **host-side contract** a DSH bundle must follow when it adds a
+sidebar entry and a main panel. It is derived from the installed
+`@deepseek-ai/dsh-client-ui-sidebar` implementation (not from a mock), and from the
+working `dsh-image-router` bundle.
+
+Runtime source of truth:
+
+- `@deepseek-ai/dsh-client-ui-sidebar/lib/client.js`, function `PanelRow`.
+- The live slot catalog: `cordis_inspect_query` → `Slots.listSubTree` with root
+  `sidebar.panellist`, and root `main`.
+- Skill reference: `cordis-plugin-development/references/ui-plugin.md` and
+  `references/practices.md` (plugin UI is part of the Harness UI).
+
+## Sidebar entry
+
+The sidebar owns the row. A plugin contributes only the row's **icon** and **label**;
+it must not draw a button, row background, tooltip, margin, or hit area.
+
+### Registration
+
+```js
+ctx.slots.inject('sidebar.panellist', () =>
+  ctx.slots.register(
+    {
+      name: 'sidebar.panellist',
+      id: 'dsh-env-manager', // row key; also the main panel key
+      order: 40,
+      label: () => t('title'), // thunk, re-read on locale projection
+    },
+    SidebarGlyph,
+  ),
+)
+```
+
+Rules:
+
+1. `sidebar.panellist` is a **list** slot. Its registration fields are `id` (required),
+   `order`, and `label`. `id` must be unique; reusing a shipped id replaces that row.
+2. `name` is the common slots registration field. Include it; the live sidebar
+   registers only entries that carry their slot name.
+3. `label` is the row text and tooltip. Use a thunk when the text is localized so the
+   owner can re-read it without re-registering.
+4. The second argument is the glyph component. The owner renders it inside
+   `span.panelGlyph` and passes exactly `{ size, active }`.
+
+### Glyph contract
+
+The owner passes:
+
+- `size`: `16` when the sidebar is wide (`wide ? 16 : 18`);
+- `active`: whether this row is the selected panel.
+
+The glyph must:
+
+- render an inline `<svg>` with `viewBox="0 0 20 20"`,
+  `width={size}`, `height={size}`;
+- default defensively to `20` if `size` is missing or invalid;
+- use `fill="none"` and `stroke="currentColor"` (shipped icons are monochrome line
+  icons; they inherit light/dark theme colors);
+- use `opacity: 0.72` when `active === false`;
+- set `aria-hidden="true"` and omit `aria-label`/tooltip — the row button owns the
+  accessible name from `label`;
+- avoid fixed pixel width/height, background, border, border-radius, margin, or padding.
+
+A filled colored square at `48×48` is the common failure mode: it overflows the
+`panelGlyph` box, ignores the `size` prop, and looks like a different navigation
+control from the shipped rows.
+
+## Main panel
+
+```js
+ctx.slots.inject('main', () =>
+  ctx.slots.register(
+    { name: 'main', key: 'dsh-env-manager', inject: () => ({}) },
+    Panel,
+  ),
+)
+```
+
+- `main` is a **keyed** root slot. `key` must equal the sidebar `id`.
+- A sidebar id without a matching `main` key opens an empty page; a `main` key without
+  the sidebar id is unreachable.
+- The panel owns its own layout, header, and content. It fills the same region as
+  `conversation`.
+
+## Styling and localization
+
+- Use theme tokens (`--dsw-alias-*`) and `currentColor`; do not hard-code brand colors
+  in the sidebar glyph.
+- The host row supplies `.panelRow`, `.panelActive`, hover, focus, tooltip, and
+  `aria-current`.
+- Register the locale namespace best-effort, and make the sidebar `label` read the
+  active locale. Do not re-register the row to change language.
+
+## Verification
+
+After installing or changing the plugin:
+
+1. `Slots.listSubTree('sidebar.panellist')` must list the id with `active: true` and the
+   expected order.
+2. `Slots.listSubTree('main')` must list the same key as an occupant.
+3. Toggle the sidebar between wide and collapsed; the glyph must render at `16` and
+   `18` pixels respectively, with no clipping or colored background.
+4. Switch `en`/`zh`; the row label must change without a reload or duplicate row.
+5. Select the row and confirm the panel replaces the conversation region.
+
+Client changes are picked up by HMR while the Web client watcher is running; a newly
+installed bundle may need one page refresh before its module is present.

package/docs/02-harness/context-policy.md

@@ -0,0 +1,43 @@
+# Context Policy
+
+## What to Load Automatically
+
+For any non-trivial change, load:
+
+- `docs/00-project/project-brief.md`
+- `docs/00-project/current-state.md`
+- `docs/01-architecture/design.md`
+- `docs/01-architecture/detailed-design.md`
+- `docs/01-architecture/module-boundaries.md`
+- `docs/02-harness/harness-standard.md`
+
+## What to Load by Task Type
+
+### Adding or changing a tool
+
+- `docs/01-architecture/tool-contract.md`
+- `docs/01-architecture/detailed-design.md` §11
+- `docs/04-development/coding-style.md`
+- `docs/05-domain/operation-binding-template.md` (if routing related)
+
+### Changing rule resolution
+
+- `docs/01-architecture/design.md` §6
+- `docs/01-architecture/module-boundaries.md`
+- `docs/05-domain/rule-template.md`
+
+### Changing the HTTP transport or the UI
+
+- `docs/01-architecture/ui-design.md`
+- `docs/01-architecture/decisions/ADR-0009-client-host-http-transport.md`
+- `docs/01-architecture/security-model.md` §2, §4, §6
+- `docs/04-development/coding-style.md`
+
+### Checking a DSH runtime assumption
+
+- `docs/01-architecture/api-verification.md`
+
+### Deployment changes
+
+- `docs/06-operations/deployment-guide.md`
+- `docs/06-operations/security-policy.md`

package/docs/02-harness/harness-standard.md

@@ -0,0 +1,91 @@
+# Harness Standard
+
+## Purpose
+
+The harness ensures that AI-assisted development remains aligned with the project architecture, constraints, and verification expectations.
+
+## Harness Layers
+
+### 1. Context Layer
+
+Defines what the agent must know before work.
+
+Includes:
+
+- project brief
+- current state
+- design documents
+- module boundaries
+- storage contract
+
+### 2. Constraint Layer
+
+Defines what the agent must not violate.
+
+Includes:
+
+- no plain-text credentials in registry files
+- no arbitrary JavaScript/shell execution in rule templates
+- no auto-apply of production rule or skill changes
+- no unbounded evidence storage
+- no hidden durable state outside documented files
+
+### 3. Execution Layer
+
+Defines how work should be implemented.
+
+Includes:
+
+- small changes
+- testable modules
+- tools as thin wrappers over services
+- business logic in resolver/router modules
+- file-based state
+- clear output file contracts
+
+### 4. Verification Layer
+
+Defines how work is validated.
+
+Includes:
+
+- unit tests for resolvers and routers
+- fixture-based storage tests
+- manual Web/Desktop UI checklist
+- output file contract validation
+- regression tests for bugfixes
+
+### 5. Continuity Layer
+
+Defines how future agents resume work.
+
+Includes:
+
+- update `current-state.md`
+- update relevant docs
+- preserve ADRs
+- archive completed OpenSpec changes
+- avoid hidden assumptions
+
+## Required Agent Behavior
+
+Before implementation:
+
+1. Read the relevant docs.
+2. Identify affected modules.
+3. Identify storage contract impact.
+4. Identify tests to add.
+5. Keep scope small.
+
+During implementation:
+
+1. Prefer minimal changes.
+2. Avoid unrelated refactoring.
+3. Keep logic testable.
+4. Preserve file-based architecture.
+
+After implementation:
+
+1. Run or specify tests.
+2. Update docs if needed.
+3. Update `docs/00-project/current-state.md`.

package/docs/02-harness/task-execution-policy.md

@@ -0,0 +1,26 @@
+# Task Execution Policy
+
+## Scope
+
+Each task should be small enough to implement, test and review in one focused session.
+
+## Task Format
+
+Use the Tasks rule in `docs/03-openspec/tasks-rule.md`.
+
+## Execution Order
+
+1. Read context
+2. Propose plan
+3. Implement
+4. Test
+5. Update docs and current-state.md
+
+## Stopping Conditions
+
+Stop and report when:
+
+- the task scope becomes unclear
+- a storage contract change is required but not documented
+- a security or approval policy implication is discovered
+- tests fail and cannot be fixed within the task scope

package/docs/02-harness/verification-policy.md

@@ -0,0 +1,97 @@
+# Verification Policy
+
+Every implementation task must include at least one of:
+
+- unit tests for pure logic
+- integration tests for storage / registry / tools
+- a manual UI checklist
+- a contract check against a fixture
+
+## Required by module
+
+### `domain`
+
+- Valid record accepted; unknown field rejected
+- Id pattern and `schemaVersion` enforced
+- Discriminated union rejects mismatched runtime/location
+- `parseRecordInput` accepts omitted timestamps; `finalizeRecord` stamps them
+
+### `storage`
+
+- Atomic write/read round trip
+- No temp file left after success or a caught failure
+- Missing directory handled
+- Invalid YAML skipped with diagnostic, file kept
+- Backup pruning (max 5)
+
+### `registry`
+
+- Load and lookup
+- Duplicate id detection
+- Broken reference detection for every reference kind
+- Reload after write reflects the change
+- Concurrent loads share one in-flight scan
+
+### `resolver`
+
+- Layer precedence
+- Field-level merge
+- Provenance for the worked example
+- Undefined variable, cycle, path traversal, type mismatch, malformed template
+- Only runtime-applicable log source and class location resolved
+
+### `router`
+
+- Every match level
+- Highest-level selection
+- Same-level conflict
+- Skill availability: present, missing, source mismatch, provider mismatch,
+  registry unavailable or incomplete
+- Production policy and approval defaults
+- Parameter mapping failures
+
+### `session`
+
+- Set, get, clear
+- Cross-session isolation
+- Corrupt state treated as "no default", `persisted: false`
+
+### `app`
+
+- Save→get round trip
+- Delete refused while referenced
+- Dry-run writes nothing
+- UI actor production denial
+
+### `tools`
+
+- Returned value matches the declared `output.schema`
+- Expected failures throw `EnvManagerError` with the right code
+- No credential value in serialized output
+- `env_validate` is read-only
+- Approval denial changes nothing on disk
+
+### `transport`
+
+- Header, origin, method and size rejection
+- Status mapping for each error class
+- Production UI write denied by default
+- No stack trace or file path in the response body
+
+### Client UI (manual)
+
+- Panels load with empty and populated registries
+- Create/edit/delete round trip through the HTTP API
+- Rule preview shows provenance
+- Conflict warning appears for same-level bindings
+- Production actions are visually distinct and confirmed
+- Locale switches between `en` and `zh`
+- Full checklist: `docs/01-architecture/ui-design.md` §12
+
+## Evidence to record
+
+For each completed task, `current-state.md` should state what was verified and what remains manual.
+
+## Regression rule
+
+A bugfix must add a test that fails before the fix and passes after it, unless the defect is UI-only.

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

@@ -0,0 +1,25 @@
+# Archive Rule
+
+Completed or superseded proposals and designs must be archived in `docs/99-archive/`.
+
+## When to Archive
+
+- A proposal is implemented and verified.
+- A design is superseded by a new one.
+- A spike or experiment is abandoned.
+
+## Format
+
+Prefix archived files with date:
+
+```text
+docs/99-archive/YYYY-MM-DD-proposal-name.md
+```
+
+## Content
+
+Each archived file must include:
+
+- Original title and date
+- Reason for archiving
+- Link to the current approach (if superseded)

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

@@ -0,0 +1,30 @@
+# Bugfix Rule
+
+A bugfix addresses a specific, reproducible defect.
+
+## Required Sections
+
+### 1. Symptom
+
+What went wrong.
+
+### 2. Root Cause
+
+Why it happened.
+
+### 3. Fix
+
+What changed.
+
+### 4. Regression Test
+
+Test that prevents recurrence.
+
+### 5. Verification
+
+How to confirm the fix.
+
+## Rules
+
+- Include a regression test unless the bug is UI-only.
+- Update `current-state.md` if the bug affects implemented features.

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

@@ -0,0 +1,33 @@
+# Design Rule
+
+A design document explains how a feature will be built.
+
+## Required Sections
+
+### 1. Overview
+
+What is being designed and why.
+
+### 2. Data Flow
+
+Step-by-step flow with input/output boundaries.
+
+### 3. Module Allocation
+
+Which modules are involved and what each owns.
+
+### 4. Schema Changes
+
+New or changed YAML/JSON schemas.
+
+### 5. Security Considerations
+
+Credential handling, approval policies, production access.
+
+### 6. Error Handling
+
+Expected failure modes and responses.
+
+### 7. Verification Plan
+
+Tests and manual checks.

package/docs/03-openspec/openspec-usage-guide.md

@@ -0,0 +1,31 @@
+# OpenSpec Usage Guide
+
+Use OpenSpec artifacts to plan and track changes.
+
+## Artifact Types
+
+- **Proposal**: Why and what we will change.
+- **Design**: How we will build it.
+- **Spec**: Detailed implementation contract.
+- **Tasks**: Small, verifiable work items.
+- **Bugfix**: Specific defect resolution.
+
+## Workflow
+
+1. Create a proposal in `docs/03-openspec/proposals/` (or similar).
+2. Once accepted, write a design in `docs/01-architecture/designs/` (or update `design.md`).
+3. Turn the design into a spec.
+4. Break into tasks.
+5. Implement, verify, archive.
+
+## Naming
+
+- Proposals: `proposal-{short-name}.md`
+- Designs: `design-{short-name}.md`
+- Specs: `spec-{short-name}.md`
+- Tasks: embedded in implementation issue or PR description
+- Bugfixes: `bugfix-{short-name}.md`
+
+## Review
+
+Every OpenSpec artifact should be reviewed before implementation.

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

@@ -0,0 +1,70 @@
+# Proposal Rule
+
+A proposal must explain why the change is needed and what it changes.
+
+## Required Sections
+
+### 1. Problem
+
+Describe the user-visible or engineering problem.
+
+### 2. Goal
+
+Describe the intended outcome.
+
+### 3. Scope
+
+List what is included.
+
+### 4. Out of Scope
+
+List what is explicitly excluded.
+
+### 5. Affected Modules
+
+Choose from:
+
+- tools
+- domain
+- config
+- storage
+- registry
+- resolver
+- router
+- session
+- memory-bridge
+- client
+- docs
+
+### 6. Storage Impact
+
+State whether the change affects:
+
+- `data/environments/*.yaml`
+- `data/services/*.yaml`
+- `data/deployments/*.yaml`
+- `data/rules/*.yaml`
+- `data/operations/*.yaml`
+- `data/sessions/*.json`
+- `schemaVersion` (record compatibility)
+
+### 7. Constraints
+
+Must confirm:
+
+- No plain-text credentials introduced.
+- No arbitrary code execution in rule templates.
+- No auto-apply of production changes.
+- File-based source of truth remains unchanged.
+
+### 8. Risks
+
+List implementation risks.
+
+### 9. Verification
+
+Describe how to verify.
+
+## Proposal Quality Bar
+
+A good proposal is small enough to implement and test in one focused change.

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

@@ -0,0 +1,33 @@
+# Spec Rule
+
+A spec document turns a proposal into actionable implementation details.
+
+## Required Sections
+
+### 1. Objectives
+
+Clear, measurable outcomes.
+
+### 2. Functional Requirements
+
+What the system must do.
+
+### 3. Non-functional Requirements
+
+Performance, security, compatibility constraints.
+
+### 4. Interface Definitions
+
+Tool names, parameters, return values, events.
+
+### 5. Data Definitions
+
+Schemas for inputs, outputs and storage records.
+
+### 6. Acceptance Criteria
+
+Specific conditions that must be met.
+
+### 7. Open Questions
+
+Unresolved items to confirm before implementation.

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

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

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

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