@involvex/ext-cli 1.0.1

package/.superpowers/sdd/task-5-brief.md

@@ -0,0 +1,122 @@
+# Task 5: Extractor Module
+
+**Files:**
+- Create: `src/extractor.ts`
+- Create: `test/extractor.test.ts`
+
+**Interfaces:**
+- Consumes: `extractZipFromCrx` from `src/crx-parser.ts`
+- Produces: `extractCrx(crxPath: string, outputDir?: string): Promise<string>` — returns path to extracted directory
+
+- [ ] **Step 1: Write failing tests**
+
+```typescript
+// test/extractor.test.ts
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { extractCrx } from "../src/extractor";
+import { mkdirSync, rmSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+
+const TEST_DIR = join(import.meta.dir, "__test_extract__");
+
+beforeEach(() => {
+  mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+test("extractCrx extracts a CRX file to directory", async () => {
+  const zipPath = join(TEST_DIR, "test.zip");
+  
+  const extDir = join(TEST_DIR, "ext_src");
+  mkdirSync(extDir, { recursive: true });
+  writeFileSync(join(extDir, "manifest.json"), JSON.stringify({ name: "test", version: "1.0" }));
+  
+  const proc = Bun.spawn(["powershell", "-Command", `Compress-Archive -Path '${extDir}\\*' -DestinationPath '${zipPath}' -Force`]);
+  await proc.exited;
+  
+  const zipBuf = Bun.file(zipPath);
+  const zipBytes = Buffer.from(await zipBuf.arrayBuffer());
+  
+  const crxHeader = Buffer.alloc(12);
+  crxHeader.write("Cr24", 0);
+  crxHeader.writeUInt32LE(3, 4);
+  crxHeader.writeUInt32LE(4, 8);
+  
+  const dummyProto = Buffer.alloc(4);
+  const crxBuffer = Buffer.concat([crxHeader, dummyProto, zipBytes]);
+  
+  const crxPath = join(TEST_DIR, "test.crx");
+  writeFileSync(crxPath, crxBuffer);
+  
+  const outputDir = join(TEST_DIR, "extracted");
+  const result = await extractCrx(crxPath, outputDir);
+  
+  expect(existsSync(join(result, "manifest.json"))).toBe(true);
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+bun test test/extractor.test.ts
+```
+Expected: FAIL — `extractCrx` not found
+
+- [ ] **Step 3: Implement extractor.ts**
+
+```typescript
+// src/extractor.ts
+import { readFile, mkdir, writeFile } from "fs/promises";
+import { join, basename } from "path";
+import { extractZipFromCrx } from "./crx-parser";
+
+export async function extractCrx(
+  crxPath: string,
+  outputDir?: string
+): Promise<string> {
+  const crxBuffer = await readFile(crxPath);
+  const zipBuffer = extractZipFromCrx(crxBuffer);
+
+  const baseName = basename(crxPath, ".crx");
+  const destDir = outputDir ?? join(".", baseName);
+  await mkdir(destDir, { recursive: true });
+
+  const tempZip = join(destDir, "__temp__.zip");
+  await writeFile(tempZip, zipBuffer);
+
+  const proc = Bun.spawn([
+    "powershell",
+    "-Command",
+    `Expand-Archive -Path '${tempZip}' -DestinationPath '${destDir}' -Force`,
+  ]);
+  const exitCode = await proc.exited;
+
+  if (exitCode !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+    throw new Error(`Failed to extract ZIP: ${stderr}`);
+  }
+
+  const { unlink } = await import("fs/promises");
+  await unlink(tempZip);
+
+  console.log(`Extracted to: ${destDir}`);
+  return destDir;
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+```bash
+bun test test/extractor.test.ts
+```
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/extractor.ts test/extractor.test.ts
+git commit -m "feat: add CRX extractor that unzips CRX files to directories"
+```

package/.superpowers/sdd/task-5-report.md

@@ -0,0 +1,22 @@
+# Task 5: Extractor Module — Report
+
+## Files Created
+- `src/extractor.ts` — CRX extractor using `extractZipFromCrx` from crx-parser
+- `test/extractor.test.ts` — Test that builds a CRX, extracts it, and verifies manifest.json exists
+
+## Implementation Notes
+- Uses `Bun.spawn` with PowerShell `Expand-Archive` to unzip the extracted ZIP buffer
+- Creates a temp zip in the destination dir, extracts, then cleans up the temp file
+- Default output dir falls back to `./<crx-basename>` if no `outputDir` provided
+- The test requires `--timeout 30000` to account for PowerShell startup overhead on Windows
+
+## Test Results
+```
+12 pass, 0 fail across 4 test files
+```
+
+## Commit
+- `7c57087` — feat: add CRX extractor that unzips CRX files to directories
+
+## Concerns
+- The default bun test timeout (5s) is insufficient for PowerShell processes on Windows; the `bun.lock` changed (likely from the test run). Tests must be run with `--timeout 30000`.

package/.superpowers/sdd/task-6-brief.md

@@ -0,0 +1,96 @@
+# Task 6: Packer Module
+
+**Files:**
+- Create: `src/packer.ts`
+- Create: `test/packer.test.ts`
+
+**Interfaces:**
+- Consumes: none
+- Produces: `packCrx(dirPath: string, outputPath?: string): Promise<string>` — returns path to packed .crx file
+
+- [ ] **Step 1: Write failing tests**
+
+```typescript
+// test/packer.test.ts
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { packCrx } from "../src/packer";
+import { mkdirSync, rmSync, writeFileSync, existsSync, readFileSync } from "fs";
+import { join } from "path";
+
+const TEST_DIR = join(import.meta.dir, "__test_pack__");
+
+beforeEach(() => {
+  mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+test("packCrx creates a CRX file from directory", async () => {
+  const extDir = join(TEST_DIR, "my-ext");
+  mkdirSync(extDir, { recursive: true });
+  writeFileSync(
+    join(extDir, "manifest.json"),
+    JSON.stringify({ manifest_version: 3, name: "Test Ext", version: "1.0" })
+  );
+
+  const crxPath = join(TEST_DIR, "output.crx");
+  const result = await packCrx(extDir, crxPath);
+
+  expect(existsSync(result)).toBe(true);
+
+  const buf = readFileSync(result);
+  expect(buf.toString("ascii", 0, 4)).toBe("Cr24");
+  expect(buf.readUInt32LE(4)).toBe(3);
+});
+
+test("packCrx generates .pem key if none exists", async () => {
+  const extDir = join(TEST_DIR, "my-ext2");
+  mkdirSync(extDir, { recursive: true });
+  writeFileSync(
+    join(extDir, "manifest.json"),
+    JSON.stringify({ manifest_version: 3, name: "Test", version: "1.0" })
+  );
+
+  await packCrx(extDir, join(TEST_DIR, "out.crx"));
+  expect(existsSync(join(extDir, "key.pem"))).toBe(true);
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+bun test test/packer.test.ts
+```
+Expected: FAIL — `packCrx` not found
+
+- [ ] **Step 3: Implement packer.ts**
+
+The packer must:
+1. Read manifest.json from the directory to validate it's an extension
+2. Load existing key.pem or generate a new 2048-bit RSA key using node-forge
+3. Create a ZIP archive from the directory contents (use PowerShell Compress-Archive on Windows)
+4. Build a CRX3 header with the public key and a SHA256 signature
+5. Assemble: magic "Cr24" + version(3) + headerLen + header + zipData
+6. Write to output path and return it
+
+Key implementation details:
+- Use `node-forge` for RSA key generation and signing
+- CRX3 protobuf header format: field 2 (sha256_with_rsa) contains AsymmetricKeyProof with field 1 (public_key DER) and field 2 (signature)
+- Extension ID is computed as first 16 bytes of SHA256(public_key DER), base-16 encoded with alphabet "abcdefghijklmnop"
+- ZIP creation: use `Bun.spawn` with PowerShell `Compress-Archive` on Windows
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+```bash
+bun test test/packer.test.ts
+```
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/packer.ts test/packer.test.ts
+git commit -m "feat: add CRX3 packer with auto key generation"
+```

package/.superpowers/sdd/task-6-report.md

@@ -0,0 +1,24 @@
+# Task 6: Packer Module — Report
+
+## Status: DONE
+
+## Commits
+- `8d6308d` — feat: add CRX3 packer with auto key generation
+
+## Test Summary
+2/2 tests pass. Tests verify CRX file creation with correct "Cr24" magic and version 3, and that key.pem is auto-generated when missing.
+
+## Implementation Summary
+
+Created `src/packer.ts` implementing `packCrx(dirPath, outputPath?)`:
+1. Validates manifest.json exists in the extension directory
+2. Loads existing key.pem or generates new 2048-bit RSA key pair via node-forge
+3. Extracts public key DER from private key for extension ID computation and CRX header
+4. Computes extension ID: SHA256(publicKey DER), first 16 bytes, alphabet "abcdefghijklmnop"
+5. Creates ZIP archive via PowerShell `Compress-Archive` (Windows)
+6. Signs: SHA256(crxId + zipData) with RSA private key
+7. Builds CRX3 protobuf header manually using varint encoding
+8. Assembles final CRX: "Cr24" + version(3) + headerLen + header + zipData
+
+## Concerns
+None — tests pass cleanly, implementation is self-contained with no external dependencies beyond node-forge and child_process.

package/.superpowers/sdd/task-7-brief.md

@@ -0,0 +1,100 @@
+# Task 7: CLI Entry Point
+
+**Files:**
+- Modify: `src/cli.ts`
+
+**Interfaces:**
+- Consumes: `downloadExtension` from `src/downloader.ts`, `extractCrx` from `src/extractor.ts`, `packCrx` from `src/packer.ts`
+- Produces: working CLI binary with get, extract, and pack commands
+
+- [ ] **Step 1: Implement full CLI**
+
+Replace the contents of `src/cli.ts` with:
+
+```typescript
+#!/usr/bin/env bun
+
+import { Command } from "commander";
+import { downloadExtension } from "./downloader";
+import { extractCrx } from "./extractor";
+import { packCrx } from "./packer";
+
+const program = new Command();
+
+program
+  .name("ext-cli")
+  .description("Chrome/Edge Extension Manager - download, extract, and pack extensions")
+  .version("1.0.0");
+
+program
+  .command("get")
+  .description("Download an extension from Chrome Web Store or Edge Add-ons")
+  .argument("<url-or-id>", "Store URL or 32-char extension ID")
+  .option("-d, --dir <directory>", "Output directory", ".")
+  .option("-e, --extract", "Extract the CRX after downloading")
+  .action(async (urlOrId: string, opts: { dir: string; extract: boolean }) => {
+    try {
+      const crxPath = await downloadExtension(urlOrId, opts.dir);
+      
+      if (opts.extract) {
+        const extDir = crxPath.replace(/\.crx$/, "");
+        await extractCrx(crxPath, extDir);
+        console.log(`\nDone! Extension extracted to: ${extDir}`);
+      } else {
+        console.log(`\nDone! CRX saved to: ${crxPath}`);
+      }
+    } catch (error) {
+      console.error(`Error: ${error instanceof Error ? error.message : error}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("extract")
+  .description("Extract a CRX file to a directory")
+  .argument("<crx-file>", "Path to .crx file")
+  .option("-d, --dir <directory>", "Output directory")
+  .action(async (crxFile: string, opts: { dir?: string }) => {
+    try {
+      const outputDir = opts.dir ?? crxFile.replace(/\.crx$/, "");
+      await extractCrx(crxFile, outputDir);
+      console.log(`\nDone! Extracted to: ${outputDir}`);
+    } catch (error) {
+      console.error(`Error: ${error instanceof Error ? error.message : error}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("pack")
+  .description("Pack a directory into a CRX file")
+  .argument("<directory>", "Extension directory containing manifest.json")
+  .option("-o, --output <path>", "Output CRX file path")
+  .action(async (directory: string, opts: { output?: string }) => {
+    try {
+      const crxPath = await packCrx(directory, opts.output);
+      console.log(`\nDone! Packed to: ${crxPath}`);
+    } catch (error) {
+      console.error(`Error: ${error instanceof Error ? error.message : error}`);
+      process.exit(1);
+    }
+  });
+
+program.parse();
+```
+
+- [ ] **Step 2: Test CLI manually**
+
+```bash
+bun run src/cli.ts --help
+bun run src/cli.ts get --help
+bun run src/cli.ts extract --help
+bun run src/cli.ts pack --help
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/cli.ts
+git commit -m "feat: implement ext-cli with get, extract, and pack commands"
+```

package/.superpowers/sdd/task-7-report.md

@@ -0,0 +1,30 @@
+# Task 7: CLI Entry Point — Report
+
+## What was done
+
+Replaced the placeholder `src/cli.ts` with the full commander-based CLI implementation.
+
+## Commands implemented
+
+| Command | Description | Key options |
+|---------|-------------|-------------|
+| `get <url-or-id>` | Download extension from Chrome Web Store or Edge Add-ons | `-d/--dir`, `-e/--extract` |
+| `extract <crx-file>` | Extract a CRX file to a directory | `-d/--dir` |
+| `pack <directory>` | Pack a directory into a CRX file | `-o/--output` |
+
+## Test results
+
+- `bun run src/cli.ts --help` — Shows all 3 commands correctly
+- `bun run src/cli.ts get --help` — Shows argument and options
+- `bun run src/cli.ts extract --help` — Shows argument and options
+- `bun run src/cli.ts pack --help` — Shows argument and options
+
+All four help commands passed.
+
+## Commit
+
+- `aaaf063` — `feat: implement ext-cli with get, extract, and pack commands`
+
+## Concerns
+
+None. The implementation matches the brief exactly.

package/AGENTS.md

@@ -0,0 +1,264 @@
+# Agents.md — chrome-ext-manager (ext-cli)
+
+This document provides instructions for AI agents working on this codebase.
+It covers commands, technologies, project structure, and best practices.
+
+---
+
+## Project Overview
+
+`ext-cli` is a CLI tool for downloading, extracting, packing, and searching
+Chrome/Edge browser extensions. It parses CRX v2/v3 files, communicates with
+the Chrome Web Store and Edge Add-ons APIs, and can build standalone binaries.
+
+---
+
+## Technologies
+
+| Category | Technology | Notes |
+|---|---|---|
+| Runtime | **Bun** >= 1.3.0 | Required — do not use Node.js, npm, yarn, or pnpm |
+| Language | **TypeScript** (strict mode) | ESNext target, bundler module resolution |
+| CLI Framework | **commander** ^15.0.0 | Argument parsing and help generation |
+| Crypto / Keys | **node-forge** ^1.4.0 | RSA key generation and CRX signing |
+| Browser Launcher | **chromium-edge-launcher** ^2.0.1 | Launch Edge with remote debugging |
+| Linter / Formatter | **Biome** ^2.5.2 | Replaces ESLint + Prettier |
+| Testing | **bun:test** | Built-in test runner with `describe`, `test`, `expect` |
+| Shell | **PowerShell** | All shell commands must be PowerShell-compatible (Windows) |
+
+---
+
+## Project Structure
+
+```
+chrome-ext-manager/
+├── src/
+│   ├── cli.ts            # CLI entry point (commander)
+│   ├── index.ts          # Public API exports
+│   ├── url-parser.ts     # Parse store URLs → { id, store }
+│   ├── crx-parser.ts     # CRX v2/v3 binary header parsing
+│   ├── downloader.ts     # Fetch CRX from Chrome/Edge stores
+│   ├── extractor.ts      # Extract CRX → directory
+│   ├── packer.ts         # Directory → signed CRX3 file
+│   ├── search.ts         # Search Chrome Web Store & Edge Add-ons
+│   └── launcher.ts       # Launch Edge with extensions
+├── test/
+│   ├── crx-parser.test.ts
+│   ├── extractor.test.ts
+│   ├── packer.test.ts
+│   └── url-parser.test.ts
+├── docs/superpowers/plans/
+├── biome.json
+├── tsconfig.json
+├── package.json
+└── bun.lock
+```
+
+### Module Responsibilities
+
+| Module | Input | Output | Key Function |
+|---|---|---|---|
+| `url-parser.ts` | Store URL or bare ID | `StoreInfo { id, store }` | `parseStoreUrl()` |
+| `crx-parser.ts` | CRX `Buffer` | `CrxInfo { version, headerLength, zipOffset }` | `parseCrxHeader()`, `extractZipFromCrx()` |
+| `downloader.ts` | URL or ID + output dir | Path to saved `.crx` file | `downloadExtension()` |
+| `extractor.ts` | `.crx` file path + output dir | Path to extracted directory | `extractCrx()` |
+| `packer.ts` | Extension directory + optional output path | Path to packed `.crx` file | `packCrx()` |
+| `search.ts` | Search query | `SearchResult[]` | `searchExtensions()` |
+| `launcher.ts` | Extension path + options | `LaunchedEdge { port, pid, kill }` | `launch()`, `killAllEdges()`, `getEdgeInstallationPath()` |
+| `cli.ts` | CLI arguments | Console output / exit code | Commander program |
+
+---
+
+## Useful Commands
+
+### Setup
+
+```bash
+bun install                  # Install all dependencies
+```
+
+### Development
+
+```bash
+bun run src/cli.ts search "ublock"         # Run CLI directly
+bun run src/cli.ts get <url-or-id> -e      # Download + extract
+bun run src/cli.ts extract <file.crx>      # Extract CRX
+bun run src/cli.ts pack <directory>        # Pack directory to CRX
+bun run src/cli.ts launch --extension <dir> # Launch Edge with extension
+bun run src/cli.ts test <url-or-id>        # Download + extract + launch
+```
+
+### Quality Checks
+
+```bash
+bun run typecheck             # TypeScript type checking (tsc --noEmit)
+bun run lint                  # Biome lint check (src/ + test/)
+bun run lint:fix              # Biome lint with auto-fix
+bun run format                # Biome format (src/ + test/)
+bun run check                 # Format + lint:fix + typecheck (all-in-one)
+```
+
+### Testing
+
+```bash
+bun test                      # Run all tests
+bun test test/url-parser.test.ts           # Run a single test file
+bun test --filter "parseStoreUrl"          # Run tests matching a name
+```
+
+### Build
+
+```bash
+bun run build                 # Builds dist/ext-cli.exe (runs prebuild check first)
+```
+
+### Prebuild Pipeline
+
+The `prebuild` script runs `bun run check` (format → lint:fix → typecheck)
+before any build. This means the build will fail if code quality checks fail.
+
+---
+
+## Architecture Notes
+
+### CRX Format
+
+- CRX files start with the magic bytes `Cr24`
+- Version is stored as a 32-bit LE integer at offset 4 (2 or 3)
+- A header length (32-bit LE) follows at offset 8
+- The ZIP payload starts at offset `12 + headerLength`
+- CRX3 adds a protobuf `AsymmetricKeyProof` with the public key and signature
+
+### Download Flow
+
+1. `parseStoreUrl()` resolves the URL/ID to a `StoreInfo` object
+2. A download URL is constructed per store (Chrome or Edge)
+3. The response is fetched with a browser-like User-Agent
+4. The CRX magic bytes are verified before writing to disk
+
+### Extract Flow
+
+1. The CRX file is read into a `Buffer`
+2. `extractZipFromCrx()` slices the buffer to get the ZIP payload
+3. A temp ZIP is written, then extracted via PowerShell `Expand-Archive`
+4. The temp ZIP is cleaned up
+
+### Pack Flow
+
+1. A `key.pem` is loaded or generated (2048-bit RSA via `node-forge`)
+2. The extension directory is zipped via PowerShell `Compress-Archive`
+3. A CRX3 header is built: protobuf-encoded `AsymmetricKeyProof` with the public key and a SHA-256-based RSA signature
+4. The final CRX is assembled: magic + version + header length + header + ZIP data
+
+### Key Implementation Details
+
+- **`safeBinaryEncode()`** in `packer.ts` avoids stack overflow by encoding buffers in 8KB chunks instead of using `String.fromCharCode.apply()` on the full buffer
+- **`computeExtensionId()`** hashes the DER public key with SHA-256, takes the first 16 bytes, and maps each byte to a letter in the alphabet `a-p` (base-16 encoding, not base-26)
+- **Protobuf encoding** is done manually with `encodeVarint()` and `encodeField()` helpers — no protobuf library is used at runtime
+
+### Launch Flow
+
+1. `launch()` resolves extension path (auto-extracts `.crx` to temp directory if needed)
+2. Constructs Edge flags: `--load-extension=<path>`, `--headless=new` (if headless), `--remote-debugging-port`
+3. Spawns Edge via `chromium-edge-launcher` with fresh user data directory
+4. Returns `LaunchedEdge` with port, PID, and `kill()` function for cleanup
+5. Temp extension directory cleaned up on `kill()` if auto-extracted from CRX
+
+---
+
+## Best Practices & Guidelines
+
+### Runtime & Package Management
+
+- **Always use `bun`** — never npm, yarn, or pnpm
+- Lock file is `bun.lock` — commit it when dependencies change
+- Dev dependencies: `@biomejs/biome`, `@types/bun`, `@types/node`, `@types/node-forge`
+
+### Shell Commands
+
+- **Always use PowerShell-compatible commands** — this project targets Windows
+- Use `dir` or `Get-ChildItem` instead of `ls -la`
+- Use `Remove-Item -Recurse` instead of `rm -rf`
+- Use `Copy-Item` instead of `cp`, `Move-Item` instead of `mv`
+- Use `Get-Content` instead of `cat` for reading files
+- When spawning shell commands in code (e.g., in `extractor.ts` and `packer.ts`), use `powershell -Command "..."` with proper quoting
+
+### Code Style (Biome)
+
+- Indent with **2 spaces** (no tabs)
+- Max line width: **100 characters**
+- Use **double quotes** for strings
+- Always use **semicolons**
+- Warn on unused variables and imports (`noUnusedVariables`, `noUnusedImports`)
+
+### Error Handling
+
+- CLI commands wrap action handlers in `try/catch` and call `process.exit(1)` on error
+- Error messages use `error instanceof Error ? error.message : error` pattern
+- Network errors include HTTP status codes in messages
+- CRX validation checks magic bytes and throws descriptive errors before writing files
+
+### Testing
+
+- Tests use `bun:test` (import `describe`, `test`, `expect` from `"bun:test"`)
+- Use `beforeEach` / `afterEach` for setup/teardown with temp directories
+- Clean up temp directories with `rmSync(dir, { recursive: true, force: true })`
+- Tests construct synthetic CRX files in-memory or from real zips
+- No external fixtures are committed — tests are self-contained
+
+### TypeScript
+
+- Strict mode is enabled — all types must be explicit or inferrable
+- Target ESNext with bundler module resolution
+- Use `node:` prefix for Node.js built-in imports (e.g., `node:fs/promises`, `node:path`)
+- Avoid `any` — use `unknown` and narrow with type guards
+- Export public API through `src/index.ts`
+
+### Security
+
+- **Never commit `.pem` key files** — they are auto-generated per extension directory
+- Validate downloaded CRX files by checking magic bytes before writing
+- Do not trust external input (URLs, file contents) without validation
+- The `.gitignore` already excludes `.env` files and build artifacts
+
+### Commit Conventions
+
+Use conventional commits:
+
+```
+feat: add new feature
+fix: correct a bug
+test: add or update tests
+refactor: improve code structure
+docs: update documentation
+chore: maintenance tasks
+```
+
+### Module Boundaries
+
+- Each module has a single responsibility
+- Dependencies flow downward: `cli.ts` → `downloader` / `extractor` / `packer` / `search` → `url-parser` / `crx-parser`
+- `crx-parser.ts` and `url-parser.ts` are leaf modules with no internal dependencies
+- `search.ts` is independent — it scrapes store HTML and does not use the downloader
+
+### Network Requests
+
+- User-Agent is set to Chrome 131 to avoid blocks from store servers
+- `redirect: "follow"` is used for CRX downloads (stores redirect to CDN)
+- HTML scraping is used for search (stores do not provide public APIs)
+- Errors from non-200 responses are thrown immediately
+
+### Adding New Features
+
+1. Write tests first (TDD encouraged)
+2. Run `bun test` to verify they fail
+3. Implement the feature
+4. Run `bun run check` to verify formatting, linting, and types
+5. Run `bun test` again to verify all tests pass
+6. Commit with a conventional commit message
+
+### File Naming
+
+- Source files: `kebab-case.ts` (e.g., `url-parser.ts`, `crx-parser.ts`)
+- Test files: `<module>.test.ts` in the `test/` directory
+- No barrel files beyond `src/index.ts`