kb

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Nov 1, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package kb owns all access to knowledge-base files.

Index

Constants

This section is empty.

Variables

View Source 
var ErrWriteRefused = errors.New("write refused")

Functions

func ApplyMove 

func ApplyMove(root string, plan MovePlan) error

ApplyMove preserves the original bytes, then routes changed sources through Write.

func CanonicalID 

func CanonicalID(id string) string

CanonicalID is the spelling used for comparisons and public note IDs.

func CaptureContent 

func CaptureContent(text, title string, now time.Time) (string, string, error)

CaptureContent shares timestamp, filename and frontmatter rules across front ends.

func CommitWrite 

func CommitWrite(root string, paths []string, message string, commitOnWrite bool) error

CommitWrite stages and commits only the supplied root-relative paths.

func CommitWriteStatus 

func CommitWriteStatus(root string, paths []string, message string, commitOnWrite bool) (bool, error)

CommitWriteStatus reports whether CommitWrite actually advanced HEAD.

func Content 

func Content(body string, metadata *Frontmatter) (string, error)

Content serializes safe YAML frontmatter without interpreting body text.

func Init 

func Init(path string) error

Init creates a KB, leaving an existing KB untouched.

func LockWrites 

func LockWrites(root string) (func(), error)

LockWrites serializes file mutations and cache transactions across processes. The returned release function must run after reindexing and any git commit.

func NoteNotFound 

func NoteNotFound(id string) error

NoteNotFound gives file and index reads the same public error and exit identity.

func PreviewInit 

func PreviewInit(path string) error

PreviewInit performs the same safety checks as Init without writing.

func PreviewWrite 

func PreviewWrite(root, id, mode string) error

PreviewWrite validates a proposed write without creating directories or files.

func Resolve 

func Resolve(target string, notes []Note) (string, bool)

Resolve tries exact ID, unique basename, then unique case-insensitive alias. 

func ResolveLink(target string, notes []Note) (id, reason string)

ResolveLink also explains unresolved references for the broken-link report. 

func RewriteLinks(body, old, new string, before, after []Note) (string, int)

RewriteLinks preserves resolved destinations across a move, retaining link suffixes.

func Slug 

func Slug(text string) string

func UnifiedDiff 

func UnifiedDiff(oldPath, newPath, before, after string) string

UnifiedDiff emits a valid whole-file unified hunk without external tools.

func ValidateID 

func ValidateID(id string, write bool) error

ValidateID shares path rules for reads and writes; writes refuse an accidental extension.

Types

type Details 

type Details struct {
	Problem    map[string]string `json:"problem,omitempty" jsonschema:"Inspector problems by component"`
	Embeddings struct {
		Model  string `json:"model"`
		Notes  int    `json:"notes"`
		Chunks int    `json:"chunks"`
	} `json:"embeddings"`
	Links        int    `json:"links" jsonschema:"links"`
	BrokenLinks  int    `json:"broken_links" jsonschema:"broken links"`
	Orphans      int    `json:"orphans" jsonschema:"orphans"`
	Problems     int    `json:"problems" jsonschema:"problems"`
	IndexedNotes int    `json:"indexed_notes" jsonschema:"indexed notes"`
	IndexPath    string `json:"index_path" jsonschema:"index path"`
	Root         string `json:"root" jsonschema:"root"`
	NoteCount    int    `json:"note_count" jsonschema:"note count"`
	Initialized  bool   `json:"initialized" jsonschema:"initialized"`
}

Details is the stable info response, including for an uninitialized directory.

func Info 

func Info(root string) (Details, error)

Info counts Markdown files recursively, skipping dot-directories and child symlinks. A missing root is an error; an existing uninitialized root is inspectable.

type Frontmatter 

type Frontmatter struct {
	Title   string   `json:"title,omitempty" yaml:"title,omitempty" jsonschema:"Optional display title"`
	Tags    []string `json:"tags,omitempty" yaml:"tags,omitempty" jsonschema:"Optional tags"`
	Aliases []string `json:"aliases,omitempty" yaml:"aliases,omitempty" jsonschema:"Optional link aliases"`
	Created string   `json:"-" yaml:"created,omitempty"`
}

Frontmatter is optional metadata supplied with agent writes.

type LinkRef 

type LinkRef struct {
	Raw, Target, Heading, Alias string
	Start, End                  int
	Embed                       bool
	Line                        int
}

LinkRef retains the spelling inside brackets and a body-relative, one-based line. 

func ExtractLinks(body string) []LinkRef

ExtractLinks scans wikilinks outside fences and matched inline code spans.

type MoveChange 

type MoveChange struct{ ID, Path, Before, After string }

type MovePlan 

type MovePlan struct {
	OldPath, NewPath string
	Result           MoveResult
	Changes          []MoveChange
}

func PlanMove 

func PlanMove(root, old, new string) (MovePlan, error)

PlanMove validates every affected path before any mutation.

type MoveResult 

type MoveResult struct {
	Old         string      `json:"old"`
	New         string      `json:"new"`
	Rewritten   []Rewritten `json:"rewritten"`
	Total       int         `json:"total"`
	Commit      bool        `json:"commit"`
	DryRun      bool        `json:"dry_run,omitempty"`
	CommitError string      `json:"-"`
}

type Note 

type Note struct {
	ID      string   `json:"id"`
	Path    string   `json:"path"`
	Title   string   `json:"title"`
	Aliases []string `json:"aliases"`
	Tags    []string `json:"tags"`
	Created string   `json:"created"`
	Updated string   `json:"updated"`
	MTime   int64    `json:"mtime"`
	Size    int64    `json:"size"`
	Problem string   `json:"problem,omitempty"`
	Body    string   `json:"body"`
}

Note is a Markdown file; Path and ID are relative to the KB root.

func Parse 

func Parse(path string, raw []byte) (Note, error)

Parse removes optional frontmatter, retaining the Markdown body verbatim.

func Read 

func Read(root, id string) (Note, string, error)

Read resolves one ID without traversing unrelated notes. Child symlinks are refused.

func Walk 

func Walk(root string) ([]Note, error)

Walk skips dot-directories, invalid IDs and child symlinks, matching Info.

type Resolver 

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

Resolver indexes exact IDs, basenames and aliases for one graph snapshot.

func NewResolver 

func NewResolver(notes []Note) *Resolver

NewResolver records ambiguous matches as empty IDs. 

func (r *Resolver) ResolveLink(target string) (id, reason string)

ResolveLink tries exact ID, unique basename, then unique case-insensitive alias.

type Rewritten 

type Rewritten struct {
	ID    string `json:"id"`
	Count int    `json:"count"`
}

type WriteResult 

type WriteResult struct {
	Commit      bool   `json:"commit" jsonschema:"Whether the write committed successfully"`
	Changed     bool   `json:"-" jsonschema:"-"`
	CommitError string `json:"-" jsonschema:"-"`
	ID          string `json:"id" jsonschema:"Note ID relative to root without .md"`
	Path        string `json:"path" jsonschema:"Relative Markdown path"`
	Bytes       int    `json:"bytes" jsonschema:"Total bytes in the resulting file"`
	Mode        string `json:"mode" jsonschema:"Applied write mode"`
}

func Write 

func Write(root, id, content, mode string) (WriteResult, error)

Write atomically publishes a note; cache updates belong to the application layer.

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.