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(shell, guardDirectory string, known []string) string
- func GitReadOnlyCommand(command string) bool
- func HookCommand(helper, directory string) string
- func HookConfig(helper, directory string) (config, state string, err error)
- func IsTool(name string) bool
- func IsZshStartup(directory string) bool
- func KnownPaths(pathList string) []string
- func Paths(frontendDirectory string) (directory, channel string)
- func Rewrite(script, helper, directory string) (string, error)
- func RewriteForItem(script, helper, directory, item string) (string, error)
- func RunHook(helper, directory string, input io.Reader, output, diagnostics io.Writer) int
- func SVNReadOnlyCommand(command string) bool
- func WorktreeWrites(argv []string) bool
- func WriteZshStartup(directory, setup string) error
- func Writes(argv []string, lookup Lookup) bool
- func ZshPath(entries ...string) string
- 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 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.
const UserZdotdirEnvironment = "MEKUGI_USER_ZDOTDIR"
UserZdotdirEnvironment keeps the ZDOTDIR the session started with, unset when it had none, while ZDOTDIR points at the zsh startup wrappers.
Variables ¶
var Shells = []string{"sh", "bash", "dash", "zsh", "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 or zsh 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. Both shells look 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 HookCommand ¶
func HookConfig ¶
HookConfig uses the native session-layer hook and exact trust identity. It neither changes user files nor grants sandbox permissions.
func IsTool ¶
IsTool identifies a version-control executable independently of whether its invocation needs remote-write approval.
func IsZshStartup ¶
IsZshStartup reports whether directory holds startup files that WriteZshStartup wrote, as an outer session's ZDOTDIR does.
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 RewriteForItem ¶
RewriteForItem retains the host item ID in command-local guard input.
func RunHook ¶
RunHook 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.
func WriteZshStartup ¶
WriteZshStartup writes zsh startup files to directory, which ZDOTDIR then names. Each runs the user's own file of the same name, from the ZDOTDIR the session started with or a later one the user's files set, then sources setup. Setup thus runs after every startup file that may replace PATH, for login and plain `zsh -c` shells alike.
Types ¶
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 {
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