aiskillstore/marketplace / skills/0xbigboss/gen-env
gen-env
VerifiedCreates, updates, or reviews a project's gen-env command for running multiple isolated instances on localhost. Handles instance identity, port allocation, data isolation, browser state separation, and cleanup.
| File | Kind | Size |
|---|---|---|
| ADVANCED_PATTERNS.md | markdown | 11.6 KB |
| IMPLEMENTATION.md | markdown | 22.1 KB |
| SKILL.md | skill md | 7.8 KB |
| skill-report.json | config | 198.8 KB |
ADVANCED_PATTERNS.md
View on GitHub# Advanced gen-env Patterns
Complex scenarios: monorepos, CI pipelines, Tilt/Docker integration, and multi-service stacks.
## Monorepo with Shared Toolkit
When gen-env logic is shared across apps:
```
monorepo/
├── packages/
│ └── localnet-toolkit/
│ └── src/
│ ├── gen-env/
│ │ ├── ports.ts # Port allocation
│ │ ├── identity.ts # Instance naming
│ │ └── index.ts # Main export
│ └── index.ts
├── apps/
│ ├── app-a/
│ │ └── scripts/
│ │ └── gen-env.ts # Imports from toolkit
│ └── app-b/
│ └── scripts/
│ └── gen-env.ts
└── .localnet.env # Shared across apps
```
App-specific gen-env imports shared logic:
```typescript
// apps/app-a/scripts/gen-env.ts
import { allocatePorts, createInstance, generateEnv } from "@org/localnet-toolkit";
const APP_PORTS = [
"POSTGRES_PORT",
"API_PORT",
"WEB_PORT",
// App-specific ports
"FEATURE_SERVICE_PORT",
] as const;
// Extend base implementation
const instance = await createInstance(name, {
ports: APP_PORTS,
urlGenerators: {
FEATURE_API: (host, ports) => `http://${host}:${ports.FEATURE_SERVICE_PORT}/api`,
},
});
```
## Multi-Service Stack (Canton/Blockchain)
For complex stacks with many services:
```typescript
// Organized by service group
const PORT_GROUPS = {
database: ["POSTGRES_PORT"],
auth: ["KEYCLOAK_PORT", "KEYCLOAK_MGMT_PORT"],
proxy: ["ENVOY_ADMIN_API_PORT", "ENVOY_LEDGER_API_PORT", "ENVOY_ADMIN_PORT"],
canton_sv: ["SV_LEDGER_API", "SV_ADMIN_API", "SV_VALIDATOR_API", "SV_JSON_API"],
canton_provider: ["PROVIDER_LEDGER_API", "PROVIDER_ADMIN_API", "PROVIDER_VALIDATOR_API"],
canton_user: ["USER_LEDGER_API", "USER_ADMIN_API", "USER_VALIDATOR_API"],
ui: ["SV_UI_PORT", "APP_PROVIDER_UI_PORT", "APP_USER_UI_PORT"],
app: ["NEXTJS_PORT", "API_GATEWAY_PORT", "STORYBOOK_PORT"],
dev: ["TILT_PORT", "CHROME_CDP_PORT"],
};
const PORT_KEYS = Object.values(PORT_GROUPS).flat();
```
## Base Environment Resolution
When project has base env files with shell variable syntax:
```typescript
/**
* Resolve ${VAR} and ${VAR:-default} in env files
* CRITICAL: Don't copy shell syntax literally into generated env
*/
function resolveEnvFile(
path: string,
context: Record<string, string>
): Record<string, string> {
const result: Record<string, string> = {};
const content = readFileSync(path, "utf-8");
for (const line of content.split("\n")) {
const trimmed = line.trim();
if (!trimmed || trimmed.startsWith("#")) continue;
const match = trimmed.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
if (!match) continue;
const [, key, rawValue] = match;
const resolved = resolveValue(rawValue, { ...context, ...result });
result[key] = resolved;
}
return result;
}
function resolveValue(value: string, context: Record<string, string>): string {
// Handle ${VAR:-default} and ${VAR}
return value.replace(
/\$\{(\w+)(?::-([^}]*))?\}/g,
(_, name, fallback) => {
if (context[name] !== undefined) return context[name];
if (fallback !== undefined) return resolveValue(fallback, context);
return "";
}
);
}
// Usage: merge base files with generated ports
const BASE_FILES = ["env/compose.env", "env/common.env", "env/local.env"];
function generateWithBaseFiles(instance: InstanceConfig): string {
// Start with instance identity and ports
const context: Record<string, string> = {
...Object.fromEntries(
Object.entries(instance.ports).map(([k, v]) => [k, String(v)])
),
};
const sections: string[] = [
`# Generated by gen-env for ${instance.name}`,
"",
"# === Instance Identity ===",
// ... identity vars
];
// Resolve and merge base files
for (const file of BASE_FILES) {
if (!existsSync(file)) continue;
const resolved = resolveEnvFile(file, context);
Object.assign(context, resolved);
sections.push(``, `# --- ${basename(file)} (resolved) ---`);
for (const [key, value] of Object.entries(resolved)) {
sections.push(`${key}=${value}`);
}
}
return sections.join("\n") + "\n";
}
```
## CI/CD Integration
### GitHub Actions
```yaml
- name: Generate localnet env
run: |
# Use run number for unique naming in CI
bun bin/gen-env.ts ci-${{ github.run_number }} --random
- name: Start services
run: |
source .localnet.env
docker compose up -d
- name: Run tests
run: |
source .localnet.env
yarn test:e2e
- name: Cleanup
if: always()
run: |
source .localnet.env
docker compose -p $COMPOSE_PROJECT_NAME down -v
```
### CI-Specific Adjustments
```typescript
const CI = process.env.CI === "true";
// Shorter timeouts in CI
const PORT_CHECK_TIMEOUT_MS = CI ? 50 : 100;
// CI naming includes run ID for parallel jobs
function getCIName(): string {
const runId = process.env.GITHUB_RUN_NUMBER || process.env.CI_JOB_ID || Date.now();
return `ci-${runId}`;
}
// Force random ports in CI (no lockfile reuse)
if (CI) {
options.random = true;
options.force = true;
}
```
## Tilt Integration
### Tiltfile Config Reader
```python
# tilt/localnet_config.star
def _load_env(path):
"""Parse KEY=VALUE env file into dict."""
env = {}
if not os.path.exists(path):
return env
content = str(read_file(path))
for line in content.split("\n"):
line = line.strip()
if not line or line.startswith("#") or "=" not in line:
continue
key, value = line.split("=", 1)
env[key] = value
return env
def get_localnet_config():
"""
Load localnet configuration from .localnet.env.
Falls back to static defaults for fresh clones without gen-env.
"""
env_path = ".localnet.env"
fallback_path = "apps/localnet/all.env"
if os.path.exists(env_path):
env = _load_env(env_path)
elif os.path.exists(fallback_path):
print("Warning: .localnet.env not found, using fallback")
print("Run: gen-env --name <your-workspace>")
env = _load_env(fallback_path)
else:
fail("No env file found. Run: gen-env --name <workspace>")
def get_str(key, default):
return env.get(key, default)
def get_int(key, default):
val = env.get(key)
if val == None or val == "":
return default
return int(val)
return {
# Identity
"compose_name": get_str("COMPOSE_NAME", "localnet"),
"compose_project_name": get_str("COMPOSE_PROJECT_NAME", "localnet"),
"docker_network": get_str("DOCKER_NETWORK", "localnet"),
"container_prefix": get_str("CONTAINER_PREFIX", ""),
"host": get_str("APP_HOST", "localhost"),
# Ports
"postgres_port": get_int("POSTGRES_PORT", 5432),
"api_port": get_int("API_PORT", 8080),
"web_port": get_int("WEB_PORT", 3000),
# ... more ports
}
# Export for use in Tiltfile (POSIX-compatible, works with dash/sh)
LOCALNET_ENV_SOURCE = """
if [ -f .localnet.env ]; then
set -a; . ./.localnet.env; set +a
fi
"""
```
### Tiltfile Usage
```python
load("./tilt/localnet_config.star", "get_localnet_config", "LOCALNET_ENV_SOURCE")
cfg = get_localnet_config()
# Use in local_resource
local_resource(
"api-gateway",
serve_cmd=LOCALNET_ENV_SOURCE + "yarn workspace api-gateway dev",
serve_env={
"PORT": str(cfg["api_port"]),
"HOST": cfg["host"],
},
links=[link("http://{}:{}".format(cfg["host"], cfg["api_port"]), "API")],
)
# Use in docker_compose
docker_compose(
"apps/localnet/compose.yaml",
env_file=".localnet.env",
project_name=cfg["compose_project_name"],
)
```
## Docker Compose Integration
### compose.yaml
```yaml
services:
postgres:
image: postgres:14
container_name: ${CONTAINER_PREFIX}postgres
ports:
- "${POSTGRES_PORT:-5432}:5432"
volumes:
- postgres_data:/var/lib/postgresql/data
networks:
- default
api:
build: ./apps/api
container_name: ${CONTAINER_PREFIX}api
ports:
- "${API_PORT:-8080}:8080"
environment:
DATABASE_URL: postgres://user:pass@postgres:5432/dev
HOST: ${APP_HOST:-localhost}
depends_on:
- postgres
networks:
- default
networks:
default:
name: ${DOCKER_NETWORK:-localnet}
volumes:
postgres_data:
name: ${VOLUME_PREFIX:-localnet}_postgres_data
```
### Running with gen-env
```bash
# Generate env
gen-env feature-x
# Start (uses COMPOSE_PROJECT_NAME from env)
source .localnet.env
docker compose up -d
# Or explicit
docker compose --env-file .localnet.env up -d
```
## Auto-Naming Strategies
### From Git Worktree
```typescript
function getWorktreeName(): string {
try {
const toplevel = execSync("git rev-parse --show-toplevel", {
encoding: "utf-8",
}).trim();
return basename(toplevel);
} catch {
return basename(process.cwd());
}
}
```
### From Branch Name
```typescript
function getBranchName(): string {
try {
const branch = execSync("git branch --show-current", {
encoding: "utf-8",
}).trim();
return branch.replace(/\//g, "-");
} catch {
return "default";
}
}
```
### Interactive Selection
```typescript
async function promptForName(): Promise<string> {
const suggestions = [
getWorktreeName(),
getBranchName(),
`dev-${process.env.USER}`,
].filter(Boolean);
console.log("Suggested names:");
suggestions.forEach((s, i) => console.log(` ${i + 1}. ${s}`));
// If running interactively, prompt
// Otherwise use first suggestion
return suggestions[0];
}
```
## Cleanup Utilities
### List All Instances
```bash
#!/usr/bin/env bash
# bin/gen-env-list
echo "=== Docker Containers ==="
docker ps -a --filter "name=localnet-" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
echo ""
echo "=== Docker Volumes ==="
docker volume ls --filter "name=localnet-" --format "table {{.Name}}\t{{.Driver}}"
echo ""
echo "=== Docker Networks ==="
docker network ls --filter "name=localnet-" --format "table {{.Name}}\t{{.Driver}}"
```
### Clean Specific Instance
```bash
#!/usr/bin/env bash
# bin/gen-env-clean-instance
INSTANCE=${1:?Usage: gen-env-clean-instance <instance-name>}
PROJECT="localnet-${INSTANCE}"
echo "Cleaning instance: $PROJECT"
docker compose -p "$PROJECT" down -v --remove-orphans 2>/dev/null || true
docker network rm "$PROJECT" 2>/dev/null || true
echo "Done"
```
### Clean All Instances (Dangerous)
```bash
#!/usr/bin/env bash
# bin/gen-env-clean-all
echo "WARNING: This will remove ALL localnet instances!"
read -p "Continue? [y/N] " -n 1 -r
echo
[[ $REPLY =~ ^[Yy]$ ]] || exit 1
echo "Stopping containers..."
containers=$(docker ps -a --filter "name=localnet-" -q)
[ -n "$containers" ] && docker rm -f $containers
echo "Removing volumes..."
volumes=$(docker volume ls --filter "name=localnet-" -q)
[ -n "$volumes" ] && docker volume rm $volumes
echo "Removing networks..."
networks=$(docker network ls --filter "name=localnet-" -q)
[ -n "$networks" ] && docker network rm $networks
echo "Done"
```
## Debugging Tips
### Verify Isolation
```bash
# Check container names include instance prefix
docker ps --format "{{.Names}}" | grep localnet
# Check volumes are instance-specific
docker volume ls | grep localnet
# Check networks are separate
docker network ls | grep localnet
# Verify browser sees correct host
curl -v http://feature-x.localhost:3000 2>&1 | grep "Host:"
```
### Port Conflict Debugging
```bash
# What's using a port?
lsof -i :3000
# All ports in use by localnet containers
docker ps --format "{{.Ports}}" | grep -oE "[0-9]+->|:[0-9]+"
# Check if port is actually free
nc -z localhost 51234 && echo "IN USE" || echo "FREE"
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |