aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
feat(cli): bgagent linear remove-workspace command
- Dominant language
- TypeScript
- Stars
- 143
- Forks
- 46
- Avg merge
- 3d 9h
- Merged PRs (30d)
- 20
Description
## Summary
Add a `bgagent linear remove-workspace ` CLI command that lets a Linear-workspace admin deregister a workspace previously onboarded via `bgagent linear setup` or `bgagent linear add-workspace`. Surfaced during PR #160 review (krokoko) — tracked as a follow-up that never landed.
Today, removing a workspace requires manual surgery across DDB and Secrets Manager, which is error-prone and undocumented.
## Motivation
Workspace onboarding is a one-line CLI command. Workspace removal isn't — operators have to:
1. Find the row in `LinearWorkspaceRegistryTable` and either delete it or flip `status` to `revoked`
2. Delete the per-workspace OAuth secret in Secrets Manager (`bgagent-linear-oauth-`)
3. (Optional) Clean up `LinearProjectMappingTable` rows for that workspace
Without the command, a workspace removal can leave dangling secrets, stale registry rows that the resolver still reads, or orphan project mappings that confuse operators.
## Proposed UX
```
$ bgagent linear remove-workspace acme
Found workspace 'acme' (Linear workspace ID: ws-uuid-1234, status=active)
This will:
• Mark the registry row as status=revoked (preserves audit trail)
• Delete the Secrets Manager secret 'bgagent-linear-oauth-acme'
• Delete 4 project mappings for this workspace
Type the workspace slug to confirm: acme
✔ Registry row revoked
✔ Secret deleted
✔ 4 project mappings removed
Done.
```
Flags:
- `--purge` — also delete the registry row entirely (default: keep with `status=revoked` for audit)
- `--keep-mappings` — leave `LinearProjectMappingTable` rows alone
- `--yes` — skip the slug-confirmation prompt (for scripted use)
## Acceptance criteria
- [ ] New CLI command `bgagent linear remove-workspace ` registered under `cli/src/commands/linear/`
- [ ] Calls a new authenticated REST endpoint (`DELETE /v1/linear/workspaces/{slug}`) — keeps DDB / Secrets Manager grants on the API role, not on every CLI user
- [ ] New Lambda handler under `cdk/src/handlers/linear/` that:
- Verifies the caller is the workspace admin (matches the user who ran `setup` for that slug — same auth pattern as existing OAuth admin commands)
- Updates `LinearWorkspaceRegistryTable` row to `status='revoked'` (or deletes it with `--purge`)
- Deletes the corresponding `bgagent-linear-oauth-` secret from Secrets Manager
- Optionally deletes `LinearProjectMappingTable` rows where `workspace_slug = `
- [ ] Resolver code (`linear-oauth-resolver.ts` + Python equivalent) treats `status='revoked'` as fail-closed (already does — re-verify under test)
- [ ] Tests: jest for the handler (happy path, not-found, not-admin, secret-already-gone, mappings-empty); CLI command jest test (flags, prompts, error surfaces)
- [ ] Doc: short section in `docs/guides/LINEAR_SETUP_GUIDE.md` under "Removing a workspace"
## Out of scope
- Re-onboarding a previously-revoked workspace (separate issue if needed; today operators can just `bgagent linear add-workspace` again)
- UI in any web console — CLI only
## References
- Original surface in PR #160 review (krokoko, "or task only")
- Phase 2.0b shipped via PR #160 (merged 2026-05-26)
- Related: registry table schema in `cdk/src/constructs/linear-integration.ts`, OAuth secret naming convention in `cdk/src/handlers/shared/linear-oauth-resolver.ts`
## Estimate
~1–2 hours: handler + CLI command + tests + doc snippet. No infra changes (existing tables and secret prefix are reused).
Contributor guide
Assessment
This issue has not been assessed yet.