QRun-IO/qctl
3
0 Fork 0
Code Issues 45 Pull Requests 7 Actions Packages Projects Releases 4 Wiki Activity

Add organization/team management #61

New Issue
Open
opened 2026-01-03 23:47:17 +00:00 by KofTwentyTwo · 0 comments
KofTwentyTwo commented 2026-01-03 23:47:17 +00:00 (Migrated from github.com)
Copy link
Copy source

User Story

As an organization administrator, I want to manage teams and members so that I can organize access and collaboration across the organization.

Design

Command Interface

# Organization commands
qctl org show
qctl org settings
qctl org usage

# Team management
qctl team list
qctl team create platform-eng --description "Platform Engineering"
qctl team show platform-eng
qctl team delete platform-eng

# Member management
qctl team member list platform-eng
qctl team member add platform-eng james.maes@acme.com
qctl team member remove platform-eng james.maes@acme.com
qctl team member invite platform-eng alice@external.com --role developer

# App ownership
qctl team app assign platform-eng orders-api
qctl team app unassign platform-eng orders-api
qctl team app list platform-eng

Organization Hierarchy

┌─────────────────────────────────────────────────────────────────┐
│                    Organization Structure                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Organization: ACME Corp                                        │
│  ├── Owners (1)                                                 │
│  │   └── cto@acme.com                                           │
│  │                                                              │
│  ├── Teams                                                      │
│  │   ├── Platform Engineering                                   │
│  │   │   ├── Members: james.maes, alice.smith, bob.jones        │
│  │   │   └── Apps: orders-api, inventory-api, gateway           │
│  │   │                                                          │
│  │   ├── Frontend Team                                          │
│  │   │   ├── Members: carol.white, dan.brown                    │
│  │   │   └── Apps: web-app, mobile-bff                          │
│  │   │                                                          │
│  │   └── Data Team                                              │
│  │       ├── Members: eve.green                                 │
│  │       └── Apps: etl-pipeline, analytics-api                  │
│  │                                                              │
│  └── Service Accounts                                           │
│      ├── ci-pipeline (CI/CD)                                    │
│      └── monitoring (Observability)                             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Output Format

$ qctl org show
Organization: ACME Corp
ID: org_abc123
Plan: Enterprise
Created: 2025-06-15

Usage:
  Teams: 3 / unlimited
  Members: 8 / unlimited
  Apps: 7 / unlimited
  Deployments (month): 156 / unlimited

Owners:
  cto@acme.com

$ qctl team list
NAME              MEMBERS  APPS  DESCRIPTION
platform-eng      3        3     Platform Engineering
frontend          2        2     Frontend Development
data              1        2     Data & Analytics

$ qctl team show platform-eng
Team: Platform Engineering
ID: team_xyz789
Created: 2025-07-01
Created by: james.maes@acme.com

Members (3):
  NAME           EMAIL                  ROLE        JOINED
  James Maes     james.maes@acme.com    admin       2025-07-01
  Alice Smith    alice.smith@acme.com   developer   2025-07-15
  Bob Jones      bob.jones@acme.com     developer   2025-08-01

Apps (3):
  NAME           ENVIRONMENTS
  orders-api     dev, staging, prod
  inventory-api  dev, staging, prod
  gateway        dev, staging, prod

$ qctl team member invite platform-eng alice@external.com --role developer
Invitation sent to alice@external.com
Role: developer
Expires: 2026-01-10 (7 days)

Pending invitations:
  alice@external.com - developer - expires 2026-01-10

Invitation Flow

┌──────────────────────────────────────────────────────────────┐
│                    Member Invitation Flow                    │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  1. Admin invites user                                       │
│     qctl team member invite team alice@external.com          │
│              │                                               │
│              ▼                                               │
│  2. Voyage sends invitation email                            │
│     [Accept Invitation] button with unique token             │
│              │                                               │
│              ▼                                               │
│  3. User clicks link, creates account or links SSO           │
│              │                                               │
│              ▼                                               │
│  4. User added to team with specified role                   │
│     Audit event recorded                                     │
│                                                              │
└──────────────────────────────────────────────────────────────┘

API Integration

GET /v1/org
GET /v1/org/usage
PUT /v1/org/settings

GET /v1/teams
POST /v1/teams
GET /v1/teams/{teamId}
DELETE /v1/teams/{teamId}

GET /v1/teams/{teamId}/members
POST /v1/teams/{teamId}/members
DELETE /v1/teams/{teamId}/members/{userId}
POST /v1/teams/{teamId}/invitations

GET /v1/teams/{teamId}/apps
POST /v1/teams/{teamId}/apps
DELETE /v1/teams/{teamId}/apps/{appId}

Files to Create/Modify

File Action Description
qctl-core/src/main/java/io/qrun/qctl/core/org/OrgCommand.java Create Organization commands
qctl-core/src/main/java/io/qrun/qctl/core/org/ShowCommand.java Create Show org details
qctl-core/src/main/java/io/qrun/qctl/core/org/UsageCommand.java Create Show org usage
qctl-core/src/main/java/io/qrun/qctl/core/team/TeamCommand.java Create Team command group
qctl-core/src/main/java/io/qrun/qctl/core/team/ListCommand.java Create List teams
qctl-core/src/main/java/io/qrun/qctl/core/team/CreateCommand.java Create Create team
qctl-core/src/main/java/io/qrun/qctl/core/team/ShowCommand.java Create Show team details
qctl-core/src/main/java/io/qrun/qctl/core/team/MemberCommand.java Create Member management
qctl-core/src/main/java/io/qrun/qctl/core/team/AppCommand.java Create App assignment
qctl-core/src/main/java/io/qrun/qctl/core/team/InviteCommand.java Create Member invitation
qctl-core/src/main/java/io/qrun/qctl/core/model/Organization.java Create Organization model
qctl-core/src/main/java/io/qrun/qctl/core/model/Team.java Create Team model
qctl-core/src/main/java/io/qrun/qctl/core/model/Member.java Create Member model
qctl-core/src/main/java/io/qrun/qctl/core/model/Invitation.java Create Invitation model

Implementation Tasks

  • Create OrgCommand with show/settings/usage subcommands
  • Create TeamCommand group
  • Implement team CRUD operations
  • Implement member list/add/remove
  • Add member invitation with email
  • Implement app assignment to teams
  • Add team usage statistics
  • Show pending invitations
  • Add invitation expiry handling
  • Implement team deletion with safety checks
  • Add confirmation prompts for destructive operations
  • Write unit tests for team operations

Acceptance Criteria

  • Can view organization details and usage
  • Can create and delete teams
  • Can add and remove team members
  • Can invite external users via email
  • Can assign apps to teams
  • Team members inherit team-scoped permissions
  • Deleting a team requires confirmation
  • Pending invitations are visible
  • Usage metrics show current vs limits
## User Story As an organization administrator, I want to manage teams and members so that I can organize access and collaboration across the organization. ## Design ### Command Interface ```bash # Organization commands qctl org show qctl org settings qctl org usage # Team management qctl team list qctl team create platform-eng --description "Platform Engineering" qctl team show platform-eng qctl team delete platform-eng # Member management qctl team member list platform-eng qctl team member add platform-eng james.maes@acme.com qctl team member remove platform-eng james.maes@acme.com qctl team member invite platform-eng alice@external.com --role developer # App ownership qctl team app assign platform-eng orders-api qctl team app unassign platform-eng orders-api qctl team app list platform-eng ``` ### Organization Hierarchy ``` ┌─────────────────────────────────────────────────────────────────┐ │ Organization Structure │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Organization: ACME Corp │ │ ├── Owners (1) │ │ │ └── cto@acme.com │ │ │ │ │ ├── Teams │ │ │ ├── Platform Engineering │ │ │ │ ├── Members: james.maes, alice.smith, bob.jones │ │ │ │ └── Apps: orders-api, inventory-api, gateway │ │ │ │ │ │ │ ├── Frontend Team │ │ │ │ ├── Members: carol.white, dan.brown │ │ │ │ └── Apps: web-app, mobile-bff │ │ │ │ │ │ │ └── Data Team │ │ │ ├── Members: eve.green │ │ │ └── Apps: etl-pipeline, analytics-api │ │ │ │ │ └── Service Accounts │ │ ├── ci-pipeline (CI/CD) │ │ └── monitoring (Observability) │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Output Format ``` $ qctl org show Organization: ACME Corp ID: org_abc123 Plan: Enterprise Created: 2025-06-15 Usage: Teams: 3 / unlimited Members: 8 / unlimited Apps: 7 / unlimited Deployments (month): 156 / unlimited Owners: cto@acme.com $ qctl team list NAME MEMBERS APPS DESCRIPTION platform-eng 3 3 Platform Engineering frontend 2 2 Frontend Development data 1 2 Data & Analytics $ qctl team show platform-eng Team: Platform Engineering ID: team_xyz789 Created: 2025-07-01 Created by: james.maes@acme.com Members (3): NAME EMAIL ROLE JOINED James Maes james.maes@acme.com admin 2025-07-01 Alice Smith alice.smith@acme.com developer 2025-07-15 Bob Jones bob.jones@acme.com developer 2025-08-01 Apps (3): NAME ENVIRONMENTS orders-api dev, staging, prod inventory-api dev, staging, prod gateway dev, staging, prod $ qctl team member invite platform-eng alice@external.com --role developer Invitation sent to alice@external.com Role: developer Expires: 2026-01-10 (7 days) Pending invitations: alice@external.com - developer - expires 2026-01-10 ``` ### Invitation Flow ``` ┌──────────────────────────────────────────────────────────────┐ │ Member Invitation Flow │ ├──────────────────────────────────────────────────────────────┤ │ │ │ 1. Admin invites user │ │ qctl team member invite team alice@external.com │ │ │ │ │ ▼ │ │ 2. Voyage sends invitation email │ │ [Accept Invitation] button with unique token │ │ │ │ │ ▼ │ │ 3. User clicks link, creates account or links SSO │ │ │ │ │ ▼ │ │ 4. User added to team with specified role │ │ Audit event recorded │ │ │ └──────────────────────────────────────────────────────────────┘ ``` ### API Integration ``` GET /v1/org GET /v1/org/usage PUT /v1/org/settings GET /v1/teams POST /v1/teams GET /v1/teams/{teamId} DELETE /v1/teams/{teamId} GET /v1/teams/{teamId}/members POST /v1/teams/{teamId}/members DELETE /v1/teams/{teamId}/members/{userId} POST /v1/teams/{teamId}/invitations GET /v1/teams/{teamId}/apps POST /v1/teams/{teamId}/apps DELETE /v1/teams/{teamId}/apps/{appId} ``` ## Files to Create/Modify | File | Action | Description | |------|--------|-------------| | `qctl-core/src/main/java/io/qrun/qctl/core/org/OrgCommand.java` | Create | Organization commands | | `qctl-core/src/main/java/io/qrun/qctl/core/org/ShowCommand.java` | Create | Show org details | | `qctl-core/src/main/java/io/qrun/qctl/core/org/UsageCommand.java` | Create | Show org usage | | `qctl-core/src/main/java/io/qrun/qctl/core/team/TeamCommand.java` | Create | Team command group | | `qctl-core/src/main/java/io/qrun/qctl/core/team/ListCommand.java` | Create | List teams | | `qctl-core/src/main/java/io/qrun/qctl/core/team/CreateCommand.java` | Create | Create team | | `qctl-core/src/main/java/io/qrun/qctl/core/team/ShowCommand.java` | Create | Show team details | | `qctl-core/src/main/java/io/qrun/qctl/core/team/MemberCommand.java` | Create | Member management | | `qctl-core/src/main/java/io/qrun/qctl/core/team/AppCommand.java` | Create | App assignment | | `qctl-core/src/main/java/io/qrun/qctl/core/team/InviteCommand.java` | Create | Member invitation | | `qctl-core/src/main/java/io/qrun/qctl/core/model/Organization.java` | Create | Organization model | | `qctl-core/src/main/java/io/qrun/qctl/core/model/Team.java` | Create | Team model | | `qctl-core/src/main/java/io/qrun/qctl/core/model/Member.java` | Create | Member model | | `qctl-core/src/main/java/io/qrun/qctl/core/model/Invitation.java` | Create | Invitation model | ## Implementation Tasks - [ ] Create OrgCommand with show/settings/usage subcommands - [ ] Create TeamCommand group - [ ] Implement team CRUD operations - [ ] Implement member list/add/remove - [ ] Add member invitation with email - [ ] Implement app assignment to teams - [ ] Add team usage statistics - [ ] Show pending invitations - [ ] Add invitation expiry handling - [ ] Implement team deletion with safety checks - [ ] Add confirmation prompts for destructive operations - [ ] Write unit tests for team operations ## Acceptance Criteria - [ ] Can view organization details and usage - [ ] Can create and delete teams - [ ] Can add and remove team members - [ ] Can invite external users via email - [ ] Can assign apps to teams - [ ] Team members inherit team-scoped permissions - [ ] Deleting a team requires confirmation - [ ] Pending invitations are visible - [ ] Usage metrics show current vs limits
Sign in to join this conversation.
No Branch/Tag Specified
Labels
Clear labels
Feature
bug
Something isn't working
 dependencies
documentation
Improvements or additions to documentation
 duplicate
This issue or pull request already exists
 enhancement
New feature or request
 enterprise
Enterprise feature
 epic
Epic-level tracking issue
 good first issue
Good for newcomers
 help wanted
Extra attention is needed
 in-progress
invalid
This doesn't seem right
 module:core
Core infrastructure
 module:qbit
Package management module
 module:qqq
Template scaffolding module
 module:qrun
Build/deploy module
 module:qstudio
AI planning module
 question
Further information is requested
 secuurity
story
Feature story linked to epic
 wontfix
This will not be worked on
No labels enterprise story
Milestone
No items
No Milestone v1.0.0 - Production Ready
Projects
Clear projects
No projects
Assignees
Clear assignees
forge-recovery (Forge Recovery) james.maes (James Maes)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: QRun-IO/qctl#61