Add background fetch support for run code

Author: Oscar

openspec/changes/add-run-code-background-fetch/design.md

@@ -0,0 +1,36 @@
+## Context
+Nenya already separates automatic Custom JS/CSS page-load injection from manual Run Code execution. Automatic rules intentionally stay on the legacy MAIN-world path so existing page-load behavior does not change, while manual Run Code executes through `chrome.userScripts.execute()` to avoid host-page CSP issues. The new request is to let manual snippets perform cross-origin requests through the extension background so they are not limited by the page origin's CORS rules.
+
+## Goals / Non-Goals
+- Goals:
+  - Provide a simple helper callable directly from manual Run Code snippets.
+  - Perform network requests from the extension background using existing host permissions.
+  - Preserve the current separation between manual Run Code and automatic Custom JS/CSS.
+- Non-Goals:
+  - Do not change automatic page-load Custom JS/CSS execution.
+  - Do not emulate the full browser `Response` prototype.
+  - Do not add a generic fetch bridge for arbitrary content scripts outside the manual Run Code flow.
+
+## Decisions
+- Decision: Inject a helper into the manual Run Code wrapper rather than requiring each user snippet to hand-roll message passing.
+  - Rationale: The feature is specifically for manual snippets, so the wrapper is the narrowest place to expose it.
+- Decision: Route messages through the dedicated user-script messaging channel.
+  - Rationale: Chrome's userScripts API treats user-script messaging as a separate, less-trusted context, so background handlers should distinguish it from ordinary extension messages.
+- Decision: Return a serializable response wrapper with `ok`, `status`, `statusText`, `url`, `redirected`, `headers`, `text()`, and `json()`.
+  - Rationale: Most snippets only need these fields and readers. Returning the full native `Response` object is not possible across extension messaging boundaries.
+- Decision: Validate the requested URL and restrict supported init fields to an explicit allowlist.
+  - Rationale: Even though manual Run Code is user-authored, the background should avoid becoming an unconstrained proxy surface.
+
+## Risks / Trade-offs
+- Cookie-backed auth may still fail if the target origin does not have the expected browser session or if the browser blocks the relevant cookies.
+- The helper will look fetch-like, but it cannot be behavior-identical to the native `fetch()` and `Response` APIs because the result crosses a messaging boundary.
+- Streaming bodies are out of scope, so large responses are buffered before being returned.
+
+## Migration Plan
+1. Add the OpenSpec delta and validate it.
+2. Update the manual Run Code wrapper to expose the helper.
+3. Add background handlers for user-script messages and request execution.
+4. Verify that automatic Custom JS/CSS still uses the legacy path unchanged.
+
+## Open Questions
+- The helper name should be short and obvious in snippets. `nenyaFetch` is the current default unless product copy prefers another name.

openspec/changes/add-run-code-background-fetch/proposal.md

@@ -0,0 +1,14 @@
+# Change: add background-backed fetch for manual Run Code
+
+## Why
+Manual "Run Code in page" snippets currently execute in the page's browser context, so direct `fetch()` calls from sites like `https://x.com` still hit normal web CORS restrictions. Users need a supported way to make authenticated cross-origin requests from manual snippets without rewriting each script around extension internals.
+
+## What Changes
+- Add a background-backed fetch helper that is available to manual Run Code snippets.
+- Keep the helper scoped to user-triggered manual Run Code, not automatic Custom JS/CSS page-load rules.
+- Define the request and response contract, including support for URL, method, headers, body, and credential mode passthrough.
+- Return response status, headers, final URL, and body readers in a snippet-friendly shape so user code can work with the result similarly to `fetch()`.
+
+## Impact
+- Affected specs: `custom-js-css`
+- Affected code: `src/background/index.js`, manual Run Code wrapper generation, and any related options or popup surfaces that document or trigger Run Code

openspec/changes/add-run-code-background-fetch/specs/custom-js-css/spec.md

@@ -0,0 +1,23 @@
+## MODIFIED Requirements
+### Requirement: The background service SHALL execute custom JavaScript payloads securely
+The background service SHALL keep automatic Custom JS/CSS page-load injection on the legacy MAIN-world execution path, and it SHALL provide a background-backed fetch helper only to manual, user-triggered Run Code snippets executed through the user-scripts path.
+
+#### Scenario: Execute JS on behalf of the content script
+- **GIVEN** the content script requests `{ type: 'INJECT_CUSTOM_JS', ruleId, code }`,
+- **THEN** the background service worker MUST verify `sender.tab.id` exists and `code` is non-empty, call `chrome.scripting.executeScript()` with the MAIN-world eval path, and reply `{ success: true }`,
+- **AND** host-page CSP MAY block this automatic custom-code path on pages that disallow eval, so stored rules do not gain new page-load execution privileges unexpectedly,
+- **AND** errors (invalid tab, injection failure, runtime exceptions) MUST be caught and responded to with `{ success: false, error }` so the caller can log and avoid retry storms.
+
+#### Scenario: Manual Run Code receives a background-backed fetch helper
+- **GIVEN** the user manually runs a "Run Code in page" snippet,
+- **WHEN** the background builds the user-script wrapper,
+- **THEN** it MUST expose a fetch-like helper to the snippet that sends the request through the extension background instead of the page origin,
+- **AND** the helper MUST only be available to manual Run Code snippets, not automatic page-load Custom JS/CSS rules.
+
+#### Scenario: Background-backed fetch executes with explicit validation
+- **GIVEN** a manual Run Code snippet calls the helper with a URL and optional init object,
+- **WHEN** the request reaches the background through the user-script messaging channel,
+- **THEN** the background MUST validate that the URL is absolute and that only supported request fields are honored,
+- **AND** it MUST perform the network request from the extension origin so matching host permissions can bypass page-origin CORS limits,
+- **AND** it MUST return a serializable response object that includes `ok`, `status`, `statusText`, `url`, `redirected`, `headers`, plus body readers that allow the snippet to call `text()` or `json()` on the returned value,
+- **AND** request failures or response-body parse failures MUST reject the snippet call with a descriptive error instead of silently returning an unusable result.

openspec/changes/add-run-code-background-fetch/tasks.md

@@ -0,0 +1,12 @@
+## 1. Specification
+- [x] 1.1 Add an OpenSpec delta for background-backed fetch in manual Run Code.
+- [x] 1.2 Validate the OpenSpec change.
+
+## 2. Implementation
+- [x] 2.1 Add a manual Run Code helper that exposes background-backed fetch to user snippets.
+- [x] 2.2 Add background request handling that validates and performs the fetch with the extension origin.
+- [x] 2.3 Serialize the response into a snippet-friendly shape without changing automatic Custom JS/CSS injection behavior.
+
+## 3. Verification
+- [x] 3.1 Run OpenSpec validation and syntax checks for touched scripts.
+- [x] 3.2 Manually review the final diff for helper scope, request validation, and response serialization.