twenty/.github/workflows/ci-app-docs-drift.yaml

name: CI App Docs Drift

# When a PR changes the app-development surface (twenty-sdk, create-twenty-app,
# twenty-client-sdk, or the shared manifest types), an agent checks whether the
# app documentation under packages/twenty-docs/developers/extend/apps is
# impacted and, only when it is, posts a single sticky comment with its findings.

on:
  pull_request:

permissions:
  contents: read
  id-token: write

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  changed-files-check:
    uses: ./.github/workflows/changed-files.yaml
    with:
      files: |
        packages/twenty-sdk/**
        packages/create-twenty-app/**
        packages/twenty-client-sdk/**
        packages/twenty-shared/src/application/**
        packages/twenty-shared/src/types/**

  docs-drift-check:
    needs: changed-files-check
    # Secrets are unavailable on fork PRs; skip there and on bot PRs.
    if: >-
      needs.changed-files-check.outputs.any_changed == 'true' &&
      github.event.pull_request.head.repo.full_name == github.repository &&
      github.event.pull_request.user.type != 'Bot'
    timeout-minutes: 30
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      id-token: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          fetch-depth: 0

      - name: Run docs drift agent
        id: drift-agent
        uses: anthropics/claude-code-action@ac7e24bf2938964b8ab203e417a2773802392ddd # v1.0.146
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          claude_args: |
            --max-turns 60 --json-schema '{"type":"object","properties":{"hasDrift":{"type":"boolean"},"summary":{"type":"string"}},"required":["hasDrift","summary"]}' --allowedTools "Bash(git diff *),Bash(git log *),Bash(git show *),Bash(grep *),Bash(cat *),Bash(ls *),Bash(find *),Bash(head *),Bash(tail *),Bash(gh pr comment *)"
          prompt: |
            You are the app-documentation drift checker for the twenty repository.

            A pull request changed files in the app-development platform. Your job is to
            decide whether the documentation under
            `packages/twenty-docs/developers/extend/apps/` (English pages only — ignore
            `packages/twenty-docs/l/`) is impacted, and report your findings as ONE pull
            request comment.

            ## Step 1 — Understand the change

            The PR branch is checked out with full history; the base branch is
            `origin/${{ github.base_ref }}`. Inspect what the PR changes however you
            see fit. Only these kinds of changes are documentation-relevant:

            - CLI commands, subcommands, flags, defaults, or help text
              (`packages/twenty-sdk/src/cli/commands/**`)
            - `define*` function signatures, config properties, validation rules,
              or their warnings (`packages/twenty-sdk/src/sdk/define/**`)
            - Enum / string-union values and manifest types
              (`packages/twenty-shared/src/application/**`, `packages/twenty-shared/src/types/**`)
            - Exports added/removed/renamed in the `exports` maps of `twenty-sdk` or
              `twenty-client-sdk` package.json, or in their public entry points
            - Front-component runtime hooks and host API
              (`packages/twenty-sdk/src/sdk/front-component/**`)
            - The scaffold template (`packages/create-twenty-app/src/constants/template/**`)
              and scaffolder flags/prompts (`packages/create-twenty-app/src/cli.ts`,
              `create-app.command.ts`)
            - Environment variables injected into logic functions or front components
            - Error codes surfaced to app developers

            Internal refactors, tests, and implementation-only changes are NOT relevant —
            if the changes contain only those, say so and stop.

            ## Step 2 — Map to documentation

            Use this mapping to know which pages to check (read the actual pages):

            | Source area | Docs pages |
            |---|---|
            | CLI commands (`src/cli/commands`) | `operations/cli.mdx`, `getting-started/quick-start.mdx`, `operations/sync-and-recovery.mdx`, `getting-started/local-server.mdx`, `getting-started/scaffolding.mdx` |
            | `defineObject`/`defineField`/relations/indexes | `data/*.mdx` |
            | `defineApplication`/roles/install hooks/variables | `config/*.mdx` |
            | Logic functions, triggers, connections, agents/skills | `logic/*.mdx` |
            | Views, navigation, page layouts, front components, command menu | `layout/*.mdx` |
            | Publish/install/deploy, versioning, engines | `operations/publishing.mdx`, `operations/sync-and-recovery.mdx` |
            | Testing APIs (`twenty-sdk/cli` operations) | `operations/testing.mdx` |
            | Scaffold template | `getting-started/project-structure.mdx`, `getting-started/quick-start.mdx`, `operations/testing.mdx`, `operations/publishing.mdx` |
            | client SDK (`core`/`metadata`/`rest`/`generate`) | `logic/logic-functions.mdx`, `layout/front-components.mdx`, `operations/cli.mdx` |
            | Enum value sets (FieldType, ViewType, availabilityType, NavigationMenuItemType, ...) | the page documenting that value set (search for the enum name) |

            Also check whether the PR already updates the impacted docs pages — if it
            does, verify the update matches the code change.

            ## Step 3 — Report

            If there is NO documentation impact, do NOT post or create any comment.
            Skip the comment entirely and go straight to Step 4.

            Only when the documentation is impacted, post exactly one comment on PR
            #${{ github.event.pull_request.number }} with:
            `gh pr comment ${{ github.event.pull_request.number }} --edit-last --create-if-none --body ...`
            (this updates the previous drift-check comment in place on subsequent runs).
            Start the comment body with the marker `<!-- app-docs-drift-check -->`.

            Comment format:
            - Title line: `### App docs drift check`
            - A table with columns **Change** (what changed in the code),
              **Docs page** (repo-relative path), **Status** (`✅ already updated in this PR`
              / `⚠️ needs update`), and **Suggested fix** (one concrete sentence, e.g. the
              exact value to add to a table).
            - Be terse. No preamble, no sign-off. Only report genuine drift — if unsure
              whether something is user-facing, say it's uncertain rather than asserting.

            ## Step 4 — Return the verdict

            After posting the comment, return your final answer as the structured
            output the CI gate consumes:
            - `hasDrift`: `true` if at least one impacted docs page still needs updating
              (drift is NOT fully resolved by this PR); `false` if there is no
              documentation impact, or every impacted page is already correctly updated
              in this PR.
            - `summary`: one terse sentence describing the verdict.

            Environment: GH_TOKEN is available for `gh`. The PR branch is checked out.
          settings: |
            {
              "env": {
                "GH_TOKEN": "${{ secrets.GITHUB_TOKEN }}"
              }
            }

      - name: Gate on drift verdict
        if: always()
        env:
          AGENT_OUTCOME: ${{ steps.drift-agent.outcome }}
          STRUCTURED_OUTPUT: ${{ steps.drift-agent.outputs.structured_output }}
        run: |
          if [ "$AGENT_OUTCOME" != "success" ]; then
            echo "::error::Docs drift checker did not complete (agent step outcome: $AGENT_OUTCOME)."
            exit 1
          fi
          if [ -z "$STRUCTURED_OUTPUT" ]; then
            echo "::error::Docs drift checker did not return a structured verdict."
            exit 1
          fi
          has_drift=$(printf '%s' "$STRUCTURED_OUTPUT" | jq -r '.hasDrift')
          if [ "$has_drift" = "true" ]; then
            echo "::error::App docs drift detected. See the app-docs-drift-check comment on this PR."
            exit 1
          fi
          if [ "$has_drift" = "false" ]; then
            echo "No app docs drift."
            exit 0
          fi
          echo "::error::Structured verdict present but 'hasDrift' was not a recognizable boolean: $has_drift"
          exit 1