diff --git a/.github/agents/go-developer.agent.md b/.github/agents/go-developer.agent.md new file mode 100644 index 0000000..c43bc84 --- /dev/null +++ b/.github/agents/go-developer.agent.md @@ -0,0 +1,36 @@ +--- +name: go-developer +description: General-purpose Go developer for gh-devlake — implements features, fixes bugs, writes tests, and follows project conventions. +--- + +# Go Developer Agent + +You are a Go developer working on `gh-devlake`, a GitHub CLI extension built with Go + Cobra. + +## Architecture Awareness + +- **Command layer** (`cmd/`): Cobra commands. Constructors are `newXxxCmd()`, run functions are `runXxx`. +- **Internal packages** (`internal/`): `devlake/` (API client), `azure/` (CLI + Bicep), `docker/` (CLI wrapper), `prompt/` (interactive input), `token/` (PAT resolution), `gh/` (GitHub CLI wrapper). +- **Plugin registry**: `cmd/connection_types.go` — add `ConnectionDef` entries to support new DevOps tools. +- **Generic API helpers**: `doPost[T]`, `doGet[T]`, `doPut[T]`, `doPatch[T]` in `internal/devlake/client.go`. +- **State files**: `.devlake-azure.json` / `.devlake-local.json` — persisted deployment info. +- **Discovery chain**: `--url` flag → state file → well-known ports. + +## Cross-Repo Context + +Use MCP tools to read related repositories when needed: + +- `apache/incubator-devlake` — official upstream. Backend Go plugin framework, REST API routes, domain models. +- `DevExpGBB/incubator-devlake` — fork with unreleased plugins (e.g., `gh-copilot`). Check `backend/plugins/gh-copilot/` for implementation patterns. +- `eldrick-test-org/devlake-demo` — demo stack with docker-compose, API payload examples, simulation scripts. + +## Validation Checklist + +Before marking work complete: + +1. `go build ./...` — must compile +2. `go test ./...` — all tests pass +3. `go vet ./...` — no issues +4. New models/types follow existing naming patterns +5. Terminal output in `cmd/` follows `.github/instructions/terminal-output.instructions.md` +6. Errors are wrapped with context: `fmt.Errorf("context: %w", err)` diff --git a/.github/agents/prettify.agent.md b/.github/agents/prettify.agent.md new file mode 100644 index 0000000..94c69ad --- /dev/null +++ b/.github/agents/prettify.agent.md @@ -0,0 +1,50 @@ +--- +name: prettify +description: Terminal UX specialist — enforces output formatting rules, improves readability, and ensures consistent visual rhythm across all CLI commands. +--- + +# Prettify Agent + +You are a terminal UX specialist for `gh-devlake`. Your job is to enforce and improve the visual quality of all CLI output. + +## Scope + +You may: + +- **Enforce** formatting rules from `.github/instructions/terminal-output.instructions.md` +- **Fix** spacing, indentation, emoji usage, and header consistency violations +- **Improve** output grouping, wording clarity, and progress indicators +- **Propose** restructured output flows for better end-to-end readability + +You must NOT change program logic, API calls, or data flow — only `fmt.Print*` statements and string constants. + +## Rules Reference + +All terminal output rules live in `.github/instructions/terminal-output.instructions.md`. Key rules: + +1. Blank line (`\n`) before every emoji-prefixed step +2. Blank line before AND after separators (`───`, `═══`, phase banners) +3. Blank line after completion banners +4. Sub-items (3-space indent) stay tight under their parent — no blank lines between them +5. Phase banners get blank lines on both sides +6. Blank line before interactive prompts + +## Established Patterns + +Study these files for the current output style: + +- `cmd/configure_full.go` — top-level banners, phase banners, full end-to-end flow +- `cmd/configure_connections.go` — emoji steps with sub-items +- `cmd/cleanup.go` — completion banners, cleanup flow +- `cmd/deploy_azure.go` — long multi-phase deployment output +- `cmd/status.go` — compact status display + +## Review Criteria + +When reviewing or modifying output: + +1. Walk the full terminal scroll mentally — does it read as a clear story? +2. Are steps visually distinct with breathing room? +3. Is emoji usage consistent with the table in `AGENTS.md`? +4. Do headers use Unicode `═` at 40 characters width? +5. Are sub-items grouped tight under their parent step? diff --git a/.github/skills/devlake-api-patterns/SKILL.md b/.github/skills/devlake-api-patterns/SKILL.md new file mode 100644 index 0000000..90b2b3f --- /dev/null +++ b/.github/skills/devlake-api-patterns/SKILL.md @@ -0,0 +1,62 @@ +--- +name: devlake-api-patterns +description: DevLake REST API integration patterns — typed generic helpers, endpoint conventions, and cross-repo API references. Use when implementing or modifying DevLake API calls. +--- + +# DevLake API Patterns + +## Generic Typed Helpers + +All API calls use generic helpers in `internal/devlake/client.go`: + +| Helper | HTTP Method | Success Codes | +|--------|------------|---------------| +| `doPost[T]` | POST | 200, 201 | +| `doGet[T]` | GET | 200 | +| `doPut[T]` | PUT | 200, 201 | +| `doPatch[T]` | PATCH | 200 | + +Usage pattern: + +```go +result, err := doPost[Connection](c, "/plugins/github/connections", req) +``` + +All helpers: marshal request → send → check status → unmarshal response into `*T`. + +## API Endpoint Patterns + +DevLake REST API follows consistent URL patterns: + +| Operation | Pattern | Example | +|-----------|---------|---------| +| List connections | `GET /plugins/{plugin}/connections` | `/plugins/github/connections` | +| Create connection | `POST /plugins/{plugin}/connections` | `/plugins/gh-copilot/connections` | +| Test connection | `POST /plugins/{plugin}/test` | `/plugins/github/test` | +| Test saved connection | `POST /plugins/{plugin}/connections/{id}/test` | `/plugins/github/connections/1/test` | +| Scope configs | `GET/POST /plugins/{plugin}/connections/{id}/scope-configs` | | +| Upsert scopes | `PUT /plugins/{plugin}/connections/{id}/scopes` | | +| Projects | `GET/POST /projects` | `/projects/MyProject` | +| Blueprints | `PATCH /blueprints/{id}`, `POST /blueprints/{id}/trigger` | | +| Pipelines | `GET /pipelines/{id}` | | +| Health | `GET /ping` | | + +## Cross-Repo References + +For deeper API understanding, read these from related repos using MCP tools: + +### apache/incubator-devlake (official upstream) + +- `backend/server/api/` — route registration and handler definitions +- `backend/core/plugin/` — plugin interfaces (`PluginSource`, `PluginTask`, etc.) +- `backend/plugins/github/api/` — reference implementation for connection/scope endpoints + +### DevExpGBB/incubator-devlake (fork) + +- `backend/plugins/gh-copilot/` — custom Copilot plugin with `listGhCopilotRemoteScopes` +- Check for unreleased API changes not yet in upstream + +### eldrick-test-org/devlake-demo + +- `scripts/` — PowerShell examples of API calls via `Invoke-RestMethod` +- `README.md` — API payload examples for connections, scopes, blueprints diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml new file mode 100644 index 0000000..7fc8dbd --- /dev/null +++ b/.github/workflows/copilot-setup-steps.yml @@ -0,0 +1,30 @@ +# Setup steps for the GitHub Copilot Coding Agent. +# This workflow installs Go, downloads dependencies, and validates +# that the project compiles and passes tests — giving the agent a +# working environment identical to local development. + +name: Copilot Setup Steps + +on: + workflow_dispatch: + +permissions: + contents: read + +jobs: + # The job MUST be called copilot-setup-steps or it will not be picked up by Copilot. + copilot-setup-steps: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + + - uses: actions/setup-go@v5 + with: + go-version: '1.22' + cache: true + + - run: go mod download + + - run: go build ./... + + - run: go test ./... -short diff --git a/AGENTS.md b/AGENTS.md index 5bfbf03..6942afa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,106 +40,11 @@ The `gh-copilot` plugin computes scope IDs as: enterprise + org → `"enterprise ## Roadmap See `.github/skills/gh-devlake-roadmap/SKILL.md` for version plan, milestones, and design decisions. Project board: https://github.com/orgs/DevExpGbb/projects/21 -## Terminal Output & UX — CRITICAL +## Terminal Output & UX -**The terminal IS the UI.** Every `fmt.Print` call is a UX decision. Readability, rhythm, and breathing room are non-negotiable. +**The terminal IS the UI.** See `.github/instructions/terminal-output.instructions.md` for the full formatting rules (auto-applied to `cmd/**/*.go`). -### Line Spacing Rules - -These rules are mandatory for all terminal output in `cmd/` files. - -**Rule 1: Blank line before every step.** -Every step (emoji + action text) MUST be preceded by `\n`: -```go -// ✅ CORRECT — blank line before step -fmt.Println("\n🔍 Discovering DevLake instance...") - -// ❌ WRONG — no breathing room, steps run together -fmt.Println("🔍 Discovering DevLake instance...") -``` - -**Rule 2: Blank line before AND after section separators.** -Separator lines (`───`, `═══`, phase banners) must have blank lines on both sides: -```go -// ✅ CORRECT -fmt.Println("\n" + strings.Repeat("─", 50)) -fmt.Println("✅ Connection configured!") -fmt.Println(strings.Repeat("─", 50)) -fmt.Println() - -// ❌ WRONG — separator jammed against previous/next output -fmt.Println(strings.Repeat("─", 50)) -fmt.Println("✅ Connection configured!") -fmt.Println(strings.Repeat("─", 50)) -``` - -**Rule 3: Blank line after completion banners.** -After a success/summary block, always add a trailing blank line: -```go -fmt.Println("═══════════════════════════════════════") -fmt.Println(" ✅ Setup Complete!") -fmt.Println("═══════════════════════════════════════") -fmt.Println() // ← always trail with blank line -``` - -**Rule 4: Sub-items stay tight under their parent.** -Detail lines (3-space indent) do NOT get blank lines between them: -```go -// ✅ CORRECT — grouped tight under parent step -fmt.Println("\n📡 Creating GitHub connection...") -fmt.Printf(" Endpoint: %s\n", endpoint) -fmt.Printf(" Token: %s\n", masked) -fmt.Printf(" ✅ Created (ID=%d)\n", conn.ID) - -// ❌ WRONG — unnecessary blank lines break grouping -fmt.Println("\n📡 Creating GitHub connection...") -fmt.Println() -fmt.Printf(" Endpoint: %s\n", endpoint) -``` - -**Rule 5: Phase banners get a blank line before and after.** -```go -fmt.Println() // or use \n prefix on next line - -fmt.Println("╔══════════════════════════════════════╗") -fmt.Println("║ PHASE 1: Configure Connections ║") -fmt.Println("╚══════════════════════════════════════╝") - -fmt.Println() // blank line after banner before first step -``` - -### Header Standards - -All headers use Unicode double-line `═` at **40 characters** width: - -**Top-level command banner:** -```go -fmt.Println("\n════════════════════════════════════════") -fmt.Println(" DevLake — Command Title") -fmt.Println("════════════════════════════════════════") -``` - -**Phase banner (box-drawing):** -```go -fmt.Println("\n╔══════════════════════════════════════╗") -fmt.Println("║ PHASE N: Description ║") -fmt.Println("╚══════════════════════════════════════╝") -``` - -**Section separator (thin line):** -```go -fmt.Println("\n" + strings.Repeat("─", 50)) -``` - -**Completion banner:** -```go -fmt.Println("\n════════════════════════════════════════") -fmt.Println(" ✅ Action Complete!") -fmt.Println("════════════════════════════════════════") -fmt.Println() -``` - -### Emoji Usage +Quick reference — standard emoji vocabulary: | Emoji | Meaning | Example | |-------|---------|---------| @@ -158,27 +63,15 @@ fmt.Println() | 💾 | Save / persist | `State saved to ...` | | 🧹 | Cleanup | `Cleaning up resources...` | -### Indentation - -- **Steps**: No indent — start at column 0 with emoji -- **Sub-items under a step**: 3-space indent (`" "`) -- **Content inside banners**: 2-space indent (`" "`) -- **Bullet lists**: 2-space indent + `•` (`" • item"`) -- **Numbered steps**: 2-space indent + number (`" 1. step"`) - -### UX Principles - -1. **Think end-to-end.** Before adding output, mentally walk through the entire command flow. Does the full terminal scroll look clean? Are steps visually distinct? Can a user scan from top to bottom and understand what happened? - -2. **Breathing room over density.** When in doubt, add a blank line. Cramped output is harder to scan than output with generous spacing. - -3. **Group related output, separate unrelated steps.** Sub-items under a step stay tight; different steps get blank lines between them. - -4. **Every command tells a story.** The output should read as: banner → steps with progress → summary. The user should never wonder "is it still running?" or "did that work?" +## Related Repositories -5. **Consistency is UX.** If one command uses `═══` headers and another uses `===`, it feels broken even if it works. Match the established patterns exactly. +These repos provide essential context. Use MCP tools (`mcp_github_get_file_contents`, `mcp_github_search_code`) to read them. -6. **Prompts go to stderr, output to stdout.** Keep stdout clean for piping. All `prompt.*` functions write to `os.Stderr`. +| Repository | Purpose | +|------------|---------| +| `apache/incubator-devlake` | Official upstream — backend Go code, plugin framework, domain models, REST API routes | +| `DevExpGBB/incubator-devlake` | Fork with unreleased custom plugins (gh-copilot). Rolls up to apache upstream | +| `eldrick-test-org/devlake-demo` | Demo stack — docker-compose, simulation scripts, API payload examples | ## Code Conventions