{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://kovanex.dev/schema/kovanex.yml.json",
  "title": "Kovanex Pipeline Definition",
  "description": "Schema for kovanex.yml — CI/CD pipeline configuration for Kovanex DevOps platform.",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Pipeline name displayed in UI and logs."
    },
    "on": {
      "$ref": "#/$defs/trigger",
      "description": "Trigger conditions — when the pipeline should run."
    },
    "env": {
      "type": "object",
      "additionalProperties": { "type": "string" },
      "description": "Global environment variables available to all jobs."
    },
    "jobs": {
      "type": "object",
      "additionalProperties": { "$ref": "#/$defs/job" },
      "description": "Map of job names to job definitions. Jobs run in topological order based on 'needs'."
    }
  },
  "required": ["jobs"],
  "additionalProperties": false,

  "$defs": {
    "trigger": {
      "type": "object",
      "properties": {
        "push": {
          "type": "object",
          "properties": {
            "branches": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Branch patterns to trigger on. Supports glob: 'main', 'release/*', '*'."
            },
            "tags": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Tag patterns to trigger on. Supports glob: 'v*', 'v1.*'."
            }
          },
          "additionalProperties": false,
          "description": "Trigger on git push."
        },
        "pull_request": {
          "type": "object",
          "properties": {
            "branches": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Target branch patterns for PR triggers."
            }
          },
          "additionalProperties": false,
          "description": "Trigger on pull request creation or update."
        },
        "manual": {
          "type": "boolean",
          "description": "Allow manual trigger via CLI or UI.",
          "default": false
        }
      },
      "additionalProperties": false
    },

    "job": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Job display name. Defaults to the job key."
        },
        "runs-on": {
          "type": "string",
          "description": "Runner label filter: 'any', 'default', 'linux', 'docker', or custom label.",
          "default": "any"
        },
        "needs": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Job dependencies — list of job names that must complete before this job starts."
        },
        "steps": {
          "type": "array",
          "items": { "$ref": "#/$defs/step" },
          "description": "Ordered list of steps to execute."
        },
        "env": {
          "type": "object",
          "additionalProperties": { "type": "string" },
          "description": "Job-level environment variables (merged with global env)."
        },
        "secrets": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Vault paths to inject as environment variables. Example: 'kv/env/myproject'."
        }
      },
      "required": ["steps"],
      "additionalProperties": false
    },

    "step": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Step display name shown in logs."
        },
        "uses": {
          "type": "string",
          "description": "Built-in action reference. Currently: 'checkout@v1'."
        },
        "run": {
          "type": "string",
          "description": "Shell command to execute. Supports multiline (YAML literal block)."
        },
        "env": {
          "type": "object",
          "additionalProperties": { "type": "string" },
          "description": "Step-level environment variables."
        },
        "with": {
          "type": "object",
          "additionalProperties": { "type": "string" },
          "description": "Parameters passed to the action specified in 'uses'."
        },
        "fire_and_forget": {
          "type": "boolean",
          "description": "Report success immediately before execution completes. Used for self-deploy steps that restart the server.",
          "default": false
        }
      },
      "oneOf": [
        { "required": ["run"] },
        { "required": ["uses"] }
      ],
      "additionalProperties": false
    }
  }
}