cmdutil

Documentation

Index

• func AuditLogPath() string
• func AutoSaveTrackerConfig(parsed *tracker.ParsedURL, configDir string) error
• func DestructiveLogPath() string
• func FormatDestructiveMessage(entry tracker.DestructiveEntry) string
• func InstanceFromFlags(cmd *cobra.Command) *tracker.Instance
• func InstanceFromURL(parsed *tracker.ParsedURL) (*tracker.Instance, bool)
• func LoadAllInstances(dir string) ([]tracker.Instance, error)
• func LoadAllInstancesCtx(ctx context.Context, dir string) ([]tracker.Instance, error)
• func LoadAllInstancesWithResolver(dir string, lookup config.EnvLookup, resolver *vault.Resolver) ([]tracker.Instance, error)
• func LoadNotionIndexInstances(dir string) ([]index.NotionInstance, error)
• func PrintConnectedTrackers(w io.Writer, loader func() ([]tracker.Instance, error))
• func PrintExamples(w io.Writer)
• func PrintJSON(w io.Writer, v any) error
• func ResolveProvider(cmd *cobra.Command, kind string, deps Deps) (tracker.Provider, func(), error)
• func SetupHelp(rootCmd *cobra.Command, loader func() ([]tracker.Instance, error))
• func SplitIDs(ids string) []string
• func TruncateRunes(s string, maxRunes int) string
• func WarnSkippedTrackers(w io.Writer, dir string, loaded []tracker.Instance) bool
• type AutoResult
  • func ResolveAutoProvider(ctx context.Context, cmd *cobra.Command, input string, allowFindFallback bool, ...) (*AutoResult, error)
• type Deps
  • func DefaultDeps() Deps
• type DispatchDestructiveNotifier
  • func (d *DispatchDestructiveNotifier) NotifyDestructive(ctx context.Context, entry tracker.DestructiveEntry)

Functions

func AuditLogPath

func AuditLogPath() string

AuditLogPath returns the path to the audit log file (~/.human/audit.log), creating the directory if needed.

func AutoSaveTrackerConfig

func AutoSaveTrackerConfig(parsed *tracker.ParsedURL, configDir string) error

AutoSaveTrackerConfig ensures the parsed tracker URL is represented in .humanconfig.yaml. If the config file doesn't exist, it creates one. If it exists, it appends the tracker entry if not already present.

func DestructiveLogPath

func DestructiveLogPath() string

DestructiveLogPath returns the path to the destructive operations log file (~/.human/destructive.log), creating the directory if needed.

func FormatDestructiveMessage

func FormatDestructiveMessage(entry tracker.DestructiveEntry) string

FormatDestructiveMessage builds a human-readable notification message from a DestructiveEntry.

func InstanceFromFlags

func InstanceFromFlags(cmd *cobra.Command) *tracker.Instance

InstanceFromFlags builds a tracker instance from root persistent flags, returning nil when insufficient flags are provided.

func InstanceFromURL

func InstanceFromURL(parsed *tracker.ParsedURL) (*tracker.Instance, bool)

InstanceFromURL attempts to build a tracker Instance from a parsed URL using environment variable credentials. Returns (instance, true) if credentials are available and the instance was built. Returns (zero, false) if credentials are missing.

func LoadAllInstances

func LoadAllInstances(dir string) ([]tracker.Instance, error)

LoadAllInstances collects tracker instances from all provider configs. The dir parameter accepts config.DirProject (resolved via the per-request env map in daemon context) or config.DirCwd (".") for direct CLI usage. If a vault section is present in .humanconfig, secret references (e.g. 1pw://) are resolved automatically.

This is the legacy entry point and uses the process environment to resolve config.DirProject. Daemon-served code paths must use LoadAllInstancesCtx with a cobra command context that carries the per-request env map.

func LoadAllInstancesCtx

func LoadAllInstancesCtx(ctx context.Context, dir string) ([]tracker.Instance, error)

LoadAllInstancesCtx is the context-aware variant of LoadAllInstances. The ctx is consulted for env values (HUMAN_PROJECT_DIR) before falling back to the process environment, so daemon-served handlers see only their own request's env map.

func LoadAllInstancesWithResolver

func LoadAllInstancesWithResolver(dir string, lookup config.EnvLookup, resolver *vault.Resolver) ([]tracker.Instance, error)

LoadAllInstancesWithResolver collects tracker instances using a custom env lookup function and vault secret resolver. This enables both per-project token scoping and 1pw:// secret references in .humanconfig.

Daemon callers should pass a concrete dir (not config.DirProject) since they already know the project directory from the per-request routing.

func LoadNotionIndexInstances

func LoadNotionIndexInstances(dir string) ([]index.NotionInstance, error)

LoadNotionIndexInstances loads Notion instances and converts them to index.NotionInstance for use by the indexer.

func PrintConnectedTrackers

func PrintConnectedTrackers(w io.Writer, loader func() ([]tracker.Instance, error))

PrintConnectedTrackers appends a "Connected trackers:" section to the help output. Errors are silently ignored so that help always works.

func PrintExamples

func PrintExamples(w io.Writer)

PrintExamples prints the quick command and provider examples.

func PrintJSON

func PrintJSON(w io.Writer, v any) error

PrintJSON encodes v as indented JSON to w.

func ResolveProvider

func ResolveProvider(cmd *cobra.Command, kind string, deps Deps) (tracker.Provider, func(), error)

ResolveProvider loads instances, applies CLI flag overrides, and resolves the provider for the given kind using the tracker name from persistent flags.

func SetupHelp

func SetupHelp(rootCmd *cobra.Command, loader func() ([]tracker.Instance, error))

SetupHelp overrides the root command's help function to append examples and connected trackers when showing root-level help.

func SplitIDs

func SplitIDs(ids string) []string

SplitIDs splits a comma-separated string into trimmed, non-empty parts.

func TruncateRunes

func TruncateRunes(s string, maxRunes int) string

TruncateRunes limits s to at most maxRunes runes, appending "..." when it had to cut. It counts runes rather than bytes so a multi-byte character is never split mid-encoding (which would emit a replacement glyph).

func WarnSkippedTrackers

func WarnSkippedTrackers(w io.Writer, dir string, loaded []tracker.Instance) bool

WarnSkippedTrackers checks which trackers are configured in .humanconfig but did not produce loaded instances (typically due to missing credentials) and writes diagnostic messages to w. Returns true if any trackers were skipped.

Types

type AutoResult

type AutoResult struct {
	Provider tracker.Provider
	Kind     string
	Key      string // resolved key (= input if key, = extracted key if URL)
	Cleanup  func()
}

AutoResult holds the resolved provider and extracted key from ResolveAutoProvider.

func ResolveAutoProvider

func ResolveAutoProvider(ctx context.Context, cmd *cobra.Command, input string, allowFindFallback bool, deps Deps) (*AutoResult, error)

ResolveAutoProvider loads all instances, applies flag overrides, and resolves the provider without requiring a fixed kind. It uses tracker.Resolve for auto-detection and falls back to FindTracker + ResolveByKind for ambiguous get commands.

When input is a URL, it parses the URL to extract kind, base URL, and key, then tries to match an existing config instance or build one from env vars.

type Deps

type Deps struct {
	LoadInstances       func(dir string) ([]tracker.Instance, error)
	LoadInstancesCtx    func(ctx context.Context, dir string) ([]tracker.Instance, error)
	InstanceFromFlags   func(cmd *cobra.Command) *tracker.Instance
	AuditLogPath        func() string
	DestructiveLogPath  func() string
	DestructiveNotifier func(ctx context.Context) tracker.DestructiveNotifier // returns nil if no notification configured; ctx carries per-request env
}

Deps holds injectable dependencies for command builders that need tracker instance loading and resolution.

LoadInstancesCtx is the preferred entry point: it carries the cobra command context so daemon-served handlers can resolve project paths from per-request env maps without mutating os.Environ. LoadInstances is kept for backwards compatibility with legacy tests and direct CLI callers; resolve.go prefers LoadInstancesCtx when set.

loadDestructiveNotifierCtx is the context-aware variant of DestructiveNotifier — daemon paths set it so per-request notifier configuration is read from the request's env, not the daemon process.

func DefaultDeps

func DefaultDeps() Deps

DefaultDeps returns a Deps using the real implementations.

type DispatchDestructiveNotifier

type DispatchDestructiveNotifier struct {
	Notifier dispatch.Notifier
	ChatID   int64 // Telegram chat ID (0 if not applicable)
}

DispatchDestructiveNotifier adapts dispatch.Notifier to tracker.DestructiveNotifier.

func (*DispatchDestructiveNotifier) NotifyDestructive

func (d *DispatchDestructiveNotifier) NotifyDestructive(ctx context.Context, entry tracker.DestructiveEntry)

NotifyDestructive sends a fire-and-forget notification for a destructive operation.