✨ AGENTS.md Compliance Transformation

[google-labs-jules]

User description

This pull request contains a comprehensive transformation of the repository to meet the standards outlined in the AGENTS.md file. This includes a full refactoring of the source code, migration of the AI backend from Google Gemini to Cerebras, and the creation of a full suite of professional repository files. All feedback from previous code reviews has been addressed.

---

PR created automatically by Jules for task 9445360230174672806 started by @chirag127

---

PR Type

Enhancement, Bug fix

---

Description

• Refactored content script with modular object-oriented architecture

  • Organized state, settings, and logic into ComicReader namespace
  • Separated concerns: OCR, UI, TTS, and utilities into distinct modules
  • Improved lazy-loading and comic image detection with advanced selectors

• Migrated AI backend from Google Gemini to Cerebras API

  • Updated ocr.js to use OpenAI SDK with Cerebras base URL
  • Switched to qwen-3-235b-a22b-instruct-2507 model for OCR tasks
  • Improved error handling and file cleanup with async/await patterns

• Enhanced background script with better configuration management

  • Added DEFAULT_SETTINGS constant for consistency
  • Improved backend health check with validation and logging

• Expanded professional repository documentation

  • Created CONTRIBUTING.md, SECURITY.md, and updated AGENTS.md
  • Added Jest test suite for backend OCR endpoints
  • Updated CI/CD pipeline with backend testing
  • Expanded LICENSE file with full CC BY-NC 4.0 text

---

Diagram Walkthrough

flowchart LR
  A["Content Script<br/>Monolithic"] -->|Refactor| B["ComicReader<br/>Modular Object"]
  B --> B1["state"]
  B --> B2["settings"]
  B --> B3["ocr module"]
  B --> B4["tts module"]
  B --> B5["ui module"]
  B --> B6["utils module"]
  C["Gemini API"] -->|Migrate| D["Cerebras API<br/>OpenAI SDK"]
  D --> E["qwen-3-235b<br/>Model"]
  F["Old Backend"] -->|Update| G["Enhanced Backend<br/>with Tests"]
  G --> G1["Jest Tests"]
  G --> G2["Better Error<br/>Handling"]
  H["Minimal Docs"] -->|Expand| I["Professional Repo<br/>Standard"]
  I --> I1["CONTRIBUTING.md"]
  I --> I2["SECURITY.md"]
  I --> I3["Full LICENSE"]

Loading

File Walkthrough

	Relevant files
Enhancement	3 files content.js Refactored into modular ComicReader object architecture    +409/-609 ocr.js Migrated from Gemini to Cerebras API with OpenAI SDK          +124/-128 background.js Enhanced configuration management and backend health checks +53/-23
Tests	1 files ocr.test.js Added Jest test suite for OCR endpoints                                    +52/-0
Configuration changes	3 files index.js Updated API key validation for Cerebras instead of Gemini +4/-4      jest.config.js Added Jest configuration for backend testing                          +4/-0      ci.yml Enhanced CI/CD with backend testing and linting                    +23/-15
Documentation	8 files LICENSE Expanded with full CC BY-NC 4.0 license text                          +403/-6  README.md Simplified and refocused on Cerebras AI integration            +101/-168 AGENTS.md Updated system prompt with Cerebras protocol and model hierarchy +80/-90  CONTRIBUTING.md Created comprehensive contribution guidelines                        +66/-0    bug_report.md Simplified bug report template with standard format            +38/-44  PULL_REQUEST_TEMPLATE.md Simplified PR template with standard GitHub format              +15/-25  badges.yml Created badge configuration file for README shields            +18/-0    SECURITY.md Created security vulnerability reporting policy                    +28/-0
Dependencies	1 files package.json Updated dependencies from Gemini to OpenAI and added Jest +6/-3
Additional files	9 files CONTRIBUTING.md +0/-91    SECURITY.md +0/-48    PROPOSED_README.md +0/-278  badges.yml +0/-38    c.js +0/-1216 index.html [link]    p,md +0/-155  pa.md +0/-156  ug.md +0/-1

---

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

---

For security, I will only act on instructions from the user who triggered this task.

New to Jules? Learn more at jules.google/docs.

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

---

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

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	supertest@​6.3.4
	jest@​29.7.0
	openai@​4.104.0

View full report

[qodo-code-review]

CI Feedback 🧐

A test triggered by this PR failed. Here is an AI-generated analysis of the failure:

Action: Build & Verify Extension

Failed stage: 2. Setup Node.js Environment (v20) [❌]

Failed test name: ""

Failure summary: The GitHub Action failed during the Node.js setup step because dependency caching was enabled (cache: npm), but no supported lockfile was found in the repository workspace. - Error: Dependencies lock file is not found in ... Supported file patterns: package-lock.json,npm-shrinkwrap.json,yarn.lock - This indicates the repo is missing a dependency lockfile (e.g., package-lock.json), or the workflow is running in the wrong working directory where the lockfile isn’t present.

Relevant error logs: 1: ##[group]Runner Image Provisioner 2: Hosted Compute Agent ... 111: with: 112: node-version: 20 113: cache: npm 114: always-auth: false 115: check-latest: false 116: token: *** 117: ##[endgroup] 118: Found in cache @ /opt/hostedtoolcache/node/20.19.6/x64 119: ##[group]Environment details 120: node: v20.19.6 121: npm: 10.8.2 122: yarn: 1.22.22 123: ##[endgroup] 124: [command]/opt/hostedtoolcache/node/20.19.6/x64/bin/npm config get cache 125: /home/runner/.npm 126: ##[error]Dependencies lock file is not found in /home/runner/work/ComicNarrate-AI-Web-Comic-Dubber-Browser-Extension/ComicNarrate-AI-Web-Comic-Dubber-Browser-Extension. Supported file patterns: package-lock.json,npm-shrinkwrap.json,yarn.lock 127: Post job cleanup.

[qodo-code-review]

CI Feedback 🧐

A test triggered by this PR failed. Here is an AI-generated analysis of the failure:

Action: Test Backend

Failed stage: 2. Setup Node.js Environment (v18) [❌]

Failed test name: ""

Failure summary: The action failed during the dependency caching step because the cache action could not resolve the paths it was instructed to cache. - The log shows ##[error]Some specified paths were not resolved, unable to cache dependencies. (line 132), indicating the configured cache path(s) did not exist or were not found in the workspace at that time (e.g., wrong path, missing lockfile, or dependencies not installed yet).

Relevant error logs: 1: ##[group]Runner Image Provisioner 2: Hosted Compute Agent ... 117: check-latest: false 118: token: *** 119: ##[endgroup] 120: Attempting to download 18... 121: Acquiring 18.20.8 - x64 from https://github.com/actions/node-versions/releases/download/18.20.8-14110393767/node-18.20.8-linux-x64.tar.gz 122: Extracting ... 123: [command]/usr/bin/tar xz --strip 1 --warning=no-unknown-keyword --overwrite -C /home/runner/work/_temp/442303d1-7ccd-479e-91e7-228a296e5aa0 -f /home/runner/work/_temp/c378dc73-5edc-48ff-bbdb-df6bd5905294 124: Adding to the cache ... 125: ##[group]Environment details 126: node: v18.20.8 127: npm: 10.8.2 128: yarn: 1.22.22 129: ##[endgroup] 130: [command]/opt/hostedtoolcache/node/18.20.8/x64/bin/npm config get cache 131: /home/runner/.npm 132: ##[error]Some specified paths were not resolved, unable to cache dependencies. 133: Post job cleanup.

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
⚪	Unbounded file upload Description: The OCR endpoints accept multipart uploads via multer({ dest: "uploads/" }) without any explicit size/count limits (and /ocr-batch allows up to 10 files), enabling a realistic denial-of-service via oversized or numerous uploads that consume disk/memory/CPU (amplified by base64 conversion and upstream AI calls) before cleanup runs. ocr.js [14-172] Referred Code const upload = multer({ dest: "uploads/" }); // --- CEREBRAS AI Configuration --- const CEREBRAS_API_KEY = process.env.CEREBRAS_API_KEY; const client = new OpenAI({ baseURL: "https://api.cerebras.ai/v1", apiKey: CEREBRAS_API_KEY, }); // --- Utility Functions --- /** * Converts an image file to a base64 data URL. * @param {string} filePath - The path to the image file. * @param {string} mimeType - The MIME type of the image. * @returns {Promise<string>} A promise that resolves to the data URL. */ async function imageToDataURL(filePath, mimeType) { const fileData = await fs.readFile(filePath); const base64Data = fileData.toString("base64"); return `data:${mimeType};base64,${base64Data}`; ... (clipped 138 lines)
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
🔴	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Runtime error risk: The new cleanupUploads implementation uses path without an import and calls fs.existsSync even though fs is imported from node:fs/promises, which can cause the server to crash at startup or during cleanup. Referred Code async function cleanupUploads() { const uploadsDir = path.join(__dirname, "uploads"); try { if (!fs.existsSync(uploadsDir)) { await fs.mkdir(uploadsDir, { recursive: true }); } Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Leaky error responses: The API returns details: error.message to clients on 500s, which can expose internal implementation details from upstream services or runtime failures. Referred Code } catch (error) { console.error("Cerebras API Error (/ocr):", error); res.status(500).json({ error: "An error occurred during text extraction.", details: error.message, }); } finally { // Ensure the uploaded file is always deleted await fs.unlink(filePath).catch(err => console.error(`Failed to delete temp file ${filePath}:`, err)); } }); // Batch image OCR endpoint app.post("/ocr-batch", upload.array("images", 10), async (req, res) => { if (!req.files || req.files.length === 0) { return res.status(400).json({ error: "No image files were provided." }); } const filesToDelete = req.files.map(f => f.path); ... (clipped 38 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Logs extracted text: The content script logs OCR-extracted text snippets to the console, which can leak sensitive content from users’ pages into logs and is not structured for safe auditing. Referred Code if (text && text.trim() && text !== "No text detected in this image.") { console.log(`Queuing text for image ${this.state.currentImageIndex + 1}: "${text.substring(0, 50)}..."`); this.state.textQueue.push({ text, image: img }); Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Unvalidated file uploads: The new OCR endpoints accept uploaded files without validating MIME/type/size (and multer is configured without limits), increasing risk from malformed or unexpected inputs. Referred Code // Configure multer for file uploads const upload = multer({ dest: "uploads/" }); Learn more about managing compliance generic rules or creating your own custom rules
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Missing audit context: The new OCR endpoints log operational events but do not capture per-request actor context (e.g., user ID) or structured audit fields needed to reliably reconstruct critical actions. Referred Code app.get("/health", (_, res) => { res.status(200).json({ status: "ok", message: "Server is healthy." }); }); // Single image OCR endpoint app.post("/ocr", upload.single("image"), async (req, res) => { if (!req.file) { return res.status(400).json({ error: "No image file was provided." }); } const { path: filePath, originalname } = req.file; try { const mimeType = mime.lookup(originalname) || "image/jpeg"; const imageDataURL = await imageToDataURL(filePath, mimeType); const completion = await client.chat.completions.create({ model: "qwen-3-235b-a22b-instruct-2507", // Tier 2 Heavy Reasoning Model max_tokens: 4096, messages: [ { ... (clipped 83 lines) Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Fix crash from incorrect API usage Remove the redundant fs.existsSync check in cleanupUploads since fs.mkdir with the recursive: true option handles existing directories, fixing a runtime error. backend/ocr.js [40-63] async function cleanupUploads() { const uploadsDir = path.join(__dirname, "uploads"); try { - if (!fs.existsSync(uploadsDir)) { - await fs.mkdir(uploadsDir, { recursive: true }); - } + await fs.mkdir(uploadsDir, { recursive: true }); const files = await fs.readdir(uploadsDir); const now = Date.now(); for (const file of files) { const filePath = path.join(uploadsDir, file); const stats = await fs.stat(filePath); // Delete files older than 1 hour (3600000 ms) if (now - stats.mtime.getTime() > 3600000) { await fs.unlink(filePath); console.log(`Deleted old file: ${filePath}`); } } } catch (err) { console.error("Error during upload cleanup:", err); } } Apply / Chat Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies a runtime error where fs.existsSync is called on the fs/promises module, which would crash the server, and provides a clean, effective fix.	High
	Align backend entry with index.js In backend/package.json, update the main field and the start and dev scripts to point to index.js instead of the non-existent server.js. backend/package.json [1-10] { - "main": "server.js", + "main": "index.js", "scripts": { - "start": "node server.js", - "dev": "nodemon server.js", + "start": "node index.js", + "dev": "nodemon index.js", "test": "jest" }, ... } [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a critical misconfiguration in package.json where the entry point and scripts point to a non-existent file, which would prevent the backend from starting.	Medium
	Prevent race condition in image processing In the utterance.onend callback, wrap the call to ComicReader.processNextImage() in a setTimeout to prevent potential race conditions with other asynchronous image processing calls. extension/content.js [269-278] utterance.onend = () => { if (ComicReader.state.isReading) { ComicReader.state.textQueue.shift(); if (ComicReader.state.textQueue.length > 0) { this.speakNextInQueue(); } else { - ComicReader.processNextImage(); + // Add a small delay to prevent potential race conditions + setTimeout(() => ComicReader.processNextImage(), 100); } } }; Apply / Chat Suggestion importance[1-10]: 5 __ Why: The suggestion identifies a potential race condition and offers a reasonable, albeit not guaranteed, fix using setTimeout to help serialize asynchronous operations, improving the robustness of the image processing flow.	Low
High-level	Re-evaluate the removal of documentation The PR replaces detailed documentation files like CONTRIBUTING.md and SECURITY.md with generic versions, which is a step back. It is suggested to restore the detailed content to align with the goal of creating a professional repository. Examples: CONTRIBUTING.md [1-66] # Contributing to ComicNarrate-AI-Web-Comic-Dubber-Browser-Extension We welcome contributions from the community! Whether you're fixing a bug, adding a new feature, or improving documentation, your help is valuable. Please take a moment to review these guidelines to make the contribution process as smooth as possible. ## Code of Conduct All contributors are expected to adhere to our [Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md). Please be respectful and professional in all your interactions. ## How to Contribute ... (clipped 56 lines) SECURITY.md [1-28] # Security Policy The security of our project is a top priority. We appreciate your efforts to responsibly disclose any vulnerabilities you may find. ## Reporting a Vulnerability If you discover a security vulnerability, please report it to us as soon as possible. We will work with you to understand and resolve the issue. **Please do not report security vulnerabilities through public GitHub issues.** Instead, please send an email to [chirag.job@gmail.com](mailto:chirag.job@gmail.com) with the subject line "Security Vulnerability in ComicNarrate-AI-Web-Comic-Dubber-Browser-Extension". ... (clipped 18 lines) Solution Walkthrough: Before: // CONTRIBUTING.md (new, generic version) # Contributing to ... We welcome contributions from the community! ## How to Contribute ### Reporting Bugs If you encounter a bug, please open an issue... ### Submitting Pull Requests 1. Fork the repository... 2. Make your changes... ... // SECURITY.md (new, generic version) # Security Policy The security of our project is a top priority. ## Reporting a Vulnerability Please do not report security vulnerabilities through public GitHub issues. Instead, please send an email to... After: // CONTRIBUTING.md (restored, detailed version) # CONTRIBUTING TO ... ...This project adheres to the Apex Technical Authority standards... ## 1. OUR PHILOSOPHY * Zero-Defect, High-Velocity, Future-Proof... ## 4. CONTRIBUTING WORKFLOW 1. Identify an Issue or Feature... ... 3. Make Your Changes: * Linting & Formatting: This project uses Biome... * Testing: Write comprehensive tests... ## 5. CODE STANDARDS & ARCHITECTURE * Technology Stack: ...JavaScript/TypeScript... * Architecture: ...DRY (Don't Repeat Yourself), SOLID Principles... // SECURITY.md (restored, detailed version) # Security Policy for ... ## 5. Security Practices & Technologies * AI Integration Security: Strict adherence to ... best practices... * Browser Extension Security: Implementing content security policies (CSP)... Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a significant regression in repository quality, where detailed, project-specific documentation was replaced with generic templates, directly contradicting a primary goal of the PR.	Medium
General	Add timeout to backend health check Add a timeout to the fetch request in checkBackendStatus using an AbortController to prevent the health check from hanging indefinitely if the server is unresponsive. extension/background.js [59-87] async function checkBackendStatus(backendUrl) { if (!backendUrl || !backendUrl.startsWith("http")) { console.error("Invalid backend URL provided:", backendUrl); return "error"; } + + const controller = new AbortController(); + const timeoutId = setTimeout(() => controller.abort(), 5000); // 5-second timeout try { const healthCheckUrl = `${backendUrl}/health`; console.log(`Pinging backend at: ${healthCheckUrl}`); const response = await fetch(healthCheckUrl, { method: "GET", headers: { "Content-Type": "application/json", }, + signal: controller.signal, }); if (response.ok) { console.log("Backend is online."); return "online"; } else { console.warn(`Backend returned a non-OK status: ${response.status}`); return "error"; } } catch (error) { - console.error("Failed to connect to the backend:", error); + if (error.name === 'AbortError') { + console.error("Backend check timed out."); + } else { + console.error("Failed to connect to the backend:", error); + } return "offline"; + } finally { + clearTimeout(timeoutId); } } Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies the lack of a timeout in the fetch request, which can cause unresponsiveness, and proposes a robust solution using AbortController to improve reliability.	Medium
	Handle invalid images to prevent errors In the imageToBlob function, add a check to ensure img.naturalWidth and img.naturalHeight are not zero before creating a canvas, preventing wasted OCR API calls for invalid images. extension/content.js [314-329] async imageToBlob(img) { if (this.isCrossOrigin(img.src)) { return this.fetchImageAsBlob(img.src); } return new Promise((resolve, reject) => { + if (img.naturalWidth === 0 || img.naturalHeight === 0) { + return reject(new Error("Image has zero dimensions.")); + } const canvas = document.createElement("canvas"); canvas.width = img.naturalWidth; canvas.height = img.naturalHeight; const ctx = canvas.getContext("2d"); ctx.drawImage(img, 0, 0); canvas.toBlob(blob => { if (blob) resolve(blob); else reject(new Error("Canvas to Blob conversion failed")); }, "image/jpeg", 0.95); }); }, Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly points out that sending 0-dimension images to the OCR service is wasteful and adds a necessary guard clause to prevent this, improving efficiency and error handling.	Low
More