common

package
v1.0.3 Latest Latest
Warning

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

 Go to latest Published: May 13, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package common provides shared infrastructure for tool adapters, including the Installer lifecycle (Prepare → Apply → Verify → Rollback).

Index

Constants

View Source 
const Version = "0.1.0"

Version is the canonical Sequoia version string shared across all adapters and the CLI. It is embedded in installed skill files, system prompts, and the .sequoia-version marker file.

Variables

View Source 
var CommandFS embed.FS
View Source 
var CommandFiles = []string{
	"sequoia-init.md",
	"sequoia-audit.md",
	"sequoia-review.md",
	"sequoia-fix.md",
	"sequoia-diff.md",
}

CommandFiles is the ordered list of command template filenames shared by all adapters. Each adapter's embed.FS must contain these files under a "templates/commands/" directory.

Functions

func AtomicWriteFile added in v1.0.3 

func AtomicWriteFile(path string, data []byte, perm os.FileMode) error

AtomicWriteFile writes data to path atomically using a temporary file and rename. On Windows this prevents truncated files on crash, where os.WriteFile truncates in place. The temporary file is cleaned up if the rename fails.

func InjectMarkdownSection added in v1.0.3 

func InjectMarkdownSection(path, content string) error

InjectMarkdownSection writes content into the Markdown file at path between <!-- sequoia:start --> and <!-- sequoia:end --> markers. If the file does not exist it is created with the section. If markers are already present the content between them is replaced. Otherwise the section is appended at the end of the file. 

func IsSymlink(home string) bool

IsSymlink reports whether resolving home produces a different path, which implies the presence of a symlink somewhere in the path.

func RemoveMarkdownSection added in v1.0.3 

func RemoveMarkdownSection(path string) error

RemoveMarkdownSection deletes the content between <!-- sequoia:start --> and <!-- sequoia:end --> markers from the file at path. Returns nil when the file does not exist or contains no markers.

func RenderTemplate 

func RenderTemplate(fs embed.FS, name string, data interface{}) (string, error)

RenderTemplate reads the named file from fs, parses it as a text/template, and executes it with data. Parsed templates are cached in a sync.Map so each (fs, name) pair is only parsed once. The data parameter is passed directly to template.Execute and can be any type that the template references.

func RenderTemplateLang added in v1.0.3 

func RenderTemplateLang(fs embed.FS, name string, lang string, data interface{}) (string, error)

RenderTemplateLang renders a template with language-aware resolution. It first tries the language-specific file ("{name}.{lang}.tmpl"), and if that file does not exist in the embedded FS, falls back to the base name ("{name}.tmpl") for backward compatibility with existing templates that do not have language suffixes.

Parsed templates are cached using the same sync.Map cache as RenderTemplate, keyed by (FS pointer, resolved name).

func ReplaceFile added in v1.0.3 

func ReplaceFile(path, content string) error

ReplaceFile writes content to the file at path, creating a backup with a timestamped name at path+".sequoia-backup-<suffix>" if the file already exists and is not Sequoia-managed. A session-tracking file at path+".sequoia-session" records the backup suffix so that RestoreOrRemoveFile can locate the correct backup during uninstall. Creates parent directories if needed.

func ResolveHome 

func ResolveHome(base string) (string, error)

ResolveHome resolves base to its canonical path by evaluating all symlinks. On Windows, calling filepath.EvalSymlinks on a non-existent path returns an error. On Unix, it returns the path as-is.

Returns an error if the path does not exist or cannot be resolved. 

func ResolveSymlink(path string) (resolved string, warning string)

ResolveSymlink resolves path via filepath.EvalSymlinks. If resolution succeeds, the resolved path is returned with no warning. If resolution fails:

  • If the path is a symlink (detected via os.Lstat), the original path is returned along with a warning message containing the unresolved path.
  • If the path is not a symlink (or Lstat itself fails), the original path is returned without a warning.

func RestoreOrRemoveFile added in v1.0.3 

func RestoreOrRemoveFile(path string) error

RestoreOrRemoveFile restores the original content from the session-tracked backup (path+".sequoia-backup-<suffix>") if a .sequoia-session file exists. If no session file is found, it falls back to the legacy predictable backup name (path+".sequoia-backup") for backwards compatibility. If the file is Sequoia-managed and has no backup, it deletes the file. If the file doesn't exist or is not managed and has no backup, returns nil.

func StageFile 

func StageFile(dir, name string, content []byte) error

StageFile writes content to filepath.Join(dir, name), creating dir and any missing parent directories (mode 0o755). The file itself is written with mode 0o644.

Types

type BaseAdapter added in v1.0.3 

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

BaseAdapter provides shared Install, Uninstall, Status, and path methods for tool adapters. Concrete adapters embed BaseAdapter and set the function fields to customize path resolution, detection, and system prompt handling.

The Install/Uninstall flow follows the same 8-step pattern for all adapters; only the system prompt strategy and path layout differ.

func (*BaseAdapter) AddWarning added in v1.0.3 

func (a *BaseAdapter) AddWarning(msg string)

AddWarning appends a non-fatal warning message. Thread-safe.

func (*BaseAdapter) CommandsPath added in v1.0.3 

func (a *BaseAdapter) CommandsPath() string

CommandsPath returns the absolute path to the commands directory.

func (*BaseAdapter) Detect added in v1.0.3 

func (a *BaseAdapter) Detect() bool

Detect reports whether the tool is present on this machine.

func (*BaseAdapter) HomeDir added in v1.0.3 

func (a *BaseAdapter) HomeDir() string

HomeDir returns the current home directory override (empty string means production — os.UserHomeDir() is used by the resolveBase function).

func (*BaseAdapter) ID added in v1.0.3 

func (a *BaseAdapter) ID() string

ID returns the unique machine-readable identifier.

func (*BaseAdapter) Install added in v1.0.3 

func (a *BaseAdapter) Install(opts adapters.InstallOpts) (err error)

Install installs Sequoia files using the common 9-step pattern. The system prompt strategy is delegated to writeSystemPrompt.

When opts.Context is set and cancelled, Install aborts early and rolls back any partial work before returning the context error.

On failure, the returned error wraps adapters.ErrInstallFailed so callers can detect install failures with errors.Is(err, adapters.ErrInstallFailed).

func (*BaseAdapter) IsInstalled added in v1.0.3 

func (a *BaseAdapter) IsInstalled() bool

IsInstalled reports whether Sequoia has already been installed.

func (*BaseAdapter) Name added in v1.0.3 

func (a *BaseAdapter) Name() string

Name returns the human-readable display name.

func (*BaseAdapter) PromptStrategy added in v1.0.3 

func (a *BaseAdapter) PromptStrategy() adapters.PromptStrategy

PromptStrategy returns the injection strategy used by this adapter.

func (*BaseAdapter) ResolveBase added in v1.0.3 

func (a *BaseAdapter) ResolveBase(fn func(homeDir string) (string, error))

ResolveBase sets the base directory resolution function.

func (*BaseAdapter) SetDetectFn added in v1.0.3 

func (a *BaseAdapter) SetDetectFn(fn func() bool)

SetDetectFn sets the function that detects whether the tool is present.

func (*BaseAdapter) SetHomeDir added in v1.0.3 

func (a *BaseAdapter) SetHomeDir(dir string)

SetHomeDir overrides the user home directory (for testing).

func (*BaseAdapter) SetIDName added in v1.0.3 

func (a *BaseAdapter) SetIDName(id, name string)

SetIDName sets the adapter's unique ID and human-readable name.

func (*BaseAdapter) SetInstallTemplates added in v1.0.3 

func (a *BaseAdapter) SetInstallTemplates(fs embed.FS, stagingPrefix, sysPromptTmpl string, makeData func() interface{})

SetInstallTemplates sets the template embed.FS, staging prefix, system prompt template name, and the function that produces template data.

func (*BaseAdapter) SetIsInstalledFn added in v1.0.3 

func (a *BaseAdapter) SetIsInstalledFn(fn func(base string) bool)

SetIsInstalledFn sets the function that checks if Sequoia is installed.

func (*BaseAdapter) SetPathFns added in v1.0.3 

func (a *BaseAdapter) SetPathFns(skills, commands, systemPrompt, versionFile, backup func(base string) string)

SetPathFns sets all five path functions at once.

func (*BaseAdapter) SetRollbackOnSystemPromptError added in v1.0.3 

func (a *BaseAdapter) SetRollbackOnSystemPromptError(v bool)

SetRollbackOnSystemPromptError enables or disables rollback of skill and command installers when the system prompt step fails during Install().

func (*BaseAdapter) SetStrategy added in v1.0.3 

func (a *BaseAdapter) SetStrategy(strategy adapters.PromptStrategy, write func(base, content string) error, remove func(base string) error)

SetStrategy sets the prompt strategy and its write/remove functions.

func (*BaseAdapter) SkillsPath added in v1.0.3 

func (a *BaseAdapter) SkillsPath() string

SkillsPath returns the absolute path to the skills directory.

func (*BaseAdapter) Status added in v1.0.3 

func (a *BaseAdapter) Status() adapters.AdapterStatus

Status returns the current installation status.

func (*BaseAdapter) SystemPromptPath added in v1.0.3 

func (a *BaseAdapter) SystemPromptPath() string

SystemPromptPath returns the absolute path to the system prompt file.

func (*BaseAdapter) Uninstall added in v1.0.3 

func (a *BaseAdapter) Uninstall(opts adapters.InstallOpts) (err error)

Uninstall removes Sequoia files using the common pattern. The system prompt strategy is delegated to removeSystemPrompt.

When opts.Context is set and cancelled, Uninstall returns early without modifying any files.

Errors from individual file removals are collected via errors.Join. Missing files are not treated as errors (os.IsNotExist is checked). On failure, the returned error wraps adapters.ErrUninstallFailed so callers can detect uninstall failures with errors.Is.

func (*BaseAdapter) Warnings added in v1.0.3 

func (a *BaseAdapter) Warnings() []string

Warnings returns a copy of all accumulated warning messages. Thread-safe.

type Installer 

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

Installer manages the four-phase install lifecycle for a ToolAdapter. The expected call order is: Prepare → Apply → Verify. On any failure in Apply or Verify, the caller should invoke Rollback.

func NewInstaller 

func NewInstaller(cfg InstallerConfig) *Installer

NewInstaller creates an Installer from the given config.

func (*Installer) Apply 

func (i *Installer) Apply() error

Apply copies files from SourceDir to TargetDir. It MUST be called after a successful Prepare. Returns an error if any file copy fails. Apply does NOT call Rollback on failure — the caller is responsible.

func (*Installer) Prepare 

func (i *Installer) Prepare() error

Prepare validates paths, checks write permissions, and backs up existing files. It MUST be called before Apply. Returns an error if TargetDir is not writable or any backup fails.

func (*Installer) Rollback 

func (i *Installer) Rollback() error

Rollback restores files backed up during Prepare, then removes the backup directory. It also removes any files listed in i.applied that were NOT backed up (clean installs with no prior state). Safe to call even if Apply was never called. Returns the first error encountered, but continues restoring all files.

func (*Installer) Run 

func (i *Installer) Run() error

Run executes the full Prepare → Apply → Verify cycle. On Apply or Verify failure it calls Rollback (best-effort) and returns the original error. This is the convenience wrapper that most adapters use instead of calling each phase individually.

func (*Installer) Verify 

func (i *Installer) Verify() error

Verify checks that all installed files exist and are readable. It MUST be called after a successful Apply. Returns an error if any expected file is missing or unreadable.

type InstallerConfig 

type InstallerConfig struct {
	// SourceDir is the directory containing the template files to install.
	SourceDir string
	// TargetDir is the destination directory where files will be placed.
	TargetDir string
	// BackupDir is where existing files are backed up during Prepare.
	BackupDir string
	// Files is the list of filenames (relative to SourceDir/TargetDir) to install.
	Files []string
}

InstallerConfig holds everything the Installer needs to run.

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.