projecttool

package
v0.3.0-alpha.1 Latest Latest
Warning

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

 Go to latest Published: Aug 4, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Overview

Package projecttool provides pure inspection, deterministic generation, and Node-free builds for a consumer-owned Modary application Definition. Its F0 public API and versioned generated documents are alpha contracts.

Index

Constants

View Source 
const (
	// ProjectManifestName is the fixed consumer project manifest name.
	ProjectManifestName = "modary.yaml"
	// MaximumManifestBytes bounds configuration input before YAML decoding.
	MaximumManifestBytes = int64(1 << 20)
)
View Source 
const (
	// GraphSchemaVersion identifies the alpha generated Module graph format.
	GraphSchemaVersion = "modary.module-graph/v1alpha1"
	// CatalogSchemaVersion identifies the alpha generated Action catalog format.
	CatalogSchemaVersion = "modary.action-catalog/v1alpha1"
	// MaximumGeneratedArtifactBytes bounds both rendered and existing artifacts.
	MaximumGeneratedArtifactBytes = int64(64 << 20)
)
View Source 
const CommandUsage = `Usage:
  modary verify
  modary generate
  modary generate --check
  modary check
  modary build
  modary help
`

CommandUsage is the stable usage text for a consumer-owned project tool.

Variables

View Source 
var (
	// ErrContextRequired reports a nil project-tool context.
	ErrContextRequired = errors.New("project tool context is required")
	// ErrUsage reports invalid command syntax or command options.
	ErrUsage = errors.New("invalid project tool usage")
	// ErrDrift reports missing or differing generated artifacts.
	ErrDrift = errors.New("generated artifacts have drift")
	// ErrCallbackPanic reports a contained consumer callback panic.
	ErrCallbackPanic = errors.New("project tool callback panic")
	// ErrBuildUnsupported reports that the current platform cannot enforce the
	// secure compiler-staging contract required by Project.Build.
	ErrBuildUnsupported = errors.New("secure project build is unsupported")
)

Functions

func Run 

func Run(ctx context.Context, args []string, provider DefinitionProvider, options Options) error

Run dispatches pure consumer project commands. Invalid syntax and help do not read the project, while an invalid manifest fails before DefinitionProvider.

Types

type BuildOptions 

type BuildOptions struct {
	Stdout io.Writer
	Stderr io.Writer
}

BuildOptions receives Go compiler output. Nil writers select the process standard streams; typed nil writers are rejected before compiler invocation. Writers are trusted, cooperative dependencies: Write must return. Build can bound a canceled compiler and inherited compiler pipes, but cannot interrupt an arbitrary io.Writer blocked inside its own Write method.

type BuildResult 

type BuildResult struct {
	Output string `json:"output"`
}

BuildResult identifies the installed consumer binary.

type BuildTarget 

type BuildTarget struct {
	Package string `yaml:"package" json:"package"`
	Output  string `yaml:"output" json:"output"`
}

BuildTarget declares the consumer Go package and final binary location using the same portable path grammar as Outputs.

type CallbackPanicError 

type CallbackPanicError struct{ Operation string }

CallbackPanicError reports a recovered consumer callback panic without exposing the recovered value, which may contain application secrets.

func (*CallbackPanicError) Error 

func (err *CallbackPanicError) Error() string

Error describes the callback operation without exposing the panic value.

func (*CallbackPanicError) Unwrap 

func (err *CallbackPanicError) Unwrap() error

Unwrap classifies the failure as ErrCallbackPanic, including for a typed-nil receiver.

type CatalogDocument 

type CatalogDocument struct {
	SchemaVersion string                `json:"schema_version"`
	Application   appkit.Metadata       `json:"application"`
	Actions       []action.CatalogEntry `json:"actions"`
}

CatalogDocument is the alpha on-disk Action contract identified by CatalogSchemaVersion.

type DefinitionProvider 

type DefinitionProvider = appkit.DefinitionProvider

DefinitionProvider constructs the consumer's explicit Go composition. Run calls it once only after command syntax and modary.yaml have been validated.

type Drift 

type Drift struct {
	Path   string      `json:"path"`
	Status DriftStatus `json:"status"`
}

Drift identifies one generated artifact that is absent or differs from its deterministic expected bytes.

type DriftError 

type DriftError struct{ Items []Drift }

DriftError is returned by command check mode and Build. Programmatic callers can use Project.Check when drift is expected data rather than an error.

func (*DriftError) Error 

func (err *DriftError) Error() string

Error renders the complete deterministic drift list.

func (*DriftError) Unwrap 

func (err *DriftError) Unwrap() error

Unwrap classifies the mismatch as ErrDrift, including for a typed-nil receiver.

type DriftStatus 

type DriftStatus string

DriftStatus classifies a generated artifact mismatch. 

const (
	// DriftMissing means the configured artifact does not exist.
	DriftMissing DriftStatus = "missing"
	// DriftDifferent means the artifact bytes differ from canonical output.
	DriftDifferent DriftStatus = "different"
)

type Generation 

type Generation struct {
	Written   []string `json:"written"`
	Unchanged []string `json:"unchanged"`
}

Generation reports deterministic relative paths changed or already current.

type GraphDocument 

type GraphDocument struct {
	SchemaVersion string                       `json:"schema_version"`
	Application   appkit.Metadata              `json:"application"`
	Modules       []ModuleInfo                 `json:"modules"`
	Edges         []module.GraphEdge           `json:"edges"`
	Order         []string                     `json:"order"`
	Provides      map[module.Capability]string `json:"provides"`
}

GraphDocument is the alpha on-disk Module graph contract identified by GraphSchemaVersion.

type Manifest 

type Manifest struct {
	Application appkit.Metadata `yaml:"application" json:"application"`
	Outputs     Outputs         `yaml:"outputs" json:"outputs"`
	Build       BuildTarget     `yaml:"build" json:"build"`
}

Manifest is the strict consumer project file. Go Definition composition is deliberately absent: application code remains the sole Module source.

func ParseManifest 

func ParseManifest(data []byte) (Manifest, error)

ParseManifest parses exactly one strict YAML document. YAML aliases and anchors are rejected so configuration meaning is local and reviewable.

type ModuleInfo 

type ModuleInfo struct {
	ID         string              `json:"id"`
	Version    string              `json:"version"`
	Type       module.ModuleType   `json:"type"`
	Requires   []module.Capability `json:"requires,omitempty"`
	Provides   []module.Capability `json:"provides,omitempty"`
	Migrations []string            `json:"migrations,omitempty"`
}

ModuleInfo is the deterministic callback-free projection of one Module.

type Options 

type Options struct {
	Root   string
	Stdout io.Writer
	Stderr io.Writer
}

Options configures the consumer-owned project command. An empty root selects the current directory and nil writers select the process standard streams.

type Outputs 

type Outputs struct {
	Graph      string `yaml:"graph" json:"graph"`
	Actions    string `yaml:"actions" json:"actions"`
	TypeScript string `yaml:"typescript,omitempty" json:"typescript,omitempty"`
}

Outputs declares consumer-owned generated artifact locations. Paths use `/` separators and portable ASCII components matching [A-Za-z0-9._-]+.

type Project 

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

Project is an immutable validated project-root and output policy. It stores no Module composition and owns no open resource.

func Load 

func Load(root string) (*Project, error)

Load validates the canonical root, its strict modary.yaml, output aliases, and every existing output path component without following symlinks.

func LoadContext 

func LoadContext(ctx context.Context, root string) (*Project, error)

LoadContext is the cancelable form of Load. The root directory is opened before its identity is inspected, and that verified handle is used for the entire load operation.

func (*Project) Build 

func (project *Project) Build(ctx context.Context, definition appkit.Definition, options BuildOptions) (result BuildResult, resultErr error)

Build verifies the supplied Definition, requires every generated artifact to be current, and invokes only "go build" for the configured consumer package. Ambient GOFLAGS, GOENV, and GOWORK are disabled so they cannot inject tool execution or replace the verified consumer module graph. The compiler writes into a private staging directory outside the project. A validated output is copied through the verified project Root and installed with one sibling rename, which is atomic only where the host filesystem guarantees rename atomicity. An existing live binary is never moved out of the way first. Same-root builds are serialized within this process and post-install failures attempt rollback from a prepared sibling copy.

func (*Project) Check 

func (project *Project) Check(definition appkit.Definition) ([]Drift, error)

Check compares every expected artifact without creating a directory or file. Drift entries are sorted by path.

func (*Project) CheckContext 

func (project *Project) CheckContext(ctx context.Context, definition appkit.Definition) ([]Drift, error)

CheckContext is the cancelable form of Check.

func (*Project) Generate 

func (project *Project) Generate(definition appkit.Definition) (Generation, error)

Generate validates and renders the complete batch before writing. Every changed file is replaced with one atomic rename, but the generated set is not a filesystem-wide transaction. Calls in this process are serialized per root and a commit failure attempts to roll already replaced files back in process.

func (*Project) GenerateContext 

func (project *Project) GenerateContext(ctx context.Context, definition appkit.Definition) (Generation, error)

GenerateContext is the cancelable form of Generate. Cancellation before the first replacement removes all prepared files and leaves every configured artifact at its baseline state.

func (*Project) Manifest 

func (project *Project) Manifest() Manifest

Manifest returns the validated, output-only consumer manifest.

func (*Project) Root 

func (project *Project) Root() string

Root returns the canonical consumer root captured by Load.

func (*Project) Verify 

func (project *Project) Verify(definition appkit.Definition) (Snapshot, error)

Verify validates the manifest/Definition identity and renders every expected artifact in memory, but performs no write.

func (*Project) VerifyContext 

func (project *Project) VerifyContext(ctx context.Context, definition appkit.Definition) (Snapshot, error)

VerifyContext is the cancelable form of Verify.

type Snapshot 

type Snapshot struct {
	Application appkit.Metadata       `json:"application"`
	Modules     []ModuleInfo          `json:"modules"`
	Graph       module.Graph          `json:"graph"`
	Actions     []action.CatalogEntry `json:"actions"`
}

Snapshot is a defensive, deterministic projection of the pure consumer Definition. It contains no lifecycle callback, handler, migration FS, or service resolver.

func Inspect 

func Inspect(definition appkit.Definition) (Snapshot, error)

Inspect validates static Module registrations, migration declarations, capabilities, dependency graph, Action ownership, and Action contracts. It never starts Modules or invokes a consumer callback.

func InspectContext 

func InspectContext(ctx context.Context, definition appkit.Definition) (Snapshot, error)

InspectContext is the cancelable form of Inspect. Cancellation is observed between each registration and contract canonicalization boundary.

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.