feat(pkg/plan): complete public plan library per RFD 0053

[Copilot]

• Rewrite pkg/plan/plan_test.go for readability
• Fix bug in TestChecksum: determinism assertion compared Checksum(input) against itself (always true); capture results in two variables instead

Original prompt

Context

PR #2 (0264_public_plan_library branch) introduces a new pkg/plan package in salasberryfin/rancher as a public plan library for the system-agent, as described in RFD 0053. The current PR only adds two files: pkg/plan/go.mod and pkg/plan/types.go.

Goal

Improve the existing pkg/plan package based on a review against RFD 0053 and the source of truth in rancher/system-agent. Do not make any changes to system-agent itself — that is handled in a follow-up.

Required Changes

1. Fix pkg/plan/go.mod

The current go.mod specifies go 1.25.0 which does not exist. Fix it to use a valid Go version that matches the rancher/rancher repository (use go 1.23 or whatever is used in the root go.mod of rancher/rancher). Remove the toolchain directive if it references a non-existent version.

2. File structure: split types.go into focused files

The single types.go is acceptable but splitting it into focused files improves navigability for external consumers. Suggested structure:

• pkg/plan/types.go — core plan types: Plan, File, CommonInstruction, OneTimeInstruction, PeriodicInstruction, PeriodicInstructionOutput
• pkg/plan/probe.go — probe types: Probe, HTTPGetAction, ProbeStatus
• pkg/plan/state.go — plan state type, constants, and Secret field name constants
• pkg/plan/plan.go — helper functions: Parse, Checksum

Only do the split if it genuinely improves the package. If it adds complexity without benefit, keep everything in types.go plus add the new files for state constants and helpers.

3. Add pkg/plan/state.go

Add a new file defining the plan lifecycle state type and all constants that external consumers need. These are currently missing from the library entirely:

package plan

// PlanState represents the lifecycle state of a plan execution.
type PlanState string

const (
    PlanStatePending    PlanState = "pending"
    PlanStateInProgress PlanState = "in-progress"
    PlanStateSucceeded  PlanState = "succeeded"
    PlanStateFailed     PlanState = "failed"
    PlanStateCancelled  PlanState = "cancelled"
)

// Secret data field keys written by the agent or orchestrator.
const (
    // SecretPlanStateKey is set by the orchestrator to "pending" and transitioned by the agent.
    SecretPlanStateKey = "plan-state"
    // SecretPlanRevisionKey is a monotonically increasing counter incremented each time a new plan version is loaded.
    SecretPlanRevisionKey = "plan-revision"
    // SecretAppliedOutputKey holds the gzip+base64 encoded output from one-time instructions.
    SecretAppliedOutputKey = "applied-output"
    // SecretAppliedPeriodicOutputKey holds the gzip+base64 encoded output from periodic instructions.
    SecretAppliedPeriodicOutputKey = "applied-periodic-output"
    // SecretProbeStatusesKey holds the current probe health statuses.
    SecretProbeStatusesKey = "probe-statuses"
    // SecretFailureCountKey tracks consecutive failures.
    SecretFailureCountKey = "failure-count"
    // SecretAppliedChecksumKey is used for backward compatibility with orchestrators that do not yet set plan-state.
    SecretAppliedChecksumKey = "applied-checksum"
)

// Annotation and type constants for plan Secrets.
const (
    // SecretTypeMachinePlan is the Kubernetes Secret type for plan Secrets.
    SecretTypeMachinePlan = "rke.cattle.io/machine-plan"
    // AnnotationCancelled when set to "true" on the plan Secret triggers cancellation.
    AnnotationCancelled = "plan.cattle.io/cancelled"
    // AnnotationCancelledValue is the value that triggers cancellation.
    AnnotationCancelledValue = "true"
)

4. Add PeriodicInstructionOutput to the types

This type is part of the public contract (consumers need it to decode applied-periodic-output). It currently lives only in rancher/system-agent/pkg/applyinator. Add it to pkg/plan/types.go (or a dedicated file):

// PeriodicInstructionOutput holds the result of a periodic instruction execution.
// The Stdout and Stderr fields are gzip+base64 encoded byte slices.
type PeriodicInstructionOutput struct {
    Name                  string `json:"name"`
    Stdout                []byte `json:"stdout"`
    Stderr                []byte `json:"stderr"`
    ExitCode              int    `json:"exitCode"`
    // LastSuccessfulRunTime is a time.UnixDate formatted string of the last successful run.
    LastSuccessfulRunTime string `json:"lastSuccessfulRunTime"`
    // Failures is the number of consecutive times this instruction has failed.
    Failures              int    `json:"failures"`
    // LastFailedRunTime is a time.UnixDate formatted string of when the instruction started failing.
    LastFailedRunTime     string `json:"lastFailedRunTime"`
}

5. Add pkg/plan/plan.go with Parse and Checksum helpers

The RFD specifies the library should provide JSON parsing with validation and content hash computation. Add:

package plan

import (
    "c...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>