finfocus-plugin-dev
Implement and maintain a FinFocus cost plugin in a repository scaffolded by `finfocus plugin init`. Use when adding or changing pricing logic in a plugin, adding a resource type, writing the Supports handler, returning GetProjectedCost or GetActualCost results, testing a plugin l
Install
npx skills add https://github.com/rshade/finfocus/tree/main/agent-skills/finfocus-plugin-dev
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install rshade-finfocus@llmmart
git clone https://github.com/rshade/finfocus.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole rshade/finfocus collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
FinFocus Plugin Development
A FinFocus plugin is a standalone binary that serves the CostSourceService
gRPC API from github.com/rshade/finfocus-spec/sdk/go/pluginsdk. The
finfocus CLI launches it, asks Supports, then calls GetProjectedCost (and
optionally GetActualCost, GetRecommendations, and others) per resource.
This repository was scaffolded by finfocus plugin init.
Rules
- Never hand-edit SDK-version state (the
finfocus-specline ingo.mod,SpecVersion, workflow pins). Runfinfocus plugin upgradeand follow thefinfocus-plugin-upgradeskill. - Never fabricate prices. If the plugin cannot price a resource, return
"not supported" from
Supportsor an error fromGetProjectedCost. Do not guess, and do not return a default. The scaffold's example rates incalculateEC2InstanceCostare placeholders: replace them. Scaffolds from finfocus v0.4.0 and earlier also default a missing instance type tot3.microand price unknown types at thet3.microrate; remove both. - Price from real data: a local pricing table with a documented source and
date, or the provider's pricing API. Record the source in
billing_detail. - Do not run
git commitorgit addunless the user asks. SpecVersionmust bev-prefixed (v0.7.2). Usepluginsdk.SpecVersion, as the scaffold does. Older scaffolds wrote a bare literal such as"0.6.1";finfocus plugin upgraderewrites it.- Never write to stdout from the plugin: the SDK prints a single
PORT=<n>handshake line there. Log to stderr or the SDK log writer.
Repo layout (from finfocus plugin init)
| Path | Purpose | Edit? |
|---|---|---|
cmd/plugin/main.go |
Builds pricing.NewCalculator() and calls pluginsdk.Serve; reads --port and FINFOCUS_PLUGIN_PORT; optional health server |
Rarely |
internal/pricing/calculator.go |
Calculator embeds *pluginsdk.BasePlugin; GetPluginInfo, Supports, GetProjectedCost, GetActualCost |
Yes, main work |
internal/pricing/data.go |
PricingData load/save helpers and example data |
Yes, if you use local tables |
internal/client/client.go |
Provider API client stub (GetResourceCost, ValidateCredentials, GetSupportedRegions) |
If you call live APIs |
internal/pricing/calculator_test.go |
Example tests using pluginsdk.NewTestPlugin |
Yes, extend |
manifest.yaml, manifest.json |
Plugin metadata (name, version, providers, capabilities) | Keep in sync |
Makefile |
build, test, lint, install, cover, security |
Rarely |
.golangci-lint.yml |
Lint config used by make lint |
No |
.github/workflows/ |
CI, release, release-please (docker, claude review when generated) | Via upgrade only |
docs/, docker/, issues.md, examples/ |
Generated docs, image, TODO list | As needed |
Binary name is finfocus-plugin-<name>; make build writes it to bin/.
Details on the SDK are in references/sdk-api.md.
Add a resource type end to end
- Find the real input. Run a plan (see Testing loop) and read what the
plugin receives. Core sends the Pulumi type token
(
aws:ec2/instance:Instance),provider,sku,region, and the resource inputs astags. Scaffolds from v0.4.0 and earlier matchaws:ec2:Instance, which core never sends; fix that case. Normalize the token in one function and test it. - Register support. Add the provider or resource type to the matcher in
NewCalculator(base.Matcher().AddProvider,AddResourceType) and extendSupports(see below). - Extract inputs. Read SKU and region from
req.GetResource(); fall back topluginsdk/mappinghelpers (ExtractAWSSKU,ExtractAzureSKU,ExtractGCPSKU, and the*Regionforms) overTags. - Price it. Compute an hourly rate and call
c.Calculator().CreateProjectedCostResponse(currency, hourly, detail), which setsCostPerMonth = hourly * 730. For a monthly price, build the response withpluginsdk.NewGetProjectedCostResponse( pluginsdk.WithProjectedCostDetails(unit, currency, monthly, detail)). - Test. Add a table-driven case for the new type, plus one unsupported and one missing-SKU case.
- Run the real loop (Testing loop) and compare the number with the provider's public price page.
- Update
manifest.yaml/manifest.jsoncapabilities if they changed and the README resource list.
Supports contract
Supports(ctx, *pbc.SupportsRequest) (*pbc.SupportsResponse, error) is the
optional SupportsProvider interface.
- Answer
Supported: falsewith aReasonrather than returning an error. Core treats an RPC error as fail-open (calls the plugin anyway). - A plugin that does not implement
Supportsgets the SDK default (Supported: false,Reason: pluginsdk.DefaultSupportsNotImplementedReason). Core treats that reason as fail-open too, so implementSupportsfor real. - Core sends provider, resource type, SKU, and region, and caches answers per client, provider, type, region, SKU, and feature. A region-bound plugin must decline other regions here so the router can pick another plugin.
- Keep it cheap and offline: no API calls.
Cost response contracts
GetProjectedCostreturnsCurrency,UnitPrice(hourly),CostPerMonth, andBillingDetail. UseBillingDetailto state assumptions (OS, tenancy, defaults applied, price source).- Validate with
pluginsdk.ValidateProjectedCostRequest(needs provider, type, SKU, region). If tags containref.*keys and SKU is empty, core validates withValidateProjectedCostRequestLenient; do the same, then price from theref.<property>.skutags or report what is missing inBillingDetail. $0is a valid priced result and does not trigger fallback to the next plugin; only an error or empty result does. Return$0only when the resource is truly free. Otherwise return an error, so another plugin can try.- Unsupported resource: return
pluginsdk.NotSupportedError(resource). No billing data:pluginsdk.NoDataError(id). - Cache hints: set
ExpiresAtwithpluginsdk.WithProjectedCostExpiresAt. Past timestamps skip caching; core caps TTLs at 7 days. - Optional extras (implement only if you can do them correctly):
GetRecommendations,GetPricingSpec,EstimateCost,BatchCost,DryRun. Seereferences/sdk-api.md.
Testing loop
make test(unit tests, in-process gRPC viapluginsdk.NewTestPlugin).- Conformance:
pluginsdk.RunBasicConformance(plugin)(also Standard and Advanced) in a test; seereferences/testing.md. make installcopies the binary to~/.finfocus/plugins/<name>/<version>/.finfocus plugin listthenfinfocus plugin validate.- Price a real plan:
finfocus cost projected --pulumi-json plan.json(create the plan withpulumi preview --json > plan.json). Add--debugto see plugin calls. make lintbefore finishing.
More in references/testing.md and references/core-contract.md.
Common pitfalls
- Core does not set
PORT. Use--portorFINFOCUS_PLUGIN_PORT; the SDK'sServehandles both and announces the chosen port on stdout. - Pulumi tokens vary (
aws:ec2/instance:Instance); never match on a single hard-coded spelling. - Nested inputs arrive as dotted tag keys (
sku.capacity,rootBlockDevice.0.volumeType) beside the collapsed key. - A mismatch between
PluginVersion,manifest.*version, and the install directory makesplugin listconfusing. Keep them equal. - A
regionkey inplugin.metadata.jsonmakes core look forfinfocus-plugin-<name>-<region>first. Region-per-binary plugins should follow that name. make installmust writeplugin.manifest.jsonas flat JSON whosenameandversionmatch the install directory, orfinfocus plugin validatefails. Scaffolds from v0.4.0 and earlier copymanifest.yamlthere instead; replace that line with the current scaffold'sprintf.
Files (finfocus)
-
references
-
core-contract.md 3.9 KB
Loading… -
sdk-api.md 7 KB
Loading… -
testing.md 2.5 KB
Loading…
-
-
finfocus-plugin-dev.skill 10.8 KB · in bundle
-
SKILL.md 8.7 KB
--- name: finfocus-plugin-dev description: > Implement and maintain a FinFocus cost plugin in a repository scaffolded by `finfocus plugin init`. Use when adding or changing pricing logic in a plugin, adding a resource type, writing the Supports handler, returning GetProjectedCost or GetActualCost results, testing a plugin locally against a Pulumi plan, or installing a plugin build into `~/.finfocus/plugins`. Triggers on: "implement GetProjectedCost", "add a resource type to my plugin", "plugin Supports", "finfocus plugin", "pluginsdk", "finfocus-spec SDK", "test my plugin locally", "plugin pricing logic", "plugin expires_at", or any task inside a FinFocus plugin repo. For SDK version bumps use the finfocus-plugin-upgrade skill instead. --- <!-- Copyright 2025-2026 Richard Shade. Licensed under Apache-2.0. --> <!-- SPDX-License-Identifier: Apache-2.0 --> # FinFocus Plugin Development A FinFocus plugin is a standalone binary that serves the `CostSourceService` gRPC API from `github.com/rshade/finfocus-spec/sdk/go/pluginsdk`. The `finfocus` CLI launches it, asks `Supports`, then calls `GetProjectedCost` (and optionally `GetActualCost`, `GetRecommendations`, and others) per resource. This repository was scaffolded by `finfocus plugin init`. ## Rules - **Never hand-edit SDK-version state** (the `finfocus-spec` line in `go.mod`, `SpecVersion`, workflow pins). Run `finfocus plugin upgrade` and follow the `finfocus-plugin-upgrade` skill. - **Never fabricate prices.** If the plugin cannot price a resource, return "not supported" from `Supports` or an error from `GetProjectedCost`. Do not guess, and do not return a default. The scaffold's example rates in `calculateEC2InstanceCost` are placeholders: replace them. Scaffolds from finfocus v0.4.0 and earlier also default a missing instance type to `t3.micro` and price unknown types at the `t3.micro` rate; remove both. - Price from real data: a local pricing table with a documented source and date, or the provider's pricing API. Record the source in `billing_detail`. - Do not run `git commit` or `git add` unless the user asks. - `SpecVersion` must be `v`-prefixed (`v0.7.2`). Use `pluginsdk.SpecVersion`, as the scaffold does. Older scaffolds wrote a bare literal such as `"0.6.1"`; `finfocus plugin upgrade` rewrites it. - Never write to stdout from the plugin: the SDK prints a single `PORT=<n>` handshake line there. Log to stderr or the SDK log writer. ## Repo layout (from `finfocus plugin init`) | Path | Purpose | Edit? | | --- | --- | --- | | `cmd/plugin/main.go` | Builds `pricing.NewCalculator()` and calls `pluginsdk.Serve`; reads `--port` and `FINFOCUS_PLUGIN_PORT`; optional health server | Rarely | | `internal/pricing/calculator.go` | `Calculator` embeds `*pluginsdk.BasePlugin`; `GetPluginInfo`, `Supports`, `GetProjectedCost`, `GetActualCost` | Yes, main work | | `internal/pricing/data.go` | `PricingData` load/save helpers and example data | Yes, if you use local tables | | `internal/client/client.go` | Provider API client stub (`GetResourceCost`, `ValidateCredentials`, `GetSupportedRegions`) | If you call live APIs | | `internal/pricing/calculator_test.go` | Example tests using `pluginsdk.NewTestPlugin` | Yes, extend | | `manifest.yaml`, `manifest.json` | Plugin metadata (name, version, providers, capabilities) | Keep in sync | | `Makefile` | `build`, `test`, `lint`, `install`, `cover`, `security` | Rarely | | `.golangci-lint.yml` | Lint config used by `make lint` | No | | `.github/workflows/` | CI, release, release-please (docker, claude review when generated) | Via upgrade only | | `docs/`, `docker/`, `issues.md`, `examples/` | Generated docs, image, TODO list | As needed | Binary name is `finfocus-plugin-<name>`; `make build` writes it to `bin/`. Details on the SDK are in `references/sdk-api.md`. ## Add a resource type end to end 1. **Find the real input.** Run a plan (see Testing loop) and read what the plugin receives. Core sends the Pulumi type token (`aws:ec2/instance:Instance`), `provider`, `sku`, `region`, and the resource inputs as `tags`. Scaffolds from v0.4.0 and earlier match `aws:ec2:Instance`, which core never sends; fix that case. Normalize the token in one function and test it. 2. **Register support.** Add the provider or resource type to the matcher in `NewCalculator` (`base.Matcher().AddProvider`, `AddResourceType`) and extend `Supports` (see below). 3. **Extract inputs.** Read SKU and region from `req.GetResource()`; fall back to `pluginsdk/mapping` helpers (`ExtractAWSSKU`, `ExtractAzureSKU`, `ExtractGCPSKU`, and the `*Region` forms) over `Tags`. 4. **Price it.** Compute an hourly rate and call `c.Calculator().CreateProjectedCostResponse(currency, hourly, detail)`, which sets `CostPerMonth = hourly * 730`. For a monthly price, build the response with `pluginsdk.NewGetProjectedCostResponse( pluginsdk.WithProjectedCostDetails(unit, currency, monthly, detail))`. 5. **Test.** Add a table-driven case for the new type, plus one unsupported and one missing-SKU case. 6. **Run the real loop** (Testing loop) and compare the number with the provider's public price page. 7. **Update** `manifest.yaml`/`manifest.json` capabilities if they changed and the README resource list. ## Supports contract `Supports(ctx, *pbc.SupportsRequest) (*pbc.SupportsResponse, error)` is the optional `SupportsProvider` interface. - Answer `Supported: false` with a `Reason` rather than returning an error. Core treats an RPC error as fail-open (calls the plugin anyway). - A plugin that does not implement `Supports` gets the SDK default (`Supported: false`, `Reason: pluginsdk.DefaultSupportsNotImplementedReason`). Core treats that reason as fail-open too, so implement `Supports` for real. - Core sends provider, resource type, SKU, and region, and caches answers per client, provider, type, region, SKU, and feature. A region-bound plugin must decline other regions here so the router can pick another plugin. - Keep it cheap and offline: no API calls. ## Cost response contracts - `GetProjectedCost` returns `Currency`, `UnitPrice` (hourly), `CostPerMonth`, and `BillingDetail`. Use `BillingDetail` to state assumptions (OS, tenancy, defaults applied, price source). - Validate with `pluginsdk.ValidateProjectedCostRequest` (needs provider, type, SKU, region). If tags contain `ref.*` keys and SKU is empty, core validates with `ValidateProjectedCostRequestLenient`; do the same, then price from the `ref.<property>.sku` tags or report what is missing in `BillingDetail`. - `$0` is a valid priced result and does **not** trigger fallback to the next plugin; only an error or empty result does. Return `$0` only when the resource is truly free. Otherwise return an error, so another plugin can try. - Unsupported resource: return `pluginsdk.NotSupportedError(resource)`. No billing data: `pluginsdk.NoDataError(id)`. - Cache hints: set `ExpiresAt` with `pluginsdk.WithProjectedCostExpiresAt`. Past timestamps skip caching; core caps TTLs at 7 days. - Optional extras (implement only if you can do them correctly): `GetRecommendations`, `GetPricingSpec`, `EstimateCost`, `BatchCost`, `DryRun`. See `references/sdk-api.md`. ## Testing loop 1. `make test` (unit tests, in-process gRPC via `pluginsdk.NewTestPlugin`). 2. Conformance: `pluginsdk.RunBasicConformance(plugin)` (also Standard and Advanced) in a test; see `references/testing.md`. 3. `make install` copies the binary to `~/.finfocus/plugins/<name>/<version>/`. 4. `finfocus plugin list` then `finfocus plugin validate`. 5. Price a real plan: `finfocus cost projected --pulumi-json plan.json` (create the plan with `pulumi preview --json > plan.json`). Add `--debug` to see plugin calls. 6. `make lint` before finishing. More in `references/testing.md` and `references/core-contract.md`. ## Common pitfalls - Core does not set `PORT`. Use `--port` or `FINFOCUS_PLUGIN_PORT`; the SDK's `Serve` handles both and announces the chosen port on stdout. - Pulumi tokens vary (`aws:ec2/instance:Instance`); never match on a single hard-coded spelling. - Nested inputs arrive as dotted tag keys (`sku.capacity`, `rootBlockDevice.0.volumeType`) beside the collapsed key. - A mismatch between `PluginVersion`, `manifest.*` version, and the install directory makes `plugin list` confusing. Keep them equal. - A `region` key in `plugin.metadata.json` makes core look for `finfocus-plugin-<name>-<region>` first. Region-per-binary plugins should follow that name. - `make install` must write `plugin.manifest.json` as flat JSON whose `name` and `version` match the install directory, or `finfocus plugin validate` fails. Scaffolds from v0.4.0 and earlier copy `manifest.yaml` there instead; replace that line with the current scaffold's `printf`.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.