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

package/docs/06-operations/troubleshooting.md

@@ -0,0 +1,141 @@
+# Troubleshooting
+
+## Install fails with "Cannot find module .../lib/index.js"
+
+This means DSH found the bundle but the Host build output was absent or incomplete.
+
+1. Prefer the published package: `plugin_manager` → `install_bundle` with
+   `dsh-env-manager-plugin@0.1.1`. The npm tarball includes `lib/`.
+2. If installing a local checkout, use the current `main`; `lib/` is committed there on
+   purpose. Older clones did not include it.
+3. If the checkout is older or `lib/` was deleted, run `npm install && npm run build`
+   in the repository, then reinstall the bundle.
+4. Do not copy only `index.js` into a profile; the bundle needs `lib/`, `client.js`,
+   `cordis.patch.yml` and the locale files together.
+
+`index.js` now reports this condition with a dedicated message instead of a bare
+`ERR_MODULE_NOT_FOUND`.
+
+## DSH does not start: duplicate bundle registration
+
+The plugin must appear **once** in the profile. A failed manual install often leaves both
+an old `dsh-env-manager` entry and a new `dsh-env-manager-plugin` entry, which inserts the
+same loader row twice.
+
+For the affected profile, stop DSH, back up both files, and inspect:
+
+```powershell
+$p = Join-Path $HOME '.dsh\profiles\<profile>'
+Get-Content -Raw (Join-Path $p 'package.json')
+Get-ChildItem (Join-Path $p 'node_modules') | Where-Object Name -match 'env-manager'
+```
+
+In `package.json`:
+
+- keep `dsh-env-manager-plugin` exactly once in `dependencies`;
+- keep `dsh-env-manager-plugin` exactly once in `dsh.profile.bundles`;
+- remove the legacy `dsh-env-manager` dependency and bundle entry;
+- do not add a second bundle entry by hand.
+
+Then remove any stale `node_modules/dsh-env-manager` link and reinstall through
+`plugin_manager`. Do not copy files into the profile as a workaround.
+
+From a checkout you can run the repair helper before restarting:
+
+```powershell
+node scripts/repair-profile.mjs --profile <profile>
+node scripts/repair-profile.mjs --profile <profile> --fix
+```
+
+The helper edits only `package.json` (with a timestamped backup); it never deletes
+registry data. It lives in the repository and in `dsh-env-manager-plugin@0.1.1`+.
+
+## Plugin is not visible after install
+
+1. Ask `plugin_manager` for `action: list_bundles` — confirm the bundle is listed.
+2. Check the activation result for `failed` / `overridden` / `restart-required`.
+3. Restart DSH.
+
+## Host build fails
+
+1. Run `npm run build` and read the first error, not the count.
+2. Confirm `tsconfig.json` exists and `outDir` is `lib`.
+3. Check that `index.js` re-exports `./lib/index.js` and the file exists.
+
+## Tools are not registered
+
+1. Confirm the bundle is active.
+2. Check Host logs for an exception in `apply`.
+3. Call `env_list`: an empty list is correct on a fresh install; an unknown tool means registration failed.
+4. Reinstall after every Host rebuild; Host code changes need a fresh module generation.
+
+## Client panel does not appear
+
+1. Verify `client.js` is listed in `files` and exported as `./client`.
+2. Check the browser console for module-loader errors.
+3. Verify the slot id and name match a live slot.
+4. Reinstall the bundle after editing `client.js`.
+
+## Registry loads with warnings
+
+Warnings are expected when a file is invalid. They name the file and the field.
+
+1. Fix the YAML or the field.
+2. Run `env_validate` again.
+3. Invalid files are never deleted automatically, so the data is still on disk.
+
+## `env_resolve` returns `RULE_UNDEFINED_VARIABLE`
+
+1. The message names the field and the missing variable.
+2. Check that the variable exists in a referenced rule profile or in an environment/deployment override.
+3. Remember that only the deployment's runtime fields are in scope.
+
+## `RULE_CYCLE`
+
+Two or more fields reference each other. Break the cycle in the rule profile; the message contains the cycle path.
+
+## `RULE_PATH_TRAVERSAL`
+
+A resolved path contains a `..` segment. Fix the template; traversal is rejected by design.
+
+## `DEPLOYMENT_AMBIGUOUS`
+
+The service has several bindings in the environment. Pass `deploymentId` explicitly.
+
+## `BINDING_CONFLICT`
+
+Two enabled bindings match at the same level. Disable one, narrow one, or merge them. The plugin will not choose for you.
+
+## `SKILL_UNAVAILABLE`
+
+The bound Skill is not registered, or its source/provider does not match. Install or correct the Skill; do not add a fallback binding that changes the environment silently.
+
+## `POLICY_DENIED`
+
+Either the environment is production and the binding does not allow it, or an approval was denied. Fix the policy deliberately, not by flipping flags in a hurry.
+
+## Session default is not remembered
+
+If the tool reports `persisted: false`, the state file could not be written. Check `dataDir` permissions and the `sessions/` directory. The value is kept in a process-local cache, so it still works for this process but is lost on restart.
+
+## Panel says "Cannot reach the Host"
+
+1. Confirm the bundle is active and the Host is running.
+2. Reload the page; the panel uses a same-origin `POST /env-manager/api`.
+3. In the browser console, a 403 means the request header or origin check failed — this is the transport control, not a bug.
+4. A 404 means the route was not registered; reinstall the bundle after a Host rebuild.
+
+## Panel write is denied for a production record
+
+`writePolicy.allowUiProductionWrites` defaults to `false`. Edit the YAML through the Agent (`env_save`, with approval) or change the policy deliberately.
+
+## Panel shows "Unknown" skill availability
+
+The Skill catalog was absent or incomplete when the operation was resolved. Check that the Skill registry is available; the router never assumes a missing catalog means "available".
+
+## Storage errors
+
+1. Verify write permission on `dataDir`.
+2. Check that `dataDir` is not inside a read-only workspace.
+3. Confirm the file name matches the record `id`.
+4. Check `schemaVersion`; V1 only reads `1`.

package/docs/07-templates/adr-template.md

@@ -0,0 +1,21 @@
+# ADR-{NNNN}: Title
+
+## Status
+
+Proposed / Accepted / Superseded
+
+## Context
+
+What is the issue that we're seeing that is motivating this decision?
+
+## Decision
+
+What is the change that we're proposing or have accepted?
+
+## Consequences
+
+What becomes easier or more difficult to do because of this change?
+
+## Alternatives Considered
+
+What other approaches were considered and why were they rejected?

package/docs/07-templates/bugfix-template.md

@@ -0,0 +1,11 @@
+# Bugfix: {Name}
+
+## Symptom
+
+## Root Cause
+
+## Fix
+
+## Regression Test
+
+## Verification

package/docs/07-templates/case-template.md

@@ -0,0 +1,15 @@
+# Case: {Name}
+
+## Environment
+
+## Service
+
+## Operation
+
+## Expected Behavior
+
+## Actual Behavior
+
+## Resolution
+
+## Lessons Learned

package/docs/07-templates/design-template.md

@@ -0,0 +1,29 @@
+# Design: {Name}
+
+## Overview
+
+What is being designed and why.
+
+## Data Flow
+
+Step-by-step flow.
+
+## Module Allocation
+
+Which modules are involved and what each owns.
+
+## Schema Changes
+
+New or changed YAML/JSON schemas.
+
+## Security Considerations
+
+Credential handling, approval policies, production access.
+
+## Error Handling
+
+Expected failure modes and responses.
+
+## Verification Plan
+
+Tests and manual checks.

package/docs/07-templates/proposal-template.md

@@ -0,0 +1,19 @@
+# Proposal: {Name}
+
+## Problem
+
+## Goal
+
+## Scope
+
+## Out of Scope
+
+## Affected Modules
+
+## Storage Impact
+
+## Constraints
+
+## Risks
+
+## Verification

package/docs/07-templates/spec-template.md

@@ -0,0 +1,15 @@
+# Spec: {Name}
+
+## Objectives
+
+## Functional Requirements
+
+## Non-functional Requirements
+
+## Interface Definitions
+
+## Data Definitions
+
+## Acceptance Criteria
+
+## Open Questions

package/docs/07-templates/tasks-template.md

@@ -0,0 +1,12 @@
+# Tasks: {Name}
+
+- [ ] Task 1
+  - Files:
+  - Behavior:
+  - Tests:
+  - Verification:
+- [ ] Task 2
+  - Files:
+  - Behavior:
+  - Tests:
+  - Verification:

package/docs/99-archive/README.md

@@ -0,0 +1,13 @@
+# Archive
+
+This directory contains obsolete or historical documents.
+
+Do not rely on archived documents for current decisions.
+
+## Naming
+
+Prefix files with date:
+
+```text
+docs/99-archive/YYYY-MM-DD-title.md
+```

package/docs/README.md

@@ -0,0 +1,142 @@
+# DSH Environment Manager Docs
+
+This directory is the **project-level Harness Context Hub** for the DSH Environment Manager plugin.
+
+It is used by humans and AI agents to understand project state, architecture, constraints, development standards, and operational procedures.
+
+## Reading Policy
+
+Do not read every document blindly. Read documents based on task type.
+
+### Required for Every Non-trivial Change
+
+1. `AGENTS.md` at the repository root
+2. `docs/00-project/project-brief.md`
+3. `docs/00-project/current-state.md`
+4. `docs/02-harness/harness-standard.md`
+5. `docs/04-development/development-guide.md`
+
+### Architecture or Schema Changes
+
+Also read:
+
+1. `docs/01-architecture/design.md`
+2. `docs/01-architecture/data-model.md`
+3. `docs/01-architecture/detailed-design.md`
+4. `docs/01-architecture/module-boundaries.md`
+5. `docs/01-architecture/storage-contract.md`
+
+### Environment Model Questions
+
+Also read:
+
+1. `docs/01-architecture/decisions/ADR-0010-environment-plane-model.md`
+2. `docs/01-architecture/decisions/ADR-0011-k8s-node-execution-model.md`
+3. `docs/01-architecture/data-model.md` §3
+4. `docs/01-architecture/ui-design.md` §6.3
+
+### Runtime API Questions
+
+Also read:
+
+1. `docs/01-architecture/api-verification.md`
+2. `docs/01-architecture/decisions/ADR-0009-client-host-http-transport.md`
+
+### Implementation Work
+
+Also read:
+
+1. `docs/01-architecture/implementation-plan.md`
+2. `docs/01-architecture/ui-design.md` (Client changes only)
+3. `docs/02-harness/client-ui-integration.md` (sidebar/main slot changes only)
+
+### Tool Surface Changes
+
+Also read:
+
+1. `docs/01-architecture/tool-contract.md`
+2. `docs/01-architecture/data-model.md`
+3. `docs/01-architecture/detailed-design.md` §11
+
+### Resolver / Rule Work
+
+Also read:
+
+1. `docs/01-architecture/design.md` §6
+2. `docs/05-domain/rule-template.md`
+3. `docs/01-architecture/decisions/ADR-0005-layered-rule-resolution.md`
+
+### Router / Skill Binding Work
+
+Also read:
+
+1. `docs/01-architecture/design.md` §7
+2. `docs/05-domain/operation-binding-template.md`
+3. `docs/01-architecture/decisions/ADR-0003-skill-router-over-search.md`
+
+### Security-Sensitive Work
+
+Also read:
+
+1. `docs/01-architecture/security-model.md`
+2. `docs/06-operations/security-policy.md`
+
+### Deployment / Operations Work
+
+Also read:
+
+1. `docs/06-operations/deployment-guide.md`
+2. `docs/06-operations/release.md`
+3. `docs/06-operations/security-policy.md`
+4. `docs/06-operations/troubleshooting.md`
+
+### OpenSpec Work
+
+Also read:
+
+1. `docs/03-openspec/proposal-rule.md`
+2. `docs/03-openspec/design-rule.md`
+3. `docs/03-openspec/spec-rule.md`
+4. `docs/03-openspec/tasks-rule.md`
+
+## Hard Rules
+
+- Durable registry data is YAML files under the plugin data directory.
+- Registry data is never committed to Git.
+- Credentials are references only; values never appear in registry files or tool output.
+- Rule templates use interpolation only; no code execution.
+- Production write operations and production-affecting management writes require approval.
+- Conflicts, missing Skills and broken references fail loudly; nothing is chosen silently.
+- Every completed change updates `docs/00-project/current-state.md`.
+
+## Directory Map
+
+```text
+docs/
+├── 00-project/       # brief, current state, glossary, roadmap
+├── 01-architecture/  # design, data model, tools, storage, security, ADRs
+├── 02-harness/       # AI-assisted development harness standards
+├── 03-openspec/      # proposal/design/spec/tasks rules
+├── 04-development/   # coding, testing, local run, dependency rules
+├── 05-domain/        # environment/service/deployment/rule/binding templates
+├── 06-operations/    # deployment, release, security, troubleshooting
+├── 07-templates/     # reusable artifact templates
+└── 99-archive/       # obsolete or historical docs
+```
+
+### Architecture Index
+
+| Document | Purpose |
+|---|---|
+| `architecture-overview.md` | layers, components, request flows |
+| `design.md` | V1 scope, algorithms, acceptance criteria |
+| `detailed-design.md` | module contracts, algorithms, tool/HTTP specs, tests |
+| `data-model.md` | record schemas and result types |
+| `tool-contract.md` | model-facing tool inputs, outputs, errors |
+| `storage-contract.md` | files, atomicity, sessions, migration |
+| `module-boundaries.md` | module ownership and dependencies |
+| `ui-design.md` | panels, transport, states, i18n, QA checklist |
+| `security-model.md` | credential, policy and redaction controls |
+| `api-verification.md` | verified DSH runtime facts and open probes |
+| `implementation-plan.md` | ordered tasks, acceptance, cut line |
+| `decisions/ADR-*.md` | accepted decisions (ADR-0009 = UI transport, ADR-0010 = environment/plane model, ADR-0011 = K8s node/access model) |

package/icon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <circle cx="32" cy="32" r="28" fill="#0ea5e9"/>
+  <path d="M22 20h20v8H22zm0 14h20v8H22z" fill="#ffffff"/>
+</svg>

package/index.js

@@ -0,0 +1,31 @@
+/**
+ * DSH Environment Manager - Host entry point.
+ *
+ * The implementation lives in `lib/` (compiled from `src/`); this shim keeps the
+ * bundle entry stable across builds. `lib/` is committed so a checkout, git
+ * install or npm tarball all have the same executable entry.
+ */
+
+let implementation
+
+try {
+  implementation = await import('./lib/index.js')
+} catch (error) {
+  const missingLib =
+    error &&
+    error.code === 'ERR_MODULE_NOT_FOUND' &&
+    /lib[\\/]index\.js/.test(String(error.message))
+
+  if (missingLib) {
+    throw new Error(
+      '[dsh-env-manager-plugin] Missing build output: lib/index.js. ' +
+        'Install the published `dsh-env-manager-plugin` package, or run ' +
+        '`npm install && npm run build` in the plugin checkout before installing it.',
+      { cause: error },
+    )
+  }
+
+  throw error
+}
+
+export const { name, inject, Config, apply } = implementation

package/lib/app/app.d.ts

@@ -0,0 +1,67 @@
+import type { Actor, CredentialDirectory, Diagnostic, FindResult, GetResult, ListResult, MetaResult, OperationResolution, RecordKind, RemoveOptions, RemoveResult, ResolveRequest, RouteRequest, SaveOptions, SaveResult, ServiceContext, SessionContext, SkillDirectory, ValidationReport } from '../domain/types.js';
+import type { Logger } from '../logger.js';
+export declare const VERSION = "0.1.0";
+export interface AppOptions {
+    dataDir: string;
+    maxRecords: number;
+    writePolicy: {
+        allowUiProductionWrites: boolean;
+    };
+    skills: SkillDirectory | null;
+    credentials: CredentialDirectory | null;
+    logger: Logger;
+    defaults?: {
+        environmentId?: string;
+    };
+}
+export interface SaveContext {
+    actor?: Actor;
+}
+export interface GetContextOptions {
+    actor?: Actor;
+}
+export interface ResolveOutcome {
+    context: ServiceContext;
+    warnings: Diagnostic[];
+}
+export declare class App {
+    private readonly options;
+    private readonly loader;
+    private readonly sessions;
+    constructor(options: AppOptions);
+    get dataDir(): string;
+    init(): Promise<void>;
+    private snapshot;
+    private counts;
+    private warnings;
+    meta(): Promise<MetaResult>;
+    list(kind: RecordKind): Promise<ListResult>;
+    get(kind: RecordKind, id: string): Promise<GetResult>;
+    find(query: string): Promise<FindResult>;
+    saveYaml(kind: RecordKind, yaml: string, options?: SaveOptions & SaveContext): Promise<SaveResult>;
+    save(kind: RecordKind, raw: unknown, options?: SaveOptions & SaveContext): Promise<SaveResult>;
+    remove(kind: RecordKind, id: string, actor: Actor, options?: RemoveOptions): Promise<RemoveResult>;
+    validate(): Promise<ValidationReport>;
+    /**
+     * Store one SSH/web credential in the DSH credential service and return only
+     * its reference. Registry YAML must never contain the value itself.
+     */
+    setCredential(ref: string, value: string): Promise<{
+        ref: string;
+        configured: boolean;
+    }>;
+    /** Remove a credential owned by this plugin; other namespaces are rejected. */
+    unsetCredential(ref: string): Promise<{
+        ref: string;
+        removed: true;
+    }>;
+    resolve(request: ResolveRequest): Promise<ResolveOutcome>;
+    route(request: RouteRequest): Promise<OperationResolution>;
+    getContext(sessionId: string): Promise<SessionContext>;
+    setContext(sessionId: string, environmentId: string | null): Promise<SessionContext>;
+    needsProductionApproval(kind: RecordKind, raw: unknown): Promise<boolean>;
+    private mapFor;
+    private selectDeployment;
+    private isProductionRecord;
+    private describeCredentials;
+}