From 8c901692895e25fa26c9040be940fb7b47957513 Mon Sep 17 00:00:00 2001 From: zhi Date: Sat, 21 Mar 2026 12:07:23 +0000 Subject: [PATCH] docs: add cross-project hf implementation todo list --- plans/hf-cross-project-todo.md | 405 +++++++++++++++++++++++++++++++++ 1 file changed, 405 insertions(+) create mode 100644 plans/hf-cross-project-todo.md diff --git a/plans/hf-cross-project-todo.md b/plans/hf-cross-project-todo.md new file mode 100644 index 0000000..7646f37 --- /dev/null +++ b/plans/hf-cross-project-todo.md @@ -0,0 +1,405 @@ +# hf / HarborForge Cross-Project TODO + +> Scope: HarborForge.Cli, HarborForge.Backend, HarborForge.Frontend, HarborForge.OpenclawPlugin, HarborForge.Monitor, HarborForge.Test +> +> Goal: land the new `hf` CLI and the supporting backend/frontend/plugin/monitor changes described in the main CLI plan. + +--- + +## 0. Cross-cutting / coordination + +- [ ] Finalize MVP scope for first shipping version of `hf` +- [ ] Confirm which existing backend routes can be reused vs which new routes are needed +- [ ] Define canonical code-first lookup policy across all resources +- [ ] Define permission introspection strategy for `--help` / `--help-brief` +- [ ] Define JSON output contract for CLI list/get commands +- [ ] Define CLI exit code / stderr conventions +- [ ] Define local plugin↔monitor communication protocol over `monitor_port` +- [ ] Define release order across submodules +- [ ] Define rollback strategy if plugin / monitor bridge is unavailable + +--- + +## 1. HarborForge.Cli + +### 1.1 Go project scaffold +- [ ] Initialize Go module for `hf` +- [ ] Add binary entrypoint (`cmd/hf/main.go` or equivalent) +- [ ] Add internal package layout (`config`, `help`, `mode`, `passmgr`, `client`, `commands`) +- [ ] Add build instructions to `README.md` +- [ ] Add `.gitignore` for Go artifacts +- [ ] Add repo-config-safe contribution note if needed + +### 1.2 Runtime mode detection +- [ ] Implement `which pass_mgr` detection on startup +- [ ] Add runtime mode enum: padded-cell mode / manual mode +- [ ] Block manual credential flags in padded-cell mode +- [ ] Return exact error when forbidden manual token flags are used: + - [ ] `padded-cell installed, --token flag disabled, use command directly` +- [ ] Define equivalent handling for `--acc-mgr-token` and related manual secret flags + +### 1.3 Config handling +- [ ] Resolve binary directory correctly at runtime +- [ ] Read `/.hf-config.json` +- [ ] Write/update `base-url` via `hf config --url` +- [ ] Add config validation for malformed/missing config +- [ ] Add `hf config --acc-mgr-token` +- [ ] Implement `pass_mgr set --public --key hf-acc-mgr-token --secret ` +- [ ] Return exact error on failure: + - [ ] `--acc-mgr-token can only be set with padded-cell plugin` + +### 1.4 Help system +- [ ] Implement `hf --help` +- [ ] Implement `hf --help-brief` +- [ ] Implement ` --help` +- [ ] Implement ` --help-brief` +- [ ] Implement leaf command `--help` +- [ ] Implement leaf command `--help-brief` +- [ ] Show all subcommands in normal help, marking unavailable ones as `(not permitted)` +- [ ] Hide unavailable commands entirely in `--help-brief` +- [ ] Ensure leaf `--help` for unavailable commands only prints `not permitted` +- [ ] Hide manual auth flags from help in padded-cell mode +- [ ] Show required manual auth flags in help in manual mode +- [ ] Handle special help behavior for `hf user create` + +### 1.5 Auth/token resolution layer +- [ ] Implement shared normal token resolution helper +- [ ] In padded-cell mode, resolve via `pass_mgr get-secret --key hf-token` +- [ ] In manual mode, require explicit `--token` +- [ ] Emit exact error on missing manual token: + - [ ] `--token required or execute this with pcexec` +- [ ] Ensure `hf --help` never requires token +- [ ] Ensure subcommand help can render even when token is unavailable + +### 1.6 Output model +- [ ] Add default human-readable output mode +- [ ] Add `--json` output mode +- [ ] Ensure list outputs include canonical resource code fields +- [ ] Ensure machine-readable output is stable enough for agent use + +### 1.7 Base commands +- [ ] Implement `hf version` +- [ ] Implement `hf health` + +### 1.8 User commands +- [ ] Implement `hf user create` +- [ ] Forbid `--token` on `hf user create` +- [ ] Do not support `--role` on `hf user create` +- [ ] Default created accounts to `guest` +- [ ] In padded-cell mode, auto-generate password with: + - [ ] `pass_mgr generate --key hf --username ` +- [ ] In padded-cell mode, auto-fetch account-manager token with: + - [ ] `pass_mgr get-secret --public --key hf-acc-mgr-token` +- [ ] Emit exact missing-password error: + - [ ] `--pass required or execute with pcexec` +- [ ] Emit exact missing-account-manager-token error: + - [ ] `--acc-mgr-token required or execute with pcexec` +- [ ] Implement `hf user list` +- [ ] Implement `hf user get ` +- [ ] Implement `hf user update ` +- [ ] Implement `hf user activate ` +- [ ] Implement `hf user deactivate ` +- [ ] Implement `hf user delete ` + +### 1.9 Role / permission commands +- [ ] Implement `hf role list` +- [ ] Implement `hf role get ` +- [ ] Implement `hf role create` +- [ ] Implement `hf role update` +- [ ] Implement `hf role delete` +- [ ] Implement `hf permission list` +- [ ] Implement `hf role set-permissions` +- [ ] Implement `hf role add-permissions` +- [ ] Implement `hf role remove-permissions` + +### 1.10 Project / milestone commands +- [ ] Implement `hf project list` +- [ ] Implement `hf project get ` +- [ ] Implement `hf project create` +- [ ] Implement `hf project update ` +- [ ] Implement `hf project delete ` +- [ ] Implement `hf project members ` +- [ ] Implement `hf project add-member ` +- [ ] Implement `hf project remove-member ` +- [ ] Implement `hf milestone list --project ` +- [ ] Implement `hf milestone get ` +- [ ] Implement `hf milestone create` +- [ ] Implement `hf milestone update ` +- [ ] Implement `hf milestone delete ` +- [ ] Implement `hf milestone progress ` + +### 1.11 Task commands +- [ ] Implement `hf task list` +- [ ] Add filters: + - [ ] `--project ` + - [ ] `--milestone ` + - [ ] `--status ` + - [ ] `--taken-by ` + - [ ] `--due-today ` + - [ ] repeated `--order-by ` +- [ ] Implement `hf task get ` +- [ ] Implement `hf task create` +- [ ] Implement `hf task update ` +- [ ] Implement `hf task transition ` +- [ ] Implement `hf task take ` +- [ ] Return clear error when task is already taken by someone else +- [ ] Return clear error when caller lacks permission to take task +- [ ] Implement `hf task delete ` +- [ ] Implement `hf task search` + +### 1.12 Meeting commands +- [ ] Implement `hf meeting list` +- [ ] Implement `hf meeting get ` +- [ ] Implement `hf meeting create` +- [ ] Implement `hf meeting update ` +- [ ] Implement `hf meeting attend ` +- [ ] Ensure attend adds caller to participant list +- [ ] Implement `hf meeting delete ` + +### 1.13 Support commands +- [ ] Implement `hf support list` +- [ ] Implement `hf support get ` +- [ ] Implement `hf support create` +- [ ] Implement `hf support update ` +- [ ] Implement `hf support take ` +- [ ] Implement `hf support transition ` +- [ ] Implement `hf support delete ` + +### 1.14 Propose commands +- [ ] Implement `hf propose list --project ` +- [ ] Implement `hf propose get ` +- [ ] Implement `hf propose create` +- [ ] Implement `hf propose update ` +- [ ] Implement `hf propose accept --milestone ` +- [ ] Implement `hf propose reject ` +- [ ] Implement `hf propose reopen ` + +### 1.15 Monitor commands +- [ ] Implement `hf monitor overview` +- [ ] Implement `hf monitor server list` +- [ ] Implement `hf monitor server get ` +- [ ] Implement `hf monitor server create --identifier ` +- [ ] Implement `hf monitor server delete ` +- [ ] Implement `hf monitor api-key generate ` +- [ ] Implement `hf monitor api-key revoke ` + +### 1.16 CLI packaging / release +- [ ] Add cross-platform build targets if needed +- [ ] Add release artifact naming for `hf` +- [ ] Add install documentation +- [ ] Add shell examples for padded-cell and manual mode + +--- + +## 2. HarborForge.Backend + +### 2.1 Code-first API support +- [ ] Audit all CLI-targeted resources for code availability +- [ ] Ensure `project-code` is accepted in get/update/delete/member APIs +- [ ] Ensure `milestone-code` is accepted in get/update/delete/progress APIs +- [ ] Ensure `task-code` is accepted in get/update/delete/transition APIs +- [ ] Ensure `meeting-code` is accepted in get/update/delete/attend APIs +- [ ] Ensure `support-code` is accepted in get/update/delete/take/transition APIs +- [ ] Ensure `propose-code` is accepted in get/update/delete/accept/reject/reopen APIs +- [ ] Add code-based list filters where missing +- [ ] Ensure CLI-related list payloads always include canonical code fields + +### 2.2 User / account-manager flow +- [ ] Review current `account-manager` permission implementation +- [ ] Add dedicated backend flow for account-manager-based account creation if current `/users` route is insufficient +- [ ] Ensure `hf user create` maps cleanly to backend account-manager permission model +- [ ] Ensure new accounts default to `guest` +- [ ] Ensure admin role cannot be assigned through normal user management APIs + +### 2.3 Permission introspection for CLI help +- [ ] Decide how CLI will query effective permissions +- [ ] Add/extend backend endpoint(s) for current-user permission introspection if needed +- [ ] Ensure CLI can cheaply determine whether a subcommand is permitted +- [ ] Support permission-aware help rendering without excessive API chattiness + +### 2.4 Task / meeting / support actions +- [ ] Add/confirm backend route for task self-assignment (`task take`) +- [ ] Add/confirm conflict behavior when task already has a different assignee +- [ ] Add/confirm backend route for meeting attendance (`meeting attend`) +- [ ] Ensure meeting attendance updates participant list +- [ ] Add/confirm backend route for support self-assignment (`support take`) + +### 2.5 Frontend-facing code migration support +- [ ] Add code-based detail endpoints or code query support for frontend routing +- [ ] Ensure frontend can resolve resources by code without fallback to id-only APIs +- [ ] Update serializers to expose code prominently wherever applicable + +### 2.6 Legacy Python CLI retirement +- [ ] Track parity between new `hf` CLI and old backend Python CLI +- [ ] Once parity is acceptable, remove legacy Python CLI from backend repo +- [ ] Remove backend docs referencing the old Python CLI + +--- + +## 3. HarborForge.Frontend + +### 3.1 Code-first UI migration +- [ ] Audit current routes and identify every place still using raw ids +- [ ] Move project detail lookup toward `project-code` +- [ ] Move milestone detail lookup toward `milestone-code` +- [ ] Move task detail lookup toward `task-code` +- [ ] Move meeting detail lookup toward `meeting-code` +- [ ] Move support detail lookup toward `support-code` +- [ ] Move propose detail lookup toward `propose-code` +- [ ] Stop surfacing raw ids as the main visible identifier in lists/details +- [ ] Display codes consistently in relevant list and detail views + +### 3.2 User / role UX alignment +- [ ] Review current user management page against final backend behavior +- [ ] Ensure only code/name-first identifiers are shown where relevant +- [ ] Ensure account role display matches single-role model everywhere + +### 3.3 Meeting / support UI +- [ ] Audit current frontend support for meeting resources +- [ ] Add/adjust UI for meeting participant state if needed +- [ ] Add/adjust UI for support take/ownership state if needed + +### 3.4 Monitor UI alignment +- [ ] Ensure monitor views expose server identifier/code cleanly +- [ ] Review display of OpenClaw/plugin metadata once Monitor bridge is implemented + +### 3.5 Future CLI alignment aids +- [ ] Consider showing canonical codes more prominently to help users map UI↔CLI +- [ ] Ensure copyable resource codes are easy to find from the UI + +--- + +## 4. HarborForge.OpenclawPlugin + +### 4.1 Plugin identity and packaging +- [ ] Rename plugin registration name to `harbor-forge` +- [ ] Audit all docs/config/install references to old plugin name +- [ ] Ensure plugin config keys and examples reflect the new registration name + +### 4.2 Remove sidecar architecture +- [ ] Remove plugin-side `server/` telemetry sidecar +- [ ] Remove sidecar startup/shutdown lifecycle logic +- [ ] Remove sidecar-specific docs and examples +- [ ] Replace old OpenClaw telemetry flow with direct plugin-exposed data path + +### 4.3 Plugin config updates +- [ ] Add `monitor_port` to plugin config schema +- [ ] Document `monitor_port` in plugin README/docs/examples +- [ ] Ensure runtime reads and validates `monitor_port` + +### 4.4 CLI install support +- [ ] Add install script flag `--install-cli` +- [ ] Resolve OpenClaw profile bin directory (default `~/.openclaw/bin`) +- [ ] Build `HarborForge.Cli` +- [ ] Install compiled `hf` binary to profile `bin/` +- [ ] `chmod +x` installed binary +- [ ] Handle failure cases cleanly if CLI build/install fails + +### 4.5 Skills deployment +- [ ] Add plugin `skills/` directory +- [ ] Add `skills/hf/` +- [ ] Add `skills/hf/SKILL.md` +- [ ] In `SKILL.md`, explain basic `hf` usage +- [ ] In `SKILL.md`, encourage agents to use `hf --help-brief` +- [ ] In `SKILL.md`, point to normal `--help` for full command tree +- [ ] Installer should copy normal plugin skills into profile `skills/` +- [ ] Installer should **not** copy `skills/hf/` unless `--install-cli` is present +- [ ] Installer should copy `skills/hf/` when `--install-cli` is present + +### 4.6 Monitor bridge endpoint +- [ ] Define how plugin exposes OpenClaw metadata to Monitor over local port +- [ ] Decide HTTP endpoint structure / payload schema +- [ ] Expose OpenClaw version +- [ ] Expose plugin version +- [ ] Expose agent list / agent metadata +- [ ] Ensure plugin remains functional even if Monitor never connects + +--- + +## 5. HarborForge.Monitor + +### 5.1 Docker/runtime changes +- [ ] Add `MONITOR_PORT` env var +- [ ] Ensure Monitor listens on `127.0.0.1:` +- [ ] Update Docker runtime docs/examples +- [ ] Update docker-compose to expose that port to host `127.0.0.1` + +### 5.2 Plugin communication +- [ ] Implement local communication client to query plugin over `MONITOR_PORT` +- [ ] Define request timeout / retry / fallback policy +- [ ] Keep startup independent of plugin communication success +- [ ] Keep heartbeat/telemetry upload independent of plugin communication success +- [ ] If plugin is reachable, enrich telemetry with: + - [ ] OpenClaw version + - [ ] plugin version + - [ ] agent info +- [ ] If plugin is unreachable, continue current behavior unchanged + +### 5.3 Telemetry model alignment +- [ ] Ensure backend-facing telemetry payloads can carry optional OpenClaw metadata +- [ ] Avoid making plugin-derived fields mandatory +- [ ] Ensure monitor data model cleanly distinguishes: + - [ ] host/hardware telemetry + - [ ] optional OpenClaw metadata + +### 5.4 Docs / examples +- [ ] Update Monitor README to explain `MONITOR_PORT` +- [ ] Explain degraded mode when plugin bridge is absent +- [ ] Provide example Docker run / compose snippet with host loopback exposure + +--- + +## 6. HarborForge.Test / HarborForge.Frontend.Test + +### 6.1 Keep test runner aligned +- [ ] Preserve Frontend.Test Dockerfile as owner of proxy startup +- [ ] Keep `run-test-frontend.sh` from overriding default test container CMD unless strictly necessary +- [ ] Keep expose-port mode working with 127.0.0.1 + proxy architecture + +### 6.2 Code-first frontend test updates +- [ ] Update tests to prefer resource codes over ids in assertions and navigation +- [ ] Remove assumptions that UI surfaces raw ids where codes should be primary + +### 6.3 Future CLI tests +- [ ] Add tests for `hf` help rendering +- [ ] Add tests for `hf --help-brief` +- [ ] Add tests for padded-cell mode vs manual mode +- [ ] Add tests for exact stderr messages +- [ ] Add tests for code-only command acceptance + +--- + +## 7. Suggested implementation order + +### Phase A — Foundations +- [ ] Finalize CLI help / mode / output model +- [ ] Finalize backend permission introspection approach +- [ ] Finalize plugin↔monitor local protocol + +### Phase B — Backend first +- [ ] Add/finish code-based backend support +- [ ] Add/finish task take / meeting attend / support take +- [ ] Add any missing account-manager creation behavior + +### Phase C — CLI MVP +- [ ] Build `hf` scaffold +- [ ] Ship `version`, `health`, `config` +- [ ] Ship `user create`, `user list`, `user get` +- [ ] Ship `task list`, `task get`, `task take` +- [ ] Ship initial `monitor` commands + +### Phase D — Frontend alignment +- [ ] Move frontend to code-first lookup/display +- [ ] Surface canonical codes consistently in UI + +### Phase E — Plugin / Monitor integration +- [ ] Rename plugin to `harbor-forge` +- [ ] Remove plugin sidecar +- [ ] Add `--install-cli` +- [ ] Add `skills/hf` +- [ ] Add `monitor_port` / `MONITOR_PORT` bridge + +### Phase F — Cleanup / retirement +- [ ] Remove legacy backend Python CLI +- [ ] Update all docs to point to `hf` +- [ ] Add final tests and packaging flow