Taskfile.yml

version: '3'

dotenv: ['.env']

vars:
  OPENAPI_V2: '{{.CLOUD_REPO_PATH}}/backend/spec/api/v2/openapi.json'
  OPENAPI_V3: '{{.CLOUD_REPO_PATH}}/backend/spec/api/v3/openapi.json'
  TS_SDK: browser-use-node
  PY_SDK: browser-use-python

tasks:
  # ── OpenAPI Spec ──────────────────────────────────────────────
  spec:pull:
    desc: Pull fresh OpenAPI specs from running local backend
    cmds:
      - curl -sf {{.BACKEND_URL}}/api/v2/openapi.json | python3 -m json.tool > {{.OPENAPI_V2}}
      - curl -sf {{.BACKEND_URL}}/api/v3/openapi.json | python3 -m json.tool > {{.OPENAPI_V3}}
      - echo "Updated OpenAPI specs from {{.BACKEND_URL}}"

  spec:diff:
    desc: Show what changed in the OpenAPI specs
    dir: '{{.CLOUD_REPO_PATH}}'
    cmds:
      - git diff --stat backend/spec/api/v2/openapi.json backend/spec/api/v3/openapi.json
      - git diff backend/spec/api/v2/openapi.json backend/spec/api/v3/openapi.json

  # ── Type Generation (deterministic, no AI) ────────────────────
  gen:types:
    desc: Generate v2 + v3 types for both TS and Python
    cmds:
      - task: gen:types:ts
      - task: gen:types:py

  gen:types:ts:
    desc: Generate TypeScript types from OpenAPI (v2 + v3)
    dir: '{{.TS_SDK}}'
    cmds:
      - npx openapi-typescript {{.OPENAPI_V2}} -o src/generated/v2/types.ts
      - npx openapi-typescript {{.OPENAPI_V3}} -o src/generated/v3/types.ts
      - echo "TypeScript types generated (v2 + v3)"

  gen:types:py:
    desc: Generate Python models from OpenAPI (v2 + v3)
    cmds:
      - |
        datamodel-codegen \
          --input {{.OPENAPI_V2}} \
          --input-file-type openapi \
          --output {{.PY_SDK}}/src/browser_use_sdk/generated/v2/models.py \
          --output-model-type pydantic_v2.BaseModel \
          --snake-case-field \
          --field-constraints \
          --use-union-operator \
          --disable-timestamp
      - |
        datamodel-codegen \
          --input {{.OPENAPI_V3}} \
          --input-file-type openapi \
          --output {{.PY_SDK}}/src/browser_use_sdk/generated/v3/models.py \
          --output-model-type pydantic_v2.BaseModel \
          --snake-case-field \
          --field-constraints \
          --use-union-operator \
          --disable-timestamp
      - echo "Python models generated (v2 + v3)"

  # ── Build ─────────────────────────────────────────────────────
  build:ts:
    desc: Build TypeScript SDK (CJS + ESM)
    dir: '{{.TS_SDK}}'
    cmds:
      - pnpm install --frozen-lockfile
      - pnpm build

  build:py:
    desc: Build Python SDK
    dir: '{{.PY_SDK}}'
    cmds:
      - uv build

  build:
    desc: Build both SDKs
    cmds:
      - task: build:ts
      - task: build:py

  # ── Type Check ────────────────────────────────────────────────
  check:ts:
    desc: Type-check TypeScript SDK
    dir: '{{.TS_SDK}}'
    cmds:
      - pnpm tsc --noEmit

  check:py:
    desc: Type-check Python SDK
    dir: '{{.PY_SDK}}'
    cmds:
      - uv run pyright src/

  check:
    desc: Type-check both SDKs
    cmds:
      - task: check:ts
      - task: check:py

  # ── Test ──────────────────────────────────────────────────────
  test:ts:
    desc: Run TypeScript tests
    dir: '{{.TS_SDK}}'
    cmds:
      - pnpm test

  test:py:
    desc: Run Python vibe tests (no backend or API needed)
    dir: '{{.PY_SDK}}'
    cmds:
      - uv run python -m pytest tests/ -m "not live and not prod"

  test:
    desc: Run all tests (vibe tests, no backend required)
    cmds:
      - task: test:ts
      - task: test:py

  test:live:ts:
    desc: Run TypeScript live integration tests (requires running backend)
    dir: '{{.TS_SDK}}'
    cmds:
      - npx tsx tests/live.test.ts

  test:live:py:
    desc: Run Python live integration tests (requires running backend)
    dir: '{{.PY_SDK}}'
    cmds:
      - uv run python -m pytest tests/ -m live -v -s

  test:live:
    desc: Run all live integration tests (requires running backend)
    cmds:
      - task: test:live:ts
      - task: test:live:py

  test:prod:ts:
    desc: Run TypeScript prod smoke tests (hits real API)
    dir: '{{.TS_SDK}}'
    cmds:
      - npx tsx tests/prod.test.ts

  test:prod:py:
    desc: Run Python prod smoke tests (hits real API)
    dir: '{{.PY_SDK}}'
    cmds:
      - uv run python -m pytest tests/ -m prod -v -s

  test:prod:
    desc: Run all prod smoke tests (hits real API, uses .env.prod)
    cmds:
      - task: test:prod:ts
      - task: test:prod:py

  # ── Version Management ────────────────────────────────────────
  version:
    desc: Show current versions
    cmds:
      - echo "TS {{.TS_SDK}}:" $(node -p "require('./{{.TS_SDK}}/package.json').version")
      - echo "PY {{.PY_SDK}}:" $(cd {{.PY_SDK}} && uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")

  version:bump:
    desc: "Bump version (usage: task version:bump -- patch|minor|major)"
    cmds:
      - cmd: cd {{.TS_SDK}} && npm version {{.CLI_ARGS | default "patch"}} --no-git-tag-version
      - cmd: |
          NEW_VERSION=$(node -p "require('./{{.TS_SDK}}/package.json').version")
          cd {{.PY_SDK}} && sed -i '' "s/^version = \".*\"/version = \"${NEW_VERSION}\"/" pyproject.toml
          echo "Python version bumped to ${NEW_VERSION}"
      - cmd: |
          NEW_VERSION=$(node -p "require('./{{.TS_SDK}}/package.json').version")
          sed -i '' "s/| TypeScript | npm | [0-9]*\.[0-9]*\.[0-9]* |/| TypeScript | npm | ${NEW_VERSION} |/" README.md
          sed -i '' "s/| Python | PyPI | [0-9]*\.[0-9]*\.[0-9]* |/| Python | PyPI | ${NEW_VERSION} |/" README.md
          echo "README.md versions updated to ${NEW_VERSION}"
      - task: version

  release:
    desc: "Cut a release: bump version, commit, push branch, open PR (usage: task release -- patch|minor|major)"
    cmds:
      - cmd: |
          set -euo pipefail
          BUMP="{{.CLI_ARGS}}"
          if [ -z "$BUMP" ]; then BUMP="patch"; fi
          if [ "$BUMP" != "patch" ] && [ "$BUMP" != "minor" ] && [ "$BUMP" != "major" ]; then
            echo "ERROR: invalid bump '$BUMP'. Use patch, minor, or major." >&2
            exit 1
          fi

          # Refuse to run on a dirty tree — too easy to ship unrelated WIP.
          if ! git diff --quiet || ! git diff --cached --quiet; then
            echo "ERROR: working tree is dirty. Commit or stash before releasing." >&2
            git status --short >&2
            exit 1
          fi

          # The task auto-creates the release branch from main, so it must be
          # run FROM main. Refuse otherwise — running from a feature branch
          # would surprise the user with a branch named off a non-main tip.
          CURRENT_BRANCH="$(git rev-parse --abbrev-ref HEAD)"
          if [ "$CURRENT_BRANCH" != "main" ]; then
            echo "ERROR: refusing to run. \`task release\` auto-creates a release branch off main, so it must be started from main." >&2
            echo "Currently on: $CURRENT_BRANCH" >&2
            echo "Switch first:" >&2
            echo "  git checkout main" >&2
            exit 1
          fi

          # Fast-forward main to origin/main so the new branch is based on the
          # latest published main, not whatever stale state we have locally.
          # --ff-only fails if local main has unpushed commits, which would be
          # weird — bail loud so the user reconciles.
          git fetch origin main --quiet
          if ! git merge-base --is-ancestor origin/main HEAD; then
            echo "ERROR: local main has commits not on origin/main. Reconcile before releasing." >&2
            echo "  git log origin/main..HEAD --oneline" >&2
            exit 1
          fi
          git pull --ff-only origin main --quiet

          # Create the release branch. Date+time keeps it unique across
          # multiple releases the same day; the branch auto-deletes on PR merge
          # (squash + delete-on-merge), so the branch list stays clean.
          NEW_BRANCH="release/$(date +%Y%m%d-%H%M%S)"
          git checkout -b "$NEW_BRANCH"
          echo "::notice::Created release branch $NEW_BRANCH from main."
      - task: "version:bump"
        vars: { CLI_ARGS: '{{.CLI_ARGS | default "patch"}}' }
      - cmd: |
          set -euo pipefail
          BUMP="{{.CLI_ARGS}}"
          if [ -z "$BUMP" ]; then BUMP="patch"; fi
          NEW_VERSION="$(node -p "require('./{{.TS_SDK}}/package.json').version")"
          echo
          echo "Releasing v${NEW_VERSION}."

          # Stage the manifest + README updates that version:bump touched.
          git add {{.TS_SDK}}/package.json {{.PY_SDK}}/pyproject.toml README.md

          # Commit. Conventional-ish message so it's obvious in main's history.
          git commit -m "release: v${NEW_VERSION}" -m "Bumps both SDK manifests. Merging this PR will trigger auto-release-on-version-bump → publish.yml (gated by the release env)."

          # Push the branch. -u so future pushes work without args.
          BRANCH="$(git rev-parse --abbrev-ref HEAD)"
          git push -u origin "$BRANCH"

          # Open the PR. If gh is logged in, this Just Works; otherwise prints
          # the manual fallback URL.
          if command -v gh >/dev/null 2>&1; then
            gh pr create \
              --repo browser-use/sdk \
              --base main \
              --head "$BRANCH" \
              --title "release: v${NEW_VERSION}" \
              --body "Bumps both SDK manifests to v${NEW_VERSION}.

          Merging this PR triggers \`auto-release-on-version-bump\` → \`publish.yml\` (gated by the \`release\` env, requires a non-author approver, OIDC publish to npm + PyPI).

          Generated by \`task release -- $BUMP\`."
          else
            echo "gh CLI not found. Push succeeded; open the PR manually:"
            echo "  https://github.com/browser-use/sdk/compare/main...$BRANCH?expand=1"
          fi

          echo
          echo "Done. Merge the PR to trigger the release."

  # ── Publish ───────────────────────────────────────────────────
  # Releases now ship through GitHub Releases + gated CI (.github/workflows/publish.yml).
  # The tasks below are intentionally non-functional. The old commands are kept
  # commented inline so a maintainer can emergency-unblock by editing this file
  # (intentional friction: editing Taskfile is the only path).
  publish:ts:
    desc: "[DEPRECATED] Use GitHub Releases. See RUNBOOK.md."
    dir: '{{.TS_SDK}}'
    cmds:
      - |
        echo "ERROR: 'task publish:ts' is deprecated."
        echo "Releases now ship through GitHub Releases + gated CI."
        echo "See RUNBOOK.md > 'Release authentication' for the new flow."
        echo
        echo "Emergency unblock (logged): uncomment the line below in Taskfile.yml"
        echo "  # npm publish --access public"
        exit 1

  publish:py:
    desc: "[DEPRECATED] Use GitHub Releases. See RUNBOOK.md."
    dir: '{{.PY_SDK}}'
    cmds:
      - |
        echo "ERROR: 'task publish:py' is deprecated."
        echo "Releases now ship through GitHub Releases + gated CI."
        echo "See RUNBOOK.md > 'Release authentication' for the new flow."
        echo
        echo "Emergency unblock (logged): uncomment the lines below in Taskfile.yml"
        echo "  # rm -rf dist/"
        echo "  # task: build:py"
        echo "  # uv publish --token <PYPI_TOKEN>"
        exit 1

  publish:
    desc: "[DEPRECATED] Use GitHub Releases. See RUNBOOK.md."
    cmds:
      - |
        echo "ERROR: 'task publish' is deprecated."
        echo "Releases now ship through GitHub Releases + gated CI."
        echo "See RUNBOOK.md > 'Release authentication' for the new flow."
        echo
        echo "Emergency unblock (logged): uncomment the lines below in Taskfile.yml"
        echo "  # task: publish:ts"
        echo "  # task: publish:py"
        exit 1

  # ── Snapshots ─────────────────────────────────────────────────
  snapshot:save:
    desc: Save current OpenAPI specs as snapshots (run after successful generation)
    cmds:
      - cp {{.OPENAPI_V2}} snapshots/v2.json
      - cp {{.OPENAPI_V3}} snapshots/v3.json
      - task: docs:sync
      - echo "Snapshots saved and docs synced"

  snapshot:diff:
    desc: Show what changed between snapshots and current specs
    cmds:
      - echo "=== v2 changes ==="
      - diff snapshots/v2.json {{.OPENAPI_V2}} || true
      - echo ""
      - echo "=== v3 changes ==="
      - diff snapshots/v3.json {{.OPENAPI_V3}} || true

  # ── Docs ─────────────────────────────────────────────────────
  docs:sync:
    desc: Copy OpenAPI specs into docs for Mintlify
    cmds:
      - cp snapshots/v2.json docs/openapi/v2.json
      - cp snapshots/v3.json docs/openapi/v3.json

  docs:dev:
    desc: Start Mintlify docs dev server
    deps: [docs:sync]
    dir: docs
    cmds:
      - mint dev

  docs:install:
    desc: Install Mintlify CLI globally
    cmds:
      - npm install -g mintlify

  # ── Full Pipeline ─────────────────────────────────────────────
  update:
    desc: "Full mechanical pipeline: spec -> types -> check -> docs"
    cmds:
      - task: spec:pull
      - task: gen:types
      - task: check
      - task: docs:sync
      - echo ""
      - echo "Types regenerated and type-checked."
      - echo "Next steps:"
      - echo "  1. /sdk build   -- regenerate SDK client code"
      - echo "  2. /sdk test    -- vibe test against localhost"
      - echo "  3. /sdk docs    -- update docs + drift check"
      - echo "  4. git diff     -- review everything"