Bring back the website into the Effection repo (#1040)

We brought it out because of tooling concerns. We're bringing it back
in because it makes it so much easier to work on

Co-authored-by: Taras Mankovski <[email protected]>

Author: cowboyd

.gitattributes

@@ -3,12 +3,16 @@
 
 # Explicitly set line endings for text files
 *.ts text eol=lf
+*.tsx text eol=lf
 *.mjs text eol=lf
 *.js text eol=lf
 *.json text eol=lf
 *.md text eol=lf
 *.yml text eol=lf
 *.yaml text eol=lf
+*.css text eol=lf
+*.svg text eol=lf
+*.html text eol=lf
 
 # Binary files
 *.png binary

.github/workflows/verify.yaml

@@ -2,9 +2,11 @@ name: Verify
 
 on:
   push:
-    branches: v[3-9]
+    branches:
+      - v[3-9]
   pull_request:
-    branches: v[3-9]
+    branches:
+      - v[3-9]
 
 permissions:
   contents: read
@@ -40,7 +42,7 @@ jobs:
 
       - name: test (Windows)
         if: runner.os == 'Windows'
-        run: deno task test
+        run: deno test --allow-run --allow-write --allow-read --allow-env --allow-ffi --ignore=www
         shell: cmd
 
       - name: test (Unix)

.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:
+      - tm/import-www
+
+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

@@ -7,7 +7,7 @@
   },
   "lock": false,
   "tasks": {
-    "test": "deno test --allow-run --allow-ffi",
+    "test": "deno test --allow-run --allow-write --allow-read --allow-env --allow-ffi",
     "test:node": "deno task build:npm 0.0.0 && node test/main/node.mjs hello world",
     "build:jsr": "deno run -A tasks/build-jsr.ts",
     "build:npm": "deno run -A tasks/build-npm.ts"
@@ -19,16 +19,15 @@
     "exclude": [
       "build",
       "website",
-      "www",
-      "packages",
-      "docs/*.ts"
+      "www/build",
+      "packages"
     ]
   },
   "fmt": {
     "exclude": [
       "build",
       "website",
-      "www",
+      "www/build",
       "packages",
       "CODE_OF_CONDUCT.md",
       "README.md"
@@ -48,11 +47,26 @@
       "dom.iterable"
     ]
   },
+  "deploy": {
+    "org": "Frontside",
+    "project": "effection-www",
+    "entrypoint": "https://jsr.io/@std/http/1.0.20/file_server.ts",
+    "root": "./www"
+  },
+  "nodeModulesDir": "auto",
+  "workspace": [
+    "./www"
+  ],
   "imports": {
-    "@deno/dnt": "jsr:@deno/[email protected]",
-    "ctrlc-windows": "npm:[email protected]",
-    "@std/testing": "jsr:@std/testing@^1",
+    "https://deno.land/x/[email protected]/index.ts": "npm:[email protected]",
+    "@std/path/posix/basename": "jsr:@std/path@1/posix/basename",
+    "remark-gfm": "npm:[email protected]",
+    "rehype-prism-plus": "npm:[email protected]",
+    "@mdx-js/mdx": "npm:@mdx-js/[email protected]",
+    "@std/testing/bdd": "jsr:@std/testing@^1/bdd",
     "@std/expect": "jsr:@std/expect@^1",
-    "ts-expect": "npm:[email protected]"
+    "ts-expect": "npm:[email protected]",
+    "ctrlc-windows": "npm:[email protected]",
+    "@deno/dnt": "jsr:@deno/[email protected]"
   }
 }

docs/docs.ts

@@ -8,12 +8,12 @@ import {
 } from "effection";
 import structure from "./structure.json" with { type: "json" };
 
-import { basename } from "https://deno.land/[email protected]/path/posix/basename.ts";
+import { basename } from "@std/path/posix/basename";
 
-import remarkGfm from "npm:remark-gfm@3.0.1";
-import rehypePrismPlus from "npm:rehype-prism-plus@1.5.1";
+import remarkGfm from "remark-gfm";
+import rehypePrismPlus from "rehype-prism-plus";
 
-import { evaluate } from "npm:@mdx-js/mdx@2.3.0";
+import { evaluate } from "@mdx-js/mdx";
 
 import { Fragment, jsx, jsxs } from "revolution/jsx-runtime";
 

lib/main.ts

@@ -175,7 +175,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(
-      typeof globalThis.process !== "undefined" ? globalThis.process : 0,
+      typeof global.process !== "undefined" ? global.process : 0,
     ) === "[object process]"
   ) {
     return yield* op.node();

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.