core

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 25, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package core provides shared primitives for the Krewire ecosystem, including the common error type and process exit-code mapping.

Package core — workload registry (KWF-M8K2Q, KWL-K1N2Q).

Index

Constants

View Source 
const DefaultEnv = EnvLocal

DefaultEnv is assumed when no environment is declared anywhere.

Variables

View Source 
var AllKinds = []Kind{KindApp, KindCLI, KindSite, KindBook, KindWorker, KindService, KindInfra, KindKernel}

AllKinds lists every valid Kind in canonical order.

View Source 
var AllScopes = []Scope{ScopeWorkspace, ScopeModule, ScopeDomain, ScopePackage, ScopeService, ScopeFunc}

AllScopes lists every valid Scope in canonical order.

View Source 
var CurrentVersion = MustParseVersion("0.1.0")

CurrentVersion is the libs module's own version. Bump per release.

View Source 
var EcosystemVersions = map[ModuleName]Version{
	ModuleFramework: MustParseVersion("0.1.0"),
	ModuleLibs:      CurrentVersion,
	ModuleMdbind:    MustParseVersion("0.1.0"),
	ModuleKrewire:   MustParseVersion("0.1.0"),
	ModuleGuild:     MustParseVersion("0.1.0"),
	ModuleInternal:  MustParseVersion("0.1.0"),
}

EcosystemVersions is the known-good compatibility matrix for the current release.

View Source 
var Workloads = []Workload{
	{Kind: KindCLI, Package: "framework/tui", Title: "CLI tools", SpecID: "KWF-5XJFC", Status: StatusShipped},
	{Kind: KindApp, Package: "framework/web", Title: "Backend / API", SpecID: "KWF-M07QS", Status: StatusShipped},
	{Kind: KindSite, Package: "framework/web/ssg", Title: "Static sites (SSG)", SpecID: "KWF-PT8OD", Status: StatusShipped},
	{Kind: KindBook, Package: "mdbind", Title: "Documentation sites", SpecID: "KWM-FX9H2", Status: StatusShipped},
	{Kind: KindApp, Package: "framework/app", Title: "Fullstack / Monolith", SpecID: "KWF-C4087", Status: StatusShipped},
	{Kind: KindSite, Package: "framework/runtime", Title: "Frontend (client)", SpecID: "KWF-T4X9P", Status: StatusPlanned},
	{Kind: KindWorker, Package: "framework/worker", Title: "Workers & jobs", SpecID: "KWF-L5H2F", Status: StatusPlanned},
	{Kind: KindService, Package: "framework/service", Title: "Microservice", SpecID: "KWF-L5H2F", Status: StatusPlanned},
	{Kind: KindInfra, Package: "framework/infra", Title: "Cloud infrastructure", SpecID: "KWF-B7N3D", Status: StatusPlanned},
}

Workloads is the canonical 9-workload matrix from internal/docs/project-vision.md.

Functions

func CheckEcosystemCompatibility 

func CheckEcosystemCompatibility(required, actual map[ModuleName]Version) error

CheckEcosystemCompatibility verifies that actual versions satisfy required versions per IsCompatible. Pass the go.mod require versions as actual; the matrix as required.

func FormatStack 

func FormatStack(frames []StackFrame) string

FormatStack renders frames as an indented multi-line trace, newest first.

func FormatTree added in v0.2.0 

func FormatTree(err error) string

FormatTree renders err as a human-readable diagnostic tree: the message chain top-down, each annotated with its creation point when a stack was captured, attributes inline, and the nearest hint as footer (KWL-P8W2N KWL-ERRV-010).

func HintOf added in v0.2.0 

func HintOf(err error) string

HintOf returns the nearest hint found walking the wrap chain from the outside in, or "" when none is attached (KWL-P8W2N KWL-ERRV-009).

func IsOptIn 

func IsOptIn(kind Kind, imported []string) bool

IsOptIn reports whether importing the given import paths violates opt-in for the declared kind. For example, a KindApp monolith importing framework/service should be flagged.

func ParseRequirementID 

func ParseRequirementID(s string) error

ParseRequirementID validates s as a RequirementID.

func ValidateKrewireYamlPath 

func ValidateKrewireYamlPath(path string) error

ValidateKrewireYamlPath ensures the config path is krewire.yaml.

func WithAttrs added in v0.2.0 

func WithAttrs(err error, attrs ...Attr) error

WithAttrs attaches structured diagnostic attributes to err. Nil-safe; wrapping repeatedly accumulates layers extractable by AttrsOf.

func WithHint added in v0.2.0 

func WithHint(err error, text string) error

WithHint attaches one actionable user-facing hint to err. Nil-safe.

func WithStack 

func WithStack(err error) error

WithStack captures the calling goroutine's stack at the wrap point and attaches it to err. Nil-safe; stacking an already-stacked error adds a second, outer trace (KWL-P8W2N KWL-ERRV-003).

Types

type Attr added in v0.2.0 

type Attr struct {
	Key   string
	Value any
}

Attr is one structured key/value pair attached to an error for diagnostics (KWL-P8W2N KWL-ERRV-008).

func AttrsOf added in v0.2.0 

func AttrsOf(err error) []Attr

AttrsOf collects attributes across the wrap chain, outermost first. Each wrap layer contributes its own attributes exactly once.

type DomainEvent 

type DomainEvent struct {
	Type    string    `json:"type"`
	Payload any       `json:"payload"`
	At      time.Time `json:"at"`
}

DomainEvent is a cross-module domain event.

func NewDomainEvent 

func NewDomainEvent(typ string, payload any) DomainEvent

NewDomainEvent creates a DomainEvent with the current time.

type Env 

type Env string

Env is the target environment a workload runs in. 

const (
	// EnvLocal is the developer-machine default.
	EnvLocal Env = "local"
	// EnvProduction is the live serving environment.
	EnvProduction Env = "production"
	// EnvTesting is the automated-test environment.
	EnvTesting Env = "testing"
)

func Envs 

func Envs() []Env

Envs returns every valid environment in canonical order.

func ParseEnv 

func ParseEnv(s string) (Env, error)

ParseEnv resolves s into an Env. Empty (after trimming) yields DefaultEnv; matching is case-insensitive; anything else is a usage error naming the allowed set.

func (Env) String 

func (e Env) String() string

String returns the canonical lowercase name.

type Error 

type Error struct {
	// Message is the human-readable error message.
	Message string
	// Code is the process exit code associated with the error.
	Code ExitCode
}

Error pairs a human-readable message with an ExitCode.

func FailureError 

func FailureError(message string) *Error

FailureError creates an Error with ExitCodeFailure.

func NewError 

func NewError(message string, code ExitCode) *Error

NewError creates an Error with the given message and exit code.

func UsageError 

func UsageError(message string) *Error

UsageError creates an Error with ExitCodeUsage.

func (*Error) Error 

func (e *Error) Error() string

Error implements the error interface.

func (*Error) ExitCode 

func (e *Error) ExitCode() ExitCode

ExitCode returns the exit code associated with the error.

type ExitCode 

type ExitCode int

ExitCode is a standard process exit code used across Krewire applications. 

const (
	// ExitCodeSuccess indicates successful termination.
	ExitCodeSuccess ExitCode = 0
	// ExitCodeFailure indicates a generic runtime failure.
	ExitCodeFailure ExitCode = 1
	// ExitCodeUsage indicates invalid usage: missing or malformed arguments,
	// configuration, or input.
	ExitCodeUsage ExitCode = 2
)

func ExitCodeFromInt 

func ExitCodeFromInt(code int) ExitCode

ExitCodeFromInt maps a raw process exit code back to the closest known ExitCode.

func (ExitCode) Int 

func (c ExitCode) Int() int

Int returns the numeric value used by the operating system.

type Kind 

type Kind string

Kind is a Krewire project kind. Eight kinds cover the unified workload spectrum. 

const (
	KindApp     Kind = "app"
	KindCLI     Kind = "cli"
	KindSite    Kind = "site"
	KindBook    Kind = "book"
	KindWorker  Kind = "worker"
	KindService Kind = "service"
	KindInfra   Kind = "infra"
	KindKernel  Kind = "kernel"
)

func ParseKind 

func ParseKind(s string) (Kind, error)

ParseKind parses s as a Kind, returning UsageError on unknown.

func (Kind) IsValid 

func (k Kind) IsValid() bool

IsValid reports whether k is one of the eight known kinds.

type ModuleName 

type ModuleName string

ModuleName identifies a Krewire module in the ecosystem compatibility matrix. 

const (
	ModuleFramework ModuleName = "framework"
	ModuleLibs      ModuleName = "libs"
	ModuleMdbind    ModuleName = "mdbind"
	ModuleKrewire   ModuleName = "krewire"
	ModuleGuild     ModuleName = "guild"
	ModuleDocs      ModuleName = "docs"
	ModuleLanding   ModuleName = "krewire.github.io"
	ModuleInternal  ModuleName = "internal"
)

type Project 

type Project struct {
	Name       string `json:"name"`
	ModulePath string `json:"modulePath"`
	Kind       Kind   `json:"kind"`
	ConfigPath string `json:"configPath"`
}

Project describes a Krewire project for validation.

func (Project) Validate 

func (p Project) Validate() error

Validate checks project invariants.

type RequirementID 

type RequirementID string

RequirementID is a requirement identifier such as FRK-CLI-001 or KWL-CORE-001.

type Scope 

type Scope string

Scope is the ecosystem level a spec, test, or doc targets. Ordered: Workspace < Module < Domain < Package < Service < Func. See KWL-ARCH-J2K9Q.

Workspace is the Krewire Workspace (hub dir ~/Workspace/Dev/krewire with bin/kiw + 7 repos), which is also the Go `go.work` workspace at the hub root (see `go.work` and `AGENTS.md`). Domain is a DDD bounded context (e.g. catalog, user) — a cohesive set of Packages inside a Module (internal/<domain>/). Pre-extraction it is Package set, post-extraction it becomes its own Service (and often its own Module/Project). Service is a Krewire runtime deployable, implemented in Go as a main package (e.g. cmd/<service>/ or service/<name>/); Func is inside Package. 

const (
	ScopeWorkspace Scope = "Workspace"
	ScopeModule    Scope = "Module"
	ScopeDomain    Scope = "Domain"
	ScopePackage   Scope = "Package"
	ScopeService   Scope = "Service"
	ScopeFunc      Scope = "Func"
)

func ParseScope 

func ParseScope(s string) (Scope, error)

ParseScope parses s as a Scope, case-insensitive, returning UsageError on unknown. Accepted forms are the canonical names (Workspace, Module, Domain, Package, Service, Func), case-insensitive, with surrounding whitespace trimmed. "Project" is no longer a valid scope — use Module (Go module, formerly Project==Module).

func (Scope) IsValid 

func (s Scope) IsValid() bool

IsValid reports whether s is one of the six known scopes.

func (Scope) Less 

func (s Scope) Less(other Scope) bool

Less reports whether s is ordered before other.

func (Scope) Level 

func (s Scope) Level() int

Level returns the ordering index (0..5). Invalid scopes return -1.

type SpecID 

type SpecID string

SpecID is a Krewire specification identifier. Two forms are accepted:

  • Short: KWF-M8K2Q (ProjectId-Code)
  • Full file prefix: KWF-ARCH-M8K2Q (ProjectId-Scope-Code) — with or without slug suffix.

func ParseSpecID 

func ParseSpecID(s string) (SpecID, error)

ParseSpecID validates s as a SpecID and returns UsageError on failure.

func (SpecID) Code 

func (id SpecID) Code() string

Code returns the 5-char code component.

func (SpecID) Project 

func (id SpecID) Project() string

Project returns the ProjectId component (e.g., KWF).

func (SpecID) Scope 

func (id SpecID) Scope() string

Scope returns the Scope component or empty for short form.

type StackFrame 

type StackFrame struct {
	Func string
	File string
	Line int
}

StackFrame is one rendered-ready entry of a captured stack.

func StackOf 

func StackOf(err error) []StackFrame

StackOf extracts the most recently attached stack from err, or nil (KWL-P8W2N KWL-ERRV-002).

func (StackFrame) String 

func (f StackFrame) String() string

String renders "Func File:Line".

type Status 

type Status string

Status is the implementation status of a workload. 

const (
	StatusShipped Status = "shipped"
	StatusPlanned Status = "planned"
)

type Version 

type Version struct {
	Major      int
	Minor      int
	Patch      int
	PreRelease string
	Build      string
}

Version is a semantic version per https://semver.org/. Build metadata is retained but ignored for precedence.

func MustParseVersion 

func MustParseVersion(s string) Version

MustParseVersion parses s or panics. Use for constants.

func ParseVersion 

func ParseVersion(s string) (Version, error)

ParseVersion parses s as a semantic version. Leading "v" is optional.

func (Version) Compare 

func (v Version) Compare(other Version) int

Compare returns -1 if v < other, 0 if equal, 1 if v > other per semver precedence. Build metadata is ignored.

func (Version) Equal 

func (v Version) Equal(other Version) bool

Equal reports whether v == other (ignoring build).

func (Version) IsCompatible 

func (v Version) IsCompatible(required Version) bool

IsCompatible reports whether actual satisfies required per semver caret semantics for the Krewire ecosystem: for 0.y.z, minor must match; for >=1.0.0, major must match and actual >= required.

func (Version) Less 

func (v Version) Less(other Version) bool

Less reports whether v < other.

func (Version) String 

func (v Version) String() string

String returns the canonical string form without leading "v".

type Versioned 

type Versioned interface {
	Version() Version
}

Versioned is implemented by any module that exposes its version via core.Version.

type Workload 

type Workload struct {
	Kind    Kind   `json:"kind"`
	Package string `json:"package"`
	Title   string `json:"title"`
	SpecID  string `json:"specId"` // e.g. KWF-5XJFC
	Status  Status `json:"status"`
}

Workload describes one cell of the unified workload matrix.

func WorkloadFor 

func WorkloadFor(k Kind) (Workload, bool)

WorkloadFor returns the first Workload matching k and whether it was found.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.