packops

type AddDoc struct {
	SchemaVersion  int                                         `json:"schema_version"`
	DryRun         bool                                        `json:"dry_run,omitempty"`
	Pack           string                                      `json:"pack"`
	Skills         []string                                    `json:"skills"`
	Agents         []string                                    `json:"agents"`
	Rules          []string                                    `json:"rules,omitempty"`
	Wiring         bool                                        `json:"wiring"`
	Unresolved     []string                                    `json:"unresolved,omitempty"`
	Skipped        []string                                    `json:"skipped,omitempty"`
	Warnings       []string                                    `json:"warnings,omitempty"`
	Variables      map[string]skills.LockedVariableDeclaration `json:"variables,omitempty"`
	UnmetVariables []VariableRequirement                       `json:"unmet_variables,omitempty"`
	Stack          *StackSummary                               `json:"stack,omitempty"`
	Sources        []SourceSummary                             `json:"sources,omitempty"`
}

type AddOptions struct {
	Repo   string
	Ref    string
	Path   string
	Trust  bool
	DryRun bool
	// BlockOnFindings refuses the whole import with a *FindingsError
	// before any write when the resolved selection carries security
	// findings and Trust is false. The CLI leaves it false (partial
	// import with per-resource skips, its documented contract); the REST
	// layer sets it so a 409 can never follow a half-done import.
	BlockOnFindings bool
	// Auth authenticates the pack repository clone. A token or vault
	// reference here never applies to an external source. An ssh-key
	// path is reused for SSH sources that resolved no other auth.
	Auth skills.AuthConfig
	// SourceAuth is an explicit per-source override, keyed by source name.
	// A present key wins even when the value is zero. Omitted keys fall
	// through to stored member auth, the manifest, then ambient.
	SourceAuth map[string]skills.AuthConfig
	// Resolver expands manifest and stored credential references. Nil means
	// a credential_ref on a source is an error for that source.
	Resolver skills.CredentialResolver
}

type AddResult struct {
	Doc   AddDoc
	Notes []string
}

type ApplyDoc struct {
	SchemaVersion int    `json:"schema_version"`
	Pack          string `json:"pack"`
	DryRun        bool   `json:"dry_run,omitempty"`
	Applied       int    `json:"applied"`
	Total         int    `json:"total"`
	Rows          []Row  `json:"rows"`
}

type ApplyOptions struct {
	Force  bool
	DryRun bool
	// Clients restricts wiring to these client slugs.
	Clients []string
	// Port is the gateway port passed to the stack launcher. Zero means
	// the launcher's default (the CLI passes 8180).
	Port int
}

type Counts struct {
	Skills int  `json:"skills"`
	Agents int  `json:"agents"`
	Rules  int  `json:"rules"`
	Wiring bool `json:"wiring"`
	// Stack is true when the pack carries a resolved stack record.
	// omitempty keeps packs without a stack on the previous JSON shape.
	Stack bool `json:"stack,omitempty"`
	// Sources is the number of pinned external sources. omitempty keeps
	// packs without sources on the previous JSON shape.
	Sources int `json:"sources,omitempty"`
}

type FindingsError struct {
	Pack      string
	Resources []PreviewResource
}

type LaunchOptions struct {
	StackPath string
	Port      int
	Replace   bool
}

type LaunchResult struct {
	StackName string
	Port      int
}

type Managers struct {
	Skills   *skillsync.Manager
	Agents   *agentsync.Manager
	Wiring   *wiring.Manager
	Contexts *contexts.Manager
	Home     string
	// LockPath overrides the import lockfile path (skills.lock.yaml).
	// Empty means the HOME-derived default. Callers that inject a custom
	// lockfile path into their importer (the API server) must set the
	// same path here, or the importer and the pack record would write
	// two different files.
	LockPath string
	// Launcher deploys a pack-carried stack. Nil means this interface
	// cannot start a gateway (the REST server in this release).
	Launcher StackLauncher
	// StoredVariables reports vault keys. available is false when the
	// store cannot be read (locked or unset); the apply gate then falls
	// through to the loader instead of prompting.
	StoredVariables func() (keys map[string]bool, available bool)
}

type Origin struct {
	Source    string    `json:"source"`
	Repo      string    `json:"repo"`
	Ref       string    `json:"ref,omitempty"`
	CommitSHA string    `json:"commit_sha,omitempty"`
	FetchedAt time.Time `json:"fetched_at,omitempty"`
}

type PackInfo struct {
	Name        string   `json:"name"`
	Version     string   `json:"version,omitempty"`
	Description string   `json:"description,omitempty"`
	Author      string   `json:"author,omitempty"`
	Origin      Origin   `json:"origin"`
	Counts      Counts   `json:"counts"`
	Unresolved  []string `json:"unresolved,omitempty"`
	// Applied reports whether any per-client projection exists: an
	// imported-but-never-applied pack is registry-only, and list views
	// surface that as attention rather than reading healthy.
	Applied bool `json:"applied"`
	// Collision marks a pack name claimed by more than one source; the
	// listed repos disambiguate. Detail fetches for a colliding name
	// refuse instead of picking one.
	Collision      bool            `json:"collision,omitempty"`
	CollisionRepos []string        `json:"collision_repos,omitempty"`
	Sources        []SourceSummary `json:"sources,omitempty"`
}

type PackRuleFile struct {
	Name string
	Path string // absolute path on disk in the clone
	// Rel is the path within the pack repo, recorded as provenance so a
	// later install can name where the rule came from. Clone paths are
	// temporary and must never be persisted.
	Rel string
}

type PackStatus struct {
	Info           PackInfo `json:"info"`
	Rows           []Row    `json:"rows"`
	NeedsAttention bool     `json:"needs_attention"`
}

type PreviewOptions struct {
	Repo string
	Ref  string
	Path string
	// Auth authenticates the pack repository clone. A token here never
	// applies to an external source.
	Auth skills.AuthConfig
	// SourceAuth is an explicit per-source override, keyed by source name.
	SourceAuth map[string]skills.AuthConfig
	// LockPath is the import lockfile used to reuse stored member auth.
	// Empty means the HOME-derived default.
	LockPath string
	// Resolver expands manifest and stored credential references.
	Resolver skills.CredentialResolver
}

type PreviewResource struct {
	Kind     string                   `json:"kind"`
	Name     string                   `json:"name"`
	Findings []skills.SecurityFinding `json:"findings,omitempty"`
	// Blocking mirrors the import gate exactly: body findings always
	// block; supporting-file findings block only at danger severity.
	// Non-blocking findings stay visible without forcing a trust grant.
	Blocking bool `json:"blocking,omitempty"`
	// Source is the external source name. Empty for the pack repository.
	Source string `json:"source,omitempty"`
}

type PreviewResult struct {
	Pack        string            `json:"pack"`
	Version     string            `json:"version,omitempty"`
	Description string            `json:"description,omitempty"`
	Author      string            `json:"author,omitempty"`
	Wiring      bool              `json:"wiring"`
	Clients     []string          `json:"clients,omitempty"`
	Skills      []PreviewResource `json:"skills"`
	Agents      []PreviewResource `json:"agents"`
	Rules       []PreviewResource `json:"rules"`
	Unresolved  []string          `json:"unresolved,omitempty"`
	Warnings    []string          `json:"warnings,omitempty"`
	Stack       *StackSummary     `json:"stack,omitempty"`
	Sources     []SourceSummary   `json:"sources,omitempty"`
}

type RemoveDoc struct {
	SchemaVersion int      `json:"schema_version"`
	Pack          string   `json:"pack"`
	DryRun        bool     `json:"dry_run,omitempty"`
	Rows          []Row    `json:"rows"`
	Kept          []string `json:"kept,omitempty"`
}

type RemoveOptions struct {
	Force  bool
	DryRun bool
	// GatewayPort feeds the wiring status probe used to find pack-tagged
	// wiring records.
	GatewayPort int
}

type Row struct {
	Kind        string `json:"kind"`
	Name        string `json:"name"`
	Client      string `json:"client,omitempty"`
	Action      string `json:"action,omitempty"`
	State       string `json:"state,omitempty"`
	Detail      string `json:"detail,omitempty"`
	Remediation string `json:"remediation,omitempty"`
}

type SourceSummary struct {
	Name      string   `json:"name"`
	Repo      string   `json:"repo"`
	Ref       string   `json:"ref,omitempty"`
	CommitSHA string   `json:"commit_sha,omitempty"`
	Skills    []string `json:"skills"`
	Agents    []string `json:"agents"`
	Error     string   `json:"error,omitempty"`
}

type StackLauncher interface {
	// Launch deploys the stack at StackPath as a background daemon and
	// returns the port it listens on. Replace stops a running daemon
	// with the same stack name first.
	Launch(ctx context.Context, opts LaunchOptions) (LaunchResult, error)
	// Stop stops the daemon named by stackName and removes its
	// containers. It must only be called for a daemon whose state file
	// StackFile is under the pack checkout directory.
	Stop(ctx context.Context, stackName string) error
}

type StackSummary struct {
	Path    string `json:"path"`
	Name    string `json:"name"`
	Servers int    `json:"servers"`
}

type StatusOptions struct {
	// Pack restricts the report to one pack; empty means all.
	Pack string
	// GatewayPort feeds the wiring status probe (the caller resolves it:
	// the CLI from running state, the API server from its own listener).
	GatewayPort int
}

type VariableRequirement struct {
	Key         string `json:"key"`
	Type        string `json:"type"`
	Secret      bool   `json:"secret"`
	Description string `json:"description,omitempty"`
	Docs        string `json:"docs,omitempty"`
	Command     string `json:"command"`
}