docs: tweak the redirect implementation in webpage

[snipsnipsnip]

Some refactoring.

• As for the webpage, I've noticed that we can implement a redirect without
  enabling the $docsify.executeScript option.
• As for the options page, I added a top-level await for the floating
  promise, even though it is not expected to resolve.

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

Release Notes

• New Features

  • Added License file redirect support in documentation
  • Improved redirect detection with better error handling

• Bug Fixes

  • Enhanced URL encoding security for resource redirects

• Chores

  • Strengthened documentation configuration for improved security

Walkthrough

This PR refactors the documentation site's redirect mechanism from script-based to JSON-based, adds a new tryRedirect utility to parse and execute redirects, updates URL encoding for resource types, consolidates imports for options initialization, and converts the main options startup flow from Promise chains to async/await.

Changes

Cohort / File(s)	Summary
Documentation Site Redirect Logic .github/site/index.mjs	Enhanced URL encoding by including resource type in encodeURIComponent, refactored redirect mechanism to return JSON strings instead of inline scripts, added tryRedirect(text) utility to parse and execute JSON redirects, disabled executeScript in docsify config, added route handler for '/LICENSE', and integrated tryRedirect into beforeEach hook.
Options Event Router Type Update src/app-options/options_event_router.ts	Updated initOptions() return type from Promise<void> to Promise<never>.
Root Options Initialization Refactor src/root/options.ts	Consolidated imports to use central "src/app-options" module, converted Promise-chain-based initialization to async/await pattern with new runRouterAsync() function, upgraded logging from console.log to console.info, and introduced explicit mainPromise for lifecycle management.

Sequence Diagram

sequenceDiagram
    actor User
    participant Browser
    participant Site as index.mjs
    participant Router as OptionsEventRouter
    participant Element as GhostbirdOptionsElement

    rect rgb(200, 220, 255)
    note over Site: Old: Script-based redirect
    User->>Browser: Click link with redirectTo
    Browser->>Site: beforeEach processes HTML script
    Site->>Browser: Execute inline script
    Browser->>Browser: location.replace() after script execution
    end

    rect rgb(220, 255, 220)
    note over Site: New: JSON-based redirect
    User->>Browser: Click link with redirectTo
    Browser->>Site: beforeEach invokes tryRedirect(text)
    Site->>Site: Parse JSON {"redirectTo": url}
    Site->>Browser: location.replace(url) immediately
    Browser->>Browser: Navigate to new location
    end

    rect rgb(255, 240, 200)
    note over Router: Old: Promise.then() pattern
    Element->>Router: Custom element defined
    Router->>Router: .then(e => initOptions(e))
    end

    rect rgb(255, 220, 220)
    note over Router: New: async/await pattern
    Element->>Router: Custom element defined
    Router->>Router: await runRouterAsync()
    Router->>Router: await router.initOptions(element)
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

The changes span three files with mixed complexity: straightforward type annotation updates, URL encoding logic modifications, and a moderate async/await refactoring pattern. The JSON-based redirect mechanism introduces new parsing logic that requires verification, while the options initialization consolidation follows a standard pattern conversion from callbacks to async/await.

Possibly related PRs

• Tweak the webpage #45: Modifies docsify routes and hook.beforeEach pipeline for redirect behavior, overlapping with the route handler and plugin integration changes in this PR.
• chore: bump tools version and update the webpage #47: Updates urlFor, redirectTo, and route handlers in the site builder, directly related to the redirect and URL encoding modifications here.

Poem

🐰 Redirects now dance in JSON's gentle grace,
No scripts needed—just a cleaner place.
Async/await replaces promise chains,
Type-safe options flow through the veins.
URL-encoded types, redirects so neat,
This refactor makes the code complete! ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description Check	⚠️ Warning	The pull request description significantly deviates from the required template. While the author provides some context about the refactoring changes (webpage redirect implementation and top-level await for options page), the description is missing multiple required sections including the dual-licensing agreement checkbox, the "What is the current behavior?" section referencing an issue, the "What is the new behavior?" section with detailed explanation, the manual testing steps section, and the "Anything else?" section. The description lacks the structured format and critical information specified in the template, particularly the step-by-step testing instructions and the licensing agreement confirmation.	The author should update the pull request description to follow the required template structure. Specifically, they should include the dual-licensing agreement checkbox, add a detailed "What is the current behavior?" section referencing the relevant issue, provide a comprehensive "What is the new behavior?" section, include clear step-by-step manual testing instructions, and complete the "Anything else?" section as needed. This will ensure proper documentation and traceability for the refactoring changes.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title "docs: tweak the redirect implementation in webpage" directly corresponds to the main changes in .github/site/index.mjs, which implement a redirect system without the $docsify.executeScript option. While the PR also includes refactoring changes to the options page code (files in src/app-options/ and src/root/), the webpage redirect implementation appears to be the more substantial change with multiple functional modifications. The title clearly communicates the primary change and allows a teammate to understand the focus of the PR.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 10.00000% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 46.93%. Comparing base (4884a84) to head (9e8b215).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

Components	Coverage Δ
app	32.47% <100.00%> (ø)
ghosttext	49.18% <ø> (ø)
infra	43.88% <0.00%> (-0.12%)	⬇️

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/root/options.ts (1)

7-26: LGTM: Improved readability with async/await.

The refactoring from Promise chains to async/await significantly improves code readability while maintaining equivalent functionality.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 4884a84 and 9e8b215.

📒 Files selected for processing (3)

• .github/site/index.mjs (4 hunks)
• src/app-options/options_event_router.ts (1 hunks)
• src/root/options.ts (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (2)

src/app-options/options_event_router.ts (1)

src/app-options/ghostbird_options_element.ts (1)

• GhostbirdOptionsElement (3-53)

src/root/options.ts (3)

src/app-options/options_event_router.ts (1)

• OptionsEventRouter (3-11)

src/root/startup/startup_options.ts (1)

• startupOptions (18-19)

src/app-options/ghostbird_options_element.ts (1)

• GhostbirdOptionsElement (3-53)

🔇 Additional comments (8)

.github/site/index.mjs (4)

14-14: LGTM: Defensive encoding of resource type.

Encoding the type parameter is a safe defensive practice, even though 'blob' and 'tree' don't require encoding.

---

67-67: LGTM: Security improvement by disabling script execution.

Changing executeScript to false prevents arbitrary script execution in markdown content, which is a valuable security hardening measure.

---

77-77: LGTM: LICENSE route addition.

The new route handles the LICENSE file consistently with other file routes.

---

102-102: LGTM: Correct hook placement for redirect handling.

The tryRedirect hook is correctly positioned as the first beforeEach hook to intercept redirect instructions before other processing occurs.

src/app-options/options_event_router.ts (1)

8-10: LGTM: Accurate type reflects non-resolving promise.

The return type Promise<never> correctly reflects that startSync contains an infinite loop and never resolves normally.

src/root/options.ts (3)

3-3: LGTM: Consolidated imports.

The import consolidation from a central "src/app-options" module improves maintainability.

---

28-28: LGTM: More semantic logging level.

Using console.info for startup messages is more semantically appropriate than console.log.

Also applies to: 34-34

---

30-30: Intentional non-resolving await at module level.

The top-level await mainPromise waits on a Promise<never> that runs an infinite event loop, meaning this module never completes loading. This is acceptable for an entrypoint script but would cause issues if this module were ever dynamically imported elsewhere.

Per the PR description, this design is intentional.

Also applies to: 36-36