sitesync

package
v0.28.1 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package sitesync syncs Creght site code between a local directory and the platform: the pull, diff, push, resolve and version list of the creght CLI, as a library. The CLI's own commands run through this package, so the two never drift apart.

A directory synced with this package is an ordinary creght workspace — .creght/state.json, the recorded base under .creght/base/, conflict markers (<<<<<<< local / ======= / >>>>>>> remote) and .creghtignore are exactly what the CLI reads and writes — so the CLI and this package can take turns on the same directory.

The package never starts a process and never touches the CLI's config.json: the caller names the API host and supplies the token.

c, err := sitesync.New(sitesync.Options{
	Host:  "https://creght.cn",
	Token: func(ctx context.Context) (string, error) { return oauth.AccessToken(ctx) },
	Log:   os.Stderr,
})
site, _ := sitesync.ParseSite("p9ok3myl0ne6/p9ok3mzxgpzm")
res, err := c.Pull(ctx, "./site", site, sitesync.PullOptions{})
diff, err := c.Diff(ctx, "./site", sitesync.DiffOptions{Delete: true})
pushed, err := c.Push(ctx, "./site", sitesync.PushOptions{Delete: true})

Index

Constants

This section is empty.

Variables

View Source
var ErrUnauthorized = creght.ErrUnauthorized

ErrUnauthorized matches (with errors.Is) an error from a request the platform answered with 401: the token is missing, expired or revoked.

Functions

func Conflicts

func Conflicts(dir string) ([]string, error)

Conflicts lists the files of the workspace in dir that still hold conflict markers, as site paths such as /page/Index.tsx (creght resolve --list).

func IsUnauthorized

func IsUnauthorized(err error) bool

IsUnauthorized reports whether err came from a 401.

func Resolve

func Resolve(dir string, path string, side Side) (int, error)

Resolve settles every conflict block in one file of the workspace in dir by keeping one side, and returns how many blocks it resolved (creght resolve). path is the site path, with or without the leading slash ("page/Index.tsx" or "/page/Index.tsx"). Purely local; push uploads it.

Types

type Client

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

Client syncs workspaces against one Creght deployment.

func New

func New(opts Options) (*Client, error)

New returns a Client for opts.Host.

func (*Client) Diff

func (c *Client) Diff(ctx context.Context, dir string, opts DiffOptions) (DiffResult, error)

Diff compares the workspace in dir with the remote site against the recorded base, without changing anything (creght diff --json). A conflict does not make it fail; check DiffResult.HasConflicts.

func (*Client) Host

func (c *Client) Host() string

Host is the canonical API host the client talks to.

func (*Client) Pull

func (c *Client) Pull(ctx context.Context, dir string, site Site, opts PullOptions) (PullResult, error)

Pull brings the site into dir: a new directory, or a workspace of the same site, whose local edits are three-way merged with the remote ones against the recorded base (creght pull). With opts.VersionNo it pulls a read-only version snapshot instead.

func (*Client) Push

func (c *Client) Push(ctx context.Context, dir string, opts PushOptions) (PushResult, error)

Push uploads the workspace in dir (creght push). Without Force it refuses when a file changed both locally and remotely since the last pull — pull first to merge — unless SkipConflicts is set.

func (*Client) Versions

func (c *Client) Versions(ctx context.Context, site Site) (PublishState, error)

Versions returns the site's versions (creght version list).

type DiffEntry

type DiffEntry = workspace.DiffEntry

DiffEntry is one file of a DiffResult. Status is one of

local-change    push would upload it; Action is file_create, file_update or file_delete
conflict        changed on both sides (or still holds conflict markers); push refuses
remote-only     changed only remotely; pull brings it in
no-base         differs from the remote with no recorded base
ignored-remote  hidden by .creghtignore but still on the site

type DiffOptions

type DiffOptions struct {
	// Delete plans remote deletions for files removed locally (diff --delete).
	Delete bool
}

DiffOptions are diff's flags.

type DiffResult

type DiffResult = workspace.DiffResult

DiffResult is the change plan, exactly as creght diff --json prints it.

type FileChange

type FileChange = workspace.FileChange

FileChange is one change made to the remote site. Action is file_create, file_update or file_delete.

type Options

type Options struct {
	// Host is the API host of the Creght deployment, e.g. https://creght.cn.
	Host string
	// Token returns the access token to send. It is called before every
	// request, so a caller that refreshes its token can return the fresh one.
	// A nil Token sends no token, which only public reads accept.
	Token func(ctx context.Context) (string, error)
	// Log receives the progress and plan lines the CLI prints (merged files,
	// conflicts, "synced N files"). Nil discards them.
	Log io.Writer
}

Options configures a Client.

type PublishState

type PublishState = creght.SitePublishState

PublishState is a site's versions and publish targets, exactly as creght version list --json prints it. For a reader of a public-copy project that is not a member, ReadOnly is set and only the versions and the live version are filled.

type PullOptions

type PullOptions struct {
	// VersionNo, when set, pulls that site version as a read-only snapshot
	// (pull --version_no): the directory is made to match the version
	// exactly, deleting everything else except .git and .creght at its root,
	// and push, diff and resolve refuse to run there. The directory must be
	// new, empty, or already a snapshot.
	VersionNo int64
	// Force overwrites local files with the remote workspace instead of
	// merging (pull --force); overwritten local work is backed up under
	// .creght/backup/. Ignored with VersionNo.
	Force bool
	// SkipAgentsFile leaves out the AGENTS.md a pull writes into a workspace
	// that has none. Ignored with VersionNo.
	SkipAgentsFile bool
}

PullOptions are pull's flags.

type PullResult

type PullResult struct {
	Dir     string
	Changed int
	// Merged are files changed on both sides whose edits merged cleanly.
	Merged []string
	// Conflicted are files changed on both sides with overlapping edits; they
	// now hold conflict markers. Pull still succeeds — the CLI turns a
	// non-empty Conflicted into a failing exit — and push refuses until each
	// is edited or settled with Resolve.
	Conflicted []string
	// BackupDir is where overwritten local work was saved, if anything was.
	BackupDir         string
	AgentsFileCreated bool
	// Snapshot is set for a VersionNo pull.
	Snapshot *Snapshot
}

PullResult reports what Pull did.

type PushOptions

type PushOptions struct {
	// Delete deletes remote files removed locally (push --delete).
	Delete bool
	// Force overwrites the remote site with the local workspace without the
	// three-way check (push --force). It uploads every differing file and
	// deletes every remote file missing locally whether or not Delete is set;
	// remote edits it overwrites are backed up under .creght/backup/.
	Force bool
	// SkipConflicts pushes everything else when some files conflict, leaving
	// those for a later pull (push --skip-conflicts).
	SkipConflicts bool
}

PushOptions are push's flags.

type PushResult

type PushResult struct {
	Changes []FileChange
	// SkippedConflicts are the files SkipConflicts left out.
	SkippedConflicts []string
}

PushResult reports what Push changed.

type Side

type Side string

Side picks which half of a conflict Resolve keeps.

const (
	// Ours keeps the local side (creght resolve --ours).
	Ours Side = "ours"
	// Theirs keeps the remote side (creght resolve --theirs).
	Theirs Side = "theirs"
)

type Site

type Site struct {
	ProjectID string
	SiteID    string
}

Site names one site of a project.

func ParseSite

func ParseSite(ref string) (Site, error)

ParseSite parses the CLI's "<project_id>/<site_id>" form.

func (Site) String

func (s Site) String() string

String is the "<project_id>/<site_id>" form.

type Snapshot

type Snapshot struct {
	VersionNo int64
	// VersionID and Note are labels from the publish state; zero or empty
	// when it could not be read.
	VersionID int64
	Note      string
	// Files is how many files the version has; Removed is how many files the
	// directory held that the version does not, and were deleted.
	Files   int
	Removed int
}

Snapshot describes a version pulled with PullOptions.VersionNo.

type Version

type Version = creght.SiteVersion

Version is one entry of PublishState.Versions.

type Workspace

type Workspace struct {
	Dir  string
	Site Site
	// APIHost is the deployment the workspace was pulled from; empty for
	// workspaces pulled by old CLI versions.
	APIHost string
	// SnapshotVersionNo is set when the directory holds a read-only version
	// snapshot (pulled with PullOptions.VersionNo) rather than a workspace.
	SnapshotVersionNo int64
}

Workspace is what .creght/state.json records about a directory.

func OpenWorkspace

func OpenWorkspace(dir string) (Workspace, error)

OpenWorkspace reads dir's .creght/state.json. dir must be the workspace root.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL