poe2-trade-butler-development

name	poe2-trade-butler-development
description	Use before making code changes in the POE2-Trade-Butler Chrome extension, especially domain migration, manifest permissions, content scripts, storage, favorites/history, Korean translation cache, Chrome manual regression checks, build tooling, or tests. This skill gives project-specific structure hints and the safest files to inspect before editing.

POE2 Trade Butler Development Hints

Use this skill before implementation work in this repository. It is a quick orientation map so you touch the right files, avoid generated-file churn, and verify through the Windows package-script path.

First Pass

1. Read AGENTS.md for current branch rules, WSL/PowerShell split, and the dev_key.pub development extension ID workflow.
2. Check the task category:
   • Domain or Kakao Games migration: inspect src/manifest.json, src/utils/api.ts, src/support/koreanTranslate.ts, and URL fixtures in src/utils/*.test.ts.
   • Sidebar/UI behavior: inspect src/content-script.ts, src/components/sidebar.ts, src/ui/, and src/styles/.
   • Storage or favorites/history: inspect src/storage/storage.ts, the specific src/storage/*Storage.ts module, and src/storage/initStorage.ts.
   • Background fetch/auth/Google Drive/notice work: inspect src/background.ts, src/utils/GoogleDriveApi.ts, and relevant storage settings.
3. Use rg before editing. The same concern is often duplicated in manifest matches, runtime URL parsing, saved favorite serialization, and tests.

Architecture Map

• src/manifest.json is the Chrome MV3 manifest source. Webpack copies it to dist/manifest.json.
• webpack.config.js owns entrypoints:
  • popup -> src/components/popup.ts
  • background -> src/background.ts
  • content-script -> src/content-script.ts
• src/content-script.ts imports src/storage/initStorage.ts, renders the sidebar into the trade page .content element, and starts first-run guide behavior.
• src/background.ts handles extension messages:
  • GET_AUTH_TOKEN / REMOVE_CACHED_ACCESS_TOKEN
  • RELOAD_EXTENSION
  • FETCH_LSCACHE for trade static data fetches
  • FETCH_MARKDOWN for notice content It also runs legacy migrations, preview cleanup, deletion listeners, and version badge updates.
• src/components/sidebar.ts is a large orchestration surface for history, favorites, settings, sidebar dimensions, preview state, and storage warnings. Keep edits local and prefer extracting only when the task genuinely needs it.
• src/ui/ contains modal and filesystem-style UI helpers used by sidebar and settings.
• src/styles/ contains sidebar/settings/tool/modal styling. Pair UI changes with the relevant SCSS/CSS file rather than inline styles unless the existing code already does so nearby.

Domain Migration Hotspots

Legacy Korean service handling currently appears in several places:

• src/manifest.json
  • host_permissions
  • content_scripts[].matches
• src/utils/api.ts
  • parseSearchUrl
  • getUrlFromSearchHistory
  • isKoreanServer
  • getServerRegion
• src/support/koreanTranslate.ts
  • static trade data URLs for items, filters, stats, and static
• src/utils/shareFavorites.ts
  • serialized favorite region mapping
• src/utils/ChunkifyUtil.test.ts and src/utils/shareFavorites.test.ts
  • URL fixtures and Korean region expectations

When changing the Kakao Games domain, update all of these together. Do not only patch the manifest; saved favorite import/export and history URL reconstruction can still preserve the old host.

Preserve existing GGG regional hosts unless the task explicitly says otherwise: www, jp, br, ru, th, de, fr, es under pathofexile.com.

Storage Model

• Storage is wrapped by StorageManager in src/storage/storage.ts.
• Supported storage areas are currently local and sync.
• Strategies:
  • default for normal values
  • chunkedArray for large sync arrays
  • googleDrive for favorite sync via Drive
• Any file importing StorageManager must be pulled into src/storage/initStorage.ts. Do not edit that generated file by hand; run npm run pre:build or npm run build:dev.
• Favorites use a root folder entry with id root.
• Favorite sync can switch between chunked chrome.storage.sync and Google Drive depending on settingStorage.isFavoriteGDriveSyncEnabled().
• Deletion listeners in background.ts clean orphan preview snapshots when search history or favorites are deleted.

Generated Files

Generated files can become dirty after builds:

• src/utils/supportedLanguages.ts
  • Generated from _locales/*/messages.json by scripts/generate-supported-languages.ts.
• src/storage/initStorage.ts
  • Generated by scripts/generate-storage-manager-initializer.ts.

If a build dirties them with no content change, restore them instead of committing formatting or line-ending churn. If locale directories or storage manager imports really changed, commit the generated update with the source change.

Development Extension ID

Do not store the Chrome extension ID in .env. The development ID is fixed by dev_key.pub.

In development builds, webpack.config.js reads dev_key.pem or dev_key.pub and injects the public key as manifest.key. The known development ID derived from the current dev_key.pub is:

ipnemofnhodcgcplnnfekbfpmngeeocm

Use npm run build:dev to verify key injection. The log should include:

Development key added to manifest.json from public key.

Playwright Extension Checks

Prefer Playwright's bundled Chromium for deterministic extension regression checks. Branded Chrome 137+ can ignore or block the old --load-extension command-line flow; if that happens, do not keep debugging the flag. Use npm run test:e2e instead.

The E2E suite builds dist/ with npm run build:dev, launches a persistent Chromium context with:

• --disable-extensions-except=<repo>\dist
• --load-extension=<repo>\dist

For migration checks, seed legacy storage through the extension service worker, close the context, relaunch the same profile, and then inspect chrome.storage.local and chrome.storage.sync. This avoids relying on the old Daum page still being reachable or the user being logged in.

Chrome Debugging And Migration Checks

Use Windows Chrome for manual extension checks. Keep two workflows separate:

• Logged-in site checks use the user's real Chrome profile.
• Deterministic migration checks use a clean temporary Chrome profile.

Before launching a profile with remote debugging, close existing Chrome windows for that profile. If Chrome is already running, it can reuse the old browser process and ignore the new debugging flags.

For logged-in Kakao checks:

1. Confirm the intended Chrome profile directory from chrome://version > Profile Path. Do not infer it from the profile display name alone.
2. Start Chrome from Windows PowerShell with remote debugging and that profile, then open chrome://extensions/:

   $chrome = "${env:ProgramFiles}\Google\Chrome\Application\chrome.exe"
   & $chrome --remote-debugging-port=9222 --profile-directory="Profile X" "chrome://extensions/"
   

3. Turn on Developer Mode, load the unpacked extension from D:\project\POE2-Trade-Butler-origin\dist, and verify the extension ID is ipnemofnhodcgcplnnfekbfpmngeeocm.
4. If the extension is missing, check the loaded folder is dist, npm run build:dev completed, Developer Mode is enabled, and the browser was started with the intended profile.
5. Open the target trade page, for example https://poe.kakaogames.com/trade2/search/poe2/Runes%20of%20Aldur, and let the user handle any required site login.

For migration regression checks:

1. Use a clean temporary Chrome user data directory so the starting storage state is known:

   $chrome = "${env:ProgramFiles}\Google\Chrome\Application\chrome.exe"
   & $chrome --remote-debugging-port=9222 --user-data-dir="$env:TEMP\poe2tb-migration-profile" "chrome://extensions/"
   

2. Build and load the previous version first, using the same dev_key.pub so the extension ID stays stable. Seed legacy Daum data through the UI or extension storage: search history entries, favorite folder metadata URLs, and Google Drive favorite data when testing Drive sync.
3. Build the migration branch with npm run build:dev, reload the unpacked extension, and verify storage version advances only after successful migration.
4. Confirm old https://poe.game.daum.net/trade2/... URLs are rewritten to https://poe.kakaogames.com/trade2/... in local/sync storage and, when Drive sync is enabled and the Drive hint exists, in the Drive favorite file.
5. Also verify the no-Drive path: if the Drive hint key is absent or Drive sync is disabled, migration must not require Google Drive login or call Drive migration code.

Verification

Run package scripts from Windows PowerShell, not WSL, when using the shared checkout.

Typical verification order:

1. Focused tests for the touched area, for example: npm test -- src/utils/shareFavorites.test.ts
2. Full test suite: npm test
3. Development build for extension loading: npm run build:dev
4. For release packaging changes only: npm run build

If npm install changes package-lock.json only by npm metadata churn, do not commit it unless dependency versions actually changed or the task is explicitly about dependency setup.