From c3a61b198fb5e894aa7341bc17ec85e736f1fecd Mon Sep 17 00:00:00 2001 From: zhi Date: Sat, 21 Mar 2026 12:01:48 +0000 Subject: [PATCH] docs: require code-first identifiers for hf and UI --- plans/harborforge-cli-go-plan.md | 76 +++++++++++++++++++++++++------- 1 file changed, 59 insertions(+), 17 deletions(-) diff --git a/plans/harborforge-cli-go-plan.md b/plans/harborforge-cli-go-plan.md index 208145d..6daa338 100644 --- a/plans/harborforge-cli-go-plan.md +++ b/plans/harborforge-cli-go-plan.md @@ -29,17 +29,61 @@ This CLI should work well in two environments: - Config location: **same directory as the CLI binary** - Secret integration: `pass_mgr` - Command style: grouped subcommands (`hf user ...`, `hf task ...`, `hf monitor ...`) -- Identifiers: prefer **codes/names** instead of internal numeric ids whenever possible +- Identifiers: use **codes/names** instead of internal numeric ids - `project-code` - `milestone-code` - `task-code` - `meeting-code` - `support-code` + - `propose-code` - `role-name` - `username` --- +## Resource Code Policy + +Resource codes are now the canonical user-facing identifiers. + +### Rules + +- all resource codes are assumed to be **unique** +- code format rules are assumed to be defined by the backend already +- the CLI must accept **codes only** for resource-oriented commands +- the CLI must **not** accept internal numeric ids for those resources +- CLI list responses must include the resource code for every code-bearing resource + +### Scope + +This applies to: +- `project-code` +- `milestone-code` +- `task-code` +- `meeting-code` +- `support-code` +- `propose-code` + +### Backend implication + +Most backend APIs currently still accept only ids. The backend roadmap should add first-class support for code-based lookup and mutation across these resources. + +Additionally: +- list APIs used by the CLI should always return the resource code in their payloads +- get/update/delete/action endpoints should support code-based addressing for CLI-targeted resources +- new CLI-targeted API surface should treat codes as canonical identifiers + +### Frontend implication + +The frontend should also migrate toward code-first lookup and display: +- prefer code-based routing / lookup over id-based lookup +- stop surfacing raw ids as primary identifiers in UI +- update resource detail/list pages to display codes consistently +- replace existing id-based displays with code-based displays wherever resources already have codes + +This is an intentional cross-project requirement and should be applied broadly, not only inside the CLI. + +--- + ## OpenClaw Plugin / Monitor Integration Requirements This CLI plan now also carries **cross-project integration constraints** for: @@ -529,27 +573,27 @@ hf user list [--token ] ### `hf user get` ```bash -hf user get [--token ] +hf user get [--token ] ``` ### `hf user update` ```bash -hf user update [--email ] [--full-name ] [--pass ] [--active ] [--token ] +hf user update [--email ] [--full-name ] [--pass ] [--active ] [--token ] ``` ### `hf user activate` ```bash -hf user activate [--token ] +hf user activate [--token ] ``` ### `hf user deactivate` ```bash -hf user deactivate [--token ] +hf user deactivate [--token ] ``` ### `hf user delete` ```bash -hf user delete [--token ] +hf user delete [--token ] ``` > `hf user worklogs` is not planned. @@ -849,11 +893,9 @@ hf propose list --project [--status ] [--order-by [--token ] +hf propose get [--token ] ``` -> If propose code does not exist yet in backend, the CLI may temporarily accept ids, but code-based lookup is the target direction. - ### `hf propose create` ```bash hf propose create --project --title --desc <desc> [--token <token>] @@ -861,22 +903,22 @@ hf propose create --project <project-code> --title <title> --desc <desc> [--toke ### `hf propose update` ```bash -hf propose update <propose-code|propose-id> [--title <title>] [--desc <desc>] [--token <token>] +hf propose update <propose-code> [--title <title>] [--desc <desc>] [--token <token>] ``` ### `hf propose accept` ```bash -hf propose accept <propose-code|propose-id> --milestone <milestone-code> [--token <token>] +hf propose accept <propose-code> --milestone <milestone-code> [--token <token>] ``` ### `hf propose reject` ```bash -hf propose reject <propose-code|propose-id> [--reason <reason>] [--token <token>] +hf propose reject <propose-code> [--reason <reason>] [--token <token>] ``` ### `hf propose reopen` ```bash -hf propose reopen <propose-code|propose-id> [--token <token>] +hf propose reopen <propose-code> [--token <token>] ``` --- @@ -895,7 +937,7 @@ hf monitor server list [--token <token>] ### `hf monitor server get` ```bash -hf monitor server get <server-identifier|server-id> [--token <token>] +hf monitor server get <identifier> [--token <token>] ``` ### `hf monitor server create` @@ -905,17 +947,17 @@ hf monitor server create --identifier <identifier> [--name <display-name>] [--to ### `hf monitor server delete` ```bash -hf monitor server delete <identifier|server-id> [--token <token>] +hf monitor server delete <identifier> [--token <token>] ``` ### `hf monitor api-key generate` ```bash -hf monitor api-key generate <identifier|server-id> [--token <token>] +hf monitor api-key generate <identifier> [--token <token>] ``` ### `hf monitor api-key revoke` ```bash -hf monitor api-key revoke <identifier|server-id> [--token <token>] +hf monitor api-key revoke <identifier> [--token <token>] ``` ---