cmdutil

type CanonicalCmdFlags struct {
	DryRun bool
	Yes    bool
	Force  bool
}

type CanonicalFileEntry struct {
	Scope      string
	BaseName   string
	SourcePath string
}

type CanonicalFileSpec struct {
	// Kind is the capitalized header label ("Settings" | "MCP" | "Rules").
	Kind string
	// DirSegment is the directory under ~/.agents/<DirSegment>/.
	// Used in user-facing path text, the remove header, and the
	// confirmation prompt.
	DirSegment string
	// SingularRem is the singular noun used in remove output strings
	// ("settings file" | "MCP file" | "rule file").
	SingularRem string
	// EmptyHint produces the message shown when no files exist for
	// the scope. Per-subcommand because the message lists the kind's
	// own valid file extensions or noun.
	EmptyHint func(scope string) string
	// MissingDirHint produces the message shown when the
	// agentsHome/<DirSegment>/<scope>/ directory itself doesn't exist.
	// Defaults if nil to "No ~/.agents/<DirSegment>/<scope>/ directory yet ...".
	MissingDirHint func(scope string) string

	// List enumerates entries for a scope. Returning an os.IsNotExist
	// error indicates the scope directory is missing — the helper
	// turns that into the MissingDirHint informational message.
	List func(agentsHome, scope string) ([]CanonicalFileEntry, error)
	// Resolve finds one entry by basename or stem; the returned error
	// is propagated as-is, so callers can wrap with errorWithHints.
	Resolve func(agentsHome, scope, name string) (CanonicalFileEntry, error)
	// EnsureScope verifies target is under <agentsHome>/<DirSegment>/<scope>/.
	EnsureScope func(agentsHome, scope, target string) error

	// Use / Short / Long / Example populate the parent cobra.Command
	// (the `da <kind>` node). Example is a pre-joined string — leaves
	// build multi-line examples with CanonicalCmdExampleBlock(...) or
	// a plain string literal.
	Use     string
	Short   string
	Long    string
	Example string

	// List / Show / Remove subcommand strings + Args validators.
	// Args is the pre-bound cobra.PositionalArgs validator from the
	// leaf's Deps (mcp uses MaxArgsWithHints, settings/rules use
	// MaximumNArgsWithHints, so binding stays at the leaf). Run is the
	// leaf-specific runner that receives unpacked scope/name args from
	// the canonical RunE wrapper.
	ListSub    SubCmdStrings
	ListArgs   cobra.PositionalArgs
	ListRun    func(scope string) error
	ShowSub    SubCmdStrings
	ShowArgs   cobra.PositionalArgs
	ShowRun    func(scope, name string) error
	RemoveSub  SubCmdStrings
	RemoveArgs cobra.PositionalArgs
	RemoveRun  func(scope, name string) error
}

type CanonicalResourceDef struct {
	// Identity — used by the data-layer RunCanonical* helpers and the
	// parent commands.* user-facing strings.
	Kind        string // "MCP" | "Settings" | "Rule"
	DirSegment  string // "mcp" | "settings" | "rules"
	SingularRem string // "MCP file" | "settings file" | "rule file"

	// EnsureScope verifies the resolved target path is under
	// <agentsHome>/<DirSegment>/<scope>/. The three platform.EnsureUnder*
	// helpers have the same signature, so we can bind them directly.
	EnsureScope func(agentsHome, scope, target string) error

	// EmptyHint / MissingDirHint produce the informational messages the
	// list path prints when the scope has no files / no directory.
	// MissingDirHint is optional — RunCanonicalList falls back to a
	// generic message when nil (settings uses the fallback).
	EmptyHint      func(scope string) string
	MissingDirHint func(scope string) string

	// CLI surface — parent `da <kind>` cobra.Command.
	Use      string   // "mcp" | "settings" | "rules"
	Short    string   // one-line summary
	Long     string   // multi-line description for `--help`
	Examples []string // top-level Example block lines (joined with "\n")

	// List subcommand strings.
	ListShort    string
	ListExamples []string
	ListArgsHint string // passed to MaxArgsWithHints / MaximumNArgsWithHints

	// Show subcommand strings.
	ShowShort    string
	ShowArgsHint string

	// Remove subcommand strings.
	RemoveShort    string
	RemoveLong     string
	RemoveArgsHint string
}

type RemoveDeps struct {
	DryRun bool
	Yes    bool
	Force  bool
}

type ResourceRunners struct {
	// List enumerates entries for a scope. Returning an os.IsNotExist
	// error indicates the scope directory is missing — RunCanonicalList
	// turns that into the def's MissingDirHint informational message.
	List func(agentsHome, scope string) ([]CanonicalFileEntry, error)
	// Resolve looks up one entry by basename or stem. Errors are
	// propagated verbatim, so leaves should wrap with the parent
	// commands.ErrorWithHints / commands.UsageError shape via their
	// deps before returning.
	Resolve func(agentsHome, scope, name string) (CanonicalFileEntry, error)

	// ListRun / ShowRun / RemoveRun are the leaf's per-verb runners.
	// The cobra RunE wrappers in canonical_cmd.go unpack args and call
	// these directly.
	ListRun   func(scope string) error
	ShowRun   func(scope, name string) error
	RemoveRun func(scope, name string) error
}

type RoutedTarget struct {
	// Scope is the resolved ownership scope.
	Scope config.EditScope
	// SourceID is the stable local source identifier the write lands in.
	SourceID string
	// Owner names the team/org that owns a governed or owned-project source.
	// Empty for local and personal-project targets.
	Owner string
}

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

type ScopeSourceFlags struct {
	// Scope is the requested ownership scope (local/team/org/project). Empty
	// resolves to the default, ScopeLocal.
	Scope string
	// Source is the stable local source id (the `id` in the `sources` array,
	// §3) the write targets. Required for governed scopes; for local it names
	// the personal store and may be left to the command's default.
	Source string
}

type SubCmdStrings struct {
	Use     string
	Short   string
	Long    string
	Example string
}