grimoire-framework 1.0.0

package/.grimoire/infrastructure/tools/cli/railway-cli.yaml

@@ -0,0 +1,260 @@
+tool:
+  schema_version: 1.0
+  id: railway-cli
+  type: cli
+  name: Railway CLI
+  version: 1.0.0
+  description: Official Railway command-line interface for deploying and managing cloud applications, databases, and services
+  knowledge_strategy: declarative
+
+  capabilities:
+    - Deploy applications from CLI
+    - Manage Railway projects and services
+    - Configure environment variables
+    - View logs and metrics
+    - Manage databases (PostgreSQL, MySQL, MongoDB, Redis)
+    - Link services together
+    - Run commands in Railway environment
+    - Handle deployments and rollbacks
+
+  use_cases:
+    - rapid_deployment: "Deploy applications with zero configuration"
+    - environment_management: "Manage environment variables across environments"
+    - log_monitoring: "Stream and view application logs"
+    - database_provisioning: "Create and manage databases"
+    - service_linking: "Connect services via private networking"
+    - ci_cd: "Integrate with CI/CD pipelines"
+
+  installation:
+    npm: "npm install -g @railway/cli"
+    brew: "brew install railway"
+    shell: "bash <(curl -fsSL cli.new)"
+
+  cli_specific:
+    executable: "railway"
+    configuration:
+      auth_file: "~/.railway/config.json"
+      project_file: ".railway/project.json"
+
+  command_groups:
+    initialization:
+      - command: "railway login"
+        description: "Authenticate with Railway"
+        method: "Opens browser for OAuth"
+
+      - command: "railway init"
+        description: "Initialize Railway project in current directory"
+        creates: ".railway directory with project.json"
+        options:
+          - "Create new project"
+          - "Link to existing project"
+
+      - command: "railway link"
+        description: "Link current directory to Railway project"
+        usage: "railway link [PROJECT_ID]"
+
+    deployment:
+      - command: "railway up"
+        description: "Deploy current directory"
+        common_flags:
+          - "--detach (deploy without attaching to logs)"
+          - "--service SERVICE_NAME (deploy specific service)"
+        notes:
+          - "Automatically detects framework"
+          - "Uses Nixpacks for building"
+          - "Supports Dockerfile if present"
+
+      - command: "railway deploy"
+        description: "Alias for railway up"
+
+      - command: "railway status"
+        description: "Show deployment status"
+        shows:
+          - "Active deployments"
+          - "Service status"
+          - "URLs"
+
+    environment:
+      - command: "railway variables"
+        description: "List environment variables"
+        common_flags:
+          - "--service SERVICE_NAME"
+          - "--environment ENVIRONMENT_NAME"
+
+      - command: "railway variables set"
+        description: "Set environment variable"
+        usage: "railway variables set KEY=VALUE"
+        common_flags:
+          - "--service SERVICE_NAME"
+
+      - command: "railway variables delete"
+        description: "Delete environment variable"
+        usage: "railway variables delete KEY"
+
+    services:
+      - command: "railway service"
+        description: "Manage services in project"
+        subcommands:
+          - "railway service create"
+          - "railway service list"
+          - "railway service delete"
+
+      - command: "railway add"
+        description: "Add a database or service"
+        options:
+          - "PostgreSQL"
+          - "MySQL"
+          - "MongoDB"
+          - "Redis"
+        notes:
+          - "Automatically provisions and configures"
+          - "Sets environment variables"
+
+    logs_and_monitoring:
+      - command: "railway logs"
+        description: "Stream application logs"
+        common_flags:
+          - "--service SERVICE_NAME"
+          - "--deployment DEPLOYMENT_ID"
+          - "--tail N (show last N lines)"
+
+      - command: "railway run"
+        description: "Run command with Railway environment"
+        usage: "railway run COMMAND"
+        examples:
+          - "railway run npm start"
+          - "railway run node migrate.js"
+        notes:
+          - "Injects environment variables from Railway"
+          - "Useful for running migrations"
+
+    project_management:
+      - command: "railway list"
+        description: "List all Railway projects"
+
+      - command: "railway open"
+        description: "Open project in Railway dashboard"
+
+      - command: "railway whoami"
+        description: "Show current authenticated user"
+
+      - command: "railway domain"
+        description: "Manage custom domains"
+        subcommands:
+          - "railway domain add DOMAIN"
+          - "railway domain list"
+          - "railway domain remove DOMAIN"
+
+    environments:
+      - command: "railway environment"
+        description: "Manage environments (production, staging, etc.)"
+        subcommands:
+          - "railway environment create NAME"
+          - "railway environment list"
+          - "railway environment delete NAME"
+
+  workflow_patterns:
+    new_project:
+      - step: 1
+        action: "railway login"
+        purpose: "Authenticate"
+      - step: 2
+        action: "railway init"
+        purpose: "Create/link project"
+      - step: 3
+        action: "railway add (select database if needed)"
+        purpose: "Provision resources"
+      - step: 4
+        action: "railway variables set KEY=VALUE"
+        purpose: "Configure environment"
+      - step: 5
+        action: "railway up"
+        purpose: "Deploy application"
+
+    continuous_deployment:
+      - step: 1
+        action: "railway login --browserless (in CI)"
+        purpose: "Authenticate in CI"
+      - step: 2
+        action: "railway up --detach"
+        purpose: "Deploy without logs"
+      - step: 3
+        action: "railway status"
+        purpose: "Verify deployment"
+
+    database_migration:
+      - step: 1
+        action: "railway run node migrations/run.js"
+        purpose: "Run migrations with Railway env"
+
+  best_practices:
+    - "Use railway run for migrations to access production environment"
+    - "Separate environments for staging and production"
+    - "Use service names to manage multiple services"
+    - "Store secrets in Railway variables, not in code"
+    - "Use --detach flag in CI/CD pipelines"
+    - "Monitor logs during deployment with railway logs"
+    - "Use private networking for service-to-service communication"
+
+  authentication:
+    browser_login:
+      command: "railway login"
+      method: "OAuth via browser"
+
+    ci_login:
+      command: "railway login --browserless"
+      requires: "RAILWAY_TOKEN environment variable"
+      obtain: "From Railway Dashboard > Account > Tokens"
+
+  private_networking:
+    description: "Services can communicate via private URLs"
+    format: "SERVICE_NAME.railway.internal"
+    port: "Default service port"
+    example: "postgres.railway.internal:5432"
+    benefits:
+      - "No public exposure required"
+      - "Lower latency"
+      - "Free internal traffic"
+
+  deployment_features:
+    auto_detection:
+      - "Detects framework automatically"
+      - "Generates optimal build configuration"
+      - "Supports: Node.js, Python, Go, Ruby, PHP, etc."
+
+    build_systems:
+      - "Nixpacks (default)"
+      - "Dockerfile (if present)"
+      - "Buildpacks (legacy)"
+
+    zero_config:
+      - "No railway.json required"
+      - "Smart defaults for popular frameworks"
+      - "Automatic port detection"
+
+  common_issues:
+    not_logged_in:
+      error: "Not authenticated"
+      solution: "Run 'railway login' to authenticate"
+
+    no_project_linked:
+      error: "No project linked"
+      solution: "Run 'railway init' or 'railway link PROJECT_ID'"
+
+    build_failures:
+      error: "Build failed"
+      troubleshooting:
+        - "Check logs with railway logs"
+        - "Verify dependencies in package.json"
+        - "Check Nixpacks compatibility"
+        - "Add custom Dockerfile if needed"
+
+    environment_issues:
+      error: "Missing environment variables"
+      solution: "Use 'railway variables set' or configure in dashboard"
+
+  limitations:
+    - "Requires Railway account"
+    - "Billing based on resource usage"
+    - "Some regions may have limited availability"
+    - "Build time limits on free tier"

package/.grimoire/infrastructure/tools/cli/supabase-cli.yaml

@@ -0,0 +1,224 @@
+tool:
+  schema_version: 1.0
+  id: supabase-cli
+  type: cli
+  name: Supabase CLI
+  version: 1.0.0
+  description: Official Supabase command-line interface for local development, database migrations, Edge Functions, and project management
+  knowledge_strategy: declarative
+
+  capabilities:
+    - Local Supabase stack (PostgreSQL, Auth, Storage, Realtime)
+    - Database migrations and version control
+    - Edge Functions development and deployment
+    - Database diff and schema comparison
+    - Type generation for TypeScript
+    - Project linking and management
+    - Self-hosting setup
+
+  use_cases:
+    - local_development: "Run full Supabase stack locally with Docker"
+    - migration_management: "Create and apply database migrations"
+    - edge_functions: "Develop and deploy serverless functions"
+    - type_safety: "Generate TypeScript types from database schema"
+    - schema_diffing: "Compare local and remote database schemas"
+    - project_setup: "Initialize and configure Supabase projects"
+
+  installation:
+    npm: "npm install -g supabase"
+    homebrew: "brew install supabase/tap/supabase"
+    scoop: "scoop bucket add supabase https://github.com/supabase/scoop-bucket.git && scoop install supabase"
+
+  cli_specific:
+    executable: "supabase"
+    configuration:
+      config_file: "supabase/config.toml"
+      migrations_dir: "supabase/migrations"
+      functions_dir: "supabase/functions"
+      seed_file: "supabase/seed.sql"
+
+  command_groups:
+    initialization:
+      - command: "supabase init"
+        description: "Initialize a new Supabase project"
+        creates:
+          - "supabase/config.toml"
+          - "supabase/.gitignore"
+
+      - command: "supabase link"
+        description: "Link to a remote Supabase project"
+        common_flags:
+          - "--project-ref"
+        notes:
+          - "Requires Supabase access token"
+          - "Creates .env with SUPABASE_ACCESS_TOKEN"
+
+    local_development:
+      - command: "supabase start"
+        description: "Start local Supabase stack"
+        requirements:
+          - "Docker Desktop running"
+        provides:
+          - "PostgreSQL on localhost:54322"
+          - "Studio UI on http://localhost:54323"
+          - "Kong API Gateway on localhost:54321"
+          - "Inbucket email testing on localhost:54324"
+
+      - command: "supabase stop"
+        description: "Stop local Supabase stack"
+        common_flags:
+          - "--no-backup (skip backup before stopping)"
+
+      - command: "supabase status"
+        description: "Show status of local services"
+        output:
+          - "Service URLs and credentials"
+          - "API keys (anon, service_role)"
+
+    database_migrations:
+      - command: "supabase db diff"
+        description: "Generate migration from schema changes"
+        common_flags:
+          - "--file MIGRATION_NAME"
+          - "--schema public"
+        workflow:
+          - "Make schema changes in local database"
+          - "Run db diff to generate migration SQL"
+          - "Review and commit migration file"
+
+      - command: "supabase migration new"
+        description: "Create a new empty migration file"
+        usage: "supabase migration new MIGRATION_NAME"
+        generates: "supabase/migrations/YYYYMMDDHHMMSS_migration_name.sql"
+
+      - command: "supabase db push"
+        description: "Push local migrations to remote database"
+        common_flags:
+          - "--dry-run (preview without applying)"
+        notes:
+          - "Applies all pending migrations"
+          - "Requires linked project"
+
+      - command: "supabase db reset"
+        description: "Reset local database and reapply migrations"
+        common_flags:
+          - "--db-url (specify database URL)"
+        warning: "Destructive - drops all data"
+
+    edge_functions:
+      - command: "supabase functions new"
+        description: "Create a new Edge Function"
+        usage: "supabase functions new FUNCTION_NAME"
+        creates: "supabase/functions/FUNCTION_NAME/index.ts"
+
+      - command: "supabase functions serve"
+        description: "Serve Edge Functions locally"
+        common_flags:
+          - "--env-file (load environment variables)"
+          - "--no-verify-jwt (disable JWT verification)"
+        runs_on: "http://localhost:54321/functions/v1/FUNCTION_NAME"
+
+      - command: "supabase functions deploy"
+        description: "Deploy Edge Functions to remote project"
+        usage: "supabase functions deploy FUNCTION_NAME"
+        common_flags:
+          - "--no-verify-jwt"
+
+    type_generation:
+      - command: "supabase gen types typescript"
+        description: "Generate TypeScript types from database schema"
+        common_flags:
+          - "--local (use local database)"
+          - "--project-id PROJECT_REF (use remote project)"
+          - "--schema public"
+        output: "TypeScript definitions for database tables and views"
+        usage_example: "supabase gen types typescript --local > database.types.ts"
+
+    testing:
+      - command: "supabase db test"
+        description: "Run pgTAP tests"
+        requirements:
+          - "pgTAP extension enabled"
+          - "Test files in supabase/tests/"
+
+    secrets:
+      - command: "supabase secrets set"
+        description: "Set secrets for Edge Functions"
+        usage: "supabase secrets set KEY=VALUE"
+        notes:
+          - "Secrets available in Edge Functions via Deno.env"
+
+      - command: "supabase secrets list"
+        description: "List all secrets"
+
+  workflow_patterns:
+    feature_development:
+      - step: 1
+        action: "supabase start"
+        purpose: "Start local stack"
+      - step: 2
+        action: "Make schema changes in Studio or SQL"
+        purpose: "Develop feature"
+      - step: 3
+        action: "supabase db diff --file feature_name"
+        purpose: "Generate migration"
+      - step: 4
+        action: "supabase db reset"
+        purpose: "Test migration"
+      - step: 5
+        action: "supabase db push"
+        purpose: "Deploy to remote"
+
+    edge_function_development:
+      - step: 1
+        action: "supabase functions new my_function"
+        purpose: "Create function"
+      - step: 2
+        action: "Edit supabase/functions/my_function/index.ts"
+        purpose: "Implement logic"
+      - step: 3
+        action: "supabase functions serve"
+        purpose: "Test locally"
+      - step: 4
+        action: "supabase functions deploy my_function"
+        purpose: "Deploy to remote"
+
+  best_practices:
+    - "Always version control supabase/migrations directory"
+    - "Use db diff instead of manual migration writing"
+    - "Test migrations with db reset before pushing"
+    - "Keep migrations small and atomic"
+    - "Use descriptive migration names"
+    - "Generate types after schema changes"
+    - "Store secrets in proper environment, not in code"
+    - "Use --dry-run flag before db push"
+
+  authentication:
+    access_token:
+      purpose: "Required for linking and remote operations"
+      obtain: "From Supabase Dashboard > Account > Access Tokens"
+      env_var: "SUPABASE_ACCESS_TOKEN"
+      scope: "Project-level access"
+
+  common_issues:
+    docker_not_running:
+      error: "Cannot connect to Docker daemon"
+      solution: "Start Docker Desktop before running supabase start"
+
+    port_conflicts:
+      error: "Port already in use"
+      solution: "Stop conflicting services or change ports in config.toml"
+
+    migration_conflicts:
+      error: "Migration conflict detected"
+      solution: "Resolve conflicts in migration files, ensure proper ordering"
+
+    outdated_cli:
+      error: "CLI version too old"
+      solution: "Update CLI: npm update -g supabase or brew upgrade supabase"
+
+  limitations:
+    - "Requires Docker for local development"
+    - "Some features may differ between local and remote"
+    - "Edge Functions use Deno runtime (not Node.js)"
+    - "Migration rollback requires manual SQL"