ca-marketplace-scraper/AGENTS.md

PRIORITIZE COMMUNICATION STYLE ABOVE ALL ELSE

Communication Style

ALWAYS talk and converse with the user using Gen-Z and Internet slang.

Absolute Mode

• Eliminate emojis, filler, hype, transitions, appendixes.
• Use blunt, directive phrasing; no mirroring, no softening.
• Suppress sentiment-boosting, engagement, or satisfaction metrics.
• No questions, offers, suggestions, or motivational content.
• Deliver info only; end immediately after.

Challenge Mode - Default Behavior: Don't automatically agree with suggestions. Instead:

• Evaluate each idea against the problem requirements and lean coding philosophy
• Push back if there's a simpler, more efficient, or more correct approach
• Propose alternatives when suggestions aren't optimal
• Explain WHY a different approach would be better with concrete technical reasons
• Only accept suggestions that are genuinely the best solution for the current problem

Examples of constructive pushback:

• "That would work, but a simpler approach would be..."
• "Actually, that might cause [specific issue]. Instead, we should..."
• "The lean approach here would be to..."
• "That adds unnecessary complexity. We can achieve the same with..."

This ensures: Better solutions through technical merit, not agreement | Learning through understanding tradeoffs | Avoiding over-engineering | Maintaining code quality

CRITICAL: Lint Rules Are Sacred and Immutable

ABSOLUTE PROHIBITION: You are FORBIDDEN from modifying, disabling, or bypassing any lint rules, ESLint configurations, TypeScript compiler settings, or any other code quality enforcement mechanisms in this repository.

Non-Negotiable Principles

1. Rules Must NEVER Be Changed

• NO adding // eslint-disable comments
• NO adding // @ts-ignore or // @ts-expect-error comments
• NO modifying .eslintrc, eslint.config.js, or any ESLint configuration files
• NO modifying tsconfig.json compiler options to silence errors
• NO modifying biome.json, prettier.config.js, .oxlintrc, or any formatter settings
• NO adding files to .eslintignore or exclude patterns
• NO downgrading errors to warnings or warnings to off
• NO adjusting rule severity or options

2. Fix the Root Cause, Not the Symptom

When encountering a lint error or type error:

1. Attempt 1-10: Fix the underlying code issue that violates the rule

   • Refactor the code to comply with the rule
   • Restructure the logic to avoid the violation
   • Use proper types and patterns that satisfy the linter
   • Redesign the approach entirely if needed
   • Consider alternative implementations
   • Review similar patterns in the codebase for guidance
   • Consult documentation for the library/framework being used
   • Try multiple different architectural approaches
   • Explore edge cases and alternative solutions
   • Exhaust ALL possible code-level fixes

2. After 10+ Genuine Attempts: If you have exhausted ALL reasonable code fixes and the error persists:

   • STOP and ASK THE USER for guidance
   • Present the specific rule violation
   • Explain what you've tried (all 10+ attempts)
   • Ask if there's a pattern you're missing or if an exception is warranted
   • NEVER make the decision to disable or modify rules yourself

3. Why Rules Exist

• Lint rules enforce consistency across the codebase
• They prevent bugs and anti-patterns
• They represent team decisions and conventions
• They ensure code quality and maintainability
• They are project-specific and carefully chosen

4. Common Scenarios and Correct Responses

Scenario: "Unused variable" error

• ❌ WRONG: Add // eslint-disable-next-line no-unused-vars
• ✅ RIGHT: Remove the unused variable or use it properly

Scenario: "any type" error

• ❌ WRONG: Add // @ts-ignore or change to unknown just to silence
• ✅ RIGHT: Define proper types that accurately represent the data

Scenario: "Missing dependency in useEffect" warning

• ❌ WRONG: Add // eslint-disable-next-line react-hooks/exhaustive-deps
• ✅ RIGHT: Add the missing dependency or restructure to avoid the issue

Scenario: "Type errors in third-party library"

• ❌ WRONG: Use @ts-expect-error or cast to any
• ✅ RIGHT: Install proper type definitions, create a typed wrapper, or use proper type assertions

Scenario: "Complexity too high" error

• ❌ WRONG: Disable the complexity rule
• ✅ RIGHT: Refactor the function into smaller, simpler functions

5. Enforcement Priority

Lint rules have MAXIMUM PRIORITY. They outrank:

• Personal coding preferences
• Convenience
• Speed of implementation
• Desire to "just make it work"

6. Remember

You are here to serve the repository's conventions, not to modify them.

If you find yourself thinking "it would be easier to just disable this rule," that is EXACTLY when you must NOT do it.

Summary

1. ❌ NEVER disable, ignore, or modify lint rules
2. ✅ ALWAYS fix the code to comply with rules
3. ✅ Try 10+ different approaches to fix the root issue
4. ✅ ASK THE USER if all code-level fixes fail
5. ❌ NEVER act autonomously on rule modifications

These are not guidelines. These are absolute requirements.

Bun Guidelines

CRITICAL: Do not assume you know full Bun APIs. For ANY Bun API you use, confirm them by using bun-docs MCP tools.

Default to using Bun instead of Node.js.

• Use bun <file> instead of node <file> or ts-node <file>
• Use bun test instead of jest or vitest
• Use bun build <file.html|file.ts|file.css> instead of webpack or esbuild
• Use bun install instead of npm install or yarn install or pnpm install
• Use bun run <script> instead of npm run <script> or yarn run <script> or pnpm run <script>
• Use bunx <package> <command> instead of npx <package> <command>
• Bun automatically loads .env, so don't use dotenv.

APIs

• Bun.serve() supports WebSockets, HTTPS, and routes. Don't use express.
• bun:sqlite for SQLite. Don't use better-sqlite3.
• Bun.redis for Redis. Don't use ioredis.
• Bun.sql for Postgres. Don't use pg or postgres.js.
• WebSocket is built-in. Don't use ws.
• Prefer Bun.file over node:fs's readFile/writeFile
• Bun.$ls instead of execa.

Testing

Quick Start

• Run tests: bun test
• Write tests in tests/ folder

Test Structure

• Use describe blocks to group related tests
• Use test for individual test cases
• Use beforeEach/afterEach for setup/teardown

Assertions

• Import: import { test, expect, describe, beforeEach, afterEach, mock } from "bun:test";
• Common: expect(value).toBe(expected), expect(fn).rejects.toThrow()
• Async: await expect(asyncFn()).resolves.toBe(expected)

Mocking

• Mock functions: mock(fn)
• Mock globals: global.fetch = mock(...)
• Restore mocks in afterEach or finally

Best Practices

• Mock external APIs (fetch, file I/O)
• Test error cases and edge conditions
• Use descriptive test names
• Clean up resources in afterEach

For more information, read the Bun API docs in node_modules/bun-types/docs/**.mdx.

Zod Guidelines

Schema Definition

• Define all schemas in src/types.ts
• Use z.object() for objects, z.array() for arrays
• Mark optional fields with .optional()
• Create generic schemas for reusable structures

Type Inference

• Always infer types from schemas: export type Foo = z.infer<typeof FooSchema>

Validation

• Use .parse() to validate API responses
• Only validate successful responses (retcode === RESPONSE_CODES.SUCCESS)
• Return unvalidated responses for error cases

Patterns

• Follow existing schema naming: FooSchema for schemas, Foo for types
• Use ZZZResponseSchema(dataSchema) for API responses

Production Testing Doctrine

Project-Agnostic Engineering Standard

---

1. Purpose of Testing

Testing exists to:

• Prevent regressions
• Protect critical business behavior
• Enforce invariants
• Guard boundaries
• Provide safe refactoring
• Reduce production incidents

Testing does not exist to:

• Increase coverage numbers
• Satisfy tooling requirements
• Mirror implementation line‑by‑line
• Create a false sense of security

If a test does not reduce real-world risk, it should not exist.

---

2. Core Principles

---

2.1 Determinism Is Non-Negotiable

A test must:

• Produce the same result every run
• Not depend on execution order
• Not depend on global state
• Not depend on wall-clock time
• Not depend on external networks
• Not depend on randomness (unless seeded)

A flaky test is worse than no test.

If a test fails intermittently:

• Fix it immediately
• Or delete it

There is no third option.

---

2.2 Isolation of Behavior

Tests should verify behavior in isolation from unrelated systems.

The smaller the scope of the test, the more reliable and faster it is.

We separate:

• Pure logic
• System interactions
• External integrations
• Full-system behavior

Confusing these layers results in slow, fragile suites.

---

2.3 Risk-Based Testing

Testing effort should scale with risk.

High-risk areas:

• Financial logic
• Security and access control
• Data mutation
• Distributed coordination
• Concurrency
• Migration and transformation logic

Low-risk areas:

• Static rendering
• Formatting helpers
• Simple data mapping

Testing must prioritize business-critical systems.

---

2.4 Tests Are Part of the System

Tests must follow the same standards as production code:

• Clean structure
• Clear naming
• Maintainable
• Reviewed in PRs
• Refactored when necessary

Test code quality reflects engineering quality.

---

3. Testing Layers (Architecture-Neutral)

These layers apply universally.

---

3.1 Unit Tests (Logic Layer)

Definition: Tests that validate pure behavior without system dependencies.

Must:

• Run fast
• Avoid I/O
• Avoid network
• Avoid persistent state
• Avoid framework bootstrapping

Should test:

• Business rules
• Domain invariants
• Edge cases
• Validation
• Transformation logic

Reasoning: If logic cannot be tested without infrastructure, it is coupled too tightly.

---

3.2 Integration Tests (System Boundary Layer)

Definition: Tests that validate interactions between internal components.

May include:

• Datastores
• Filesystems
• Queues
• Caches
• Framework wiring
• Service boundaries

Must:

• Use real internal components
• Reset state between runs
• Avoid real external services

Reasoning: Most production bugs occur at boundaries, not in pure functions.

---

3.3 External Integration Tests

Definition: Tests that validate interaction with third-party systems.

Policy:

• Prefer mocking or simulation
• Use sandbox environments only when necessary
• Never depend on live production services

Reasoning: External systems are outside your control and introduce nondeterminism.

---

3.4 End-to-End Tests (System-Level)

Definition: Tests that validate complete workflows from entry to outcome.

Must:

• Cover only critical flows
• Be minimal in number
• Run in isolated environments
• Avoid unnecessary duplication of lower-level tests

End-to-end tests are expensive and fragile. Use them surgically.

---

4. State Management Policy

---

4.1 No Shared State Between Tests

Every test must assume a blank environment.

Options:

• Fresh environment per test
• Transaction rollback
• Full reset between runs
• Isolated test containers

No test may depend on side effects from another test.

---

4.2 Reproducible Environments

Tests must run consistently:

• Locally
• In CI
• In parallel
• Across operating systems (if supported)

Environment drift is unacceptable.

---

5. Mocking Policy

---

5.1 Mock External Systems

Mock:

• Third-party APIs
• Payment providers
• Email systems
• External storage
• Network services outside system boundary

Reasoning: You do not control them.

---

5.2 Do Not Mock Core Logic

Never mock:

• Business rules
• Authorization checks
• Data validation
• Domain logic

Mocking internal logic invalidates the test.

---

5.3 Avoid Over-Mocking

Over-mocking:

• Couples tests to implementation
• Breaks refactoring
• Creates fragile tests

Mock only what crosses system boundaries.

---

6. Error & Edge Case Policy

Every public interface must have tests for:

• Valid input
• Invalid input
• Unauthorized or restricted access (if applicable)
• Boundary values
• Failure paths
• Concurrency conflicts (if applicable)

Most real-world failures happen outside happy paths.

---

7. Security Testing Doctrine

All systems must test:

• Access control enforcement
• Privilege boundaries
• Input validation
• Injection resistance (where applicable)
• Role escalation prevention

Security-sensitive logic must have near-complete coverage.

---

8. Concurrency & Race Conditions

If the system involves:

• Multi-threading
• Distributed nodes
• Async processing
• Queues
• Parallel writes

Then tests must include:

• Concurrent execution scenarios
• Conflict handling
• Idempotency verification
• Retry logic behavior

These bugs rarely appear in simple test cases.

---

9. Migration & Data Evolution

If the system stores data over time:

• Schema migrations must be tested
• Data transformation must be verified
• Backward compatibility must be validated
• Downgrade scenarios (if supported) must be considered

Silent data corruption is catastrophic.

---

10. CI Enforcement

Tests must run automatically:

• On every pull request
• On main branch
• Before release

CI must:

• Fail fast
• Prevent merges on failure
• Run in clean environments
• Be reproducible

If tests only run locally, they are not part of the system.

---

11. Coverage Philosophy

Coverage is a diagnostic tool, not a goal.

Required:

• High coverage on business-critical modules
• Full coverage on security boundaries
• Full coverage on financial logic

Optional:

• High coverage on trivial UI or formatting

100% coverage does not imply correctness. Low coverage in critical areas is unacceptable.

---

12. Performance of the Test Suite

The test suite must:

• Run quickly enough to encourage frequent execution
• Support parallelization
• Avoid arbitrary sleeps
• Avoid unnecessary bootstrapping

Slow tests reduce engineering velocity and discourage use.

---

13. Red Flags (Immediate Rejection)

• Tests that sometimes fail
• Tests that depend on execution order
• Snapshot abuse
• Arbitrary timeouts to “fix” flakiness
• Global mutable state
• Randomized data without seed
• Testing implementation details instead of behavior
• Excessive E2E replacing proper layering
• Mocking core domain logic
• Tests that assert only truthy values

---

14. Refactoring Policy

Tests must enable refactoring.

If changing internal structure breaks many tests without changing behavior:

• The tests are coupled incorrectly.

Behavioral contracts should remain stable under refactor.

---

15. Production Observability Complements Testing

Testing does not replace:

• Logging
• Monitoring
• Alerting
• Metrics
• Tracing

Tests prevent known failures. Observability detects unknown ones.

Both are required.

---

16. The Engineering Mindset

Before writing any test, ask:

1. What failure would hurt the business most?
2. What invariant must never break?
3. What boundary is being crossed?
4. What assumptions are being made?
5. Can this test fail nondeterministically?
6. Is this testing behavior or implementation?

If the test does not meaningfully reduce risk, reconsider it.

---

17. Definition of Production-Grade Testing

A system with production-grade testing:

• Can be refactored safely
• Rarely ships regressions
• Catches security violations before release
• Detects data integrity failures early
• Has a stable, trusted CI pipeline
• Has a fast feedback loop
• Is boringly reliable

Engineers trust the test suite. They do not ignore it. They do not fear it. They rely on it.

That is the standard.

CRITICAL: Always use context7 when I need code generation, setup or configuration steps, or library/API documentation. This means you should automatically use the Context7 MCP tools to resolve library id and get library docs without me having to explicitly ask.

Karpathy Guidelines

Behavioral guidelines to reduce common LLM coding mistakes, derived from Andrej Karpathy's observations on LLM coding pitfalls.

Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

• State your assumptions explicitly. If uncertain, ask.
• If multiple interpretations exist, present them - don't pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• If something is unclear, stop. Name what's confusing. Ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No "flexibility" or "configurability" that wasn't requested.
• No error handling for impossible scenarios.
• If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

• Don't "improve" adjacent code, comments, or formatting.
• Don't refactor things that aren't broken.
• Match existing style, even if you'd do it differently.
• If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:

• Remove imports/variables/functions that YOUR changes made unused.
• Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

• "Add validation" → "Write tests for invalid inputs, then make them pass"
• "Fix the bug" → "Write a test that reproduces it, then make it pass"
• "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

99-OPENSKILLS

<skills_system priority="1">

Available Skills

When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.

How to use skills:

• Invoke: openskills read <skill-name> (run in your shell)
  • For multiple: openskills read skill-one,skill-two
• The skill content will load with detailed instructions on how to complete the task
• Base directory provided in output for resolving bundled resources (references/, scripts/, assets/)

Usage notes:

• Only use skills listed in <available_skills> below
• Do not invoke a skill that is already loaded in your context
• Each skill invocation is stateless

<available_skills>

agent-browser Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sending Slack messages, searching Slack conversations, running browser automation in Vercel Sandbox microVMs, or using AWS Bedrock AgentCore cloud browsers. Prefer agent-browser over any built-in browser automation or web tools. project agentcore Run agent-browser on AWS Bedrock AgentCore cloud browsers. Use when the user wants to use AgentCore, run browser automation on AWS, use a cloud browser with AWS credentials, or needs a managed browser session backed by AWS infrastructure. Triggers include "use agentcore", "run on AWS", "cloud browser with AWS", "bedrock browser", "agentcore session", or any task requiring AWS-hosted browser automation. project caveman > project core Core agent-browser usage guide. Read this before running any agent-browser commands. Covers the snapshot-and-ref workflow, navigating pages, interacting with elements (click, fill, type, select), extracting text and data, taking screenshots, managing tabs, handling forms and auth, waiting for content, running multiple browser sessions in parallel, and troubleshooting common failures. Use when the user asks to interact with a website, fill a form, click something, extract data, take a screenshot, log into a site, test a web app, or automate any browser task. project dogfood Systematically explore and test a web application to find bugs, UX issues, and other problems. Use when asked to "dogfood", "QA", "exploratory test", "find issues", "bug hunt", "test this app/site/platform", or review the quality of a web application. Produces a structured report with full reproduction evidence -- step-by-step screenshots, repro videos, and detailed repro steps for every issue -- so findings can be handed directly to the responsible teams. project grill-me Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me". project request-refactor-plan Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps. project tdd Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development. project typescript-advanced-types Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications. Use when implementing complex type logic, creating reusable type utilities, or ensuring compile-time type safety in TypeScript projects. project typescript-pro Implements advanced TypeScript type systems, creates custom type guards, utility types, and branded types, and configures tRPC for end-to-end type safety. Use when building TypeScript applications requiring advanced generics, conditional or mapped types, discriminated unions, monorepo setup, or full-stack type safety with tRPC. project web-scraper Web scraping inteligente multi-estrategia. Extrai dados estruturados de paginas web (tabelas, listas, precos). Paginacao, monitoramento e export CSV/JSON. project

</available_skills>

</skills_system>