client

type AdminOpts struct {
	// Server maps to --server <s>: the server to operate on.
	Server string
	// Force maps to --force where the subcommand supports it.
	Force bool
}

type Backend int

type BuildOpts struct {
	// Keep, if true, leaves the staging build directory in place after a
	// successful build for debugging. Default removes it.
	Keep bool
}

type ConfigOpts struct {
	// Key, if set, is the `key` positional: prints that entry's value. Empty
	// prints the whole effective configuration.
	Key string
	// Value, if set, is the `value` positional: writes Key=Value instead of
	// printing.
	Value string
	// Unset maps to --unset: delete Key from the configuration file.
	Unset bool
	// Scope maps to --scope <scope> {system,user,project}.
	Scope string
	// JSON maps to --json: output as JSON.
	JSON bool
}

type DepsPolicy int

type DocOpts struct {
	// Version, if set, is the `version` positional.
	Version string
	// Home maps to --home: open the project home page.
	Home bool
	// List maps to --list: list documentation files only.
	List bool
}

type DownloadOpts struct {
	// Version, if set, is the `version` positional: an exact version, or any
	// constraint expression deps.ParseConstraints accepts.
	Version string
	// All downloads every match instead of the single best one (--all). It is
	// also what makes an empty name legal, and that combination downloads
	// every rock the servers offer.
	All bool
	// Source restricts the download to the `.src.rock` (--source). Mutually
	// exclusive with Rockspec and Arch, which upstream enforces as a parser
	// mutex; setting two is an error, not a silent pick.
	Source bool
	// Rockspec restricts the download to the bare `.rockspec` (--rockspec).
	// Mutually exclusive with Source and Arch.
	Rockspec bool
	// Arch restricts the download to one manifest arch (--arch <arch>), e.g.
	// "all" or "linux-x86_64". Mutually exclusive with Source and Rockspec.
	Arch string
	// Servers are searched BEFORE the configured Config.Servers rather than
	// instead of them, which is what upstream's --server does — see
	// SearchOpts.Servers for why this differs from InstallOpts.Servers.
	Servers []string
}

type Engine interface {
	// The eight operations the native backend already implements.
	Install(ctx context.Context, name string, opts InstallOpts) error
	Build(ctx context.Context, specPath string, opts BuildOpts) error
	Make(ctx context.Context, opts MakeOpts) error
	Pack(ctx context.Context, target string, opts PackOpts) (string, error)
	Unpack(ctx context.Context, archive, destDir string) error
	Remove(ctx context.Context, name string, opts RemoveOpts) error
	Search(ctx context.Context, pattern string, opts SearchOpts) ([]SearchResult, error)
	Download(ctx context.Context, name string, opts DownloadOpts) (string, error)

	// The ten operations not yet implemented by the native backend.
	// Until a backend implements them they return rocks.ErrNotImplemented.
	Purge(ctx context.Context, opts PurgeOpts) error
	Lint(ctx context.Context, specPath string, opts LintOpts) error
	NewVersion(ctx context.Context, specPath string, opts NewVersionOpts) (string, error)
	WriteRockspec(ctx context.Context, url string, opts WriteRockspecOpts) (string, error)
	Doc(ctx context.Context, name string, opts DocOpts) error
	Test(ctx context.Context, specPath string, opts TestOpts) error
	Config(ctx context.Context, opts ConfigOpts) (string, error)
	Upload(ctx context.Context, specPath string, opts UploadOpts) error
	InitProject(ctx context.Context, opts InitProjectOpts) error
	Admin(ctx context.Context, subCmd string, args []string, opts AdminOpts) error
}

type InitProjectOpts struct {
	// Name, if set, is the `name` positional (the project name). Empty lets
	// upstream derive it from the working directory.
	Name string
	// Version, if set, is the `version` positional.
	Version string
	// Reset maps to --reset: delete and regenerate the project config and
	// ./lua tree.
	Reset bool
}

type InstallOpts struct {
	// Version, if set, narrows the candidate set to those matching this
	// constraint (parsed via deps.ParseConstraints). Empty means "any
	// version satisfying the rockspec's transitive constraints" — i.e.
	// the resolver picks the newest.
	Version string

	// Servers overrides r.cfg.Servers for this Install. Empty means use
	// the facade's configured servers.
	Servers []string

	// Deps controls whether transitive dependencies are also installed.
	Deps DepsPolicy
}

type InstalledRock = rocks.InstalledRock

type LintOpts struct{}

type MakeOpts struct {
	// RockspecPath, if non-empty, names the rockspec to build. Empty
	// means search r.cfg.WorkingDir for exactly one `*.rockspec`.
	RockspecPath string
}

type NewVersionOpts struct {
	// NewVersion, if set, is the `new_version` positional.
	NewVersion string
	// NewURL, if set, is the `new_url` positional (requires NewVersion).
	NewURL string
	// Dir maps to --dir <dir>: output directory for the new rockspec.
	Dir string
	// Tag maps to --tag <tag>: new SCM tag.
	Tag string
}

type Option func(*Rocks)

type PackOpts struct {
	// SrcOnly, if true, produces a `.src.rock` containing the rockspec
	// and original source archive rather than a deployable `.rock`.
	SrcOnly bool
}

type PurgeOpts struct {
	// OldVersions maps to --old-versions: keep the highest version of each
	// rock and remove the rest.
	OldVersions bool
	// Force maps to --force: with --old-versions, force removal even if it
	// would break dependencies.
	Force bool
	// ForceFast maps to --force-fast: like Force but without dependency
	// reporting.
	ForceFast bool
}

type RemoveOpts struct {
	// Version, if set, restricts removal to that exact version; empty removes
	// all versions of the rock (the `version` positional).
	Version string
	// Force maps to --force: remove even if it would break dependencies.
	Force bool
	// ForceFast maps to --force-fast: forced removal without reporting
	// dependency issues.
	ForceFast bool
	// Deps maps to --deps-mode {all,one,order,none}.
	Deps DepsPolicy
}

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

type SearchOpts struct {
	// Version, if set, is the `version` positional to search for.
	Version string
	// Source maps to --source: return only rockspecs and source rocks.
	Source bool
	// Binary maps to --binary: return only pure-Lua and binary rocks.
	Binary bool
	// All maps to --all: list all suitable contents of the server(s).
	All bool
	// Servers, when non-empty, are searched BEFORE the servers in
	// Config.Servers rather than instead of them — upstream's --server
	// prepends to cfg.rocks_servers (cmd.lua:130), and a search reports
	// everything that matches anywhere. Note this differs from
	// InstallOpts.Servers, which overrides the configured list: an install
	// picks one artifact, so restricting where it may come from is the useful
	// meaning there.
	//
	// The lua backend appends a --server <s> global option per entry.
	Servers []string
}

type SearchResult struct {
	// Name is the matched rock name.
	Name string
	// Version is the matched version-revision string.
	Version string
	// Arch is the manifest arch of this offering: "rockspec" for a bare
	// .rockspec, "src" for a source rock, "all" for a pure-Lua binary rock, a
	// concrete "<os>-<cpu>" for a host-built one, or "installed" for a rock
	// the Lua VM provides. It is what tells a rockspec from an installable
	// binary rock, so tt needs it to decide between build and install.
	Arch string
	// Server is the repository the match came from, normalized as
	// dir.normalize renders it: a local directory reads as a plain path with
	// no file:// prefix and no trailing slash. A rock provided by the VM
	// carries the pseudo-server "provided by VM or rocks_provided".
	Server string
	// Namespace is the namespace the match was found under, empty when the
	// search carried none (the porcelain line then has only four fields).
	Namespace string
}

type ShowInfo = rocks.ShowInfo

type TestOpts struct {
	// Prepare maps to --prepare: install test deps only, do not run the suite.
	Prepare bool
	// TestType maps to --test-type <type>: select the test suite type.
	TestType string
	// Args are passed through as the trailing `args` positionals to the suite.
	Args []string
}

type UploadOpts struct {
	// SrcRock, if set, is the `src-rock` positional (a matching .src.rock).
	SrcRock string
	// SkipPack maps to --skip-pack: do not pack and send the source rock.
	SkipPack bool
	// APIKey maps to --api-key <key>.
	APIKey string
	// TempKey maps to --temp-key <key>.
	TempKey string
	// Force maps to --force: replace an existing rockspec of the same revision.
	Force bool
	// Sign maps to --sign: upload a signature file alongside each file.
	Sign bool
}

type WriteRockspecOpts struct {
	// Name, if set, is the `name` positional.
	Name string
	// Version, if set, is the `version` positional.
	Version string
	// Output maps to --output <file>: write the rockspec with this filename.
	Output string
	// License maps to --license <string>.
	License string
	// Summary maps to --summary <txt>.
	Summary string
	// Detailed maps to --detailed <txt>.
	Detailed string
	// Homepage maps to --homepage <txt>.
	Homepage string
	// LuaVersions maps to --lua-versions <ver>.
	LuaVersions string
	// RockspecFormat maps to --rockspec-format <ver>.
	RockspecFormat string
	// Tag maps to --tag <tag>.
	Tag string
	// Lib maps to --lib <libs>: comma-separated C libraries to link to.
	Lib string
}