packs

type InstallResult struct {
	// PendingProtoGenerate is set true when the install emitted (or
	// previously emitted but did not yet render) a `.proto` file that
	// the project's `buf generate` / `forge generate` pipeline has NOT
	// yet wired into `buf.yaml` and `gen/`. The CLI uses this to print
	// a "run `forge generate` to compile new proto definitions" hint
	// at the tail of the install so the user isn't left in a
	// half-installed state with broken `go mod tidy`.
	//
	// Pack templates that contribute `.proto` files also import the
	// not-yet-generated `gen/<ns>/v1` package, so tidy is intentionally
	// deferred to the post-`forge generate` run — this field is the
	// signal that the deferral happened and the user must take action.
	PendingProtoGenerate bool
}

type Manager interface {
	Load(ctx context.Context, name string) (*Pack, error)
	Install(ctx context.Context, pack *Pack, projectDir string, cfg *config.ProjectConfig) error
	Remove(ctx context.Context, pack *Pack, projectDir string, cfg *config.ProjectConfig) error
	List(ctx context.Context) ([]Pack, error)
	InstalledPacks(ctx context.Context, cfg *config.ProjectConfig) ([]*Pack, error)
	IsInstalled(ctx context.Context, name string, cfg *config.ProjectConfig) bool
	RenderGenerateFiles(ctx context.Context, pack *Pack, projectDir string, cfg *config.ProjectConfig) error
}

type Pack struct {
	Name        string `yaml:"name"`
	Description string `yaml:"description"`
	Version     string `yaml:"version"`
	// Kind selects the language/runtime the pack targets. "go" (default —
	// or empty for backward compatibility) installs Go files under pkg/ and
	// runs `go get` / `go mod tidy`. "frontend" installs TypeScript/React
	// assets under each frontends/<name>/ directory and runs `npm install`
	// in those directories. See PackKindGo, PackKindFrontend.
	Kind string `yaml:"kind"`
	// Subpath is an informational hint declaring where, under pkg/, the pack
	// prefers its non-proto/non-migration code to live. It documents the pack's
	// chosen organization (e.g. "middleware/auth/jwtauth") and is surfaced by
	// `forge pack info` so a user can see at a glance what subtree the pack
	// touches. Forge does NOT enforce categories or matrix rules — output
	// paths in `files:` and `generate:` are the source of truth. If omitted,
	// the pack is treated as living at the top level under pkg/.
	//
	// For frontend packs, Subpath is informational and describes the path
	// under each frontends/<name>/ directory (e.g. "src/components/data-table").
	Subpath      string     `yaml:"subpath"`
	Config       PackConfig `yaml:"config"`
	Files        []PackFile `yaml:"files"`
	Dependencies []string   `yaml:"dependencies"`
	// NPMDependencies lists npm package specs (`name` or `name@version`)
	// installed via `npm install` into each frontend directory. Only
	// honoured when Kind == "frontend".
	NPMDependencies []string `yaml:"npm_dependencies"`
	// ProviderNPMDependencies pulls extra npm deps in keyed by the value of
	// `pack_config.provider`. Lets a single frontend pack ship variant-specific
	// SDKs (e.g. `@clerk/nextjs` for `provider=clerk`, `firebase` for
	// `provider=firebase-auth`) without forcing every install to pay for them.
	// Only honoured when Kind == "frontend".
	ProviderNPMDependencies map[string][]string `yaml:"provider_npm_dependencies"`
	// AllowedThirdParty is the per-pack opt-out for the frontendpacklint
	// soft rule that flags pack templates importing third-party UI libs
	// (@radix-ui/*, @headlessui/*, @tanstack/react-table, ...). Each entry
	// is a package prefix that this pack legitimately needs to wrap
	// (e.g. "@tanstack/react-table" — a headless engine forge wraps with
	// base library primitives, or "recharts" for a charts pack).
	// Only honoured when Kind == "frontend".
	AllowedThirdParty []string `yaml:"allowed_third_party"`
	// SupportsKinds restricts a frontend pack to specific frontend kinds
	// (one of "web", "mobile", "vite-spa"). Empty (default) means the pack
	// supports all kinds. Most legacy frontend packs are Next.js-coded
	// (App Router paths, `next/navigation` imports) and should declare
	// `supports_kinds: [web]` until their templates are adapted to the
	// other kinds.
	//
	// Honoured only when Kind == "frontend". On install, forge errors out
	// if any of the project's frontends declares a kind not in this list,
	// listing the unsupported frontends and the supported set.
	SupportsKinds []string        `yaml:"supports_kinds,omitempty"`
	Generate      []PackFile      `yaml:"generate"`
	Migrations    []PackMigration `yaml:"migrations"`

	// DependsOn lists the names of OTHER PACKS this pack requires to be
	// installed first. Distinct from Dependencies (Go module deps) and
	// NPMDependencies (npm package deps): DependsOn captures pack-to-pack
	// ordering — e.g. api-key depends on audit-log because the api-key
	// generate hook writes audit entries through the audit_events table
	// that audit-log creates. Forge topologically sorts at install time
	// (auto-installing transitive deps) and at generate time (so consumer
	// generate hooks run after producer hooks).
	//
	// Cycle detection is the loader's responsibility — a cycle is a pack
	// authoring bug, not a project bug, so we surface it loudly. Empty
	// for the common case (most packs are leaves with no pack-to-pack
	// ordering need).
	DependsOn []string `yaml:"depends_on,omitempty"`

	// PostInstall is a human-facing "next steps" block the CLI prints
	// after a successful install — the exact wiring the user must do by
	// hand (call sites, interceptor chains, env vars). Packs that install
	// code with zero call sites (e.g. jwt-auth's Init/Interceptor) MUST
	// say so here: silently shipping unwired code is how users end up
	// believing a pack is active when it isn't.
	PostInstall string `yaml:"post_install,omitempty"`
}

type PackConfig struct {
	Section  string         `yaml:"section"`
	Defaults map[string]any `yaml:"defaults"`
}

type PackFile struct {
	Template    string `yaml:"template"`
	Output      string `yaml:"output"`
	Overwrite   string `yaml:"overwrite"`   // "always" | "once" | "never"
	Description string `yaml:"description"` // optional human description
}

type PackMigration struct {
	// Name is the slug appended after the allocated ID (e.g. "api_keys" →
	// "00002_api_keys.up.sql"). Required.
	Name string `yaml:"name"`
	// Up is the template that renders the up-migration SQL. Required.
	Up string `yaml:"up"`
	// Down is the template that renders the down-migration SQL. Required.
	Down string `yaml:"down"`
	// Description is an optional human description.
	Description string `yaml:"description"`
}