notify

Documentation

Index

• func DetectIPCSocket(env EnvironmentSource, opts EnvOpts) string
• func IsRemoteEnvironment(opts EnvOpts) bool
• func IsVSCodeFamily(env EnvironmentSource) bool
• func NotifyNonTTY(hash string, env EnvironmentSource, commitMsg, diffStat string, ...)
• func NotifyOSDialog(data DialogData, opts DialogOpts) error
• func NotifyOSSimple(commitMsg string, opts DialogOpts) error
• func NotifyVSCodeTerminal(hash string, env EnvironmentSource, ipcSocket, lorePath, repoRoot string, ...) error
• func ResolveLoreBinary(opts PathOpts) (string, error)
• func ResolveRepoRoot(opts PathOpts) (string, error)
• type DialogData
• type DialogOpts
• type EnvOpts
• type EnvironmentSource
  • func DetectEnvironment(opts EnvOpts) EnvironmentSource
• type NotificationMode
• type NotifyConfig
  • func DefaultNotifyConfig() NotifyConfig
• type NotifyOpts
• type PathOpts
• type VSCodeOpts

Functions

func DetectIPCSocket

func DetectIPCSocket(env EnvironmentSource, opts EnvOpts) string

DetectIPCSocket finds the IPC socket for the VS Code family instance. Tries fork-specific env vars first, then falls back to VSCODE_IPC_HOOK_CLI. Returns empty string if no live socket is found.

func IsRemoteEnvironment

func IsRemoteEnvironment(opts EnvOpts) bool

IsRemoteEnvironment returns true if running in a remote context where local IPC and display are unavailable.

func IsVSCodeFamily

func IsVSCodeFamily(env EnvironmentSource) bool

IsVSCodeFamily returns true if the environment is VS Code or one of its forks.

func NotifyNonTTY

func NotifyNonTTY(hash string, env EnvironmentSource, commitMsg, diffStat string,
	prefillType, prefillWhat, prefillWhy string, opts NotifyOpts)

NotifyNonTTY is the main entry point called by the hook when a non-TTY environment is detected. It orchestrates the full fallback chain:

VS Code terminal → OS dialog → OS notification → silent

The pending record is already saved before this function is called. This function is best-effort: errors are swallowed, the hook always returns.

func NotifyOSDialog

func NotifyOSDialog(data DialogData, opts DialogOpts) error

NotifyOSDialog launches a Linux GUI dialog (zenity/kdialog/yad) for Lore documentation. Runs as a detached process — does not block the hook.

func NotifyOSSimple

func NotifyOSSimple(commitMsg string, opts DialogOpts) error

NotifyOSSimple sends a simple OS notification (no dialog/form). This is the last-resort notification before silent mode.

func NotifyVSCodeTerminal

func NotifyVSCodeTerminal(hash string, env EnvironmentSource, ipcSocket, lorePath, repoRoot string, opts VSCodeOpts) error

NotifyVSCodeTerminal opens a terminal in the correct VS Code instance and sends a lore pending resolve command.

Uses VSCODE_IPC_HOOK_CLI (inherited by the hook from the parent VS Code process) to target the correct instance even when multiple are open.

This is a best-effort approach: code --command workbench.action.terminal.sendSequence is an undocumented internal API. If any step fails, the caller should fall back to OS dialog notification.

func ResolveLoreBinary

func ResolveLoreBinary(opts PathOpts) (string, error)

ResolveLoreBinary finds the absolute path to the lore binary. Priority: os.Executable() → PATH lookup → known install locations.

func ResolveRepoRoot

func ResolveRepoRoot(opts PathOpts) (string, error)

ResolveRepoRoot finds the absolute path to the git repository root. Uses git rev-parse --show-toplevel, falls back to cwd.

Types

type DialogData

type DialogData struct {
	CommitHash  string
	CommitMsg   string
	DiffStat    string
	LorePath    string
	RepoRoot    string
	PrefillType string // pre-selected doc type (e.g. "bugfix")
	PrefillWhat string // pre-filled What answer
	PrefillWhy  string // pre-filled Why answer (if confidence >= 0.6)
	Branch      string // current branch at commit time (e.g. "feature/auth")
	Scope       string // conventional commit scope (e.g. "auth")

	// I18n labels — populated from i18n.T().Notify by the caller.
	LabelTitle      string // "Lore"
	LabelTitleWhat  string // "Lore — What"
	LabelTitleWhy   string // "Lore — Why"
	LabelType       string // "Type:"
	LabelWhat       string // "What did you change?"
	LabelWhy        string // "Why did you make this change?"
	LabelCancel     string // "Cancel"
	LabelNext       string // "Next"
	LabelSave       string // "Save"
	LabelSkip       string // "Skip"
	LabelOK         string // "OK"
	LabelError      string // "Lore error: "
	LabelErrResolve string // "Failed to resolve pending"

	// IconPath is the absolute path to the Lore logo (PNG) for dialog/notification icons.
	// Resolved at call site; empty means no custom icon.
	IconPath string
}

DialogData holds the pre-filled data for OS dialog questions.

type DialogOpts

type DialogOpts struct {
	// StartCommand launches a detached command. Defaults to defaultStartCommand.
	StartCommand func(name string, args []string, env []string) error

	// LookPath searches for a binary in PATH. Defaults to exec.LookPath.
	// Used on Linux to detect zenity/kdialog/yad.
	LookPath func(file string) (string, error)
}

DialogOpts holds injectable dependencies for OS dialog notification.

type EnvOpts

type EnvOpts struct {
	// GetEnv reads an environment variable. Defaults to os.Getenv.
	GetEnv func(string) string

	// IsTTY reports whether the current environment is an interactive TTY.
	// When nil, defaults to false (caller should check TTY separately).
	IsTTY func() bool

	// DialTimeout tests socket connectivity. Defaults to net.DialTimeout.
	DialTimeout func(network, address string, timeout time.Duration) (net.Conn, error)
}

EnvOpts holds injectable dependencies for environment detection (testability).

type EnvironmentSource

type EnvironmentSource = string

EnvironmentSource identifies the IDE or context that launched the git commit.

const (
	EnvTerminal  EnvironmentSource = "terminal"
	EnvVSCode    EnvironmentSource = "vscode"
	EnvCursor    EnvironmentSource = "cursor"
	EnvWindsurf  EnvironmentSource = "windsurf"
	EnvCodium    EnvironmentSource = "codium"
	EnvJetBrains EnvironmentSource = "jetbrains"
	EnvNeovim    EnvironmentSource = "neovim"
	EnvVim       EnvironmentSource = "vim"
	EnvEmacs     EnvironmentSource = "emacs"
	EnvCI        EnvironmentSource = "ci"
	EnvGitGUI    EnvironmentSource = "git-gui"
	EnvUnknown   EnvironmentSource = "unknown"
)

func DetectEnvironment

func DetectEnvironment(opts EnvOpts) EnvironmentSource

DetectEnvironment identifies the IDE or context that launched the git process. Detection order (first match wins):

1. CI (priority absolute — never notify in CI)
2. Emacs (INSIDE_EMACS is reliable)
3. Neovim (NVIM env var)
4. Vim (VIM without NVIM)
5. VS Code family (distinguish forks via GIT_ASKPASS path)
6. JetBrains (IDEA_INITIAL_DIRECTORY or JediTerm)
7. TTY interactive → terminal
8. Unknown non-TTY

type NotificationMode

type NotificationMode = string

NotificationMode controls notification behavior.

const (
	ModeAuto     NotificationMode = "auto"
	ModeTerminal NotificationMode = "terminal"
	ModeDialog   NotificationMode = "dialog"
	ModeNotify   NotificationMode = "notify"
	ModeSilent   NotificationMode = "silent"
)

type NotifyConfig

type NotifyConfig struct {
	Mode         NotificationMode // auto, terminal, dialog, notify, silent
	DisabledEnvs []string         // environments to skip notification
}

NotifyConfig holds user configuration for notification behavior.

func DefaultNotifyConfig

func DefaultNotifyConfig() NotifyConfig

DefaultNotifyConfig returns sensible defaults.

type NotifyOpts

type NotifyOpts struct {
	EnvOpts    EnvOpts
	PathOpts   PathOpts
	VSCodeOpts VSCodeOpts
	DialogOpts DialogOpts
	Config     NotifyConfig

	// I18nLabels populates i18n labels on DialogData.
	// When nil, English fallback labels are used inside the dialog builders.
	I18nLabels func(data *DialogData)
}

NotifyOpts holds all dependencies for the main notification orchestrator.

type PathOpts

type PathOpts struct {
	// Executable returns the path of the current binary. Defaults to os.Executable.
	Executable func() (string, error)

	// LookPath searches for a binary in PATH. Defaults to exec.LookPath.
	LookPath func(file string) (string, error)

	// GitCommand runs a git command and returns its output. Defaults to exec.Command("git", ...).Output().
	GitCommand func(args ...string) (string, error)

	// Getwd returns the current working directory. Defaults to os.Getwd.
	Getwd func() (string, error)

	// Home returns the user's home directory. Defaults to os.UserHomeDir.
	Home func() (string, error)
}

PathOpts holds injectable dependencies for path resolution (testability).

type VSCodeOpts

type VSCodeOpts struct {
	// LookPath searches for a binary in PATH. Defaults to exec.LookPath.
	LookPath func(file string) (string, error)

	// RunCommand executes a command synchronously. Defaults to cmd.Run().
	RunCommand func(name string, args []string, env []string) error

	// StartCommand launches a detached command. Defaults to cmd.Start().
	StartCommand func(name string, args []string, env []string) error

	// Sleep pauses execution. Defaults to time.Sleep.
	Sleep func(d time.Duration)
}

VSCodeOpts holds injectable dependencies for VS Code terminal notification.