@arthai/agents 1.0.0

package/skills/railway/metrics/references/railpack.md

@@ -0,0 +1,257 @@
+# Railpack Reference
+
+Railpack is Railway's default builder. Zero-config for most projects.
+
+Full docs: https://railpack.com/llms.txt
+
+## Detection
+
+Railpack analyzes source code to detect language, framework, and build requirements automatically.
+
+Supported: Node, Python, Go, PHP, Java, Ruby, Rust, Elixir, Gleam, Deno, C/C++, static files.
+
+## Static Sites
+
+### Detection Patterns
+
+Railpack serves static files via Caddy when it detects:
+1. `Staticfile` in root (can specify `root: dist`)
+2. `index.html` in root
+3. `public/` directory
+4. `RAILPACK_STATIC_FILE_ROOT` env var set
+
+### Root Directory Priority
+
+1. `RAILPACK_STATIC_FILE_ROOT` env var
+2. `root` in `Staticfile`
+3. `public/` directory
+4. Current directory (if index.html exists)
+
+### Common Patterns
+
+Railpack auto-detects common static build outputs. Only set `RAILPACK_STATIC_FILE_ROOT` for non-standard output directories.
+
+| Framework | Build Output | Config Needed |
+|-----------|--------------|---------------|
+| Plain HTML | root | None (auto-detected) |
+| Vite | dist | None (auto-detected) |
+| Astro (static) | dist | None (auto-detected) |
+| Create React App | build | None (auto-detected) |
+| Angular | dist/<project> | `RAILPACK_STATIC_FILE_ROOT=dist/<project>` (non-standard path) |
+| Custom output | varies | Set if output dir is non-standard |
+
+### Custom Caddyfile
+
+Put a `Caddyfile` in project root to override default serving behavior.
+
+## Node.js
+
+### Detection
+- `package.json` in root
+
+### Version Priority
+1. `RAILPACK_NODE_VERSION` env var
+2. `engines.node` in package.json
+3. `.nvmrc` or `.node-version`
+4. Default: Node 22
+
+### Package Manager Detection
+1. `packageManager` field in package.json (enables Corepack)
+2. Lock file: `pnpm-lock.yaml`, `bun.lockb`, `yarn.lock`
+3. Default: npm
+
+### Build Command
+Auto-detected from package.json `scripts.build`. Override via `buildCommand` in service settings.
+
+### Start Command
+Auto-detected:
+1. `scripts.start` in package.json
+2. `main` field in package.json
+3. `index.js` or `index.ts` in root
+
+Override via `startCommand` in service settings.
+
+### Framework Detection
+
+| Framework | Detection | Notes |
+|-----------|-----------|-------|
+| Next.js | `next` in dependencies | Caches `.next/cache` |
+| Vite | `vite` in devDependencies | Static or SSR mode |
+| Astro | `astro` in dependencies | Caches `.astro` |
+| Nuxt | `nuxt` in dependencies | Auto start command |
+| Remix | `@remix-run/*` in deps | - |
+
+### Static Site Mode (SPA)
+
+For frameworks like Vite, CRA, Astro (static), Angular:
+- Railpack builds then serves via Caddy
+- Set `RAILPACK_SPA_OUTPUT_DIR` if output isn't `dist`
+
+## Python
+
+### Detection
+- `requirements.txt`, `pyproject.toml`, `Pipfile`, or `uv.lock`
+
+### Version Priority
+1. `RAILPACK_PYTHON_VERSION` env var
+2. `.python-version` file
+3. `requires-python` in pyproject.toml
+4. Default: Python 3.12
+
+### WSGI/ASGI Auto-Config
+
+| Framework | Start Command |
+|-----------|---------------|
+| Django | `gunicorn <project>.wsgi` |
+| FastAPI | `uvicorn main:app --host 0.0.0.0` |
+| Flask | `gunicorn app:app` |
+
+Override via `startCommand` in service settings.
+
+## Go
+
+### Detection
+- `go.mod` in root
+
+### Build
+Compiles to binary automatically. For `cmd/` structure, set binary name or use `RAILPACK_GO_BIN`.
+
+## Rust
+
+### Detection
+- `Cargo.toml` in root
+
+### Build
+Release build by default. Binary auto-detected from Cargo.toml.
+
+## Configuration
+
+### Preferred: Service Settings
+
+Use `environment` skill to set:
+- `buildCommand` - Custom build command
+- `startCommand` - Custom start command
+
+These are stored in Railway and don't pollute your codebase.
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `RAILPACK_STATIC_FILE_ROOT` | Static file serving directory |
+| `RAILPACK_SPA_OUTPUT_DIR` | SPA build output (defaults to `dist`) |
+| `RAILPACK_NODE_VERSION` | Node.js version |
+| `RAILPACK_PYTHON_VERSION` | Python version |
+| `RAILPACK_GO_BIN` | Go binary name |
+| `RAILPACK_PACKAGES` | Additional Mise packages (`pkg@version`) |
+| `RAILPACK_BUILD_APT_PACKAGES` | System packages for build |
+| `RAILPACK_DEPLOY_APT_PACKAGES` | System packages for runtime |
+
+### railpack.json
+
+Advanced config for custom build steps:
+
+```json
+{
+  "$schema": "https://schema.railpack.com",
+  "packages": {
+    "ffmpeg": "latest"
+  },
+  "deploy": {
+    "aptPackages": ["libmagic1"]
+  }
+}
+```
+
+### railway.toml
+
+Alternative config format:
+
+```toml
+[build]
+builder = "RAILPACK"
+buildCommand = "npm run build"
+
+[deploy]
+startCommand = "npm start"
+```
+
+## Minimal Project Scaffolding
+
+When no code exists, suggest these patterns:
+
+### Static HTML
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>My Site</title>
+</head>
+<body>
+  <h1>Hello Railway</h1>
+</body>
+</html>
+```
+
+### Vite React
+```bash
+npm create vite@latest . -- --template react
+```
+
+### Astro
+```bash
+npm create astro@latest
+```
+
+### Python FastAPI
+```python
+# main.py
+from fastapi import FastAPI
+app = FastAPI()
+
+@app.get("/")
+def root():
+    return {"message": "Hello Railway"}
+```
+
+```txt
+# requirements.txt
+fastapi
+uvicorn
+```
+
+### Go HTTP Server
+```go
+// main.go
+package main
+
+import (
+    "fmt"
+    "net/http"
+    "os"
+)
+
+func main() {
+    port := os.Getenv("PORT")
+    if port == "" {
+        port = "8080"
+    }
+    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+        fmt.Fprintf(w, "Hello Railway")
+    })
+    http.ListenAndServe(":"+port, nil)
+}
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Static site 404s | Check output dir - set `RAILPACK_STATIC_FILE_ROOT` if non-standard |
+| Wrong build command | Use `environment` skill to set `buildCommand` |
+| Wrong start command | Use `environment` skill to set `startCommand` |
+| Missing system package | Add to `RAILPACK_BUILD_APT_PACKAGES` or `RAILPACK_DEPLOY_APT_PACKAGES` |
+| Wrong Node version | Set `RAILPACK_NODE_VERSION` or add `.nvmrc` |
+| Wrong Python version | Set `RAILPACK_PYTHON_VERSION` or add `.python-version` |

package/skills/railway/metrics/references/variables.md

@@ -0,0 +1,170 @@
+# Variables Reference
+
+Variables in Railway support references to other services, shared variables, and Railway-provided values.
+
+## Template Syntax
+
+```
+${{NAMESPACE.VAR}}
+```
+
+| Namespace | Description |
+|-----------|-------------|
+| `shared` | Shared variables (project-wide) |
+| `<serviceName>` | Variables from another service (case-sensitive) |
+
+## Examples
+
+**Reference shared variable:**
+```json
+{ "value": "${{shared.DOMAIN}}" }
+```
+
+**Reference another service's variable:**
+```json
+{ "value": "${{api.API_KEY}}" }
+```
+
+**Combine with text:**
+```json
+{ "value": "https://${{shared.DOMAIN}}/api" }
+```
+
+## Railway-Provided Variables
+
+Railway injects these into every service automatically.
+
+### Networking
+| Variable | Description | Example | Availability |
+|----------|-------------|---------|--------------|
+| `RAILWAY_PUBLIC_DOMAIN` | Public domain | `myapp.up.railway.app` | Only if service has a domain |
+| `RAILWAY_PRIVATE_DOMAIN` | Private DNS (internal only) | `myapp.railway.internal` | Always |
+| `RAILWAY_TCP_PROXY_DOMAIN` | TCP proxy domain | `roundhouse.proxy.rlwy.net` | Only if TCP proxy enabled |
+| `RAILWAY_TCP_PROXY_PORT` | TCP proxy port | `11105` | Only if TCP proxy enabled |
+
+**Note:** `RAILWAY_PUBLIC_DOMAIN` is only available if the service has a domain configured.
+Check the service's environment config to verify a domain exists before referencing it.
+
+### Context
+| Variable | Description |
+|----------|-------------|
+| `RAILWAY_PROJECT_ID` | Project ID |
+| `RAILWAY_PROJECT_NAME` | Project name |
+| `RAILWAY_ENVIRONMENT_ID` | Environment ID |
+| `RAILWAY_ENVIRONMENT_NAME` | Environment name |
+| `RAILWAY_SERVICE_ID` | Service ID |
+| `RAILWAY_SERVICE_NAME` | Service name |
+| `RAILWAY_DEPLOYMENT_ID` | Deployment ID |
+| `RAILWAY_REPLICA_ID` | Replica ID |
+| `RAILWAY_REPLICA_REGION` | Region (e.g., `us-west2`) |
+
+### Volume (if attached)
+| Variable | Description |
+|----------|-------------|
+| `RAILWAY_VOLUME_NAME` | Volume name |
+| `RAILWAY_VOLUME_MOUNT_PATH` | Mount path |
+
+### Git (if deployed from GitHub)
+| Variable | Description |
+|----------|-------------|
+| `RAILWAY_GIT_COMMIT_SHA` | Commit SHA |
+| `RAILWAY_GIT_BRANCH` | Branch name |
+| `RAILWAY_GIT_REPO_NAME` | Repository name |
+| `RAILWAY_GIT_REPO_OWNER` | Repository owner |
+| `RAILWAY_GIT_AUTHOR` | Commit author |
+| `RAILWAY_GIT_COMMIT_MESSAGE` | Commit message |
+
+## Wiring Services Together
+
+### Frontend → Backend (public network)
+Use when: Browser makes requests to API (browser can't access private network)
+
+```json
+{
+  "services": {
+    "<frontendId>": {
+      "variables": {
+        "API_URL": { "value": "https://${{backend.RAILWAY_PUBLIC_DOMAIN}}" }
+      }
+    }
+  }
+}
+```
+
+### Service → Database (private network)
+Use when: Backend connects to database (faster, no egress cost, more secure)
+
+Railway databases auto-generate connection URL variables. Use the private versions:
+
+| Database | Variable Reference |
+|----------|-------------------|
+| Postgres | `${{Postgres.DATABASE_URL}}` |
+| MySQL | `${{MySQL.DATABASE_URL}}` |
+| Redis | `${{Redis.REDIS_URL}}` |
+| Mongo | `${{Mongo.MONGO_URL}}` |
+
+**Postgres/MySQL example:**
+```json
+{
+  "services": {
+    "<apiId>": {
+      "variables": {
+        "DATABASE_URL": { "value": "${{Postgres.DATABASE_URL}}" }
+      }
+    }
+  }
+}
+```
+
+**Redis example:**
+```json
+{
+  "services": {
+    "<apiId>": {
+      "variables": {
+        "REDIS_URL": { "value": "${{Redis.REDIS_URL}}" }
+      }
+    }
+  }
+}
+```
+
+**Mongo example:**
+```json
+{
+  "services": {
+    "<apiId>": {
+      "variables": {
+        "MONGO_URL": { "value": "${{Mongo.MONGO_URL}}" }
+      }
+    }
+  }
+}
+```
+
+**Note:** Service names are case-sensitive. Match the exact name from your project (e.g., "Postgres", "Redis").
+
+### Service → Service (private network)
+Use when: Microservices communicate internally
+
+```json
+{
+  "services": {
+    "<workerServiceId>": {
+      "variables": {
+        "API_INTERNAL_URL": { "value": "http://${{api.RAILWAY_PRIVATE_DOMAIN}}:${{api.PORT}}" }
+      }
+    }
+  }
+}
+```
+
+## When to Use Public vs Private
+
+| Use Case | Domain | Reason |
+|----------|--------|--------|
+| Browser → API | Public | Browser can't access private network |
+| Service → Service | Private | Faster, no egress, more secure |
+| Service → Database | Private | Databases should never be public |
+| External webhook → Service | Public | External services need public access |
+| Cron job → API | Private | Internal communication |

package/skills/railway/metrics/scripts/railway-api.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Railway GraphQL API helper
+# Usage: railway-api.sh '<graphql-query>' ['<variables-json>']
+
+set -e
+
+if ! command -v jq &>/dev/null; then
+  echo '{"error": "jq not installed. Install with: brew install jq"}'
+  exit 1
+fi
+
+CONFIG_FILE="$HOME/.railway/config.json"
+
+if [[ ! -f "$CONFIG_FILE" ]]; then
+  echo '{"error": "Railway config not found. Run: railway login"}'
+  exit 1
+fi
+
+TOKEN=$(jq -r '.user.token' "$CONFIG_FILE")
+
+if [[ -z "$TOKEN" || "$TOKEN" == "null" ]]; then
+  echo '{"error": "No Railway token found. Run: railway login"}'
+  exit 1
+fi
+
+if [[ -z "$1" ]]; then
+  echo '{"error": "No query provided"}'
+  exit 1
+fi
+
+# Build payload with query and optional variables
+if [[ -n "$2" ]]; then
+  PAYLOAD=$(jq -n --arg q "$1" --argjson v "$2" '{query: $q, variables: $v}')
+else
+  PAYLOAD=$(jq -n --arg q "$1" '{query: $q}')
+fi
+
+curl -s https://backboard.railway.com/graphql/v2 \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "$PAYLOAD"