@involvex/ext-cli 1.0.1

package/docs/superpowers/plans/2026-07-05-ext-cli.md

@@ -0,0 +1,1115 @@
+# ext-cli Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build a Bun-based CLI tool (`ext-cli`) that downloads Chrome/Edge extensions from their respective web stores, extracts CRX files to directories, and packs directories into CRX files.
+
+**Architecture:** Single-package Bun project with TypeScript. CLI uses `commander` for argument parsing. Core logic split into three modules: `downloader` (fetch CRX from store), `extractor` (CRX → directory), `packer` (directory → CRX). CRX parsing handles both v2 and v3 formats. Edge support via separate download URL pattern.
+
+**Tech Stack:** Bun runtime, TypeScript, commander (CLI args), `@tomjs/unzip-crx` (CRX extraction), `node-forge` (RSA key generation for packing), protobufjs (CRX3 header parsing)
+
+---
+
+## File Structure
+
+```
+chrome-ext-manager/
+├── package.json
+├── tsconfig.json
+├── src/
+│   ├── cli.ts              # CLI entry point, argument parsing
+│   ├── index.ts            # Public API exports
+│   ├── downloader.ts       # Download CRX from Chrome/Edge store
+│   ├── extractor.ts        # Extract CRX file to directory
+│   ├── packer.ts           # Pack directory into CRX file
+│   ├── crx-parser.ts       # CRX v2/v3 binary format parsing
+│   ├── url-parser.ts       # Parse store URLs → extension IDs
+│   └── utils.ts            # Shared helpers (file ops, progress)
+├── test/
+│   ├── crx-parser.test.ts
+│   ├── url-parser.test.ts
+│   ├── extractor.test.ts
+│   ├── packer.test.ts
+│   └── fixtures/
+│       ├── sample.crx      # Small test CRX file
+│       └── extension-dir/  # Test extension directory
+│           └── manifest.json
+└── docs/
+    └── superpowers/
+        └── plans/
+            └── 2026-07-05-ext-cli.md
+```
+
+---
+
+## Global Constraints
+
+- Runtime: Bun >= 1.3.0
+- Language: TypeScript (strict mode)
+- Package manager: bun (not npm/yarn/pnpm)
+- Shell commands: PowerShell-compatible (Windows)
+- CLI binary name: `ext-cli`
+- Auto-generate .pem keys when packing
+- Support both Chrome Web Store and Edge Add-ons URLs
+
+---
+
+### Task 1: Project Scaffolding
+
+**Files:**
+- Create: `package.json`
+- Create: `tsconfig.json`
+- Create: `src/cli.ts` (minimal)
+- Create: `src/index.ts` (minimal)
+
+**Interfaces:**
+- Consumes: none
+- Produces: project structure ready for development
+
+- [ ] **Step 1: Initialize Bun project**
+
+```bash
+cd D:\repos\chrome-ext-manager
+bun init -y
+```
+
+- [ ] **Step 2: Install dependencies**
+
+```bash
+bun add commander node-forge
+bun add -d @types/node @types/bun typescript
+```
+
+- [ ] **Step 3: Create tsconfig.json**
+
+```json
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "resolveJsonModule": true,
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}
+```
+
+- [ ] **Step 4: Create minimal src/cli.ts**
+
+```typescript
+#!/usr/bin/env bun
+
+console.log("ext-cli - Chrome/Edge Extension Manager");
+```
+
+- [ ] **Step 5: Create minimal src/index.ts**
+
+```typescript
+export { downloadExtension } from "./downloader";
+export { extractCrx } from "./extractor";
+export { packCrx } from "./packer";
+```
+
+- [ ] **Step 6: Add scripts to package.json**
+
+Add to `package.json`:
+```json
+{
+  "name": "ext-cli",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": {
+    "ext-cli": "./src/cli.ts"
+  },
+  "scripts": {
+    "build": "bun build src/cli.ts --compile --outfile ext-cli",
+    "dev": "bun run src/cli.ts",
+    "test": "bun test"
+  }
+}
+```
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add -A
+git commit -m "feat: scaffold ext-cli project with bun, typescript, commander"
+```
+
+---
+
+### Task 2: URL Parser Module
+
+**Files:**
+- Create: `src/url-parser.ts`
+- Create: `test/url-parser.test.ts`
+
+**Interfaces:**
+- Consumes: none
+- Produces: `parseStoreUrl(url: string): StoreInfo` where `StoreInfo = { id: string; store: 'chrome' | 'edge' }`
+
+- [ ] **Step 1: Write failing tests**
+
+```typescript
+// test/url-parser.test.ts
+import { describe, test, expect } from "bun:test";
+import { parseStoreUrl } from "../src/url-parser";
+
+describe("parseStoreUrl", () => {
+  test("parses Chrome Web Store URL", () => {
+    const result = parseStoreUrl(
+      "https://chromewebstore.google.com/webstore/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm"
+    );
+    expect(result).toEqual({ id: "cjpalhdlnbpafiamejdnhcphjbkeiagm", store: "chrome" });
+  });
+
+  test("parses Chrome URL with query params", () => {
+    const result = parseStoreUrl(
+      "https://chromewebstore.google.com/detail/ext-name/abcdef1234567890abcdef12?hl=en"
+    );
+    expect(result).toEqual({ id: "abcdef1234567890abcdef12", store: "chrome" });
+  });
+
+  test("parses Edge Add-ons URL", () => {
+    const result = parseStoreUrl(
+      "https://microsoftedge.microsoft.com/addons/detail/ublock-origin/odfafepnkmbhccpbejgmiehpchacaeak"
+    );
+    expect(result).toEqual({ id: "odfafepnkmbhccpbejgmiehpchacaeak", store: "edge" });
+  });
+
+  test("parses bare 32-char extension ID as chrome", () => {
+    const result = parseStoreUrl("cjpalhdlnbpafiamejdnhcphjbkeiagm");
+    expect(result).toEqual({ id: "cjpalhdlnbpafiamejdnhcphjbkeiagm", store: "chrome" });
+  });
+
+  test("throws on invalid input", () => {
+    expect(() => parseStoreUrl("")).toThrow();
+    expect(() => parseStoreUrl("not-a-valid-id!")).toThrow();
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+bun test test/url-parser.test.ts
+```
+Expected: FAIL — `parseStoreUrl` not found
+
+- [ ] **Step 3: Implement url-parser.ts**
+
+```typescript
+// src/url-parser.ts
+
+export interface StoreInfo {
+  id: string;
+  store: "chrome" | "edge";
+}
+
+const CHROME_URL_RE =
+  /chromewebstore\.google\.com\/webstore\/detail\/[^/]+\/([a-z]{32})/i;
+const EDGE_URL_RE =
+  /microsoftedge\.microsoft\.com\/addons\/detail\/([a-z]{32})/i;
+const BARE_ID_RE = /^[a-z]{32}$/i;
+
+export function parseStoreUrl(input: string): StoreInfo {
+  const trimmed = input.trim();
+
+  // Try Chrome Web Store URL
+  const chromeMatch = trimmed.match(CHROME_URL_RE);
+  if (chromeMatch) {
+    return { id: chromeMatch[1].toLowerCase(), store: "chrome" };
+  }
+
+  // Try Edge Add-ons URL
+  const edgeMatch = trimmed.match(EDGE_URL_RE);
+  if (edgeMatch) {
+    return { id: edgeMatch[1].toLowerCase(), store: "edge" };
+  }
+
+  // Try bare extension ID (32 lowercase letters)
+  if (BARE_ID_RE.test(trimmed)) {
+    return { id: trimmed.toLowerCase(), store: "chrome" };
+  }
+
+  throw new Error(
+    `Invalid extension URL or ID: "${input}". Expected a Chrome Web Store URL, Edge Add-ons URL, or a 32-character extension ID.`
+  );
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+```bash
+bun test test/url-parser.test.ts
+```
+Expected: ALL PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/url-parser.ts test/url-parser.test.ts
+git commit -m "feat: add URL parser for Chrome/Edge store URLs and bare IDs"
+```
+
+---
+
+### Task 3: CRX Parser Module
+
+**Files:**
+- Create: `src/crx-parser.ts`
+- Create: `test/crx-parser.test.ts`
+
+**Interfaces:**
+- Consumes: none
+- Produces: `parseCrxHeader(buffer: Buffer): CrxInfo` and `extractZipFromCrx(buffer: Buffer): Buffer`
+
+- [ ] **Step 1: Write failing tests**
+
+```typescript
+// test/crx-parser.test.ts
+import { describe, test, expect } from "bun:test";
+import { parseCrxHeader, extractZipFromCrx } from "../src/crx-parser";
+import { readFileSync } from "fs";
+import { join } from "path";
+
+describe("CRX Parser", () => {
+  test("parseCrxHeader reads CRX3 header", () => {
+    // Create a minimal CRX3 mock: Cr24 + version 3 + header_len + header bytes + zip
+    const header = Buffer.alloc(16); // 12 byte header + 4 byte dummy
+    header.write("Cr24", 0); // magic
+    header.writeUInt32LE(3, 4); // version
+    header.writeUInt32LE(4, 8); // header length (4 bytes of dummy)
+    header.writeUInt32LE(0, 12); // dummy header bytes
+
+    const info = parseCrxHeader(header);
+    expect(info.version).toBe(3);
+    expect(info.headerLength).toBe(4);
+    expect(info.zipOffset).toBe(16);
+  });
+
+  test("parseCrxHeader reads CRX2 header", () => {
+    const header = Buffer.alloc(16);
+    header.write("Cr24", 0); // magic
+    header.writeUInt32LE(2, 4); // version
+    header.writeUInt32LE(4, 8); // header length
+
+    const info = parseCrxHeader(header);
+    expect(info.version).toBe(2);
+  });
+
+  test("parseCrxHeader throws on invalid magic", () => {
+    const bad = Buffer.from("NOTACRX");
+    expect(() => parseCrxHeader(bad)).toThrow("Not a CRX file");
+  });
+
+  test("extractZipFromCrx returns zip bytes after header", () => {
+    // Build a fake CRX3: 12 byte fixed header + 4 byte protobuf header + "ZIPDATA"
+    const fixed = Buffer.alloc(12);
+    fixed.write("Cr24", 0);
+    fixed.writeUInt32LE(3, 4);
+    fixed.writeUInt32LE(4, 8);
+
+    const protoHeader = Buffer.alloc(4);
+    const zipData = Buffer.from("PKZIP_DATA_HERE");
+
+    const crx = Buffer.concat([fixed, protoHeader, zipData]);
+    const zip = extractZipFromCrx(crx);
+
+    expect(zip.equals(zipData)).toBe(true);
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+bun test test/crx-parser.test.ts
+```
+Expected: FAIL — `parseCrxHeader` not found
+
+- [ ] **Step 3: Implement crx-parser.ts**
+
+```typescript
+// src/crx-parser.ts
+
+export interface CrxInfo {
+  version: number;
+  headerLength: number;
+  zipOffset: number;
+}
+
+const CRX_MAGIC = "Cr24";
+
+/**
+ * Parse the CRX binary header (supports CRX2 and CRX3).
+ * Returns metadata about the header so callers can extract the ZIP payload.
+ */
+export function parseCrxHeader(buffer: Buffer): CrxInfo {
+  if (buffer.length < 12) {
+    throw new Error("Not a CRX file: buffer too small");
+  }
+
+  const magic = buffer.toString("ascii", 0, 4);
+  if (magic !== CRX_MAGIC) {
+    throw new Error(`Not a CRX file: invalid magic "${magic}" (expected "${CRX_MAGIC}")`);
+  }
+
+  const version = buffer.readUInt32LE(4);
+  if (version !== 2 && version !== 3) {
+    throw new Error(`Unsupported CRX version: ${version}`);
+  }
+
+  const headerLength = buffer.readUInt32LE(8);
+  const zipOffset = 12 + headerLength;
+
+  return { version, headerLength, zipOffset };
+}
+
+/**
+ * Extract the ZIP payload from a CRX buffer.
+ * The ZIP starts immediately after the CRX header (fixed 12 bytes + header protobuf).
+ */
+export function extractZipFromCrx(buffer: Buffer): Buffer {
+  const info = parseCrxHeader(buffer);
+  return buffer.subarray(info.zipOffset);
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+```bash
+bun test test/crx-parser.test.ts
+```
+Expected: ALL PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/crx-parser.ts test/crx-parser.test.ts
+git commit -m "feat: add CRX v2/v3 parser for header reading and ZIP extraction"
+```
+
+---
+
+### Task 4: Downloader Module
+
+**Files:**
+- Create: `src/downloader.ts`
+
+**Interfaces:**
+- Consumes: `parseStoreUrl` from `url-parser.ts`
+- Produces: `downloadExtension(urlOrId: string, outputDir?: string): Promise<string>` — returns path to saved .crx file
+
+- [ ] **Step 1: Implement downloader.ts**
+
+```typescript
+// src/downloader.ts
+import { parseStoreUrl } from "./url-parser";
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+
+const CHROME_CRX_URL =
+  "https://clients2.google.com/service/update2/crx?response=redirect&prodversion=131.0&acceptformat=crx2,crx3&x=id%3D{ID}%26uc";
+
+const EDGE_CRX_URL =
+  "https://edge.microsoft.com/extensionwebstorebase/v1/crx?response=redirect&x=id%3D{ID}%26installsource%3Dondemand%26uc";
+
+function buildDownloadUrl(id: string, store: "chrome" | "edge"): string {
+  const template = store === "chrome" ? CHROME_CRX_URL : EDGE_CRX_URL;
+  return template.replace("{ID}", id);
+}
+
+/**
+ * Download a CRX file from the Chrome Web Store or Edge Add-ons.
+ * Accepts a full store URL or a bare 32-char extension ID.
+ * Returns the path to the saved .crx file.
+ */
+export async function downloadExtension(
+  urlOrId: string,
+  outputDir: string = "."
+): Promise<string> {
+  const { id, store } = parseStoreUrl(urlOrId);
+  const downloadUrl = buildDownloadUrl(id, store);
+
+  console.log(`Downloading ${store} extension: ${id}`);
+  console.log(`URL: ${downloadUrl}`);
+
+  const response = await fetch(downloadUrl, {
+    headers: {
+      "User-Agent":
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+    },
+    redirect: "follow",
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Download failed: HTTP ${response.status} ${response.statusText}`
+    );
+  }
+
+  const arrayBuffer = await response.arrayBuffer();
+  const buffer = Buffer.from(arrayBuffer);
+
+  // Verify it's a valid CRX file
+  const magic = buffer.toString("ascii", 0, 4);
+  if (magic !== "Cr24") {
+    throw new Error(
+      `Invalid CRX response: got "${magic}" instead of "Cr24". The extension may not exist or the store may have changed.`
+    );
+  }
+
+  // Ensure output directory exists
+  await mkdir(outputDir, { recursive: true });
+
+  const outputPath = join(outputDir, `${id}.crx`);
+  await writeFile(outputPath, buffer);
+
+  console.log(`Saved: ${outputPath} (${(buffer.length / 1024).toFixed(1)} KB)`);
+  return outputPath;
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/downloader.ts
+git commit -m "feat: add downloader for Chrome Web Store and Edge Add-ons CRX files"
+```
+
+---
+
+### Task 5: Extractor Module
+
+**Files:**
+- Create: `src/extractor.ts`
+- Create: `test/extractor.test.ts`
+
+**Interfaces:**
+- Consumes: `extractZipFromCrx` from `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 () => {
+  // Create a minimal CRX3 wrapping a small ZIP
+  // For this test, we create a real ZIP first, then wrap in CRX header
+  // We'll use a fixture approach: create a ZIP with a manifest.json
+  const zipPath = join(TEST_DIR, "test.zip");
+  
+  // Use bun to create a zip via command
+  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;
+  
+  // Read the zip and wrap in CRX3 header
+  const zipBuf = Bun.file(zipPath);
+  const zipBytes = Buffer.from(await zipBuf.arrayBuffer());
+  
+  // Build CRX3 header: Cr24 + version(3) + headerLen(4 bytes of protobuf)
+  const crxHeader = Buffer.alloc(12);
+  crxHeader.write("Cr24", 0);
+  crxHeader.writeUInt32LE(3, 4);
+  crxHeader.writeUInt32LE(4, 8); // header length = 4 dummy bytes
+  
+  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, readdir } from "fs/promises";
+import { join, basename } from "path";
+import { extractZipFromCrx } from "./crx-parser";
+
+/**
+ * Extract a CRX file to a directory.
+ * Reads the CRX header, extracts the embedded ZIP, and unzips to outputDir.
+ * Returns the path to the extracted directory.
+ */
+export async function extractCrx(
+  crxPath: string,
+  outputDir?: string
+): Promise<string> {
+  const crxBuffer = await readFile(crxPath);
+  const zipBuffer = extractZipFromCrx(crxBuffer);
+
+  // Determine output directory name from CRX filename
+  const baseName = basename(crxPath, ".crx");
+  const destDir = outputDir ?? join(".", baseName);
+  await mkdir(destDir, { recursive: true });
+
+  // Write ZIP to temp file, then extract
+  const tempZip = join(destDir, "__temp__.zip");
+  await writeFile(tempZip, zipBuffer);
+
+  // Use Bun's built-in unzip via tar or powershell
+  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}`);
+  }
+
+  // Clean up temp ZIP
+  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"
+```
+
+---
+
+### 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);
+
+  // Verify it starts with Cr24 magic
+  const buf = readFileSync(result);
+  expect(buf.toString("ascii", 0, 4)).toBe("Cr24");
+  expect(buf.readUInt32LE(4)).toBe(3); // CRX version 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**
+
+```typescript
+// src/packer.ts
+import { readdir, readFile, writeFile, mkdir } from "fs/promises";
+import { join, basename } from "path";
+import forge from "node-forge";
+
+/**
+ * Create a CRX3 file from an extension directory.
+ * Generates a .pem key if one doesn't exist in the directory.
+ * Returns the path to the created .crx file.
+ */
+export async function packCrx(
+  dirPath: string,
+  outputPath?: string
+): Promise<string> {
+  // Read manifest to verify it's an extension
+  const manifestPath = join(dirPath, "manifest.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf-8"));
+  if (!manifest.name || !manifest.version) {
+    throw new Error("Invalid extension: manifest.json must have 'name' and 'version'");
+  }
+
+  // Load or generate private key
+  const keyPath = join(dirPath, "key.pem");
+  let privateKey: forge.pki.PrivateKey;
+  try {
+    const keyPem = await readFile(keyPath, "utf-8");
+    privateKey = forge.pki.privateKeyFromPem(keyPem);
+  } catch {
+    // Generate new 2048-bit RSA key
+    privateKey = forge.pki.rsa.generatePrivateKey(2048);
+    const pem = forge.pki.privateKeyToPem(privateKey);
+    await writeFile(keyPath, pem);
+    console.log(`Generated key: ${keyPath}`);
+  }
+
+  // Create ZIP from directory contents
+  const zipBuffer = await createZipFromDir(dirPath);
+
+  // Build CRX3 header
+  const publicKey = forge.pki.publicKeyToDer(forge.pki.publicKeyFromPem(
+    forge.pki.publicKeyToPem(privateKey.publicKey)
+  ));
+
+  // Create signed data: SHA256 of (CRX ID + ZIP)
+  const crxId = computeCrxId(publicKey);
+  const signedData = Buffer.concat([Buffer.from(crxId), zipBuffer]);
+  const sha256Digest = forge.md.sha256.create().update(signedData.getBytes()).digest().getBytes();
+
+  // Create RSA signature
+  const md = forge.md.sha256.create();
+  md.update(sha256Digest);
+  const signature = privateKey.sign(md);
+
+  // Build protobuf header manually (simplified CRX3 format)
+  const header = buildCrx3Header(publicKey, Buffer.from(signature, "binary"));
+
+  // Assemble CRX file
+  const magic = Buffer.from("Cr24");
+  const version = Buffer.alloc(4);
+  version.writeUInt32LE(3, 0);
+  const headerLen = Buffer.alloc(4);
+  headerLen.writeUInt32LE(header.length, 0);
+
+  const crx = Buffer.concat([magic, version, headerLen, header, zipBuffer]);
+
+  const outPath = outputPath ?? join(".", `${basename(dirPath)}.crx`);
+  await writeFile(outPath, crx);
+
+  console.log(`Packed: ${outPath} (${(crx.length / 1024).toFixed(1)} KB)`);
+  return outPath;
+}
+
+/**
+ * Compute a Chrome extension ID from a DER-encoded public key.
+ * This is the base-26 encoding of the key hash.
+ */
+function computeCrxId(derPublicKey: Buffer): string {
+  const md = forge.md.sha256.create();
+  md.update(forge.util.binary.raw.encode(derPublicKey));
+  const hash = md.digest().getBytes();
+
+  // Chrome uses first 16 bytes of SHA256, then base-26 encodes
+  const bytes = Buffer.from(hash, "binary").subarray(0, 16);
+  const alphabet = "abcdefghijklmnop";
+
+  let id = "";
+  for (let i = 0; i < bytes.length; i++) {
+    id += alphabet[bytes[i] % 16];
+  }
+  return id;
+}
+
+/**
+ * Build a minimal CRX3 protobuf header.
+ * Format: field 2 (sha256_with_rsa) = AsymmetricKeyProof { public_key, signature }
+ */
+function buildCrx3Header(publicKey: Buffer, signature: Buffer): Buffer {
+  // Protobuf encoding for CRX3 header
+  // This is a simplified encoder for the required fields
+  
+  function encodeVarint(value: number): number[] {
+    const bytes: number[] = [];
+    while (value > 0x7f) {
+      bytes.push((value & 0x7f) | 0x80);
+      value >>>= 7;
+    }
+    bytes.push(value & 0x7f);
+    return bytes;
+  }
+
+  function encodeLengthDelimited(fieldNumber: number, data: Buffer): number[] {
+    const tag = (fieldNumber << 3) | 2;
+    return [...encodeVarint(tag), ...encodeVarint(data.length), ...data];
+  }
+
+  // AsymmetricKeyProof: field 1 = public_key, field 2 = signature
+  const publicKeyField = encodeLengthDelimited(1, publicKey);
+  const signatureField = encodeLengthDelimited(2, signature);
+  const asymmetricProof = Buffer.from([...publicKeyField, ...signatureField]);
+
+  // CrxFileHeader: field 2 = sha256_with_rsa (repeated)
+  const proofField = encodeLengthDelimited(2, asymmetricProof);
+
+  return Buffer.from(proofField);
+}
+
+/**
+ * Create a ZIP archive from a directory using PowerShell.
+ */
+async function createZipFromDir(dirPath: string): Promise<Buffer> {
+  const tempZip = join(dirPath, "__temp_pack__.zip");
+  
+  const proc = Bun.spawn([
+    "powershell",
+    "-Command",
+    `Compress-Archive -Path '${dirPath}\\*' -DestinationPath '${tempZip}' -Force`,
+  ]);
+  const exitCode = await proc.exited;
+
+  if (exitCode !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+    throw new Error(`Failed to create ZIP: ${stderr}`);
+  }
+
+  const zipBuffer = Buffer.from(await Bun.file(tempZip).arrayBuffer());
+  await import("fs/promises").then((fs) => fs.unlink(tempZip));
+  
+  return zipBuffer;
+}
+```
+
+- [ ] **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"
+```
+
+---
+
+### Task 7: CLI Entry Point
+
+**Files:**
+- Modify: `src/cli.ts`
+
+**Interfaces:**
+- Consumes: `downloadExtension`, `extractCrx`, `packCrx` from other modules
+- Produces: working CLI binary
+
+- [ ] **Step 1: Implement full CLI**
+
+```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
+# Test help
+bun run src/cli.ts --help
+
+# Test get help
+bun run src/cli.ts get --help
+
+# Test extract help
+bun run src/cli.ts extract --help
+
+# Test pack 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"
+```
+
+---
+
+### Task 8: End-to-End Testing
+
+**Files:**
+- No new files
+
+**Interfaces:**
+- Consumes: all modules
+- Produces: verified working CLI
+
+- [ ] **Step 1: Test downloading a real extension**
+
+```bash
+# Download uBlock Origin from Chrome Web Store
+bun run src/cli.ts get "https://chromewebstore.google.com/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm" -d "./test-output"
+
+# Verify .crx file exists
+dir test-output
+```
+
+- [ ] **Step 2: Test download + extract**
+
+```bash
+# Download and extract in one step
+bun run src/cli.ts get "https://chromewebstore.google.com/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm" -d "./test-output2" -e
+
+# Verify extracted directory
+dir test-output2
+```
+
+- [ ] **Step 3: Test extract from local file**
+
+```bash
+# Extract the previously downloaded CRX
+bun run src/cli.ts extract "./test-output/cjpalhdlnbpafiamejdnhcphjbkeiagm.crx" -d "./test-extracted"
+```
+
+- [ ] **Step 4: Test pack from directory**
+
+```bash
+# Pack the extracted directory back to CRX
+bun run src/cli.ts pack "./test-extracted" -o "./test-packed.crx"
+```
+
+- [ ] **Step 5: Clean up test files**
+
+```bash
+Remove-Item -Recurse -Force ./test-output, ./test-output2, ./test-extracted, ./test-packed.crx -ErrorAction SilentlyContinue
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add -A
+git commit -m "test: verify end-to-end workflow for download, extract, and pack"
+```
+
+---
+
+### Task 9: Build & Release
+
+**Files:**
+- Modify: `package.json`
+
+**Interfaces:**
+- Consumes: all source files
+- Produces: standalone binary `ext-cli`
+
+- [ ] **Step 1: Build standalone binary**
+
+```bash
+bun build src/cli.ts --compile --outfile ext-cli.exe
+```
+
+- [ ] **Step 2: Test the binary**
+
+```bash
+.\ext-cli.exe --help
+.\ext-cli.exe get --help
+```
+
+- [ ] **Step 3: Update package.json with bin field**
+
+Ensure `package.json` has:
+```json
+{
+  "bin": {
+    "ext-cli": "./ext-cli.exe"
+  }
+}
+```
+
+- [ ] **Step 4: Final commit**
+
+```bash
+git add -A
+git commit -m "feat: add standalone binary build for ext-cli"
+```
+
+---
+
+## Summary
+
+| Task | Description | Dependencies |
+|------|-------------|--------------|
+| 1 | Project scaffolding | None |
+| 2 | URL parser | None |
+| 3 | CRX parser | None |
+| 4 | Downloader | Task 2 |
+| 5 | Extractor | Task 3 |
+| 6 | Packer | None |
+| 7 | CLI entry point | Tasks 4, 5, 6 |
+| 8 | E2E testing | Task 7 |
+| 9 | Build & release | Task 8 |
+
+**Parallelizable:** Tasks 2, 3, and 6 can be done in parallel. Task 4 depends on 2. Task 5 depends on 3.
+
+---
+
+## CLI Usage Examples
+
+```bash
+# Download extension (saves .crx file)
+ext-cli get "https://chromewebstore.google.com/webstore/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm"
+
+# Download and extract to directory
+ext-cli get "https://chromewebstore.google.com/webstore/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm" -e
+
+# Download to specific directory
+ext-cli get cjpalhdlnbpafiamejdnhcphjbkeiagm -d "./extensions" -e
+
+# Download Edge extension
+ext-cli get "https://microsoftedge.microsoft.com/addons/detail/ublock-origin/odfafepnkmbhccpbejgmiehpchacaeak" -e
+
+# Extract local CRX file
+ext-cli extract ./my-extension.crx -d ./unpacked
+
+# Pack directory to CRX (auto-generates key.pem)
+ext-cli pack ./my-extension -o ./my-extension.crx
+```