dc/.gitea/workflows/docs.yaml

name: Publish code documentation
run-name: Publishing typedoc and SAS docs

# The code documentation sites are published here rather than inline in the
# release job, so that they can be republished on their own - after a secret
# rotation, or for a release whose artefact upload failed (the release job
# cannot simply be re-run: semantic-release refuses once the tag exists).
on:
  workflow_dispatch:

env:
  NODE_VERSION: '24.15.0'

jobs:
  typedoc:
    runs-on: ubuntu-latest
    # One deploy per site at a time: `surfer deploy` swaps the site atomically,
    # so two runs racing is not corruption, but it is a wasted build and the
    # last swap wins.
    concurrency:
      group: surfer-webdoc
      cancel-in-progress: false
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}

      - name: Write .npmrc file
        run: |
          printf '%s\n' "$NPMRC" > "$RUNNER_TEMP/npmrc"
          echo "legacy-peer-deps=true" >> "$RUNNER_TEMP/npmrc"
          echo "NPM_CONFIG_USERCONFIG=$RUNNER_TEMP/npmrc" >> "$GITHUB_ENV"
        shell: bash
        env:
          NPMRC: ${{ secrets.NPMRC }}

      - name: Install dependencies
        run: |
          cd client
          # Decrypt and Install sheet
          echo "$SHEET_PWD" | gpg --batch --yes --passphrase-fd 0 ./libraries/sheet-crypto.tgz.gpg
          npm ci
          # client install scripts are off (client/.npmrc); the generator that
          # creates src/environments/version.ts runs explicitly
          npm run postinstall
        shell: bash
        env:
          SHEET_PWD: ${{ secrets.SHEET_PWD }}

      - name: Build typedoc
        run: |
          cd client
          npm run compodoc:build

      # Deploy tooling is pinned to an exact version: an unpinned `latest` would
      # let a breaking or compromised upstream release publish straight to the
      # live site.  `deploy` (v7) replaces the site atomically, and it takes the
      # Cloudron username plus an app password - the v6 `put --token` flow this
      # replaces is gone.
      #
      # webdoc is a NAMED site on the app whose default site is the marketing
      # site, so the name and its alias domain are both passed.  Surfer picks
      # the target only from `--site-name` (it travels as the Surfer-Deployment
      # header); without it `deploy` replaces the app's DEFAULT site, which is
      # what serves datacontroller.io - so an unnamed deploy published the
      # Typedoc over the top of the marketing site instead of to webdoc.
      - name: Deploy typedoc
        env:
          SURFER_PASSWORD: ${{ secrets.WEBDOC_DATACONTROLLER_IO }}
          REF_NAME: ${{ gitea.ref_name }}
          COMMIT_SHA: ${{ gitea.sha }}
        run: |
          set -euo pipefail
          npx --yes @cloudron/surfer@7.2.0 deploy client/documentation \
            --server webdoc.datacontroller.io \
            --site-name webdoc \
            --domain webdoc.datacontroller.io \
            --username allan \
            --password "$SURFER_PASSWORD" \
            --message "Typedoc from ${REF_NAME} @ ${COMMIT_SHA:0:8}"

      - name: Remove registry config
        # written earlier in this job; nothing deletes it on the way out
        if: always()
        run: rm -f "$RUNNER_TEMP/npmrc"

  sas-docs:
    runs-on: ubuntu-latest
    concurrency:
      group: surfer-code-datacontroller
      cancel-in-progress: false
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}

      - name: Install dependencies
        run: |
          # `sasjs doc` shells out to doxygen
          apt-get update
          apt-get install -y doxygen
          cd sas
          npm ci
          CLI_VERSION=$(node -p "require('./package.json').dependencies['@sasjs/cli']")
          npm i -g "@sasjs/cli@${CLI_VERSION}"

      - name: Build SAS docs
        run: |
          cd sas
          sasjs doc

      # No `--site-name` here on purpose: code.datacontroller.io is its own app
      # and the SAS docs are its DEFAULT site, so naming one would create a
      # separate site and leave the served copy stale.  Do not copy the named
      # form from the typedoc job above - that app's default site is the
      # marketing site, which is why it must not be the target.
      - name: Deploy SAS docs
        env:
          SURFER_PASSWORD: ${{ secrets.WEBDOC_DATACONTROLLER_IO }}
          REF_NAME: ${{ gitea.ref_name }}
          COMMIT_SHA: ${{ gitea.sha }}
        run: |
          set -euo pipefail
          npx --yes @cloudron/surfer@7.2.0 deploy sas/sasjsbuild/sasdocs \
            --server code.datacontroller.io \
            --username allan \
            --password "$SURFER_PASSWORD" \
            --message "SAS docs from ${REF_NAME} @ ${COMMIT_SHA:0:8}"