Skip to content

aiskillstore/marketplace / skills/0xbigboss/gen-env

gen-env

Verified

Creates, 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.

FileKindSize
ADVANCED_PATTERNS.mdmarkdown11.6 KB
IMPLEMENTATION.mdmarkdown22.1 KB
SKILL.mdskill md7.8 KB
skill-report.jsonconfig198.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"
```
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 implementationStars: 323kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 323kUpdated Claude CodeCodexVerifiedInstall