tapper

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 24, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DefaultAppName is the base directory name used for Tapper user
	// configuration. Helpers use this value to build platform specific config
	// paths, for example:
	//   $XDG_CONFIG_HOME/tapper   (or ~/.config/tapper) on Unix-like systems
	//   %APPDATA%\tapper          on Windows
	// Example config file:
	//   $XDG_CONFIG_HOME/tapper/aliases.yaml
	DefaultAppName = "tapper"

	// DefaultLocalConfigDir is the directory name used for repository or
	// project local configuration.
	DefaultLocalConfigDir = ".tapper"
)

Config version strings identify KEG configuration schema versions. Each constant is a stable identifier for a particular config schema. When a new schema is introduced add a new constant and update the Config alias to point to the latest version. These values are used by parsing and migration code (for example ParseConfigData) to detect older formats and perform upgrades. Use a YYYY-MM format for easy sorting and human readability.

Variables

This section is empty.

Functions

func LocalGitData 

func LocalGitData(ctx context.Context, rt *toolkit.Runtime, projectPath, key string) ([]byte, error)

LocalGitData attempts to run `git -C projectPath config --local --get key`.

If git is not present or the command fails it returns an error. The returned bytes are trimmed of surrounding whitespace. The function logs diagnostic messages using the logger from rt.

Types

type BacklinksOptions 

type BacklinksOptions struct {
	KegTargetOptions

	// NodeID is the target node to inspect incoming links for.
	NodeID string

	// Format to use. %i is node id
	// %d is date
	// %t is node title
	// %% for literal %
	Format string

	IdOnly bool

	Reverse bool
}

type CatOptions 

type CatOptions struct {
	// NodeIDs are the node identifiers to read (e.g., "0", "42").
	// Multiple IDs produce concatenated output separated by blank lines.
	NodeIDs []string

	// Tag is an optional tag expression (same syntax as tap tags) used to
	// select nodes. Mutually exclusive with NodeIDs.
	Tag string

	KegTargetOptions

	// Edit opens the node in the editor instead of printing output.
	Edit bool

	// ContentOnly displays content only.
	ContentOnly bool

	// StatsOnly displays stats only.
	StatsOnly bool

	// MetaOnly displays metadata only.
	MetaOnly bool

	// Stream carries stdin piping information when editing.
	Stream *toolkit.Stream
}

CatOptions configures behavior for Runner.Cat.

type Config 

type Config struct {
	// contains filtered or unexported fields
}

Config represents the user's tapper configuration.

Config is a data-only model. We do not preserve YAML comments or original document formatting.

func DefaultProjectConfig 

func DefaultProjectConfig(user, userKegRepo string) *Config

func DefaultUserConfig 

func DefaultUserConfig(name string, userRepos string) *Config

DefaultUserConfig returns a sensible default Config for a new user.

The returned Config is a fully populated in-memory config suitable as a starting point when no on-disk config is available. The DefaultRegistry is set to "knut" and a local file based keg pointing at the user data path is provided under the alias "local".

func MergeConfig 

func MergeConfig(cfgs ...*Config) *Config

MergeConfig merges multiple Config values into a single configuration.

Merge semantics:

  • Later configs override earlier values for the same keys.
  • KegMap entries are appended in order, but entries with the same Keg are overridden by later entries.
  • The returned Config will have a Kegs map and a KegMap slice.

func ParseConfig 

func ParseConfig(raw []byte) (*Config, error)

ParseConfig parses raw YAML into a Config data model.

func ReadConfig 

func ReadConfig(rt *toolkit.Runtime, path string) (*Config, error)

ReadConfig reads the YAML file at path and returns a parsed Config.

When the file does not exist the function returns a Config value and an error that wraps keg.ErrNotExist so callers can detect no-config cases.

func (*Config) AddKeg 

func (cfg *Config) AddKeg(alias string, target kegurl.Target) error

AddKeg adds or updates a keg entry in the Config.

func (*Config) AddKegMap 

func (cfg *Config) AddKegMap(entry KegMapEntry) error

AddKegMap adds or updates a keg map entry in the Config.

func (*Config) Clone 

func (cfg *Config) Clone() *Config

Clone produces a deep copy of the Config.

func (*Config) DefaultKeg 

func (cfg *Config) DefaultKeg() string

DefaultKeg returns the alias of the default keg to use.

func (*Config) DefaultRegistry 

func (cfg *Config) DefaultRegistry() string

DefaultRegistry returns the default registry name.

func (*Config) KegMap 

func (cfg *Config) KegMap() []KegMapEntry

KegMap returns the list of path/regex to keg alias mappings.

func (*Config) Kegs 

func (cfg *Config) Kegs() map[string]kegurl.Target

Kegs returns a map of keg aliases to their targets.

func (*Config) ListKegs 

func (cfg *Config) ListKegs() []string

ListKegs returns a sorted slice of all keg names in the configuration. Returns an empty slice if the config or its data is nil.

func (*Config) LogFile 

func (cfg *Config) LogFile() string

LogFile returns the log file path.

func (*Config) LogLevel 

func (cfg *Config) LogLevel() string

LogLevel returns the log level.

func (*Config) LookupAlias 

func (cfg *Config) LookupAlias(rt *toolkit.Runtime, projectRoot string) string

LookupAlias returns the keg alias matching the given project root path. It first checks regex patterns in KegMap entries, then prefix matches. For multiple prefix matches, the longest matching prefix wins. Returns empty string if no match is found or config data is nil.

func (*Config) Registries 

func (cfg *Config) Registries() []KegRegistry

Registries return the list of configured registries.

func (*Config) ResolveAlias 

func (cfg *Config) ResolveAlias(alias string) (*kegurl.Target, error)

ResolveAlias looks up the keg by alias and returns a parsed Target.

Returns (nil, error) when not found or parse fails.

func (*Config) ResolveDefault 

func (cfg *Config) ResolveDefault(rt *toolkit.Runtime) (*kegurl.Target, error)

func (*Config) ResolveKegMap 

func (cfg *Config) ResolveKegMap(rt *toolkit.Runtime, projectRoot string) (*kegurl.Target, error)

ResolveKegMap chooses the appropriate keg (via alias) based on path.

Precedence rules:

  1. Regex entries in KegMap have the highest precedence.
  2. PathPrefix entries are considered next; when multiple prefixes match the longest prefix wins.
  3. If no entry matches, the DefaultKeg is used if set.

The function expands env vars and tildes prior to comparisons, so stored prefixes and patterns may contain ~ or $VAR values.

func (*Config) SetDefaultKeg 

func (cfg *Config) SetDefaultKeg(keg string) error

SetDefaultKeg sets the default keg alias.

func (*Config) SetDefaultRegistry 

func (cfg *Config) SetDefaultRegistry(_ context.Context, registry string) error

SetDefaultRegistry sets the default registry.

func (*Config) SetLogFile 

func (cfg *Config) SetLogFile(_ context.Context, path string) error

SetLogFile sets the log file path.

func (*Config) SetLogLevel 

func (cfg *Config) SetLogLevel(level string) error

SetLogLevel sets the log level.

func (*Config) SetUserRepoPath 

func (cfg *Config) SetUserRepoPath(path string) error

SetUserRepoPath sets the user repository path.

func (*Config) ToYAML 

func (cfg *Config) ToYAML() ([]byte, error)

ToYAML serializes the Config to YAML bytes.

func (*Config) Touch 

func (cfg *Config) Touch(rt *toolkit.Runtime)

Touch updates the Updated timestamp on the Config using the runtime clock.

func (*Config) Updated 

func (cfg *Config) Updated() time.Time

Updated returns the last update timestamp.

func (*Config) UserRepoPath 

func (cfg *Config) UserRepoPath() string

UserRepoPath returns the path to discover KEGs on the local file system.

func (*Config) Write 

func (cfg *Config) Write(rt *toolkit.Runtime, path string) error

Write writes the Config back to path using atomic replacement.

type ConfigEditOptions 

type ConfigEditOptions struct {
	// Project indicates whether to edit local config instead of user config
	Project bool

	User bool

	ConfigPath string
}

ConfigEditOptions configures behavior for Tap.ConfigEdit.

type ConfigOptions 

type ConfigOptions struct {
	// Project indicates whether to display project config
	Project bool

	// User indicates whether to display user config
	User bool

	// Template prints out a templated. Combine with either project or user
	// flag. Defaults to using --user flag
	Template bool
}

ConfigOptions configures behavior for Tap.Config.

type ConfigService 

type ConfigService struct {
	Runtime *toolkit.Runtime

	PathService *PathService

	// ConfigPath is the path to the config file.
	ConfigPath string
	// contains filtered or unexported fields
}

func NewConfigService 

func NewConfigService(root string, rt *toolkit.Runtime) (*ConfigService, error)

func (*ConfigService) Config 

func (s *ConfigService) Config(cache bool) *Config

Config returns the merged user and project configuration with optional caching. If cache is true and a merged config exists, it returns the cached version. Otherwise, it retrieves both configs, merges them, caches the result, and returns it.

func (*ConfigService) LocalRepoKegs 

func (s *ConfigService) LocalRepoKegs(cache bool) ([]string, error)

func (*ConfigService) ProjectConfig 

func (s *ConfigService) ProjectConfig(cache bool) (*Config, error)

ProjectConfig returns the project-level configuration with optional caching. If cache is true and a cached config exists, it returns the cached version. Otherwise, it reads the config from the local config root and caches the result.

func (*ConfigService) ResetCache 

func (s *ConfigService) ResetCache()

func (*ConfigService) ResolveTarget 

func (s *ConfigService) ResolveTarget(alias string, cache bool) (*kegurl.Target, error)

func (*ConfigService) UserConfig 

func (s *ConfigService) UserConfig(cache bool) (*Config, error)

UserConfig returns the global user configuration

type CreateOptions 

type CreateOptions struct {
	KegTargetOptions

	Title  string
	Lead   string
	Tags   []string
	Attrs  map[string]string
	Stream *toolkit.Stream
}

CreateOptions configures behavior for Runner.Create.

type DirOptions 

type DirOptions struct {
	KegTargetOptions

	NodeID string
}

type EditOptions 

type EditOptions struct {
	// NodeID is the node identifier to edit (e.g., "0", "42")
	NodeID string

	KegTargetOptions

	// Stream carries stdin piping information.
	Stream *toolkit.Stream
}

EditOptions configures behavior for Tap.Edit.

type GrepOptions 

type GrepOptions struct {
	KegTargetOptions

	// Query is the regex pattern used to search nodes.
	Query string

	// Format to use. %i is node id
	// %d is date
	// %t is node title
	// %% for literal %
	Format string

	IdOnly bool

	Reverse bool

	// IgnoreCase enables case-insensitive regex matching.
	IgnoreCase bool
}

type IndexOptions 

type IndexOptions struct {
	KegTargetOptions

	// Rebuild rebuilds the full index
	Rebuild bool

	// NoUpdate skips updating node meta information
	NoUpdate bool
}

IndexOptions configures behavior for Runner.Index.

type InfoEditOptions 

type InfoEditOptions struct {
	KegTargetOptions
	Stream *toolkit.Stream
}

InfoEditOptions configures behavior for Tap.InfoEdit.

type InfoOptions 

type InfoOptions struct {
	KegTargetOptions
}

InfoOptions configures behavior for Tap.Info.

type InitOptions 

type InitOptions struct {
	// Destination selection. Exactly one may be true.
	Project  bool
	User     bool
	Registry bool

	// For project destination: when true, use cwd as the project root base.
	// Otherwise git root is preferred (falling back to cwd).
	Cwd bool

	// Registry-specific options.
	Repo     string // registry name
	UserName string // registry namespace
	TokenEnv string

	// Keg name (user destination)
	Name string

	// Explicit filesystem path for local destinations.
	Path string

	Creator string
	Title   string
	Keg     string
}

InitOptions configures behavior for Runner.InitKeg.

type KegInfoOptions 

type KegInfoOptions struct {
	KegTargetOptions
}

KegInfoOptions configures behavior for Tap.KegInfo.

type KegMapEntry 

type KegMapEntry struct {
	Alias      string `yaml:"alias,omitempty"`
	PathPrefix string `yaml:"pathPrefix,omitempty"`
	PathRegex  string `yaml:"pathRegex,omitempty"`
}

KegMapEntry is an entry mapping a path prefix or regex to a keg alias.

type KegRegistry 

type KegRegistry struct {
	Name     string `yaml:"name,omitempty"`
	Url      string `yaml:"url,omitempty"`
	Token    string `yaml:"token,omitempty"`
	TokenEnv string `yaml:"tokenEnv,omitempty"`
}

KegRegistry describes a named registry configuration entry.

type KegService 

type KegService struct {
	Runtime *toolkit.Runtime

	ConfigService *ConfigService
	// contains filtered or unexported fields
}

func (*KegService) Resolve 

func (s *KegService) Resolve(ctx context.Context, opts ResolveKegOptions) (*keg.Keg, error)

type KegTargetOptions 

type KegTargetOptions struct {
	// Keg is the configured alias.
	Keg string

	// Project resolves using project-local keg discovery.
	Project bool

	// Cwd, when combined with Project, uses cwd as the base instead of git root.
	Cwd bool

	// Path is an explicit local project path used for project keg discovery.
	Path string
}

KegTargetOptions describes how a command should resolve a keg target.

type ListOptions 

type ListOptions struct {
	KegTargetOptions

	// Format to use. %i is node id, %d
	// %i is node id
	// %d is date
	// %t is node title
	// %% for literal %
	Format string

	IdOnly bool

	Reverse bool
}

type MetaOptions 

type MetaOptions struct {
	// NodeID is the node identifier to inspect (e.g., "0", "42")
	NodeID string

	KegTargetOptions

	// Edit opens metadata in the editor.
	Edit bool

	// Stream carries stdin piping information.
	Stream *toolkit.Stream
}

MetaOptions configures behavior for Tap.Meta.

type MoveOptions 

type MoveOptions struct {
	KegTargetOptions

	SourceID string
	DestID   string
}

type PathService 

type PathService struct {
	*appctx.AppPaths
}

func NewPathService 

func NewPathService(rt *toolkit.Runtime, root string) (*PathService, error)

func (*PathService) Project 

func (s *PathService) Project() string

func (*PathService) ProjectConfig 

func (s *PathService) ProjectConfig() string

func (*PathService) UserConfig 

func (s *PathService) UserConfig() string

type ProjectKegNotFoundError 

type ProjectKegNotFoundError struct {
	Tried []string
}

ProjectKegNotFoundError indicates project-local keg discovery failed. Tried contains the concrete keg-file locations that were checked.

func (*ProjectKegNotFoundError) Error 

func (e *ProjectKegNotFoundError) Error() string

type RemoveOptions 

type RemoveOptions struct {
	KegTargetOptions

	NodeIDs []string
}

type ResolveKegOptions 

type ResolveKegOptions struct {
	Root    string
	Keg     string
	Project bool
	Cwd     bool
	Path    string
	NoCache bool
}

type StatsOptions 

type StatsOptions struct {
	// NodeID is the node identifier to inspect (e.g., "0", "42")
	NodeID string

	KegTargetOptions
}

StatsOptions configures behavior for Tap.Stats.

type TagsOptions 

type TagsOptions struct {
	KegTargetOptions

	// Tag filters nodes by tag. When empty, all tags are listed.
	Tag string

	// Format to use. %i is node id
	// %d is date
	// %t is node title
	// %% for literal %
	Format string

	IdOnly bool

	Reverse bool
}

type Tap 

type Tap struct {
	Root string
	// Runtime carries process-level dependencies.
	Runtime *toolkit.Runtime

	PathService   *PathService
	ConfigService *ConfigService
	KegService    *KegService
}

func NewTap 

func NewTap(opts TapOptions) (*Tap, error)
func (t *Tap) Backlinks(ctx context.Context, opts BacklinksOptions) ([]string, error)

func (*Tap) Cat 

func (t *Tap) Cat(ctx context.Context, opts CatOptions) (string, error)

Cat reads and displays node(s) content with metadata as frontmatter.

When multiple node IDs are provided, outputs are concatenated and separated by blank lines. When --tag is provided, nodes are selected by tag expression.

func (*Tap) Config 

func (t *Tap) Config(opts ConfigOptions) (string, error)

Config displays the merged or project configuration.

func (*Tap) ConfigEdit 

func (t *Tap) ConfigEdit(ctx context.Context, opts ConfigEditOptions) error

ConfigEdit opens the configuration file in the default editor.

func (*Tap) Create 

func (t *Tap) Create(ctx context.Context, opts CreateOptions) (keg.NodeId, error)

Create creates a new node in the project's default keg.

It resolves the TapProject (via r.getProject), determines the project's default keg target, constructs a Keg service for that target, and delegates to keg.Keg.Create to allocate and persist the new node.

Errors are wrapped with contextual messages to aid callers.

func (*Tap) Dir 

func (t *Tap) Dir(ctx context.Context, opts DirOptions) (string, error)

func (*Tap) Edit 

func (t *Tap) Edit(ctx context.Context, opts EditOptions) error

Edit opens a node in an editor using a temporary markdown file.

The temp file format is: 

---
<meta yaml>
---
<markdown body>

If stdin is piped, it seeds the temp file content. On save, frontmatter is written to meta.yaml and the body is written to the node content file.

func (*Tap) Grep 

func (t *Tap) Grep(ctx context.Context, opts GrepOptions) ([]string, error)

func (*Tap) Index 

func (t *Tap) Index(ctx context.Context, opts IndexOptions) (string, error)

Index updates indices for a keg (nodes.tsv, tags, links, backlinks). Default behavior is incremental. Set opts.Rebuild to force a full rebuild.

func (*Tap) Info 

func (t *Tap) Info(ctx context.Context, opts InfoOptions) (string, error)

Info displays the keg metadata (keg.yaml file contents).

func (*Tap) InfoEdit 

func (t *Tap) InfoEdit(ctx context.Context, opts InfoEditOptions) error

InfoEdit opens the keg configuration file in the default editor.

func (*Tap) InitKeg 

func (t *Tap) InitKeg(ctx context.Context, name string, options InitOptions) error

InitKeg creates a keg entry for the given name.

If the name is empty, an ErrInvalid-wrapped error is returned. InitKeg gets the project via getProject and then performs the actions required to create a keg. The current implementation defers to project.DefaultKeg for further resolution and returns any error encountered when obtaining the project.

func (*Tap) KegInfo 

func (t *Tap) KegInfo(ctx context.Context, opts KegInfoOptions) (string, error)

KegInfo displays diagnostics for a resolved keg.

func (*Tap) List 

func (t *Tap) List(ctx context.Context, opts ListOptions) ([]string, error)

func (*Tap) ListKegs 

func (t *Tap) ListKegs(cache bool) ([]string, error)

ListKegs returns all available keg directories by scanning the user repository and merging with configured keg aliases. When cache is true, cached config values may be used.

func (*Tap) LookupKeg 

func (t *Tap) LookupKeg(ctx context.Context, kegAlias string) (*keg.Keg, error)

func (*Tap) Meta 

func (t *Tap) Meta(ctx context.Context, opts MetaOptions) (string, error)

Meta reads node metadata, replaces it from stdin, or edits it in a temp file.

func (*Tap) Move 

func (t *Tap) Move(ctx context.Context, opts MoveOptions) error

func (*Tap) Remove 

func (t *Tap) Remove(ctx context.Context, opts RemoveOptions) error

func (*Tap) Stats 

func (t *Tap) Stats(ctx context.Context, opts StatsOptions) (string, error)

Stats reads and displays programmatic node stats.

func (*Tap) Tags 

func (t *Tap) Tags(ctx context.Context, opts TagsOptions) ([]string, error)

type TapOptions 

type TapOptions struct {
	Root       string
	ConfigPath string
	Runtime    *toolkit.Runtime
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.