@cleocode/cleo 2026.2.5 → 2026.2.7

package/packages/ct-skills/skills/railway-platform/_shared/scripts/railway-common.sh

@@ -0,0 +1,262 @@
+#!/usr/bin/env bash
+# Shared Railway CLI utilities
+# Source this file for common preflight checks and helper functions
+# Usage: source _shared/scripts/railway-common.sh
+
+set -euo pipefail
+
+# Minimum required CLI version
+readonly MIN_RAILWAY_VERSION="4.27.3"
+
+# Check if Railway CLI is installed
+check_railway_cli() {
+    if command -v railway &>/dev/null; then
+        local path
+        path=$(which railway)
+        echo '{"installed": true, "path": "'"$path"'"}'
+        return 0
+    else
+        echo '{"installed": false, "error": "cli_missing", "message": "Railway CLI not installed. Install with: npm install -g @railway/cli or brew install railway"}'
+        return 1
+    fi
+}
+
+# Check if user is authenticated
+check_railway_auth() {
+    local output
+    local exit_code
+    
+    output=$(railway whoami --json 2>&1) || exit_code=$?
+    
+    if [[ ${exit_code:-0} -eq 0 ]]; then
+        echo "$output"
+        return 0
+    else
+        echo '{"authenticated": false, "error": "not_authenticated", "message": "Not logged in to Railway. Run: railway login"}'
+        return 1
+    fi
+}
+
+# Get workspace info
+get_workspaces() {
+    local whoami
+    whoami=$(check_railway_auth) || return 1
+    echo "$whoami" | jq '.workspaces // []'
+}
+
+# Check if project is linked
+check_railway_linked() {
+    local output
+    local exit_code
+    
+    output=$(railway status --json 2>&1) || exit_code=$?
+    
+    if [[ ${exit_code:-0} -eq 0 ]] && [[ "$output" != *"No linked project"* ]] && [[ "$output" != *"error"* ]]; then
+        echo "$output"
+        return 0
+    else
+        echo '{"linked": false, "error": "not_linked", "message": "No Railway project linked. Run: railway link or railway init"}'
+        return 1
+    fi
+}
+
+# Check if parent directory is linked
+check_parent_linked() {
+    local current_dir
+    current_dir=$(pwd)
+    
+    cd .. || return 1
+    
+    local output
+    local exit_code
+    
+    output=$(railway status --json 2>&1) || exit_code=$?
+    
+    cd "$current_dir" || return 1
+    
+    if [[ ${exit_code:-0} -eq 0 ]] && [[ "$output" != *"No linked project"* ]]; then
+        echo '{"parent_linked": true, "context": '"$output"'}'
+        return 0
+    else
+        echo '{"parent_linked": false}'
+        return 1
+    fi
+}
+
+# Check CLI version
+check_railway_version() {
+    local required="${1:-$MIN_RAILWAY_VERSION}"
+    local version
+    
+    if ! command -v railway &>/dev/null; then
+        echo '{"ok": false, "error": "cli_missing", "message": "Railway CLI not installed"}'
+        return 1
+    fi
+    
+    version=$(railway --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+    
+    if [[ -z "$version" ]]; then
+        echo '{"ok": false, "error": "version_unknown", "message": "Could not determine Railway CLI version"}'
+        return 1
+    fi
+    
+    # Compare versions
+    local lowest
+    lowest=$(printf '%s\n%s' "$required" "$version" | sort -V | head -n1)
+    
+    if [[ "$lowest" == "$required" ]]; then
+        echo "{\"ok\": true, \"version\": \"$version\", \"required\": \"$required\"}"
+        return 0
+    else
+        echo "{\"ok\": false, \"version\": \"$version\", \"required\": \"$required\", \"error\": \"version_outdated\", \"message\": \"Railway CLI $version is below required $required. Run: railway upgrade\"}"
+        return 1
+    fi
+}
+
+# Full preflight check
+railway_preflight() {
+    local check_version="${1:-true}"
+    
+    # Check CLI installed
+    if ! command -v railway &>/dev/null; then
+        echo '{"ready": false, "error": "cli_missing", "step": "cli", "message": "Railway CLI not installed. Install with: npm install -g @railway/cli or brew install railway"}'
+        return 1
+    fi
+    
+    # Check version if requested
+    if [[ "$check_version" == "true" ]]; then
+        local version_check
+        version_check=$(check_railway_version) || {
+            echo "$version_check"
+            return 1
+        }
+    fi
+    
+    # Check authenticated
+    local auth_check
+    auth_check=$(railway whoami --json 2>&1) || {
+        echo '{"ready": false, "error": "not_authenticated", "step": "auth", "message": "Not logged in to Railway. Run: railway login"}'
+        return 1
+    }
+    
+    echo '{"ready": true, "cli": true, "authenticated": true}'
+    return 0
+}
+
+# List projects with essential fields only
+list_projects_essential() {
+    if ! railway_preflight >/dev/null; then
+        return 1
+    fi
+    
+    railway list --json 2>/dev/null | jq '[.[] | {
+        id: .id,
+        name: .name,
+        workspace: (.workspace // .workspaceId // "personal"),
+        services: [.services[].name // empty]
+    }]' 2>/dev/null || echo '[]'
+}
+
+# Get project context (safely)
+get_project_context() {
+    local context
+    context=$(check_railway_linked) || return 1
+    
+    # Extract essential fields
+    echo "$context" | jq '{
+        project: {
+            id: .project.id,
+            name: .project.name
+        },
+        environment: {
+            id: .environment.id,
+            name: .environment.name
+        },
+        service: {
+            id: .service.id,
+            name: .service.name
+        },
+        services: [.services[].node // .services[] | {id: .id, name: .name}]
+    }'
+}
+
+# Detect project type from files
+detect_project_type() {
+    local dir="${1:-.}"
+    
+    # Check for various project types
+    if [[ -f "$dir/package.json" ]]; then
+        if [[ -f "$dir/next.config.js" ]] || [[ -f "$dir/next.config.ts" ]] || [[ -f "$dir/next.config.mjs" ]]; then
+            echo '{"type": "nextjs", "language": "javascript", "framework": "next"}'
+        elif [[ -f "$dir/nuxt.config.ts" ]] || [[ -f "$dir/nuxt.config.js" ]]; then
+            echo '{"type": "nuxt", "language": "javascript", "framework": "nuxt"}'
+        elif grep -q '"express"' "$dir/package.json" 2>/dev/null; then
+            echo '{"type": "express", "language": "javascript", "framework": "express"}'
+        elif [[ -f "$dir/vite.config.ts" ]] || [[ -f "$dir/vite.config.js" ]]; then
+            echo '{"type": "vite", "language": "javascript", "framework": "vite"}'
+        else
+            echo '{"type": "nodejs", "language": "javascript", "framework": null}'
+        fi
+    elif [[ -f "$dir/requirements.txt" ]] || [[ -f "$dir/pyproject.toml" ]]; then
+        if [[ -f "$dir/main.py" ]] && grep -q 'fastapi\|FastAPI' "$dir/main.py" 2>/dev/null; then
+            echo '{"type": "fastapi", "language": "python", "framework": "fastapi"}'
+        elif [[ -f "$dir/manage.py" ]]; then
+            echo '{"type": "django", "language": "python", "framework": "django"}'
+        else
+            echo '{"type": "python", "language": "python", "framework": null}'
+        fi
+    elif [[ -f "$dir/go.mod" ]]; then
+        echo '{"type": "go", "language": "go", "framework": null}'
+    elif [[ -f "$dir/Cargo.toml" ]]; then
+        echo '{"type": "rust", "language": "rust", "framework": null}'
+    elif [[ -f "$dir/Dockerfile" ]]; then
+        echo '{"type": "docker", "language": null, "framework": "docker"}'
+    elif [[ -f "$dir/index.html" ]]; then
+        echo '{"type": "static", "language": "html", "framework": null}'
+    else
+        echo '{"type": "unknown", "language": null, "framework": null}'
+    fi
+}
+
+# Detect monorepo type
+detect_monorepo_type() {
+    local dir="${1:-.}"
+    
+    if [[ -f "$dir/pnpm-workspace.yaml" ]]; then
+        echo '{"type": "pnpm-workspace", "shared": true}'
+    elif [[ -f "$dir/turbo.json" ]]; then
+        echo '{"type": "turborepo", "shared": true}'
+    elif [[ -f "$dir/nx.json" ]]; then
+        echo '{"type": "nx", "shared": true}'
+    elif [[ -f "$dir/package.json" ]] && grep -q '"workspaces"' "$dir/package.json"; then
+        echo '{"type": "npm-workspace", "shared": true}'
+    elif [[ -d "$dir/packages" ]] || [[ -d "$dir/apps" ]]; then
+        # Check if apps share code
+        local has_shared=false
+        if [[ -d "$dir/packages/shared" ]] || [[ -d "$dir/libs" ]]; then
+            has_shared=true
+        fi
+        if [[ "$has_shared" == "true" ]]; then
+            echo '{"type": "monorepo", "shared": true}'
+        else
+            echo '{"type": "monorepo", "shared": false}'
+        fi
+    else
+        echo '{"type": "single", "shared": false}'
+    fi
+}
+
+# Helper: Print error message to stderr
+railway_error() {
+    echo "Error: $1" >&2
+}
+
+# Helper: Print warning message
+railway_warn() {
+    echo "Warning: $1"
+}
+
+# Helper: Print success message
+railway_success() {
+    echo "✓ $1"
+}

package/packages/ct-skills/skills/railway-platform/references/01-getting-started.md

@@ -0,0 +1,149 @@
+# Getting Started
+
+Install Railway CLI and authenticate for first-time setup.
+
+## Installation
+
+### macOS
+
+```bash
+brew install railway
+```
+
+### Linux / Windows (WSL)
+
+```bash
+npm install -g @railway/cli
+```
+
+### Verify Installation
+
+```bash
+railway --version
+# Should be 4.27.0 or higher
+```
+
+## Authentication
+
+### Interactive Login
+
+```bash
+railway login
+```
+
+Opens browser for authentication.
+
+### Browserless Login (SSH/CI)
+
+```bash
+railway login --browserless
+```
+
+Follow the URL provided and paste the code.
+
+### Token-Based Authentication
+
+For CI/CD pipelines:
+
+```bash
+# Project-level token
+RAILWAY_TOKEN=xxx railway up
+
+# Account-level token  
+RAILWAY_API_TOKEN=xxx railway list
+```
+
+Get tokens from Railway dashboard:
+1. Project Settings → Tokens
+2. Account Settings → API Tokens
+
+## Project Linking
+
+### Create New Project
+
+```bash
+railway init -n my-project
+```
+
+Options:
+- `-n, --name` - Project name
+- `-w, --workspace` - Workspace (if multiple)
+
+### Link to Existing Project
+
+```bash
+railway link -p project-name
+```
+
+Options:
+- `-p, --project` - Project name or ID
+- `-e, --environment` - Environment (default: production)
+- `-s, --service` - Service to link
+
+### Check Current Status
+
+```bash
+railway status --json
+```
+
+Returns:
+```json
+{
+  "project": {
+    "id": "...",
+    "name": "my-project"
+  },
+  "environment": {
+    "id": "...",
+    "name": "production"
+  },
+  "service": {
+    "id": "...",
+    "name": "web"
+  }
+}
+```
+
+## Quick Verification
+
+### Full Check
+
+```bash
+# Check CLI
+command -v railway
+
+# Check auth
+railway whoami
+
+# Check linked project
+railway status
+```
+
+### Troubleshooting
+
+**"command not found"**
+```bash
+# Reinstall
+npm install -g @railway/cli
+```
+
+**"not authenticated"**
+```bash
+railway login
+```
+
+**"no linked project"**
+```bash
+# Link existing
+railway link -p project-name
+
+# Or create new
+railway init -n new-project
+```
+
+## Next Steps
+
+Once installed and authenticated:
+- [02-projects.md](02-projects.md) - Manage projects
+- [03-services.md](03-services.md) - Create services
+- [04-deployments.md](04-deployments.md) - Deploy code

package/packages/ct-skills/skills/railway-platform/references/02-projects.md

@@ -0,0 +1,116 @@
+# Project Management
+
+Manage Railway projects, workspaces, and settings.
+
+## List Projects
+
+```bash
+railway list --json
+```
+
+Returns all projects across workspaces with essential fields.
+
+## Switch Projects
+
+### Link to Different Project
+
+```bash
+railway link -p project-name
+```
+
+### Unlink Current Directory
+
+```bash
+railway unlink
+```
+
+## Project Settings
+
+### Update via API
+
+```bash
+source _shared/scripts/railway-api.sh
+
+PROJECT_ID=$(get_project_id)
+
+railway_api '
+  mutation updateProject($id: String!, $input: ProjectUpdateInput!) {
+    projectUpdate(id: $id, input: $input) {
+      name
+      prDeploys
+      isPublic
+    }
+  }
+' "{\"id\": \"$PROJECT_ID\", \"input\": {\"prDeploys\": true}}"
+```
+
+### Available Settings
+
+| Setting | Type | Description |
+|---------|------|-------------|
+| `name` | String | Project name |
+| `description` | String | Project description |
+| `isPublic` | Boolean | Public visibility |
+| `prDeploys` | Boolean | Deploy PRs to preview environments |
+| `botPrEnvironments` | Boolean | Deploy Dependabot/Renovate PRs |
+
+## Workspaces
+
+### List Workspaces
+
+```bash
+railway whoami --json | jq '.workspaces'
+```
+
+### Create Project in Specific Workspace
+
+```bash
+railway init -n my-project --workspace workspace-id
+```
+
+## Environments
+
+### Create Environment
+
+```bash
+railway environment new staging
+```
+
+### Duplicate Environment
+
+```bash
+railway environment new staging --duplicate production
+```
+
+### Switch Environment
+
+```bash
+railway environment staging
+```
+
+## PR Deploys
+
+Enable automatic deployment of pull requests:
+
+```bash
+# Via API (see above)
+# Set prDeploys: true
+```
+
+Each PR creates a preview environment with:
+- Isolated database (if using templates)
+- Unique URL
+- Shared variables inherited
+
+## Project Deletion
+
+```bash
+railway delete
+```
+
+⚠️ Permanent - cannot be undone.
+
+## Next Steps
+
+- [03-services.md](03-services.md) - Create services
+- [06-environments.md](06-environments.md) - Environment configuration

package/packages/ct-skills/skills/railway-platform/references/03-services.md

@@ -0,0 +1,147 @@
+# Service Operations
+
+Create, configure, and manage Railway services.
+
+## Create Service
+
+### Empty Service
+
+```bash
+railway add --service my-service
+```
+
+### From GitHub Repo
+
+```bash
+# Create empty service first
+railway add --service my-api
+
+# Then configure source (see 06-environments.md)
+```
+
+### From Docker Image
+
+```bash
+source _shared/scripts/railway-api.sh
+
+PROJECT_ID=$(get_project_id)
+ENV_ID=$(get_environment_id)
+
+railway_api '
+  mutation serviceCreate($input: ServiceCreateInput!) {
+    serviceCreate(input: $input) {
+      id
+      name
+    }
+  }
+' "{\"input\": {\"projectId\": \"$PROJECT_ID\", \"name\": \"nginx\", \"source\": {\"image\": \"nginx:latest\"}}}"
+```
+
+## Service Status
+
+```bash
+railway service status --json
+```
+
+Shows:
+- Service name and ID
+- Current deployment status
+- Latest deployment info
+
+## Update Service
+
+### Rename Service
+
+```bash
+source _shared/scripts/railway-api.sh
+
+SERVICE_ID=$(get_service_id)
+
+railway_api '
+  mutation updateService($id: String!, $input: ServiceUpdateInput!) {
+    serviceUpdate(id: $id, input: $input) {
+      id
+      name
+    }
+  }
+' "{\"id\": \"$SERVICE_ID\", \"input\": {\"name\": \"new-name\"}}"
+```
+
+### Change Icon
+
+```bash
+railway_api '
+  mutation updateService($id: String!, $input: ServiceUpdateInput!) {
+    serviceUpdate(id: $id, input: $input) {
+      id
+      icon
+    }
+  }
+' "{\"id\": \"$SERVICE_ID\", \"input\": {\"icon\": \"https://devicons.railway.app/nodejs\"}}"
+```
+
+Icon sources:
+- Devicons: `https://devicons.railway.app/{name}`
+- Custom URL: Any image URL
+- Emoji: Direct emoji string
+
+## Link Service
+
+Switch linked service for current directory:
+
+```bash
+railway service link
+# Interactive selection
+
+# Or specify directly
+railway service link my-service
+```
+
+## Delete Service
+
+```bash
+source _shared/scripts/railway-api.sh
+
+ENV_ID=$(get_environment_id)
+SERVICE_ID=$(get_service_id)
+
+# Stage deletion
+railway_api '
+  mutation stageChanges($environmentId: String!, $input: EnvironmentConfig!) {
+    environmentStageChanges(environmentId: $environmentId, input: $input, merge: true) {
+      id
+    }
+  }
+' "{\"environmentId\": \"$ENV_ID\", \"input\": {\"services\": {\"$SERVICE_ID\": {\"isDeleted\": true}}}}"
+
+# Apply changes (see 06-environments.md)
+```
+
+## Service Types
+
+### Web Service
+
+Default service type:
+- Exposes HTTP port
+- Public domain assigned
+- Health checks enabled
+
+### Worker
+
+Background service:
+- No public domain
+- Runs continuously
+- Good for queue processors
+
+### Cron Job
+
+Scheduled execution:
+- Runs on schedule
+- Exits after completion
+- See [10-cron.md](10-cron.md)
+
+## Next Steps
+
+- [04-deployments.md](04-deployments.md) - Deploy services
+- [06-environments.md](06-environments.md) - Configure services
+- [05-databases.md](05-databases.md) - Database services