Document plugin-specific flag applicability in help text

[ewega]

Problem

Several flags on configure connection and configure scope are plugin-specific, but this isn't documented anywhere in the CLI help text. Users don't know which flags apply to which plugin without trial and error or reading source code. This will get worse as more plugins are added (#13 GitLab, #14 Azure DevOps).

Connection flags with plugin-specific applicability

Flag	Applies to	Notes
--token	All plugins	Shared — but future plugins may use different auth (e.g., OAuth)
--org	GitHub (optional), Copilot (required unless enterprise provided)	Different semantics per plugin
--enterprise	Copilot only	Ignored by GitHub
--endpoint	All plugins	But default differs per plugin
--proxy	All plugins	Shared

Scope flags with plugin-specific applicability

Flag	Applies to	Notes
--repos	GitHub only	Not applicable to Copilot
--repos-file	GitHub only	Not applicable to Copilot
--deployment-pattern	GitHub only	DORA config
--production-pattern	GitHub only	DORA config
--incident-label	GitHub only	DORA config
--enterprise	Copilot only	Not applicable to GitHub
--org	Both	But different semantics

Current help output (scope example)

$ gh devlake configure scope add --help

Flags:
      --connection-id int         Connection ID (auto-detected if omitted)
      --deployment-pattern string Regex to match deployment workflows (default "(?i)deploy")
      --enterprise string         Enterprise slug (enables enterprise-level metrics)
      --incident-label string     Issue label for incidents (default "incident")
      --org string                Organization slug
      --plugin string             Plugin to configure (github, gh-copilot)
      --production-pattern string Regex to match production environment (default "(?i)prod")
      --repos string              Comma-separated repos (owner/repo)
      --repos-file string         Path to file with repos (one per line)

All flags are mixed together with no indication of which apply to which plugin.

Dependencies

Blocked by:

• configure connection add: Extract connection creation into add subcommand #54 (connection add) — Long text moves to add subcommand created there
• configure scope add/list/delete: Add CRUD subcommands for scope management #55 (scope CRUD) — Long text moves to add subcommand created there

Blocks:

• Dynamic plugin-specific flag validation and contextual help #59 (dynamic flag validation) — Option A text will be superseded by auto-generated text in Dynamic plugin-specific flag validation and contextual help #59

Parallel with: #57 (ScopeFunc) — independent changes, no file overlap

Proposed solution (Option A: help text annotations)

Update the Long description text on configure connection add and configure scope add to clearly document which flags apply to which plugin. This is a pure documentation improvement — no behavioral changes.

Scope add — updated Long text

Adds repository scopes and scope-configs to existing DevLake connections.

Shared flags (all plugins):
  --plugin             Plugin to configure (required in flag mode)
  --connection-id      Connection ID (required in flag mode)
  --org                Organization slug

GitHub-specific flags:
  --repos              Comma-separated repos (owner/repo)
  --repos-file         Path to file with repos (one per line)
  --deployment-pattern Regex to match deployment workflows
  --production-pattern Regex to match production environment
  --incident-label     Issue label for incidents

GitHub Copilot-specific flags:
  --enterprise         Enterprise slug (enables enterprise-level metrics)

Example (GitHub):
  gh devlake configure scope add --plugin github --connection-id 1 --org my-org --repos org/repo1,org/repo2

Example (Copilot):
  gh devlake configure scope add --plugin gh-copilot --connection-id 2 --org my-org --enterprise my-ent

Connection add — updated Long text

Creates a single DevLake plugin connection.

Shared flags (all plugins):
  --plugin             Plugin to configure
  --token              Personal access token
  --name               Connection display name
  --endpoint           API endpoint override
  --proxy              HTTP proxy URL

GitHub Copilot-specific flags:
  --enterprise         Enterprise slug
  --org                Organization slug (required unless enterprise provided)

Token resolution order:
  --token flag → .devlake.env → environment variable → masked prompt

Implementation

1. Update Long text in configure connection add (or current configureConnectionsCmd until configure connection add: Extract connection creation into add subcommand #54 ships)
2. Update Long text in configure scope add (or current scope command until configure scope add/list/delete: Add CRUD subcommands for scope management #55 ships)
3. Add per-plugin examples in the Long text to show typical flag combinations

This is lightweight and can be done alongside #54 and #55, or independently.

Acceptance criteria

• gh devlake configure connection add --help shows flags grouped by plugin applicability
• gh devlake configure scope add --help shows flags grouped by plugin applicability
• Each group has a clear header (e.g., "GitHub-specific flags:")
• Per-plugin examples are included
• No behavioral changes — flags still work the same way

Why not dynamic validation now?

Dynamic flag validation (warning when irrelevant flags are passed, contextual help after plugin selection) is tracked separately in #59 for v0.4.0. That approach requires metadata on ConnectionDef and runtime validation logic — more appropriate when 3+ plugins are active. This issue (Option A) is the quick win that improves UX immediately.

References

• cmd/configure_connections.go — connection command with Long text (moving to configure_connection_add.go per configure connection add: Extract connection creation into add subcommand #54)
• cmd/configure_scopes.go — scope command with Long text (moving to configure_scope_add.go per configure scope add/list/delete: Add CRUD subcommands for scope management #55)
• configure connection add: Extract connection creation into add subcommand #54 — configure connection add restructuring
• configure scope add/list/delete: Add CRUD subcommands for scope management #55 — configure scope add/list/delete restructuring
• Make scope dispatch tool-agnostic: Add ScopeFunc to ConnectionDef #57 — tool-agnostic scope dispatch (complementary)
• Dynamic plugin-specific flag validation and contextual help #59 — dynamic flag validation (supersedes this issue's help text with auto-generated text)