docs: add opencode monorepo config adoption design spec

2026-04-28 19:50:51 -04:00
parent bf393eacae
commit d10d5305a3
1 changed files with 136 additions and 0 deletions
--- a/docs/superpowers/specs/2025-07-14-opencode-monorepo-config-design.md
+++ b/docs/superpowers/specs/2025-07-14-opencode-monorepo-config-design.md
@@ -0,0 +1,136 @@
+# 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