CLI Settings Reconfiguration
CLI Settings Reconfiguration
User input
then lets bring a new command,
hi ensureor smth that enables the selection of the initialscaffold initthat lets you input backlog, asset manager, repo manager of the .devpunks/settings.json. this command should reuse the same code path of that initial selector picker steps. therefore we should abstract that code and put it in both commands.this hi ensure essentially lets you reconfigure the settings.json without going a full run of scaffold init
we also have to add a new field in settings.json, the backlog project url. and make sure that write backlog always knows about such url.
Context
Repository operators need to change backlog, asset, and repository authorities after initial adoption without rerunning the full scaffold initializer. The configured backlog destination must also be explicit as backlogProjectUrl so backlog-writing agents target the intended project instead of rediscovering or guessing it.
Non-Goals
- Rerun scaffold setup, regenerate managed assets, or rewrite project documentation as a side effect of settings reconfiguration.
- Add provider-specific project creation or credential management.
- Reject legacy settings files solely because they predate the backlog project URL field.
- Bootstrap a repository that has no
.devpunks/settings.json; operators must runhi scaffold initfirst.
Acceptance Criteria
hi ensurelets an operator selectbacklogProvider,assetProviderSlug, andrepositoryManager, then enterbacklogProjectUrl. The URL is trimmed, must be an absolute HTTP(S) URL, and rejects empty, relative, or non-HTTP values.- One shared settings-selection path owns the three provider prompts and
backlogProjectUrl; bothhi scaffold initandhi ensureuse it, while init's wiki-framework prompt remains init-only. hi ensureupdates.devpunks/settings.jsonwithout running the broader scaffold initialization flow or changing unrelated project files.- Existing settings values are the prompt defaults; accepting every default is idempotent. A missing settings file exits with actionable guidance to run
hi scaffold init. - Reconfiguration preserves known non-provider fields and required tools not owned solely by the previous repository manager; it removes obsolete manager-only tools, adds the new manager's requirements, and de-duplicates the result.
- Existing settings without
backlogProjectUrlremain readable and can be upgraded throughhi ensure. - Init writes the selected
backlogProjectUrl; setup leaves it unchanged; update check is read-only; update apply preserves its exact trimmed value while refreshing managed settings fields. - Before any provider materialization, scaffolded
write-backlogguidance reads.devpunks/settings.jsonand treatsbacklogProviderplusbacklogProjectUrlas destination authority. If the URL is missing or invalid, it stops with actionablehi ensureguidance rather than discovering or guessing a destination. - The
write-backlogchange originates inwearedevpunks-skills, is synchronized into Harness and CLI baseline surfaces, and is present in a scaffolded consumer. - Root and command help,
docs/README.md,docs/runbooks/hi-cli-scaffolding.md, and routed wiki guidance explainhi ensure, its settings-only scope, and its distinction from tool-installinghi tools ensure.
Constraints
- Keep
.devpunks/settings.jsonbackward compatible for existing repositories. - Continue using
hiandhintas executable names while retaining the@punks/clipackage identity. - Shared skill changes originate in
wearedevpunks-skillsand are synchronized into Harness Intelligence. - Provider selection and URL validation must remain provider-neutral; provider-specific URL parsing is outside this capability.
Decision Log
| Decision | Rationale |
|---|---|
Use hi ensure | Matches the requested working name; documentation can disambiguate the existing nested hi tools ensure. |
| Require the URL only when writing through the selector | Preserves legacy settings readability while ensuring new or reconfigured settings have a destination. |
| Accept absolute HTTP(S) URLs | Supplies a useful project authority without inventing provider-specific URL formats. |