Documentation
¶
Overview ¶
Package skills installs and keeps the byted-supabase Claude/agent skill in sync with the running CLI binary. The skill itself is NOT bundled in this repo; it is published to skills.volces.com and installed globally via the external `skills` tool (`npx -y skills add <source> -s <name> -g -y`).
Like the MCP layer, every file here is net-new so it never conflicts on an upstream rebase. The two touchpoints are:
- internal/update calls Sync after a CLI update so the skill tracks the binary version (and installs it on first run).
- cmd/root.go calls Init at startup; on version drift it stores a pending StaleNotice that Execute prints to stderr, mirroring the upgrade hint.
Index ¶
- func CLIName() string
- func Init(currentVersion string)
- func InstallCommand() string
- func Installer() string
- func IsSynced(version string) bool
- func Name() string
- func ReadSyncedVersion() (string, bool)
- func Registry() string
- func SetPending(n *StaleNotice)
- func Source() string
- func WriteState(state State) error
- type CmdResult
- type InstallSpec
- type Runner
- type StaleNotice
- type State
- type SyncOptions
- type SyncResult
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CLIName ¶ added in v0.1.21
func CLIName() string
CLIName returns the binary name users type, branded with the registered distribution when one is installed (else the upstream default). Exported so help text assembled at runtime — after the distribution/agent seams are installed — prints the name the running distribution actually uses.
func Init ¶
func Init(currentVersion string)
Init runs the cheap, local, network-free skill drift check. It compares the version recorded in skills-state.json against the running binary version and, on mismatch, stores a pending StaleNotice for Execute to print. Safe to call once near the end of cmd.Execute.
Skip rules (shouldSkip): CI envs, dev/empty builds, non-release versions, and the BYTED_SUPABASE_CLI_NO_SKILLS_NOTIFIER opt-out. Nothing is emitted on a cold start (no state file yet) — the skill notice is reserved for genuine drift, not "never installed".
func InstallCommand ¶ added in v0.1.21
func InstallCommand() string
InstallCommand returns the user-facing command that (re)installs the skill, branded with the distribution's CLI name when one is registered.
func Installer ¶ added in v0.1.21
func Installer() string
Installer returns the npm package spec of the `skills` CLI to run through npx (e.g. "@example-scope/skills@latest" for a distribution's own channel), with the same precedence as Source/Name: env, then agent seam, then the public default.
func IsSynced ¶
IsSynced reports whether the recorded skill version matches version (both normalized). Used by the update path to avoid re-running npx every time.
func Name ¶
func Name() string
Name returns the skill name to install (`-s <name>`), with the same precedence as Source: env, then agent seam, then upstream default.
func ReadSyncedVersion ¶
ReadSyncedVersion returns the recorded skill version, or false if there is no readable state yet.
func Registry ¶ added in v0.1.21
func Registry() string
Registry returns the npm registry to resolve Installer from (injected as npm_config_registry; empty keeps the user's npm configuration), with the same precedence as Source/Name: env, then agent seam, then the empty default.
func SetPending ¶
func SetPending(n *StaleNotice)
SetPending stores a stale notice; pass nil to clear.
func Source ¶
func Source() string
Source returns the `skills add` source: the env override when set (testing or staging registries), else the registered agent seam's source (downstream distributions ship their own skill), else the upstream default.
func WriteState ¶
WriteState persists the skills state, creating ~/.supabase if needed.
Types ¶
type InstallSpec ¶ added in v0.1.21
type InstallSpec struct {
// Installer is the npm package spec of the `skills` CLI to run through npx.
Installer string
// Registry, when non-empty, pins npm_config_registry for the subprocess so
// Installer resolves from that registry only.
Registry string
// Source and Name are the `skills add <source> -s <name>` arguments.
Source string
Name string
}
InstallSpec bundles what to install and how to fetch the installer.
type Runner ¶
type Runner interface {
Install(ctx context.Context, spec InstallSpec, force bool) *CmdResult
}
Runner installs the skill. The default implementation shells out to npx; tests inject a fake.
type StaleNotice ¶
StaleNotice signals that the locally installed skill version no longer matches the running CLI binary. Current is the last synced version, Target is the running binary version.
func GetPending ¶
func GetPending() *StaleNotice
GetPending returns the pending stale notice, or nil.
func (*StaleNotice) Message ¶
func (n *StaleNotice) Message() string
Message is a single-line, agent-parseable hint pointing at the fix command.
type State ¶
type State struct {
Skill string `json:"skill"`
Source string `json:"source"`
Version string `json:"version"`
UpdatedAt string `json:"updated_at"`
}
State records the last successful skill install so version drift can be detected cheaply (no network) on subsequent CLI runs.
type SyncOptions ¶
type SyncOptions struct {
Version string // CLI version to stamp into state; "" is treated as dev (still installs)
Force bool // pass --force to reinstall even if the skill is current
Runner Runner // nil → default npx runner
Now func() time.Time // nil → time.Now
}
SyncOptions controls a Sync call.
type SyncResult ¶
type SyncResult struct {
Action string // "synced" | "failed"
Skill string
Version string
Err error
Detail string // trailing combined output on failure (for JSON/debug)
}
SyncResult is the outcome of a Sync call.
func Sync ¶
func Sync(ctx context.Context, opts SyncOptions) *SyncResult
Sync installs (or reinstalls) the skill and, on success, records the version in the global state file. It always runs the installer — callers that want to skip a redundant install should gate on IsSynced first.
Source Files