docs: Add comprehensive guide for auto-compilation flow development and deployment strategies

Author: jumski

.changeset/auto-compile-http-control.md

@@ -0,0 +1,6 @@
+---
+'pgflow': minor
+'@pgflow/edge-worker': minor
+---
+
+Add auto-compilation flow and HTTP control plane server for edge worker

.github/workflows/ci.yml

@@ -49,11 +49,8 @@ jobs:
           echo "NX_BASE=origin/main" >> $GITHUB_ENV
           echo "NX_HEAD=HEAD" >> $GITHUB_ENV
 
-      - name: Verify NX_BASE and NX_HEAD are set
-        run: echo "BASE=$NX_BASE HEAD=$NX_HEAD"
-
       - name: Pre-start Supabase for affected packages
-        run: ./scripts/ci-prestart-supabase.sh core client
+        run: ./scripts/ci-prestart-supabase.sh core client cli
 
       - name: Quality gate (lint + typecheck + test)
         run: pnpm nx affected -t lint typecheck test --parallel --configuration=production --base="$NX_BASE" --head="$NX_HEAD"
@@ -76,50 +73,95 @@ jobs:
 
       - uses: ./.github/actions/setup
 
+      - name: Check if edge-worker is affected
+        id: check
+        run: |
+          if pnpm nx show projects --affected --base=origin/main --head=HEAD | grep -q "^edge-worker$"; then
+            echo "affected=true" >> $GITHUB_OUTPUT
+            echo "edge-worker is affected, running e2e tests"
+          else
+            echo "affected=false" >> $GITHUB_OUTPUT
+            echo "edge-worker not affected, skipping e2e tests"
+          fi
+
       - name: Setup Deno
+        if: steps.check.outputs.affected == 'true'
         uses: denoland/setup-deno@v2
         with:
           deno-version: '2.1.4'
 
       - name: Install sqruff
+        if: steps.check.outputs.affected == 'true'
         uses: ./.github/actions/setup-sqruff
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Setup Atlas
+        if: steps.check.outputs.affected == 'true'
         uses: ariga/setup-atlas@master
         with:
           cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
 
-      - name: Set Nx base for affected commands
-        run: |
-          echo "NX_BASE=origin/main" >> $GITHUB_ENV
-          echo "NX_HEAD=HEAD" >> $GITHUB_ENV
+      - name: Pre-start Supabase
+        if: steps.check.outputs.affected == 'true'
+        run: ./scripts/ci-prestart-supabase.sh edge-worker
 
-      - name: Verify NX_BASE and NX_HEAD are set
-        run: echo "BASE=$NX_BASE HEAD=$NX_HEAD"
+      - name: Run edge-worker e2e tests
+        if: steps.check.outputs.affected == 'true'
+        run: pnpm nx run edge-worker:e2e
 
-      - name: Pre-start Supabase for affected packages
-        run: ./scripts/ci-prestart-supabase.sh edge-worker
+  # ─────────────────────────────────────── 2b. CLI E2E ──────────────────────────────────────
+  cli-e2e:
+    runs-on: ubuntu-latest
+    env:
+      NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
-      - name: Check if edge-worker e2e tests are affected
-        id: check-affected
+      - uses: ./.github/actions/setup
+
+      - name: Check if cli is affected
+        id: check
         run: |
-          if pnpm nx show projects --affected -t test:e2e --base="$NX_BASE" --head="$NX_HEAD" | grep -q "^edge-worker$"; then
+          if pnpm nx show projects --affected --base=origin/main --head=HEAD | grep -q "^cli$"; then
             echo "affected=true" >> $GITHUB_OUTPUT
-            echo "Edge-worker e2e tests are affected by changes"
+            echo "cli is affected, running e2e tests"
           else
             echo "affected=false" >> $GITHUB_OUTPUT
-            echo "Edge-worker e2e tests are not affected by changes - skipping"
+            echo "cli not affected, skipping e2e tests"
           fi
 
-      - name: Run edge-worker e2e tests
-        if: steps.check-affected.outputs.affected == 'true'
-        run: pnpm nx affected -t test:e2e --parallel --base="$NX_BASE" --head="$NX_HEAD"
+      - name: Setup Deno
+        if: steps.check.outputs.affected == 'true'
+        uses: denoland/setup-deno@v2
+        with:
+          deno-version: '2.1.4'
+
+      - name: Install sqruff
+        if: steps.check.outputs.affected == 'true'
+        uses: ./.github/actions/setup-sqruff
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Atlas
+        if: steps.check.outputs.affected == 'true'
+        uses: ariga/setup-atlas@master
+        with:
+          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
+
+      - name: Pre-start Supabase
+        if: steps.check.outputs.affected == 'true'
+        run: ./scripts/ci-prestart-supabase.sh cli
+
+      - name: Run cli e2e tests
+        if: steps.check.outputs.affected == 'true'
+        run: pnpm nx run cli:e2e
 
   # ────────────────────────────────── 3. DEPLOY WEBSITE ───────────────────────────
   deploy-website:
-    needs: [build-and-test, edge-worker-e2e]
+    needs: [build-and-test, edge-worker-e2e, cli-e2e]
     runs-on: ubuntu-latest
     environment: ${{ github.event_name == 'pull_request' && 'preview' || 'production' }}
     env:
@@ -142,9 +184,6 @@ jobs:
           echo "NX_BASE=origin/main" >> $GITHUB_ENV
           echo "NX_HEAD=HEAD" >> $GITHUB_ENV
 
-      - name: Verify NX_BASE and NX_HEAD are set
-        run: echo "BASE=$NX_BASE HEAD=$NX_HEAD"
-
       - name: Check if website is affected
         id: check-affected
         run: |
@@ -203,7 +242,7 @@ jobs:
   # ────────────────────────────────── 4. DEPLOY DEMO ───────────────────────────
   deploy-demo:
     if: false # temporarily disabled
-    needs: [build-and-test, edge-worker-e2e]
+    needs: [build-and-test, edge-worker-e2e, cli-e2e]
     runs-on: ubuntu-latest
     environment: ${{ github.event_name == 'pull_request' && 'preview' || 'production' }}
     env:
@@ -224,9 +263,6 @@ jobs:
           echo "NX_BASE=origin/main" >> $GITHUB_ENV
           echo "NX_HEAD=HEAD" >> $GITHUB_ENV
 
-      - name: Verify NX_BASE and NX_HEAD are set
-        run: echo "BASE=$NX_BASE HEAD=$NX_HEAD"
-
       - name: Validate Supabase environment variables
         run: |
           if [ -z "$VITE_SUPABASE_URL" ]; then

.gitignore

@@ -72,3 +72,4 @@ deno-dist/
 .netlify
 .cursor/rules/nx-rules.mdc
 .github/instructions/nx.instructions.md
+config.toml.backup