aws-samples / aws-samples/sample-autonomous-cloud-coding-agents

feat(cli): bgagent linear remove-workspace command

Open
#306 3 comments 0 reactions 1 assignee Claimed by @scottschreckengaust View on GitHub
adapters approved enhancement good first issue
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.