Documentation
¶
Index ¶
- Constants
- Variables
- func BaseDir() (string, error)
- func CheckAndClean(name string) (bool, error)
- func Delete(name string) error
- func EnsureLogDir() error
- func EnsureTelemetryServerDir(stackName, serverName string) error
- func FindOrphan(port int) (int, bool, error)
- func Home() (string, error)
- func HomeOverridden() bool
- func IsRunning(state *DaemonState) bool
- func KillDaemon(state *DaemonState) error
- func LockPath(name string) (string, error)
- func LogDir() (string, error)
- func LogPath(name string) (string, error)
- func PinsDir() (string, error)
- func PinsPath(name string) (string, error)
- func Save(state *DaemonState) error
- func SkillPinsPath(name string) (string, error)
- func StacksDir() (string, error)
- func StateDir() (string, error)
- func StatePath(name string) (string, error)
- func TelemetryDir() (string, error)
- func TelemetryServerDir(stackName, serverName string) (string, error)
- func TelemetryServerPath(stackName, serverName, signal string) (string, error)
- func VaultDir() (string, error)
- func VerifyPID(pid int) bool
- func WithLock(name string, timeout time.Duration, fn func() error) error
- type DaemonState
Constants ¶
const HomeEnv = "GRIDCTL_HOME"
HomeEnv is the environment variable that replaces the home directory for every gridctl-derived path: the ~/.gridctl state tree and the client projection targets (~/.claude, ~/.gemini, ...) alike. It is a $HOME replacement, not a data-dir override: pointing it at /tmp/demo gives a fully isolated instance whose projections land under /tmp/demo/.claude and never touch the real client directories.
The --home global flag is sugar that sets this variable in-process before any path resolves; the daemon child inherits it through os.Environ(), which is why the env var is the primary mechanism.
Variables ¶
var ErrNewerSchema = errors.New("state file written by a newer gridctl")
ErrNewerSchema marks a state file written by a newer gridctl. Callers must refuse to act on it, and above all must not "clean it up": the file belongs to a daemon this binary cannot represent.
Functions ¶
func BaseDir ¶
BaseDir returns the base gridctl directory (<home>/.gridctl). It errors rather than falling back to a relative path when the home cannot be resolved: every caller below joins onto this value, and a destructive operation aimed at a relative ".gridctl" would target the working directory.
func CheckAndClean ¶
CheckAndClean checks if a state file exists and if the process is running. If the process is dead, it removes the state file and returns true (cleaned). If the process is running, it returns false (not cleaned). If no state file exists, it returns false.
func EnsureLogDir ¶
func EnsureLogDir() error
EnsureLogDir creates the log directory if it doesn't exist.
func EnsureTelemetryServerDir ¶
EnsureTelemetryServerDir creates the per-server telemetry directory with mode 0700, matching the vault/state convention. Any new directories on the path inherit the same restrictive permissions because lumberjack will not chmod them on its own.
func FindOrphan ¶
FindOrphan looks for an orphan gridctl daemon listening on port — a process that owns the port but has no managed state file (because e.g. an earlier shutdown deleted state mid-way, or the daemon was started in a mode that doesn't write state, like 'serve --foreground').
Returns (pid, true, nil) only when all three signals agree:
- The /health endpoint on port responds 200.
- Exactly one process (after excluding our own PID) holds the TCP listen socket for that port.
- That process's executable basename is "gridctl".
Any ambiguity — health probe fails, no listener, multiple listeners after self-exclusion, or executable name mismatch — returns ok=false so the caller falls through to the legacy behavior rather than acting on guesswork.
func Home ¶
Home resolves the directory gridctl treats as the user's home: GRIDCTL_HOME when set (must be absolute), otherwise the OS home. It never falls back to a relative path: a home that cannot be resolved is an error, so downstream destructive operations (gridctl reset --purge does an os.RemoveAll under this path) can never target the working directory by accident.
func HomeOverridden ¶
func HomeOverridden() bool
HomeOverridden reports whether the active home comes from GRIDCTL_HOME rather than the OS home. Commands that mutate state print a one-line stderr disclosure when this is true.
func IsRunning ¶
func IsRunning(state *DaemonState) bool
IsRunning checks if the daemon process is still running.
func KillDaemon ¶
func KillDaemon(state *DaemonState) error
KillDaemon sends SIGTERM to the daemon process, waits up to 5 seconds for graceful shutdown, then sends SIGKILL if the process is still running.
func PinsPath ¶
PinsPath returns the path to the pin file for a stack (<home>/.gridctl/pins/{name}.json).
func Save ¶
func Save(state *DaemonState) error
Save writes a daemon state file, stamping the current schema version and the resolved home the daemon runs under.
func SkillPinsPath ¶
SkillPinsPath returns the path to the skill pin file for a stack (<home>/.gridctl/pins/skills/{name}.json). A subdirectory, not a filename suffix, keeps the namespace disjoint from tool pins: any suffix scheme inside PinsDir would collide with a stack literally named with that suffix (PinsPath("x.skills") == a suffix-based SkillPinsPath("x")). Skill pins track registry documents, not live tool sets, and the two stores version independently.
func TelemetryDir ¶
TelemetryDir returns the root directory for opt-in telemetry persistence (<home>/.gridctl/telemetry). Subtree layout: <stack>/<server>/{logs,metrics,traces}.jsonl.
func TelemetryServerDir ¶
TelemetryServerDir returns the per-server directory under TelemetryDir for the given stack and server.
func TelemetryServerPath ¶
TelemetryServerPath returns the path to a single signal file for a server. signal must be "logs", "metrics", or "traces"; any string is accepted but only those three are produced by the daemon.
Types ¶
type DaemonState ¶
type DaemonState struct {
// SchemaVersion identifies the state-file schema. Absent (0) in
// files written before versioning; treated as version 1 on read.
SchemaVersion int `json:"schema_version,omitempty"`
StackName string `json:"stack_name"`
StackFile string `json:"stack_file"`
PID int `json:"pid"`
Port int `json:"port"`
StartedAt time.Time `json:"started_at"`
// Home is the resolved home directory the daemon was started under
// (see Home()). Subcommands compare it against their own resolved
// home so a GRIDCTL_HOME mismatch surfaces as a named warning
// instead of a confusing empty state.
Home string `json:"home,omitempty"`
// AuthToken and AuthHeader carry the gateway's inbound credentials so
// local subcommands can authenticate against the API they already know
// the port of. Empty when gateway.auth is not configured.
//
// The daemon records the token already resolved, because the config
// loader expands ${VAR} references before the value reaches it. The
// alternative — each subcommand loading the stack and expanding it —
// would turn a `gridctl status` into a vault passphrase prompt.
//
// This does place a resolved secret on disk. The state file is written
// 0600 (see SaveDaemonState), matching the vault's own plaintext
// secrets.json and the machine key in pkg/mcpauth, so it is consistent
// with the existing posture rather than a new exposure.
AuthToken string `json:"auth_token,omitempty"`
AuthHeader string `json:"auth_header,omitempty"`
AuthType string `json:"auth_type,omitempty"`
}
DaemonState represents the state of a running daemon.
Source Files