store

package
v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Jun 10, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package store is the git-backed markdown source of truth. Pages live under wiki/ (or the served folder itself when there is no wiki/, so a bare folder or Obsidian vault works unchanged), raw documents under raw/, schema in CLAUDE.md.

Index

Constants

View Source
const SearchLimit = 50

SearchLimit is how many hits search surfaces. Backends fetch one extra so a caller can tell the results were truncated and report it.

Variables

This section is empty.

Functions

func FrontmatterTags added in v0.3.0

func FrontmatterTags(fm map[string]any) []string

FrontmatterTags reads the tags field, accepting either a YAML list or a comma-separated string. FrontmatterTags collects a page's tags from the frontmatter: the `tags` field (a list or a comma string), Hugo's `categories`, and the values of a Hugo/Zola `[taxonomies]` table.

func SplitFrontmatter

func SplitFrontmatter(raw string) (map[string]any, string)

SplitFrontmatter separates a leading frontmatter block from the markdown body. It reads YAML (--- ... ---), TOML (+++ ... +++), and JSON, and returns a nil map when there is no frontmatter.

Types

type Attribution added in v0.3.0

type Attribution struct {
	Author   string
	Approver string
	When     time.Time
}
type BrokenLink struct {
	From string `json:"from"`
	To   string `json:"to"`
}

type Change added in v0.3.0

type Change struct {
	Slug    string    `json:"slug"`
	Title   string    `json:"title"`
	Author  string    `json:"author"`
	When    time.Time `json:"when"`
	Deleted bool      `json:"deleted,omitempty"`
}

type GraphEdge

type GraphEdge struct {
	From string `json:"from"`
	To   string `json:"to"`
}

type GraphNode added in v0.3.0

type GraphNode struct {
	Slug   string `json:"slug"`
	Title  string `json:"title"`
	Degree int    `json:"degree"`
}

type GraphView added in v0.3.0

type GraphView struct {
	Nodes     []GraphNode `json:"nodes"`
	Edges     []GraphEdge `json:"edges"`
	Truncated bool        `json:"truncated,omitempty"`
	Total     int         `json:"total,omitempty"` // total node count when truncated
}

type Health added in v0.3.0

type Health struct {
	Orphans []PageMeta   `json:"orphans"`
	Broken  []BrokenLink `json:"broken"`
	Stale   []StalePage  `json:"stale"`
}

type Hub added in v0.3.0

type Hub struct {
	Slug   string `json:"slug"`
	Title  string `json:"title"`
	Degree int    `json:"degree"`
}

type Neighbor added in v0.3.0

type Neighbor struct {
	Slug     string `json:"slug"`
	Title    string `json:"title"`
	Distance int    `json:"distance"`
}

type Page

type Page struct {
	Slug        string
	Title       string
	Frontmatter map[string]any
	Body        string // markdown with frontmatter stripped
	Raw         string // full file contents
}

type PageMeta

type PageMeta struct {
	Slug  string
	Title string
}

type Revision added in v0.3.0

type Revision struct {
	Hash    string    `json:"hash"`
	Author  string    `json:"author"`
	Message string    `json:"message"`
	When    time.Time `json:"when"`
}

type SearchHit

type SearchHit struct {
	Slug    string `json:"slug"`
	Title   string `json:"title"`
	Snippet string `json:"snippet"`
}

type StalePage added in v0.3.0

type StalePage struct {
	Slug  string `json:"slug"`
	Title string `json:"title"`
	Days  int    `json:"days"`
}

type Store

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

func New

func New(root string) (*Store, error)

func (*Store) AddAsset added in v0.3.0

func (s *Store) AddAsset(data []byte, originalName string) (string, error)

AddAsset stores an uploaded file under assets/ with a content-addressed name (so identical uploads dedupe), commits it, and returns the stored name.

func (*Store) AddRaw

func (s *Store) AddRaw(name string, data []byte) error

func (*Store) AssetPath added in v0.3.0

func (s *Store) AssetPath(name string) (string, error)

AssetPath returns the on-disk path for a stored asset, validating the name.

func (s *Store) Backlinks(slug string) ([]PageMeta, error)

Backlinks returns the pages that link to the given slug.

func (*Store) CacheDir added in v0.6.0

func (s *Store) CacheDir() (string, error)

CacheDir returns this wiki's directory under the OS cache directory, keyed by the resolved root path so every name for the same physical wiki (notably /tmp vs /private/tmp on macOS) shares one cache.

func (*Store) CanonicalSlug added in v0.5.0

func (s *Store) CanonicalSlug(slug string) (string, error)

CanonicalSlug returns the slug a page is actually filed under after normalization, or an error if the slug is invalid.

func (*Store) Delete added in v0.5.0

func (s *Store) Delete(slug, author, message string) error

Delete removes a page and commits the removal. The page stays recoverable from git history. It returns os.ErrNotExist when the slug has no page.

func (*Store) DeleteRaw added in v0.5.0

func (s *Store) DeleteRaw(name string) error

DeleteRaw removes a raw source document. Raw documents are working-tree only (never committed), so this is a plain removal.

func (*Store) Fingerprints added in v0.5.0

func (s *Store) Fingerprints() (map[string]string, error)

Fingerprints maps each page's slug to its content fingerprint. Incremental indexers diff it against their last view to re-read only the pages that changed. It shares the memoized walk with Signature.

func (*Store) Graph

func (s *Store) Graph() ([]PageMeta, []GraphEdge, error)

Graph returns the pages and the resolved [[wikilink]] edges between them.

func (*Store) GraphView added in v0.3.0

func (s *Store) GraphView() (*GraphView, error)

GraphView returns the whole link graph as nodes (with degree) and edges, for rendering the visual map.

func (*Store) GraphViewTop added in v0.5.0

func (s *Store) GraphViewTop(limit int) (*GraphView, error)

GraphViewTop returns a renderable subgraph for large wikis: it seeds with the most-connected pages and pulls in each hub's neighbors, so the result stays connected and keeps its edges, rather than a dust of high-degree nodes that happen not to link to one another. A limit <= 0, or a graph already within the limit, returns the full graph untouched.

func (*Store) Health added in v0.3.0

func (s *Store) Health() (*Health, error)

Health reports orphans (no incoming links), broken wikilinks, and pages untouched for longer than staleDays.

func (*Store) History added in v0.3.0

func (s *Store) History(slug string) ([]Revision, error)

History returns the git revisions of a page, newest first. A deleted page still surfaces its revisions, since its content stays recoverable from history. It returns os.ErrNotExist only when the page neither exists nor has any history (so a caller can tell a never-created slug from an existing untracked one).

func (*Store) Hubs added in v0.3.0

func (s *Store) Hubs(n int) ([]Hub, error)

Hubs returns the n most-connected pages by undirected degree.

func (*Store) Instructions

func (s *Store) Instructions() string

Instructions returns the contents of CLAUDE.md at the wiki root, if present.

func (*Store) KnownSlugs

func (s *Store) KnownSlugs() (map[string]bool, error)

func (*Store) LastTouched added in v0.3.0

func (s *Store) LastTouched(slug string) (*Attribution, bool)

LastTouched returns the author, the approver (parsed from the commit message), and time of the last commit to change a page; false when there is no history. Attributions come from one batched git log pass cached by Signature, so a page view does not fork a git subprocess.

func (*Store) Layout

func (s *Store) Layout() string

Layout reports whether pages are served from a wiki/ subdirectory or the folder itself (vault mode).

func (*Store) LinkChecker added in v0.5.0

func (s *Store) LinkChecker() (func(string) bool, error)

LinkChecker returns a predicate reporting whether a wikilink target is fine, using the same tolerant resolution as the link graph: a target is fine if it resolves to a page, or is a benign asset, same-page anchor, or external URL. Lint uses it so its warnings agree with what wiki_health reports as broken.

func (*Store) List

func (s *Store) List() ([]PageMeta, error)

List returns every page's slug and title, cached by Signature so the per-page title reads happen once per change rather than on every call.

func (*Store) ListRaw

func (s *Store) ListRaw() ([]string, error)

func (*Store) ListTemplates added in v0.3.0

func (s *Store) ListTemplates() []string

ListTemplates returns the names of page templates under .waqwaq/templates.

func (*Store) Neighbors added in v0.3.0

func (s *Store) Neighbors(slug string, depth int) ([]Neighbor, error)

Neighbors returns the pages reachable from slug within depth hops over the undirected link graph, nearest first, excluding the page itself.

func (*Store) Pages

func (s *Store) Pages() string

func (*Store) Path added in v0.3.0

func (s *Store) Path(from, to string) ([]PageMeta, error)

Path returns the shortest chain of pages connecting from to to over the undirected link graph, inclusive of both ends, or nil if they are not connected.

func (*Store) Read

func (s *Store) Read(slug string) (*Page, error)

func (*Store) ReadAtRev added in v0.3.0

func (s *Store) ReadAtRev(slug, ref string) (string, error)

ReadAtRev returns a page's content at a git revision (a commit hash, optionally with a ~N parent suffix). It returns "" when the file did not exist there.

func (*Store) ReadRaw

func (s *Store) ReadRaw(name string) (string, error)

func (*Store) ReadTemplate added in v0.3.0

func (s *Store) ReadTemplate(name string) (string, error)

ReadTemplate returns a named template's content.

func (*Store) Recent added in v0.3.0

func (s *Store) Recent(n int) ([]Change, error)

Recent returns the n most recently changed pages, newest first. It reads the recent commits with a single streaming `git log` and stops as soon as it has n distinct pages, so its cost is independent of the total page count (the old approach forked one `git log` per page).

func (s *Store) ResolveLink(target string) (string, bool)

ResolveLink maps a wikilink target (which may carry a |alias or #anchor) to a known page slug, false when it resolves to no page.

func (*Store) RevExists added in v0.3.0

func (s *Store) RevExists(ref string) bool

RevExists reports whether ref resolves to a commit in the repo.

func (*Store) Root

func (s *Store) Root() string

func (*Store) Search

func (s *Store) Search(query string) ([]SearchHit, error)

func (*Store) Signature added in v0.3.0

func (s *Store) Signature() (string, error)

Signature is a hash of every page's path, mtime, and size, so a cache can detect staleness (including edits by external tools) from stats alone, no file reads. The result is memoized so the many cache checks that call it do not each re-walk a large tree.

func (*Store) Tags added in v0.3.0

func (s *Store) Tags() (map[string][]PageMeta, error)

Tags maps every tag to the pages that carry it in their frontmatter, cached by Signature and fed from the shared pageInfos cache so only changed pages are re-read.

func (*Store) VaultAsset added in v0.3.0

func (s *Store) VaultAsset(name string) (string, bool)

VaultAsset resolves an Obsidian-style ![[image.png]] embed to the file by its basename wherever it lives in the tree. Only allowedAssetExt types are served (SVG excluded as an XSS vector), and the path comes from a server-built index of files present, never from the request.

func (*Store) Warm added in v0.5.0

func (s *Store) Warm()

Warm builds the corpus-wide caches (page list, link graph, adjacency, tags) ahead of the first request. Serve runs it in the background so an agent's first graph or tag query on a large wiki hits a warm cache instead of paying the full-corpus read. Errors are ignored: the caches rebuild lazily anyway.

func (*Store) Write

func (s *Store) Write(slug, content, author, message string) error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址