#
#                █████
#               ░░███
#       ██████  ███████    ██████
#      ███░░███░░░███░    ░░░░░███
#     ░███ ░███  ░███      ███████
#     ░███ ░███  ░███ ███ ███░░███
#     ░░██████   ░░█████ ░░████████
#      ░░░░░░     ░░░░░   ░░░░░░░░
#
#   Copyright (C) 2026 — 2026, Ota. All Rights Reserved.
#
#   DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
#   Licensed under the Apache License, Version 2.0. See LICENSE for the full license text.
#   You may not use this file except in compliance with that License.
#   Unless required by applicable law or agreed to in writing, software distributed under the
#   License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
#   either express or implied. See the License for the specific language governing permissions
#   and limitations under the License.
#
#   If you need additional information or have any questions, please email: os@ota.run

version: 1
project:
  name: full-contract
  description: Full example of the current Ota contract surface
  type: application
execution:
  default_context: host
  contexts:
    host:
      backend: native
    app:
      backend: container
      lifecycle: persistent
      container:
        image: node:24-bookworm
        resources:
          memory:
            minimum: 2GiB
            default: 3GiB
runtimes:
  python: ">=3.12"
  java:
    version: "21"
    provider: sdkman
    distribution: temurin
    only_on:
      - windows
      - macos
    platforms:
      windows:
        distribution: zulu
toolchains:
  node:
    version: "22"
    package_managers:
      pnpm: "10.0.0"
    fulfillment:
      source: corepack
      mode: run
  go:
    version: "1.26.0"
    fulfillment:
      source: go
      mode: none
  ruby:
    version: "3.3.11"
    package_managers:
      bundler: "2.5.3"
    fulfillment:
      source: ruby
      mode: run
tools:
  uv: "0.6.0"
  pwsh:
    version: "7.6.0"
    required: false
    only_on:
      - windows
  docker: "*"
  npx: "*"
env:
  vars:
    OTA_ENV:
      required: true
      allowed:
        - local
        - ci
    OTA_LOG_LEVEL:
      default: info
      allowed:
        - debug
        - info
        - warn
    PATH:
      prepend:
        - ./node_modules/.bin
  sources:
    - kind: dotenv
      path: .env.local
    - kind: dotenv
      path: .env
surfaces:
  site:
    kind: http
    label: Docs App
    purpose: Canonical browser-facing application surface
    visibility: public
    port: 3000
    path: /
    readiness:
      kind: http
      path: /health
      headers:
        Accept: application/json
      body:
        contains: '"status":"UP"'
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 10s
tasks:
  setup:
    context: host
    description: Install project dependencies
    category: setup
    script: |
      pnpm install
      pnpm exec prisma generate
    effects:
      writes:
        - node_modules
      network: true
    requirements:
      toolchains:
        - node
      checks:
        - node-installed
    safe_for_agent: true
  setup:container:
    context: app
    description: Generate Prisma client after dependency hydration in the container context
    category: setup
    run: pnpm exec prisma generate
    depends_on:
      - setup:container:deps
    effects:
      writes:
        - node_modules
    requirements:
      toolchains:
        - node
  setup:container:deps:
    context: app
    description: Hydrate project dependencies in the container context
    category: setup
    prepare:
      kind: dependency_hydration
      medium: package_dependencies
      source:
        kind: node_package_manager
        cwd: .
        manager: pnpm
        mode: install
    effects:
      writes:
        - node_modules
      network: true
      network_kind: dependency_hydration
    requirements:
      toolchains:
        - node
  setup:go:modules:
    context: host
    description: Hydrate Go module dependencies before native source verification
    category: setup
    prepare:
      kind: dependency_hydration
      medium: package_dependencies
      source:
        kind: go_modules
        cwd: .
    effects:
      network: true
      network_kind: dependency_hydration
    requirements:
      toolchains:
        - go
  setup:ruby:gems:
    context: host
    description: Hydrate repo-local Ruby dependencies before Rails verification
    category: setup
    prepare:
      kind: dependency_hydration
      medium: package_dependencies
      source:
        kind: bundler
        cwd: .
        path: vendor/bundle
    effects:
      writes:
        - .bundle
        - vendor/bundle
      network: true
      network_kind: dependency_hydration
    requirements:
      toolchains:
        - ruby
  setup:ruby:gems:compose:
    context: host
    description: Hydrate Compose-volume-backed Ruby dependencies through the app service
    category: setup
    prepare:
      kind: dependency_hydration
      medium: package_dependencies
      source:
        kind: bundler
        cwd: .
        path: vendor/bundle
        compose:
          kind: run
          service: app
          workdir: /workspace
          rm: true
    effects:
      adapter_state:
        - compose_volume:bundle_data
      network: true
      network_kind: dependency_hydration
    requirements:
      tools:
        docker: "*"
  setup:docker:images:
    context: host
    description: Pre-pull registry-backed docker dependencies before service startup
    category: setup
    prepare:
      kind: dependency_hydration
      medium: container_images
      source:
        kind: docker_compose
        cwd: .
        files:
          - docker-compose.yml
      targets:
        - postgres
    requirements:
      tools:
        docker: "*"
    effects:
      network: true
      network_kind: container_image_hydration
      external_state:
        - docker
  services:up:
    context: host
    description: Start the local service stack
    category: setup
    run: docker compose up -d postgres
    depends_on:
      - setup:docker:images
    effects:
      external_state:
        - docker
  dev:
    context: host
    description: Start the local development server on the host
    category: dev
    launch:
      kind: command
      exe: pnpm
      args:
        - dev
        - --host
        - 127.0.0.1
        - --port
        - "3000"
    requirements:
      toolchains:
        - node
    depends_on:
      - setup
    runtime:
      kind: service
      surfaces:
        - site
  dev:container:
    context: app
    description: Start the local development server in a container context
    category: dev
    launch:
      kind: command
      exe: pnpm
      args:
        - dev
        - --host
        - 0.0.0.0
        - --port
        - "3000"
    requirements:
      toolchains:
        - node
    depends_on:
      - setup:container
    runtime:
      kind: service
      surfaces:
        site:
          bind:
            address: 0.0.0.0
            port:
              mode: fixed
              value: 3000
          project:
            host:
              address: 127.0.0.1
              port:
                mode: fixed
                value: 3000
              path: /
              primary: true
  preview:quickstart:
    context: host
    description: Start the packaged preview through a structured command launch
    category: dev
    launch:
      kind: command
      exe: npx
      args:
        - vite
        - --host
        - 127.0.0.1
        - --port
        - "3000"
    requirements:
      toolchains:
        - node
      tools:
        npx: "*"
      checks:
        - node-installed
    depends_on:
      - setup
    runtime:
      kind: service
      surfaces:
        - site
  preview:packaged:
    context: host
    description: Start the packaged preview image through a structured container launch
    category: dev
    launch:
      kind: container
      image: ghcr.io/ota/full-contract-docs:latest
      volumes:
        - name: full_contract_docs
          target: /var/lib/full-contract
    requirements:
      tools:
        docker: "*"
    runtime:
      kind: service
      surfaces:
        site:
          bind:
            address: 0.0.0.0
            port:
              mode: fixed
              value: 3000
          project:
            host:
              address: 127.0.0.1
              port:
                mode: fixed
                value: 3000
              path: /
              primary: true
  test:
    context: host
    description: Run the validation suite
    category: test
    run: pnpm test
    requirements:
      toolchains:
        - node
    depends_on:
      - setup
    safe_for_agent: true
  verify:
    description: Run the canonical verification entrypoint
    category: test
    aggregate:
      tasks:
        - test
    safe_for_agent: true
    notes: |
      Use this when you want one named verification surface without a fake no-op shell body.
workflows:
  default: app
  app:
    intent: local_development
    description: Canonical container-backed app path
    setup:
      task: setup:container
    run:
      task: dev:container
    readiness:
      surfaces:
        - site
    exposes:
      - surface: site
  host:
    description: Direct host-backed dev path for local debugging
    setup:
      task: setup
    run:
      task: dev
    readiness:
      surfaces:
        - site
    exposes:
      - surface: site
  quickstart:
    intent: quickstart
    description: Structured packaged-command path for the browser preview
    setup:
      task: setup
    run:
      task: preview:quickstart
    readiness:
      surfaces:
        - site
    exposes:
      - surface: site
  packaged:
    intent: packaged_runtime
    description: Structured packaged-container path for the browser preview
    run:
      task: preview:packaged
    readiness:
      surfaces:
        - site
    exposes:
      - surface: site
checks:
  - name: node-installed
    kind: precondition
    severity: error
    run: node --version
    timeout: 10
  - name: repo-tests
    kind: health
    severity: warn
    run: pnpm test -- --runInBand
agent:
  posture: readiness_strict
  entrypoint: setup
  default_task: verify
  safe_tasks:
    - setup
    - test
    - verify
  verify_after_changes:
    - verify
  writable_paths:
    - src
    - docs
    - .github/workflows
    - node_modules
  exceptions:
    sensitive_writes:
      - .github/workflows
  protected_paths:
    - ota.yaml
    - Cargo.lock
    - LICENSE
  notes: |
    Use `ota workflows` to inspect the canonical repo paths before preparing or running them.
    Use `ota up --workflow app` for the main container-backed development path.
    Use `ota run test` to keep the contract and the implementation aligned.
metadata:
  owner: ota
  team: platform
  ota:
    minimum_version: "1.6.15"