🚚 forward port www from v3 -> v4

.github/workflows/www.yaml

@@ -0,0 +1,66 @@
+name: www
+on:
+  workflow_dispatch: # Allows manual trigger
+  schedule:
+    - cron: "0 */8 * * *" # Runs every 8 hours
+  pull_request:
+  push:
+    branches:
+      - v4
+
+jobs:
+  www:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    permissions:
+      id-token: write # Needed for auth with Deno Deploy
+      contents: read # Needed to clone the repository
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Deno
+        uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+
+      - name: Serve Website
+        run: |
+          deno task dev &
+          until curl --output /dev/null --silent --head --fail http://127.0.0.1:8000; do
+            printf '.'
+            sleep 1
+          done
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          JSR_API: ${{ secrets.JSR_API }}
+        timeout-minutes: 5
+        working-directory: ./www
+
+      - name: Download Staticalize
+        run: |
+          wget https://github.com/thefrontside/staticalize/releases/download/v0.2.2/staticalize-linux.tar.gz \
+            -O /tmp/staticalize-linux.tar.gz
+          tar -xzf /tmp/staticalize-linux.tar.gz -C /usr/local/bin
+          chmod +x /usr/local/bin/staticalize-linux
+
+      - name: Staticalize
+        run: |
+          staticalize-linux \
+            --site=http://127.0.0.1:8000 \
+            --output=www/built \
+            --base=https://effection-www.deno.dev/
+
+      - run: npx pagefind --site built
+        working-directory: ./www
+
+      - name: Upload to Deno Deploy
+        uses: denoland/deployctl@v1
+        with:
+          project: effection
+          entrypoint: "jsr:@std/http/file-server"
+          root: www/built

.gitignore

@@ -3,4 +3,5 @@
 
 # Local Netlify folder
 .netlify
-/build/
+/build/
+/node_modules/

deno.json

@@ -23,7 +23,12 @@
     "ts-expect": "npm:[email protected]",
     "@std/expect": "jsr:@std/expect@1",
     "ctrlc-windows": "npm:[email protected]",
-    "tinyexec": "npm:[email protected]"
+    "tinyexec": "npm:[email protected]",
+    "https://deno.land/x/[email protected]/index.ts": "npm:[email protected]"
   },
+  "nodeModulesDir": "auto",
+  "workspace": [
+    "./www"
+  ],
   "version": "4.0.0-alpha.9"
 }

lib/main.ts

@@ -180,6 +180,7 @@ function* withHost<T>(op: HostOperation<T>): Operation<T> {
     // @see https://github.com/iliakan/detect-node/blob/master/index.js
   } else if (
     Object.prototype.toString.call(
+      // @ts-expect-error we are just detecting the possibility, so type strictness not required
       typeof globalThis.process !== "undefined" ? globalThis.process : 0,
     ) === "[object process]"
   ) {

tasks/built-test.ts

@@ -15,6 +15,7 @@ await build({
     deno: true,
   },
   test: true,
+  testPattern: "test/**/*.test.ts",
   typeCheck: false,
   scriptModule: false,
   esModule: true,

www/.gitignore

@@ -0,0 +1,5 @@
+/node_modules
+pagefind
+build
+built
+tailwind

www/README.md

@@ -0,0 +1,110 @@
+## Effection Website
+
+The Effection website shows documentation and packages that it pulls from GIT
+repositories on GitHub.
+
+## About Git Integration
+
+The Effection website uses sophisticated GitHub integration to dynamically load
+and display documentation and packages from Effection repositories. This
+integration works through multiple layers:
+
+### Repository Access
+
+- **Dual Provider System**: Uses both Git commands (`git-provider.ts`) and
+  GitHub's Octokit API (`octokit-provider.ts`) for redundant access to
+  repository data
+- **Dynamic Remote Management**: Automatically adds and fetches GitHub remotes
+  for repositories, enabling access to branches, tags, and file contents
+- **Branch & Tag Detection**: Intelligently determines whether references are
+  branches or tags and normalizes them to proper Git reference formats
+
+### Documentation Loading
+
+- **Guides**: Pulls structured documentation from `docs/structure.json` and
+  loads MDX files from the `docs/` directory in the
+  [**thefrontside/effection**](https://github.com/thefrontside/effection)
+  repository
+- **API Documentation**: Generates API documentation using Deno's documentation
+  generator from TypeScript source files in the
+  [**thefrontside/effection**](https://github.com/thefrontside/effection)
+  repository (supports both v3 and v4 via tags like `effection-v3.*` and
+  `effection-v4.*`)
+- **README Integration**: Loads and renders README.md files from package
+  directories using MDX processing
+
+### Package Discovery
+
+- **Workspace Integration**: Reads `deno.json` files to discover packages and
+  their configurations within:
+  - [**thefrontside/effection**](https://github.com/thefrontside/effection) -
+    Core Effection library packages
+  - [**thefrontside/effectionx**](https://github.com/thefrontside/effectionx) -
+    Extended Effection ecosystem packages
+- **Multi-Version Support**: Handles different versions of packages by working
+  with Git tags and branches from both repositories
+- **Export Mapping**: Maps package exports to their corresponding source files
+  for direct GitHub links
+
+### Dynamic Content
+
+- **Live Repository Data**: Fetches star counts, default branches, and
+  repository metadata directly from GitHub
+- **Content Versioning**: Supports loading content from specific Git references
+  (branches, tags, commits)
+- **Badge Integration**: Generates badges for JSR packages, npm packages, bundle
+  sizes, and other metrics
+
+This integration ensures that the website always reflects the current state of
+the Effection ecosystem by pulling data directly from the source repositories on
+GitHub.
+
+## Deployment
+
+The website is deployed to Deno Deploy using a static site generation process
+powered by the [Staticalize](https://github.com/thefrontside/staticalize)
+utility:
+
+### Automated Deployment Process
+
+- **Trigger**: Runs automatically every 8 hours via scheduled GitHub Action, on
+  pushes to `main` branch, and can be manually triggered
+- **Static Generation**: The live website is crawled and converted to static
+  files using Staticalize
+- **Search Integration**: Pagefind indexes the static content to enable
+  client-side search functionality
+- **Deno Deploy**: Static files are uploaded to
+  [Deno Deploy](https://deno.com/deploy) and served via their edge network
+
+### Deployment Pipeline
+
+1. **Server Startup**: Spins up the dynamic website locally using
+   `deno task dev`
+2. **Content Crawling**: Staticalize crawls `http://127.0.0.1:8000` to generate
+   static HTML/CSS/JS
+3. **Search Indexing**: Pagefind processes the static files to create search
+   indexes
+4. **Upload**: Deploys the built static site to the `effection-www` project on
+   Deno Deploy
+
+This ensures the website stays current with repository changes while providing
+fast global delivery through static hosting.
+
+## Troubleshooting
+
+### "Bad credentials" Error from GitHub API
+
+If you encounter an `HttpError: Bad credentials` error when running the website:
+
+1. **Verify your GITHUB_TOKEN**: Ensure the `GITHUB_TOKEN` environment variable
+   is set with a valid GitHub personal access token
+2. **Clear the cache**: Old cached data may contain requests made with an
+   expired or invalid token. Run the clear-cache task:
+   ```bash
+   deno task clear-cache
+   ```
+3. **Restart the server**: After clearing the cache, restart the development
+   server
+
+This error typically occurs when the cache contains authenticated requests from
+a previous token that is no longer valid.