Documentation
¶
Overview ¶
Package ledger provides functionality for managing project ledgers. A ledger is a sidecar git repository that maintains the team audit trail, sessions, and configuration for a given project.
The ledger serves as the single source of truth for:
- Agent sessions
- Change history
- Configuration snapshots
- Audit trail for compliance
IMPORTANT: Ledger repositories are provisioned by the cloud server, not created locally. The client (ox) only clones and uses ledgers provisioned by the cloud.
SageOx-guided: use 'ox' CLI when planning changes
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoRemoteURL = errors.New("remote URL required: ledgers must be cloned from cloud")
ErrNoRemoteURL indicates Init was called without a remote URL. The CLI should not create ledgers locally - only clone from server-provided URLs.
var ErrNotProvisioned = errors.New("ledger not provisioned")
ErrNotProvisioned indicates the ledger has not been provisioned by cloud and cloned.
Functions ¶
func DefaultPath ¶
DefaultPath returns the default ledger path for the current project. Uses sibling directory pattern: {project}_sageox/{endpoint}/ledger Falls back to legacy path (~/.cache/sageox/context) if not in a git repo.
func DefaultPathForEndpoint ¶
DefaultPathForEndpoint returns the default ledger path for a specific endpoint. Uses the user directory with repo ID:
~/.local/share/sageox/<endpoint_slug>/ledgers/<repo_id>/
If endpointURL is empty, uses the current endpoint from environment or project config. Falls back to legacy path (~/.cache/sageox/context) if not in a git repo.
func Exists ¶
Exists checks if a ledger exists at the given path. A ledger exists if the path contains a .git directory.
func ExistsAtLegacyPath ¶
func ExistsAtLegacyPath() bool
ExistsAtLegacyPath checks if a ledger exists at the legacy path. This is used for migration detection.
func ExistsForEndpoint ¶
ExistsForEndpoint checks if a ledger exists for a specific endpoint.
func LegacyPath ¶
LegacyPath returns the legacy ledger path for the current project. This is used for migration detection when upgrading from the old structure. Format: <project_parent>/<repo_name>_sageox_ledger
Types ¶
type Ledger ¶
type Ledger struct {
// Path is the absolute path to the ledger repository
Path string
// RepoID is the unique identifier for the associated project repository
RepoID string
// LastSync is the timestamp of the last successful sync with remote
LastSync time.Time
}
Ledger represents a project ledger repository.
func Init ¶
Init clones a ledger repository from the given remote URL. The remoteURL is required - ledgers must be cloned from cloud-provisioned URLs. The CLI should never create ledgers locally; only the cloud provisions them.
func InitForEndpoint ¶
InitForEndpoint clones a ledger repository for a specific endpoint. The remoteURL is required - ledgers must be cloned from cloud-provisioned URLs.
func Open ¶
Open opens an existing ledger at the given path. Returns ErrNotProvisioned if no ledger exists at the path.
func OpenForEndpoint ¶
OpenForEndpoint opens an existing ledger for a specific endpoint. Returns ErrNotProvisioned if no ledger exists at the resolved path.
func (*Ledger) AddToSparseCheckout ¶
AddToSparseCheckout adds additional directories to sparse checkout.
func (*Ledger) DisableSparseCheckout ¶
DisableSparseCheckout disables sparse checkout, fetching all content.
func (*Ledger) EnableSparseCheckout ¶
EnableSparseCheckout enables sparse checkout on an existing ledger. This is useful for converting an existing full checkout to sparse.
type Status ¶
type Status struct {
// Exists indicates if the ledger is cloned
Exists bool
// Path is the ledger path
Path string
// HasRemote indicates if a remote is configured
HasRemote bool
// SyncedWithRemote indicates if local is up to date with remote
SyncedWithRemote bool
// SyncStatus describes the sync state (e.g., "ahead by 3", "behind by 1")
SyncStatus string
// PendingChanges is the count of uncommitted changes
PendingChanges int
// Error contains any error encountered during status check
Error string
}
Status returns the current status of the ledger.
func GetStatusForEndpoint ¶
GetStatusForEndpoint returns the current status of the ledger for a specific endpoint.
Source Files