Documentation
¶
Overview ¶
Package vcsguard decides which version-control invocations publish to a remote, and defines the approval channel between a guarded command and the router. The helper that intercepts these commands and the router that asks the user share this package, so both agree on the wire format.
Write approval covers remote writes only: pushes of any ref or tag to any remote, Subversion commits and repository-side operations, and hosting mutations through gh. Local history edits such as commit, merge or rebase are not remote writes. Commands that cannot be classified fail closed.
Index ¶
- Constants
- Variables
- func ChannelOf(directory string) string
- func DisplayScript(script string, isGuardDirectory func(string) bool) string
- func Functions(guardDirectory string, known, tools []string) string
- func GitReadOnlyCommand(command string) bool
- func HookConfig(helper, directory, sudoDirectory, tracker string) (config, state, identityHash string, err error)
- func IsGuardDirectory(directory string) bool
- func IsTool(name string) bool
- func KnownPaths(pathList string, tools []string) []string
- func Paths(frontendDirectory string) (directory, channel string)
- func Rewrite(script, helper, directory string) (string, error)
- func RewriteCommands(script, helper, directory, sudoDirectory, item string) (string, error)
- func RewriteForItem(script, helper, directory, item string) (string, error)
- func RewriteHook(request HookInput) (any, error)
- func SVNReadOnlyCommand(command string) bool
- func WorktreeWrites(argv []string) bool
- func Writes(argv []string, lookup Lookup) bool
- type HookInput
- type Lookup
- type Message
- type Reply
Constants ¶
const Channel = "vcs-approval.sock"
Channel names the session-local Unix approval socket.
const Directory = "vcs-guard"
Directory names the per-session directory of guarded command names, beside the frontend directory.
const HookEnvironment = "MEKUGI_VCS_GUARD_HOOK"
const HookKey = "/<session-flags>/config.toml:pre_tool_use:0:0"
const HookServer = "mekugi"
const HookTool = "guard_rewrite"
const ItemEnvironment = "MEKUGI_VCS_ITEM"
ItemEnvironment carries the exact host command identity to a PATH guard.
const ItemFlag = "--vcs-item"
ItemFlag carries the same identity through wrappers that clear the environment.
const MaxMessage = 1 << 20
MaxMessage bounds one approval request or reply.
const RealEnvironment = "MEKUGI_VCS_GUARD_REAL"
RealEnvironment names the variable a path function sets for the guard: the absolute path the shell was asked to run. The guard runs that file rather than the next PATH match, and removes the variable before it does.
const Timeout = 5 * time.Minute
Timeout bounds how long a guarded command waits for an answer. A command that receives none is denied.
Variables ¶
var Shells = []string{"sh", "bash", "dash", "ksh"}
var Tools = []string{"git", "gh", "hg", "svn", "jj"}
Tools are the command names the guard intercepts.
Functions ¶
func DisplayScript ¶
DisplayScript removes Rewrite's exact instrumentation from a display copy. The caller identifies session registry directories, including retained ones. It does not read the filesystem or evaluate expansions. Unrecognized source stays intact, including user assignments, quoted text and heredoc bodies.
func Functions ¶
Functions returns Bash code that defines a function for each absolute path to a guarded tool: known, and each guarded name in every absolute PATH entry when the code runs. A command that names such a path runs the guard, which sees the same arguments and runs that file. Bash looks up functions before running a name that contains a slash; a path the shell does not run itself, as through env, exec or command, bypasses its function.
func GitReadOnlyCommand ¶
GitReadOnlyCommand reports built-in readers with no worktree mutation. Options that write output or run a pager need separate caller checks.
func HookConfig ¶
func HookConfig(helper, directory, sudoDirectory, tracker string) (config, state, identityHash string, err error)
HookConfig uses the native session-layer hook and exact trust identity. It neither changes user files nor grants sandbox permissions.
func IsGuardDirectory ¶ added in v0.3.0
IsGuardDirectory recognizes an instrumentation directory name. Callers must separately validate its session registry or exact invocation-local path.
func IsTool ¶
IsTool identifies a version-control executable independently of whether its invocation needs remote-write approval.
func KnownPaths ¶
KnownPaths lists absolute paths of the guarded tools found in pathList and the standard directories, with the files their symlinks resolve to.
func Rewrite ¶
Rewrite instruments executable words, not statements. The selected native shell still expands arguments and owns control flow, redirections and status. Parsing never executes expansions or reads scripts from the filesystem.
func RewriteCommands ¶ added in v0.3.0
RewriteCommands also covers sudo independently of remote-write guarding.
func RewriteForItem ¶
RewriteForItem retains the host item ID in command-local guard input.
func RewriteHook ¶ added in v0.3.0
RewriteHook only instruments the command. Approval occurs in the shell's helper when the command is actually reached, never for an unexecuted branch.
func SVNReadOnlyCommand ¶
SVNReadOnlyCommand identifies Subversion's built-in readers and aliases.
func WorktreeWrites ¶
WorktreeWrites reports whether a VCS invocation may import, discard, or write out repository content. Unknown commands remain possible writers. This is effect attribution, independent of remote-write approval.
Types ¶
type HookInput ¶ added in v0.3.0
type HookInput struct {
Helper string `json:"helper"`
Directory string `json:"directory"`
SudoDirectory string `json:"sudo_directory"`
Tracker string `json:"tracker"`
Event string `json:"hook_event_name"`
Tool string `json:"tool_name"`
Item string `json:"tool_use_id"`
Input struct {
Command *string `json:"command"`
} `json:"tool_input"`
}
HookInput binds session resources in the trusted hook configuration. The remaining fields are expanded from Codex's native hook event, not router cwd.
type Lookup ¶
Lookup resolves a Git alias with the invocation's global options. It reports false when the name is not an alias.
type Message ¶
type Message struct {
Kind string `json:"kind,omitempty"` // sudo command or sudo-password; empty for remote writes.
Thread string `json:"thread,omitempty"`
Item string `json:"item,omitempty"`
Cwd string `json:"cwd,omitempty"`
Argv []string `json:"argv"`
Executable string `json:"executable"` // Resolved tool, separate from its display name.
}
Message asks the router to approve one remote write.
Source Files