Documentation
¶
Overview ¶
Package scaffold generates the initial project configuration and build context for a new cell.
Index ¶
- Constants
- func CopyDir(src, dst string) error
- func GenerateFlakeNix(stack string, modules []string, ver string, withNixhome bool, ...) string
- func GenerateFlakeNixWithMcp(stack string, modules []string, ver string, withNixhome bool, ...) string
- func IsGitURL(source string) bool
- func IsInitialized(dir string) bool
- func ResolveNixhome(source, buildDir, ver string, force bool) error
- func Scaffold(dir string, modelsSnippet string, nixhomePath string, force bool, ...) error
- func ScaffoldWithModules(dir string, modelsSnippet string, nixhomePath string, force bool, stack string, ...) error
- func SyncNixhome(srcPath, configDir string) error
- type GithubFlakeRef
- type InitFlowOptions
- type InitFlowResult
Constants ¶
const NixhomeSourceFile = ".devcell-source"
NixhomeSourceFile is the metadata file that tracks which source was used to populate .devcell/nixhome/. Used to detect when a different source would overwrite an existing nixhome.
Variables ¶
This section is empty.
Functions ¶
func CopyDir ¶
CopyDir recursively copies src directory to dst.
Guards against dst being nested inside src (e.g. a caller accidentally pointing a nixhome sync at a project's own directory): without this, the walk would recurse into paths it is itself writing, corrupting the copy partway through. This is a defensive backstop — callers should also reject that configuration upfront (see isPathNestedIn in syncNixhomeFromLocal) so the failure is a clear error instead of a silent partial copy.
func GenerateFlakeNix ¶
func GenerateFlakeNix(stack string, modules []string, ver string, withNixhome bool, nixPkgs ...cfg.NixPackages) string
GenerateFlakeNix produces a flake.nix string that imports the given stack and modules from the upstream devcell nixhome flake. stack is a stack name (e.g. "go"), modules is a list of module names, ver is the version tag, nixhomePath overrides the input URL to path:./nixhome. nixPkgs adds arbitrary nixpkgs packages, prioritized per channel (user override semantics). mcpEnabled lists MCP server names to enable (from [mcp] enabled in devcell.toml); each emits devcell.managedMcp.servers."<name>".enabled = true; in the flake.
func GenerateFlakeNixWithMcp ¶
func GenerateFlakeNixWithMcp(stack string, modules []string, ver string, withNixhome bool, mcpEnabled []string, nixPkgs ...cfg.NixPackages) string
GenerateFlakeNixWithMcp is like GenerateFlakeNix but also emits MCP server enablement lines from [mcp] enabled in devcell.toml.
func IsInitialized ¶
IsInitialized returns true when devcell.toml or .devcell.toml exists in dir.
func ResolveNixhome ¶
ResolveNixhome pulls nixhome into buildDir/nixhome/ from the given source.
- Local path: copy directly (rsync-like)
- Git URL: shallow sparse clone, extract nixhome/ subdir
- Empty source: clone from upstream repo at the given version tag
Always re-fetches; force is currently unused.
func ScaffoldWithModules ¶
func ScaffoldWithModules(dir string, modelsSnippet string, nixhomePath string, force bool, stack string, modules []string) error
Scaffold writes devcell.toml to dir (project root) and build artifacts (flake.nix, starship.toml) to dir/.devcell/ (build context, gitignored). ScaffoldWithModules is like Scaffold but also writes the selected modules list.
func SyncNixhome ¶
SyncNixhome copies the nixhome directory from srcPath into configDir/nixhome/. It replaces any existing nixhome copy to ensure fresh content each build. Also removes the outer flake.lock so nix regenerates it from the inner nixhome's inputs — prevents stale lock from pinning different nixpkgs than the base image, which would cause a full re-download. Writes .devcell-source to track the origin.
srcPath accepts either:
- a local filesystem path (copied as-is via CopyDir)
- a github flake ref like `github:owner/repo/ref?dir=subdir` — cloned via git (host-side; no nix dependency), then the subdir is treated as the source. This lets the thin builder mount a populated nixhome even when the user has no local checkout (CELL-38 clean-machine path).
Types ¶
type GithubFlakeRef ¶
type GithubFlakeRef struct {
Owner string
Repo string
Ref string // branch, tag, or commit. Defaults to "main" if absent.
Subdir string // empty when the flake is at the repo root.
}
GithubFlakeRef is the parsed form of a `github:owner/repo[/ref][?dir=subdir]` flake reference. Used to drive a host-side `git clone` for thin builds (we avoid requiring nix on the host — clone fetches what `nix flake metadata` would have materialized into /nix/store).
func ParseGithubFlakeRef ¶
func ParseGithubFlakeRef(ref string) (GithubFlakeRef, error)
ParseGithubFlakeRef parses a `github:` flake reference. Returns an error for any other scheme (including local paths) — callers should check IsFlakeRef or scheme-specific helpers first.
Accepted shapes:
github:owner/repo → ref="main", subdir="" github:owner/repo/branch → subdir="" github:owner/repo?dir=subdir → ref="main" github:owner/repo/branch?dir=subdir github:owner/repo/feature/wip?dir=nixhome (ref retains slashes)
func (GithubFlakeRef) CloneURL ¶
func (g GithubFlakeRef) CloneURL() string
CloneURL returns the https git URL for the parsed ref.
type InitFlowOptions ¶
type InitFlowOptions struct {
BaseDir string // project root directory
ConfigDir string // global config directory (~/.config/devcell)
NixhomeSrc string // nixhome source: local path, git URL, or "" for upstream
Stack string // explicit stack name ("" means base)
Modules []string // explicit modules (non-empty implies base stack when Stack is "")
Yes bool // skip interactive prompts, use defaults
Force bool // overwrite existing files
Offline bool // skip network I/O (git clone, ollama probe)
}
InitFlowOptions configures the shared initialization flow.
type InitFlowResult ¶
InitFlowResult holds the output of a successful init flow.
func RunInitFlow ¶
func RunInitFlow(opts InitFlowOptions) (*InitFlowResult, error)
RunInitFlow is the shared init logic used by both the docker engine's `cell init` and the first-run scaffold of every agent command. It resolves nixhome, takes the stack and modules from opts (stack defaults to "base"; there is no interactive picker), and scaffolds the project.
Source Files