project

Documentation

Overview

Package project reads .limabean.yaml, the file a repository keeps to say what VM it needs, for "limabean up".

The file comes with the repository, so it's untrusted: it can name secrets but never say where their values come from (a cmd: reference would run on the Mac), and limabean shows what it asks for before creating anything.

Index

• Constants
• Variables
• func DefaultName(dir string) string
• func Find(dir string) (string, error)
• func Schema(packs, presets []string, domain string) map[string]any
• type Claude
  • func (c Claude) Empty() bool
  • func (c Claude) Plugins() []string
• type Draft
  • func Detect(dir string, packOf func(tool string) string) (*Draft, error)
  • func (d *Draft) Empty() bool
  • func (d *Draft) Found() []string
  • func (d *Draft) Render() string
• type File
  • func Load(path string) (*File, error)
  • func Parse(b []byte, path string) (*File, error)
• type Marketplace
  • func (m Marketplace) Name() string

Constants

const FileName = ".limabean.yaml"

FileName is the project file's name; FileNames are the names it's found by.

const SchemaComment = "# yaml-language-server: $schema=" + SchemaURL + "\n"

SchemaComment is the first line limabean writes into a project file, so editors with the YAML language server (VS Code, Cursor, Zed, Neovim) complete and check its keys.

const SchemaURL = "https://rossedman.io/limabean/limabean.schema.json"

SchemaURL is where the docs site publishes Schema, for editors.

Variables

var ErrNotFound = errors.New("no " + FileName + " (or .yml) here or in a parent directory")

ErrNotFound is Find's error when there's no project file.

var FileNames = []string{FileName, ".limabean.yml"}

Functions

func DefaultName

func DefaultName(dir string) string

DefaultName turns a directory's name into a VM name.

func Find

func Find(dir string) (string, error)

Find looks for the project file in dir and its parents, and returns its path.

func Schema

func Schema(packs, presets []string, domain string) map[string]any

Schema is the JSON Schema of a project file. Its patterns are the ones Load checks with; packs and presets are what editors offer, and other names still pass, since a Mac can have packs of its own. domain is the pattern a network.allow domain must match.

Types

type Claude

type Claude struct {
	Marketplaces []Marketplace `yaml:"marketplaces"`
}

Claude is what Claude Code in the VM gets: plugins, from their marketplaces, in its user settings. Skills, agents and the rest come inside plugins. All of it is fetched inside the VM.

func (Claude) Empty

func (c Claude) Empty() bool

Empty reports whether the file asks for nothing for Claude.

func (Claude) Plugins

func (c Claude) Plugins() []string

Plugins lists every plugin to turn on.

type Draft

type Draft struct {
	Packs   []string          // sorted
	Tools   map[string]string // version pins no pack covers
	Ports   []int             // sorted
	Setup   []string          // commands, in order
	Start   []string
	Secrets []string // names from .env.example that look like credentials
	// contains filtered or unexported fields
}

A Draft is a project file worked out from what's in a repository, for limabean init --project. Detect only reads files: it never runs the repository's code or follows a symlink out of it.

func Detect

func Detect(dir string, packOf func(tool string) string) (*Draft, error)

Detect works out a draft project file from the files in dir and the directories directly under it, so a monorepo's web/ and api/ count too. packOf names the pack that installs a mise tool ("core" for one every VM has), or "".

func (*Draft) Empty

func (d *Draft) Empty() bool

Empty reports whether nothing was recognised.

func (*Draft) Found

func (d *Draft) Found() []string

Found lists what Detect recognised, one line each, for the user.

func (*Draft) Render

func (d *Draft) Render() string

Render writes the draft as a commented project file.

type File

type File struct {
	Name  string   `yaml:"name"`  // the VM's name; default the directory's
	Env   string   `yaml:"env"`   // environment template; default scratch
	Repo  string   `yaml:"repo"`  // what to clone; default the checkout's origin
	Packs []string `yaml:"packs"` // the VM's packs besides core; PACKS doesn't apply
	// Tools are the project's own mise tools, tool: version, and Apt its
	// own Ubuntu packages: what a pack would add, without one.
	Tools   map[string]string `yaml:"tools"`
	Apt     []string          `yaml:"apt"`
	Without []string          `yaml:"without"` // no longer used: accepted so older files still load
	CPUs    int               `yaml:"cpus"`
	Memory  int               `yaml:"memory"` // GiB
	Disk    int               `yaml:"disk"`   // GiB of the system disk
	Network struct {
		Allow  []string `yaml:"allow"`
		Locked bool     `yaml:"locked"`
	} `yaml:"network"`
	Secrets []string `yaml:"secrets"` // names of secrets the VM needs
	Ports   []int    `yaml:"ports"`   // what the project serves, to show after up
	Setup   string   `yaml:"setup"`   // shell commands run in the clone once, after creating
	Start   string   `yaml:"start"`   // shell commands run in the clone, in the background, after every up
	// Vars are plain variables for the VM's shells, setup and start;
	// secrets go in Secrets instead.
	Vars   map[string]string `yaml:"vars"`
	Claude Claude            `yaml:"claude"` // plugins for Claude Code in the VM
}

File is a .limabean.yaml.

func Load

func Load(path string) (*File, error)

Load reads and checks a project file. Unknown keys are errors, so typos don't go unnoticed. The name defaults to the file's directory's.

func Parse

func Parse(b []byte, path string) (*File, error)

Parse checks a project file's contents, as Load does for the file at path.

type Marketplace

type Marketplace struct {
	Source  string   `yaml:"marketplace"` // GitHub owner/repo, or an https git URL
	Plugins []string `yaml:"plugins"`     // plugin@marketplace
}

Marketplace is a plugin marketplace and the plugins to turn on from it.

func (Marketplace) Name

func (m Marketplace) Name() string

Name is the marketplace's name, as its plugins give it after the @.