SuperAPI AI Directory

finfocus-plugin-upgrade

Coding & development

View repository

Updated 10-16 08:08

About this skill

FinFocus Plugin Upgrade

Move a plugin project to a newer finfocus-spec version. finfocus plugin upgrade makes the edits that need no judgment. This skill covers the rest, using one migration guide per hop in references/.

A hop ends at a release that needs plugin-author action. Hops are not minor versions: v0.5.7, a patch release, changed a handler signature.

Rules

  • Show the plan and get approval before editing anything.
  • Work on a new branch from a clean tree. Never stash or discard the user's changes yourself; ask them to commit or stash.
  • Change only what a guide or a compile error requires. Do not change pricing math, adopt optional features, reformat files, or edit vendor/.
  • Never delete or skip a failing test to get green. Fix the cause or stop and report it.
  • Do not commit unless the user asks.

1. Plan

Run from the plugin's repository root:

finfocus plugin upgrade --dry-run --output json

If plugin upgrade is an unknown command, finfocus is too old: ask the user to update it. The command never uses the network. The default target is the finfocus-spec version that this finfocus build uses.

Read the JSON:

Field Meaning
plan.current, plan.target Version in go.mod and the version to move to
plan.up_to_date true: stop, there is nothing to do
plan.required_go go directive will be raised to this
plan.hops[] Ordered hops: to, summary, automatic, manual, guide
plan.warnings[] Stale SpecVersion constants, replace directives

Present the current and target versions, each hop's manual steps, and the warnings. Ask whether to proceed, and whether to stop at an earlier hop (--to).

Errors stop the skill:

Error Action
not a FinFocus plugin Wrong directory, or go.mod lacks the spec module
plugin is too old to upgrade Below v0.5.0. Suggest finfocus plugin init and porting the pricing code
plugin is newer than this finfocus build Update finfocus first

2. Branch and apply

git switch -c upgrade-finfocus-spec-<target>
finfocus plugin upgrade            # add --to <version> if the user chose one
go mod tidy

The command refuses a dirty or non-git tree. Pass --allow-dirty only if the user explicitly accepts mixing the upgrade with other changes. It prints the changed files. In go.mod it changes the finfocus-spec requirement and the go line, and it re-renders the file the way go mod edit does. In Go sources it changes only top-level SpecVersion version literals, in files that import finfocus-spec, and always writes them with the v prefix that GetPluginInfo requires.

--to accepts only releases this finfocus build knows: the hop versions and its own. If the user wants a different patch release, bump go.mod by hand.

3. Work through the hops

go.mod now points at the target, so build errors from every hop appear at once. Use the hops to explain them:

  1. For each hop in plan.hops, oldest first, read references/<guide> and do its manual steps.
  2. Run go build ./... && go vet ./... after each hop. Map each remaining error to the guide that explains it.
  3. If an error fits no guide, check the finfocus-spec release notes for versions between current and target. If the fix is still unclear, stop and report it rather than guessing.

4. Verify

go build ./...
go vet ./...
go test ./...

Run the project's own lint target too (make lint or golangci-lint run) if it has one. Then smoke-test against finfocus with a throwaway home:

export FINFOCUS_HOME="$(mktemp -d)"
mkdir -p "$FINFOCUS_HOME/plugins/<name>/0.0.0-upgrade"
go build -o "$FINFOCUS_HOME/plugins/<name>/0.0.0-upgrade/finfocus-plugin-<name>" ./cmd/<entrypoint>
finfocus plugin list --output json

plugin list starts the plugin and asks it for its info. It exits 0 even when the plugin fails, so read the JSON rather than the exit code:

  • specVersion must equal the target. N/A means GetPluginInfo failed.
  • notes must be absent. Failed: … means the plugin did not start.

finfocus plugin validate checks only the binary and manifest on disk. It does not start the plugin, so it is not a smoke test. If the plugin needs credentials to start, report the smoke test as skipped and say why.

5. Report

Report the versions moved between, files changed, manual steps done for each hop, verification results, and anything left open. Leave the branch for review.

References

Guide Hop
to-v0.5.7.md HandleDryRun takes a context
to-v0.6.0.md Batch validation result type, typed validation errors
to-v0.6.1.md Go 1.27.1
to-v0.6.2.md Supports reaches the host; capability checks
to-v0.7.0.md Additive only
to-v0.7.1.md Additive; scorer request id field deprecated
to-v0.7.2.md Additive; manifest validation; provider means the cloud