ca-marketplace-scraper/docs/superpowers/specs/2025-07-14-opencode-monorepo-config-design.md

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:

{
  "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)

{
  "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:

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["./src", "./test"]
}

5. bunfig.toml (new file)

[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:

"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