Documentation
¶
Overview ¶
Package cli provides shared command-line interface utilities for wherehouse commands.
This package contains reusable helpers for CLI command implementations including:
- Database connection management (OpenDatabase)
- Output formatting with lipgloss styling (OutputWriter)
- User identity resolution (GetActorUserID)
- Config and flag context utilities (GetConfig, MustGetConfig)
Index ¶
- func FormatRelativeTime(t time.Time) string
- func GetActorUserID(ctx context.Context) string
- func GetConfig(ctx context.Context) (*config.Config, bool)
- func MustGetConfig(ctx context.Context) *config.Config
- func OpenDatabase(ctx context.Context) (*store.Store, *app.App, error)
- type OutputStyles
- type OutputWriter
- func (w *OutputWriter) Error(msg string)
- func (w *OutputWriter) Info(msg string)
- func (w *OutputWriter) IsJSON() bool
- func (w *OutputWriter) Issue(kind, description string)
- func (w *OutputWriter) JSON(data any) error
- func (w *OutputWriter) KeyValue(key, value string)
- func (w *OutputWriter) Print(msg string)
- func (w *OutputWriter) Println(msg string)
- func (w *OutputWriter) Render(result any, textFn func() string) error
- func (w *OutputWriter) Success(msg string)
- func (w *OutputWriter) Warning(msg string)
- func (w *OutputWriter) Writer() io.Writer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FormatRelativeTime ¶
FormatRelativeTime formats a timestamp as a human-readable relative time string.
func GetActorUserID ¶
GetActorUserID determines the actor user ID from context and config. Falls back to OS username if no config is available.
The function checks the following sources in order:
- Configured default identity (cfg.User.DefaultIdentity)
- Username mapping (cfg.User.OSUsernameMap[osUsername])
- OS username (fallback)
Returns the resolved actor user ID string.
func GetConfig ¶
GetConfig retrieves the Config from the context. Returns the config and true if found, or nil and false if not present.
func MustGetConfig ¶
MustGetConfig retrieves the Config from the context or panics if not found. Use this when the config is guaranteed to be present (e.g., after PersistentPreRunE).
func OpenDatabase ¶
OpenDatabase opens the on-disk SQLite store from the config in ctx and returns both the store (so callers can Close it) and an App wired to it.
Returns an error if:
- Configuration is not found in context
- Database path cannot be resolved
- Database connection or migration fails
Types ¶
type OutputStyles ¶
type OutputStyles struct {
Success lipgloss.Style
Error lipgloss.Style
Warning lipgloss.Style
Info lipgloss.Style
Key lipgloss.Style
Value lipgloss.Style
}
OutputStyles contains lipgloss styles for consistent terminal formatting.
type OutputWriter ¶
type OutputWriter struct {
// contains filtered or unexported fields
}
OutputWriter handles formatted output with styling support. It respects JSON mode and quiet mode flags for consistent output behavior.
func NewOutputWriter ¶
func NewOutputWriter(out, err io.Writer, jsonMode, quietMode bool) *OutputWriter
NewOutputWriter creates an output writer with default lipgloss styles.
Parameters:
- out: Standard output writer (typically cmd.OutOrStdout())
- err: Error output writer (typically cmd.ErrOrStderr())
- jsonMode: If true, output is formatted as JSON
- quietMode: If true, suppress non-essential output
func NewOutputWriterFromConfig ¶
func NewOutputWriterFromConfig(out, err io.Writer, cfg *config.Config) *OutputWriter
NewOutputWriterFromConfig creates an output writer using settings from a Config. Delegates to NewOutputWriter with cfg.IsJSON() and cfg.IsQuiet().
func (*OutputWriter) Error ¶
func (w *OutputWriter) Error(msg string)
Error prints an error message to stderr. Always shown (ignores quiet mode). In JSON mode, outputs {"status":"error","message":"..."}.
func (*OutputWriter) Info ¶
func (w *OutputWriter) Info(msg string)
Info prints an informational message to stdout. Suppressed in quiet mode. Not shown in JSON mode.
func (*OutputWriter) IsJSON ¶ added in v0.5.2
func (w *OutputWriter) IsJSON() bool
IsJSON reports whether the writer is in JSON mode. Commands whose text output is multi-call styled messaging (e.g. Success + KeyValue) dispatch on this to emit a projected JSON shape, rather than funnelling styled text through Render.
func (*OutputWriter) Issue ¶ added in v0.5.0
func (w *OutputWriter) Issue(kind, description string)
Issue prints a typed diagnostic finding as "[kind] description". Always shown regardless of quiet mode; in JSON mode emits {"kind": ..., "description": ...}.
func (*OutputWriter) JSON ¶
func (w *OutputWriter) JSON(data any) error
JSON prints arbitrary JSON data to stdout. Always outputs JSON regardless of mode flags.
func (*OutputWriter) KeyValue ¶
func (w *OutputWriter) KeyValue(key, value string)
KeyValue prints a key-value pair with styled formatting. Suppressed in quiet mode. In JSON mode, outputs {key:value}.
func (*OutputWriter) Print ¶
func (w *OutputWriter) Print(msg string)
Print prints plain text to stdout without styling or newline. Bypasses quiet mode (always prints). Use for scripting-friendly output.
func (*OutputWriter) Println ¶
func (w *OutputWriter) Println(msg string)
Println prints plain text to stdout without styling, with newline. Bypasses quiet mode (always prints). Use for scripting-friendly output.
func (*OutputWriter) Render ¶ added in v0.5.2
func (w *OutputWriter) Render(result any, textFn func() string) error
Render writes a command's primary result, choosing the encoding from the writer's mode: in JSON mode it marshals result; otherwise it writes the string produced by textFn. The text formatter is only invoked in text mode, so callers may build styled output lazily without paying for it under --json.
Render emits in quiet mode as well: quiet suppresses incidental status messages (Success/Info), not the result the user explicitly asked for.
In text mode the string from textFn is written verbatim (via Print, no added newline): the formatter owns all line breaks, so an empty result that returns "" produces no output — matching streaming list/scry output.
func (*OutputWriter) Success ¶
func (w *OutputWriter) Success(msg string)
Success prints a success message to stdout. Suppressed in quiet mode. In JSON mode, outputs {"status":"success","message":"..."}.
func (*OutputWriter) Warning ¶
func (w *OutputWriter) Warning(msg string)
Warning prints a warning message to stderr. Suppressed in quiet mode. In JSON mode, outputs {"status":"warning","message":"..."}.
Source Files