feat: finish algolia env split

- centralize public and publisher Algolia env parsing
- disable search clearly when public env is missing
- inject dev/prod Algolia envs in deploy CI
- fix the pre-existing lazy wrapper compile blockers

Author: jderochervlk

.github/workflows/deploy.yml

@@ -46,6 +46,38 @@ jobs:
              echo "SAFE_BRANCH=$SAFE_BRANCH" >> "$GITHUB_ENV"
              echo "VITE_DEPLOYMENT_URL=https://${SAFE_BRANCH}.rescript-lang.pages.dev" >> "$GITHUB_ENV"
           fi
+      - name: Set Algolia env
+        shell: bash
+        env:
+          ALGOLIA_APP_ID: ${{ vars.ALGOLIA_APP_ID }}
+          ALGOLIA_INDEX_BASENAME: ${{ vars.ALGOLIA_INDEX_BASENAME }}
+          ALGOLIA_SEARCH_API_KEY_DEV: ${{ vars.ALGOLIA_SEARCH_API_KEY_DEV }}
+          ALGOLIA_SEARCH_API_KEY_PROD: ${{ vars.ALGOLIA_SEARCH_API_KEY_PROD }}
+          ALGOLIA_ADMIN_API_KEY_DEV: ${{ secrets.ALGOLIA_ADMIN_API_KEY_DEV }}
+          ALGOLIA_ADMIN_API_KEY_PROD: ${{ secrets.ALGOLIA_ADMIN_API_KEY_PROD }}
+        run: |
+          if [[ "${{ github.event_name }}" == "push" && "${{ github.ref_name }}" == "master" ]]; then
+            INDEX_PREFIX="prod"
+            SEARCH_KEY="$ALGOLIA_SEARCH_API_KEY_PROD"
+            ADMIN_KEY="$ALGOLIA_ADMIN_API_KEY_PROD"
+          elif [[ "${{ github.event_name }}" == "workflow_dispatch" && "${{ inputs.environment }}" == "production" ]]; then
+            INDEX_PREFIX="prod"
+            SEARCH_KEY="$ALGOLIA_SEARCH_API_KEY_PROD"
+            ADMIN_KEY="$ALGOLIA_ADMIN_API_KEY_PROD"
+          else
+            INDEX_PREFIX="dev"
+            SEARCH_KEY="$ALGOLIA_SEARCH_API_KEY_DEV"
+            ADMIN_KEY="$ALGOLIA_ADMIN_API_KEY_DEV"
+          fi
+
+          INDEX_NAME="${INDEX_PREFIX}_${ALGOLIA_INDEX_BASENAME}"
+
+          echo "VITE_ALGOLIA_APP_ID=$ALGOLIA_APP_ID" >> "$GITHUB_ENV"
+          echo "VITE_ALGOLIA_INDEX_NAME=$INDEX_NAME" >> "$GITHUB_ENV"
+          echo "VITE_ALGOLIA_SEARCH_API_KEY=$SEARCH_KEY" >> "$GITHUB_ENV"
+          echo "ALGOLIA_APP_ID=$ALGOLIA_APP_ID" >> "$GITHUB_ENV"
+          echo "ALGOLIA_INDEX_NAME=$INDEX_NAME" >> "$GITHUB_ENV"
+          echo "ALGOLIA_ADMIN_API_KEY=$ADMIN_KEY" >> "$GITHUB_ENV"
       - name: Build
         run: yarn build
         env:

__tests__/AlgoliaConfig_.test.res

@@ -0,0 +1,41 @@
+open Vitest
+
+describe("publicConfigFrom", () => {
+  test("returns config when all public vars are present", async () => {
+    let result = AlgoliaConfig.publicConfigFrom(
+      ~appId=Some("app_123"),
+      ~indexName=Some("dev_rescript_lang"),
+      ~searchApiKey=Some("search_123"),
+    )
+
+    let expected: AlgoliaConfig.publicConfig = {
+      appId: "app_123",
+      indexName: "dev_rescript_lang",
+      searchApiKey: "search_123",
+    }
+
+    expect(result)->toEqual(Some(expected))
+  })
+
+  test("reports missing public vars in declaration order", async () => {
+    let result = AlgoliaConfig.missingPublicVars(
+      ~appId=None,
+      ~indexName=Some("dev_rescript_lang"),
+      ~searchApiKey=None,
+    )
+
+    expect(result)->toEqual(["VITE_ALGOLIA_APP_ID", "VITE_ALGOLIA_SEARCH_API_KEY"])
+  })
+})
+
+describe("publisherConfigFrom", () => {
+  test("reports missing publisher vars in declaration order", async () => {
+    let result = AlgoliaConfig.missingPublisherVars(
+      ~appId=Some("app_123"),
+      ~indexName=None,
+      ~adminApiKey=None,
+    )
+
+    expect(result)->toEqual(["ALGOLIA_INDEX_NAME", "ALGOLIA_ADMIN_API_KEY"])
+  })
+})

__tests__/Search_.test.res

@@ -424,3 +424,12 @@ describe("isChildHit", () => {
     )
   })
 })
+
+test("renders disabled search copy when Algolia config is missing", async () => {
+  await viewport(1440, 500)
+
+  let screen = await render(<Search />)
+
+  await element(await screen->getByText("Search unavailable"))->toBeVisible
+  await element(await screen->getByLabelText("Search unavailable for this build"))->toBeVisible
+})

docs/superpowers/specs/2026-04-25-algolia-env-split-design.md

@@ -0,0 +1,174 @@
+# Algolia Env Split Design
+
+Date: 2026-04-25
+
+## Summary
+
+This change keeps the site on its current pre-rendered Cloudflare Pages setup and splits Algolia configuration into:
+
+- public build-time variables for browser search
+- private publish-only variables for search index uploads
+
+Fork PRs and any build without the public Algolia variables should still build successfully, but the UI must clearly show that search is unavailable. The search indexing script should continue to skip cleanly when its private publish variables are missing.
+
+## Goals
+
+- Keep the existing static React Router + Cloudflare Pages architecture.
+- Do not adopt `@react-router/cloudflare`.
+- Make browser search depend only on `VITE_` variables that are safe to bundle.
+- Keep Algolia admin credentials out of the browser bundle and out of fork PR builds.
+- Make preview and production index names deterministic via CI-computed `dev_` and `prod_` prefixes.
+- Make disabled search obvious in the UI and in local/build logs.
+
+## Non-Goals
+
+- Changing the site from prerendered Pages to a Cloudflare Workers runtime app.
+- Solving team-wide local secret distribution in this PR.
+- Enabling Algolia-backed search for fork preview builds.
+- Introducing GitHub Environments. This design uses repo-level variables and secrets only.
+
+## Current Constraints
+
+- The site is prerendered with `ssr: false` and uploaded to Cloudflare Pages as static output.
+- Frontend values must be present at build time because Vite bakes `VITE_*` values into the client bundle.
+- The deploy workflow builds in GitHub Actions before uploading to Cloudflare Pages, so Cloudflare dashboard vars are not the primary source for these build-time values.
+- Fork PR workflows must not receive Algolia secrets or public search variables.
+
+## Environment Contract
+
+### GitHub repo variables and secrets
+
+Public build-time values:
+
+- `ALGOLIA_APP_ID`
+- `ALGOLIA_INDEX_BASENAME`
+- `ALGOLIA_SEARCH_API_KEY_DEV`
+- `ALGOLIA_SEARCH_API_KEY_PROD`
+
+Private publish-only secrets:
+
+- `ALGOLIA_ADMIN_API_KEY_DEV`
+- `ALGOLIA_ADMIN_API_KEY_PROD`
+
+### Computed values in CI
+
+The workflow computes the full index name from the base name:
+
+- pull request builds with Algolia config: `dev_${ALGOLIA_INDEX_BASENAME}`
+- preview / non-fork PR deploys: `dev_${ALGOLIA_INDEX_BASENAME}`
+- production deploys from `master`: `prod_${ALGOLIA_INDEX_BASENAME}`
+
+### Variables exposed to the browser build
+
+The build step exports:
+
+- `VITE_ALGOLIA_APP_ID`
+- `VITE_ALGOLIA_INDEX_NAME`
+- `VITE_ALGOLIA_SEARCH_API_KEY`
+
+These are the only Algolia values used by the frontend.
+
+### Variables used by the indexing script
+
+The indexing script receives:
+
+- `ALGOLIA_APP_ID`
+- `ALGOLIA_INDEX_NAME`
+- `ALGOLIA_ADMIN_API_KEY`
+
+These values remain private and are never read from `import.meta.env`.
+
+## Workflow Behavior
+
+### `deploy.yml`
+
+- `pull_request` for non-fork branches uses the `DEV` public key and `DEV` admin key.
+- `pull_request` builds target the Algolia `dev_` index prefix, never the `prod_` index prefix.
+- `push` to `master` uses the `PROD` public key and `PROD` admin key.
+- `workflow_dispatch` keeps the existing `environment` input and maps it to either `DEV` or `PROD`.
+- The workflow computes the index name with the matching prefix before running the build.
+- The workflow exports both the public `VITE_*` variables and the private indexing variables for the build pipeline.
+
+### `deploy-fork-preview.yml`
+
+- Do not inject any Algolia variables or secrets.
+- The build must still succeed.
+- Search should render in its disabled state for these builds.
+- The indexing step should skip because its private variables are absent.
+- Even for pull requests, fork preview builds do not use the Algolia dev index because they receive no Algolia configuration.
+
+### `pull-request.yml`
+
+- Do not inject Algolia variables by default.
+- Validation should continue to pass with search disabled.
+- Only revisit this if a test later requires Algolia-backed search specifically.
+
+## Application Behavior
+
+### Frontend search availability
+
+Search is enabled only when all of these values are present and non-empty:
+
+- `VITE_ALGOLIA_APP_ID`
+- `VITE_ALGOLIA_INDEX_NAME`
+- `VITE_ALGOLIA_SEARCH_API_KEY`
+
+If any one is missing, the app treats search as unavailable.
+
+### Disabled UI
+
+When search is unavailable:
+
+- Do not mount the Algolia DocSearch modal.
+- Do not wire the search trigger to open the modal.
+- Render a visibly disabled search affordance instead of a normal active trigger.
+- Include explicit text such as `Search unavailable`.
+- Include accessible labeling that explains search is disabled for this build.
+
+The result should be obvious to users rather than silently removing the feature or showing a broken interaction.
+
+### Logging
+
+When the public browser variables are incomplete:
+
+- log a clear message during local development and build startup
+- include the missing variable names in the message
+
+Example shape:
+
+`Algolia search disabled: missing VITE_ALGOLIA_APP_ID, VITE_ALGOLIA_INDEX_NAME`
+
+When the indexing variables are incomplete:
+
+- keep the current graceful skip behavior
+- log which private variable is missing
+
+## Local Development
+
+- Remove tracked Algolia values from `.env`.
+- Developers can opt into local search with untracked local environment files such as `.env.local`.
+- If local Algolia values are absent, the site should still run normally with disabled search UI and a console warning.
+
+This keeps local development usable without requiring every contributor to have Algolia credentials.
+
+## Naming Decision
+
+This design uses one Algolia application and separate indices for preview and production:
+
+- `dev_<base>`
+- `prod_<base>`
+
+Index naming alone does not create a special Algolia environment. It only scopes records into separate indices. This is sufficient for this PR and avoids introducing a second Algolia application.
+
+## Verification Plan
+
+- Confirm non-fork preview deploys receive `dev_` index names and the `DEV` keys.
+- Confirm production deploys receive `prod_` index names and the `PROD` keys.
+- Confirm fork preview builds complete without Algolia configuration.
+- Confirm the UI renders the disabled search state when public vars are absent.
+- Confirm the build/dev logs clearly state why search is disabled.
+- Confirm the indexing script skips cleanly when its private variables are absent.
+
+## Open Questions
+
+None for this design. Team distribution of local development variables is intentionally deferred.

package.json

@@ -17,17 +17,18 @@
     "build:search-index": "node --env-file-if-exists=.env --env-file-if-exists=.env.local _scripts/generate_search_index.mjs",
     "build:update-index": "yarn build:generate-llms && node _scripts/generate_feed.mjs > public/blog/feed.xml && yarn build:search-index",
     "build:vite": "react-router build",
-    "build": "yarn build:res && yarn build:scripts && yarn build:update-index && yarn build:vite",
+    "check:algolia-public-env": "node scripts/log_algolia_env_status.mjs",
+    "build": "yarn check:algolia-public-env && yarn build:res && yarn build:scripts && yarn build:update-index && yarn build:vite",
     "ci:format": "prettier . --check --experimental-cli",
     "ci:test": "yarn vitest --run --browser.headless",
     "clean:res": "rescript clean",
-    "convert-images": "auto-convert-images",
+    "convert-images": "auto-image-converter",
     "dev:res": "rescript watch",
     "dev:vite": "react-router dev --host",
     "dev:wrangler": "yarn wrangler pages dev build/client",
     "dev": "yarn prepare && yarn dev:res & yarn dev:vite & yarn dev:wrangler",
     "format": "prettier . --write --experimental-cli && rescript format",
-    "prepare": "yarn build:res && yarn build:scripts && yarn build:update-index",
+    "prepare": "yarn check:algolia-public-env && yarn build:res && yarn build:scripts && yarn build:update-index",
     "preview": "yarn build && static-server build/client",
     "reanalyze": "rescript-tools reanalyze -all-cmt .",
     "test": "node scripts/test-examples.mjs && node scripts/test-hrefs.mjs",

scripts/__tests__/log_algolia_env_status.test.mjs

@@ -0,0 +1,24 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  formatDisabledMessage,
+  getMissingPublicAlgoliaVars,
+} from "../log_algolia_env_status.mjs";
+
+test("reports missing public vars in declaration order", () => {
+  assert.deepEqual(
+    getMissingPublicAlgoliaVars({
+      VITE_ALGOLIA_APP_ID: "",
+      VITE_ALGOLIA_INDEX_NAME: "dev_rescript_lang",
+      VITE_ALGOLIA_SEARCH_API_KEY: undefined,
+    }),
+    ["VITE_ALGOLIA_APP_ID", "VITE_ALGOLIA_SEARCH_API_KEY"],
+  );
+});
+
+test("formats the disabled search warning", () => {
+  assert.equal(
+    formatDisabledMessage(["VITE_ALGOLIA_APP_ID"]),
+    "Algolia search disabled: missing VITE_ALGOLIA_APP_ID",
+  );
+});

scripts/generate_search_index.res

@@ -2,10 +2,11 @@
 // Runs as a standalone Node script via: node --env-file-if-exists=.env --env-file-if-exists=.env.local _scripts/generate_search_index.mjs
 //
 // Required env vars:
+//   ALGOLIA_APP_ID       -- Algolia application ID
 //   ALGOLIA_ADMIN_API_KEY -- API key with addObject/deleteObject/editSettings ACLs
 //   ALGOLIA_INDEX_NAME    -- e.g. "rescript-lang-dev" or "rescript-lang"
 //
-// If either is missing, the script logs a warning and exits 0 (graceful skip).
+// If any are missing, the script logs a warning and exits 0 (graceful skip).
 
 let getEnv = (key: string): option<string> =>
   Node.Process.env
@@ -74,9 +75,10 @@ let main = async () => {
   let appId = getEnv("ALGOLIA_APP_ID")
   let adminApiKey = getEnv("ALGOLIA_ADMIN_API_KEY")
   let indexName = getEnv("ALGOLIA_INDEX_NAME")
+  let publisherConfig = AlgoliaConfig.publisherConfigFrom(~appId, ~indexName, ~adminApiKey)
 
-  switch (appId, adminApiKey, indexName) {
-  | (Some(appId), Some(apiKey), Some(idx)) => {
+  switch publisherConfig {
+  | Some({appId, indexName, adminApiKey}) => {
       Console.log("[search-index] Building search index records...")
 
       let apiDir = resolveApiDir()->Option.getOr("markdown-pages/docs/api")
@@ -176,11 +178,11 @@ let main = async () => {
       let jsonRecords = allRecords->Array.map(SearchIndex.toJson)
 
       // 4. Initialize Algolia client and upload
-      let client = Algolia.make(appId, apiKey)
+      let client = Algolia.make(appId, adminApiKey)
 
-      Console.log(`[search-index] Uploading to index "${idx}"...`)
+      Console.log(`[search-index] Uploading to index "${indexName}"...`)
       let _ = await client->Algolia.replaceAllObjects({
-        indexName: idx,
+        indexName,
         objects: jsonRecords,
         batchSize: 1000,
       })
@@ -189,7 +191,7 @@ let main = async () => {
       // 5. Configure index settings
       Console.log("[search-index] Updating index settings...")
       let _ = await client->Algolia.setSettings({
-        indexName: idx,
+        indexName,
         indexSettings: {
           searchableAttributes: [
             "hierarchy.lvl0",
@@ -213,10 +215,10 @@ let main = async () => {
 
       Console.log("[search-index] Done.")
     }
-  | (None, _, _) => Console.log("[search-index] ALGOLIA_APP_ID not set, skipping index upload.")
-  | (_, None, _) =>
-    Console.log("[search-index] ALGOLIA_ADMIN_API_KEY not set, skipping index upload.")
-  | (_, _, None) => Console.log("[search-index] ALGOLIA_INDEX_NAME not set, skipping index upload.")
+  | None =>
+    AlgoliaConfig.missingPublisherVars(~appId, ~indexName, ~adminApiKey)->Array.forEach(name => {
+      Console.log(`[search-index] ${name} not set, skipping index upload.`)
+    })
   }
 }