# template: api-endpoint
# version: 1
# description: Add a new FastAPI endpoint to the Recoil pipeline server

parameters:
  - name: endpoint_name
    type: string
    pattern: "^[a-z][a-z0-9_]*$"
    description: "Snake-case endpoint name (e.g., 'process_shot', 'get_model_status')"
  - name: http_method
    type: enum
    values: [GET, POST, DELETE, PATCH]
    description: "HTTP method"
  - name: url_path
    type: string
    description: "URL path (e.g., '/api/shots/{shot_id}/process')"
  - name: router_file
    type: path
    description: "Router file to modify (project-relative, e.g. 'recoil/pipeline/api/shots.py')"
  - name: request_model
    type: string
    required: false
    description: "Pydantic request model name (required for POST/PATCH; leave empty for GET/DELETE)"
  - name: response_model
    type: string
    description: "Pydantic response model name"

phases:
  - name: models
    engine: claude
    description: "Add Pydantic request/response models to recoil/pipeline/api/models.py"
    files_modify:
      - recoil/pipeline/api/models.py
    validation: |
      python3 -c 'import ast; ast.parse(open("recoil/pipeline/api/models.py").read())' && \
      grep -q '{{ response_model }}' recoil/pipeline/api/models.py && \
      echo "models OK"

  - name: endpoint
    engine: claude
    depends_on: [models]
    description: "Implement {{ http_method }} {{ url_path }} in {{ router_file }}. The endpoint accepts {{ request_model }} as request body (leave empty if {{ http_method }} is GET or DELETE) and returns {{ response_model }}. Use the FastAPI decorator that matches {{ http_method }} (e.g., @router.post for POST, @router.get for GET). The Pydantic models {{ response_model }} (and {{ request_model }} if non-empty) live in recoil/pipeline/api/models.py and were created in the prior phase."
    files_modify_param: router_file
    validation: |
      python3 -c 'import ast, sys; ast.parse(open("{{ router_file }}").read())' && \
      grep -q '{{ url_path }}' "{{ router_file }}" && \
      grep -iq '@router\.{{ http_method }}' "{{ router_file }}" && \
      echo "endpoint OK"

  - name: tests
    engine: claude
    depends_on: [endpoint]
    description: "Write API tests for the new endpoint"
    files_create:
      - "recoil/tests/test_api_{{ endpoint_name }}.py"
    validation: |
      PYTHONPATH=. pytest "recoil/tests/test_api_{{ endpoint_name }}.py" -x --tb=short && \
      echo "tests OK"

gates:
  post_build:
    - description: "FastAPI app mounts without import errors"
      command: |
        PYTHONPATH=. python3 -c 'from recoil.pipeline.api.server import app; print("API mounts OK")'
