feat(cli)!: refactor fctl for v4

.agents/skills/formance-fctl-plugin/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: formance-fctl-plugin
+description: "Create or extend embedded or external Go service plugins in fctl v4: manifests, declarative forms, API operations and contract tests. Use for plugin development rather than operating the CLI."
+---
+
+# fctl plugin development
+
+Build service commands that work through both the CLI and a standalone SDK
+caller. Keep service behavior in the plugin and terminal/authentication behavior
+in the host. Embedded and external plugins use the same public contract. The Ledger pilot
+owns its implementation in the Ledger repository's `fctl-plugin` module; fctl
+embeds that package or selects an installed executable.
+
+## Establish the contract
+
+Locate the requested fctl checkout and read its `go.mod`, `docs/plugins.md`,
+`pkg/pluginsdk/sdk.go` and `pkg/pluginsdk/interaction.go`. These files take
+precedence over assumptions about older fctl releases. If the checkout lacks
+this SDK, establish the intended version before creating another architecture.
+
+Read the service's published client or API definitions at the requested branch
+or version. Use the small Auth plugin for SDK-backed operations, Ledger for
+precise JSON and keyset pagination, and Cloud for multi-service commands. Pick
+the relevant example rather than copying the whole tree. For Ledger, consult
+the current source contract in `docs/validation.md` and the requested release
+branch; a deployed beta can differ from that contract.
+
+Map each requested command to its method, versioned route, payload, response,
+pagination, and failure behavior. Distinguish missing CLI behavior from an API
+capability absent in the deployed service.
+
+## Implement the plugin
+
+For an embedded service, create or extend `plugins/<service>`. For an external
+service, create a separate module in the product repository and depend on
+`github.com/formancehq/fctl/pkg/pluginsdk`; do not depend on the fctl core module.
+Expose `New(*http.Client) pluginsdk.Plugin`,
+`GetManifest(context.Context)` and `Execute(context.Context, ExecuteRequest)`.
+Metadata must be available with a nil client and without network access.
+
+Normalize every execution with `pluginsdk.NormalizeRequest`, then validate
+identifiers and the service payload before issuing a request. Preserve
+`ChangedFlags` when omitted values and explicit false/empty values differ.
+Return a useful error when execution lacks an injected HTTP client.
+
+Consume the injected client, endpoint and non-secret context. Use the published
+service client when it implements the needed contract, or the public
+`pkg/pluginsdk/httpclient` boundary for missing operations. Keep authentication
+and endpoint selection in the host. Plugin packages depend on public SDK/client
+packages, not Cobra, UI libraries, fctl `internal` packages or server commands.
+
+Preserve `json.RawMessage` or `json.Number` for quantities and identifiers.
+Pass raw IDs to `httpclient.Path`; it escapes each segment once, including a
+slash or literal percent sign. Avoid pre-escaping these inputs. Validate empty
+IDs and dot-segment IDs before building service routes. Keep
+mutation retries explicit; the shared HTTP boundary performs one attempt.
+Return partial response data alongside an error when the API contract requires it.
+
+## Describe the CLI
+
+Declare commands, argument counts, flags and help in the manifest. Use inherited
+`Target` for identity/organization/stack selection, and `Service` overrides for
+different host connection boundaries. Declare destructive operations with
+`Confirm: true` and a boolean `confirm` flag defaulting to false.
+
+For missing-input forms, resource selectors or a payload editor, read
+[declarative inputs](references/inputs.md). Put serializable input metadata on
+runnable leaves; the core renders the UI and validates the accepted values.
+
+For authorized embedded integration, register the factory in the existing
+`cmd/root.go` registry and give its root command the appropriate help group.
+For an isolated evaluation, use a temporary host harness and leave the requested
+checkout unchanged. A new service may also need host
+endpoint, scope and connection configuration support: inspect the current
+resolver rather than assuming a new manifest service is automatically usable.
+Keep these changes at the connection boundary; routes and payloads remain in
+the plugin. Existing service extensions usually need no core changes.
+
+## External executable and distribution
+
+Read `docs/plugin-distribution.md` and the SDK `README.md`. The executable calls
+`transport.Serve(factory)`. Supply the exact service version in its manifest;
+keep plugin revision separate. Use Ledger's executable and publisher as the
+example. Build with the product release, publish public OCI artifacts before
+advertising catalogue entries, and generate manifests from the actual binary.
+The host owns credentials, HTTP callbacks, checksums, target locks and cached
+help. Do not pass tokens in arguments, environment or request context.
+
+Test an actual subprocess through `fctl plugins install` and test a registry
+download through `plugins sync`. Cover version drift before mutations, offline
+help/completion, both explicit flags and forms, and exact JSON responses.
+
+## Verify and deliver
+
+Read [contract and CLI checks](references/verification.md) for the checks that
+apply to the new behavior. A plugin is ready when its API behavior passes local
+fixtures, its manifest registers, a standalone caller runs without core/UI
+dependencies, and the requested CLI path works in interactive and explicit modes.
+
+Use authorized disposable resources for live verification when requested, then
+read back changes and clean up owned fixtures. Report fixture coverage, real
+service results, unsupported backend behavior and unverified paths separately.

.agents/skills/formance-fctl-plugin/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "fctl Plugin Development"
+  short_description: "Create decoupled fctl plugins with forms and tests"
+  default_prompt: "Use $formance-fctl-plugin to add a service plugin to fctl v4 with declarative forms and contract tests."

.agents/skills/formance-fctl-plugin/references/inputs.md

@@ -0,0 +1,97 @@
+# Declarative forms and selectors
+
+Read the checkout's `docs/interaction.md` and the existing service's
+`interaction.go` before choosing fields. `InputSpec` expresses UI intent; it does
+not replace argument, flag or payload validation in direct SDK execution.
+
+## Bindings
+
+Each input binds exactly one of `Flag`, `Argument`, `BodyPointer` or `Context`.
+`Argument` is a zero-based index represented by `*int`; zero must not disappear
+during JSON serialization. `BodyPointer` is an RFC 6901 pointer into the request.
+`Context` is reserved for host organization/stack IDs.
+
+Supported kinds are `input`, `text`, `select` and `confirm`; the value type is
+`string`, `json`, `number` or `bool`. Choose types from the actual service
+contract. A numeric input does not expand the supported `FlagSpec.Type` set.
+Declare every bound flag and keep it consistent with the input's value type.
+`number` checks JSON numeric syntax, not an integer range or sign. Enforce
+integer, nonnegative and size constraints in plugin payload validation according
+to the service contract. Validate exact tokens or `json.Number` with integer
+arithmetic instead of converting through `float64`; preserve the API's allowed
+numeric notation and bounds.
+
+For example, a leaf creating an object can declare:
+
+```go
+pluginsdk.CommandSpec{
+    Use: "create", Short: "Create an item", Runnable: true,
+    Flags: []pluginsdk.FlagSpec{{
+        Name: "data", Type: "string", Body: true, Required: true,
+        Usage: "JSON object, @file or - for stdin",
+    }},
+    Inputs: []pluginsdk.InputSpec{
+        {Title: "Item name", Kind: "input", BodyPointer: "/name",
+            ValueType: "string", Required: true},
+        {Title: "Metadata", Kind: "text", BodyPointer: "/metadata",
+            ValueType: "json", Description: "Optional JSON object"},
+    },
+}
+```
+
+The host reads inline/file/stdin body flags; SDK callers provide `Body` directly.
+An explicit body bypasses JSON-pointer fields. Use `AlternativeArgument` for a
+positional equivalent of a flag/context input. Use `AlternativeFlag` only for a
+real declared alternative, such as `data` bypassing a payload-related flag.
+
+Explicit arguments, flags, JSON fields, environment settings and saved targets
+take precedence. Without explicit body input, missing required values open the
+form. An explicit body bypasses the form even when incomplete: the plugin then
+rejects missing required fields. Complete invocations run directly. Optional
+blank fields stay omitted. Update forms should preserve
+existing options unless the caller explicitly changes or clears them.
+
+## Discover choices
+
+Declare the read operation in the same plugin, then reference it with a full
+`CommandPath`. The host injects a GET-only client for choice discovery.
+For a runnable `show ITEM_ID` leaf with exactly one argument:
+
+```go
+pluginsdk.InputSpec{
+    Title: "Item", Kind: "select", Argument: new(0),
+    ValueType: "string", Required: true,
+    Source: &pluginsdk.ChoiceSource{
+        CommandPath: []string{"inventory", "list"},
+        ValueField: "id", LabelFields: []string{"name", "id"},
+        EmptyMessage: "No items are available; create one first",
+    },
+}
+```
+
+`ValueField` is the identifier passed to execution; labels are display only.
+Source arguments and flags can refer to previously resolved `$arg0`, `$flag`,
+`$organization` or `$stack`. Propagate any required experimental opt-in flag.
+Secret fields use `Secret: true`, kind `input`, a string value type and no
+default. Choice labels must not expose credentials.
+
+Return the service's supported list envelope, such as `data` or `cursor.data`.
+For cursor pagination preserve `hasMore` and `next`. For keyset pagination use
+`AfterField` with the exact final-row identifier and declare the list's
+`page-size` flag as `uint32` and `after` as `string`. Cursor lists need a
+declared string `cursor` flag for subsequent pages. The core enumerates pages and
+deduplicates choices; the plugin still implements the actual pagination API.
+
+`ExcludeTrueFields` hides entries with a true boolean field. `MatchFields` ANDs
+the declared fields and accepts any listed value per field. These filters can
+restrict eligible lifecycle states. Pagination advances from original rows
+before filtering, so an ineligible full page must not terminate discovery.
+`PreferredPrefix` orders suggestions; it does not authorize selecting a fallback.
+
+## Host behavior to preserve
+
+Forms require terminal stdin and stderr and write to stderr; results write to
+stdout. `--no-input`, `FCTL_NO_INPUT` and `CI` disable interaction. The host owns
+cancellation, styles, keyboard navigation and confirmation defaulting to No.
+Use metadata to extend these behaviors instead of adding prompts or output
+calls to service code. `--confirm=false` and cancellation must cause no mutation.

.agents/skills/formance-fctl-plugin/references/verification.md

@@ -0,0 +1,78 @@
+# Verify a plugin independently and through fctl
+
+Use local HTTP fixtures for API behavior before relying on a real stack. Read
+the checkout's test conventions and `justfile`; use its pinned Go/Nix toolchain.
+
+## API and manifest evidence
+
+- Call `GetManifest` with a nil HTTP client and marshal/unmarshal the manifest.
+  Register it through the existing registry tests to catch invalid bindings,
+  command paths, choice sources and inherited flags.
+- Execute each added leaf through the public SDK against `httptest.Server`.
+  Check method, escaped route, query, body and relevant headers. Verify wrong
+  argument counts, unknown flags, invalid payloads and refused confirmations
+  fail before HTTP. Include malformed/error responses relevant to the API.
+- Exercise omitted update options versus explicit false/empty values when
+  supported. Verify `9007199254740993` survives a request and a response exactly
+  when the operation carries quantities, metadata or numeric IDs.
+- Check cancellation and write count for mutations. Add idempotency/partial
+  result checks when those behaviors belong to the service contract.
+
+Use the public API, not implementation-mirroring assertions. A standalone
+consumer can use a temporary module with a local `replace` for
+the public SDK and product plugin modules (or `github.com/formancehq/fctl/v4`
+for an embedded service), then import the plugin and call `New`,
+`GetManifest` and `Execute`. Use `GOWORK=off` so workspace settings do not hide
+dependencies. Inspect its dependency closure for Cobra, pflag, UI and fctl core
+packages; none belongs to the plugin's public execution path. Do not treat the
+host CLI's own dependency closure as the plugin closure.
+
+Registry and Runner integration checks belong in the fctl module, because those
+host packages are `internal`. For an external plugin module, keep its SDK tests
+independent and place host integration tests in fctl or an isolated host checkout.
+The standalone consumer must exercise the public dependency boundary separately.
+
+## Forms and scripting
+
+Use the core's injected `interactive.Runner` in adapter fixtures to cover:
+
+- Missing values bind to the expected argument/flag/body/context without an
+  extra write; cancellation and default-No confirmation perform no mutation.
+- Explicit values and a complete `Body` skip forms, including inline JSON,
+  `@file` and stdin input. Disabled interaction returns an actionable error.
+- Selectors return actual IDs, handle empty lists and use GET-only discovery.
+  If paginated, test a second page and repeated/missing continuations; if filtered,
+  test a full ineligible page followed by an eligible page.
+
+Use a real PTY when adding a new interactive path. Check one complete form,
+resource selection and cancellation at ordinary terminal dimensions. Capture
+stdout separately from stderr and parse `-o json` even with forced color. Check
+human tables with `NO_COLOR`. Runner fixtures cannot verify visual rendering or
+actual keyboard navigation.
+
+## Repository checks and live work
+
+For authorized new plugins or host integration, run the repository checks,
+for example:
+
+```bash
+nix develop --impure --command just pc
+nix develop --impure --command just tests
+```
+
+Inspect changes from formatter/generator recipes before committing. An isolated
+SDK consumer needs its own `go test -race ./...`; the fctl suite does not discover
+tests in an external module automatically. When adding a host service boundary,
+cover Cloud, anonymous and client-credentials modes in connection fixtures.
+
+For a read-only or temporary evaluation, run formatting, race tests, vet and
+dependency checks only in the temporary module or host copy. `just pc` writes
+module, generated, lint-fix and completion files; it belongs in the writable
+integration checkout, not a read-only source checkout. Report this smaller scope.
+
+When live testing is in scope, use the selected sandbox and newly owned fixtures.
+Read back mutations, retain user-owned resources and verify cleanup. Report the
+selected stack version and actual service version separately. Deployed betas
+can lack fields present in a release branch; fixture success proves the client
+contract, while live readback proves deployed behavior. CLI work does not grant
+permission to publish releases, send invitations or modify unrelated resources.

.github/workflows/main.yml

@@ -23,8 +23,6 @@ jobs:
 
   Dirty:
     uses: formancehq/ci/.github/workflows/go-dirty.yml@v1
-    secrets:
-      SPEAKEASY_API_KEY: ${{ secrets.SPEAKEASY_API_KEY }}
 
   Tests:
     uses: formancehq/ci/.github/workflows/go-test.yml@v1
@@ -40,6 +38,5 @@ jobs:
       build-target: release-local
     secrets:
       NUMARY_GITHUB_TOKEN: ${{ secrets.NUMARY_GITHUB_TOKEN }}
-      SPEAKEASY_API_KEY: ${{ secrets.SPEAKEASY_API_KEY }}
       FURY_TOKEN: ${{ secrets.FURY_TOKEN }}
       GORELEASER_KEY: ${{ secrets.GORELEASER_KEY }}

.github/workflows/releases.yml

@@ -14,6 +14,5 @@ jobs:
       attestations: write
     secrets:
       NUMARY_GITHUB_TOKEN: ${{ secrets.NUMARY_GITHUB_TOKEN }}
-      SPEAKEASY_API_KEY: ${{ secrets.SPEAKEASY_API_KEY }}
       FURY_TOKEN: ${{ secrets.FURY_TOKEN }}
       GORELEASER_KEY: ${{ secrets.GORELEASER_KEY }}