Maintain

Maintain is the build orchestrator for the Land project. It coordinates shell scripts, a Rust CLI with embedded Rhai scripting, and a Turborepo task graph to produce deterministic builds across all Land elements. Unlike Mountain, Cocoon, or Rest, Maintain does not need to be recompiled when its source changes - it is a build wrapper, not a compiled artifact that runs inside the editor.

What Maintain provides

Architecture

Maintain is a Rust binary and library. The CLI layer accepts subcommands and delegates to the Rhai scripting engine or direct build functions. Configuration editing is performed through toml_edit and json5 for structured, non-lossy modifications to project configuration files.

graph TB
    subgraph "Maintain Build System"
        LibraryRS["Source/Library.rs\nEntry point"]
        CLI["Source/Build/CLI.rs\nCommand-line interface (clap)"]
        Constant["Source/Build/Constant.rs\nBuild constants"]
        Definition["Source/Build/Definition.rs\nBuild group definitions"]
        FnRS["Source/Build/Fn.rs\nBuild function dispatch"]
        Error["Source/Build/Error.rs\nError types"]
        Logger["Source/Build/Logger.rs\nColored terminal output"]
        Process["Source/Build/Process.rs\nChild process management"]
        TomlEdit["Source/Build/TomlEdit.rs\nCargo.toml editor"]
        JsonEdit["Source/Build/JsonEdit.rs\nJSON5 editor"]
        Pascalize["Source/Build/Pascalize.rs\nPascalCase naming utilities"]
        GetTauri["Source/Build/GetTauriTargetTriple.rs\nPlatform detection"]
        EnvResolve["Source/Build/EnvironmentResolver.rs\nEnvironment variable resolution"]
    end

    subgraph "Rhai Scripting"
        ConfigLoader["Source/Build/Rhai/ConfigLoader.rs\nConfiguration file loading"]
        ScriptRunner["Source/Build/Rhai/ScriptRunner.rs\nScript execution engine"]
        RhaiEnvResolve["Source/Build/Rhai/EnvironmentResolver.rs\nEnvironment in scripts"]
    end

    subgraph "Shell Scripts"
        DebugSh["Debug.sh\nDebug build entry"]
        DevMountain["Dev-Mountain.sh\nMountain development mode"]
        ReleaseSh["Release.sh\nRelease build entry"]
        ProfileSh["Profile.sh\nPerformance profiling"]
        DebugAll["Debug/All.sh"]
        DebugBuild["Debug/Build.sh"]
        DebugRun["Debug/Run.sh"]
        DebugWind["Debug/Wind.sh"]
    end

    LibraryRS --> CLI
    CLI --> FnRS
    CLI --> ConfigLoader
    CLI --> ScriptRunner
    FnRS --> Process
    FnRS --> TomlEdit
    FnRS --> JsonEdit
    ScriptRunner --> RhaiEnvResolve
    ConfigLoader --> ScriptRunner
    DebugSh --> CLI
    DevMountain --> CLI
    ReleaseSh --> CLI

Key Modules

Data Flow

sequenceDiagram
    participant Developer as Developer / CI
    participant ShellScript as Shell Script
    participant CLI as Maintain CLI
    participant Rhai as Rhai Engine
    participant Process as Process Manager
    participant Config as Config Editor

    Developer->>ShellScript: ./Maintain/Release.sh
    ShellScript->>CLI: Maintain release --target aarch64-apple-darwin
    CLI->>Rhai: Load build configuration script
    Rhai->>CLI: Build group definition
    CLI->>Config: Read Cargo.toml / package.json
    Config->>CLI: Current version and dependencies
    loop For each element in build group
        CLI->>Process: spawn("cargo build --release -p Mountain")
        Process->>CLI: Exit code + output
    end
    CLI->>Config: Write updated Cargo.toml (if version bump)
    CLI->>Developer: Build summary with timing

Integration Points

Configuration

Shell scripts

The primary entry points are shell scripts in Element/Maintain/:

Why Maintain does not need rebuild

Maintain’s shell scripts are plain sh - they run directly on any POSIX system without compilation. The Rust Maintain binary is a build helper CLI that is compiled once and cached; it does not run inside the editor at runtime. Changes to the shell scripts take effect immediately on the next invocation. Changes to turbo.json take effect on the next pnpm command. Only changes to the Rust source under Source/Build/ require cargo build -p Maintain.

GritQL queries

Maintain ships a set of GritQL pattern files for automated refactoring. GritQL is a structural search-and-replace language for code that operates on ASTs rather than text. Land uses these queries for:

• Bulk renames of TypeScript identifiers across all packages
• Migration of import paths when element structure changes
• Enforcement of naming conventions (PascalCase filenames, single default export)
• Updating generated code when templates change

GritQL queries are stored under Element/Maintain/Query/ and can be run against any element in the workspace.

turbo.json task graph

The turbo.json at the workspace root defines:

• globalEnv - all PascalCase env vars (BundleLevel, HotReload, Watch, TierIPC, etc.) that Turborepo passes through to child tasks
• Task dependencies - which packages must build before others (e.g. Output must build before Sky)
• Parallel execution - tasks with no declared dependencies run concurrently across CPU cores
• Cache keys - inputs that, when changed, invalidate the Turborepo cache for a task

pnpm workspace management

Maintain works within the pnpm workspace defined at Land/package.json. All TypeScript packages use the workspace: protocol for cross-package dependencies. Maintain’s Source/Build/JsonEdit.rs handles non-lossy edits to package.json files when version bumps are required - it uses the json5 crate to preserve comments and formatting that JSON.parse / JSON.stringify would destroy.

Rust CLI

The Maintain Rust binary provides subcommands for cases where shell scripts are insufficient:

# Debug build of a specific element
Maintain debug --element Mountain

# Release build for a specific target triple
Maintain release --target aarch64-apple-darwin

# Override the Rhai build script
Maintain debug --script Custom/Build.rhai

# Verbose subprocess output
Maintain release --verbose

The CLI is built on clap and delegates to either the Rhai scripting engine or direct build functions depending on the subcommand.

Source files