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

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,8 @@
+/**
+ * DSH Environment Manager - Host entry point.
+ *
+ * The implementation lives in `lib/` (compiled from `src/`); this shim keeps the
+ * bundle entry stable across builds.
+ */
+
+export { name, inject, Config, apply } from './lib/index.js'

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;
+}