From b8d53ce6ef7f3be9ffd070676d25dce95d0440a9 Mon Sep 17 00:00:00 2001 From: Abhishek Choudhary Date: Wed, 27 May 2026 11:08:13 +0800 Subject: [PATCH 1/3] docs: reconcile PRD, roadmap, and AGENTS with GA scope Bring the three top-level docs in line with the GA Readiness Handoff (issue #22) so they reflect management-plane stability rather than Phase 9 enterprise-feature work. AGENTS.md: - pkg/cmd/ tree now matches actual directories (drops auth, token, user, role, permission-policy, custom-plugin, portal, audit-log, route-template, service-registry, secret-provider). - pkg/api/ types_*.go list matches the files on disk (drops the fictional types_token.go, adds the rest). - Document Map adds skills.md, documentation-maintenance.md, ga-test-plan.md, ga-test-report.md, and user-guide/. - API7 EE vs APISIX section reframes "enterprise resources" as out-of-scope for GA and points at the deferred sections. - Commit-scope example drops the unimplemented "token" scope. PRD.md: - Goals section narrows to GA-supported runtime resources plus gateway-group; session login marked deferred. - Control-plane Tokens / Users & RBAC / Developer Portal / Custom Plugins / System sections collapsed into a single "deferred (post-GA)" note; Service Templates flagged as not supported in GA. - Phase 9 renamed to top-level "Deferred (Post-GA)" with an explicit note that these are not GA commitments. - Feature parity table replaces "Phase 9" labels with "Deferred (post-GA)". docs/roadmap.md: - Drop the stale "Phase 5 IN PROGRESS" header. - Replace the pre-completion PR breakdown with a phase-status table (Phases 1 through 8 marked complete) and a GA Readiness Handoff section that links #22 and the GA test plan/report. - Move Phase 9 content into a "Deferred (Post-GA)" table. Closes #28. --- AGENTS.md | 59 +++++++++++++----------- PRD.md | 72 ++++++++++++------------------ docs/roadmap.md | 116 +++++++++++++++++------------------------------- 3 files changed, 101 insertions(+), 146 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a45afba..1e9d5c7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,14 +14,19 @@ a7 is a Go CLI wrapping the API7 Enterprise Edition Admin API (control-plane + A | Document | Purpose | When to Read | |---|---|---| -| `AGENTS.md` (this file) | Entry point, development guide | Always — read first | -| `PRD.md` | Product requirements, command design, scope | Before adding features | -| `docs/roadmap.md` | Per-PR development plan with dependencies | Before starting any PR | +| `AGENTS.md` (this file) | Entry point, development guide | Always, read first | +| `PRD.md` | Product requirements, GA scope, command design | Before adding features | +| `docs/roadmap.md` | Phase status and deferred (post-GA) work | Before starting any PR | +| `docs/ga-test-plan.md` | GA validation checklist against a real API7 EE | Before / during GA verification | +| `docs/ga-test-report.md` | Recorded GA test runs and dispositions | When checking what has been validated | | `docs/api7ee-api-spec.md` | API7 EE Admin API reference | When implementing API client | | `docs/adr/001-tech-stack.md` | Architecture decisions, patterns | Before writing code | | `docs/golden-example.md` | Complete reference implementation | When adding new commands | | `docs/coding-standards.md` | Go style, naming conventions | Before writing code | | `docs/testing-strategy.md` | Test patterns and practices | Before writing tests | +| `docs/documentation-maintenance.md` | Rules for keeping docs in sync | When updating docs | +| `docs/skills.md` | AI agent skill taxonomy and SKILL.md format | When adding or editing `skills/` entries | +| `docs/user-guide/` | Per-resource user-facing guides | When changing user-visible behavior | ### Project Structure @@ -32,50 +37,50 @@ a7/ │ └── e2e.yml # E2E tests with real API7 EE ├── cmd/a7/main.go # Entry point ├── pkg/cmd/ # Command implementations -│ ├── root/root.go # Root command registration │ ├── factory.go # Factory DI container +│ ├── root/ # Root command registration │ ├── route/ # Published route commands │ ├── service/ # Published service commands │ ├── consumer/ # Consumer commands +│ ├── credential/ # Consumer credential commands │ ├── ssl/ # SSL certificate commands -│ ├── plugin/ # Plugin listing commands +│ ├── plugin/ # Plugin listing (read-only) +│ ├── plugin-metadata/ # Plugin metadata commands │ ├── global-rule/ # Global rule commands │ ├── stream-route/ # Stream route commands -│ ├── secret-provider/ # Secret provider commands -│ ├── plugin-metadata/ # Plugin metadata commands -│ ├── credential/ # Consumer credential commands -│ ├── route-template/ # Route template commands (EE) +│ ├── secret/ # Secret commands +│ ├── proto/ # Proto commands │ ├── gateway-group/ # Gateway group commands (EE) -│ ├── service-registry/ # Service registry commands (EE) -│ ├── token/ # Access token commands (EE) -│ ├── user/ # User management commands (EE) -│ ├── role/ # Role & RBAC commands (EE) -│ ├── permission-policy/ # Permission policy commands (EE) -│ ├── custom-plugin/ # Custom plugin commands (EE) -│ ├── portal/ # Developer portal commands (EE) -│ ├── audit-log/ # Audit log commands (EE) │ ├── context/ # Context/profile management -│ ├── auth/ # Auth login/logout commands │ ├── config/ # Declarative config commands +│ ├── debug/ # Debug logs and trace │ ├── completion/ # Shell completion +│ ├── update/ # Self-update command │ └── version/ # Version command ├── pkg/api/ # API7 EE API client │ ├── client.go # HTTP client (auth transport) │ ├── types.go # Generic response types │ ├── types_route.go # Route types │ ├── types_service.go # Service types -│ ├── types_upstream.go # Upstream types +│ ├── types_upstream.go # Upstream types (inline-only in API7 EE) │ ├── types_consumer.go # Consumer types +│ ├── types_consumer_group.go # Consumer group types (not exposed) +│ ├── types_credential.go # Credential types │ ├── types_ssl.go # SSL types +│ ├── types_plugin.go # Plugin types +│ ├── types_plugin_metadata.go # Plugin metadata types +│ ├── types_global_rule.go # Global rule types +│ ├── types_stream_route.go # Stream route types +│ ├── types_secret.go # Secret types +│ ├── types_proto.go # Proto types │ ├── types_gateway_group.go # Gateway group types (EE) -│ ├── types_token.go # Token types (EE) -│ └── ... # One types file per resource +│ └── types_config.go # Declarative config types ├── pkg/iostreams/ # I/O abstraction (TTY detection) ├── pkg/cmdutil/ # Shared command utilities -│ ├── errors.go # Error formatting -│ └── exporter.go # JSON/YAML export ├── pkg/tableprinter/ # Table output rendering ├── pkg/httpmock/ # HTTP mocking for tests +├── pkg/listutil/ # Shared list/paging helpers +├── pkg/selector/ # Label selector parsing ├── internal/config/ # Configuration/context management ├── internal/version/ # Build version info ├── internal/update/ # Self-update mechanism @@ -98,13 +103,13 @@ a7/ ### API7 EE vs APISIX Differences (Key) - API7 EE uses `/apisix/admin/services` for runtime services. Upstreams are modeled inline on services and routes. -- Gateway groups scope all operations. Many endpoints require `gateway_group_id` as a query parameter. +- Gateway groups scope all runtime operations. Many endpoints require `gateway_group_id` as a query parameter. - Auth tokens use `a7ee` prefix (access token). - PATCH endpoints use JSON Patch (RFC 6902) arrays, not merge-patch. -- Enterprise-specific resources: gateway groups, RBAC (users/roles/policies), developer portal, audit logs, custom plugins, service registries, tokens. +- GA scope covers management-plane CRUD plus gateway groups. Enterprise modules such as RBAC, developer portal, audit logs, custom plugins, service registries, and access-token management are out of scope for GA, see `PRD.md` "Deferred (Post-GA)" and `docs/roadmap.md`. ### Resources NOT Exposed in API7 EE -The following APISIX resources do **not** have REST API endpoints in API7 Enterprise Edition: +The following APISIX resources do **not** have REST API endpoints in API7 Enterprise Edition and a7 does not expose commands for them: - **Standalone Upstream** (`/apisix/admin/upstreams`): Returns "resource not found". Upstreams exist only inline within services and routes. - **Consumer Group** (`/apisix/admin/consumer_groups`): No endpoint exposed. - **Plugin Config** (`/apisix/admin/plugin_configs`): No endpoint exposed. @@ -146,7 +151,7 @@ make clean # Remove build artifacts (): Types: feat, fix, refactor, test, docs, chore -Scope: route, upstream, service, consumer, ssl, plugin, context, api, config, gateway-group, token, etc. +Scope: route, service, consumer, credential, ssl, plugin, plugin-metadata, global-rule, stream-route, secret, proto, gateway-group, context, config, debug, api, etc. Example: feat(gateway-group): add gateway-group list command with table output ``` diff --git a/PRD.md b/PRD.md index a99b594..d349765 100644 --- a/PRD.md +++ b/PRD.md @@ -4,8 +4,8 @@ - **Project Name**: a7 (repository: api7/a7) - **Purpose**: A command-line tool that wraps the API7 Enterprise Edition Admin API, providing a convenient terminal interface for managing API7 EE resources including both control-plane and data-plane operations. - **Target Users**: DevOps engineers, API developers, platform teams, and SREs responsible for managing API7 Enterprise gateways. -- **Design Philosophy**: AI-first development. Modeled after the [a6 CLI](https://github.com/moonming/a6) (for Apache APISIX), extended for Enterprise-specific capabilities (gateway groups, RBAC, service templates, developer portal, etc.). -- **Reference Implementation**: [a6 CLI](https://github.com/moonming/a6) — all features in a6 should have equivalents in a7, adapted for API7 EE's dual-API architecture. +- **Design Philosophy**: AI-first development. Modeled after the [a6 CLI](https://github.com/moonming/a6) (for Apache APISIX), extended for Enterprise-specific capabilities. GA scope is **management-plane stability**: imperative CRUD for supported API7 EE resources, gateway-group scoping, and declarative config. Enterprise modules (RBAC, developer portal, audit logs, custom plugins, access-token management) are deferred post-GA. +- **Reference Implementation**: [a6 CLI](https://github.com/moonming/a6). a6 features map to a7 where the API7 EE API supports them; items without an EE equivalent are noted as "not supported" or "deferred" below. ## Problem Statement - API7 Enterprise Edition has a comprehensive REST API but lacks an imperative CLI for ad-hoc operations. @@ -15,20 +15,20 @@ ## Goals and Non-Goals -### Goals -- Provide full CRUD operations for all API7 EE resources (both control-plane `/api/*` and APISIX admin `/apisix/admin/*` endpoints). Note: 3 APISIX resources (standalone upstream, consumer group, plugin config) are not exposed in API7 EE. -- Support **multiple authentication modes**: access tokens (X-API-KEY with `a7ee` prefix) and session-based login. -- Implement **gateway group** scoping for all runtime operations (enterprise-specific concept). +### Goals (GA Scope) +- Provide full CRUD for the **supported** API7 EE runtime resources (route, service, consumer, credential, ssl, global-rule, stream-route, plugin-metadata, secret, proto) plus gateway-group on the control plane. 3 APISIX resources (standalone upstream, consumer group, plugin config) are not exposed in API7 EE and a7 does not ship commands for them. +- Authenticate via **access token** (X-API-KEY with `a7ee` prefix). Session login is deferred (see below). +- Implement **gateway group** scoping for all runtime operations. - Implement context/profile management for switching between multiple API7 EE instances. - Support rich terminal output (tables for TTY, JSON/YAML for pipes). -- Support **file-based resource creation and update** (`-f/--file`) for all resource types. +- Support **file-based resource creation and update** (`-f/--file`) for all supported resource types. - Support **resource export** to YAML/JSON with label filtering for all applicable resources. - Provide **declarative configuration** operations (sync, dump, diff, validate) absorbing ADC-like functionality. - Provide **debug commands** for real-time log streaming and request tracing. - Provide shell completions (bash, zsh, fish, PowerShell). -- Provide **AI agent skills** (SKILL.md files) for AI coding agents to work effectively with API7 EE. -- Provide comprehensive **documentation**: ADRs, coding standards, golden example, testing strategy, user guides. -- Provide **end-to-end tests** with Docker-based API7 EE test environment. +- Provide **AI agent skills** (SKILL.md files) describing only supported workflows. +- Provide comprehensive **documentation**: ADRs, coding standards, golden example, testing strategy, user guides, GA test plan / report. +- Provide **end-to-end tests** with Docker-based API7 EE test environment, covering full CRUD round-trips through the CLI. - Maintain an extensible command architecture following a6 patterns (Factory + IOStreams + API Client). ### Non-Goals @@ -56,8 +56,8 @@ 3. **Profile/Context config**: stored in `~/.config/a7/config.yaml` ### Token Types Supported -- **Access Token** (prefix `a7ee`): Full control-plane + APISIX admin API access, user-scoped. -- **Session Login**: `a7 auth login --username --password ` for cookie-based session auth. +- **Access Token** (prefix `a7ee`): Full control-plane + APISIX admin API access, user-scoped. **GA-supported.** +- **Session Login** (`a7 auth login --username --password `): cookie-based session auth. **Deferred (post-GA).** ### Security - Prevent sensitive data from appearing in shell history by supporting key input from files or stdin. @@ -91,31 +91,13 @@ a7 [args] [flags] ### Resource Commands — Control Plane (`/api/*`) -#### Service Templates (design-time) -Service templates are not part of current a7 support. Manage runtime services -directly and define upstreams inline on services or routes. - #### Gateway Groups - `a7 gateway-group list|get|create|update|delete` -#### Tokens (access tokens) -- `a7 token list|get|create|delete|regenerate` - -#### Users & RBAC -- `a7 user list|get|create|update|delete` -- `a7 role list|get|create|update|delete` -- `a7 permission-policy list|get|create|update|delete` - -#### Developer Portal -- `a7 portal application list|get|create|update|delete` -- `a7 portal developer list|get|create|delete` +#### Service Templates +> **Not supported in GA**: Manage runtime services directly and define upstreams inline on services or routes. -#### Custom Plugins -- `a7 custom-plugin list|get|create|update|delete` - -#### System -- `a7 system settings [get|update]` -- `a7 audit-log list` +> The following control-plane modules are **deferred (post-GA)**: access-token management, RBAC (users / roles / permission policies), developer portal (applications, developers), custom plugins, system settings, audit logs. See the "Deferred (Post-GA)" section below. ### Resource Commands — Published / Runtime (`/apisix/admin/*`) @@ -165,13 +147,13 @@ All runtime commands require `--gateway-group ` (or default from context). ### Utility Commands - `a7 context create|use|list|delete|current` — Manage contexts for multiple API7 EE instances. -- `a7 auth login|logout` — Session-based authentication. - `a7 config sync|dump|diff|validate` — Declarative configuration operations. - `a7 debug logs` — Stream real-time API7 EE error logs. - `a7 debug trace` — Trace request flow through the gateway. - `a7 completion bash|zsh|fish|powershell` — Shell completion scripts. - `a7 version` — Display version information. - `a7 update` — Self-update binary. +- `a7 auth login|logout`: Session-based authentication. **Deferred (post-GA).** ## Implementation Phases @@ -227,7 +209,7 @@ All runtime commands require `--gateway-group ` (or default from context). 4. ✅ `docs/testing-strategy.md` — Unit test and E2E test patterns. 5. ✅ `docs/skills.md` — AI agent skill format specification. 6. ✅ `docs/documentation-maintenance.md` — Doc update rules and templates. -7. ✅ `docs/roadmap.md` — Per-PR development plan for Phases 5-9. +7. ✅ `docs/roadmap.md`: Phase status and deferred (post-GA) work. 8. ✅ `docs/api7ee-api-spec.md` — API7 EE Admin API reference (16 resources, dual-API). 9. ✅ `docs/user-guide/` — per-resource user guides (getting-started, configuration, route, service, upstream, consumer, ssl, plugin, global-rule, stream-route, plugin-metadata, credential, secret, proto, declarative-config, gateway-group, debug, bulk-operations). @@ -264,16 +246,20 @@ Port and adapt 40 SKILL.md files from a6, organized by category: 9. ✅ Makefile targets: `docker-up`, `docker-down`, `test-e2e`. 10. ✅ All 40 skill examples covered in resource-specific tests. -### Phase 9 — Enterprise-Specific Features 🔲 FUTURE +## Deferred (Post-GA) + +These items are **not in GA scope**. They are recorded here so the design intent is preserved, but they are not commitments for the GA release; revisit only after GA management-plane stability is locked in. + 1. 🔲 Token management (create/list/delete/regenerate). 2. 🔲 RBAC management: user, role, permission-policy. 3. 🔲 Developer Portal: application, developer, subscription. 4. 🔲 Custom plugin management. 5. 🔲 Audit log querying. -6. 🔲 `a7 auth login/logout` — Session-based authentication. -7. 🔲 Interactive mode (fuzzy selection). -8. 🔲 Extension/plugin system. -9. 🔲 Bulk operations. +6. 🔲 System settings (get/update). +7. 🔲 `a7 auth login/logout` (session-based authentication). +8. 🔲 Interactive mode (fuzzy selection). +9. 🔲 Extension/plugin system. +10. 🔲 Bulk operations. ## UX Requirements - **TTY Detection**: Default to tables in interactive terminals and JSON when piped. @@ -332,6 +318,6 @@ The following table tracks feature parity between a7 and [a6](https://github.com | Debug (logs + trace) | ✅ | ✅ | Phase 7 | | Self-update | ✅ | ✅ | Phase 7 | | E2E tests | ✅ | ✅ | Phase 8 | -| Bulk operations | ✅ | 🔲 | Phase 9 | -| Interactive mode | ✅ | 🔲 | Phase 9 | -| Extension system | ✅ | 🔲 | Phase 9 | +| Bulk operations | ✅ | 🔲 | Deferred (post-GA) | +| Interactive mode | ✅ | 🔲 | Deferred (post-GA) | +| Extension system | ✅ | 🔲 | Deferred (post-GA) | diff --git a/docs/roadmap.md b/docs/roadmap.md index 14296f9..a80bd49 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,97 +1,61 @@ # Development Roadmap -This document defines the per-PR development plan for the a7 CLI (API7 Enterprise Edition). Each PR is self-contained and ships implementation code, e2e tests against a real API7 EE instance, and user-facing documentation updates. +This document tracks phase status for the a7 CLI (API7 Enterprise Edition) and records what is **deferred (post-GA)**. For the authoritative scope statement see `PRD.md`. For per-resource validation against a live API7 EE see `docs/ga-test-plan.md` and `docs/ga-test-report.md`. -> **Status: 🚧 Phase 5 (Documentation) IN PROGRESS** +> **Status: GA Readiness Handoff.** Phases 1 through 8 are complete. Current effort is GA validation of the management plane against a real API7 EE instance (see issue #22). Phase 9 work is deferred post-GA. --- -## Phase 5 — Documentation (Current) +## Completed Phases -**Goal**: Establish comprehensive documentation for the a7 project, adapting a6 references for API7 EE specific concepts (dual-API, gateway groups, JSON Patch). +| Phase | Scope | Status | +|-------|-------|--------| +| 1 | Core CLI scaffold (Factory DI, IOStreams, HTTP client, mock framework, completions, `a7 version`) | ✅ | +| 2 | Resource CRUD for all API7 EE supported resources (route, service, consumer, credential, ssl, plugin, plugin-metadata, global-rule, stream-route, secret, proto, gateway-group) | ✅ | +| 3 | CLI usability (`-f/--file`, `export`, `--force`, `--label`). `--dry-run` and `--verbose` are partial; see PRD Phase 3. | ✅ (partial flags noted in PRD) | +| 4 | Declarative configuration (`a7 config dump|diff|sync|validate`) | ✅ | +| 5 | Documentation (ADR, coding standards, golden example, testing strategy, skills, api spec, user guides) | ✅ | +| 6 | AI agent skills (40 SKILL.md files, taxonomy in `docs/skills.md`) | ✅ | +| 7 | Debug & operations (`a7 debug logs`, `a7 debug trace`, `a7 update`) | ✅ | +| 8 | E2E tests against a real API7 EE Docker stack (per-resource CRUD, config sync/diff/dump/validate, debug, completion, version) | ✅ | -### PR-28: Core Documentation Infrastructure - -| File | Purpose | -|------|---------| -| `docs/adr/001-tech-stack.md` | Tech stack decisions, dual-API architecture | -| `docs/coding-standards.md` | Go style, naming (Tokens, Gateway Groups) | -| `docs/golden-example.md` | Reference implementation for action commands | -| `docs/testing-strategy.md` | Test patterns, E2E setup for EE | -| `docs/skills.md` | AI agent skill taxonomy and roadmap | -| `docs/documentation-maintenance.md` | Rules for keeping docs in sync | -| `docs/roadmap.md` | THIS file | -| `docs/api7ee-api-spec.md` | API7 EE Admin API reference | +For the detailed checklist of items under each phase see `PRD.md` "Implementation Phases". --- -## Phase 6 — AI Agent Skills - -**Goal**: Create 40 `SKILL.md` files enabling AI agents to operate API7 EE. - -### PR-29: AI Gateway & Enterprise Skills -- **Skills**: `a7-plugin-ai-proxy`, `a7-plugin-ai-prompt-template`, `a7-plugin-ai-rag`, `a7-recipe-gateway-group` -- **Focus**: Configuring LLM providers and supported API7 EE runtime resources. - -### PR-30: Security & Auth Skills -- **Skills**: `a7-plugin-key-auth`, `a7-plugin-openid-connect`, `a7-plugin-wolf-rbac`, `a7-recipe-rbac-setup` -- **Focus**: Enterprise authentication and role-based access control. +## GA Readiness Handoff (Current Focus) ---- - -## Phase 7 — Debug & Operations +Tracking issue: **api7/a7#22**. Scope: management-plane validation against API7 EE 3.9.12, not new enterprise features and not data-plane traffic forwarding. -**Goal**: Implement operational tools for troubleshooting API7 EE environments. +Working items live as sub-issues of #22. Exit criteria (copied from #22 for visibility): -### PR-31: Debug Logs & Trace -- **Commands**: `a7 debug logs`, `a7 debug trace ` -- **Function**: Stream logs from EE control-plane/gateway; trace request execution path with EE-specific headers. +- Core resource commands work against real API7 EE. +- E2E covers full CRUD round-trips through the CLI. +- `config sync/diff/dump/validate` work with service-centered resources. +- Unsupported resources are removed or clearly blocked. +- Docs and skills only describe supported workflows. +- CI green on `master`. +- Release notes state supported API7 EE versions and unsupported resources. -### PR-32: Resource Update (JSON Patch) -- **Commands**: `a7 update --patch` -- **Function**: Implement precise updates using JSON Patch (RFC 6902) as required by API7 EE. +`docs/ga-test-plan.md` is the per-resource test plan; `docs/ga-test-report.md` records run dispositions. --- -## Phase 8 — E2E Tests - -**Goal**: Establish a robust integration test suite against a real API7 EE instance. - -### PR-33: E2E Framework & Smoke Tests -- **Infrastructure**: `docker-compose.yml` with API7 EE + etcd + httpbin. -- **Scenarios**: `TestSmoke_Connectivity`, `TestAuth_TokenValidation`. +## Deferred (Post-GA) -### PR-34: Resource Lifecycle Tests -- **Scenarios**: CRUD tests for all 16 core resources, verifying gateway group scoping and dual-API prefix handling. +Previously tracked as "Phase 9". These are **not** in GA scope and not committed for the GA release. They are recorded so the design intent is preserved; revisit only after GA stability is locked in. ---- - -## Phase 9 — Enterprise Features - -**Goal**: Finalize CLI support for advanced API7 EE modules. - -### PR-35: Token & RBAC Management -- **Commands**: `a7 token create|list`, `a7 user/role/policy` -- **Focus**: Managing CLI access tokens and platform permissions. - -### PR-36: Custom Plugin Extensions -- **Commands**: `a7 custom-plugin` (future) -- **Focus**: Custom Lua plugin management when exposed by supported API7 EE APIs. - ---- +| Area | Notes | +|------|-------| +| Token management (`a7 token ...`) | Access-token CRUD on the control plane. | +| RBAC (`a7 user`, `a7 role`, `a7 permission-policy`) | User and role administration. | +| Developer Portal (`a7 portal ...`) | Applications, developers, subscriptions. | +| Custom plugin management (`a7 custom-plugin ...`) | When and if the EE API surface stabilizes. | +| Audit log querying (`a7 audit-log list`) | | +| System settings (`a7 system settings ...`) | | +| Session login (`a7 auth login|logout`) | Cookie-based session auth; access tokens cover GA. | +| Interactive mode | Fuzzy selection across resources. | +| Extension / plugin system | Out-of-tree CLI extensions. | +| Bulk operations | Multi-resource batch CRUD. | -## Summary Table (Remaining Phases) - -| Phase | PR | Scope | Validation | -|-------|----|-------|------------| -| 5 | PR-28 | Documentation Infrastructure | Doc linting | -| 6 | PR-29 | AI Gateway Skills | Skill validation | -| 6 | PR-30 | Security & Auth Skills | Skill validation | -| 7 | PR-31 | Debug Tooling | E2E output validation | -| 7 | PR-32 | JSON Patch Support | API integration tests | -| 8 | PR-33 | E2E Test Infra | Smoke tests | -| 8 | PR-34 | Resource CRUD E2E | Lifecycle validation | -| 9 | PR-35 | Token & RBAC | Multi-user E2E | -| 9 | PR-36 | Custom Plugin Extensions | Feature-specific E2E | - -**Total**: 9 PRs to reach production readiness. +These items are listed under "Deferred (Post-GA)" in `PRD.md`. From ffeb09bfe872e301defec4b2a233dd9c27e188ab Mon Sep 17 00:00:00 2001 From: Abhishek Choudhary Date: Wed, 27 May 2026 13:50:33 +0800 Subject: [PATCH 2/3] docs: revert PRD.md changes from this PR Drop PRD.md from the GA-scope reconciliation. AGENTS.md and docs/roadmap.md changes remain. --- PRD.md | 72 +++++++++++++++++++++++++++++++++++----------------------- 1 file changed, 43 insertions(+), 29 deletions(-) diff --git a/PRD.md b/PRD.md index d349765..a99b594 100644 --- a/PRD.md +++ b/PRD.md @@ -4,8 +4,8 @@ - **Project Name**: a7 (repository: api7/a7) - **Purpose**: A command-line tool that wraps the API7 Enterprise Edition Admin API, providing a convenient terminal interface for managing API7 EE resources including both control-plane and data-plane operations. - **Target Users**: DevOps engineers, API developers, platform teams, and SREs responsible for managing API7 Enterprise gateways. -- **Design Philosophy**: AI-first development. Modeled after the [a6 CLI](https://github.com/moonming/a6) (for Apache APISIX), extended for Enterprise-specific capabilities. GA scope is **management-plane stability**: imperative CRUD for supported API7 EE resources, gateway-group scoping, and declarative config. Enterprise modules (RBAC, developer portal, audit logs, custom plugins, access-token management) are deferred post-GA. -- **Reference Implementation**: [a6 CLI](https://github.com/moonming/a6). a6 features map to a7 where the API7 EE API supports them; items without an EE equivalent are noted as "not supported" or "deferred" below. +- **Design Philosophy**: AI-first development. Modeled after the [a6 CLI](https://github.com/moonming/a6) (for Apache APISIX), extended for Enterprise-specific capabilities (gateway groups, RBAC, service templates, developer portal, etc.). +- **Reference Implementation**: [a6 CLI](https://github.com/moonming/a6) — all features in a6 should have equivalents in a7, adapted for API7 EE's dual-API architecture. ## Problem Statement - API7 Enterprise Edition has a comprehensive REST API but lacks an imperative CLI for ad-hoc operations. @@ -15,20 +15,20 @@ ## Goals and Non-Goals -### Goals (GA Scope) -- Provide full CRUD for the **supported** API7 EE runtime resources (route, service, consumer, credential, ssl, global-rule, stream-route, plugin-metadata, secret, proto) plus gateway-group on the control plane. 3 APISIX resources (standalone upstream, consumer group, plugin config) are not exposed in API7 EE and a7 does not ship commands for them. -- Authenticate via **access token** (X-API-KEY with `a7ee` prefix). Session login is deferred (see below). -- Implement **gateway group** scoping for all runtime operations. +### Goals +- Provide full CRUD operations for all API7 EE resources (both control-plane `/api/*` and APISIX admin `/apisix/admin/*` endpoints). Note: 3 APISIX resources (standalone upstream, consumer group, plugin config) are not exposed in API7 EE. +- Support **multiple authentication modes**: access tokens (X-API-KEY with `a7ee` prefix) and session-based login. +- Implement **gateway group** scoping for all runtime operations (enterprise-specific concept). - Implement context/profile management for switching between multiple API7 EE instances. - Support rich terminal output (tables for TTY, JSON/YAML for pipes). -- Support **file-based resource creation and update** (`-f/--file`) for all supported resource types. +- Support **file-based resource creation and update** (`-f/--file`) for all resource types. - Support **resource export** to YAML/JSON with label filtering for all applicable resources. - Provide **declarative configuration** operations (sync, dump, diff, validate) absorbing ADC-like functionality. - Provide **debug commands** for real-time log streaming and request tracing. - Provide shell completions (bash, zsh, fish, PowerShell). -- Provide **AI agent skills** (SKILL.md files) describing only supported workflows. -- Provide comprehensive **documentation**: ADRs, coding standards, golden example, testing strategy, user guides, GA test plan / report. -- Provide **end-to-end tests** with Docker-based API7 EE test environment, covering full CRUD round-trips through the CLI. +- Provide **AI agent skills** (SKILL.md files) for AI coding agents to work effectively with API7 EE. +- Provide comprehensive **documentation**: ADRs, coding standards, golden example, testing strategy, user guides. +- Provide **end-to-end tests** with Docker-based API7 EE test environment. - Maintain an extensible command architecture following a6 patterns (Factory + IOStreams + API Client). ### Non-Goals @@ -56,8 +56,8 @@ 3. **Profile/Context config**: stored in `~/.config/a7/config.yaml` ### Token Types Supported -- **Access Token** (prefix `a7ee`): Full control-plane + APISIX admin API access, user-scoped. **GA-supported.** -- **Session Login** (`a7 auth login --username --password `): cookie-based session auth. **Deferred (post-GA).** +- **Access Token** (prefix `a7ee`): Full control-plane + APISIX admin API access, user-scoped. +- **Session Login**: `a7 auth login --username --password ` for cookie-based session auth. ### Security - Prevent sensitive data from appearing in shell history by supporting key input from files or stdin. @@ -91,13 +91,31 @@ a7 [args] [flags] ### Resource Commands — Control Plane (`/api/*`) +#### Service Templates (design-time) +Service templates are not part of current a7 support. Manage runtime services +directly and define upstreams inline on services or routes. + #### Gateway Groups - `a7 gateway-group list|get|create|update|delete` -#### Service Templates -> **Not supported in GA**: Manage runtime services directly and define upstreams inline on services or routes. +#### Tokens (access tokens) +- `a7 token list|get|create|delete|regenerate` + +#### Users & RBAC +- `a7 user list|get|create|update|delete` +- `a7 role list|get|create|update|delete` +- `a7 permission-policy list|get|create|update|delete` + +#### Developer Portal +- `a7 portal application list|get|create|update|delete` +- `a7 portal developer list|get|create|delete` -> The following control-plane modules are **deferred (post-GA)**: access-token management, RBAC (users / roles / permission policies), developer portal (applications, developers), custom plugins, system settings, audit logs. See the "Deferred (Post-GA)" section below. +#### Custom Plugins +- `a7 custom-plugin list|get|create|update|delete` + +#### System +- `a7 system settings [get|update]` +- `a7 audit-log list` ### Resource Commands — Published / Runtime (`/apisix/admin/*`) @@ -147,13 +165,13 @@ All runtime commands require `--gateway-group ` (or default from context). ### Utility Commands - `a7 context create|use|list|delete|current` — Manage contexts for multiple API7 EE instances. +- `a7 auth login|logout` — Session-based authentication. - `a7 config sync|dump|diff|validate` — Declarative configuration operations. - `a7 debug logs` — Stream real-time API7 EE error logs. - `a7 debug trace` — Trace request flow through the gateway. - `a7 completion bash|zsh|fish|powershell` — Shell completion scripts. - `a7 version` — Display version information. - `a7 update` — Self-update binary. -- `a7 auth login|logout`: Session-based authentication. **Deferred (post-GA).** ## Implementation Phases @@ -209,7 +227,7 @@ All runtime commands require `--gateway-group ` (or default from context). 4. ✅ `docs/testing-strategy.md` — Unit test and E2E test patterns. 5. ✅ `docs/skills.md` — AI agent skill format specification. 6. ✅ `docs/documentation-maintenance.md` — Doc update rules and templates. -7. ✅ `docs/roadmap.md`: Phase status and deferred (post-GA) work. +7. ✅ `docs/roadmap.md` — Per-PR development plan for Phases 5-9. 8. ✅ `docs/api7ee-api-spec.md` — API7 EE Admin API reference (16 resources, dual-API). 9. ✅ `docs/user-guide/` — per-resource user guides (getting-started, configuration, route, service, upstream, consumer, ssl, plugin, global-rule, stream-route, plugin-metadata, credential, secret, proto, declarative-config, gateway-group, debug, bulk-operations). @@ -246,20 +264,16 @@ Port and adapt 40 SKILL.md files from a6, organized by category: 9. ✅ Makefile targets: `docker-up`, `docker-down`, `test-e2e`. 10. ✅ All 40 skill examples covered in resource-specific tests. -## Deferred (Post-GA) - -These items are **not in GA scope**. They are recorded here so the design intent is preserved, but they are not commitments for the GA release; revisit only after GA management-plane stability is locked in. - +### Phase 9 — Enterprise-Specific Features 🔲 FUTURE 1. 🔲 Token management (create/list/delete/regenerate). 2. 🔲 RBAC management: user, role, permission-policy. 3. 🔲 Developer Portal: application, developer, subscription. 4. 🔲 Custom plugin management. 5. 🔲 Audit log querying. -6. 🔲 System settings (get/update). -7. 🔲 `a7 auth login/logout` (session-based authentication). -8. 🔲 Interactive mode (fuzzy selection). -9. 🔲 Extension/plugin system. -10. 🔲 Bulk operations. +6. 🔲 `a7 auth login/logout` — Session-based authentication. +7. 🔲 Interactive mode (fuzzy selection). +8. 🔲 Extension/plugin system. +9. 🔲 Bulk operations. ## UX Requirements - **TTY Detection**: Default to tables in interactive terminals and JSON when piped. @@ -318,6 +332,6 @@ The following table tracks feature parity between a7 and [a6](https://github.com | Debug (logs + trace) | ✅ | ✅ | Phase 7 | | Self-update | ✅ | ✅ | Phase 7 | | E2E tests | ✅ | ✅ | Phase 8 | -| Bulk operations | ✅ | 🔲 | Deferred (post-GA) | -| Interactive mode | ✅ | 🔲 | Deferred (post-GA) | -| Extension system | ✅ | 🔲 | Deferred (post-GA) | +| Bulk operations | ✅ | 🔲 | Phase 9 | +| Interactive mode | ✅ | 🔲 | Phase 9 | +| Extension system | ✅ | 🔲 | Phase 9 | From 67d3ed365d0d267da722578062d008c8623e94e1 Mon Sep 17 00:00:00 2001 From: Abhishek Choudhary Date: Wed, 27 May 2026 13:50:48 +0800 Subject: [PATCH 3/3] docs: revert docs/roadmap.md changes from this PR Drop docs/roadmap.md from the reconciliation. Only AGENTS.md remains in this PR. --- docs/roadmap.md | 116 +++++++++++++++++++++++++++++++----------------- 1 file changed, 76 insertions(+), 40 deletions(-) diff --git a/docs/roadmap.md b/docs/roadmap.md index a80bd49..14296f9 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,61 +1,97 @@ # Development Roadmap -This document tracks phase status for the a7 CLI (API7 Enterprise Edition) and records what is **deferred (post-GA)**. For the authoritative scope statement see `PRD.md`. For per-resource validation against a live API7 EE see `docs/ga-test-plan.md` and `docs/ga-test-report.md`. +This document defines the per-PR development plan for the a7 CLI (API7 Enterprise Edition). Each PR is self-contained and ships implementation code, e2e tests against a real API7 EE instance, and user-facing documentation updates. -> **Status: GA Readiness Handoff.** Phases 1 through 8 are complete. Current effort is GA validation of the management plane against a real API7 EE instance (see issue #22). Phase 9 work is deferred post-GA. +> **Status: 🚧 Phase 5 (Documentation) IN PROGRESS** --- -## Completed Phases +## Phase 5 — Documentation (Current) -| Phase | Scope | Status | -|-------|-------|--------| -| 1 | Core CLI scaffold (Factory DI, IOStreams, HTTP client, mock framework, completions, `a7 version`) | ✅ | -| 2 | Resource CRUD for all API7 EE supported resources (route, service, consumer, credential, ssl, plugin, plugin-metadata, global-rule, stream-route, secret, proto, gateway-group) | ✅ | -| 3 | CLI usability (`-f/--file`, `export`, `--force`, `--label`). `--dry-run` and `--verbose` are partial; see PRD Phase 3. | ✅ (partial flags noted in PRD) | -| 4 | Declarative configuration (`a7 config dump|diff|sync|validate`) | ✅ | -| 5 | Documentation (ADR, coding standards, golden example, testing strategy, skills, api spec, user guides) | ✅ | -| 6 | AI agent skills (40 SKILL.md files, taxonomy in `docs/skills.md`) | ✅ | -| 7 | Debug & operations (`a7 debug logs`, `a7 debug trace`, `a7 update`) | ✅ | -| 8 | E2E tests against a real API7 EE Docker stack (per-resource CRUD, config sync/diff/dump/validate, debug, completion, version) | ✅ | +**Goal**: Establish comprehensive documentation for the a7 project, adapting a6 references for API7 EE specific concepts (dual-API, gateway groups, JSON Patch). -For the detailed checklist of items under each phase see `PRD.md` "Implementation Phases". +### PR-28: Core Documentation Infrastructure + +| File | Purpose | +|------|---------| +| `docs/adr/001-tech-stack.md` | Tech stack decisions, dual-API architecture | +| `docs/coding-standards.md` | Go style, naming (Tokens, Gateway Groups) | +| `docs/golden-example.md` | Reference implementation for action commands | +| `docs/testing-strategy.md` | Test patterns, E2E setup for EE | +| `docs/skills.md` | AI agent skill taxonomy and roadmap | +| `docs/documentation-maintenance.md` | Rules for keeping docs in sync | +| `docs/roadmap.md` | THIS file | +| `docs/api7ee-api-spec.md` | API7 EE Admin API reference | --- -## GA Readiness Handoff (Current Focus) +## Phase 6 — AI Agent Skills + +**Goal**: Create 40 `SKILL.md` files enabling AI agents to operate API7 EE. + +### PR-29: AI Gateway & Enterprise Skills +- **Skills**: `a7-plugin-ai-proxy`, `a7-plugin-ai-prompt-template`, `a7-plugin-ai-rag`, `a7-recipe-gateway-group` +- **Focus**: Configuring LLM providers and supported API7 EE runtime resources. + +### PR-30: Security & Auth Skills +- **Skills**: `a7-plugin-key-auth`, `a7-plugin-openid-connect`, `a7-plugin-wolf-rbac`, `a7-recipe-rbac-setup` +- **Focus**: Enterprise authentication and role-based access control. -Tracking issue: **api7/a7#22**. Scope: management-plane validation against API7 EE 3.9.12, not new enterprise features and not data-plane traffic forwarding. +--- + +## Phase 7 — Debug & Operations -Working items live as sub-issues of #22. Exit criteria (copied from #22 for visibility): +**Goal**: Implement operational tools for troubleshooting API7 EE environments. -- Core resource commands work against real API7 EE. -- E2E covers full CRUD round-trips through the CLI. -- `config sync/diff/dump/validate` work with service-centered resources. -- Unsupported resources are removed or clearly blocked. -- Docs and skills only describe supported workflows. -- CI green on `master`. -- Release notes state supported API7 EE versions and unsupported resources. +### PR-31: Debug Logs & Trace +- **Commands**: `a7 debug logs`, `a7 debug trace ` +- **Function**: Stream logs from EE control-plane/gateway; trace request execution path with EE-specific headers. -`docs/ga-test-plan.md` is the per-resource test plan; `docs/ga-test-report.md` records run dispositions. +### PR-32: Resource Update (JSON Patch) +- **Commands**: `a7 update --patch` +- **Function**: Implement precise updates using JSON Patch (RFC 6902) as required by API7 EE. --- -## Deferred (Post-GA) +## Phase 8 — E2E Tests + +**Goal**: Establish a robust integration test suite against a real API7 EE instance. + +### PR-33: E2E Framework & Smoke Tests +- **Infrastructure**: `docker-compose.yml` with API7 EE + etcd + httpbin. +- **Scenarios**: `TestSmoke_Connectivity`, `TestAuth_TokenValidation`. -Previously tracked as "Phase 9". These are **not** in GA scope and not committed for the GA release. They are recorded so the design intent is preserved; revisit only after GA stability is locked in. +### PR-34: Resource Lifecycle Tests +- **Scenarios**: CRUD tests for all 16 core resources, verifying gateway group scoping and dual-API prefix handling. -| Area | Notes | -|------|-------| -| Token management (`a7 token ...`) | Access-token CRUD on the control plane. | -| RBAC (`a7 user`, `a7 role`, `a7 permission-policy`) | User and role administration. | -| Developer Portal (`a7 portal ...`) | Applications, developers, subscriptions. | -| Custom plugin management (`a7 custom-plugin ...`) | When and if the EE API surface stabilizes. | -| Audit log querying (`a7 audit-log list`) | | -| System settings (`a7 system settings ...`) | | -| Session login (`a7 auth login|logout`) | Cookie-based session auth; access tokens cover GA. | -| Interactive mode | Fuzzy selection across resources. | -| Extension / plugin system | Out-of-tree CLI extensions. | -| Bulk operations | Multi-resource batch CRUD. | +--- + +## Phase 9 — Enterprise Features + +**Goal**: Finalize CLI support for advanced API7 EE modules. + +### PR-35: Token & RBAC Management +- **Commands**: `a7 token create|list`, `a7 user/role/policy` +- **Focus**: Managing CLI access tokens and platform permissions. + +### PR-36: Custom Plugin Extensions +- **Commands**: `a7 custom-plugin` (future) +- **Focus**: Custom Lua plugin management when exposed by supported API7 EE APIs. + +--- -These items are listed under "Deferred (Post-GA)" in `PRD.md`. +## Summary Table (Remaining Phases) + +| Phase | PR | Scope | Validation | +|-------|----|-------|------------| +| 5 | PR-28 | Documentation Infrastructure | Doc linting | +| 6 | PR-29 | AI Gateway Skills | Skill validation | +| 6 | PR-30 | Security & Auth Skills | Skill validation | +| 7 | PR-31 | Debug Tooling | E2E output validation | +| 7 | PR-32 | JSON Patch Support | API integration tests | +| 8 | PR-33 | E2E Test Infra | Smoke tests | +| 8 | PR-34 | Resource CRUD E2E | Lifecycle validation | +| 9 | PR-35 | Token & RBAC | Multi-user E2E | +| 9 | PR-36 | Custom Plugin Extensions | Feature-specific E2E | + +**Total**: 9 PRs to reach production readiness.