tapper

type AuthEntry struct {
	AccessToken string    `yaml:"access_token"`
	TokenType   string    `yaml:"token_type,omitempty"`
	ExpiresAt   time.Time `yaml:"expires_at,omitempty"`
	Scope       string    `yaml:"scope,omitempty"`
}

type AuthLoginDeviceOptions struct {
	// HubURL is the hub base (e.g. "https://hub.example.com"). Required.
	HubURL string

	// ClientID is the OAuth2 public client identifier the hub will validate
	// against its registered clients. Required.
	ClientID string

	// Scope is an optional space-separated scope string. Omitted from the
	// device_authorization request when empty.
	Scope string

	// Timeout bounds the whole flow including the user's browser action;
	// zero uses defaultDeviceTimeout.
	Timeout time.Duration

	// HTTPClient executes the metadata GET, device_authorization POST, and
	// token POSTs. Default: http.DefaultClient.
	HTTPClient *http.Client

	// PromptOut is the writer that receives the user-facing prompt
	// ("Open <URL> and enter <CODE>"). Default: os.Stderr via the runtime
	// stream when Out is nil; an in-memory buffer in tests.
	PromptOut io.Writer

	// Now returns the current time. Default: time.Now. Tests inject a fake
	// clock to control timeout behavior deterministically.
	Now func() time.Time

	// Sleep blocks for d. Default: time.Sleep. Tests inject a no-op or
	// channel-coordinated stub so polling loops don't actually wait.
	Sleep func(d time.Duration)
}

type AuthLoginOptions struct {
	// HubURL is the hub base (e.g. "https://hub.example.com"). Required.
	// Trailing slashes are stripped; http/https schemes are enforced.
	HubURL string

	// ClientID is the OAuth2 client identifier to send to the hub. Required.
	ClientID string

	// Scope is an optional space-separated scope string. Omitted from
	// the authorize request when empty.
	Scope string

	// Timeout bounds the whole handshake; zero uses defaultAuthTimeout.
	Timeout time.Duration

	// ListenerFactory returns the loopback listener that receives the
	// /callback request. Default: net.Listen("tcp", "127.0.0.1:0").
	// Injection lets tests pin a specific address or inspect the listener.
	ListenerFactory func() (net.Listener, error)

	// BrowserOpener opens authURL in the user's browser. Default:
	// openBrowser (platform-specific exec). Tests substitute a goroutine
	// that drives authURL via http.Get.
	BrowserOpener func(ctx context.Context, rt *toolkit.Runtime, url string) error

	// HTTPClient executes the metadata GET and token POST. Default: http.DefaultClient.
	HTTPClient *http.Client

	// RandReader is the entropy source for verifier + state. Default:
	// crypto/rand.Reader. Never swap this for math/rand in production.
	RandReader io.Reader
}

type AuthLogoutOptions struct {
	// Hub is the raw or canonical hub URL. When empty and exactly one
	// hub is stored, auto-resolves to that single entry; otherwise an
	// empty Hub with multiple stored hubs surfaces a directed error.
	Hub string
}

type AuthLogoutResult struct {
	// Removed is true when an entry was actually deleted from the store.
	// False when the store was empty or the hub was not found; both of
	// those cases are soft-successes (no error returned).
	Removed bool
	// HubURL is the canonical hub that was targeted, or "" when the
	// store was empty.
	HubURL string
	// Formatted is the authoritative output line terminated with \n.
	// CLI routes to stdout when Removed=true, stderr otherwise.
	Formatted string
}

type AuthStatusOptions struct {
	// Hub is a raw or canonical hub URL. When empty and exactly one
	// hub is stored, AuthStatus auto-resolves to that single entry;
	// otherwise an empty Hub with zero or multiple stored hubs surfaces
	// a directed error/empty message (see AuthStatus docs).
	Hub string
}

type AuthStatusResult struct {
	// Present is false when no matching entry exists (empty store
	// with no --hub, or --hub that isn't in the store).
	Present bool

	// HubURL is the canonical key that matched. Zero-value when the
	// caller omitted --hub and the store is empty.
	HubURL string

	// TokenSuffix is the last 4 chars of the access token, prefixed
	// with "..." — or "[set]" when the token is shorter than 4 chars.
	// The raw token is never exposed here.
	TokenSuffix string

	// TokenType mirrors the stored entry (e.g. "Bearer"). Empty when
	// the hub returned a bare token with no type.
	TokenType string

	// Scope mirrors the stored entry. Empty when no scope was granted.
	Scope string

	// ExpiresAt mirrors the stored entry; zero when no expiry is known.
	ExpiresAt time.Time

	// ExpiryStatus is a three-way tag: "unknown" | "valid" | "expired".
	// Made explicit so callers (and future JSON consumers) don't have
	// to re-derive from ExpiresAt vs clock.
	ExpiryStatus string

	// Formatted is the exact string the CLI prints; MCP returns it
	// verbatim as text content. Terminated with a trailing newline.
	Formatted string
}

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

type BacklinksOptions struct {
	KegTargetOptions

	// NodeIDs are the target nodes to inspect incoming links for.
	// Results from all node IDs are merged and deduplicated.
	NodeIDs []string

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

	IdOnly bool

	Reverse bool

	// Limit caps the number of results returned. 0 means no limit.
	Limit int

	// Offset skips the first N results before applying limit. Must be >= 0.
	Offset int
}

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

	// LockToken is an optional cross-process lock token for edit operations.
	LockToken string
}

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

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

	User bool

	ConfigPath string

	Stream *toolkit.Stream
}

type ConfigExplainOptions struct {
	// Field limits the result to a single field. Empty means all fields.
	Field string
}

type ConfigExplainResult struct {
	Field  string // field name (e.g. "defaultKeg")
	Value  string // resolved value in the merged config
	Source string // which provider set this value ("user config", "project config", "env vars", "default")
}

type ConfigLoadWarning struct {
	Source  string // "user config" or "project config"
	Path    string // file path that caused the issue
	Message string // human-readable description
	Err     error  // underlying error
}

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

	// User indicates whether to display user config
	User bool

	// ConfigPath directly selects a config file to display.
	ConfigPath string
}

type ConfigService struct {
	Runtime *toolkit.Runtime

	PathService *PathService

	// ConfigPath is the path to the config file.
	ConfigPath string

	// LoadWarnings accumulates non-fatal issues from the last Config() call.
	// Missing config files are not warnings (graceful degradation). Corrupt
	// YAML, permission errors, etc. are recorded here.
	LoadWarnings []ConfigLoadWarning

	// ResolvedSources lists provider names that contributed to the merged config,
	// most-specific first. Populated after Config() runs the cascade.
	ResolvedSources []string
	// contains filtered or unexported fields
}

type ConfigTemplateOptions struct {
	Project bool
}

type ConfigWarning struct {
	Field   string // config field name (e.g., "kegMap[0]", "logLevel")
	Message string // human-readable description
}

type CreateOptions struct {
	KegTargetOptions

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

type DeleteFileOptions struct {
	KegTargetOptions
	NodeID string
	Name   string
}

type DeleteImageOptions struct {
	KegTargetOptions
	NodeID string
	Name   string
}

type DirOptions struct {
	KegTargetOptions

	NodeID string
}

type DoctorOptions struct {
	KegTargetOptions
}

type DownloadFileOptions struct {
	KegTargetOptions
	NodeID string
	Name   string
	Dest   string
}

type DownloadImageOptions struct {
	KegTargetOptions
	NodeID string
	Name   string
	Dest   string
}

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

	KegTargetOptions

	// LockToken is an optional cross-process lock token. When provided, the
	// command validates it against any held lock before proceeding.
	LockToken string

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

type ExportOptions struct {
	KegTargetOptions
	NodeIDs     []string
	WithHistory bool
	OutputPath  string
}

type ForceUnlockOptions struct {
	NodeID string
	KegTargetOptions
}

type GraphOptions struct {
	KegTargetOptions

	// BundleJS is the compiled browser renderer injected into the generated page.
	BundleJS []byte
}

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

	// MaxLines caps the number of matched lines returned per node.
	// 0 means unlimited. When > 0, only the first MaxLines matching lines
	// are included per node.
	MaxLines int

	// Limit caps the number of results returned. 0 means no limit.
	Limit int

	// Offset skips the first N results before applying limit. Must be >= 0.
	Offset int
}

type ImportFromKegOptions struct {
	// Source is the source keg to copy nodes from.
	Source KegTargetOptions
	// Target is the destination keg; defaults to the resolved default keg.
	Target KegTargetOptions
	// NodeIDs lists the source node IDs to import. Values may be bare integers
	// ("5") or cross-keg references ("keg:pub/5"). All must resolve to Source.
	// When empty and TagQuery is also empty, all non-zero nodes are imported.
	NodeIDs []string
	// TagQuery is a boolean tag expression (same syntax as tap tags EXPR) that
	// selects additional source nodes; combined with NodeIDs as a union.
	TagQuery string
	// LeaveStubs writes a forwarding stub at each source node location after import.
	LeaveStubs bool
	// SkipZeroNode skips the source keg's node 0 (the index/root node).
	SkipZeroNode bool
}

type ImportOptions struct {
	KegTargetOptions
	Input string
}

type ImportedNode struct {
	SourceID keg.NodeId
	TargetID keg.NodeId
}

type IndexCatOptions struct {
	KegTargetOptions

	// Name is the index file name to dump, e.g. "changes.md" or "nodes.tsv".
	// A leading "dex/" prefix is stripped automatically.
	Name string
}

type IndexOptions struct {
	KegTargetOptions

	// NoUpdate skips updating node meta information
	NoUpdate bool
}

type InfoOptions struct {
	KegTargetOptions

	// Minimal strips large sections (tags, entities, indexes) from the output,
	// returning only core config fields. Useful for MCP tools where response
	// size must stay small.
	Minimal bool
}

type InitOptions struct {
	// Destination selection. Exactly one group may be set.
	Project bool
	User    bool
	Cwd     bool   // use cwd as the project root base instead of git root
	Path    string // explicit filesystem path; implies local destination
	Hub     string // non-empty selects hub destination; value is the hub name

	// Hub-specific options.
	UserName string // hub namespace
	TokenEnv string

	Creator string
	Title   string
	Keg     string
}

type IntegrateOptions struct {
	KegTargetOptions

	// Host selects which rendered tree to install. Must name a
	// registered adapter that also has an orient artifact (see
	// OrientableHosts).
	Host string

	// DryRun, when true, causes Integrate to return the target paths
	// it would write without actually writing any files.
	DryRun bool

	// Target overrides the default install directory for Host. When
	// empty, the per-host default under the user's home directory is
	// used (see defaultIntegrateTarget).
	Target string
}

type Issue struct {
	Level   string // "error" or "warning"
	Kind    string // category: "tag-missing", "entity-missing", "broken-link", etc.
	NodeID  string // "" for keg-level issues
	Message string
}

type KegConfigEditOptions struct {
	KegTargetOptions
	Stream *toolkit.Stream
}

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

type KegInfoOptions struct {
	KegTargetOptions
}

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

type KegService struct {
	// Runtime provides filesystem and environment access used to resolve kegs.
	Runtime *toolkit.Runtime

	// ConfigService resolves configured keg aliases and targets.
	ConfigService *ConfigService
	// contains filtered or unexported fields
}

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

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

	// Cwd resolves project keg at the current working directory instead of git root.
	// Works standalone or combined with Project.
	Cwd bool

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

	// Flight is a cross-keg work-scope identifier. It is mutually
	// exclusive with Keg, Project, Cwd, and Path at the CLI: a flight
	// names a manifest that spans kegs, while the other fields pin
	// resolution to a single keg. Today only Tap.Orient consults it;
	// other surfaces hold the slot for future manifest-aware commands.
	Flight string
}

type LinksOptions struct {
	KegTargetOptions

	// NodeIDs are the source nodes to inspect outgoing links for.
	// Results from all node IDs are merged and deduplicated.
	NodeIDs []string

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

	IdOnly bool

	Reverse bool

	// Limit caps the number of results returned. 0 means no limit.
	Limit int

	// Offset skips the first N results before applying limit. Must be >= 0.
	Offset int
}

type ListFilesOptions struct {
	KegTargetOptions
	NodeID string
}

type ListImagesOptions struct {
	KegTargetOptions
	NodeID string
}

type ListOptions struct {
	KegTargetOptions

	// Query is an optional boolean expression that filters nodes. Supports both
	// plain tag names ("golang") and key=value attribute predicates
	// ("entity=plan"). When empty, all nodes are listed.
	Query string

	// 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

	// Sort selects the sort order. Empty string means sort by node ID (default).
	Sort ListSortType

	// Limit caps the number of results returned. 0 means no limit.
	Limit int

	// Offset skips the first N results before applying limit. Must be >= 0.
	Offset int
}

type ListSortType string

type LockOptions struct {
	NodeID string
	KegTargetOptions
}

type LockStatusOptions struct {
	NodeID string
	KegTargetOptions
}

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

	KegTargetOptions

	// LockToken is an optional cross-process lock token. When provided, the
	// command validates it against any held lock before proceeding.
	LockToken string

	// Edit opens metadata in the editor.
	Edit bool

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

type MoveOptions struct {
	KegTargetOptions

	SourceID string
	DestID   string
}

type NodeHistoryOptions struct {
	KegTargetOptions
	NodeID string
}

type NodeRestoreOptions struct {
	KegTargetOptions
	NodeID string
	Rev    string
}

type NodeSnapshotOptions struct {
	KegTargetOptions
	NodeID  string
	Message string
}

type OrientOptions struct {
	KegTargetOptions

	// Host, if set, causes tier-2 payloads to include the rendered
	// host artifact (SKILL.md, AGENTS.md, etc.). An unknown host
	// returns an error.
	Host string

	// Tier selects payload depth in [OrientTierMin, OrientTierMax].
	// Out-of-range values clamp to the nearest valid tier.
	Tier int
}

type PathNotFoundError struct {
	Path string
}

type PathService struct {
	*appctx.AppPaths
}

type ProjectKegNotFoundError struct {
	Tried []string
}

type RemoveOptions struct {
	KegTargetOptions

	// NodeIDs lists explicit node IDs to remove.
	NodeIDs []string

	// Query is an optional boolean expression (tags and/or key=value attr
	// predicates) that selects additional nodes to remove.
	Query string
}

type RemoveRepoOptions struct {
	// Alias is the keg alias to remove from the user config.
	Alias string

	// Force allows removing an alias that is currently set as the
	// defaultKeg or fallbackKeg in the user config.
	Force bool
}

type ResolveKegOptions struct {
	// Root is the base path used for project and fallback resolution.
	Root string
	// Keg is the explicit keg alias to resolve.
	Keg string
	// Project resolves a keg from project-local locations.
	Project bool
	// Cwd limits project resolution to the current working directory.
	Cwd bool
	// Path resolves a keg from an explicit filesystem path.
	Path string
	// NoCache disables in-memory keg caching for this resolution.
	NoCache bool
}

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

type ServeOptions struct {
	KegTargetOptions

	// Host is the bind address (default: 127.0.0.1).
	Host string

	// Port is the port to listen on (default: 0 for random).
	Port int

	// Title overrides the site title. If empty, the keg summary or URL is used.
	Title string

	// BaseURL is the base URL for absolute links. Defaults to "/".
	BaseURL string

	// Watch enables the filesystem watcher and SSE endpoint for automatic
	// browser refresh when node files change. When nil, defaults to true.
	Watch *bool
}

type ServeResult struct {
	URL string
}

type SiteOptions struct {
	KegTargetOptions

	// Output is the directory where the site will be written.
	Output string

	// Title overrides the site title. If empty, the keg summary or URL is used.
	Title string

	// BaseURL is the base URL for absolute links. Defaults to "/".
	BaseURL string

	// NoSearch skips Pagefind search indexing.
	NoSearch bool
}

type SiteResult struct {
	OutputDir string
	NodeCount int
	TagCount  int
	HasSearch bool
}

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

	KegTargetOptions
}

type TagsOptions struct {
	KegTargetOptions

	// Query is an optional boolean expression that filters nodes. Supports both
	// plain tag names ("golang") and key=value attribute predicates
	// ("entity=plan"). When non-empty it takes precedence over Tag.
	Query string

	// Tag filters nodes by tag expression. Deprecated: use Query instead.
	// When empty and Query is also 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

	// Limit caps the number of results returned. 0 means no limit.
	Limit int

	// Offset skips the first N results before applying limit. Must be >= 0.
	Offset int
}

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

	PathService   *PathService
	ConfigService *ConfigService
	KegService    *KegService
}

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

type UnlockOptions struct {
	NodeID string
	Token  string
	KegTargetOptions
}

type UploadFileOptions struct {
	KegTargetOptions
	NodeID   string
	FilePath string
	Name     string
}

type UploadImageOptions struct {
	KegTargetOptions
	NodeID   string
	FilePath string
	Name     string
}