Documentation
¶
Overview ¶
Package managedfile writes and reverts Vulnetix-owned regions of a user's config files without disturbing the rest of the file.
A "managed block" is a run of lines fenced by a Start/End marker comment. The markers are a parameter, not a constant: the Package Firewall and the AI Firewall both write to the same shell rc, and each must be able to remove its own block without touching the other's.
Index ¶
- Constants
- func Block(m Markers, body string) string
- func ClearUserEnv(keys []string)
- func EnvBlock(kind string, m Markers, vars []KV) string
- func Exists(path string) bool
- func GitIgnored(path string) bool
- func GitRoot() (string, error)
- func IsEnvLine(line, key string) bool
- func MaskSecret(s string) string
- func PersistUserEnv(vars []KV) error
- func Remove(existing string, m Markers) (string, bool)
- func RemoveBlockFile(path string, m Markers, dryRun bool) (found bool, err error)
- func RemoveEnvValues(existing string, keys []string) (string, bool)
- func ShellConfigPath() (path, kind string, err error)
- func Upsert(existing, block string, m Markers) string
- func UpsertBlockFile(path, block string, m Markers, dryRun bool) (changed bool, err error)
- func UpsertEnvValues(existing, body string, keys []string) string
- type File
- type KV
- type Markers
- type Mode
- type RemoveOutcome
- type WriteOutcome
Constants ¶
const BackupSuffix = ".vulnetix.bak"
BackupSuffix is appended to a config file's path to hold its pre-write contents. Only whole-file writes (Structured, Merge) create one; a managed block is surgical and is reverted by removing the block, so restoring a backup there would discard unrelated edits the user made after install.
Variables ¶
This section is empty.
Functions ¶
func Block ¶
Block wraps body in the markers and terminates it with a newline, which is the form Upsert expects.
func ClearUserEnv ¶
func ClearUserEnv(keys []string)
ClearUserEnv clears user-scoped environment variables on Windows. Failures are ignored: a variable that was never set is not an error worth surfacing.
func EnvBlock ¶
EnvBlock renders vars as a managed block in the given shell dialect. A value referencing another variable ($FOO) is left unquoted enough to still expand.
func GitIgnored ¶
GitIgnored reports whether path is excluded by the repository's ignore rules. A file that is not ignored must never receive a literal secret.
func GitRoot ¶
GitRoot returns the top level of the repository containing the working directory, or an error when there is none.
func IsEnvLine ¶
IsEnvLine reports whether line assigns key, in any of the assignment forms the files we touch use (.env, .envrc/sh, Makefile, csh, fish).
func PersistUserEnv ¶
PersistUserEnv sets user-scoped environment variables on Windows, where there is no rc file to write. It is a no-op elsewhere.
func Remove ¶
Remove returns existing with the managed block (and its surrounding blank lines) removed. The bool reports whether a block was found.
func RemoveBlockFile ¶
RemoveBlockFile strips the managed block from the file at path. The file is never deleted, even if the block was all it held — a shell rc belongs to the user, not to us.
func RemoveEnvValues ¶
RemoveEnvValues drops every assignment of keys from existing. The bool reports whether anything was removed; an empty result means the file held nothing else.
func ShellConfigPath ¶
ShellConfigPath returns the rc file for the user's login shell and the dialect its assignments must be written in ("fish", "csh", or "sh").
func Upsert ¶
Upsert replaces the existing managed block in existing with block, or appends block if there is none. Content outside the markers is preserved.
func UpsertBlockFile ¶
UpsertBlockFile splices block into the file at path. Unlike UpsertFile it never backs up: a shell rc is only ever edited surgically.
func UpsertEnvValues ¶
UpsertEnvValues drops every assignment of keys from existing and appends body, so the file ends up holding exactly the assignments in body. Used for project env files (.env, .envrc, Makefile) where a managed block would be unidiomatic.
Types ¶
type File ¶
type File struct {
Path string
Content string
Structured bool
// Merge, when set, computes the new file content from the file's existing
// content instead of replacing it, so our keys can be folded into a user's
// real config non-destructively.
Merge func(existing string) (string, error)
// Strip reverses a Merge write when no backup is available: it removes only
// the keys we injected. The bool reports whether anything was removed.
Strip func(path, existing string) (string, bool)
}
File is one config file to write.
type Markers ¶
Markers fence a managed block. Both are whole-line comments in the target file's comment syntax (every format we write — sh, fish, csh, ini, toml, yaml, netrc — uses '#').
type Mode ¶
type Mode int
Mode is how a File's content is written, which is also how it is reverted.
const ( // ModeBlock splices Content into the file between the markers, leaving the // rest of the file alone. The default. ModeBlock Mode = iota // ModeStructured replaces the whole file with Content. For formats where a // partial write is not expressible (XML, JSON documents with a fixed shape). ModeStructured // ModeMerge computes the new content from the existing content, folding our // keys into the user's real config. ModeMerge )
type RemoveOutcome ¶
type RemoveOutcome struct {
Mode Mode
Existed bool // the file was there at all
// Configured is false when the file is absent, or holds no trace of us.
Configured bool
Restored bool // the pre-write backup was put back
Deleted bool // the file was removed (it held nothing but our content)
Stripped bool // our keys/block were removed, the rest of the file kept
}
RemoveOutcome describes what RemoveFile did (or would do under dryRun).
func RemoveFile ¶
RemoveFile reverses an UpsertFile.
It never deletes a file that holds content we did not write: a whole-file mode prefers restoring the backup, falls back to Strip, and only deletes when the file still points at host and there is nothing to restore or strip.
type WriteOutcome ¶
type WriteOutcome struct {
Mode Mode
Changed bool // false means the file already held exactly this content
BackedUp bool // a .vulnetix.bak was written (or would be)
}
WriteOutcome describes what UpsertFile did (or would do under dryRun).
func UpsertFile ¶
func UpsertFile(f File, m Markers, dryRun bool) (WriteOutcome, error)
UpsertFile writes f, preserving everything in the file we do not own.
A whole-file write (Structured or Merge) over an existing file backs that file up first — losing a hand-tuned ~/.m2/settings.xml because we replaced it is not an acceptable failure mode.
Source Files