multica/docs/package-management.md

Package Management Guide

Overview

Super Multica uses pnpm workspaces for monorepo management. This document covers package management, dependency handling, and merge conflict resolution.

---

Directory Structure

super-multica/
├── apps/                    # Deployable applications
│   ├── cli/                 # @multica/cli
│   ├── desktop/             # @multica/desktop (Electron)
│   ├── gateway/             # @multica/gateway (NestJS WebSocket)
│   ├── server/              # @multica/server (NestJS REST)
│   ├── web/                 # @multica/web (Next.js)
│   └── mobile/              # @multica/mobile (React Native)
│
├── packages/                # Shared libraries
│   ├── core/                # @multica/core (agent, hub, channels)
│   ├── sdk/                 # @multica/sdk (gateway client)
│   ├── ui/                  # @multica/ui (shared components)
│   ├── store/               # @multica/store (Zustand)
│   ├── hooks/               # @multica/hooks (React hooks)
│   ├── types/               # @multica/types (TypeScript types)
│   └── utils/               # @multica/utils (utility functions)
│
├── skills/                  # Bundled agent skills
├── pnpm-workspace.yaml      # Workspace definition
├── pnpm-lock.yaml           # Lockfile (auto-generated)
└── .npmrc                   # pnpm configuration

---

Key Configuration Files

pnpm-workspace.yaml

Defines which directories are workspace packages:

packages:
  - "apps/*"
  - "packages/*"

.npmrc

Required configuration for Electron packaging:

shamefully-hoist=true

Why? electron-builder requires all dependencies to be hoisted to the root node_modules. Without this, Electron builds will fail with "Cannot find module" errors.

pnpm-lock.yaml

• Auto-generated lockfile
• Never manually edit
• Always regenerate on conflicts

---

Common Commands

Install Dependencies

# Install all workspace dependencies
pnpm install

# Clean install (after changing .npmrc or major updates)
rm -rf node_modules apps/*/node_modules packages/*/node_modules
rm pnpm-lock.yaml
pnpm install

Add Dependencies

# Add to root (shared dev tools)
pnpm add -D typescript -w

# Add to specific package
pnpm add lodash --filter @multica/core

# Add dev dependency to specific package
pnpm add -D vitest --filter @multica/core

# Add workspace dependency (internal package)
pnpm add @multica/utils --filter @multica/core --workspace

Update Dependencies

# Update all
pnpm update --recursive

# Update specific package
pnpm update lodash --filter @multica/core

# Interactive update
pnpm update --interactive --recursive

Run Scripts

# Run script in specific package
pnpm --filter @multica/desktop dev
pnpm --filter @multica/core build

# Run script in all packages
pnpm --recursive run build

# Run script in root
pnpm multica --help

---

Workspace Dependencies

Internal References

Use workspace:* for internal dependencies:

{
  "name": "@multica/desktop",
  "dependencies": {
    "@multica/core": "workspace:*",
    "@multica/ui": "workspace:*",
    "@multica/utils": "workspace:*"
  }
}

Dependency Direction

apps/        → depends on → packages/
packages/ui  → depends on → packages/core
packages/core → depends on → packages/types, packages/utils

❌ Circular dependencies are forbidden

Catalog (Shared Versions)

pnpm-workspace.yaml defines shared versions:

catalog:
  react: "19.2.3"
  typescript: "^5.9.3"

Use in package.json:

{
  "dependencies": {
    "react": "catalog:"
  }
}

---

Branch Merge & Conflicts

High-Conflict Files

File	Conflict Type	Resolution Strategy
pnpm-lock.yaml	Auto-generated	Always regenerate
*/package.json	Version/deps	Manual merge
pnpm-workspace.yaml	Catalog versions	Manual merge
turbo.json	Pipeline config	Manual merge

Resolving pnpm-lock.yaml Conflicts

Never manually resolve pnpm-lock.yaml conflicts. It's a machine-generated file with complex checksums.

# 1. Accept either version (doesn't matter which)
git checkout --theirs pnpm-lock.yaml
# or
git checkout --ours pnpm-lock.yaml

# 2. Delete and regenerate
rm pnpm-lock.yaml
pnpm install

# 3. Stage the new lockfile
git add pnpm-lock.yaml

# 4. Continue with merge
git merge --continue
# or
git commit

Standard Merge Workflow

# 1. Fetch and merge
git fetch origin main
git merge origin/main

# 2. If conflicts in pnpm-lock.yaml:
git checkout --theirs pnpm-lock.yaml
rm pnpm-lock.yaml
pnpm install
git add pnpm-lock.yaml

# 3. Resolve other conflicts manually
# Edit conflicted files...
git add <resolved-files>

# 4. Complete merge
git commit

# 5. Verify build
pnpm build
pnpm test

After Major Merges

Always verify:

pnpm install          # Ensure deps are correct
pnpm build            # Verify build works
pnpm test             # Run tests
pnpm typecheck        # Check types

---

Troubleshooting

"Cannot find module" in Electron Build

Cause: electron-builder can't find hoisted dependencies.

Solution:

# Ensure .npmrc has:
echo 'shamefully-hoist=true' > .npmrc

# Clean reinstall
rm -rf node_modules apps/*/node_modules packages/*/node_modules
rm pnpm-lock.yaml
pnpm install

Workspace Protocol Not Resolved

Cause: workspace:* not resolving correctly.

Solution:

# Check pnpm-workspace.yaml includes the package
# Ensure package name matches exactly
pnpm install

Peer Dependency Warnings

Cause: Missing peer dependencies.

Solution:

# Usually safe to ignore, but if causing issues:
pnpm add <missing-peer> --filter <package>

Build Order Issues

Cause: Turborepo not building dependencies first.

Solution: Check turbo.json has correct dependsOn:

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

---

Best Practices

1. Always use pnpm — Don't mix npm/yarn
2. Commit lockfile — Always commit pnpm-lock.yaml changes
3. Don't edit lockfile manually — Regenerate on conflicts
4. Use workspace:* — For internal dependencies
5. Use catalog: — For shared version management
6. Clean install after .npmrc changes — Delete node_modules and lockfile
7. Verify after merge — Run build and tests