appdef

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Nov 14, 2025 License: BSD-3-Clause Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// JsonFileName defines the file name of the app manifest,
	// that should appear in the root of each webkit dir.
	JsonFileName = "app.json"
)

Variables

View Source 
var Commands = []Command{
	CommandFormat,
	CommandLint,
	CommandTest,
	CommandBuild,
}

Commands defines all the Commands available that should be run in order.

Functions

func GenerateSchema added in v0.2.0 

func GenerateSchema() ([]byte, error)

GenerateSchema generates a JSON schema for the Definition type.

func ParseResourceReference added in v0.0.15 

func ParseResourceReference(value any) (resourceName, outputName string, ok bool)

ParseResourceReference parses a resource reference string (e.g., "db.connection_url").

Resource references follow the format: "resource_name.output_name".

Types

type App 

type App struct {
	Name             string                  `json:"name" validate:"required,lowercase,alphanumdash" description:"Unique identifier for the app (lowercase, hyphenated)"`
	Title            string                  `json:"title" validate:"required" description:"Human-readable app name for display purposes"`
	Type             AppType                 `json:"type" validate:"required,oneof=svelte-kit golang payload" description:"Application type (payload, svelte-kit, golang)"`
	Description      string                  `` /* 128-byte string literal not displayed */
	Path             string                  `json:"path" validate:"required" description:"Relative file path to the app's source code directory"`
	Build            Build                   `json:"build" description:"Build configuration for Docker containerisation"`
	Infra            Infra                   `json:"infra" validate:"required" description:"Infrastructure and deployment configuration"`
	Env              Environment             `json:"env" description:"Environment variables specific to this app"`
	UsesNPM          *bool                   `json:"usesNPM" description:"Whether this app should be included in the pnpm workspace (auto-detected if not set)"`
	TerraformManaged *bool                   `json:"terraformManaged,omitempty" description:"Whether this app's infrastructure is managed by Terraform (defaults to true)"`
	Domains          []Domain                `json:"domains,omitzero" description:"Domain configurations for accessing this app"`
	Tools            map[string]Tool         `json:"tools,omitempty" inline:"true" description:"Build tools required for CI/CD workflows"`
	Commands         map[Command]CommandSpec `` /* 161-byte string literal not displayed */
}

App represents a single application within the webkit project. Each app has its own build configuration, infrastructure requirements, environment variables, and deployment settings. Apps can be of different types (Payload CMS, SvelteKit, GoLang) and are deployed independently.

func (*App) InstallCommands added in v0.4.0 

func (a *App) InstallCommands() []string

InstallCommands returns the shell commands needed to install all tools for this app. Commands are generated based on the tool's Type field:

  • "go": generates "go install <name>@<version>"
  • "pnpm": generates "pnpm add -g <name>@<version>"
  • "script": uses the Install field directly

If a tool provides an Install field, it overrides the auto-generated command.

func (*App) IsTerraformManaged added in v0.0.8 

func (a *App) IsTerraformManaged() bool

IsTerraformManaged returns whether this app should be managed by Terraform. It defaults to true when the field is nil or explicitly set to true.

func (*App) Language 

func (a *App) Language() string

Language determines what language ecosystem a given app is. Either "go" or "js".

func (*App) MergeEnvironments 

func (a *App) MergeEnvironments(shared Environment) Environment

MergeEnvironments merges the shared env with the apps, with the app specific variables taking precedence.

func (*App) OrderedCommands 

func (a *App) OrderedCommands() []CommandSpec

OrderedCommands returns the app's commands in canonical order with Name populated.

func (*App) PrimaryDomain added in v0.0.19 

func (a *App) PrimaryDomain() string

PrimaryDomain returns the primary domain for this app. It first looks for a domain with type "primary" in the Domains array. If no primary domain is found, it returns the first domain in the array. If the Domains array is empty, it returns an empty string.

func (*App) ShouldRelease added in v0.0.10 

func (a *App) ShouldRelease() bool

ShouldRelease returns whether this app should be built and released in CI/CD. It defaults to true when the field is nil or explicitly set to true.

func (*App) ShouldUseNPM 

func (a *App) ShouldUseNPM() bool

ShouldUseNPM returns whether this app should be included in pnpm workspace. It checks the UsesNPM field first, and if not set, defaults based on Language().

type AppType 

type AppType string

AppType defines the type of application being run. 

const (
	AppTypeSvelteKit AppType = "svelte-kit"
	AppTypeGoLang    AppType = "golang"
	AppTypePayload   AppType = "payload"
)

AppType constants.

func (AppType) String 

func (a AppType) String() string

String implements fmt.Stringer on the AppType.

type Build 

type Build struct {
	Dockerfile string `json:"dockerfile" description:"Path to the Dockerfile relative to the app directory"`
	Port       int    `json:"port,omitempty" validate:"omitempty,min=1,max=65535" description:"Port number the app listens on inside the container"`
	Release    *bool  `json:"release,omitempty" description:"Whether to build and release this app in CI/CD (defaults to true)"`
}

Build defines Docker build configuration for containerised applications. These settings control how the app is built and exposed in container environments.

type Command 

type Command string

Command defines the type of action that will be actioned. 

const (
	CommandLint   Command = "lint"
	CommandTest   Command = "test"
	CommandFormat Command = "format"
	CommandBuild  Command = "build"
)

Command constants.

func (Command) String 

func (c Command) String() string

String implements fmt.Stringer on Command.

type CommandSpec 

type CommandSpec struct {
	Name     string `json:"-"`
	Cmd      string `json:"command,omitempty" description:"The shell command to execute (e.g., 'pnpm build')"`
	SkipCI   bool   `json:"skip_ci,omitempty" description:"Whether to skip running this command in CI/CD pipelines"`
	Timeout  string `json:"timeout,omitempty" description:"Maximum execution time for the command (e.g., '5m', '1h')"`
	Disabled bool   `json:"-"` // Set during unmarshal
}

CommandSpec defines an action for an app that can run in CI/CD or locally. Commands can be specified as a boolean (enable/disable), a string (command override), or an object (full configuration with timeout and CI settings).

func (*CommandSpec) JSONSchemaOneOf 

func (*CommandSpec) JSONSchemaOneOf() []interface{}

JSONSchemaOneOf returns the polymorphic schema options.

func (*CommandSpec) UnmarshalJSON 

func (c *CommandSpec) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler to

type Contact 

type Contact struct {
	Email       string
	Phone       string
	Coordinates struct{ Latitude, Longitude string }
	Address     schemaorg.Address
}

type Definition 

type Definition struct {
	Schema        string        `json:"$schema,omitempty" jsonschema:"-" description:"JSON Schema reference for IDE validation and autocomplete"`
	WebkitVersion string        `` /* 129-byte string literal not displayed */
	Project       Project       `` /* 131-byte string literal not displayed */
	Notifications Notifications `json:"notifications" description:"Alert and notification settings for the project"`
	Shared        Shared        `json:"shared" description:"Shared configuration that applies to all apps"`
	Resources     []Resource    `json:"resources" description:"Infrastructure resources such as databases and storage buckets"`
	Apps          []App         `` /* 137-byte string literal not displayed */
}

Definition represents the complete webkit application configuration. It defines the structure of the app.json file used to configure all aspects of a webkit project including apps, resources, and infrastructure.

func Read 

func Read(root afero.Fs) (*Definition, error)

func (*Definition) ApplyDefaults 

func (d *Definition) ApplyDefaults() error

ApplyDefaults ensures all required defaults are set on the Definition. This should be called after unmarshaling and before validation.

func (*Definition) ContainsGo 

func (d *Definition) ContainsGo() bool

ContainsGo returns true if any of the apps are marked as Go.

func (*Definition) ContainsJS 

func (d *Definition) ContainsJS() bool

ContainsJS returns true if any of the apps are marked as JS.

func (*Definition) FilterTerraformManaged added in v0.0.8 

func (d *Definition) FilterTerraformManaged() (*Definition, SkippedItems)

FilterTerraformManaged creates a filtered copy of the Definition containing only apps and resources that are managed by Terraform.

Returns the filtered definition and information about what was skipped.

func (*Definition) GetAppsByType added in v0.0.8 

func (d *Definition) GetAppsByType(appType AppType) []App

GetAppsByType returns all apps of the specified type from the definition.

func (*Definition) GithubLabels 

func (d *Definition) GithubLabels() []string

GithubLabels returns the labels that will appear on the GitHub repository by looking at the application types.

func (*Definition) HasAppType added in v0.0.8 

func (d *Definition) HasAppType(appType AppType) bool

HasAppType checks if the definition contains an app of the specified type.

func (*Definition) MergeAllEnvironments 

func (d *Definition) MergeAllEnvironments() Environment

MergeAllEnvironments merges shared env variables with all apps' environments. App-specific values take precedence over shared ones. If multiple apps define the same variable, the last app in the list wins.

func (*Definition) Validate added in v0.2.0 

func (d *Definition) Validate(fs afero.Fs) []error

Validate performs comprehensive validation on the Definition, collecting all errors before returning. Returns nil if validation passes.

type Domain 

type Domain struct {
	Name     string     `json:"name" validate:"required" description:"Domain name without protocol (e.g., 'example.com' or 'api.example.com')"`
	Type     DomainType `json:"type" validate:"omitempty,oneof=primary alias unmanaged" description:"Domain type (primary, alias, unmanaged)"`
	Zone     string     `json:"zone,omitempty" description:"DNS zone for the domain if different from default"`
	Wildcard bool       `json:"wildcard,omitempty" description:"Whether this is a wildcard domain (e.g., '*.example.com')"`
}

Domain represents a domain name configuration for accessing an app. Domains can be primary, aliases, or unmanaged depending on your DNS setup.

type DomainType 

type DomainType string

DomainType defines the type of domain that should be provisioned. 

const (
	DomainTypePrimary   DomainType = "primary"
	DomainTypeAlias     DomainType = "alias"
	DomainTypeUnmanaged DomainType = "unmanaged"
)

DomainType constants.

func (DomainType) String 

func (d DomainType) String() string

String implements fmt.Stringer on the DomainType.

type EnvSource 

type EnvSource string

EnvSource defines the type of application being run. 

const (
	// EnvSourceValue is a static string value (default).
	// Example: "https://api.example.com"
	EnvSourceValue EnvSource = "value"

	// EnvSourceResource references a Terraform resource output.
	// Example: "db.connection_url"
	EnvSourceResource EnvSource = "resource"

	// EnvSourceSOPS is an encrypted secret stored in a SOPS file.
	// Example: "secrets/production.yaml:API_KEY"
	EnvSourceSOPS EnvSource = "sops"
)

func (EnvSource) String 

func (e EnvSource) String() string

String implements fmt.Stringer on the EnvSource.

type EnvValue 

type EnvValue struct {
	Source EnvSource `` /* 148-byte string literal not displayed */
	// Value holds the actual value or reference depending on the source type:
	// - "value": A static string (e.g., "https://api.example.com")
	// - "resource": A Terraform resource reference (e.g., "db.connection_url")
	// - "sops": The variable name/key to lookup in the SOPS file (e.g., "API_KEY")
	Value any `json:"value,omitempty" description:"The value or reference for this variable (format depends on source type)"`
}

EnvValue represents a single environment variable configuration. It specifies both the source type and the value/reference for the variable.

type EnvVar 

type EnvVar map[string]EnvValue

EnvVar is a map of variable names to their value configurations. Each key is the environment variable name, and the value defines where the variable's value comes from (static value, resource output, or secret).

func CloneEnvVar added in v0.2.4 

func CloneEnvVar(src EnvVar) EnvVar

CloneEnvVar creates a shallow copy of an EnvVar map. This prevents mutation of the original map. Returns nil if the source is nil.

func MergeVars added in v0.2.4 

func MergeVars(base, override EnvVar) EnvVar

MergeVars merges two EnvVar maps, with override taking precedence over base. Returns a new map without mutating the inputs.

type EnvWalkEntry 

type EnvWalkEntry struct {
	Environment env.Environment
	Key         string
	Value       any
	Source      EnvSource
	Map         EnvVar
}

EnvWalkEntry holds the details of a single env variable during iteration.

type Environment 

type Environment struct {
	Default    EnvVar `` /* 132-byte string literal not displayed */
	Dev        EnvVar `json:"dev,omitempty" inline:"true" description:"Environment variables specific to the development environment"`
	Staging    EnvVar `json:"staging,omitempty" inline:"true" description:"Environment variables specific to the staging environment"`
	Production EnvVar `json:"production,omitempty" inline:"true" description:"Environment variables specific to the production environment"`
}

Environment contains environment-specific variable configurations. Variables can be defined per environment (dev, staging, production) or set once in 'default' to apply across all environments.

func (Environment) GetVarsForEnvironment added in v0.0.25 

func (e Environment) GetVarsForEnvironment(target env.Environment) (EnvVar, error)

GetVarsForEnvironment returns the EnvVar map for the specified environment. Returns an error if the environment is unknown.

func (Environment) Walk 

func (e Environment) Walk(fn EnvironmentWalker)

Walk iterates over all environments and calls fn for each env variable.

func (Environment) WalkE 

func (e Environment) WalkE(fn EnvironmentWalkerE) error

WalkE iterates over all environments and calls fn for each env variable. If fn returns an error, iteration stops and the error is returned.

type EnvironmentWalker 

type EnvironmentWalker func(entry EnvWalkEntry)

EnvironmentWalker defines a function that processes one env entry.

type EnvironmentWalkerE 

type EnvironmentWalkerE func(entry EnvWalkEntry) error

EnvironmentWalkerE defines a function that processes one env entry and may return an error.

type GitHubRepo 

type GitHubRepo struct {
	Owner string `json:"owner" validate:"required" description:"GitHub username or organisation that owns the repository"`
	Name  string `json:"name" validate:"required" description:"Repository name on GitHub"`
}

GitHubRepo defines the metadata for GitHub repositories. This information is used for CI/CD integration, secrets management, and linking documentation to the source repository.

type Infra 

type Infra struct {
	Provider ResourceProvider `json:"provider" validate:"required" description:"Cloud infrastructure provider (digitalocean, backblaze)"`
	Type     string           `json:"type" validate:"required" description:"Infrastructure type (vm, app, container, function)"`
	Config   map[string]any   `json:"config" description:"Provider-specific infrastructure configuration options"`
}

Infra defines infrastructure and deployment configuration for an app. This includes the cloud provider, deployment type (VM, container, etc.), and provider-specific configuration options. 

type MenuItem struct {
	Identifier string
	Name       string
	URL        string
	Weight     string
	Children   []MenuItem
	Params     map[string]any
}

type Notifications added in v0.0.36 

type Notifications struct {
	WebhookURL string `` /* 126-byte string literal not displayed */
}

Notifications defines alert and notification settings for the project. Provider-agnostic configuration supporting Slack, Discord, and other webhook-based services.

type Project 

type Project struct {
	Name        string     `` /* 126-byte string literal not displayed */
	Title       string     `json:"title" validate:"required" description:"Human-readable project name displayed in documentation and UIs"`
	Description string     `json:"description" validate:"required,max=200" description:"Brief description of the project's purpose and functionality"`
	Repo        GitHubRepo `json:"repo" validate:"required" description:"GitHub repository information for the project"`
}

Project defines root metadata about the project such as business names and descriptions. This information is used throughout webkit for identification, documentation generation, and CI/CD configuration.

type Resource 

type Resource struct {
	Name             string               `` /* 161-byte string literal not displayed */
	Type             ResourceType         `` /* 139-byte string literal not displayed */
	Provider         ResourceProvider     `` /* 170-byte string literal not displayed */
	Config           map[string]any       `json:"config" description:"Provider-specific resource configuration (e.g., size, region, version)"`
	Backup           ResourceBackupConfig `json:"backup,omitempty" description:"Backup configuration for the resource"`
	TerraformManaged *bool                `json:"terraformManaged,omitempty" description:"Whether this resource is managed by Terraform (defaults to true)"`
}

Resource represents an infrastructure component that applications depend on, such as databases, storage buckets, or caches. Resources are provisioned via Terraform and their outputs are made available to apps through environment variables.

func (*Resource) GitHubSecretName 

func (r *Resource) GitHubSecretName(environment env.Environment, output string) string

GitHubSecretName returns the GitHub secret name for a resource output. Format: TF_{ENVIRONMENT}_{RESOURCE_NAME}_{OUTPUT_NAME} (uppercase)

Example: 

resource.GitHubSecretName(env.Production, "connection_url")
↓
"TF_PROD_DB_CONNECTION_URL"

func (*Resource) IsTerraformManaged added in v0.0.8 

func (r *Resource) IsTerraformManaged() bool

IsTerraformManaged returns whether this resource should be managed by Terraform. It defaults to true when the field is nil or explicitly set to true.

type ResourceBackupConfig 

type ResourceBackupConfig struct {
	Enabled bool `json:"enabled" description:"Whether to enable automated backups for this resource"`
}

ResourceBackupConfig defines backup behaviour for a resource. Backups are enabled by default for all resources that support them.

type ResourceProvider 

type ResourceProvider string

ResourceProvider defines a provider of cloud infra. 

const (
	ResourceProviderDigitalOcean ResourceProvider = "digitalocean"
	ResourceProviderBackBlaze    ResourceProvider = "backblaze"
	ResourceProviderTurso        ResourceProvider = "turso"
)

ResourceProvider constants.

func (ResourceProvider) String 

func (r ResourceProvider) String() string

String implements fmt.Stringer on the ResourceProvider.

type ResourceType 

type ResourceType string

ResourceType defines the type of resource to be provisioned. 

const (
	ResourceTypePostgres ResourceType = "postgres"
	ResourceTypeS3       ResourceType = "s3"
	ResourceTypeSQLite   ResourceType = "sqlite"
)

ResourceType constants.

func (ResourceType) Outputs 

func (r ResourceType) Outputs() []string

Outputs returns the required outputs for a resource type for Terraform.

These should always be exported to GitHub secrets regardless of user config defined in the app definition.

func (ResourceType) String 

func (r ResourceType) String() string

String implements fmt.Stringer on the ResourceType.

type Shared 

type Shared struct {
	Env Environment `json:"env" description:"Environment variables shared across all apps"`
}

Shared contains configuration that is shared across all applications in the project, such as common environment variables.

type SkippedItems added in v0.0.8 

type SkippedItems struct {
	Apps      []string
	Resources []string
}

SkippedItems contains information about apps and resources that were filtered out due to not being Terraform managed.

type Social 

type Social struct {
	Twitter   string
	LinkedIn  string
	GitHub    string
	YouTube   string
	Facebook  string
	Instagram string
	TikTok    string
	Dribbble  string
}

type Tool added in v0.4.0 

type Tool struct {
	Type    string `json:"type" inline:"true" description:"Installation method: 'go', 'pnpm', or 'script'"`
	Name    string `json:"name,omitempty" inline:"true" description:"Package path (for 'go') or package name (for 'pnpm')"`
	Version string `json:"version,omitempty" inline:"true" description:"Version to install (e.g., 'latest', 'v0.2.543')"`
	Install string `json:"install,omitempty" inline:"true" description:"Custom installation command (overrides auto-generated command)"`
}

Tool represents a build tool with its installation method. Supports three types: "go", "pnpm", and "script".

For "go" and "pnpm" types, the Name and Version fields are used to generate the installation command automatically.

For "script" type, the Install field must contain the complete installation command.

The Install field can be used with any type to override the auto-generated command.

Source Files

View all Source files

Directories

Path Synopsis

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.