spells

type Charm struct {
	Ops []PatchOp `json:"ops,omitempty"`
}

type CharmConflict struct {
	Name         string `json:"name"                    yaml:"name"`
	OverriddenBy string `json:"overridden_by,omitempty" yaml:"overridden_by,omitempty"`
}

type CharmTraceStep struct {
	Charm   string   `json:"charm,omitempty"   yaml:"charm,omitempty"`
	Command []string `json:"command"           yaml:"command"`
}

type Command struct {
	Bin    string           `json:"bin,omitempty"`
	Args   []string         `json:"args,omitempty"`
	Charms map[string]Charm `json:"charms,omitempty"`
	// Sources, when non-empty, are doublestar globs (relative to the project
	// directory this command runs in) that the RUNNER expands into a file list
	// at EXECUTION time, via the same walk that builds the cache key
	// (cache.ExpandSources) - so a Sources-declaring op inherits the workspace's
	// declared ignore dirs (the core project.IgnoreDirs plus the issuing spell's
	// own mgs_listIgnoreDirs) instead of hardcoding directory names.
	//
	// An op handler runs ONCE with a null Target and is reduced to a static
	// {bin, args} record, so it cannot walk a project directory itself - which is
	// why a spell used to shell out to `find | xargs`. Declaring Sources defers
	// that walk to the runner, per project, with no shell involved.
	//
	// Expanded files are appended to Args in one of two shapes, chosen by
	// SourcesEach: batched (the default, under an ARG_MAX-safe limit) or one
	// invocation per file. A glob set matching nothing runs the command ZERO times
	// and reports success, the equivalent of `xargs -r`.
	//
	// Empty (the default) leaves Args exactly as declared.
	Sources []string `json:"sources,omitempty"`
	// SourcesEach runs Bin once PER file Sources matches (xargs -n1: one file,
	// one invocation), each invocation appending that single file to Args. False
	// (the default) batches every matched file across as few invocations as fit
	// under the runner's ARG_MAX-safe limit. Meaningless without Sources.
	SourcesEach bool `json:"sources_each,omitempty"`
	// Capture makes this command's spell method return its exec record. The field
	// belongs on Command because it is declared by a Command-returning handler;
	// Op carries the resolved copy that dispatch reads.
	Capture bool `json:"capture,omitempty"`
	// Secrets declares the environment this command needs, as env var name -> provider
	// reference: {"NPM_TOKEN": "NPM_TOKEN"} sets $NPM_TOKEN in the child from whatever
	// the workspace's secret provider resolves that reference to.
	//
	// It is the declarative escape hatch for the two shapes that cannot reach a
	// magusfile body: a command op (static argv) and a provided project (no magusfile).
	// Refs resolve through the same secret.Resolver at spawn and are injected into ONLY
	// this child's environment - never into Args, never logged, never returned by
	// `magus describe` - and Resolver.Read registers each value for redaction. Charms
	// patch Args only. Refs are static data, so the op stays hashable and describable
	// without ever holding a secret.
	Secrets map[string]string `json:"secrets,omitempty"`
	// Hints classify a FAILURE of this command into a next step. Each entry pairs a
	// substring of the tool's output with the advice magus prints when the command
	// exits non-zero and that substring appeared. The first declared match wins; a
	// command that succeeds never consults them.
	//
	// This lets a tool's own error teach its fix: "authentication required" from
	// `docker buildx build --push` is a complete diagnosis to anyone who knows docker
	// and an exit code to everyone else.
	//
	// `json:"-"` is LOAD-BEARING. BuiltinsHash marshals the resolved registry into
	// every project's SpellDefVersion, so a serialized field puts its contents in every
	// cache key - rewording a sentence of advice would invalidate every target in every
	// project. Doc is excluded for the same reason. JSON is not used to transport an
	// Op; the only marshal of the registry is the hash itself.
	Hints []Hint `json:"-"`
}

type Descriptor struct {
	Name     string   `json:"name"`
	Needs    []string `json:"needs,omitempty"`
	Provides []string `json:"provides,omitempty"`
	// IgnoreDirs names non-source directories this spell's ecosystem generates
	// (vendor, node_modules, target, __pycache__) so the input-hashing walk prunes
	// them per-project instead of the engine hardcoding language-specific names.
	// Dot-directories are already skipped structurally, so only non-dot names belong
	// here. Declared by mgs_listIgnoreDirs.
	IgnoreDirs []string `json:"ignore_dirs,omitempty"`
	// Manifests is the ordered list of candidate manifests this spell's ecosystem
	// declares. Ordered because some ecosystems have genuine alternatives - the first
	// one present in a project directory is its manifest. Declared by
	// mgs_listManifests. Distinct from Needs (cache/affected input globs), from a
	// spell's DeclarationFiles (project discovery, not exposed on Descriptor), and
	// from VersionCmd (the toolchain's own version, not the project's).
	Manifests   []Manifest          `json:"manifests,omitempty"`
	Opaque      bool                `json:"opaque,omitempty"`
	TargetNeeds map[string][]string `json:"target_needs,omitempty"`
	Ops         map[string]Op       `json:"targets,omitempty"`
	// Tools is every binary this spell drives, keyed by the bin name an op names in
	// its Command - so no op restates which tool it runs, and everything magus knows
	// about that binary sits in one place.
	//
	// It replaces five separate declarations (a primary probe, named probes, a primary
	// key, named keys, readiness) split across two axes that were never orthogonal.
	// The split also hid its own subtleties: govulncheck declaring no cache key is a
	// deliberate choice, and in two parallel maps that reads as an absence nobody
	// notices rather than a decision someone made.
	//
	// There is no privileged "primary" tool. `go` had one only for historical cache-key
	// reasons, and nothing principled distinguished it from golangci-lint - both are
	// binaries the spell drives, so both key the cache as spell:tool:version.
	Tools map[string]Tool `json:"tools,omitempty"`

	// Language is the canonical source language this spell adapts (e.g. "go",
	// "typescript"), declared by mgs_getLanguage. It tags the spell node so a
	// `language:` query groups the adapter with the files and symbols of that language;
	// empty for a spell that adapts no single source language (docker, cosign).
	Language string `json:"language,omitempty"`
	// DocOps names the ops authored as function handlers (sorted) — as opposed to
	// plain {cmd,args} record ops. `magus doctor` requires a doc comment on each of
	// these for a workspace-local Buzz spell. Not serialized: it is a resolution-path
	// fact (which authoring form an op used), not part of the spell's cache identity,
	// so it stays out of BuiltinsHash.
	DocOps []string `json:"-"`
}

type Diagnostic struct {
	File     string
	Line     int
	Col      int
	Severity string
	Code     string
	Message  string
}

type DiagnosticFormat string

type Driver interface {
	// Name returns the stable identifier for this spell or tool.
	Name() string
	// Invoke runs the spell or tool with the given request.
	// Implementations ignore fields they don't use.
	Invoke(ctx context.Context, req InvokeRequest) (InvokeResponse, error)
}

type Hint struct {
	// Contains is matched against the failed command's stdout and stderr SEPARATELY,
	// never against the two joined: a substring spanning the seam of two independent
	// streams would fire on output that appeared in neither.
	Contains string `json:"contains"`
	// Advise is the text magus prints. Write the command to run rather than the
	// diagnosis - it is printed after the tool's own error, which already said what
	// went wrong.
	Advise string `json:"advise"`
}

type InvokeRequest struct {
	Target string         // build target or sub-action
	Dir    string         // project directory; empty for workspace-level MCP tools
	Params map[string]any // MCP tool parameters; ignored by *Spell
}

type InvokeResponse struct {
	Text string // human-readable output
	Data any    // structured result for MCP tools; nil for *Spell
}

type Manifest struct {
	Value string `json:"value"`
	// LockCandidates names the lockfiles this ecosystem MIGHT resolve Value into, of
	// which exactly one will exist - not the lockfiles a project has. package.json
	// resolves into any of pnpm-lock.yaml, package-lock.json, npm-shrinkwrap.json,
	// yarn.lock or a bun lockfile depending on which package manager is in use, and
	// pyproject.toml into any of poetry.lock, pdm.lock, uv.lock or Pipfile.lock. Go and
	// Rust have exactly one each, which is what makes the plural easy to misread: a
	// consumer that takes the first element is right for go.sum and wrong for npm.
	//
	// Bare filenames rather than Paths, because a lockfile's DIRECTORY is not knowable
	// here. mgs_ functions run during spell discovery, before a project exists, and a
	// workspace hoists one lockfile to its root to serve many manifests. Which
	// directory holds the live one is resolved by walking up from the project, not
	// declared. (Locks are also relative to nothing, so Path's base - the reason Path
	// beats a string elsewhere - has nothing to carry.)
	LockCandidates []string `json:"lock_candidates,omitempty" buzz:"lockCandidates"`
}

type Op struct {
	// Kind is the op's lifecycle kind (OpKind*); empty means OpKindCommand.
	Kind string `json:"kind,omitempty"`
	Command
	// Service is set only for a service op (Kind == OpKindService); nil otherwise.
	Service *Service `json:"service,omitempty"`
	Capture bool     `json:"capture,omitempty"`
	// Doc is the handler function's documentation comment (see buzz Chunk.Doc),
	// surfaced by `magus describe` and enforced by `magus doctor` for local Buzz
	// spells. Empty for command built-ins (their Doc is not serialized in bytecode).
	// omitempty keeps it out of BuiltinsHash so the cache key is unaffected.
	Doc string `json:"doc,omitempty"`
}

type Option func(*Spell)

type PatchOp struct {
	Op    PatchOpKind `json:"op"`
	Path  string      `json:"path"`
	Value string      `json:"value,omitempty"`
	// From is the move/copy source JSON Pointer. The Buzz field is named fromPtr
	// because `from` is a reserved word in Buzz, so no mirror can declare it; the JSON
	// stays "from" (RFC 6902). Everything on the Buzz side of the boundary - the charm
	// constructors that emit it, the decoder that reads it back, and the mirror - uses
	// fromPtr. They did not always agree: the constructors emitted "from", which the
	// mirror said was called fromPtr, so an annotated charm would have read an empty
	// field. Nothing caught it because nothing referenced the Buzz name.
	From string `json:"from,omitempty" buzz:"fromPtr"`
}

type PatchOpKind string

type ProvidedProject struct {
	// Path is the project's directory relative to the WORKSPACE ROOT, forward
	// slashes. Required. It must stay inside the root and must not be "." - the root
	// project is the one the magusfile that wired the provider already owns.
	Path string `json:"path"`
	// Name is the human label, for a foreign tool whose project name is not its
	// directory (an nx project named "@acme/ui" rooted at libs/ui). Empty derives
	// one from the path, exactly as a magusfile-declared project does.
	Name string `json:"name"`
	// Spells names the spells to bind, contributing their ops, sources and outputs.
	Spells []string `json:"spells"`
	// DependsOn names upstream projects, resolved exactly as magus\project's
	// "depends_on" is: a bare path is workspace-relative, a dot-relative one is
	// relative to this project.
	//
	// The buzz tag is load-bearing, not cosmetic: this record mirrors the option keys
	// an AUTHOR writes in magus\project({...}), which is snake_case, so the generator's
	// lowerCamel default would silently rename the key the decoder reads. (The
	// host-returned ProjectEntry mirror spells the same concept dependsOn because it
	// mirrors a returned struct, not an authored map.)
	DependsOn []string `buzz:"depends_on" json:"depends_on"`
	// Sources and Outputs are globs relative to THIS PROJECT'S directory, not to the
	// workspace root - the same anchor magus\project's options use, and the anchor
	// baseStep joins against the project path. A provider reporting a foreign tool's
	// workspace-relative globs must re-anchor them first: for a project at libs/foo,
	// "libs/foo/**/*.ts" is wrong and "**/*.ts" is right.
	//
	// The anchor also bounds what is expressible: an output the foreign tool writes
	// OUTSIDE the project directory (nx's dist/{projectRoot} convention) has no
	// project-relative spelling and cannot be declared here.
	Sources []string `json:"sources"`
	Outputs []string `json:"outputs"`
	// Exclusive marks the project as must-not-run-alongside-peers in a batch.
	Exclusive bool `json:"exclusive"`
}

type Secret struct {
	// Value is the resolved credential.
	Value string
}

type Service struct {
	Command   Command `json:"command,omitempty"`
	Readiness Command `json:"readiness,omitempty"`
	Stop      Command `json:"stop,omitempty"`
	// Distinct, when non-empty, opts this service out of shared-instance dedup and
	// silences its near-duplicate (MGS5001) warning. It is a required reason string
	// (the golangci-lint nolintlint model): being distinct without a reason is
	// meaningless, so the reason IS the value. Recorded so `magus doctor` can audit
	// every deliberate divergence and flag reasons that no longer apply (a distinct
	// service with no remaining near-duplicate is a stale suppression).
	Distinct string `json:"distinct,omitempty"`
	// Idle overrides the per-service idle timeout (a duration like "30m") after which
	// the daemon reaps this shared service once its last dependent releases. Empty
	// uses the daemon's global default. Consumed by the service supervisor.
	Idle string `json:"idle,omitempty"`
}

type ServiceView struct {
	Readiness   []string `json:"readiness,omitempty"   yaml:"readiness,omitempty"`   // probe command polled until it exits 0, if any
	Stop        []string `json:"stop,omitempty"        yaml:"stop,omitempty"`        // graceful-shutdown command, if any
	Idle        string   `json:"idle,omitempty"        yaml:"idle,omitempty"`        // idle-timeout override (a duration), else the daemon default
	Distinct    string   `json:"distinct,omitempty"    yaml:"distinct,omitempty"`    // dedup opt-out reason; empty means the instance is shared
	Fingerprint string   `json:"fingerprint,omitempty" yaml:"fingerprint,omitempty"` // content hash that keys shared-instance dedup
}

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

type Tool struct {
	// Probe is the command that prints this binary's version, its result narrowed by
	// Key and mixed into the cache key. A zero Command means magus never asks -
	// correct for a tool that cannot report one, where Key.Const supplies the token.
	//
	// A Command rather than a bare argv so it matches Ready below: both are "run this
	// and read the result", and two shapes for that inside one record is the kind of
	// seam a reader has to hold in their head for no reason.
	Probe Command `json:"probe,omitempty"`
	// Key narrows what Probe's output contributes to the cache key. The zero value
	// keys on the whole output; see VersionKey.
	Key VersionKey `json:"key,omitempty"`
	// Ready gates an op on this binary being usable, for a client whose server may be
	// down. Its result is a precondition and never enters a cache key.
	Ready Command `json:"ready,omitempty"`
	// Supported is the version window this spell's ops work against. Empty accepts any
	// version.
	//
	// It is the fourth question about a tool, after does it exist, what version, and is
	// it usable. Without it a too-old binary fails with whatever that tool says about
	// an unrecognized flag - the same misleading failure readiness exists to prevent,
	// one step over. Checked against the extracted version, so it needs Probe.
	//
	// It states what the OPS need, not what a repo has qualified: "go::test does not
	// work below 1.21" belongs here, "we have not moved to node 25 yet" belongs in the
	// workspace's own bounds, which are intersected with this one.
	Supported VersionBounds `json:"supported,omitempty"`
	// Diagnostics names the convention this binary prints findings in; empty means
	// prose. On the tool rather than the op because the format is the binary's:
	// hadolint reports the same way whichever op invokes it.
	Diagnostics DiagnosticFormat `json:"diagnostics,omitempty"`
}

type Verdict int

type VersionBounds struct {
	// Min is the oldest version accepted, inclusive. Empty accepts any.
	Min string `json:"min,omitempty" yaml:"min,omitempty"`
	// Below is the first version REJECTED, exclusive. Empty accepts any.
	Below string `json:"below,omitempty" yaml:"below,omitempty"`
}

type VersionComponent string

type VersionKey struct {
	// Const is an author-supplied constant used as the token verbatim, for a tool that
	// cannot report its own version at all. No process is spawned; the author edits the
	// string by hand to invalidate. When set, UpTo is ignored.
	Const string `json:"const,omitempty"`
	// UpTo asks for extraction and names how much of the extracted version to keep.
	// Absent means no extraction: the whole output keys the cache.
	UpTo VersionComponent `json:"upTo,omitempty"`
}

type VersionKeyFunc func(version string) string