#679 - WIZ-8 Apply transaction + Done screen — atomic apply, master-key backup nag - charles/claude-hooks

claude-desktop commented

2026-05-01 19:27:53 +00:00

Collaborator

Copy link

User story

As an operator, I want a single POST /onboarding/apply that atomically configures every wizard choice (agents, secrets, plugin/mcp overrides, renames, webhooks) — and a Done screen that nags me to back up the master key — so a failure doesn't leave me half-configured.

Acceptance criteria

Apply endpoint

POST /onboarding/apply body { ...full setup row contents }. Operator-auth-gated.
One DB transaction:
1. Insert agents rows for every chosen type / pool size, keyed by role.
2. Insert secret rows for every PAT (encrypted via SC-6 helper).
3. Insert config_revision rows for every starter-pack choice (plugins, MCPs, system_prompt appendices).
4. Call WIZ-prereq-B rename endpoint inline for any type whose name diverged from default.
5. Install webhooks on every selected repo via ForgePort.createWebhook.
6. Mark setup.wizard_completed_at = Date.now().
Trigger agent-env-sync.renderForInstance for every new agent post-commit.
Returns 200 { ok: true, summary: { agents_created, secrets_added, repos_watched, webhooks_installed, plugins_enabled, mcps_enabled } }.
On any failure: roll back every step, return 500 with the error. The wizard's UI restores from setup row's mid-flow state and surfaces the error inline.
Webhook-install error policy: pick one (rollback all OR partial-land + report) and document in handler docstring.

Done screen

Summary bullets per the spec architecture section (forge, repos, agents, plugins).
Master-key backup nag: explicit copy + the on-disk path (~/.config/systemd/user/claude-hooks.service.d/secret-key.conf). [ ] I've backed up the key checkbox required to enable the Open dashboard → button.
Suggested next steps: open issue → assign dev / browse /agents/dev → check audit log.

Tests

Smoke: full wizard end-to-end — fixture forge + fixture repos + 4 agents + 2 PATs → DB state matches expectations + webhooks installed (mocked).
Failure: simulated webhook-install error rolls back the entire transaction; no half-installed state.
Done screen: backup-checkbox-required behavior verified.

Out of scope

Re-run wizard affordance (WIZ-9).

References

specs/first-login-wizard.md §Story WIZ-8
Depends on WIZ-1..WIZ-7.

## User story As an operator, I want a single `POST /onboarding/apply` that atomically configures every wizard choice (agents, secrets, plugin/mcp overrides, renames, webhooks) — and a Done screen that nags me to back up the master key — so a failure doesn't leave me half-configured. ## Acceptance criteria ### Apply endpoint - [ ] `POST /onboarding/apply` body `{ ...full setup row contents }`. Operator-auth-gated. - [ ] One DB transaction: 1. Insert `agents` rows for every chosen type / pool size, keyed by role. 2. Insert `secret` rows for every PAT (encrypted via SC-6 helper). 3. Insert `config_revision` rows for every starter-pack choice (plugins, MCPs, system_prompt appendices). 4. Call WIZ-prereq-B rename endpoint inline for any type whose name diverged from default. 5. Install webhooks on every selected repo via `ForgePort.createWebhook`. 6. Mark `setup.wizard_completed_at = Date.now()`. - [ ] Trigger `agent-env-sync.renderForInstance` for every new agent post-commit. - [ ] Returns 200 `{ ok: true, summary: { agents_created, secrets_added, repos_watched, webhooks_installed, plugins_enabled, mcps_enabled } }`. - [ ] On any failure: roll back every step, return 500 with the error. The wizard's UI restores from `setup` row's mid-flow state and surfaces the error inline. - [ ] Webhook-install error policy: pick one (rollback all OR partial-land + report) and document in handler docstring. ### Done screen - [ ] Summary bullets per the spec architecture section (forge, repos, agents, plugins). - [ ] Master-key backup nag: explicit copy + the on-disk path (`~/.config/systemd/user/claude-hooks.service.d/secret-key.conf`). `[ ] I've backed up the key` checkbox **required** to enable the `Open dashboard →` button. - [ ] Suggested next steps: open issue → assign dev / browse `/agents/dev` → check audit log. ### Tests - [ ] Smoke: full wizard end-to-end — fixture forge + fixture repos + 4 agents + 2 PATs → DB state matches expectations + webhooks installed (mocked). - [ ] Failure: simulated webhook-install error rolls back the entire transaction; no half-installed state. - [ ] Done screen: backup-checkbox-required behavior verified. ## Out of scope - Re-run wizard affordance (WIZ-9). ## References - `specs/first-login-wizard.md` §Story WIZ-8 - Depends on **WIZ-1**..**WIZ-7**.

claude-desktop added the

area:agents

type:user-story

labels

2026-05-01 19:28:16 +00:00

claude-desktop added this to the First-login wizard milestone

2026-05-01 19:28:25 +00:00