Documentation
¶
Overview ¶
Package paths provides canonical helpers for:
- Converting between vault-relative markdown file paths (e.g. "objects/people/freya.md") and Raven object IDs (e.g. "people/freya")
- Validating paths are within the vault (security)
- Parsing embedded object IDs (e.g. "file#section")
It also centralizes directory-root handling (objects/pages roots) so that parsing, CLI operations, watching, and resolution stay consistent.
Index ¶
- Constants
- Variables
- func AgentInstructionsPath(vaultPath string) string
- func CandidateFilePaths(ref, objectsRoot, pagesRoot string) []string
- func EnsureMDExtension(p string) string
- func FilePathToObjectID(filePath, objectsRoot, pagesRoot string) string
- func HasMDExtension(p string) bool
- func IsProtectedRelPath(relPath string, extraPrefixes []string) bool
- func NormalizeDirRoot(root string) string
- func ObjectIDToFilePath(objectID, typeName, objectsRoot, pagesRoot string) string
- func ParseEmbeddedID(id string) (fileID, fragment string, isEmbedded bool)
- func SchemaPath(vaultPath string) string
- func ShortNameFromID(id string) string
- func TrimMDExtension(p string) string
- func ValidateWithinVault(vaultPath, targetPath string) error
Constants ¶
const AgentInstructionsFilename = "AGENTS.md"
AgentInstructionsFilename is the vault agent instructions filename.
const MDExtension = ".md"
MDExtension is the markdown file extension.
const SchemaFilename = "schema.yaml"
SchemaFilename is the vault schema filename.
Variables ¶
var ErrPathOutsideVault = errors.New("path is outside vault")
ErrPathOutsideVault is returned when a path is outside the vault.
Functions ¶
func AgentInstructionsPath ¶
AgentInstructionsPath returns the absolute path to AGENTS.md in a vault.
func CandidateFilePaths ¶
CandidateFilePaths returns vault-relative markdown paths to try for a reference.
It always includes the "literal" interpretation (ref + ".md" after stripping any ".md" suffix), plus rooted interpretations if roots are configured.
func EnsureMDExtension ¶
EnsureMDExtension adds .md extension if not already present.
func FilePathToObjectID ¶
FilePathToObjectID converts a vault-relative file path to an object ID.
It: - strips a trailing ".md" - normalizes path separators - strips the configured objects/pages root prefixes (objects first, then pages)
func HasMDExtension ¶
HasMDExtension returns true if the path ends with .md.
func IsProtectedRelPath ¶
IsProtectedRelPath returns true if relPath (vault-relative) is protected.
extraPrefixes are additional user-configured protected prefixes (vault-relative). They are treated as directory prefixes (normalized with NormalizeDirRoot).
func NormalizeDirRoot ¶
NormalizeDirRoot normalizes a directory root to have: - no leading slash - exactly one trailing slash (unless empty)
Examples: - "/objects/" -> "objects/" - "objects" -> "objects/" - "" -> ""
func ObjectIDToFilePath ¶
ObjectIDToFilePath converts an object ID to a vault-relative markdown file path.
If roots are configured, typeName is used to decide whether to prefix with pagesRoot or objectsRoot: - typeName == "" or "page" -> pagesRoot (falls back to objectsRoot if pagesRoot is empty) - otherwise -> objectsRoot
If the objectID already includes a configured root prefix, this function will not add another prefix.
func ParseEmbeddedID ¶
ParseEmbeddedID parses an object ID that may contain an embedded fragment. For IDs like "file#section", it returns (fileID, fragment, true). For IDs without a fragment, it returns (id, "", false).
This is the canonical function for parsing embedded object IDs. Use this instead of manually calling strings.SplitN(id, "#", 2).
func SchemaPath ¶
SchemaPath returns the absolute path to schema.yaml in a vault.
func ShortNameFromID ¶
ShortNameFromID extracts the short name from an object ID. For "people/freya" -> "freya" For "daily/2025-02-01#standup" -> "standup"
func TrimMDExtension ¶
TrimMDExtension removes the .md extension if present.
func ValidateWithinVault ¶
ValidateWithinVault checks that a target path is within the vault directory. Returns an error if the path would escape the vault (security check).
This function: - Resolves both paths to absolute paths - Evaluates symlinks for security - Handles paths that don't exist yet by checking parent directories
Types ¶
This section is empty.
Source Files