Docs builds, tests, publishes and deploys from iterate/docs

.depot/actions/setup/action.yml

@@ -0,0 +1,16 @@
+# THE SETUP OF A JOB ON DEPOT'S STOCK IMAGE, after its checkout: `uses: ./.depot/actions/setup`.
+# Node, pnpm and the Doppler CLI (scripts/ci/toolchain.sh), then the install. Docs' install takes
+# seconds from the npm registry, so no store is cached.
+name: Setup
+description: Node, pnpm and the Doppler CLI, and the install
+runs:
+  using: composite
+  steps:
+    - name: Toolchain
+      shell: bash
+      run: |
+        bash scripts/ci/toolchain.sh start
+        bash scripts/ci/toolchain.sh wait
+    - name: Install dependencies
+      shell: bash
+      run: pnpm install --frozen-lockfile

.depot/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+# The checks every pull request and main push runs: typecheck, lint, format, and the Vitest suites
+# (@iterate-com/docs' processors and the CI scripts).
+permissions:
+  contents: read
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.head_ref || github.ref_name }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  check:
+    name: Typecheck, lint and test
+    runs-on: depot-ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          ref: ${{ github.sha }}
+      - name: Setup
+        uses: ./.depot/actions/setup
+      - name: Typecheck
+        run: pnpm typecheck
+      - name: Lint
+        if: ${{ !cancelled() }}
+        run: pnpm lint
+      - name: Format
+        if: ${{ !cancelled() }}
+        run: pnpm format:check
+      - name: Test
+        if: ${{ !cancelled() }}
+        run: pnpm test
+      - name: Build the Docs app
+        if: ${{ !cancelled() }}
+        run: pnpm --dir packages/docs-app build

.depot/workflows/deploy.yml

@@ -0,0 +1,80 @@
+name: Deploy
+
+# DOCS AT MAIN: every main push that changes what the Worker ships deploys `preview`
+# (docs.iterate-dev-preview.workers.dev) and then, once that answers, `prd` (docs.iterate.workers.dev,
+# which the iterate project's `docs` slug and docs.iterate.com route to), both from envs.ts. A red run
+# pages.
+permissions:
+  contents: read
+
+concurrency:
+  group: deploy-main
+  cancel-in-progress: false
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "**"
+      - "!**/*.md"
+      - "!.github/**"
+      - "!scripts/ci/npm-publish*"
+  workflow_dispatch:
+
+jobs:
+  preview:
+    name: Deploy preview
+    runs-on: depot-ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          ref: ${{ github.sha }}
+      - name: Setup
+        uses: ./.depot/actions/setup
+      - name: Deploy
+        env:
+          DOPPLER_TOKEN: ${{ secrets.DOPPLER_TOKEN }}
+        run: pnpm --dir packages/docs-app run-script deploy --env preview
+
+  # only after preview answered: a deploy that fails there never reaches production
+  prd:
+    name: Deploy prd
+    needs: preview
+    runs-on: depot-ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          ref: ${{ github.sha }}
+      - name: Setup
+        uses: ./.depot/actions/setup
+      - name: Deploy
+        env:
+          DOPPLER_TOKEN: ${{ secrets.DOPPLER_TOKEN }}
+        run: pnpm --dir packages/docs-app run-script deploy --env prd
+
+  page:
+    needs:
+      - preview
+      - prd
+    if: always() && github.ref == 'refs/heads/main' && contains(needs.*.result, 'failure')
+    runs-on: depot-ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Toolchain
+        run: bash scripts/ci/toolchain.sh start && bash scripts/ci/toolchain.sh wait
+      - name: Page #error-pulse
+        env:
+          DOPPLER_TOKEN: ${{ secrets.DOPPLER_TOKEN }}
+          NEEDS: ${{ toJSON(needs) }}
+        run: node scripts/ci/page.ts

.github/workflows/npm-publish.yml

@@ -0,0 +1,69 @@
+name: npm
+# Every main commit publishes this repo's packages whose packed contents changed to npm, under the
+# `main` dist-tag, and points each package's `latest` at the same version (scripts/ci/npm-publish.ts
+# says how); any other ref, under `canary`, which leaves `latest` alone. Pull requests' builds stay
+# on pkg.pr.new (pkg-pr-new.yml): npm is public and permanent, so only reviewed code goes there.
+#
+# A GitHub Actions workflow, not Depot's: npm's trusted publishing takes an OIDC token from GitHub's
+# own runners. Each package's settings on npmjs.com name this repository and this file.
+#
+# A pull request that can change which packages main publishes, or how, publishes nothing. Its
+# `check` job fails until npm is ready for main to publish each package, and says what sets up one
+# that is not (README.md "A new package on npm"). The two jobs share no step and never run
+# together; they share this file because npm trades a token only for the file a package trusts, so
+# a check in a workflow of its own could not ask npm as the one that publishes.
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    paths:
+      # which packages: pkg-pr-new.yml's list of folders and the name in each folder's manifest
+      # (scripts/ci/npm-publish.test.ts holds every listed one to these)
+      - .github/workflows/pkg-pr-new.yml
+      - packages/*/package.json
+      # how
+      - .github/workflows/npm-publish.yml
+      - scripts/ci/npm-publish.ts
+  workflow_dispatch: {}
+# One publish at a time, in push order, so `main` never moves back to an older commit's version. A
+# run queued behind another is replaced by a newer push's, which publishes whatever both changed. A
+# pull request's run has a group of its own, so that it replaces no publish.
+concurrency:
+  group: ${{ github.event_name == 'pull_request' && format('npm-check-{0}', github.event.pull_request.number) || 'npm-publish' }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+jobs:
+  publish:
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 1
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .nvmrc
+      # trusted publishing needs npm 11.5.1 or later
+      - run: npm install --global npm@11
+      - run: pnpm install --frozen-lockfile --filter iterate-docs --filter @iterate-com/docs...
+      - run: node scripts/ci/npm-publish.ts publish --dist-tag ${{ github.ref == 'refs/heads/main' && 'main' || 'canary' }}
+  check:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 1
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .nvmrc
+      - run: pnpm install --frozen-lockfile --filter iterate-docs
+      - run: node scripts/ci/npm-publish.ts check

.github/workflows/pkg-pr-new.yml

@@ -0,0 +1,33 @@
+name: pkg.pr.new
+# Every main commit and every pull request's head publishes @iterate-com/docs to pkg.pr.new, so any
+# of them is installable: pkg.pr.new/iterate/docs/@iterate-com/docs@<sha>. A project pins one to try
+# a pull request's processors, and the Docs app a per-commit deployment builds installs its own
+# commit's (projects.$slug.$repo.$.tsx `docsBuild`). main's npm publish (npm-publish.yml) publishes
+# the same packages, by this list.
+#
+# A GitHub Actions workflow, not Depot's: pkg.pr.new's GitHub App authenticates the run by its
+# GitHub token.
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 1
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .nvmrc
+      - run: pnpm install --frozen-lockfile --filter iterate-docs --filter @iterate-com/docs...
+      - run: pnpm --dir packages/docs build
+      # --pnpm: pack with `pnpm pack` so publishConfig.exports (dist remap) is applied and `catalog:`
+      # becomes a version; `npm pack` would ship the dev exports pointing at src/. npm-publish.ts
+      # reads the packages off this line.
+      - run: pnpm exec pkg-pr-new publish --pnpm ./packages/docs

.gitignore

@@ -0,0 +1,21 @@
+.DS_Store
+node_modules
+*.tsbuildinfo
+
+# TanStack and Vite
+.tanstack
+dist
+
+# Cloudflare
+.mf
+.wrangler
+.dev.vars*
+!.dev.vars.example
+.env*
+!.env.example
+
+__pycache__/
+
+# ad-hoc ignored files/paths
+*ignoreme*
+*.log

.nvmrc

@@ -0,0 +1 @@
+24

.oxfmtrc.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": false,
+  "quoteProps": "as-needed",
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "bracketSameLine": false,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "embeddedLanguageFormatting": "auto",
+  "sortPackageJson": false,
+  "ignorePatterns": [
+    "node_modules/",
+    "dist/",
+    ".wrangler/",
+    "routeTree.gen.ts",
+    "pnpm-lock.yaml",
+    "pnpm-workspace.yaml",
+    "packages/docs-app/src/components/ui/",
+    "packages/docs-app/src/hooks/use-mobile.ts"
+  ]
+}