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

package/docs/05-domain/operation-record-template.md

@@ -0,0 +1,55 @@
+# Operation Record Template
+
+P1 artifact. V1 defines the type and a null bridge; it does not persist records.
+
+```ts
+interface OperationRecord {
+  id: string;
+  sessionId: string;
+  environmentId: string;
+  serviceId?: string;
+  deploymentId?: string;
+  operation: string;
+  skillRef?: string;
+  startedAt: string;
+  finishedAt?: string;
+  outcome: 'success' | 'failure' | 'unknown';
+  evidenceRefs: string[];
+  summary: string;
+}
+```
+
+## JSON example
+
+```json
+{
+  "id": "op-20261101-0001",
+  "sessionId": "session-abc",
+  "environmentId": "test-a",
+  "serviceId": "aicoservice",
+  "deploymentId": "deploy-001",
+  "operation": "redeploy",
+  "skillRef": "redeploy-k8s-service",
+  "startedAt": "2026-11-01T03:00:00.000Z",
+  "finishedAt": "2026-11-01T03:04:12.000Z",
+  "outcome": "success",
+  "evidenceRefs": ["evidence:test-a/deploy-001/log-20261101"],
+  "summary": "Redeploy completed; pod rollout finished with 2/2 ready"
+}
+```
+
+## Rules
+
+- `evidenceRefs` are opaque and sanitized; never embed raw logs or secrets.
+- `summary` is redacted and bounded (default 500 characters).
+- The record carries scope ids so memory queries stay scoped.
+- Records are append-only from the plugin's perspective.
+- A record is not an audit replacement for the executing tool's own logging.
+
+## Evidence reference format
+
+```text
+evidence:{environmentId}/{deploymentId}/{kind}-{timestamp}
+```
+
+`kind` is a short token such as `log`, `config` or `check`. The content lives outside the record.

package/docs/05-domain/prompt-template.md

@@ -0,0 +1,90 @@
+# Prompt Template
+
+Templates for presenting tool results to an Agent. Keep them compact; do not dump the whole registry.
+
+## Service Context
+
+```markdown
+# Service Context
+
+Environment: {environmentId} ({environmentName}, {environmentCategory})
+Service:     {serviceId} ({serviceName})
+Deployment:  {deploymentId} ({runtimeMode})
+Status:      {status}
+
+## Source
+
+- Git: {source.gitUrl} ({source.defaultBranch})
+- Module: {source.modulePath}
+- Artifact: {artifact.name} ({artifact.path})
+
+## Location
+
+{locationSummary}
+
+## Log source
+
+{logSourceSummary}
+
+## Resolved paths
+
+| Field | Value | Defined by | Inputs |
+|---|---|---|---|
+{pathRows}
+
+## Class location
+
+{classLocationSummary}
+
+## Credentials
+
+- {ref} — configured: {configured} (source: {source})
+
+## Diagnostics
+
+{diagnostics}
+```
+
+Rules:
+
+- Mark derived values as derived; do not imply they exist.
+- Show provenance for every path, because that is how users debug overrides.
+- Never include credential values.
+
+## Operation Resolution
+
+```markdown
+# Operation Resolution
+
+Operation: {operation}
+Context:   {environmentId} / {serviceId} / {deploymentId}
+Binding:   {matchedBindingId} (level: {matchLevel})
+Skill:     {skill.name} (available: {skill.available})
+Policy:    requiresApproval={policy.requiresApproval}, allowProduction={policy.allowProduction}
+
+## Parameters
+
+- {key}: {value}
+
+## Diagnostics
+
+{diagnostics}
+```
+
+Rules:
+
+- If the result is a conflict, list every candidate binding and its level.
+- If the Skill is unavailable, state why and do not suggest an alternative Skill.
+- Never present a routing result as permission to execute.
+
+## Environment Summary
+
+```markdown
+# Environments
+
+| Environment | Category | Hosts | Clusters | Services |
+|---|---|---|---|---|
+{rows}
+```
+
+Keep list output under 50 rows; point the reader at `env_get` for detail.

package/docs/05-domain/rule-template.md

@@ -0,0 +1,73 @@
+# Rule Profile Template
+
+Copy into `<dataDir>/rules/<id>.yaml`.
+
+```yaml
+id: java-common
+schemaVersion: 1
+description: Common Java service paths, log sources and class locations
+
+variables:
+  installRoot: /opt/company/services
+  timezone: Asia/Shanghai
+
+paths:
+  serviceHome: ${installRoot}/${service.id}
+  jar: ${paths.serviceHome}/lib/${service.artifact.name}
+  logDir: ${paths.serviceHome}/logs
+  applicationLog: ${paths.logDir}/${service.id}.log
+  configDir: ${paths.serviceHome}/config
+
+logSources:
+  native:
+    kind: file
+    path: ${paths.applicationLog}
+  docker:
+    kind: container-stdout
+    container: ${deployment.location.containerName}
+  kubernetes:
+    kind: pod-logs
+    namespace: ${deployment.location.namespace}
+    workload: ${deployment.location.workload.name}
+
+classLocations:
+  native:
+    kind: deployed-dir
+    path: ${paths.serviceHome}/classes
+  kubernetes:
+    kind: jar-entry
+    path: ${paths.jar}
+    entryPrefix: com/company/aico
+
+createdAt: 2026-11-01T03:00:00.000Z
+updatedAt: 2026-11-01T03:00:00.000Z
+```
+
+## Template syntax
+
+Allowed:
+
+```text
+${installRoot}
+${paths.serviceHome}
+${service.id}
+${deployment.location.namespace}
+```
+
+Forbidden:
+
+- function calls, arithmetic, conditionals
+- environment variable access
+- shell or command substitution
+- JavaScript
+
+## Notes
+
+- A path may reference another path; cycles are errors.
+- Undefined references are errors, not empty strings.
+- The only valid form is `${identifier(.identifier)*}`, capped at 2048 characters;
+  anything else (missing brace, operators, spaces) is `RULE_TEMPLATE_INVALID`.
+- Resolved paths containing `..` are rejected.
+- `classLocations` distinguishes build output, deployed directories and jar entries.
+- Only the deployment's `runtimeMode` entry is resolved by `env_resolve`.
+- Overrides: environment `ruleOverrides`, then deployment `variables` and `ruleOverrides`.

package/docs/05-domain/service-template.md

@@ -0,0 +1,39 @@
+# Service Template
+
+Copy into `<dataDir>/services/<id>.yaml` and replace the example values.
+
+```yaml
+id: aicoservice
+schemaVersion: 1
+name: Aico Service
+aliases: [aicoservice]
+category: backend
+description: Core AI coordination service
+
+git:
+  url: https://git.example.internal/team/aicoservice.git
+  defaultBranch: main
+  modulePath: /            # monorepo subpath, omit when not needed
+
+build:
+  tool: maven              # maven | gradle | npm | custom
+  command: mvn -DskipTests package
+
+artifact:
+  name: aicoservice.jar
+  path: ${paths.serviceHome}/lib/${service.artifact.name}
+
+deployModes: [native, docker, kubernetes]
+ruleProfileRefs: [java-common, company-default]   # order matters; later wins
+
+createdAt: 2026-11-01T03:00:00.000Z
+updatedAt: 2026-11-01T03:00:00.000Z
+```
+
+## Notes
+
+- Services are environment-independent. Placement belongs in a deployment binding.
+- `ruleProfileRefs` are applied in order; when two profiles define the same field, the later one wins.
+- `deployModes` must include every runtime mode used by its deployment bindings.
+- `artifact.name` is commonly interpolated by rule profiles as `${service.artifact.name}`.
+- No credentials here. A service-level credential is not modelled in V1.

package/docs/06-operations/deployment-guide.md

@@ -0,0 +1,54 @@
+# Deployment Guide
+
+## Install as a Local Bundle
+
+In a DSH session, call the `plugin_manager` tool:
+
+```text
+action: install_bundle
+target: <absolute path to this repository>
+```
+
+Restart DSH if needed.
+
+## Verify
+
+1. Ask `plugin_manager` for `action: list_bundles` and confirm the bundle appears.
+2. Confirm it is active, not `overridden` or `restart-required`.
+3. Call `env_list` from the Agent; a fresh install returns an empty list.
+4. Open the **Environment Manager** entry in the sidebar and confirm the Overview
+   counts render.
+5. Optional transport check:
+
+   ```bash
+   curl -s -X POST http://127.0.0.1:<port>/env-manager/api \
+     -H 'content-type: application/json' \
+     -H 'x-env-manager-request: 1' \
+     -d '{"op":"meta"}'
+   ```
+
+   Without the header the route returns 403; that is the expected control.
+
+## Upgrade
+
+1. Pull the latest changes.
+2. `npm install && npm run build`.
+3. Reinstall the bundle with `plugin_manager`.
+4. Restart DSH so the Host module generation is fresh.
+5. Run `env_validate` and review diagnostics.
+
+Registry data is untouched by an upgrade. A `schemaVersion` change requires a migration; V1 has none.
+
+## Remove
+
+Call `plugin_manager` with `action: remove_bundle` and `target: dsh-env-manager-plugin`.
+
+Registry data under `dataDir` is not deleted. Back it up if you may reinstall later.
+
+## Rollback
+
+1. Reinstall the previous checkout.
+2. Restart DSH.
+3. Restore `dataDir` from the backup if the previous version wrote incompatible records.
+
+V1 accepts only `schemaVersion: 1`; records written by an unknown version are skipped with a warning rather than corrupted.

package/docs/06-operations/release.md

@@ -0,0 +1,188 @@
+# Release Guide
+
+发布由 [`.github/workflows/release.yml`](../../.github/workflows/release.yml) 自动完成：
+推送 `v*` tag 后，在 Windows runner 上运行 typecheck、build、test，打包 npm tarball，
+通过 npm Trusted Publisher（OIDC）发布到 npm，并创建 GitHub Release。
+
+## 包名说明
+
+npm 上的 `dsh-env-manager` 已经被另一个**不同功能的包**占用，因此本插件发布为：
+
+```text
+dsh-env-manager-plugin
+```
+
+插件运行时 id、Skill 名和数据目录仍是 `dsh-env-manager`；只有 npm 包名和
+`cordis.patch.yml` 的模块名使用 `dsh-env-manager-plugin`。
+
+## 触发方式
+
+### 推荐：推送 tag
+
+```sh
+git tag -a v0.1.0 -m "v0.1.0"
+git push origin v0.1.0
+```
+
+也可以一次推送提交和 tag：
+
+```sh
+git push origin main --follow-tags
+```
+
+`--follow-tags` 只推送 annotated tag；如果使用 lightweight tag，必须显式
+`git push origin v0.1.0`。
+
+### 手动触发
+
+GitHub → Actions → Release → Run workflow，输入已存在的 tag（例如 `v0.1.0`）。
+
+## 发布前检查
+
+1. `package.json` 的 `version` 必须与 tag 去掉 `v` 后完全一致；不一致时 workflow 会在
+   第一步失败。
+2. 本地运行 `npm run check`（typecheck + build + test + client 语法检查）。
+3. 确认 `lib/` 已重新构建；`npm pack` 的 `prepack` 也会构建，但本地检查应提前暴露错误。
+4. 确认 `README.md`、`docs/00-project/current-state.md` 已更新。
+5. 检查 tarball：
+
+   ```sh
+   npm pack --dry-run
+   ```
+
+   确认包含 `index.js`、`client.js`、`cordis.patch.yml`、`lib/`、`locale/`、`icon.svg`、
+   `README.md`、`LICENSE` 和 `docs/`。
+6. 提交所有发布内容，再打 tag；tag 指向的 commit 应包含完整发布内容。
+
+## 首次发布与 Trusted Publisher
+
+Trusted Publisher 只能在 npm 包已经存在后绑定，因此**第一次发布需要先手动完成**。
+之后的版本由 GitHub Actions 自动发布，不需要 `NPM_TOKEN`。
+
+### 1. 首次发布（bootstrap）
+
+Trusted Publisher 只能在包存在后绑定，因此第一次用一个不会占用 `latest` 的
+placeholder 版本把包名注册下来：
+
+```sh
+npm version 0.0.0-stage --no-git-tag-version
+npm publish --access public --tag stage
+```
+
+这一步需要交互式 2FA/OTP；不能用没有 OTP 的自动化 shell 代替。发布成功后，
+npm 上会出现 `dsh-env-manager-plugin@0.0.0-stage`，当前账号成为 maintainer；
+`stage` tag 不会覆盖 `latest`。
+
+然后把版本恢复为本次正式发布版本：
+
+```sh
+npm version 0.1.0 --no-git-tag-version
+```
+
+> 如果 `npm publish` 报 `EOTP`，请在交互终端完成 2FA；不要把一次性密码写进脚本或仓库。
+> 也可以使用 `0.0.0-bootstrap`，只要 tag 用 `stage` 而不是 `latest`。
+
+### 2. 绑定 GitHub Actions
+
+打开 npmjs.com → `dsh-env-manager-plugin` → Settings → Trusted publishing →
+Add GitHub Actions publisher：
+
+| 字段 | 值 |
+|---|---|
+| Organization or user | `zhiwuli0228` |
+| Repository | `dsh-env-manager` |
+| Workflow filename | `release.yml` |
+| Environment | 留空 |
+
+绑定后可以检查：
+
+```sh
+npm trust list dsh-env-manager-plugin
+```
+
+`npm trust` 也可能要求 2FA；失败时以 npm 网页设置页为准。
+
+### 3. 之后的自动发布
+
+```sh
+git tag -a v0.1.1 -m "v0.1.1"
+git push origin v0.1.1
+```
+
+workflow 使用 `id-token: write` 获取 OIDC token，执行：
+
+```sh
+npm publish --access public --provenance
+```
+
+不需要 `NPM_TOKEN`，也不需要 `.npmrc`。`--provenance` 只生成供应链证明；
+它本身不授予发布权限，授权来自 npm 侧的 Trusted Publisher 绑定。
+
+### 备选：NPM_TOKEN
+
+如果暂时不绑定 Trusted Publisher，可以创建 npm Automation token，配置为仓库
+secret `NPM_TOKEN`，并在 publish 前写入 `.npmrc`。当前 workflow 不使用该方案；
+不要把 token 提交到仓库。
+
+## Workflow 步骤
+
+1. Checkout tag。
+2. 校验 tag 与 `package.json` 版本。
+3. `npm ci`。
+4. `npm run check`（typecheck + build + test + client 语法检查）。
+5. `npm pack`，生成 `dsh-env-manager-plugin-<version>.tgz`。
+6. 升级 npm CLI，然后用 Trusted Publisher / OIDC 发布到 npm。
+7. 创建 GitHub Release，自动生成 release notes，并上传 tarball。
+
+## 权限
+
+```yaml
+permissions:
+  contents: write   # 创建 Release
+  id-token: write   # Trusted Publisher + npm provenance
+```
+
+不要使用 `write-all`。
+
+## 发布后验证
+
+1. 等待 registry 传播（通常 1–5 分钟）：
+
+   ```sh
+   npm view dsh-env-manager-plugin version
+   ```
+
+2. 验证元数据：
+
+   ```sh
+   npm view dsh-env-manager-plugin@0.1.0 dist.shasum dist.integrity gitHead dist.attestations
+   ```
+
+   `gitHead` 应等于 tag commit；provenance 的 `predicateType` 应为
+   `https://slsa.dev/provenance/v1`。
+
+3. 验证 Release：
+
+   ```sh
+   gh release view v0.1.0
+   ```
+
+   确认 `dsh-env-manager-plugin-0.1.0.tgz` 附件存在。
+
+4. 更新 `docs/00-project/current-state.md` 的发布状态和测试计数。
+
+## 常见失败
+
+- **`private: true` / npm 拒绝发布**：当前 `package.json` 已移除 `private`。
+- **tag 与版本不一致**：先改 `package.json`，提交后再打 tag。
+- **npm 版本已存在**：npm 不允许覆盖同版本；提升版本并重新打 tag，不要重复 publish。
+- **`EOTP` / 2FA**：交互式发布需要 OTP；CI 使用 Trusted Publisher。
+- **`ENEEDAUTH`**：没有 token 且 Trusted Publisher 未绑定，或 workflow 缺少
+  `id-token: write`。
+- **`E403` / 版本已存在**：先确认 `npm view`，不要立即重试。
+- **`npm view` 仍显示旧版本**：registry 传播/缓存，先看 workflow 日志。
+- **首次 workflow 发布失败**：Trusted Publisher 必须在包存在且绑定后才能用；
+  先完成上面的 bootstrap。
+- **lightweight tag 没被推送**：用 annotated tag 或显式 `git push origin <tag>`。
+- **Release 已存在**：`softprops/action-gh-release` 会更新已有 Release；
+  需要全新发布时使用新 tag。

package/docs/06-operations/security-policy.md

@@ -0,0 +1,53 @@
+# Security Policy (Operations)
+
+Operational rules for users and agents. Design rationale is in
+[security-model.md](../01-architecture/security-model.md).
+
+---
+
+## 1. Credentials
+
+1. Every host, cluster, endpoint and future adapter uses a `credentialRef`.
+2. Never write a password, token, private key or kubeconfig into a registry file, a test fixture or a Git commit.
+3. The plugin reports only `configured`, `missing` or `unavailable`.
+4. If a credential is missing, fix the reference; do not paste the value into the registry.
+
+## 2. Production changes
+
+1. `category: production` environments are gated.
+2. Operation bindings that target production must set `allowProduction: true` explicitly; otherwise routing fails.
+3. Management writes that affect production records require approval when performed by
+   the Agent.
+4. The UI writes as actor `'ui'` and is denied for production records unless
+   `writePolicy.allowUiProductionWrites` is enabled.
+5. A denied approval is final for that attempt; nothing is written.
+
+## 3. Rule templates
+
+1. Only `${...}` interpolation is allowed.
+2. Do not attempt to inject JavaScript, shell or environment lookups. They are rejected.
+3. If a path must differ per environment, use an override, not a new template language feature.
+4. Review rule profiles that resolve to sensitive directories. V1 does not read them, but future adapters will.
+
+## 4. Data handling
+
+1. `data/` is git-ignored. Do not commit registry data.
+2. Do not place real internal hostnames, IPs or URLs in `tests/fixtures/`.
+3. Redact command output and evidence before recording it.
+4. Keep summaries short; evidence lives behind opaque references.
+
+## 5. Sharing and scope
+
+1. Registry data is profile-global. Treat it as internal documentation.
+2. Session defaults are per session. Do not design flows that rely on a global default.
+3. Memory entries must carry environment/service/deployment scope.
+4. A conclusion from one environment is not a global rule.
+
+## 6. Incident handling
+
+If a secret is committed by mistake:
+
+1. Rotate the secret immediately.
+2. Remove it from Git history, not only from the working tree.
+3. Record the incident outside this repository.
+4. Add a check or test that would have caught it.

package/docs/06-operations/troubleshooting.md

@@ -0,0 +1,91 @@
+# Troubleshooting
+
+## 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