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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (149) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +273 -3
  3. package/client.js +2581 -0
  4. package/cordis.patch.yml +4 -0
  5. package/docs/00-project/current-state.md +272 -0
  6. package/docs/00-project/glossary.md +215 -0
  7. package/docs/00-project/project-brief.md +114 -0
  8. package/docs/00-project/roadmap.md +89 -0
  9. package/docs/01-architecture/DSH_Environment_Service_Memory_Skill_Brainstorm.md +493 -0
  10. package/docs/01-architecture/api-verification.md +416 -0
  11. package/docs/01-architecture/architecture-overview.md +222 -0
  12. package/docs/01-architecture/data-model.md +930 -0
  13. package/docs/01-architecture/decisions/ADR-0001-plugin-as-bundle.md +29 -0
  14. package/docs/01-architecture/decisions/ADR-0002-file-based-storage.md +25 -0
  15. package/docs/01-architecture/decisions/ADR-0003-skill-router-over-search.md +25 -0
  16. package/docs/01-architecture/decisions/ADR-0004-typescript-host-js-client.md +31 -0
  17. package/docs/01-architecture/decisions/ADR-0005-layered-rule-resolution.md +36 -0
  18. package/docs/01-architecture/decisions/ADR-0006-credentials-as-references.md +30 -0
  19. package/docs/01-architecture/decisions/ADR-0007-session-scoped-default-environment.md +28 -0
  20. package/docs/01-architecture/decisions/ADR-0008-memory-bridge-not-second-store.md +31 -0
  21. package/docs/01-architecture/decisions/ADR-0009-client-host-http-transport.md +87 -0
  22. package/docs/01-architecture/decisions/ADR-0010-environment-plane-model.md +87 -0
  23. package/docs/01-architecture/decisions/ADR-0011-k8s-node-execution-model.md +92 -0
  24. package/docs/01-architecture/design.md +666 -0
  25. package/docs/01-architecture/detailed-design.md +961 -0
  26. package/docs/01-architecture/implementation-plan.md +323 -0
  27. package/docs/01-architecture/module-boundaries.md +306 -0
  28. package/docs/01-architecture/security-model.md +227 -0
  29. package/docs/01-architecture/storage-contract.md +224 -0
  30. package/docs/01-architecture/tool-contract.md +438 -0
  31. package/docs/01-architecture/ui-design.md +587 -0
  32. package/docs/02-harness/agent-behavior.md +36 -0
  33. package/docs/02-harness/change-snapshot-policy.md +29 -0
  34. package/docs/02-harness/client-ui-integration.md +110 -0
  35. package/docs/02-harness/context-policy.md +43 -0
  36. package/docs/02-harness/harness-standard.md +91 -0
  37. package/docs/02-harness/task-execution-policy.md +26 -0
  38. package/docs/02-harness/verification-policy.md +97 -0
  39. package/docs/03-openspec/archive-rule.md +25 -0
  40. package/docs/03-openspec/bugfix-rule.md +30 -0
  41. package/docs/03-openspec/design-rule.md +33 -0
  42. package/docs/03-openspec/openspec-usage-guide.md +31 -0
  43. package/docs/03-openspec/proposal-rule.md +70 -0
  44. package/docs/03-openspec/spec-rule.md +33 -0
  45. package/docs/03-openspec/tasks-rule.md +31 -0
  46. package/docs/04-development/coding-style.md +67 -0
  47. package/docs/04-development/dependency-policy.md +43 -0
  48. package/docs/04-development/development-guide.md +85 -0
  49. package/docs/04-development/directory-convention.md +105 -0
  50. package/docs/04-development/local-run-guide.md +61 -0
  51. package/docs/04-development/testing-guide.md +102 -0
  52. package/docs/05-domain/deployment-template.md +76 -0
  53. package/docs/05-domain/environment-template.md +165 -0
  54. package/docs/05-domain/operation-binding-template.md +55 -0
  55. package/docs/05-domain/operation-record-template.md +55 -0
  56. package/docs/05-domain/prompt-template.md +90 -0
  57. package/docs/05-domain/rule-template.md +73 -0
  58. package/docs/05-domain/service-template.md +39 -0
  59. package/docs/06-operations/deployment-guide.md +54 -0
  60. package/docs/06-operations/release.md +198 -0
  61. package/docs/06-operations/security-policy.md +53 -0
  62. package/docs/06-operations/troubleshooting.md +141 -0
  63. package/docs/07-templates/adr-template.md +21 -0
  64. package/docs/07-templates/bugfix-template.md +11 -0
  65. package/docs/07-templates/case-template.md +15 -0
  66. package/docs/07-templates/design-template.md +29 -0
  67. package/docs/07-templates/proposal-template.md +19 -0
  68. package/docs/07-templates/spec-template.md +15 -0
  69. package/docs/07-templates/tasks-template.md +12 -0
  70. package/docs/99-archive/README.md +13 -0
  71. package/docs/README.md +142 -0
  72. package/icon.svg +4 -0
  73. package/index.js +31 -0
  74. package/lib/app/app.d.ts +67 -0
  75. package/lib/app/app.js +494 -0
  76. package/lib/app/app.js.map +1 -0
  77. package/lib/config.d.ts +55 -0
  78. package/lib/config.js +42 -0
  79. package/lib/config.js.map +1 -0
  80. package/lib/domain/constants.d.ts +21 -0
  81. package/lib/domain/constants.js +59 -0
  82. package/lib/domain/constants.js.map +1 -0
  83. package/lib/domain/errors.d.ts +20 -0
  84. package/lib/domain/errors.js +22 -0
  85. package/lib/domain/errors.js.map +1 -0
  86. package/lib/domain/schemas.d.ts +28 -0
  87. package/lib/domain/schemas.js +445 -0
  88. package/lib/domain/schemas.js.map +1 -0
  89. package/lib/domain/types.d.ts +412 -0
  90. package/lib/domain/types.js +2 -0
  91. package/lib/domain/types.js.map +1 -0
  92. package/lib/index.d.ts +18 -0
  93. package/lib/index.js +89 -0
  94. package/lib/index.js.map +1 -0
  95. package/lib/logger.d.ts +8 -0
  96. package/lib/logger.js +13 -0
  97. package/lib/logger.js.map +1 -0
  98. package/lib/memory/bridge.d.ts +18 -0
  99. package/lib/memory/bridge.js +13 -0
  100. package/lib/memory/bridge.js.map +1 -0
  101. package/lib/registry/integrity.d.ts +10 -0
  102. package/lib/registry/integrity.js +204 -0
  103. package/lib/registry/integrity.js.map +1 -0
  104. package/lib/registry/registry.d.ts +14 -0
  105. package/lib/registry/registry.js +182 -0
  106. package/lib/registry/registry.js.map +1 -0
  107. package/lib/resolver/merge.d.ts +23 -0
  108. package/lib/resolver/merge.js +90 -0
  109. package/lib/resolver/merge.js.map +1 -0
  110. package/lib/resolver/resolve.d.ts +18 -0
  111. package/lib/resolver/resolve.js +288 -0
  112. package/lib/resolver/resolve.js.map +1 -0
  113. package/lib/resolver/template.d.ts +10 -0
  114. package/lib/resolver/template.js +42 -0
  115. package/lib/resolver/template.js.map +1 -0
  116. package/lib/router/params.d.ts +3 -0
  117. package/lib/router/params.js +83 -0
  118. package/lib/router/params.js.map +1 -0
  119. package/lib/router/router.d.ts +11 -0
  120. package/lib/router/router.js +204 -0
  121. package/lib/router/router.js.map +1 -0
  122. package/lib/session/session.d.ts +16 -0
  123. package/lib/session/session.js +64 -0
  124. package/lib/session/session.js.map +1 -0
  125. package/lib/skill.d.ts +17 -0
  126. package/lib/skill.js +56 -0
  127. package/lib/skill.js.map +1 -0
  128. package/lib/storage/atomic.d.ts +10 -0
  129. package/lib/storage/atomic.js +107 -0
  130. package/lib/storage/atomic.js.map +1 -0
  131. package/lib/storage/paths.d.ts +10 -0
  132. package/lib/storage/paths.js +50 -0
  133. package/lib/storage/paths.js.map +1 -0
  134. package/lib/storage/records.d.ts +16 -0
  135. package/lib/storage/records.js +112 -0
  136. package/lib/storage/records.js.map +1 -0
  137. package/lib/storage/sessions.d.ts +17 -0
  138. package/lib/storage/sessions.js +65 -0
  139. package/lib/storage/sessions.js.map +1 -0
  140. package/lib/tools/tools.d.ts +14 -0
  141. package/lib/tools/tools.js +472 -0
  142. package/lib/tools/tools.js.map +1 -0
  143. package/lib/transport/http.d.ts +3 -0
  144. package/lib/transport/http.js +217 -0
  145. package/lib/transport/http.js.map +1 -0
  146. package/locale/en.json +6 -0
  147. package/locale/zh.json +6 -0
  148. package/package.json +101 -6
  149. package/scripts/repair-profile.mjs +141 -0
@@ -0,0 +1,4 @@
1
+ - insert:
2
+ - id: dsh-env-manager
3
+ name: dsh-env-manager-plugin
4
+ config: {}
@@ -0,0 +1,272 @@
1
+ # Current State
2
+
3
+ This file is the **project continuity snapshot**. Update it after every completed change.
4
+
5
+ ## Current Phase
6
+
7
+ **Phase 1 of the environment/plane model and Phase 1.1 of the K8s node/execution model
8
+ are implemented, tested and live-verified in the `desktop` profile: an environment is one
9
+ network, its planes are role views, and hosts also record their machine kind and command
10
+ surfaces.**
11
+
12
+ The V1 Host is implemented in TypeScript under `src/` and compiled to `lib/`. Storage,
13
+ registry, resolver, router, session store, application service, ten tools and the
14
+ same-origin HTTP API are in place, with 51 Vitest tests passing. The Client panel is
15
+ implemented in `client.js` and its sidebar/main slot registrations are live. The sidebar
16
+ glyph follows the host `sidebar.panellist` contract: it honors the owner's
17
+ `size`/`active` props and renders monochrome with `currentColor`; the contract is recorded
18
+ in [`client-ui-integration.md`](../02-harness/client-ui-integration.md).
19
+
20
+ The plugin also registers a profile-wide **discovery Skill** named `dsh-env-manager` via
21
+ `ctx.skills.register()`. Its catalog entry makes the registry discoverable from any
22
+ workspace in the same profile; its full workflow body loads only on invocation. It is a
23
+ discovery/usage Skill, not an execution Skill or operation binding, and it is removed
24
+ when the plugin is disabled or uninstalled. `config.registerSkill` defaults to `true`.
25
+
26
+ Release packaging is prepared under the npm name `dsh-env-manager-plugin` because the
27
+ unscoped `dsh-env-manager` npm name is an unrelated existing package. Pushing an
28
+ annotated `v*` tag runs [`.github/workflows/release.yml`](../../.github/workflows/release.yml)
29
+ on `windows-latest`, verifies the tag against `package.json`, runs `npm run check`, packs
30
+ the tarball, publishes with npm Trusted Publisher/OIDC, and creates a GitHub Release.
31
+ The first publish must be bootstrapped manually before Trusted Publisher can be bound;
32
+ the exact steps are in [`release.md`](../06-operations/release.md).
33
+
34
+ **Release status (2026-11-01):** `dsh-env-manager-plugin@0.1.0` is published and is the
35
+ `latest` npm tag (`gitHead` `4d884e7`). The
36
+ [GitHub Release v0.1.0](https://github.com/zhiwuli0228/dsh-env-manager/releases/tag/v0.1.0)
37
+ contains `dsh-env-manager-plugin-0.1.0.tgz`; workflow run
38
+ [`41323001406`](https://github.com/zhiwuli0228/dsh-env-manager/actions/runs/41323001406)
39
+ completed successfully. The 0.1.0 publish itself was bootstrapped manually; the workflow
40
+ detected the existing version, skipped npm publish, and created the Release. Later versions
41
+ use npm Trusted Publisher/OIDC through the same workflow.
42
+
43
+ **Plugin directory:** submitted to
44
+ [`awesome-dsh-plugin/awesome-dsh-plugin`](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
45
+ as PR [#11185](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/11185)
46
+ (`data/plugins/zhiwuli0228__dsh-env-manager.yml`, category `dev`). The repository has the
47
+ `dsh-plugin` topic; the listing is pending CI/review.
48
+
49
+ **Installation smoke test (2026-11-02):** removed the old local bundle
50
+ `dsh-env-manager` from the `desktop` profile, including its package dependency, bundle
51
+ entry, lockfile reference and stale `node_modules/dsh-env-manager` symlink. Reinstalled
52
+ the published package as `dsh-env-manager-plugin@0.1.0` from npm. The discovery Skill,
53
+ ten tools, sidebar panel and `/env-manager/api` transport all came back; the API reported
54
+ the preserved registry data (2 environments, 3 services, 3 deployments, 0 rule profiles,
55
+ 0 operation bindings) and no warnings. Registry data was intentionally not deleted during
56
+ uninstall.
57
+
58
+ **Install hardening (2026-11-03):** reproduced the reported failure from a clean clone:
59
+ `lib/` was git-ignored, so a checkout installed without a build had no `lib/index.js`.
60
+ The compiled `lib/` tree is now committed, `index.js` reports a specific missing-build
61
+ error, and the install docs use `plugin_manager install_bundle` instead of the
62
+ dependency-only `dsh plugin add` command. `scripts/repair-profile.mjs` detects duplicate
63
+ or legacy bundle entries and offers an atomic `--fix` with a backup. The published
64
+ `0.1.0` npm tarball already contained `lib/`; this fixes checkout and git installs.
65
+
66
+ The panel uses a centered 1080 px column, 22 px title with a glyph mark, underline tabs,
67
+ compact stat cards and a master/detail environment view. **Environments is the first and
68
+ default tab**; a persistent header **New environment** action is available from every tab,
69
+ and `Records` is limited to services, deployments, rule profiles and operation bindings.
70
+
71
+ Phase 1 changes the environment workflow:
72
+
73
+ - `New environment` creates only the shell: name, optional id, category and description.
74
+ It seeds the four standard roles (`management`, `business`, `database`, `extension`) and
75
+ creates no hosts, endpoints or credentials.
76
+ - The detail page is grouped by role: Overview, All nodes, one tab per declared plane,
77
+ Login records, Kubernetes/clusters, Endpoints and YAML. Plane tabs are filters over the
78
+ same `hosts[]`; a node serving two planes is one host with two roles and appears in both
79
+ tabs.
80
+ - Add/edit node supports multiple roles. Opening the form from a plane preselects that
81
+ role. A node may have zero accounts, or an optional login username + password that
82
+ writes a namespaced credential and keeps only `credentialRef` in YAML. On edit, filling
83
+ both fields adds a new password account and leaves existing accounts untouched.
84
+ - Batch import accepts `IP,name,roles,port,user` per line, with `|`/`/` for multiple
85
+ roles. It creates hosts and optional accounts but never passwords, and rejects unknown
86
+ roles/duplicate IPs/invalid ports before saving.
87
+ - Node search filters by id, name, IP, platform, admin user, role, node kind, access
88
+ method, cluster name/id, account username or web login URL. Node cards expand to show the
89
+ account table.
90
+ - Schema validation now requires at least one environment role and at least one role per
91
+ host. Standard roles are seeded automatically when a node uses a missing standard role.
92
+
93
+ Phase 1.1 adds the K8s node/execution model (ADR-0011):
94
+
95
+ - `Host.kind` classifies the machine as `vm`, `physical`, `k8s-all-in-one`, `k8s-worker`
96
+ or `pod-host`. A missing value reads as `vm`.
97
+ - `Host.access` records `ssh`, `kubectl` and/or `docker`; it is capability metadata, not
98
+ authorization. `Host.clusterRef` links K8s/Pod machines to a cluster.
99
+ - `k8s-all-in-one` and `k8s-worker` require an existing cluster reference; `pod-host` may
100
+ omit it for a Docker-only machine. A Pod is never a Host; `pod-host` is the machine
101
+ reached with `docker exec`.
102
+ - `Cluster.topology` is `all-in-one`, `separate` or `external` and is optional.
103
+ - The node form has kind/cluster/access controls; node cards and search include kind,
104
+ access and cluster; the detail page has a Kubernetes/clusters tab with add/edit and a
105
+ node count derived from `clusterRef`.
106
+ - Batch import remains generic VM (`kind: vm`, `access: [ssh]`) and never accepts secrets.
107
+
108
+ Web console logins are account-level:
109
+
110
+ - `HostAccount.loginUrl` stores the management/business console URL; it is a URL, not a
111
+ secret. The account form has `Web login URL`, username and an optional password, and the
112
+ account can be edited in place. The Host schema requires an absolute `http(s)` URL.
113
+ - `Add web login` on a node card opens the account form with protocol `web` and auth type
114
+ `password` preselected; the URL renders as a link under the account username.
115
+ - A password entered in the account form is written through the DSH credential service;
116
+ YAML keeps only `credentialRef`. Leaving the password blank preserves the existing
117
+ reference when editing.
118
+ - Account search covers username, purpose and web login URL.
119
+
120
+ Live verification covered shell creation, plane tabs, empty-plane state, add node from a
121
+ plane, multi-role edit, batch import, search, account creation and credential references.
122
+ Phase 1.1 was additionally verified live: add a cluster with topology and API endpoint, add
123
+ a K8s all-in-one node with kind/access/cluster, add a Pod host without a cluster, reject a
124
+ K8s worker without a cluster, confirm cluster/node counts and search by cluster name.
125
+ Web login URL/password and account edit were verified live after the account form change.
126
+
127
+ ## Implemented
128
+
129
+ Documentation and repository:
130
+
131
+ - [x] GitHub repository initialized
132
+ - [x] DSH bundle manifest (`package.json`, `cordis.patch.yml`)
133
+ - [x] Host plugin entry shim (`index.js` → `lib/index.js`)
134
+ - [x] Client panel (`client.js`)
135
+ - [x] Locale resources (`locale/en.json`, `locale/zh.json`)
136
+ - [x] Plugin icon (`icon.svg`)
137
+ - [x] README, LICENSE, `.gitignore`
138
+ - [x] Docs Harness Context Hub
139
+ - [x] AGENTS.md project rules
140
+ - [x] V1 design suite:
141
+ - [x] `design.md` — scope, architecture, flows, acceptance criteria
142
+ - [x] `detailed-design.md` — module contracts, algorithms, storage, tools, HTTP
143
+ - [x] `data-model.md` — record schemas, results, diagnostics catalogue
144
+ - [x] `tool-contract.md` — ten model-facing tools with DSL schemas and errors
145
+ - [x] `storage-contract.md` — dataDir resolution, atomicity, sessions, backups
146
+ - [x] `module-boundaries.md` — ownership and dependency direction
147
+ - [x] `ui-design.md` — panel layout, transport, states, i18n, QA checklist
148
+ - [x] `security-model.md` — credentials, approval, HTTP controls, redaction
149
+ - [x] `api-verification.md` — verified runtime facts F1–F21 and probes V1–V8
150
+ - [x] `implementation-plan.md` — ordered tasks T01–T24, acceptance, cut line
151
+ - [x] ADR-0001 … ADR-0011
152
+
153
+ Code:
154
+
155
+ - [x] TypeScript Host scaffold (`src/`, `tsconfig.json`, build scripts)
156
+ - [x] Domain schemas and validators
157
+ - [x] Storage layer with atomic writes, backups and session files
158
+ - [x] Registry layer with integrity diagnostics
159
+ - [x] Context resolver
160
+ - [x] Rule resolver with provenance
161
+ - [x] Operation Skill router
162
+ - [x] Profile-wide discovery Skill (`dsh-env-manager`) registered through `ctx.skills.register()`
163
+ - [x] README documents the bundled Skill lifecycle, scope, opt-out and execution boundary
164
+ - [x] GitHub Actions release pipeline (`.github/workflows/release.yml`) for tagged npm publish
165
+ - [x] Release runbook (`docs/06-operations/release.md`) with Trusted Publisher bootstrap
166
+ - [x] Session context store
167
+ - [x] Application service (`app`)
168
+ - [x] Read tools
169
+ - [x] Management tools
170
+ - [x] HTTP transport
171
+ - [x] Client configuration UI (slot registration and HTTP round-trip live-verified)
172
+ - [x] Environment detail: overview, role/plane views, nodes, accounts, login audit, clusters, endpoints, YAML
173
+ - [x] Shell-only **New environment** form with standard role seeding
174
+ - [x] Role-filtered plane tabs over one `hosts[]` collection (no per-plane copies)
175
+ - [x] Add/edit node with multiple roles and optional credential write
176
+ - [x] Node kind (`vm`/`physical`/K8s all-in-one/K8s worker/Pod host), command access and cluster reference
177
+ - [x] Kubernetes/clusters tab with cluster add/edit, topology and derived node count
178
+ - [x] Batch node import (`IP,name,roles,port,user`; no passwords; generic VM nodes)
179
+ - [x] Node search (including kind/access/cluster and account web login) and expandable account cards
180
+ - [x] Account-level web login URL, password-to-credential bridge and in-place account edit
181
+ - [x] Dedicated default **Environments** tab and persistent header create action
182
+ - [x] Records narrowed to services, deployments, rule profiles and operation bindings
183
+ - [x] Credential write path (`credential` / `credentialUnset`, namespaced refs)
184
+ - [x] Structured forms for basic info, node, account and login records
185
+ - [x] Memory bridge contract and null adapter
186
+ - [x] Tests (50 passing)
187
+ - [x] Installed in the `desktop` profile (`install_bundle`, `application: applied`)
188
+
189
+ ## Current Constraints
190
+
191
+ - V1 accepts `schemaVersion: 1` only.
192
+ - No plain-text credentials in registry files.
193
+ - An environment must declare at least one logical role and every node must declare at
194
+ least one declared role; the four standard roles are seeded on shell creation.
195
+ - `k8s-all-in-one` and `k8s-worker` nodes require a valid `clusterRef`; `pod-host` may omit
196
+ it for a Docker-only machine. `Host.access` is metadata, not an authorization grant.
197
+ - A Pod is not a registry Host. `pod-host` models the machine reached with `docker exec`;
198
+ per-Pod inventory is out of scope.
199
+ - Passwords are accepted only transiently by the add/edit node form and forwarded to
200
+ `ctx.credentials.set`; the record keeps `credentialRef` only. Shell creation and batch
201
+ import never accept passwords.
202
+ - Credential writes/deletes are restricted to `env-manager/<environmentId>/<accountId>`
203
+ (node-add refs use `<hostId>-<username>` as the account id).
204
+ - No arbitrary code in rule templates.
205
+ - No remote execution in V1.
206
+ - No production auto-apply.
207
+ - Registry data is git-ignored.
208
+ - DSH peer packages are not bundled; they resolve from the profile.
209
+
210
+ ## Current Directory Plan
211
+
212
+ ```text
213
+ dsh-env-manager/
214
+ ├── AGENTS.md
215
+ ├── index.js # host entry shim (V1)
216
+ ├── client.js # client module
217
+ ├── cordis.patch.yml
218
+ ├── package.json
219
+ ├── tsconfig.json # added in V1
220
+ ├── src/ # TypeScript host (V1)
221
+ ├── lib/ # build output, git-ignored
222
+ ├── locale/
223
+ ├── icon.svg
224
+ ├── docs/
225
+ ├── data/ # runtime registry data, git-ignored
226
+ └── tests/
227
+ ```
228
+
229
+ ## Known Gaps
230
+
231
+ - The detail view supports create/edit for basic info, nodes, accounts and login records,
232
+ but deleting a node/account/login from its row is still YAML-only. Clusters can be added
233
+ and edited; deleting a cluster is YAML-only.
234
+ - Batch import does not accept kind/access/cluster columns; imported nodes are generic VMs
235
+ and K8s/Pod hosts are edited afterwards.
236
+ - Per-Pod/container inventory is not modeled; a `pod-host` is one machine even when it runs
237
+ many Pods.
238
+ - Node editing preserves accounts and roles, but there is no bulk edit. Account editing can
239
+ rotate a password, but private-key and passphrase input remain YAML-only.
240
+ - Database primary/replica/sharding topology is deliberately not modeled in Phase 1: the
241
+ database plane is a role, and topology detail belongs in node notes until Phase 2.
242
+ - Services, deployments, rule profiles and operation bindings are YAML-only; only
243
+ environments have structured forms.
244
+ - The `oracle1` environment in the `desktop` profile is demo data created to verify account
245
+ and login rendering; replace or delete it before real use.
246
+ - Light theme contrast has not been checked yet.
247
+ - Private-key input and key passphrases are still outside the UI; password rotation works
248
+ through `Edit account`.
249
+ - Deleting an environment does not automatically delete its namespaced credentials; the
250
+ `credentialUnset` operation exists, but there is no revoke button in the panel yet.
251
+ - Runtime probes V4 (approval from a tool body) and V6 (live credential `describe`)
252
+ in `api-verification.md` §4 are not exercised yet. Live credential `set`/`unset` via
253
+ the node form were verified.
254
+ - Memory bridge is a contract and null adapter only; no memory plugin is wired.
255
+ - No cross-process write locking.
256
+ - No operation execution: routing returns the Skill and policy, it does not run them.
257
+ - The panel cannot write production records unless
258
+ `writePolicy.allowUiProductionWrites` is enabled.
259
+ - No JumpServer/PAM synchronization; account and login observations remain manual/YAML.
260
+
261
+ ## Next Recommended Work
262
+
263
+ 1. **Phase 2** — database topology (primary/replica/sharding) and richer expansion-node
264
+ modeling, stored without duplicating `hosts[]`.
265
+ 2. Batch-import kind/access/cluster columns, and optional Pod/container inventory if
266
+ operations need per-workload targeting.
267
+ 3. Row-level delete for nodes, accounts and login records, plus private-key/passphrase
268
+ input.
269
+ 4. Live probes V4 and V6, then record results in `api-verification.md`.
270
+ 5. Optional JumpServer/PAM import adapter for accounts and login observations.
271
+ 6. Add a small example registry under `examples/` for first-run demonstration.
272
+ 7. P1 memory bridge and operation records.
@@ -0,0 +1,215 @@
1
+ # Glossary
2
+
3
+ ## Environment
4
+
5
+ One complete network and one configuration page, such as `dev`, `test-a`, `staging` or
6
+ `production`.
7
+
8
+ Contains the role catalogue, hosts, clusters and access endpoints in one record. An
9
+ environment must declare at least one logical role; the panel seeds management, business,
10
+ database and expansion by default.
11
+
12
+ ## Plane
13
+
14
+ A role view over an environment's nodes: management, business, database or expansion.
15
+
16
+ A plane is **not** a separate environment and has no node copies. Opening a plane tab
17
+ filters the environment's single `hosts[]` collection. A node that serves two planes is one
18
+ host with two roles.
19
+
20
+ ## Node
21
+
22
+ The user-facing name for a host inside an environment. See **Host**.
23
+
24
+ ## Host
25
+
26
+ A single compute machine inside one environment: a VM, physical machine, Kubernetes node or
27
+ Pod-hosting machine. A Pod is not a Host.
28
+
29
+ Attributes: hostname, kind, OS, IP, SSH port, roles, command access and a `credentialRef`. A
30
+ host must declare at least one role; it may carry several roles, which is how co-location is
31
+ expressed. It may have zero accounts, or accounts that each carry their own `credentialRef`.
32
+
33
+ ## Node Kind
34
+
35
+ The machine classification on `Host.kind`: `vm`, `physical`, `k8s-all-in-one`, `k8s-worker`
36
+ or `pod-host`. It describes how the machine participates in the deployment, not which
37
+ logical plane it serves. A missing kind reads as `vm`.
38
+
39
+ ## Command Surface
40
+
41
+ The command entry points available on a host, recorded in `Host.access`: `ssh`, `kubectl`
42
+ or `docker`. This is capability metadata, not an authorization grant and not a credential.
43
+
44
+ ## Pod Host
45
+
46
+ A machine running Pods that operators reach with `docker exec`, recorded as
47
+ `Host.kind: pod-host`. It is one Host even when it runs many Pods; individual Pods belong to
48
+ the deployment model, not `hosts[]`.
49
+
50
+ ## Web Login
51
+
52
+ A management or business console login recorded on `HostAccount`: `loginUrl` is the console
53
+ entry URL, `username` is the login name and `credentialRef` points to the password in the
54
+ DSH credential service. The URL is configuration, never a secret; the password is never
55
+ stored in the environment YAML.
56
+
57
+ ## Cluster
58
+
59
+ A Kubernetes or Docker cluster inside one environment.
60
+
61
+ Attributes: kind, optional topology (`all-in-one`, `separate` or `external`), API endpoint,
62
+ namespaces and a `credentialRef`. Kubernetes and Pod-host nodes reference it through
63
+ `Host.clusterRef`.
64
+
65
+ ## Cluster Topology
66
+
67
+ A descriptive label on `Cluster.topology`:
68
+
69
+ - `all-in-one` — control plane and worker on the same machine;
70
+ - `separate` — dedicated control plane and worker machines;
71
+ - `external` — a cluster managed outside this environment.
72
+
73
+ Per-host `Host.kind` is authoritative; topology does not replace it.
74
+
75
+ ## Logical Role
76
+
77
+ A named function a host can serve, such as `management`, `business`, `database` or
78
+ `extension`.
79
+
80
+ Hosts and roles are many-to-many via `Host.roles`. Standard role ids are seeded on
81
+ environment creation; custom ids are allowed but must be declared before use.
82
+
83
+ ## Service
84
+
85
+ A deployable software component described independently of any environment.
86
+
87
+ Attributes: id, name, aliases, category, Git URL and branch, build tool, artifact name, supported deploy modes and ordered rule profile references.
88
+
89
+ ## Deployment Binding
90
+
91
+ The relationship "this service runs here, in this runtime mode".
92
+
93
+ One service may have several bindings in one environment, so `(environmentId, serviceId)` is not unique.
94
+
95
+ ## Runtime Mode
96
+
97
+ `native`, `docker` or `kubernetes`. Determines which location fields and which log source apply.
98
+
99
+ ## Rule Profile
100
+
101
+ A reusable set of variables, paths, log sources and class locations.
102
+
103
+ Referenced by services in order; later profiles win on field conflicts.
104
+
105
+ ## Rule Override
106
+
107
+ A field-level override carried by an environment or a deployment.
108
+
109
+ Overriding one field leaves the other fields of the profile intact.
110
+
111
+ ## Rule Layer
112
+
113
+ One of `global`, `service`, `environment`, `deployment`, in ascending priority.
114
+
115
+ ## Template
116
+
117
+ A string containing `${...}` references, resolved by interpolation only.
118
+
119
+ No functions, operators, conditionals or shell execution.
120
+
121
+ ## Provenance
122
+
123
+ The explanation attached to a resolved value:
124
+
125
+ - `definedBy` — the layer and profile that supplied the winning template;
126
+ - `inputs` — referenced fields and the layer that supplied each;
127
+ - `shadowed` — lower-priority definitions that lost.
128
+
129
+ ## Derived Value
130
+
131
+ A value produced by rule resolution. It is not evidence that a file or endpoint exists.
132
+
133
+ ## Verified Value
134
+
135
+ A value confirmed by an online check. V1 does not produce verified values.
136
+
137
+ ## Service Context
138
+
139
+ The structured result of resolving an environment, service, deployment, rules and credential status.
140
+
141
+ Returned by `env_resolve`.
142
+
143
+ ## Operation Binding
144
+
145
+ A predicate mapping an operation in a given context to a specific Skill, with parameter templates and policy.
146
+
147
+ ## Match Level
148
+
149
+ How specific a binding is: `deployment`, `environment-service`, `service`, `category-mode`, `global`.
150
+
151
+ Higher levels win; same-level ties are conflicts.
152
+
153
+ ## Skill Reference
154
+
155
+ A pointer to a DSH Skill: name, optional expected source and provider.
156
+
157
+ It is discovery information, not execution authorization.
158
+
159
+ ## Approval Policy
160
+
161
+ The `requiresApproval` and `allowProduction` fields on a binding.
162
+
163
+ Write operations default to requiring approval; production defaults to denied.
164
+
165
+ ## Credential Reference
166
+
167
+ A `credentialRef` string stored in a registry record.
168
+
169
+ The value behind it lives in the DSH credential service or an external vault and is never returned by this plugin.
170
+
171
+ ## Credential Status
172
+
173
+ `configured`, `missing` or `unavailable`, obtained from the credential service without reading the value.
174
+
175
+ ## Session Context
176
+
177
+ The per-session default environment.
178
+
179
+ Advisory only; it never changes registry records or another session's state.
180
+
181
+ ## Operation Record
182
+
183
+ A structured, redacted description of a performed operation: scope, operation, Skill reference, timing, outcome, evidence references and summary.
184
+
185
+ Owned by the memory plugin from P1 onward.
186
+
187
+ ## Evidence Reference
188
+
189
+ An opaque, sanitized pointer to evidence produced during an operation.
190
+
191
+ Not the evidence itself.
192
+
193
+ ## Memory Scope
194
+
195
+ The environment/service/deployment scope attached to a memory query or record.
196
+
197
+ Prevents a single-environment conclusion from becoming a global rule.
198
+
199
+ ## Memory Bridge
200
+
201
+ The optional adapter between this plugin and the memory plugin.
202
+
203
+ Introduces no second store of environment facts and applies nothing automatically.
204
+
205
+ ## Review Queue
206
+
207
+ The place where candidate rule or Skill changes wait for a human decision.
208
+
209
+ ## Source of Truth
210
+
211
+ The durable data representation. Here: YAML registry files under the plugin data directory.
212
+
213
+ ## Harness
214
+
215
+ The project-level control system for AI-assisted development: context rules, constraints, execution and verification policies, and continuity practices.
@@ -0,0 +1,114 @@
1
+ # Project Brief
2
+
3
+ ## Project Name
4
+
5
+ DSH Environment Manager (`dsh-env-manager`)
6
+
7
+ ## Positioning
8
+
9
+ A DSH (DeepSeek Harness) plugin that gives every session a shared, queryable context of enterprise environments, services, deployments, rules and operation-to-Skill bindings.
10
+
11
+ It is the "where do I work, what am I touching, which rules apply, which Skill runs it, what have we learned" layer for operational Agents.
12
+
13
+ ## Core Value
14
+
15
+ The project turns:
16
+
17
+ ```text
18
+ scattered environment facts + ad-hoc SSH notes + tribal deployment knowledge
19
+ ```
20
+
21
+ into:
22
+
23
+ ```text
24
+ structured environment registry + service catalog + deployment bindings
25
+ + resolvable rules with provenance + deterministic Skill routing
26
+ + scoped memory references
27
+ ```
28
+
29
+ ## Primary Users
30
+
31
+ - Platform and DevOps engineers
32
+ - SREs and operations staff
33
+ - Backend developers deploying to shared environments
34
+ - AI-assisted development users running DSH sessions
35
+
36
+ ## Main Workflows
37
+
38
+ ### Workflow 1: Resolve Environment Context
39
+
40
+ ```text
41
+ Agent asks: "Where does aicoservice run in test-a?"
42
+ → look up environment and service
43
+ → match the deployment binding
44
+ → resolve layered rules
45
+ → return a Service Context with provenance
46
+ ```
47
+
48
+ ### Workflow 2: Route an Operation to a Skill
49
+
50
+ ```text
51
+ Agent asks: "Redeploy aicoservice in test-a"
52
+ → resolve the Service Context
53
+ → match operation bindings by scope
54
+ → detect conflicts
55
+ → check Skill availability
56
+ → return the Skill reference and mapped parameters with policy
57
+ ```
58
+
59
+ ### Workflow 3: Configure the Registry
60
+
61
+ ```text
62
+ Engineer adds environment, hosts, clusters and roles
63
+ → adds services with Git URLs and artifacts
64
+ → adds deployment bindings
65
+ → adds rule profiles and overrides
66
+ → previews resolved paths and bindings
67
+ ```
68
+
69
+ ### Workflow 4: Accumulate Experience (P1)
70
+
71
+ ```text
72
+ Operation completes
73
+ → emit a redacted operation record
74
+ → query prior observations for the same scope
75
+ → propose a rule or Skill change for review
76
+ → never auto-apply
77
+ ```
78
+
79
+ ## Core Principles
80
+
81
+ - File-based registry is the source of truth.
82
+ - Credentials are references; values live elsewhere.
83
+ - Skill routing is explicit, deterministic and conflict-aware.
84
+ - Derived values are labelled as derived; only checks can mark them verified.
85
+ - Conflicting or missing data fails loudly.
86
+ - Memory stores the lesson; this plugin stores the context.
87
+
88
+ ## V1 Scope
89
+
90
+ Delivered:
91
+
92
+ 1. DSH bundle with Host and Client halves.
93
+ 2. File-based registry for environments, services, deployments, rules and operation bindings.
94
+ 3. Manual configuration through tools and a minimal Web/Desktop UI.
95
+ 4. Layered rule resolution with provenance.
96
+ 5. Deterministic operation-to-Skill routing with availability and policy checks.
97
+ 6. Read-only tools usable from every session.
98
+ 7. Session-scoped default environment.
99
+
100
+ Deferred:
101
+
102
+ - Remote execution adapters (SSH, Docker, Kubernetes).
103
+ - Automatic deployment or rollback.
104
+ - Automatic fact extraction from repositories or manifests.
105
+ - Memory bridge implementation (contract only in V1).
106
+ - Automatic rule or Skill evolution.
107
+
108
+ ## Non-goals
109
+
110
+ - Not a CMDB replacement.
111
+ - Not a secret vault.
112
+ - Not a remote execution engine.
113
+ - Not an unsupervised self-modifying rule system.
114
+ - Not a database-backed platform.