opencode-swarm-plugin 0.21.0 → 0.23.0

package/docs/planning/ADR-001-monorepo-structure.md

@@ -0,0 +1,171 @@
+# ADR-001: Monorepo Structure with Turborepo and Bun
+
+## Status
+
+Proposed
+
+## Context
+
+The opencode-swarm-plugin is currently a single-package TypeScript project. We need to extract the Swarm Mail actor-model primitives into a standalone package that can be:
+
+1. Published independently to npm for use in other projects
+2. Maintained with proper versioning and changelogs
+3. Developed alongside the OpenCode plugin without tight coupling
+4. Tested and built independently
+
+Research into modern monorepo solutions shows Turborepo + Bun provides:
+
+- Full compatibility (package-manager agnostic)
+- High-performance caching and incremental builds
+- Proven at scale (Vercel, PGLite's 9-package monorepo)
+- Excellent TypeScript support
+- Changesets integration for publishing
+
+Alternative considered: pnpm workspaces alone (rejected due to lack of task orchestration and caching).
+
+## Decision
+
+Adopt a Turborepo + Bun monorepo structure with:
+
+```
+opencode-swarm-plugin/
+├── packages/
+│   └── swarm-mail/            # ~3K lines - Actor-model primitives
+│       ├── src/
+│       │   ├── streams/       # Event sourcing, projections, store
+│       │   ├── agent-mail.ts  # High-level API
+│       │   └── index.ts
+│       ├── package.json       # Independent versioning, published as "swarm-mail"
+│       └── tsconfig.json
+├── src/                       # opencode-swarm-plugin source (stays at root)
+│   ├── beads.ts
+│   ├── swarm-*.ts
+│   └── plugin.ts
+├── apps/
+│   └── devtools/              # Future: SvelteKit DevTools UI
+├── turbo.json                 # Task pipeline definitions
+├── package.json               # Root = opencode-swarm-plugin, depends on swarm-mail
+└── .changeset/                # Publishing workflow
+```
+
+**Package naming:**
+
+- `swarm-mail` - Standalone actor-model library (npm: `swarm-mail`)
+- `opencode-swarm-plugin` - OpenCode integration (npm: `opencode-swarm-plugin`, depends on swarm-mail)
+
+Note: `swarm-mail` is intentionally agnostic of OpenCode - it's a general-purpose actor-model library that can be used in any TypeScript project.
+
+**Workspace dependencies:**
+
+```json
+{
+  "dependencies": {
+    "swarm-mail": "workspace:*"
+  }
+}
+```
+
+**Task pipeline (turbo.json):**
+
+```json
+{
+  "pipeline": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**"]
+    },
+    "test": {
+      "dependsOn": ["^build"]
+    },
+    "typecheck": {
+      "dependsOn": ["^build"]
+    }
+  }
+}
+```
+
+**Publishing workflow:**
+
+- Changesets for version management
+- Independent versioning per package
+- Automated changelog generation
+- CI/CD integration for npm publish
+
+## Consequences
+
+### Easier
+
+- **Independent publishing** - `swarm-mail` can be used in any TypeScript project
+- **Clear boundaries** - Separation forces clean API design
+- **Parallel development** - Teams can work on packages independently
+- **Incremental builds** - Turborepo caches unchanged packages
+- **Type safety** - TypeScript project references ensure compile order
+- **Versioning** - Changesets tracks breaking changes per package
+
+### More Difficult
+
+- **Initial migration** - ~2-3 days to restructure existing code
+- **Breaking changes** - Extracting swarm-mail may reveal tight coupling
+- **Circular dependencies** - Must carefully design package boundaries
+- **Version conflicts** - Workspace deps must align across packages
+- **Build complexity** - More moving parts (mitigated by Turborepo automation)
+- **Learning curve** - Team must learn Turborepo conventions
+
+### Risks & Mitigations
+
+| Risk                               | Impact | Mitigation                                       |
+| ---------------------------------- | ------ | ------------------------------------------------ |
+| Breaking changes during extraction | High   | Feature branch, comprehensive test suite         |
+| Circular dependencies              | High   | Use dependency-cruiser to detect cycles          |
+| Version conflicts                  | Medium | Pin shared deps in root package.json             |
+| Build failures in CI               | Medium | Turborepo remote caching, isolated test runs     |
+| Overcomplicated structure          | Low    | Start with 2 packages, add more only when needed |
+
+## Implementation Notes
+
+### Phase 1: Initial Setup (Day 1)
+
+1. Install Turborepo and configure turbo.json
+2. Create packages/@swarm/mail and packages/@swarm/plugin directories
+3. Set up workspace dependencies in root package.json
+4. Configure TypeScript project references
+
+### Phase 2: Extract swarm-mail (Day 2-3)
+
+1. Move src/streams/\* to packages/swarm-mail/src/streams/
+2. Move agent-mail.ts, swarm-mail.ts to swarm-mail
+3. Update imports in opencode-swarm-plugin to use swarm-mail
+4. Run typecheck and fix breaking changes
+5. Migrate integration tests
+
+### Phase 3: CI/CD (Day 4)
+
+1. Update GitHub Actions to use `turbo run build test`
+2. Configure Changesets for publishing
+3. Add pre-commit hooks for type checking
+4. Document publishing workflow in CONTRIBUTING.md
+
+### Phase 4: Documentation (Day 5)
+
+1. Write swarm-mail README with API examples
+2. Create migration guide for existing users
+3. Add inline JSDoc comments for public API
+4. Generate TypeDoc API reference
+
+### Success Criteria
+
+- [ ] `bun run build` builds both packages in correct order
+- [ ] `bun run test` passes all tests in isolation
+- [ ] opencode-swarm-plugin can import from swarm-mail without errors
+- [ ] Changesets generates valid changelog entries
+- [ ] CI builds complete in <2 minutes (with caching)
+- [ ] Published swarm-mail package works in standalone project
+
+### Reference Implementation
+
+PGLite monorepo structure: https://github.com/electric-sql/pglite
+
+- 9 packages with scoped naming (@electric-sql/\*)
+- workspace:\* dependencies
+- Changesets publishing workflow
+- Independent versioning per package

package/docs/planning/ADR-002-package-extraction.md

@@ -0,0 +1,393 @@
+# ADR-002: Package Extraction Strategy
+
+## Status
+
+Proposed
+
+## Context
+
+Following ADR-001's decision to adopt a monorepo structure, we need a detailed strategy for extracting the Swarm Mail actor-model primitives from the existing opencode-swarm-plugin codebase into a standalone `swarm-mail` package.
+
+The extraction must:
+
+1. Preserve all functionality without breaking changes
+2. Maintain backward compatibility for existing plugin users
+3. Provide clean API boundaries between packages
+4. Support independent versioning and publishing
+
+**Current Structure:**
+
+- `src/streams/` - Event sourcing primitives (~1.5K lines)
+- `src/agent-mail.ts` - High-level API (~500 lines)
+- `src/swarm-mail.ts` - Integration layer (~200 lines)
+- Integration tests scattered across codebase
+
+**Target Structure:**
+
+- `packages/swarm-mail` - Standalone actor-model library
+- `packages/opencode-swarm-plugin` - OpenCode integration (depends on swarm-mail)
+
+## Decision
+
+### Phase 1: Boundary Analysis (Pre-extraction)
+
+**1.1 Identify Public API Surface**
+
+```typescript
+// swarm-mail will export:
+export {
+  initializeSwarmMail,
+  sendMessage,
+  getInbox,
+  readMessage,
+  reserveFiles,
+  releaseReservations,
+} from "./agent-mail";
+export { SwarmMailStore, appendEvent, queryProjection } from "./streams/store";
+export { MailboxService, LockService, AskService } from "./streams/effect";
+export type { SwarmMailEvent, Message, FileReservation } from "./schemas";
+```
+
+**1.2 Dependency Audit**
+Use `dependency-cruiser` to detect:
+
+- Circular dependencies (fail build if found)
+- External dependencies (must be in swarm-mail package.json)
+- Internal coupling (refactor before extraction)
+
+```bash
+npx depcruise --config .dependency-cruiser.js src/
+```
+
+**1.3 Breaking Change Detection**
+Run full test suite with coverage:
+
+- Integration tests must pass 100%
+- Type checking must succeed
+- Public API must remain unchanged
+
+### Phase 2: Extraction Steps
+
+**2.1 Create Package Structure**
+
+```bash
+mkdir -p packages/swarm-mail/src/{streams,effect}
+mkdir -p packages/opencode-swarm-plugin/src
+```
+
+**2.2 Move Files (Atomic Operation)**
+
+```bash
+# Streams infrastructure
+git mv src/streams/* packages/swarm-mail/src/streams/
+
+# Agent Mail API
+git mv src/agent-mail.ts packages/swarm-mail/src/
+git mv src/swarm-mail.ts packages/swarm-mail/src/
+
+# Schemas
+git mv src/schemas/swarm-context.ts packages/swarm-mail/src/schemas/
+```
+
+**2.3 Update Imports**
+
+```typescript
+// Before (in opencode-swarm-plugin):
+import { initializeSwarmMail } from "../agent-mail";
+
+// After:
+import { initializeSwarmMail } from "swarm-mail";
+```
+
+Run AST-based codemod:
+
+```bash
+npx jscodeshift -t codemods/update-imports.js packages/opencode-swarm-plugin/src/**/*.ts
+```
+
+**2.4 Configure Package Dependencies**
+
+```json
+// packages/swarm-mail/package.json
+{
+  "name": "swarm-mail",
+  "version": "0.1.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "effect": "^3.12.3",
+    "@electric-sql/pglite": "^0.2.14",
+    "zod": "^3.24.1"
+  }
+}
+
+// packages/opencode-swarm-plugin/package.json
+{
+  "name": "opencode-swarm-plugin",
+  "dependencies": {
+    "swarm-mail": "workspace:*"
+  }
+}
+```
+
+**2.5 Migrate Tests**
+
+```bash
+# Integration tests for swarm-mail
+git mv src/agent-mail.integration.test.ts packages/swarm-mail/src/
+git mv src/swarm-mail.integration.test.ts packages/swarm-mail/src/
+git mv src/streams/**/*.test.ts packages/swarm-mail/src/streams/
+
+# Plugin-specific tests stay in opencode-swarm-plugin
+# Update test imports to use swarm-mail
+```
+
+### Phase 3: API Cleanup
+
+**3.1 Define Public Exports**
+
+```typescript
+// packages/swarm-mail/src/index.ts
+export {
+  // High-level API
+  initializeSwarmMail,
+  sendMessage,
+  getInbox,
+  readMessage,
+  summarizeThread,
+  reserveFiles,
+  releaseReservations,
+  acknowledgeMessage,
+} from "./agent-mail";
+
+export {
+  // Effect Services
+  MailboxService,
+  LockService,
+  AskService,
+  DurableDeferred,
+} from "./streams/effect";
+
+export {
+  // Event Sourcing
+  SwarmMailStore,
+  appendEvent,
+  queryProjection,
+} from "./streams/store";
+
+export type {
+  // Types
+  SwarmMailEvent,
+  Message,
+  FileReservation,
+  AgentRegistration,
+} from "./schemas";
+```
+
+**3.2 Mark Internal APIs**
+Use JSDoc `@internal` for non-public exports:
+
+```typescript
+/**
+ * @internal
+ * Internal projection builder - do not use outside swarm-mail
+ */
+export const buildProjection = ...
+```
+
+**3.3 Version Exports**
+Support both named and default exports:
+
+```typescript
+// Allow: import { initializeSwarmMail } from 'swarm-mail'
+// Allow: import SwarmMail from 'swarm-mail'
+export default {
+  initializeSwarmMail,
+  sendMessage,
+  // ...
+};
+```
+
+### Phase 4: Backward Compatibility (Transition Period)
+
+**4.1 Re-export from Plugin**
+
+```typescript
+// packages/opencode-swarm-plugin/src/agent-mail.ts (deprecated wrapper)
+/**
+ * @deprecated Import from 'swarm-mail' instead
+ */
+export {
+  initializeSwarmMail,
+  sendMessage,
+  // ...
+} from "swarm-mail";
+```
+
+**4.2 Add Deprecation Warnings**
+
+```typescript
+// packages/opencode-swarm-plugin/src/index.ts
+if (process.env.NODE_ENV !== "production") {
+  console.warn(
+    "[opencode-swarm-plugin] Importing agent-mail APIs from opencode-swarm-plugin is deprecated. " +
+      'Import from swarm-mail instead: import { initializeSwarmMail } from "swarm-mail"',
+  );
+}
+```
+
+**4.3 Migration Timeline**
+
+- v0.1.0 - Initial extraction, both packages work
+- v0.2.0 - Add deprecation warnings
+- v1.0.0 - Remove re-exports, swarm-mail required
+
+### Phase 5: Verification
+
+**5.1 Build Verification**
+
+```bash
+# Clean build
+rm -rf node_modules packages/*/dist
+bun install
+
+# Build all packages
+turbo run build
+
+# Expected: swarm-mail builds first, then opencode-swarm-plugin
+```
+
+**5.2 Test Verification**
+
+```bash
+# Run all tests
+turbo run test
+
+# Expected: All integration tests pass
+# Expected: No type errors
+```
+
+**5.3 Publish Dry Run**
+
+```bash
+# Test publishing workflow
+npx changeset add
+npx changeset version
+npm pack --dry-run
+
+# Expected: Valid tarball for swarm-mail
+```
+
+## Consequences
+
+### Easier
+
+- **Independent publishing** - swarm-mail can be versioned separately
+- **Clear boundaries** - Public API explicitly defined
+- **Standalone usage** - Other projects can use swarm-mail without plugin
+- **Focused testing** - swarm-mail tests independent of plugin
+- **Type safety** - TypeScript enforces package boundaries
+
+### More Difficult
+
+- **Import paths change** - All consumers must update imports
+- **Two-package maintenance** - Breaking changes require coordination
+- **Version alignment** - opencode-swarm-plugin must specify compatible swarm-mail version
+- **Testing complexity** - Must test both standalone and integrated usage
+
+### Risks & Mitigations
+
+| Risk                               | Impact   | Mitigation                                        |
+| ---------------------------------- | -------- | ------------------------------------------------- |
+| Breaking changes during extraction | Critical | Feature branch, full test coverage, manual QA     |
+| Missed dependencies                | High     | dependency-cruiser validation, build from scratch |
+| Import path confusion              | Medium   | Clear migration guide, deprecation warnings       |
+| Circular dependencies              | High     | Pre-extraction analysis, dependency-cruiser gate  |
+| Version mismatch bugs              | Medium   | Peer dependency constraints, CI matrix testing    |
+
+## Implementation Notes
+
+### Pre-Extraction Checklist
+
+- [ ] Run dependency-cruiser to detect circular deps
+- [ ] Audit all imports in src/streams/, src/agent-mail.ts
+- [ ] Document current public API surface
+- [ ] Create feature branch for extraction
+- [ ] Ensure all tests pass with 100% coverage
+
+### Extraction Checklist
+
+- [ ] Create packages/swarm-mail directory structure
+- [ ] Move src/streams/\* to swarm-mail
+- [ ] Move agent-mail.ts, swarm-mail.ts to swarm-mail
+- [ ] Update all imports in opencode-swarm-plugin
+- [ ] Configure package.json dependencies
+- [ ] Migrate integration tests
+- [ ] Add index.ts with public exports
+- [ ] Build both packages
+- [ ] Run full test suite
+
+### Post-Extraction Checklist
+
+- [ ] Add deprecation warnings in opencode-swarm-plugin
+- [ ] Write migration guide for users
+- [ ] Generate TypeDoc for swarm-mail API
+- [ ] Add README with usage examples
+- [ ] Configure Changesets for versioning
+- [ ] Publish swarm-mail@0.1.0 to npm
+- [ ] Update opencode-swarm-plugin to depend on published version
+
+### Success Criteria
+
+- [ ] `bun run build` succeeds for both packages
+- [ ] All integration tests pass
+- [ ] No circular dependencies detected
+- [ ] Published swarm-mail works in standalone project
+- [ ] opencode-swarm-plugin works with published swarm-mail
+- [ ] Type checking passes with no errors
+- [ ] Migration guide tested with real user
+
+### Codemod Example (update-imports.js)
+
+```javascript
+module.exports = function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+
+  // Replace ../agent-mail with swarm-mail
+  root
+    .find(j.ImportDeclaration, {
+      source: {
+        value: (v) =>
+          v.includes("../agent-mail") || v.includes("../swarm-mail"),
+      },
+    })
+    .forEach((path) => {
+      path.node.source.value = "swarm-mail";
+    });
+
+  return root.toSource();
+};
+```
+
+### Dependency Cruiser Config
+
+```javascript
+// .dependency-cruiser.js
+module.exports = {
+  forbidden: [
+    {
+      name: "no-circular",
+      severity: "error",
+      from: {},
+      to: { circular: true },
+    },
+    {
+      name: "no-plugin-in-mail",
+      severity: "error",
+      from: { path: "^packages/swarm-mail" },
+      to: { path: "^packages/opencode-swarm-plugin" },
+    },
+  ],
+};
+```