Developer Setup

This guide is for Blue-Lila employees that need to work on the Gen-X project — the code generator that powers Gen-Code. By the end of this page you will have all four repositories cloned and configured, your shell aliases in place, and the correct keyboard shortcut registered so you can accept TDD changes with a single key press.

Prerequisites

Before cloning anything, make sure the following tools are installed at the specified versions.

Clone the Repositories

Gen-X depends on three companion repositories in addition to the generator itself. Clone all four into the same parent directory (conventionally ~/go/src/).

# App generator — the core project you will be working in
git clone git@gitlab.com:blue-lila/gen-x.git

# App Tower Control (ATC) — the GUI for managing generated apps
git clone git@gitlab.com:blue-lila/atc.git

# Devt — development tooling and Git sync GUI
git clone git@gitlab.com:blue-lila/devt.git

# KitCla — stateless UI component library used by generated apps
git clone git@gitlab.com:blue-lila/kitcla.git

Configure Dependencies

Once the repositories are cloned, you need to point gen-x’s local module replacement at your actual kitcla checkout before installing dependencies.

📝 Note: In gen-x/go.mod, locate the replace directive and update it to match your username:

replace gitlab.com/blue-lila/kitcla => /home/USERNAME/go/src/kitcla

Replace USERNAME with your Linux username. If this line is left pointing at the wrong path, go mod tidy will fail with a module not found error.

After updating go.mod, install Go dependencies from each project directory:

# Navigate to the project directory (repeat for each cloned repo as needed)
cd ~/go/src/gen-x

# Download and tidy the module graph
go mod tidy
go mod vendor

Finalize Setup

With dependencies in place, copy the environment configuration file and make all shell scripts executable.

# Copy the environment file template for local use
cp config/env.dot.dist config/env.dot

# Make all shell scripts executable
find . -type f -name "*.sh" -exec chmod +x {} +

Then install the atc and devt companion apps using their install scripts:

# Navigate to each companion project and run its installer
cd ~/go/src/atc
./bin/install/install-linux.sh

cd ~/go/src/devt
./bin/install/install-linux.sh

📝 Note: Each install script has a matching uninstall-linux.sh if you need to remove an installation cleanly.

Once installed, the following local ports are in use:

Shell Aliases

💡 Tip: Adding these aliases to your .bashrc or .zshrc will save you from typing long commands dozens of times a day. The bird alias in particular chains the full build-init-run sequence into a single word.

Add the following block to your shell configuration file:

# Navigate to the go/src workspace
alias cdgo='cd ~/go/src'

# Navigate directly to gen-x
alias cdgen='cd ~/go/src/gen-x'

# Run the TDD script
alias tdd='./bin/tdd.sh'

# Start the app in the development environment (port 8086)
alias bird='cd . && ./bin/build/app_dev.sh && ./bin/init/app_dev.sh && ./bin/run/app_web_dev.sh'

# Start the app in the production environment
alias birp='cd . && ./bin/build/app_prod.sh && ./bin/init/app_prod.sh && ./bin/run/app_web_prod.sh'

# Tailwind CSS shorthand used by build scripts
alias tailwindcss='npx tailwindcss'

After saving, reload your shell with source ~/.zshrc (or source ~/.bashrc).

Custom Keyboard Shortcut

The Accept shortcut triggers the TDD acceptance endpoint at localhost:9289. When tdd pauses and prompts you to accept a set of generated changes, pressing this shortcut submits the acceptance without switching focus to a terminal window.

Register it through your desktop environment:

Settings → Keyboard → View and Customize Shortcuts → Custom Shortcuts → +

Name:     Accept
Command:  curl http://localhost:9289
Shortcut: Super + X  (Super = Windows key)

Next Steps

With your environment ready, the natural next step is to create your first app.

• Creating a New Application — register the app in ATC, write a Depicter script, and run the generator for the first time
• Daily Workflow — the three-tab routine that keeps Gen-X, the Depicter, and your target app in sync each working session