vfs

Documentation

Overview

Package vfs is the pluggable storage abstraction for AI-managed projects.

The base Storage contract is intentionally minimal (4 methods). Optional capabilities — scoping (ScopedStorage) and search (Searchable) — extend it via interface assertion or registration-time binding, mirroring the capability pattern used in mxcd/go-basicauth.

v1 ships memory-only (vfs/memory). Other backends are caller-implemented or come in v1.x / v2.

Index

• Constants
• Variables
• func RunConformance(t *testing.T, factory func() Storage)
• func ValidatePath(path string) error
• type FileMeta
• type ScopedStorage
• type Searchable
• type Storage

Constants

const MaxPathBytes = 512

MaxPathBytes is the structural cap on a path's byte length.

Variables

var (
	ErrPathInvalid  = errors.New("aikido/vfs: invalid path")
	ErrFileNotFound = errors.New("aikido/vfs: file not found")
	ErrFileTooLarge = errors.New("aikido/vfs: file too large")
	// ErrReadOnly is returned by Storage backends that do not support mutation
	// (e.g. vfs/embedfs). Callers can errors.Is-check it to fall back to a
	// writable backend or to surface a friendly message.
	ErrReadOnly = errors.New("aikido/vfs: storage is read-only")
)

Functions

func RunConformance

func RunConformance(t *testing.T, factory func() Storage)

RunConformance executes the standard conformance suite against a Storage factory. Each sub-test calls the factory to obtain a fresh Storage. Tests are serial — implementations that want parallel execution can opt in with their own t.Parallel() inside the factory if applicable.

Searchable-related sub-tests run only when the factory's Storage satisfies vfs.Searchable.

func ValidatePath

func ValidatePath(path string) error

ValidatePath enforces aikido-wide structural invariants on a path.

Caller-policy filters (max bytes, allowed extensions, hidden-path filtering) live on agent.VFSToolOptions, not here.

Types

type FileMeta

type FileMeta struct {
	Path        string
	ContentType string
	Size        int64
	UpdatedAt   time.Time
}

FileMeta describes one file's metadata.

type ScopedStorage

type ScopedStorage interface {
	Scope(scope string) Storage
}

ScopedStorage is an OPTIONAL capability for backends that multiplex tenants (or any other namespace). The library never sees a scope parameter on Storage methods — callers pre-bind via Scope and hand the resulting Storage to RegisterVFSTools (ADR-013).

type Searchable

type Searchable interface {
	Search(ctx context.Context, query string) (paths []string, err error)
	SearchSyntax() string
}

Searchable is an OPTIONAL capability for backends that support native search.

The built-in `search` tool is registered by RegisterVFSTools only when the supplied storage satisfies Searchable. SearchSyntax returns human-readable documentation of the query language; the tool description embeds it so the model knows what queries the backend accepts.

type Storage

type Storage interface {
	ListFiles(ctx context.Context) ([]FileMeta, error)
	ReadFile(ctx context.Context, path string) ([]byte, FileMeta, error)
	WriteFile(ctx context.Context, path string, content []byte, contentType string) error
	DeleteFile(ctx context.Context, path string) error
}

Storage is the base contract every VFS backend implements.

Path semantics: paths are forward-slash separated, relative, no leading slash, no `..` segments, no double slashes, no trailing slash, no null bytes, length <= 512 bytes. See ValidatePath.

Atomicity: each call is atomic at the backend level. The agent loop is not transactional in v1 (ADR-019).