SuperAPI AI Directory

finfocus-plugin-dev

Coding & development

View repository

Updated 10-28 23:22

About this skill

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.