# Design: Adopt opencode Monorepo Config

**Date:** 2025-07-14\
**Status:** Approved\
**Approach:** Full adoption (A)

## Context

Current repo (`marketplace-scrapers-monorepo`) has basic bun workspaces with 3 packages
(`core`, `api-server`, `mcp-server`). Reference: `anomalyco/opencode` monorepo patterns.

**Gaps vs opencode:**
- No Turbo (task orchestration, caching, dep graph)
- No workspace catalog (shared dep versions duplicated across packages)
- No root tsconfig (identical tsconfigs duplicated in all 3 packages)
- No `bunfig.toml` (no exact installs, no root test guard)
- `main`/`module` fields instead of `exports` field

## Changes

### 1. Root `package.json`

- Add `workspaces.catalog` block with shared deps:
  - `@typescript/native-preview`, `@types/bun`, `@types/unidecode`,
    `@types/cli-progress`
- Add `turbo` to `devDependencies`
- Add `@tsconfig/bun` to `devDependencies` + catalog
- Update root scripts: `typecheck` and `build` delegate to `turbo run`
- Keep `build:api`, `build:mcp`, `build:all`, `start` as-is (deployment-specific)
- Rename `type:check` → `typecheck` in all packages (Turbo convention)

### 2. `turbo.json` (new file)

Tasks:
```json
{
  "tasks": {
    "typecheck": {},
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
    "test": { "dependsOn": ["^build"], "outputs": [] }
  }
}
```

`core` builds before `api-server`/`mcp-server` due to `^build` dep.

### 3. Root `tsconfig.json` (new file)

```json
{
  "extends": "@tsconfig/bun/tsconfig.json",
  "compilerOptions": {
    "lib": ["dom", "ESNext"],
    "target": "ESNext",
    "module": "preserve",
    "moduleResolution": "bundler",
    "strict": true,
    "noEmit": true,
    "moduleDetection": "force",
    "jsx": "react-jsx",
    "allowJs": true,
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noUnusedLocals": false,
    "noUnusedParameters": false,
    "noPropertyAccessFromIndexSignature": false
  }
}
```

### 4. Per-package `tsconfig.json` (slim)

All 3 packages slim to:
```json
{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["./src", "./test"]
}
```

### 5. `bunfig.toml` (new file)

```toml
[install]
exact = true

[test]
root = "./do-not-run-tests-from-root"
```

Exact installs = reproducible.
Root test guard prevents accidental root-level test runs.

### 6. Package `exports` field

Replace `main`/`module` with `exports` in all 3 packages:
```json
"exports": { ".": "./src/index.ts" }
```

Remove `main` and `module` fields.
Bun resolves `.ts` directly.

### 7. Catalog references in per-package `package.json`

Replace pinned versions with `"catalog:"` for shared deps:
- `@typescript/native-preview: "catalog:"`
- `@types/bun: "catalog:"`
- `@types/unidecode: "catalog:"` (core only)
- `@types/cli-progress: "catalog:"` (core only)

## Files Changed

| File | Action |
| --- | --- |
| `package.json` | Update (catalog, turbo dep, scripts) |
| `turbo.json` | Create |
| `tsconfig.json` | Create |
| `bunfig.toml` | Create |
| `packages/core/package.json` | Update (exports, catalog refs, script rename) |
| `packages/api-server/package.json` | Update (exports, catalog refs, script rename) |
| `packages/mcp-server/package.json` | Update (exports, catalog refs, script rename) |
| `packages/core/tsconfig.json` | Update (slim, extends root) |
| `packages/api-server/tsconfig.json` | Update (slim, extends root) |
| `packages/mcp-server/tsconfig.json` | Update (slim, extends root) |

## Non-Goals

- No Husky/git hooks (not needed yet)
- No SST/cloud infra (not applicable)
- No prettier (keep biome as formatter)
- No patches mechanism
- No `postinstall` scripts