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.
- package/LICENSE +21 -0
- package/README.md +273 -3
- package/client.js +2581 -0
- package/cordis.patch.yml +4 -0
- package/docs/00-project/current-state.md +272 -0
- package/docs/00-project/glossary.md +215 -0
- package/docs/00-project/project-brief.md +114 -0
- package/docs/00-project/roadmap.md +89 -0
- package/docs/01-architecture/DSH_Environment_Service_Memory_Skill_Brainstorm.md +493 -0
- package/docs/01-architecture/api-verification.md +416 -0
- package/docs/01-architecture/architecture-overview.md +222 -0
- package/docs/01-architecture/data-model.md +930 -0
- package/docs/01-architecture/decisions/ADR-0001-plugin-as-bundle.md +29 -0
- package/docs/01-architecture/decisions/ADR-0002-file-based-storage.md +25 -0
- package/docs/01-architecture/decisions/ADR-0003-skill-router-over-search.md +25 -0
- package/docs/01-architecture/decisions/ADR-0004-typescript-host-js-client.md +31 -0
- package/docs/01-architecture/decisions/ADR-0005-layered-rule-resolution.md +36 -0
- package/docs/01-architecture/decisions/ADR-0006-credentials-as-references.md +30 -0
- package/docs/01-architecture/decisions/ADR-0007-session-scoped-default-environment.md +28 -0
- package/docs/01-architecture/decisions/ADR-0008-memory-bridge-not-second-store.md +31 -0
- package/docs/01-architecture/decisions/ADR-0009-client-host-http-transport.md +87 -0
- package/docs/01-architecture/decisions/ADR-0010-environment-plane-model.md +87 -0
- package/docs/01-architecture/decisions/ADR-0011-k8s-node-execution-model.md +92 -0
- package/docs/01-architecture/design.md +666 -0
- package/docs/01-architecture/detailed-design.md +961 -0
- package/docs/01-architecture/implementation-plan.md +323 -0
- package/docs/01-architecture/module-boundaries.md +306 -0
- package/docs/01-architecture/security-model.md +227 -0
- package/docs/01-architecture/storage-contract.md +224 -0
- package/docs/01-architecture/tool-contract.md +438 -0
- package/docs/01-architecture/ui-design.md +587 -0
- package/docs/02-harness/agent-behavior.md +36 -0
- package/docs/02-harness/change-snapshot-policy.md +29 -0
- package/docs/02-harness/client-ui-integration.md +110 -0
- package/docs/02-harness/context-policy.md +43 -0
- package/docs/02-harness/harness-standard.md +91 -0
- package/docs/02-harness/task-execution-policy.md +26 -0
- package/docs/02-harness/verification-policy.md +97 -0
- package/docs/03-openspec/archive-rule.md +25 -0
- package/docs/03-openspec/bugfix-rule.md +30 -0
- package/docs/03-openspec/design-rule.md +33 -0
- package/docs/03-openspec/openspec-usage-guide.md +31 -0
- package/docs/03-openspec/proposal-rule.md +70 -0
- package/docs/03-openspec/spec-rule.md +33 -0
- package/docs/03-openspec/tasks-rule.md +31 -0
- package/docs/04-development/coding-style.md +67 -0
- package/docs/04-development/dependency-policy.md +43 -0
- package/docs/04-development/development-guide.md +85 -0
- package/docs/04-development/directory-convention.md +105 -0
- package/docs/04-development/local-run-guide.md +61 -0
- package/docs/04-development/testing-guide.md +102 -0
- package/docs/05-domain/deployment-template.md +76 -0
- package/docs/05-domain/environment-template.md +165 -0
- package/docs/05-domain/operation-binding-template.md +55 -0
- package/docs/05-domain/operation-record-template.md +55 -0
- package/docs/05-domain/prompt-template.md +90 -0
- package/docs/05-domain/rule-template.md +73 -0
- package/docs/05-domain/service-template.md +39 -0
- package/docs/06-operations/deployment-guide.md +54 -0
- package/docs/06-operations/release.md +198 -0
- package/docs/06-operations/security-policy.md +53 -0
- package/docs/06-operations/troubleshooting.md +141 -0
- package/docs/07-templates/adr-template.md +21 -0
- package/docs/07-templates/bugfix-template.md +11 -0
- package/docs/07-templates/case-template.md +15 -0
- package/docs/07-templates/design-template.md +29 -0
- package/docs/07-templates/proposal-template.md +19 -0
- package/docs/07-templates/spec-template.md +15 -0
- package/docs/07-templates/tasks-template.md +12 -0
- package/docs/99-archive/README.md +13 -0
- package/docs/README.md +142 -0
- package/icon.svg +4 -0
- package/index.js +31 -0
- package/lib/app/app.d.ts +67 -0
- package/lib/app/app.js +494 -0
- package/lib/app/app.js.map +1 -0
- package/lib/config.d.ts +55 -0
- package/lib/config.js +42 -0
- package/lib/config.js.map +1 -0
- package/lib/domain/constants.d.ts +21 -0
- package/lib/domain/constants.js +59 -0
- package/lib/domain/constants.js.map +1 -0
- package/lib/domain/errors.d.ts +20 -0
- package/lib/domain/errors.js +22 -0
- package/lib/domain/errors.js.map +1 -0
- package/lib/domain/schemas.d.ts +28 -0
- package/lib/domain/schemas.js +445 -0
- package/lib/domain/schemas.js.map +1 -0
- package/lib/domain/types.d.ts +412 -0
- package/lib/domain/types.js +2 -0
- package/lib/domain/types.js.map +1 -0
- package/lib/index.d.ts +18 -0
- package/lib/index.js +89 -0
- package/lib/index.js.map +1 -0
- package/lib/logger.d.ts +8 -0
- package/lib/logger.js +13 -0
- package/lib/logger.js.map +1 -0
- package/lib/memory/bridge.d.ts +18 -0
- package/lib/memory/bridge.js +13 -0
- package/lib/memory/bridge.js.map +1 -0
- package/lib/registry/integrity.d.ts +10 -0
- package/lib/registry/integrity.js +204 -0
- package/lib/registry/integrity.js.map +1 -0
- package/lib/registry/registry.d.ts +14 -0
- package/lib/registry/registry.js +182 -0
- package/lib/registry/registry.js.map +1 -0
- package/lib/resolver/merge.d.ts +23 -0
- package/lib/resolver/merge.js +90 -0
- package/lib/resolver/merge.js.map +1 -0
- package/lib/resolver/resolve.d.ts +18 -0
- package/lib/resolver/resolve.js +288 -0
- package/lib/resolver/resolve.js.map +1 -0
- package/lib/resolver/template.d.ts +10 -0
- package/lib/resolver/template.js +42 -0
- package/lib/resolver/template.js.map +1 -0
- package/lib/router/params.d.ts +3 -0
- package/lib/router/params.js +83 -0
- package/lib/router/params.js.map +1 -0
- package/lib/router/router.d.ts +11 -0
- package/lib/router/router.js +204 -0
- package/lib/router/router.js.map +1 -0
- package/lib/session/session.d.ts +16 -0
- package/lib/session/session.js +64 -0
- package/lib/session/session.js.map +1 -0
- package/lib/skill.d.ts +17 -0
- package/lib/skill.js +56 -0
- package/lib/skill.js.map +1 -0
- package/lib/storage/atomic.d.ts +10 -0
- package/lib/storage/atomic.js +107 -0
- package/lib/storage/atomic.js.map +1 -0
- package/lib/storage/paths.d.ts +10 -0
- package/lib/storage/paths.js +50 -0
- package/lib/storage/paths.js.map +1 -0
- package/lib/storage/records.d.ts +16 -0
- package/lib/storage/records.js +112 -0
- package/lib/storage/records.js.map +1 -0
- package/lib/storage/sessions.d.ts +17 -0
- package/lib/storage/sessions.js +65 -0
- package/lib/storage/sessions.js.map +1 -0
- package/lib/tools/tools.d.ts +14 -0
- package/lib/tools/tools.js +472 -0
- package/lib/tools/tools.js.map +1 -0
- package/lib/transport/http.d.ts +3 -0
- package/lib/transport/http.js +217 -0
- package/lib/transport/http.js.map +1 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +101 -6
- package/scripts/repair-profile.mjs +141 -0
package/cordis.patch.yml
ADDED
|
@@ -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.
|