config

Documentation

Overview

Package config loads optional user-level defaults from ~/.config/kpot/config.toml. Every field is optional — a missing file produces a zero-value Config and is not an error.

Precedence rules live in the consuming packages: the editor package treats Editor as a tier between $EDITOR/$VISUAL and the built-in fallbacks (config wins, env beats config in some Unix tools but here config is preferred so a personal preference sticks reliably).

Index

• Constants
• func DefaultPath() (string, error)
• func DefaultVaultDir() (string, error)
• func EnsureVaultDir(vaultPath string) error
• func ExpandHome(p string) (string, error)
• func ResolveVault(arg string, cfg Config) (string, error)
• type Config
  • func Load() (Config, error)
  • func LoadFrom(path string) (Config, error)
  • func (c Config) ClipboardTTL() time.Duration
  • func (c Config) IdleTimeout() time.Duration
  • func (c Config) KeychainMode() string

Constants

const (
	KeychainAuto   = "auto"   // prompt once per vault on first cache miss
	KeychainAlways = "always" // cache silently after every successful open
	KeychainNever  = "never"  // never read or write the keychain
)

Keychain mode controls whether kpot caches the per-vault open key in the OS-native secret store. Empty == KeychainAuto.

const DefaultIdleLockMinutes = 10

DefaultIdleLockMinutes is the fallback when config doesn't set a value. Plan §2.2 specifies 10 minutes.

const StarterTemplate = `` /* 1192-byte string literal not displayed */

StarterTemplate is the comment-rich config.toml that `kpot config init` writes for first-time users. Every key is shown either as a default-matching live value or commented out with an example, so `kpot config show` and the file's contents stay aligned.

Keep this in sync with the Configuration section of README.md and the user-visible defaults in this package — the file is the canonical reference users edit.

Functions

func DefaultPath

func DefaultPath() (string, error)

DefaultPath is ~/.config/kpot/config.toml on Unix, the platform equivalent (via os.UserConfigDir) elsewhere.

func DefaultVaultDir

func DefaultVaultDir() (string, error)

DefaultVaultDir is the fallback location when Config.VaultDir is empty. Picked once and exposed so init / cmd code can both call `os.MkdirAll` on the same path without re-resolving HOME.

func EnsureVaultDir

func EnsureVaultDir(vaultPath string) error

EnsureVaultDir creates the resolved vault parent directory if it doesn't exist AND tightens its permissions to 0o700 if it does. Used by `kpot init <name>` so:

1. The user doesn't get "no such file or directory" the first time they create a vault under the default location.
2. A pre-existing `~/.kpot/` (created with a more permissive mode by another tool, or by a shell rc that ran `mkdir -p` under the default umask) is brought back to owner-only access. `os.MkdirAll` is a no-op for existing dirs and only applies its mode arg to newly created components, so the explicit Chmod is the load-bearing step.

Returns nil for an absolute path that's already inside an existing directory (parent == ".").

func ExpandHome

func ExpandHome(p string) (string, error)

ExpandHome converts a leading `~/` or bare `~` into the user's home directory. Other forms (absolute paths, relative paths, empty) pass through unchanged. Exported so cmd/kpot can normalize CLI args the same way config.toml values are normalized at load time.

func ResolveVault

func ResolveVault(arg string, cfg Config) (string, error)

ResolveVault converts a user-supplied vault designator (or empty for "use default_vault") into a filesystem path kpot should read or write. It does NOT verify the file exists; callers handle that based on context (init wants it absent, open wants it present).

Resolution rules:

1. arg empty + cfg.DefaultVault empty → error (caller prints usage).
2. arg empty: use cfg.DefaultVault as the input and continue below.
3. arg starts with `~/` or is bare `~`: expand to the user's home before any other rule fires. Lets `kpot ~/vaults/work.kpot` work the same way as `vault_dir = "~/..."` in config.
4. arg contains a path separator (`/` or `\`): use as-is. The user gave us a path, don't second-guess.
5. arg ALREADY ends with `.kpot` AND a file by that name exists in the current working directory: use the CWD path. This preserves the historical `cd /repo && kpot vault.kpot` workflow. Bare names without the suffix DO NOT trigger this branch — that would let a malicious repo ship a `personal.kpot` and shadow the user's real vault.
6. Add `.kpot` suffix if missing, then resolve under <effective vault dir>/<candidate>. Default vault dir is ~/.kpot when cfg.VaultDir is empty.

Whitespace around arg is trimmed before any of the above. Returned paths are NOT normalized to absolute — relative paths come back relative when that's what the resolution produced.

Types

type Config

type Config struct {
	// Editor is preferred over $EDITOR / $VISUAL when set. Empty means
	// "fall back to environment variables / built-in candidates".
	Editor string `toml:"editor"`

	// ClipboardClearSeconds overrides the 30-second auto-clear default.
	// Zero means "use the default". Negative is rejected at load time.
	ClipboardClearSeconds int `toml:"clipboard_clear_seconds"`

	// Keychain controls OS-keychain caching of vault open keys.
	// Valid values: "auto" (default), "always", "never". Validated
	// at load time.
	Keychain string `toml:"keychain"`

	// IdleLockMinutes auto-closes a REPL session after N minutes of
	// no command activity. Zero means "use the default" (10 minutes).
	// Negative is rejected at load time. -1 / "off" semantics: set to
	// a very large number if you really want effectively-never.
	IdleLockMinutes int `toml:"idle_lock_minutes"`

	// VaultDir is the directory bare-name vault arguments are resolved
	// against. `kpot personal` → `<VaultDir>/personal.kpot` when no
	// matching file exists in CWD. Empty falls back to ~/.kpot. The
	// `~/` prefix is expanded at load time so callers see an absolute
	// path. Trailing slashes are tolerated.
	VaultDir string `toml:"vault_dir"`

	// DefaultVault is the vault opened when the user runs bare `kpot`
	// with no positional argument. The value goes through the same
	// resolution as a CLI argument: bare names get `.kpot` appended
	// and resolve under VaultDir; absolute / slash-containing values
	// are used as-is. Empty means "no default" — bare `kpot` prints
	// usage as before.
	DefaultVault string `toml:"default_vault"`
}

Config holds the values read from config.toml. New fields must be optional (toml: omitempty implied — an absent key just leaves the zero value in place).

func Load

func Load() (Config, error)

Load reads DefaultPath. A missing file is treated as "no overrides" and returns a zero-value Config with nil error.

func LoadFrom

func LoadFrom(path string) (Config, error)

LoadFrom reads the given path. Missing file → zero-value Config. Used by tests to point at a temp file, and by Load internally.

func (Config) ClipboardTTL

func (c Config) ClipboardTTL() time.Duration

ClipboardTTL returns the configured clipboard auto-clear duration, or 0 if unset (caller should treat 0 as "use the package default").

func (Config) IdleTimeout

func (c Config) IdleTimeout() time.Duration

IdleTimeout returns the configured idle-lock duration. Zero in the config field maps to the default; the caller never sees zero.

func (Config) KeychainMode

func (c Config) KeychainMode() string

KeychainMode normalizes Config.Keychain, defaulting empty to KeychainAuto. Always returns one of the three KeychainXxx constants.