Merge pull request #213 from hookdeck/feat/phase-5a-gateway-resources

feat: Agentic DX phase 5a: CLI — gateway group, source management, connection deprecation notice

Author: leggetter

.github/workflows/release.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v5
         with:
-          version: v2.10.2
+          version: v2.12.1
           args: release -f .goreleaser/mac.yml --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GORELEASER_GITHUB_TOKEN }}
@@ -51,7 +51,7 @@ jobs:
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v5
         with:
-          version: v2.10.2
+          version: v2.12.1
           args: release -f .goreleaser/linux.yml --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GORELEASER_GITHUB_TOKEN }}
@@ -70,7 +70,7 @@ jobs:
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v5
         with:
-          version: v2.10.2
+          version: v2.12.1
           args: release -f .goreleaser/windows.yml --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GORELEASER_GITHUB_TOKEN }}
@@ -143,7 +143,7 @@ jobs:
       - name: Build npm binaries with GoReleaser
         uses: goreleaser/goreleaser-action@v5
         with:
-          version: v2.10.2
+          version: v2.12.1
           args: build -f .goreleaser/npm.yml --clean --skip validate
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test-npm-build.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Install GoReleaser
         uses: goreleaser/goreleaser-action@v5
         with:
-          version: v2.10.2
+          version: v2.12.1
           install-only: true
 
       - name: Run npm build tests

.github/workflows/test.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v5
         with:
-          version: v2.10.2
+          version: v2.12.1
           args: release --skip=publish --snapshot -f .goreleaser/mac.yml --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GORELEASER_GITHUB_TOKEN }}
@@ -56,7 +56,7 @@ jobs:
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v5
         with:
-          version: v2.10.2
+          version: v2.12.1
           args: release --skip=publish --snapshot -f .goreleaser/linux.yml --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GORELEASER_GITHUB_TOKEN }}
@@ -75,7 +75,7 @@ jobs:
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v5
         with:
-          version: v2.10.2
+          version: v2.12.1
           args: release --skip=publish --snapshot -f .goreleaser/windows.yml --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GORELEASER_GITHUB_TOKEN }}

.gitignore

@@ -17,3 +17,6 @@ __debug_bin
 node_modules/
 .env
 test-scripts/.install-test/
+
+# Temporary OpenAPI spec download (large; do not commit)
+.plans/openapi-2025-07-01.json

.goreleaser/linux.yml

@@ -52,46 +52,24 @@ nfpms:
     formats:
       - deb
       - rpm
-dockers:
-  - goos: linux
-    goarch: amd64
-    ids:
+# dockers_v2 uses buildx to build multi-arch manifests in one step,
+# avoiding the "is a manifest list" error from the legacy dockers + docker_manifests flow
+dockers_v2:
+  - ids:
       - hookdeck-linux
-    image_templates:
-      - "hookdeck/hookdeck-cli:{{ .Tag }}-amd64"
-      - "{{ if not .Prerelease }}hookdeck/hookdeck-cli:latest-amd64{{ end }}"
-    build_flag_templates:
-      - "--pull"
-      - "--label=org.opencontainers.image.created={{.Date}}"
-      - "--label=org.opencontainers.image.name={{.ProjectName}}"
-      - "--label=org.opencontainers.image.revision={{.FullCommit}}"
-      - "--label=org.opencontainers.image.version={{.Version}}"
-      - "--label=repository=https://github.com/hookdeck/hookdeck-cli"
-      - "--label=homepage=https://hookdeck.com"
-      - "--platform=linux/amd64"
-  - goos: linux
-    goarch: arm64
-    ids:
       - hookdeck-linux-arm64
-    image_templates:
-      - "hookdeck/hookdeck-cli:{{ .Tag }}-arm64"
-      - "{{ if not .Prerelease }}hookdeck/hookdeck-cli:latest-arm64{{ end }}"
-    build_flag_templates:
-      - "--pull"
-      - "--label=org.opencontainers.image.created={{.Date}}"
-      - "--label=org.opencontainers.image.name={{.ProjectName}}"
-      - "--label=org.opencontainers.image.revision={{.FullCommit}}"
-      - "--label=org.opencontainers.image.version={{.Version}}"
-      - "--label=repository=https://github.com/hookdeck/hookdeck-cli"
-      - "--label=homepage=https://hookdeck.com"
-      - "--platform=linux/arm64/v8"
-docker_manifests:
-  - name_template: "hookdeck/hookdeck-cli:{{ .Tag }}"
-    image_templates:
-      - "hookdeck/hookdeck-cli:{{ .Tag }}-amd64"
-      - "hookdeck/hookdeck-cli:{{ .Tag }}-arm64"
-  - name_template: "hookdeck/hookdeck-cli:latest"
-    image_templates:
-      - "hookdeck/hookdeck-cli:latest-amd64"
-      - "hookdeck/hookdeck-cli:latest-arm64"
-    skip_push: auto
+    images:
+      - "hookdeck/hookdeck-cli"
+    tags:
+      - "{{ .Tag }}"
+      - "{{ if not .Prerelease }}latest{{ end }}"
+    platforms:
+      - linux/amd64
+      - linux/arm64
+    labels:
+      "org.opencontainers.image.created": "{{.Date}}"
+      "org.opencontainers.image.name": "{{.ProjectName}}"
+      "org.opencontainers.image.revision": "{{.FullCommit}}"
+      "org.opencontainers.image.version": "{{.Version}}"
+      "repository": "https://github.com/hookdeck/hookdeck-cli"
+      "homepage": "https://hookdeck.com"

.plans/README.md

@@ -20,11 +20,33 @@ See [`connection-management-status.md`](./connection-management/connection-manag
 - Connection count command
 - Connection cloning
 
+## Documentation and Transformation Updates ✅
+
+**REFERENCE.md generation:**
+- `REFERENCE.md` is now generated from Cobra command metadata via `go run ./tools/generate-reference`
+- See `tools/generate-reference/main.go` and `REFERENCE.template.md`
+
+**Transformation examples:**
+- All transformation code examples updated from `module.exports = async (r) => r` to the correct Hookdeck format: `addHandler("transform", (request, context) => { return request; })`
+- Applied in: pkg/cmd (create, run, upsert), README.md, REFERENCE.md (via regen), test/acceptance (helpers, transformation_test.go)
+- Transformation run API response model aligned with OpenAPI `TransformationExecutorOutput` (uses `request` field for transformed payload)
+- CLI adds default `content-type: application/json` when request headers are empty so the transformation engine executes successfully
+
+**README rebalance:**
+- Added Sources and destinations subsection (within Manage connections) with examples and link to [REFERENCE.md#sources](REFERENCE.md#sources) and [REFERENCE.md#destinations](REFERENCE.md#destinations)
+- Added Transformations section with examples and link to [REFERENCE.md#transformations](REFERENCE.md#transformations)
+- Added Requests, events, and attempts section with examples and links to [REFERENCE.md#requests](REFERENCE.md#requests), [REFERENCE.md#events](REFERENCE.md#events), [REFERENCE.md#attempts](REFERENCE.md#attempts)
+
 ## Active Planning Documents
 
 - **[`connection-management-status.md`](./connection-management/connection-management-status.md)** - Current implementation status (98% complete)
 - **[`resource-management-implementation.md`](./resource-management-implementation.md)** - Overall resource management plan
 
+## Testing and sandbox
+
+- **Always run tests** when implementing or changing code (`go test ./pkg/...`, and for CLI changes `go test ./test/acceptance/...`). Do not skip tests to avoid failures.
+- If tests fail due to **TLS/certificate errors**, **network**, or **sandbox** (e.g. `x509`, `operation not permitted`), **prompt the user** and **re-run with elevated permissions** (e.g. `required_permissions: ["all"]`) so tests can pass.
+
 ## Development Guidelines
 
 All CLI development follows the patterns documented in [`AGENTS.md`](../AGENTS.md):
@@ -35,4 +57,4 @@ All CLI development follows the patterns documented in [`AGENTS.md`](../AGENTS.m
 - **Ordered array configurations** - For API arrays with ordering (rules, steps, middleware)
 - **Idempotent upsert pattern** - For declarative resource management with `--dry-run` support
 
-Design specifications have been consolidated into `AGENTS.md` as general principles with connection management as concrete examples.
+Design specifications have been consolidated into `AGENTS.md` as general principles with connection management as concrete examples.

.plans/connection-management/connection-management-status.md

@@ -1,5 +1,10 @@
 # Connection Management Implementation Status
 
+## Tests and sandbox
+
+- **Always run tests** when implementing or changing code. Do not skip tests to avoid failures.
+- If tests fail due to **TLS/certificate errors**, **network**, or **sandbox** (e.g. `x509`, `operation not permitted`), **prompt the user** and **re-run with elevated permissions** (e.g. `required_permissions: ["all"]`) so tests can pass.
+
 ## Executive Summary
 
 Connection management for the Hookdeck CLI is **98% complete and production-ready**. All core CRUD operations, lifecycle management, comprehensive authentication, rule configuration, and rate limiting have been fully implemented. The remaining 2% consists of optional enhancements (bulk operations, connection count, cloning) that are low priority.

.plans/resource-management-implementation.md

@@ -32,14 +32,23 @@
   - [ ] `destination update` - Critical for URL changes
   - [ ] `destination delete` - Clean up unused
 
+### ✅ Recent (February 2026)
+- **Transformation examples** - All examples updated to `addHandler("transform", ...)` format (README, REFERENCE, pkg/cmd, tests)
+- **Transformation run** - API response model fixed to match OpenAPI; CLI displays transformed output; default content-type for empty headers
+
 ### 📋 Planned
-- **Transformation Management** (Priority 2 - Week 2)
+- **Transformation Management** (Priority 2 - Week 2) - CRUD already present; examples and run output now correct
 - **Project Management Extensions** (Priority 3 - Week 3)
 - **Advanced Features** (Future)
 
 
 ---
 
+## Testing and sandbox
+
+- **Always run tests** when implementing or changing code. Do not skip tests to avoid failures.
+- If tests fail due to **TLS/certificate errors**, **network**, or **sandbox** (e.g. `x509`, `operation not permitted`), **prompt the user** and **re-run with elevated permissions** (e.g. `required_permissions: ["all"]`) so tests can pass.
+
 ## Background
 
 The Hookdeck CLI currently supports limited commands in `@pkg/cmd` with basic project management. This plan outlines implementing comprehensive resource management for projects, connections, sources, destinations, and transformations using the Hookdeck API (https://api.hookdeck.com/2025-07-01/openapi).
@@ -56,6 +65,7 @@ The Hookdeck CLI currently supports limited commands in `@pkg/cmd` with basic pr
 - **Idempotent operations** - `upsert` commands with `--dry-run` support for declarative management
 - **Type-driven validation** - Progressive validation based on `--type` parameters
 - **JSON fallback** - Complex configurations via `--rules`, `--rules-file`, `--config`, `--config-file`
+- **Plural alias for resource commands** - Every resource command group uses singular as primary `Use` and **must** have the plural as an alias (e.g. `source`/`sources`, `connection`/`connections`, `project`/`projects`). See AGENTS.md § Resource command naming and plural alias.
 
 All CLI commands must follow these established patterns for consistency across the codebase.
 
@@ -66,7 +76,7 @@ All CLI commands must follow these established patterns for consistency across t
 3. **Add source management** - Manage webhook sources with various provider types
 4. **Add destination management** - Manage HTTP, CLI, and Mock API destinations
 5. **Add transformation management** - Manage JavaScript code transformations
-6. **Create reference documentation** - Comprehensive `REFERENCE.md` with examples
+6. ~~**Create reference documentation**~~ - ✅ REFERENCE.md generated via `go run ./tools/generate-reference` from Cobra metadata
 7. **Maintain consistency** - Follow existing CLI patterns and architecture
 
 ## Success Criteria
@@ -398,9 +408,10 @@ func validateSourceType(sourceType string, flags *sourceCreateFlags) error {
 
 ### Phase 4: Documentation and Examples
 
-#### Task 4.1: Create Reference Documentation
-**Files to create:**
-- `REFERENCE.md` - Comprehensive CLI reference
+#### Task 4.1: Create Reference Documentation ✅
+**Files:** `REFERENCE.md` (generated), `tools/generate-reference/main.go`, `REFERENCE.template.md`
+
+REFERENCE.md is generated from Cobra command metadata. Run `go run ./tools/generate-reference` after changing commands/flags. README rebalanced with Sources/destinations, Transformations, and Requests/events/attempts sections, each linking to REFERENCE.md subsections.
 
 **Content Structure:**
 ```markdown
@@ -464,6 +475,8 @@ cmd.Example = `  # List all sources
 
 ### Phase 5: Testing and Validation
 
+**CLI conventions checklist (all phases):** When adding or reviewing a resource command group, ensure it has a **plural alias** (e.g. `source`/`sources`, `connection`/`connections`, `project`/`projects`). See AGENTS.md § Resource command naming and plural alias.
+
 #### Task 5.1: Add Command Tests
 **Files to create:**
 - `pkg/cmd/*_test.go` - Unit tests for all commands