core

Documentation

Overview

Package core is the UI-agnostic hebb engine: indexing, search, vault scaffolding, sync and hygiene. The CLI and the MCP surface are thin layers over this package, so a future GUI can reuse it without rework.

Index

• func GitCommitAll(vaultPath, msg string) (bool, error)
• func GitPull(vaultPath string) error
• func GitPush(vaultPath string) error
• func IndexFile(cfg Config, db *sql.DB, rel string) error
• func IsGitRepo(vaultPath string) bool
• func OpenDB(dbPath string) (*sql.DB, error)
• func RemoveFile(db *sql.DB, rel string) error
• type Config
  • func ResolveVault(flagVault, flagDB string) (Config, error)
• type ContextResult
  • func ExpandContext(db *sql.DB, notePath string, depth, limit int) []ContextResult
• type GitConfig
  • func (g GitConfig) Debounce() int
  • func (g GitConfig) Message() string
  • func (g GitConfig) PullEnabled() bool
  • func (g GitConfig) PushEnabled() bool
• type IndexResult
  • func FullReindex(cfg Config, db *sql.DB) (IndexResult, error)
• type Note
  • func ParseNote(content, relPath string) Note
• type SearchResult
  • func Search(db *sql.DB, query string, limit int, tag, pathPrefix string) ([]SearchResult, error)
• type SyncOptions
• type SyncResult
  • func GitSync(vaultPath string, opts SyncOptions) (SyncResult, error)
• type TagCount
  • func Stats(db *sql.DB) (notes, links int, topTags []TagCount, err error)
• type TopicResult
  • func GetContextForTopic(db *sql.DB, topic string, limit int, pathPrefix string) []TopicResult
• type UpdateConfig
• type VaultConfig
  • func DefaultVaultConfig(name string) VaultConfig
  • func LoadVaultConfig(vaultPath string) (VaultConfig, bool, error)
  • func (vc VaultConfig) Save(vaultPath string) error
• type Watcher
  • func Watch(cfg Config, db *sql.DB) (*Watcher, error)
  • func (wt *Watcher) Close()

Functions

func GitCommitAll

func GitCommitAll(vaultPath, msg string) (bool, error)

GitCommitAll stages every change and commits with msg. It reports whether a commit was made: a clean tree is a no-op (committed=false), not an error.

func GitPull

func GitPull(vaultPath string) error

GitPull runs `git pull --rebase --autostash`. On a conflict (or any rebase failure) it aborts the rebase to restore a clean working tree and returns an error, so hebb never leaves the vault mid-rebase or auto-resolves. With no upstream configured it is a no-op.

func GitPush

func GitPush(vaultPath string) error

GitPush pushes the current branch to its upstream.

func IndexFile

func IndexFile(cfg Config, db *sql.DB, rel string) error

IndexFile indexes or updates a single note by vault-relative path. If the file no longer exists it is removed from the index.

func IsGitRepo

func IsGitRepo(vaultPath string) bool

IsGitRepo reports whether vaultPath is inside a git work tree.

func OpenDB

func OpenDB(dbPath string) (*sql.DB, error)

OpenDB opens (creating if needed) the index database and ensures the schema.

func RemoveFile

func RemoveFile(db *sql.DB, rel string) error

RemoveFile drops a note and its links from the index.

Types

type Config

type Config struct {
	VaultPath   string
	DBPath      string
	ExcludeDirs []string
	Git         GitConfig // git-mode settings from the vault's [git] block
}

Config locates a vault and its index database.

func ResolveVault

func ResolveVault(flagVault, flagDB string) (Config, error)

ResolveVault determines the vault path (flag, then $HEBB_VAULT, then the nearest ancestor of the cwd containing .hebb/) and the index db path.

type ContextResult

type ContextResult struct {
	Path         string
	Title        string
	Relationship string
	Snippet      string
}

ContextResult is a note reached by following the link graph.

func ExpandContext

func ExpandContext(db *sql.DB, notePath string, depth, limit int) []ContextResult

ExpandContext follows wiki-links out from a seed note (1-2 hops).

type GitConfig

type GitConfig struct {
	Enabled         bool   `toml:"enabled"`
	AutoPull        *bool  `toml:"auto_pull"`        // default true when enabled
	AutoPush        *bool  `toml:"auto_push"`        // default true when enabled
	DebounceSeconds int    `toml:"debounce_seconds"` // watcher quiet-period before a sync; default 10
	CommitMessage   string `toml:"commit_message"`   // default "hebb: sync vault"
}

GitConfig is the committed [git] block. Git mode keeps the vault's markdown in sync with a remote (pull before work, commit + push after). It is off unless enabled is true. AutoPull/AutoPush are pointers so an unset value defaults to on (only meaningful when enabled), while an explicit false turns that half off.

func (GitConfig) Debounce

func (g GitConfig) Debounce() int

Debounce is the resolved quiet-period in seconds before the watcher syncs.

func (GitConfig) Message

func (g GitConfig) Message() string

Message is the resolved auto-commit message.

func (GitConfig) PullEnabled

func (g GitConfig) PullEnabled() bool

PullEnabled reports whether git mode should pull (on by default when enabled).

func (GitConfig) PushEnabled

func (g GitConfig) PushEnabled() bool

PushEnabled reports whether git mode should commit+push (on by default when enabled).

type IndexResult

type IndexResult struct {
	Indexed int
	Removed int
}

IndexResult summarises a reindex.

func FullReindex

func FullReindex(cfg Config, db *sql.DB) (IndexResult, error)

FullReindex walks the vault, parses every markdown file and upserts the index, removing entries whose files no longer exist on disk.

type Note

type Note struct {
	Title       string
	Body        string // markdown lightly stripped for FTS
	Tags        []string
	Frontmatter map[string]any
	Links       []string
}

Note is a parsed markdown note ready for indexing.

func ParseNote

func ParseNote(content, relPath string) Note

ParseNote parses raw markdown into structured data. relPath is the vault relative path, used as the fallback title.

type SearchResult

type SearchResult struct {
	Path    string
	Title   string
	Snippet string
	Tags    string
	Rank    float64
}

SearchResult is a single FTS hit.

func Search

func Search(db *sql.DB, query string, limit int, tag, pathPrefix string) ([]SearchResult, error)

Search runs an FTS5 query, falling back to LIKE if the query is invalid.

type SyncOptions

type SyncOptions struct {
	Pull    bool
	Commit  bool
	Push    bool
	Message string // commit message; defaults when empty
}

SyncOptions selects which git steps GitSync performs.

type SyncResult

type SyncResult struct {
	Pulled    bool
	Committed bool
	Pushed    bool
}

SyncResult reports what GitSync actually did.

func GitSync

func GitSync(vaultPath string, opts SyncOptions) (SyncResult, error)

GitSync commits local changes, pulls (rebasing onto the upstream), and pushes, per opts. Commit runs before pull so the rebase has a clean tree; pull runs before push so a fast-forward is likely. It is a no-op where there is nothing to do (clean tree, no upstream). It never force-pushes; a pull that conflicts is aborted and surfaced as an error so the user resolves it by hand.

type TagCount

type TagCount struct {
	Tag   string
	Count int
}

TagCount is a tag and its frequency.

func Stats

func Stats(db *sql.DB) (notes, links int, topTags []TagCount, err error)

Stats returns note count, link count and the top tags.

type TopicResult

type TopicResult struct {
	Path      string
	Title     string
	Relevance string
	Snippet   string
	Tags      string
}

TopicResult is a note assembled into a topic context bundle.

func GetContextForTopic

func GetContextForTopic(db *sql.DB, topic string, limit int, pathPrefix string) []TopicResult

GetContextForTopic combines full-text search, link expansion and tag siblings.

type UpdateConfig

type UpdateConfig struct {
	Auto bool `toml:"auto"`
}

UpdateConfig is the committed [update] block. The scheduled update-check job reports a newer release by default; with auto = true it installs it (opt-in, since self-replacing a binary unattended is a deliberate choice).

type VaultConfig

type VaultConfig struct {
	Name        string       `toml:"name"`
	ExcludeDirs []string     `toml:"exclude_dirs"`
	WebPort     int          `toml:"web_port"`
	Jobs        []string     `toml:"jobs"`
	Skills      []string     `toml:"skills"`
	Git         GitConfig    `toml:"git"`
	Update      UpdateConfig `toml:"update"`
}

VaultConfig is the committed, per-vault contract stored at <vault>/.hebb/config.toml. It self-identifies a vault and configures the parts of hebb that vary per vault (excludes, web port, enabled jobs/skills).

func DefaultVaultConfig

func DefaultVaultConfig(name string) VaultConfig

DefaultVaultConfig returns the baseline config for a vault of the given name.

func LoadVaultConfig

func LoadVaultConfig(vaultPath string) (VaultConfig, bool, error)

LoadVaultConfig reads <vault>/.hebb/config.toml. The boolean reports whether the file existed: when it does not, defaults named after the vault directory are returned so callers always receive a usable config. A malformed file is an error.

func (VaultConfig) Save

func (vc VaultConfig) Save(vaultPath string) error

Save writes the config to <vault>/.hebb/config.toml, creating .hebb/ if needed. It is idempotent.

type Watcher

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

Watcher incrementally updates the index as markdown files change.

func Watch

func Watch(cfg Config, db *sql.DB) (*Watcher, error)

Watch starts watching the vault tree, reindexing single files on change and removing them on delete. Close stops it.

func (*Watcher) Close

func (wt *Watcher) Close()

Close stops the watcher.