zhi/HarborForge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: move plans into archive and place next wave doc under plans

Browse Source
This commit is contained in:
nav
2026-03-29 11:19:33 +00:00
parent c2b9242aca
commit b416c60ae7
7 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

430
archive/achieve/hf-cross-project-todo.md Normal file
View File

@@ -0,0 +1,430 @@
# 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
- [x] Finalize MVP scope for first shipping version of `hf`
- MVP includes: all CRUD commands for users, roles, projects, milestones, tasks, meetings, support, proposals, monitor
- Permission-aware help system, padded-cell/manual mode, code-first resource addressing
- Plugin installer `--install-cli` for automated deployment
- [x] Confirm which existing backend routes can be reused vs which new routes are needed
- [x] Define canonical code-first lookup policy across all resources
- [x] Define permission introspection strategy for `--help` / `--help-brief`
- settled as: token → current user → user role → role permissions
- `hf user create` remains a special account-manager-token flow and is not gated by ordinary user-token write permission
- [x] Define JSON output contract for CLI list/get commands
- current CLI contract: `--json` emits raw success payloads on stdout without a universal envelope; list/get responses should preserve canonical code-bearing fields when backend payloads provide them
- [x] Define CLI exit code / stderr conventions
- current CLI contract: success exits `0`; validation/runtime failures exit `1`; errors go to stderr and successful output goes to stdout
- [x] Define local plugin↔monitor communication protocol over `monitor_port`
- Monitor exposes `GET /health`, `GET /telemetry`, `POST /openclaw` on 127.0.0.1:MONITOR_PORT
- Plugin pushes OpenClaw metadata via POST /openclaw; Monitor enriches heartbeats with received data
- All communication is optional/degradable — both sides function independently
- [x] Define release order across submodules
- 1. Backend (code-first APIs, permission introspection)
- 2. CLI (depends on backend API surface)
- 3. Frontend (code-first UI, independent of CLI)
- 4. Monitor (standalone, bridge is optional)
- 5. Plugin (depends on CLI build for --install-cli, depends on Monitor for bridge)
- [x] Define rollback strategy if plugin / monitor bridge is unavailable
- Graceful degradation: Monitor operates normally without plugin data
- Plugin operates normally without Monitor bridge
- No hard dependency in either direction — bridge is optional enrichment
> Note: the CLI contract items above are now documented from the currently implemented `HarborForge.Cli` behavior; they can still be refined later if a stricter release contract is needed.
---
## 1. HarborForge.Cli
### 1.1 Go project scaffold
- [x] Initialize Go module for `hf`
- [x] Add binary entrypoint (`cmd/hf/main.go` or equivalent)
- [x] Add internal package layout (`config`, `help`, `mode`, `passmgr`, `client`, `commands`)
- [x] Add build instructions to `README.md`
- [x] Add `.gitignore` for Go artifacts
- [x] Add repo-config-safe contribution note if needed
- CLI README already contains build/run/install docs; no separate contribution note needed for current scope
### 1.2 Runtime mode detection
- [x] Implement `which pass_mgr` detection on startup
- [x] Add runtime mode enum: padded-cell mode / manual mode
- [x] Block manual credential flags in padded-cell mode
- [x] Return exact error when forbidden manual token flags are used:
- [x] `padded-cell installed, --token flag disabled, use command directly`
- [x] Define equivalent handling for `--acc-mgr-token` and related manual secret flags
### 1.3 Config handling
- [x] Resolve binary directory correctly at runtime
- [x] Read `<binary-dir>/.hf-config.json`
- [x] Write/update `base-url` via `hf config --url`
- [x] Add config validation for malformed/missing config
- [x] Add `hf config --acc-mgr-token`
- [x] Implement `pass_mgr set --public --key hf-acc-mgr-token --secret <token>`
- [x] Return exact error on failure:
- [x] `--acc-mgr-token can only be set with padded-cell plugin`
### 1.4 Help system
- [x] Implement `hf --help`
- [x] Implement `hf --help-brief`
- [x] Implement `<group> --help`
- [x] Implement `<group> --help-brief`
- [x] Implement leaf command `--help`
- [x] Implement leaf command `--help-brief`
- [x] Show all subcommands in normal help, marking unavailable ones as `(not permitted)`
- [x] Hide unavailable commands entirely in `--help-brief`
- [x] Ensure leaf `--help` for unavailable commands only prints `not permitted`
- [x] Hide manual auth flags from help in padded-cell mode
- [x] Show required manual auth flags in help in manual mode
- [x] Handle special help behavior for `hf user create`
### 1.5 Auth/token resolution layer
- [x] Implement shared normal token resolution helper
- [x] In padded-cell mode, resolve via `pass_mgr get-secret --key hf-token`
- [x] In manual mode, require explicit `--token`
- [x] Emit exact error on missing manual token:
- [x] `--token <token> required or execute this with pcexec`
- [x] Ensure `hf --help` never requires token
- [x] Ensure subcommand help can render even when token is unavailable
### 1.6 Output model
- [x] Add default human-readable output mode
- [x] Add `--json` output mode
- [x] Ensure list outputs include canonical resource code fields
- [x] Ensure machine-readable output is stable enough for agent use
### 1.7 Base commands
- [x] Implement `hf version`
- [x] Implement `hf health`
### 1.8 User commands
- [x] Implement `hf user create`
- [x] Forbid `--token` on `hf user create`
- [x] Do not support `--role` on `hf user create`
- [x] Default created accounts to `guest`
- [x] In padded-cell mode, auto-generate password with:
- [x] `pass_mgr generate --key hf --username <username>`
- [x] In padded-cell mode, auto-fetch account-manager token with:
- [x] `pass_mgr get-secret --public --key hf-acc-mgr-token`
- [x] Emit exact missing-password error:
- [x] `--pass <password> required or execute with pcexec`
- [x] Emit exact missing-account-manager-token error:
- [x] `--acc-mgr-token <token> required or execute with pcexec`
- [x] Implement `hf user list`
- [x] Implement `hf user get <username>`
- [x] Implement `hf user update <username>`
- [x] Implement `hf user activate <username>`
- [x] Implement `hf user deactivate <username>`
- [x] Implement `hf user delete <username>`
### 1.9 Role / permission commands
- [x] Implement `hf role list`
- [x] Implement `hf role get <role-name>`
- [x] Implement `hf role create`
- [x] Implement `hf role update`
- [x] Implement `hf role delete`
- [x] Implement `hf permission list`
- [x] Implement `hf role set-permissions`
- [x] Implement `hf role add-permissions`
- [x] Implement `hf role remove-permissions`
### 1.10 Project / milestone commands
- [x] Implement `hf project list`
- [x] Implement `hf project get <project-code>`
- [x] Implement `hf project create`
- [x] Implement `hf project update <project-code>`
- [x] Implement `hf project delete <project-code>`
- [x] Implement `hf project members <project-code>`
- [x] Implement `hf project add-member <project-code>`
- [x] Implement `hf project remove-member <project-code>`
- [x] Implement `hf milestone list --project <project-code>`
- [x] Implement `hf milestone get <milestone-code>`
- [x] Implement `hf milestone create`
- [x] Implement `hf milestone update <milestone-code>`
- [x] Implement `hf milestone delete <milestone-code>`
- [x] Implement `hf milestone progress <milestone-code>`
### 1.11 Task commands
- [x] Implement `hf task list`
- [x] Add filters:
- [x] `--project <project-code>`
- [x] `--milestone <milestone-code>`
- [x] `--status <status>`
- [x] `--taken-by <me|null|username>`
- [x] `--due-today <true|false>`
- [x] repeated `--order-by <due-date|priority|created|name>`
- [x] Implement `hf task get <task-code>`
- [x] Implement `hf task create`
- [x] Implement `hf task update <task-code>`
- [x] Implement `hf task transition <task-code> <status>`
- [x] Implement `hf task take <task-code>`
- [x] Return clear error when task is already taken by someone else
- [x] Return clear error when caller lacks permission to take task
- [x] Implement `hf task delete <task-code>`
- [x] Implement `hf task search`
### 1.12 Meeting commands
- [x] Implement `hf meeting list`
- [x] Implement `hf meeting get <meeting-code>`
- [x] Implement `hf meeting create`
- [x] Implement `hf meeting update <meeting-code>`
- [x] Implement `hf meeting attend <meeting-code>`
- [x] Ensure attend adds caller to participant list
- [x] Implement `hf meeting delete <meeting-code>`
### 1.13 Support commands
- [x] Implement `hf support list`
- [x] Implement `hf support get <support-code>`
- [x] Implement `hf support create`
- [x] Implement `hf support update <support-code>`
- [x] Implement `hf support take <support-code>`
- [x] Implement `hf support transition <support-code> <status>`
- [x] Implement `hf support delete <support-code>`
### 1.14 Propose commands
- [x] Implement `hf propose list --project <project-code>`
- [x] Implement `hf propose get <propose-code>`
- [x] Implement `hf propose create`
- [x] Implement `hf propose update <propose-code>`
- [x] Implement `hf propose accept <propose-code> --milestone <milestone-code>`
- [x] Implement `hf propose reject <propose-code>`
- [x] Implement `hf propose reopen <propose-code>`
### 1.15 Monitor commands
- [x] Implement `hf monitor overview`
- [x] Implement `hf monitor server list`
- [x] Implement `hf monitor server get <identifier>`
- [x] Implement `hf monitor server create --identifier <identifier>`
- [x] Implement `hf monitor server delete <identifier>`
- [x] Implement `hf monitor api-key generate <identifier>`
- [x] Implement `hf monitor api-key revoke <identifier>`
### 1.16 CLI packaging / release
- [x] Add cross-platform build targets if needed
- [x] Add release artifact naming for `hf`
- [x] Add install documentation
- [x] Add shell examples for padded-cell and manual mode
---
## 2. HarborForge.Backend
### 2.1 Code-first API support
- [x] Audit all CLI-targeted resources for code availability
- [x] Ensure `project-code` is accepted in get/update/delete/member APIs
- [x] Ensure `milestone-code` is accepted in get/update/delete/progress APIs
- [x] Ensure `task-code` is accepted in get/update/delete/transition APIs
- [x] Ensure `meeting-code` is accepted in get/update/delete/attend APIs
- [x] Ensure `support-code` is accepted in get/update/delete/take/transition APIs
- [x] Ensure `propose-code` is accepted in get/update/delete/accept/reject/reopen APIs
- [x] Add code-based list filters where missing
- [x] Ensure CLI-related list payloads always include canonical code fields
### 2.2 User / account-manager flow
- [x] Review current `account-manager` permission implementation
- [x] Add dedicated backend flow for account-manager-based account creation if current `/users` route is insufficient
- [x] Ensure `hf user create` maps cleanly to backend account-manager permission model
- [x] Ensure new accounts default to `guest`
- [x] Ensure admin role cannot be assigned through normal user management APIs
### 2.3 Permission introspection for CLI help
- [x] Decide how CLI will query effective permissions
- [x] Add/extend backend endpoint(s) for current-user permission introspection if needed
- [x] Ensure CLI can cheaply determine whether a subcommand is permitted
- [x] Support permission-aware help rendering without excessive API chattiness
### 2.4 Task / meeting / support actions
- [x] Add/confirm backend route for task self-assignment (`task take`)
- [x] Add/confirm conflict behavior when task already has a different assignee
- [x] Add/confirm backend route for meeting attendance (`meeting attend`)
- [x] Ensure meeting attendance updates participant list
- [x] Add/confirm backend route for support self-assignment (`support take`)
### 2.5 Frontend-facing code migration support
- [x] Add code-based detail endpoints or code query support for frontend routing
- [x] Ensure frontend can resolve resources by code without fallback to id-only APIs
- [x] Update serializers to expose code prominently wherever applicable
### 2.6 Legacy Python CLI retirement
- [x] Track parity between new `hf` CLI and old backend Python CLI
- [x] Once parity is acceptable, remove legacy Python CLI from backend repo
- [x] Remove backend docs referencing the old Python CLI
---
## 3. HarborForge.Frontend
### 3.1 Code-first UI migration
- [x] Audit current routes and identify every place still using raw ids
- [x] Move project detail lookup toward `project-code`
- [x] Move milestone detail lookup toward `milestone-code`
- [x] Move task detail lookup toward `task-code`
- [x] Move meeting detail lookup toward `meeting-code`
- [x] Move support detail lookup toward `support-code`
- [x] Move propose detail lookup toward `propose-code`
- [x] Stop surfacing raw ids as the main visible identifier in lists/details
- [x] Display codes consistently in relevant list and detail views
### 3.2 User / role UX alignment
- [x] Review current user management page against final backend behavior
- [x] Ensure only code/name-first identifiers are shown where relevant
- [x] Ensure account role display matches single-role model everywhere
### 3.3 Meeting / support UI
- [x] Audit current frontend support for meeting resources
- [x] Add/adjust UI for meeting participant state if needed
- [x] Add/adjust UI for support take/ownership state if needed
### 3.4 Monitor UI alignment
- [x] Ensure monitor views expose server identifier/code cleanly
- [ ] Review display of OpenClaw/plugin metadata once Monitor bridge is deployed
### 3.5 Future CLI alignment aids
- [x] Consider showing canonical codes more prominently to help users map UI↔CLI
- [x] Ensure copyable resource codes are easy to find from the UI
---
## 4. HarborForge.OpenclawPlugin
### 4.1 Plugin identity and packaging
- [x] Rename plugin registration name to `harbor-forge`
- [x] Audit all docs/config/install references to old plugin name
- [x] Ensure plugin config keys and examples reflect the new registration name
### 4.2 Remove sidecar architecture
- [x] Remove plugin-side `server/` telemetry sidecar
- [x] Remove sidecar startup/shutdown lifecycle logic
- [x] Remove sidecar-specific docs and examples
- [x] Replace old OpenClaw telemetry flow with direct plugin-exposed data path
### 4.3 Plugin config updates
- [x] Add `monitor_port` to plugin config schema
- [x] Document `monitor_port` in plugin README/docs/examples
- [x] Ensure runtime reads and validates `monitor_port`
### 4.4 CLI install support
- [x] Add install script flag `--install-cli`
- [x] Resolve OpenClaw profile bin directory (default `~/.openclaw/bin`)
- [x] Build `HarborForge.Cli`
- [x] Install compiled `hf` binary to profile `bin/`
- [x] `chmod +x` installed binary
- [x] Handle failure cases cleanly if CLI build/install fails
### 4.5 Skills deployment
- [x] Add plugin `skills/` directory
- [x] Add `skills/hf/`
- [x] Add `skills/hf/SKILL.md`
- [x] In `SKILL.md`, explain basic `hf` usage
- [x] In `SKILL.md`, encourage agents to use `hf --help-brief`
- [x] In `SKILL.md`, point to normal `--help` for full command tree
- [x] Installer should copy normal plugin skills into profile `skills/`
- [x] Installer should **not** copy `skills/hf/` unless `--install-cli` is present
- [x] Installer should copy `skills/hf/` when `--install-cli` is present
### 4.6 Monitor bridge endpoint
- [x] Define how plugin exposes OpenClaw metadata to Monitor over local port
- Plugin periodically POSTs metadata to Monitor bridge `POST /openclaw`
- [x] Decide HTTP endpoint structure / payload schema
- `POST /openclaw` with `{ version, plugin_version, agents }`
- [x] Expose OpenClaw version
- [x] Expose plugin version
- [x] Expose agent list / agent metadata
- [x] Ensure plugin remains functional even if Monitor never connects
---
## 5. HarborForge.Monitor
### 5.1 Docker/runtime changes
- [x] Add `MONITOR_PORT` env var
- [x] Ensure Monitor listens on `127.0.0.1:<MONITOR_PORT>`
- [x] Update Docker runtime docs/examples
- [x] Update docker-compose to expose that port to host `127.0.0.1`
### 5.2 Plugin communication
- [x] Implement local communication client to query plugin over `MONITOR_PORT`
- Note: the architecture is reversed — Monitor hosts the bridge, plugin pushes via POST /openclaw
- [x] Define request timeout / retry / fallback policy
- Plugin uses 3s timeout; Monitor bridge uses 5s read/write timeouts
- [x] Keep startup independent of plugin communication success
- [x] Keep heartbeat/telemetry upload independent of plugin communication success
- [x] If plugin is reachable, enrich telemetry with:
- [x] OpenClaw version
- [x] plugin version
- [x] agent info
- [x] If plugin is unreachable, continue current behavior unchanged
### 5.3 Telemetry model alignment
- [x] Ensure backend-facing telemetry payloads can carry optional OpenClaw metadata
- [x] Avoid making plugin-derived fields mandatory
- [x] Ensure monitor data model cleanly distinguishes:
- [x] host/hardware telemetry
- [x] optional OpenClaw metadata
### 5.4 Docs / examples
- [x] Update Monitor README to explain `MONITOR_PORT`
- [x] Explain degraded mode when plugin bridge is absent
- [x] 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
- [x] Finalize CLI help / mode / output model
- [x] Finalize backend permission introspection approach
- [x] Finalize plugin↔monitor local protocol
### Phase B — Backend first
- [x] Add/finish code-based backend support
- [x] Add/finish task take / meeting attend / support take
- [x] Add any missing account-manager creation behavior
### Phase C — CLI MVP
- [x] Build `hf` scaffold
- [x] Ship `version`, `health`, `config`
- [x] Ship `user create`, `user list`, `user get`
- [x] Ship `task list`, `task get`, `task take`
- [x] Ship initial `monitor` commands
### Phase D — Frontend alignment
- [x] Move frontend to code-first lookup/display
- [x] Surface canonical codes consistently in UI
### Phase E — Plugin / Monitor integration
- [x] Rename plugin to `harbor-forge`
- [x] Remove plugin sidecar
- [x] Add `--install-cli`
- [x] Add `skills/hf`
- [x] Add `monitor_port` / `MONITOR_PORT` bridge
### Phase F — Cleanup / retirement
- [x] Remove legacy backend Python CLI
- [x] Update all docs to point to `hf`
- [ ] Add final tests and packaging flow