openapi: 3.0.3
info:
  title: Shoehorn Forge API
  description: |
    Workflow engine for scaffolding, automation, and self-service actions.
    Molds are templates; runs are workflow executions.
  version: 1.0.0

servers:
  - url: https://shoehorn.example.com/api/v1
    description: Production

paths:
  # --- Molds (Templates) ---
  /forge/molds:
    get:
      summary: List molds
      description: Returns available workflow templates.
      tags: [Molds]
      parameters:
        - name: category
          in: query
          schema: { type: string }
        - name: published
          in: query
          schema: { type: boolean }
      responses:
        '200':
          description: List of molds

    post:
      summary: Create mold
      tags: [Molds]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateMoldRequest' }
      responses:
        '201':
          description: Mold created

  /forge/molds/{slug}:
    get:
      summary: Get mold by slug
      tags: [Molds]
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Mold details including actions and parameters

    put:
      summary: Update mold
      tags: [Molds]
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateMoldRequest' }
      responses:
        '200':
          description: Mold updated

    delete:
      summary: Delete mold
      tags: [Molds]
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
      responses:
        '204':
          description: Mold deleted

  /forge/molds/{slug}/publish:
    post:
      summary: Publish mold
      description: Makes the mold visible to all users.
      tags: [Molds]
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Mold published

  /forge/molds/{slug}/unpublish:
    post:
      summary: Unpublish mold
      tags: [Molds]
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Mold unpublished

  # --- Runs (Workflow Executions) ---
  /forge/runs:
    get:
      summary: List workflow runs
      tags: [Runs]
      parameters:
        - name: mold_slug
          in: query
          schema: { type: string }
        - name: status
          in: query
          schema: { type: string, enum: [pending, running, completed, failed, cancelled, awaiting_approval] }
        - name: limit
          in: query
          schema: { type: integer, default: 20 }
        - name: cursor
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Paginated workflow runs

    post:
      summary: Execute a workflow
      description: Creates and starts a new workflow run from a mold.
      tags: [Runs]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [mold_slug, parameters]
              properties:
                mold_slug: { type: string }
                parameters: { type: object, description: User-provided parameter values }
      responses:
        '201':
          description: Run created and started

  /forge/runs/{runId}:
    get:
      summary: Get run details
      tags: [Runs]
      parameters:
        - name: runId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Run details with step statuses

  /forge/runs/{runId}/cancel:
    post:
      summary: Cancel a running workflow
      tags: [Runs]
      parameters:
        - name: runId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Run cancelled

  /forge/runs/{runId}/approve:
    post:
      summary: Approve a pending workflow
      description: Approves a workflow that is in awaiting_approval state.
      tags: [Runs]
      parameters:
        - name: runId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Run approved and resumed

  /forge/runs/{runId}/reject:
    post:
      summary: Reject a pending workflow
      tags: [Runs]
      parameters:
        - name: runId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Run rejected

  /forge/runs/{runId}/logs:
    get:
      summary: Get run execution logs
      tags: [Runs]
      parameters:
        - name: runId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Execution logs

  # --- Stats ---
  /forge/stats:
    get:
      summary: Get forge statistics
      tags: [Forge Stats]
      responses:
        '200':
          description: Workflow execution statistics

components:
  schemas:
    CreateMoldRequest:
      type: object
      required: [name, slug]
      properties:
        name: { type: string }
        slug: { type: string }
        description: { type: string }
        category: { type: string }
        icon: { type: string }
        parameters:
          type: array
          items: { $ref: '#/components/schemas/MoldParameter' }
        actions:
          type: array
          items: { $ref: '#/components/schemas/MoldAction' }
        requires_approval: { type: boolean, default: false }

    UpdateMoldRequest:
      type: object
      properties:
        name: { type: string }
        description: { type: string }
        category: { type: string }
        parameters:
          type: array
          items: { $ref: '#/components/schemas/MoldParameter' }
        actions:
          type: array
          items: { $ref: '#/components/schemas/MoldAction' }
        requires_approval: { type: boolean }

    MoldParameter:
      type: object
      required: [name, type]
      properties:
        name: { type: string }
        type: { type: string, enum: [string, number, boolean, select, multi-select] }
        label: { type: string }
        description: { type: string }
        required: { type: boolean, default: false }
        default: {}
        options:
          type: array
          items: { type: string }
          description: Options for select/multi-select types

    MoldAction:
      type: object
      required: [name, type]
      properties:
        name: { type: string }
        type: { type: string, enum: [github-action, api-call, script, approval] }
        config: { type: object }
