sidecar

package
v0.3.1 Latest Latest
Warning

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

 Go to latest Published: May 18, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package sidecar coordinates skeeper's mirrored Git repository.

Index

Constants

View Source 
const (
	// DirName is the sidecar clone directory in the main worktree.
	DirName = ".skeeper"
)

Variables

This section is empty.

Functions

func DefaultNamespace added in v0.1.1 

func DefaultNamespace(repoName string) string

DefaultNamespace returns a safe sidecar namespace derived from a repo name.

func PrintJSON added in v0.2.0 

func PrintJSON(w io.Writer, value any) error

PrintJSON writes a stable JSON payload for CLI renderers.

func UpdateGitignore 

func UpdateGitignore(root string, namespaces []config.Namespace) error

UpdateGitignore appends or replaces skeeper's managed ignore block.

Types

type DiffOptions added in v0.2.1 

type DiffOptions struct {
	JSON      bool
	Namespace string
	Classes   []reconcile.PathClass
}

DiffOptions configures working-tree diff output.

type FSCKOptions added in v0.2.0 

type FSCKOptions struct {
	JSON         bool
	SourceBranch string
}

FSCKOptions configures working-tree drift checks.

type FSCKResult added in v0.2.0 

type FSCKResult struct {
	OK          bool                      `json:"ok"`
	Namespaces  []reconcile.NamespaceDiff `json:"namespaces,omitempty"`
	Diagnostics []reconcile.Diagnostic    `json:"diagnostics,omitempty"`
}

FSCKResult reports working-tree drift against the lock.

type HydrateOptions added in v0.2.1 

type HydrateOptions struct {
	DryRun     bool
	JSON       bool
	KeepLocal  bool
	AdoptLocal bool
	PruneLocal bool
	Merge      bool
	Ours       bool
	Theirs     bool
}

HydrateOptions configures safe lock materialization into the working tree.

type HydrateResult 

type HydrateResult struct {
	OK             bool                   `json:"ok"`
	Restored       []string               `json:"restored"`
	Skipped        []string               `json:"skipped,omitempty"`
	Rescue         *state.RescueManifest  `json:"rescue,omitempty"`
	Commit         string                 `json:"commit"`
	DryRun         bool                   `json:"dry_run,omitempty"`
	HooksInstalled bool                   `json:"hooks_installed"`
	Plan           reconcile.DiffSummary  `json:"plan"`
	FSCKAfter      *FSCKResult            `json:"fsck_after,omitempty"`
	Diagnostics    []reconcile.Diagnostic `json:"diagnostics,omitempty"`
}

HydrateResult reports files restored by hydrate.

type InitDefaults 

type InitDefaults struct {
	SidecarName string
	Visibility  string
	Namespace   string
	Patterns    []string
}

InitDefaults reports the values init should present before user overrides.

type InitOptions 

type InitOptions struct {
	Sidecar      string
	SidecarName  string
	Visibility   string
	Namespace    string
	NamespaceSet bool
	Bootstrap    string
	Patterns     []string
	Track        []string
}

InitOptions configures project bootstrap.

type InitResult 

type InitResult struct {
	Root      string
	Sidecar   string
	Config    config.Config
	HookPath  string
	Gitignore string
}

InitResult reports files changed by init.

type LogOptions added in v0.2.0 

type LogOptions struct {
	Latest       bool
	SourceBranch string
}

LogOptions configures sidecar history output.

type MergeDriverNamespace added in v0.2.0 

type MergeDriverNamespace struct {
	Name   string                   `json:"name"`
	Branch string                   `json:"branch"`
	Digest lockfile.NamespaceDigest `json:"digest"`
	Files  int                      `json:"files"`
	Bytes  int64                    `json:"bytes"`
}

MergeDriverNamespace reports regenerated lock data for one namespace.

type MergeDriverOptions added in v0.2.0 

type MergeDriverOptions struct {
	BasePath    string `json:"base_path,omitempty"`
	CurrentPath string `json:"current_path,omitempty"`
	OtherPath   string `json:"other_path,omitempty"`
}

MergeDriverOptions contains paths passed by Git's custom merge-driver protocol.

type MergeDriverResult added in v0.2.0 

type MergeDriverResult struct {
	LockPath     string                 `json:"lock_path"`
	OutputPath   string                 `json:"output_path,omitempty"`
	Namespaces   []MergeDriverNamespace `json:"namespaces"`
	BasePath     string                 `json:"base_path,omitempty"`
	CurrentPath  string                 `json:"current_path,omitempty"`
	OtherPath    string                 `json:"other_path,omitempty"`
	ChangedFiles int                    `json:"changed_files"`
}

MergeDriverResult reports a regenerated lockfile merge result.

type MutateOptions added in v0.2.0 

type MutateOptions struct {
	DryRun  bool
	JSON    bool
	Force   bool
	Commit  bool
	Message string
}

MutateOptions configures adopt/untrack.

type MutateResult added in v0.2.0 

type MutateResult struct {
	Plan    reconcile.Plan             `json:"plan"`
	Changed []reconcile.TargetDecision `json:"changed"`
	DryRun  bool                       `json:"dry_run,omitempty"`
}

MutateResult reports adopt/untrack changes.

type NamespaceStatus added in v0.1.1 

type NamespaceStatus struct {
	Name            string                   `json:"name"`
	Branch          string                   `json:"branch"`
	LastCommit      string                   `json:"last_commit,omitempty"`
	LastUnix        int64                    `json:"last_unix,omitempty"`
	Remote          string                   `json:"remote"`
	TrackedFiles    int                      `json:"tracked_files"`
	LockedCommit    string                   `json:"locked_commit,omitempty"`
	LockedDigest    lockfile.NamespaceDigest `json:"locked_digest,omitempty"`
	RemoteTip       string                   `json:"remote_tip,omitempty"`
	LocalBranchTip  string                   `json:"local_branch_tip,omitempty"`
	WorktreeHead    string                   `json:"sidecar_worktree_head,omitempty"`
	LockRemoteState string                   `json:"lock_remote_state,omitempty"`
	CloneState      string                   `json:"clone_state,omitempty"`
	Diff            reconcile.ClassCount     `json:"diff"`
	Paths           []reconcile.PathDiff     `json:"paths,omitempty"`
}

NamespaceStatus describes one namespace's sidecar state.

type NamespaceSyncResult added in v0.1.1 

type NamespaceSyncResult struct {
	Name         string                   `json:"name"`
	Branch       string                   `json:"branch"`
	ChangedFiles int                      `json:"changed_files"`
	Committed    bool                     `json:"committed"`
	Commit       string                   `json:"commit"`
	Digest       lockfile.NamespaceDigest `json:"digest"`
	Files        int                      `json:"files"`
	Bytes        int64                    `json:"bytes"`
	Warnings     []reconcile.Diagnostic   `json:"warnings,omitempty"`
}

NamespaceSyncResult reports one namespace sync outcome.

type NamespaceVerification added in v0.2.0 

type NamespaceVerification struct {
	Name     string                   `json:"name"`
	Branch   string                   `json:"branch"`
	Commit   string                   `json:"commit"`
	Digest   lockfile.NamespaceDigest `json:"digest"`
	Expected lockfile.NamespaceDigest `json:"expected_digest"`
	OK       bool                     `json:"ok"`
}

NamespaceVerification reports one namespace verification.

type PatternAddOptions added in v0.2.0 

type PatternAddOptions struct {
	Namespace     string
	Exclude       []string
	AdoptExisting bool
	DryRun        bool
	JSON          bool
	Force         bool
	Commit        bool
	Message       string
}

PatternAddOptions configures pattern add.

type PatternAddResult added in v0.2.0 

type PatternAddResult struct {
	ConfigPath string         `json:"config_path"`
	Gitignore  string         `json:"gitignore"`
	Plan       reconcile.Plan `json:"plan"`
	DryRun     bool           `json:"dry_run,omitempty"`
}

PatternAddResult reports pattern add.

type PatternTestOptions added in v0.2.0 

type PatternTestOptions struct {
	Namespace string
	JSON      bool
}

PatternTestOptions configures pattern test.

type PatternTestResult added in v0.2.0 

type PatternTestResult struct {
	Namespace string   `json:"namespace"`
	Glob      string   `json:"glob"`
	Matches   []string `json:"matches"`
}

PatternTestResult reports pattern test matches.

type PullOptions added in v0.3.0 

type PullOptions struct {
	JSON  bool
	NoGit bool
}

PullOptions configures a Git-like sidecar pull.

type PullResult added in v0.3.0 

type PullResult struct {
	OK          bool                   `json:"ok"`
	GitUpdated  bool                   `json:"git_updated"`
	LockUpdated bool                   `json:"lock_updated"`
	Hydrate     HydrateResult          `json:"hydrate"`
	Diagnostics []reconcile.Diagnostic `json:"diagnostics,omitempty"`
}

PullResult reports a completed sidecar pull.

type ReconcileOptions added in v0.2.1 

type ReconcileOptions struct {
	DryRun     bool
	JSON       bool
	AdoptLocal bool
	PruneLocal bool
	Merge      bool
	Ours       bool
	Theirs     bool
}

ReconcileOptions configures explicit drift reconciliation.

type ReconcileResult added in v0.2.1 

type ReconcileResult struct {
	OK          bool                   `json:"ok"`
	DryRun      bool                   `json:"dry_run,omitempty"`
	Plan        reconcile.DiffSummary  `json:"plan"`
	Hydrate     *HydrateResult         `json:"hydrate,omitempty"`
	Sync        *SyncResult            `json:"sync,omitempty"`
	Rescue      *state.RescueManifest  `json:"rescue,omitempty"`
	Diagnostics []reconcile.Diagnostic `json:"diagnostics,omitempty"`
}

ReconcileResult reports a reconciliation plan or mutation.

type RepairAction added in v0.3.0 

type RepairAction struct {
	Kind    string `json:"kind"`
	Message string `json:"message"`
}

RepairAction describes one repair step that was taken or recommended.

type RepairOptions added in v0.3.0 

type RepairOptions struct {
	Check bool
	JSON  bool
}

RepairOptions configures the public repair workflow.

type RepairResult added in v0.3.0 

type RepairResult struct {
	OK          bool                   `json:"ok"`
	Check       bool                   `json:"check,omitempty"`
	Status      Status                 `json:"status"`
	Verify      VerifyResult           `json:"verify"`
	FSCK        FSCKResult             `json:"fsck"`
	Hooks       hooks.CheckResult      `json:"hooks"`
	Rescues     []state.RescueManifest `json:"rescues,omitempty"`
	Actions     []RepairAction         `json:"actions,omitempty"`
	Diagnostics []reconcile.Diagnostic `json:"diagnostics,omitempty"`
}

RepairResult reports health checks, safe repairs, and remaining issues.

type RepairStatus added in v0.2.0 

type RepairStatus struct {
	Transaction *state.Transaction `json:"transaction,omitempty"`
	Bypass      *state.Bypass      `json:"bypass,omitempty"`
}

RepairStatus reports local-only repair state.

type RescueListResult added in v0.2.1 

type RescueListResult struct {
	Rescues []state.RescueManifest `json:"rescues"`
}

RescueListResult reports known rescue manifests.

type RescueRestoreOptions added in v0.2.1 

type RescueRestoreOptions struct {
	JSON      bool
	Overwrite bool
}

RescueRestoreOptions configures rescue restore.

type RestoreOptions added in v0.3.0 

type RestoreOptions struct {
	DryRun bool
	All    bool
	Paths  []string
}

RestoreOptions configures local file restoration from the locked sidecar state.

type RestoreResult added in v0.3.0 

type RestoreResult struct {
	OK          bool                   `json:"ok"`
	Restored    []string               `json:"restored"`
	Skipped     []string               `json:"skipped,omitempty"`
	Rescue      *state.RescueManifest  `json:"rescue,omitempty"`
	DryRun      bool                   `json:"dry_run,omitempty"`
	Diagnostics []reconcile.Diagnostic `json:"diagnostics,omitempty"`
}

RestoreResult reports files restored from the locked sidecar state.

type Service 

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

Service executes sidecar workflows.

func New 

func New(runner gitexec.Runner) *Service

New returns a sidecar service.

func (*Service) Adopt added in v0.2.0 

func (s *Service) Adopt(ctx context.Context, dir string, targets []string, opts MutateOptions) (MutateResult, error)

Adopt stops tracking files in the main index after sidecar coverage is pushed.

func (*Service) Diff added in v0.2.1 

func (s *Service) Diff(ctx context.Context, dir string, opts DiffOptions) (reconcile.DiffSummary, error)

Diff returns a rich working-tree diff against the lock.

func (*Service) FSCK added in v0.2.0 

func (s *Service) FSCK(ctx context.Context, dir string, opts FSCKOptions) (FSCKResult, error)

FSCK compares working-tree owned specs against skeeper.lock.

func (*Service) HooksCheck added in v0.2.0 

func (s *Service) HooksCheck(ctx context.Context, dir string) (hooks.CheckResult, error)

HooksCheck checks managed hooks.

func (*Service) HooksInstall added in v0.2.0 

func (s *Service) HooksInstall(ctx context.Context, dir string) (hooks.InstallResult, error)

HooksInstall installs managed hooks.

func (*Service) Hydrate 

func (s *Service) Hydrate(ctx context.Context, dir string, options ...HydrateOptions) (HydrateResult, error)

Hydrate clones the sidecar if needed and restores spec files from skeeper.lock.

func (*Service) Init 

func (s *Service) Init(ctx context.Context, dir string, opts InitOptions) (InitResult, error)

Init creates the remote sidecar, clones it, writes config, and installs hooks.

func (*Service) InitDefaults 

func (s *Service) InitDefaults(ctx context.Context, dir string) (InitDefaults, error)

InitDefaults returns deterministic defaults for the project at dir.

func (*Service) Log 

func (s *Service) Log(ctx context.Context, dir, path string, options ...LogOptions) (string, error)

Log returns sidecar history for a mirrored file path.

func (*Service) MergeDriver added in v0.2.0 

func (s *Service) MergeDriver(
	ctx context.Context,
	dir string,
	opts MergeDriverOptions,
) (MergeDriverResult, error)

MergeDriver regenerates skeeper.lock for Git merge-driver invocations.

func (*Service) PatternAdd added in v0.2.0 

func (s *Service) PatternAdd(ctx context.Context, dir, glob string, opts PatternAddOptions) (PatternAddResult, error)

PatternAdd adds a namespace pattern and optionally adopts existing matches.

func (*Service) PatternTest added in v0.2.0 

func (s *Service) PatternTest(
	ctx context.Context,
	dir, glob string,
	opts PatternTestOptions,
) (PatternTestResult, error)

PatternTest reports matches for a candidate glob.

func (*Service) Pull added in v0.3.0 

func (s *Service) Pull(ctx context.Context, dir string, opts PullOptions) (PullResult, error)

Pull fetches sidecar refs, materializes remote-only managed files, and preserves local drift.

func (*Service) Push added in v0.3.0 

func (s *Service) Push(ctx context.Context, dir string, opts SyncOptions) (SyncResult, error)

Push mirrors local managed files into the sidecar without pruning remote-only files by default.

func (*Service) Reconcile added in v0.2.1 

func (s *Service) Reconcile(ctx context.Context, dir string, opts ReconcileOptions) (ReconcileResult, error)

Reconcile reports or applies an explicit local/locked reconciliation.

func (*Service) RecordBypass added in v0.2.0 

func (s *Service) RecordBypass(ctx context.Context, dir, reason string) error

RecordBypass records an audited pre-commit bypass.

func (*Service) Repair added in v0.3.0 

func (s *Service) Repair(ctx context.Context, dir string, opts RepairOptions) (RepairResult, error)

Repair is the single public recovery entry point for local Skeeper state.

func (*Service) RepairAbort added in v0.2.0 

func (s *Service) RepairAbort(ctx context.Context, dir string) error

RepairAbort aborts a transaction before main-index mutation.

func (*Service) RepairResume added in v0.2.0 

func (s *Service) RepairResume(ctx context.Context, dir string) (SyncResult, error)

RepairResume resumes by running a fresh sync with the recorded inputs.

func (*Service) RepairStatus added in v0.2.0 

func (s *Service) RepairStatus(ctx context.Context, dir string) (RepairStatus, error)

RepairStatus returns current repair state.

func (*Service) RescueList added in v0.2.1 

func (s *Service) RescueList(ctx context.Context, dir string) (RescueListResult, error)

RescueList returns local rescue manifests.

func (*Service) RescueRestore added in v0.2.1 

func (s *Service) RescueRestore(
	ctx context.Context,
	dir string,
	id string,
	paths []string,
	opts RescueRestoreOptions,
) (state.RescueManifest, error)

RescueRestore restores files from a rescue manifest.

func (*Service) Restore added in v0.3.0 

func (s *Service) Restore(ctx context.Context, dir string, opts RestoreOptions) (RestoreResult, error)

Restore restores explicit paths from the locked sidecar state.

func (*Service) Status 

func (s *Service) Status(ctx context.Context, dir string, options ...StatusOptions) (Status, error)

Status returns a remote-aware summary suitable for CLI display and CI checks.

func (*Service) Sync 

func (s *Service) Sync(ctx context.Context, dir string, opts SyncOptions) (SyncResult, error)

Sync is the push-only primitive: it mirrors main-tree spec files into the sidecar, pushes, writes, and stages skeeper.lock. The user-facing sync workflow is SyncWorkflow, which pulls before pushing.

func (*Service) SyncWorkflow added in v0.3.0 

func (s *Service) SyncWorkflow(ctx context.Context, dir string, opts SyncOptions) (SyncWorkflowResult, error)

SyncWorkflow runs the Git-like default workflow: pull remote specs, then push local specs.

func (*Service) Track added in v0.3.0 

func (s *Service) Track(ctx context.Context, dir, glob string, opts TrackOptions) (TrackResult, error)

Track adds a public managed glob and optionally syncs matching existing files.

func (*Service) Untrack added in v0.2.0 

func (s *Service) Untrack(ctx context.Context, dir string, targets []string, opts MutateOptions) (MutateResult, error)

Untrack removes main-index tracking while preserving sidecar coverage.

func (*Service) Update added in v0.2.1 

func (s *Service) Update(ctx context.Context, dir string, opts UpdateOptions) (UpdateResult, error)

Update runs the high-level safe clone update workflow.

func (*Service) Verify added in v0.2.0 

func (s *Service) Verify(ctx context.Context, dir string, opts VerifyOptions) (VerifyResult, error)

Verify validates skeeper.lock against the sidecar remote.

type Status 

type Status struct {
	Sidecar     string                 `json:"sidecar"`
	Branch      string                 `json:"branch"`
	OK          bool                   `json:"ok"`
	LockPresent bool                   `json:"lock_present"`
	LockCommit  string                 `json:"lock_commit,omitempty"`
	Namespaces  []NamespaceStatus      `json:"namespaces"`
	Transaction *state.Transaction     `json:"transaction,omitempty"`
	Bypass      *state.Bypass          `json:"bypass,omitempty"`
	HooksOK     bool                   `json:"hooks_ok"`
	Hooks       hooks.CheckResult      `json:"hooks"`
	NextAction  string                 `json:"next_action"`
	Diagnostics []reconcile.Diagnostic `json:"diagnostics,omitempty"`
}

Status describes the current sidecar state.

type StatusOptions added in v0.3.0 

type StatusOptions struct {
	Check bool
	Paths bool
}

StatusOptions configures status output and check behavior.

type SyncOptions 

type SyncOptions struct {
	DryRun  bool
	JSON    bool
	Commit  bool
	Message string
	Hook    bool
	Staged  bool
	Force   bool
	Mirror  bool
	// ResolveOurs is set by explicit reconciliation flows after the user chooses
	// the local side for a sidecar conflict.
	ResolveOurs bool
	// Pull is accepted for older call sites; CLI sync uses SyncWorkflow.
	Pull bool
}

SyncOptions configures a sync run.

type SyncResult 

type SyncResult struct {
	ChangedFiles int                   `json:"changed_files"`
	Committed    bool                  `json:"committed"`
	Commit       string                `json:"commit,omitempty"`
	Namespaces   []NamespaceSyncResult `json:"namespaces"`
	LockPath     string                `json:"lock_path,omitempty"`
	DryRun       bool                  `json:"dry_run,omitempty"`
}

SyncResult reports a completed sync.

type SyncWorkflowResult added in v0.3.0 

type SyncWorkflowResult struct {
	OK     bool       `json:"ok"`
	Pull   PullResult `json:"pull"`
	Push   SyncResult `json:"push"`
	DryRun bool       `json:"dry_run,omitempty"`
}

SyncWorkflowResult reports the high-level pull + push workflow.

type TrackOptions added in v0.3.0 

type TrackOptions struct {
	Namespace string
	Exclude   []string
	Sync      bool
	DryRun    bool
	JSON      bool
	Force     bool
	Commit    bool
	Message   string
}

TrackOptions configures public coverage tracking.

type TrackResult added in v0.3.0 

type TrackResult struct {
	ConfigPath string         `json:"config_path"`
	Gitignore  string         `json:"gitignore"`
	Plan       reconcile.Plan `json:"plan"`
	DryRun     bool           `json:"dry_run,omitempty"`
	Synced     bool           `json:"synced,omitempty"`
}

TrackResult reports a public tracking change.

type UpdateOptions added in v0.2.1 

type UpdateOptions struct {
	JSON      bool
	NoGit     bool
	Reconcile string
	Ours      bool
	Theirs    bool
}

UpdateOptions configures the high-level agent update workflow.

type UpdateResult added in v0.2.1 

type UpdateResult struct {
	OK             bool          `json:"ok"`
	GitUpdated     bool          `json:"git_updated"`
	Verify         VerifyResult  `json:"verify"`
	Hydrate        HydrateResult `json:"hydrate"`
	FSCK           FSCKResult    `json:"fsck"`
	HooksInstalled bool          `json:"hooks_installed"`
	HooksOK        bool          `json:"hooks_ok"`
}

UpdateResult reports update workflow steps.

type VerifyOptions added in v0.2.0 

type VerifyOptions struct {
	JSON         bool
	Hook         bool
	SourceBranch string
}

VerifyOptions configures lock verification.

type VerifyResult added in v0.2.0 

type VerifyResult struct {
	OK          bool                    `json:"ok"`
	Namespaces  []NamespaceVerification `json:"namespaces"`
	Diagnostics []reconcile.Diagnostic  `json:"diagnostics,omitempty"`
}

VerifyResult reports lock verification.

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.