theia App → theia IDE Migration Analysis

Created: 2025-10-26 Build Status: Build #10 running (dependency fixes applied) Objective: Migrate from custom theia-app (npm-based) to official theia-ide (git submodule) while preserving Coditect branding

Executive Summary

Current State

theia-app/: Custom NPM package (az1ai-theia-app v0.1.0) with Coditect branding
theia-ide/: Official Eclipse theia IDE v1.65.100 (newly added git submodule)

Migration Goal

Use theia-ide as the iframe IDE instead of theia-app, preserving:

✅ Coditect branding (robot logo, "Coditect AI Agents" welcome)
✅ Custom chat welcome provider
✅ Agent instructions (@ mentions)
✅ MCP SDK integration
✅ 30+ VSCode extensions

Key Differences

Aspect	theia-app	theia-ide
Source	NPM packages (^1.65.0)	Git submodule (v1.65.100)
Build	`theia build --app-target browser`	Monorepo with lerna
Packages	20 @theia/* packages	70+ @theia/* packages
Branding	Custom `coditect-branding-frontend-module`	Default "theia IDE"
Extensions	30+ bundled plugins	Plugin system
MCP	@modelcontextprotocol/sdk 1.20.1	Not included
Size	Smaller, focused	Complete IDE distribution

Detailed Component Analysis

1. Package Dependencies

theia-app Dependencies (20 packages)

{
  "@theia/core": "^1.65.0",
  "@theia/editor": "^1.65.0",
  "@theia/filesystem": "^1.65.0",
  "@theia/keymaps": "^1.65.0",
  "@theia/messages": "^1.65.0",
  "@theia/monaco": "^1.65.0",
  "@theia/navigator": "^1.65.0",
  "@theia/preferences": "^1.65.0",
  "@theia/terminal": "^1.65.0",
  "@theia/workspace": "^1.65.0",
  "@theia/ai-core": "^1.65.0",
  "@theia/ai-core-ui": "^1.65.0",
  "@theia/ai-chat": "^1.65.0",
  "@theia/ai-chat-ui": "^1.65.0",
  "@theia/ai-openai": "^1.65.0",
  "@theia/ai-ollama": "^1.65.0",
  "@theia/ai-mcp": "^1.65.0",
  "@theia/ai-code-completion": "^1.65.0",
  "@theia/ai-editor": "^1.65.0",
  "@theia/ai-history": "^1.65.0",
  "@theia/ai-ide": "^1.65.0",
  "@theia/vsx-registry": "^1.65.0",
  "@theia/plugin-ext": "^1.65.0",
  "@theia/plugin-ext-vscode": "^1.65.0",
  "@modelcontextprotocol/sdk": "1.20.1"
}

theia-ide Dependencies (70+ packages)

{
  "@theia/ai-anthropic": "1.65.1",
  "@theia/ai-chat": "1.65.1",
  "@theia/ai-chat-ui": "1.65.1",
  "@theia/ai-claude-code": "1.65.1",
  "@theia/ai-code-completion": "1.65.1",
  "@theia/ai-core": "1.65.1",
  "@theia/ai-core-ui": "1.65.1",
  "@theia/ai-editor": "1.65.1",
  "@theia/ai-google": "1.65.1",
  "@theia/ai-history": "1.65.1",
  "@theia/ai-huggingface": "1.65.1",
  "@theia/ai-ide": "1.65.1",
  "@theia/ai-llamafile": "1.65.1",
  "@theia/ai-mcp": "1.65.1",
  "@theia/ai-mcp-server": "1.65.1",
  "@theia/ai-mcp-ui": "1.65.1",
  "@theia/ai-ollama": "1.65.1",
  "@theia/ai-openai": "1.65.1",
  "@theia/ai-scanoss": "1.65.1",
  "@theia/ai-terminal": "1.65.1",
  "@theia/ai-vercel-ai": "1.65.1",
  // ... 50+ more packages
  "theia-ide-product-ext": "1.65.100"
}

Key Observations:

✅ theia-ide has MORE AI packages (anthropic, claude-code, google, huggingface, llamafile, vercel-ai)
✅ theia-ide has exact versions (1.65.1) vs caret versions (^1.65.0)
❌ theia-ide MISSING @modelcontextprotocol/sdk (need to add)
✅ theia-ide has complete feature set (dev-container, collaboration, notebook, remote, etc.)

2. Branding Implementation

Current Branding Files (theia-app)

File: theia-app/src/browser/coditect-chat-welcome-provider.tsx (114 lines)

Key Components:

CoditectAiLogo - SVG robot icon (200×200)
- Matches theia theme colors (uses CSS variables)
- Robot head with antenna
- Body with control panel
- Friendly design
CoditectChatWelcomeMessageProvider - Welcome message override
- Title: "Coditect AI Agents"
- Instructions: @ mentions for agents (@Coditect-Code-Generator, @Coditect-UI-Designer, @Coditect-Code-Reviewer)
- Context variables: #file, #_f, #selectedText
- Link to https://coditect.ai/docs
Disabled Message - When AI features disabled
- "🚀 Coditect AI Features Available!"
- Instructions to enable via settings menu

File: theia-app/src/browser/coditect-branding-frontend-module.ts (703 bytes)

Integration Pattern:

import { ContainerModule } from '@theia/core/shared/inversify';
import { ChatWelcomeMessageProvider } from '@theia/ai-chat-ui/lib/browser/chat-tree-view';
import { CoditectChatWelcomeMessageProvider } from './coditect-chat-welcome-provider';

export default new ContainerModule((bind, unbind, isBound, rebind) => {
    console.log('🎨 Coditect branding module loading...');
    rebind(ChatWelcomeMessageProvider).to(CoditectChatWelcomeMessageProvider).inSingletonScope();
    console.log('✅ Coditect branding: Rebound ChatWelcomeMessageProvider to custom implementation');
});

Package.json Integration:

{
  "theiaExtensions": [
    {
      "frontend": "lib/browser/coditect-branding-frontend-module"
    }
  ]
}

Key Insight: InversifyJS rebind() replaces theia's default ChatWelcomeMessageProvider with Coditect's custom implementation.

3. Build System Differences

theia-app Build Process

{
  "scripts": {
    "prepare": "theia build --app-target browser",
    "start": "theia start --hostname=0.0.0.0 --port=3000",
    "watch": "theia build --watch"
  },
  "devDependencies": {
    "@theia/cli": "^1.65.0"
  }
}

Build Output:

lib/ - Compiled TypeScript
src-gen/ - Generated theia code
gen-webpack.config.js - Webpack configuration

theia-ide Build Process

{
  "scripts": {
    "clean": "theia clean && rimraf node_modules",
    "build": "yarn -s rebuild && theia build --app-target=\"browser\" --mode development",
    "build:prod": "yarn -s rebuild && theia  build --app-target=\"browser\"",
    "rebuild": "theia rebuild:browser --cacheRoot ../..",
    "start": "theia start --plugins=local-dir:../../plugins",
    "watch": "concurrently --kill-others -n tsc,build -c red,yellow \"tsc -b -w --preserveWatchOutput\" \"yarn -s watch:bundle\"",
    "update:theia": "ts-node ../../scripts/update-theia-version.ts",
    "update:next": "ts-node ../../scripts/update-theia-version.ts next"
  }
}

Build Output (monorepo):

applications/browser/ - Browser application
applications/electron/ - Electron application
packages/ - Individual theia packages
plugins/ - Plugin directory

Key Difference: theia-ide is a monorepo with lerna, theia-app is a single package.

4. Configuration Differences

theia-app Configuration

{
  "theia": {
    "frontend": {
      "config": {
        "applicationName": "Coditect AI IDE",
        "defaultTheme": "dark",
        "defaultIconTheme": "vs-seti",
        "preferences": {
          "ai.openai.apiKey": "",
          "ai.ollama.models": []
        }
      }
    },
    "backend": {
      "config": {
        "startupTimeout": -1,
        "resolveSystemPlugins": false
      }
    },
    "generator": {
      "config": {
        "preloadTemplate": "./resources/preload.html"
      }
    }
  }
}

theia-ide Configuration

{
  "theia": {
    "frontend": {
      "config": {
        "applicationName": "theia IDE",
        "warnOnPotentiallyInsecureHostPattern": false,
        "preferences": {
          "toolbar.showToolbar": true,
          "files.enableTrash": false,
          "security.workspace.trust.enabled": false
        },
        "reloadOnReconnect": true
      }
    },
    "backend": {
      "config": {
        "warnOnPotentiallyInsecureHostPattern": false,
        "startupTimeout": -1,
        "resolveSystemPlugins": false,
        "configurationFolder": ".theia-ide",
        "frontendConnectionTimeout": 3000
      }
    },
    "generator": {
      "config": {
        "preloadTemplate": "./resources/preload.html"
      }
    }
  }
}

Configuration Changes Needed:

Change applicationName from "theia IDE" → "Coditect AI IDE"
Add AI preferences (openai.apiKey, ollama.models)
Keep security settings (workspace trust disabled is good)

5. Plugin System

theia-app Plugins (30+)

Bundled via theiaPlugins in package.json:

ms-python.python
vscode-eslint
prettier-vscode
gitlens
vscode-docker
rust-analyzer
... 25+ more

Installation: Downloaded from Open VSX and bundled during theia build

theia-ide Plugins

Uses plugins/ directory with local-dir plugin resolution:

{
  "start": "theia start --plugins=local-dir:../../plugins"
}

Migration Strategy: Copy plugin URLs to theia-ide or use plugin directory.

Migration Strategy

Phase 1: Preparation (No Code Changes)

Objective: Understand theia-ide structure and plan integration

Tasks:

✅ Clone theia-ide as git submodule (DONE)
✅ Analyze package.json differences (DONE)
✅ Document branding implementation (DONE)
⏳ Examine theia-ide monorepo structure
⏳ Identify extension integration points

Duration: 1-2 hours Risk: Low (no code changes)

Phase 2: Branding Integration

Objective: Add Coditect branding to theia-ide without breaking build

Tasks:

Add MCP SDK dependency to theia-ide/applications/browser/package.json:

cd theia-ide/applications/browser
yarn add @modelcontextprotocol/sdk@1.20.1

Copy branding source files:

mkdir -p theia-ide/applications/browser/src/browser
cp theia-app/src/browser/coditect-chat-welcome-provider.tsx \
   theia-ide/applications/browser/src/browser/
cp theia-app/src/browser/coditect-branding-frontend-module.ts \
   theia-ide/applications/browser/src/browser/

Update package.json configuration:

{
  "theia": {
    "frontend": {
      "config": {
        "applicationName": "Coditect AI IDE",
        "defaultTheme": "dark",
        "defaultIconTheme": "vs-seti",
        "preferences": {
          "ai.openai.apiKey": "",
          "ai.ollama.models": []
        }
      }
    }
  },
  "theiaExtensions": [
    {
      "frontend": "lib/browser/coditect-branding-frontend-module"
    }
  ]
}

Build theia-ide:

cd theia-ide/applications/browser
yarn install
yarn build:prod

Test branding:

yarn start
# Access http://localhost:3000
# Verify: "Coditect AI Agents" welcome message appears
# Verify: Robot logo displays

Duration: 2-3 hours Risk: Medium (TypeScript compilation, dependency resolution)

Rollback: Git reset to clean state if build fails

Phase 3: Plugin Migration

Objective: Copy 30+ VSCode extensions to theia-ide

Strategy 1: Plugin URLs (faster):

{
  "theiaPlugins": {
    "ms-python.python": "https://open-vsx.org/api/ms-python/python/2024.16.1/file/ms-python.python-2024.16.1.vsix",
    // ... copy all 30+ URLs from theia-app
  }
}

Strategy 2: Plugin Directory (more flexible):

# Copy plugins from theia-app if already downloaded
cp -r theia-app/plugins/* theia-ide/plugins/

Tasks:

Copy plugin URLs to theia-ide package.json
Run yarn install to download plugins
Verify plugins load correctly
Test key plugins (Python, Rust, ESLint, Prettier)

Duration: 1-2 hours Risk: Low (plugins are self-contained)

Phase 4: Docker Integration

Objective: Update dockerfile.combined-fixed to use theia-ide instead of theia-app

Current Dockerfile (theia-app):

FROM node:20 AS theia-builder
WORKDIR /app/theia-app
COPY theia-app/package*.json ./
RUN npm ci
COPY theia-app/ .
RUN npm run prepare

New Dockerfile (theia-ide):

FROM node:20 AS theia-builder
WORKDIR /app/theia-ide
COPY theia-ide/applications/browser/package*.json ./
RUN yarn install --frozen-lockfile
COPY theia-ide/ .
WORKDIR /app/theia-ide/applications/browser
RUN yarn build:prod

Changes:

Switch from npm to yarn (theia-ide uses yarn workspaces)
Copy entire theia-ide monorepo (not just applications/browser)
Build from applications/browser subdirectory

Tasks:

Update dockerfile.combined-fixed (theia-builder stage)
Update .dockerignore to exclude theia-app

Test local Docker build:

docker build -f dockerfile.combined-fixed -t test-theia-ide .
docker run -p 3000:3000 test-theia-ide

Verify theia IDE loads at http://localhost:3000
Verify Coditect branding appears

Duration: 1-2 hours Risk: Medium (Docker caching, build context size)

Phase 5: GKE Deployment

Objective: Deploy theia-ide to production GKE with Build #11

Prerequisites:

✅ Build #10 successful (dependency fixes)
✅ Branding integration complete (Phase 2)
✅ Docker build successful (Phase 4)

Tasks:

Ensure theia-ide submodule committed:

git add theia-ide
git commit -m "feat: Migrate to official Eclipse theia IDE v1.65.100 with Coditect branding"

Submit Cloud Build (Build #11):

cd /home/hal/v4/PROJECTS/t2
gcloud builds submit --config cloudbuild-combined.yaml \
  --project serene-voltage-464305-n2 2>&1 | tee /tmp/build-log-v11.txt

Monitor build:
```
tail -f /tmp/build-log-v11.txt
```

Update GKE deployment:

kubectl set image deployment/coditect-combined \
  combined=us-central1-docker.pkg.dev/serene-voltage-464305-n2/coditect/coditect-combined:<BUILD_ID> \
  -n coditect-app

Test production:

curl -I https://coditect.ai/theia
# Verify: 200 OK
# Open browser: https://coditect.ai/theia
# Verify: "Coditect AI Agents" welcome message

Duration: 30-45 minutes (build time) Risk: Low (incremental change, can rollback)

Branding Preservation Checklist

Required Elements

✅ Robot logo SVG (200×200, theme-aware colors)
✅ Welcome message: "Coditect AI Agents"
✅ Agent instructions: @ mentions (@Coditect-Code-Generator, etc.)
✅ Context variables: #file, #_f, #selectedText
✅ Documentation link: https://coditect.ai/docs
✅ Disabled message: "🚀 Coditect AI Features Available!"
✅ Settings link for enabling AI features

Integration Points

✅ ChatWelcomeMessageProvider rebind via InversifyJS
✅ theiaExtensions configuration in package.json
✅ applicationName: "Coditect AI IDE"
✅ Default theme: dark
✅ Default icon theme: vs-seti

Testing Verification

# 1. Welcome message appears
# 2. Robot logo displays
# 3. Agent instructions visible
# 4. Theme colors match (CSS variables work)
# 5. Documentation link clickable
# 6. Disabled message shows when AI disabled
# 7. Settings link opens preferences

Risk Assessment

High Risk Items

Monorepo Build Complexity
- Risk: theia-ide monorepo has complex build dependencies
- Mitigation: Follow official build instructions exactly
- Fallback: Use theia-app until theia-ide build stable
Docker Build Size
- Risk: theia-ide includes entire monorepo (larger than theia-app)
- Mitigation: Use multi-stage build, exclude unnecessary files
- Fallback: Build only applications/browser, exclude other apps
Plugin Compatibility
- Risk: Plugins may not work with theia-ide plugin system
- Mitigation: Test key plugins first (Python, Rust, ESLint)
- Fallback: Use fewer plugins initially, add incrementally

Medium Risk Items

Branding Integration
- Risk: InversifyJS rebind may not work in monorepo structure
- Mitigation: Test locally before Docker build
- Fallback: Patch theia-ide directly if extension system fails
MCP SDK Integration
- Risk: @modelcontextprotocol/sdk may conflict with theia-ide dependencies
- Mitigation: Use exact version 1.20.1
- Fallback: Update to latest compatible version

Low Risk Items

Configuration Changes
- Risk: applicationName change is trivial
- Mitigation: None needed
- Fallback: N/A
Theme Settings
- Risk: Theme configuration is well-documented
- Mitigation: None needed
- Fallback: N/A

Next Steps (Immediate Actions)

1. Wait for Build #10 Completion

Status: Build #10 running (archive creation phase) ETA: 25-35 minutes Action: Monitor /tmp/build-log-v10.txt for completion

2. Examine theia-ide Structure

cd /home/hal/v4/PROJECTS/t2/theia-ide
ls -la applications/browser/
cat applications/browser/package.json
ls -la packages/

3. Create Branding Integration Branch

git checkout -b feature/theia-ide-branding

4. Test Local theia-ide Build

cd theia-ide/applications/browser
yarn install
yarn build
yarn start

5. Plan Build #11 Strategy

Verify Build #10 successful (all Rust binaries compile)
Add branding integration to theia-ide
Update dockerfile.combined-fixed
Submit Build #11 with theia-ide

Questions to Resolve

Technical Questions

Does theia-ide monorepo build work in Docker BuildKit?
- Test: Local Docker build before Cloud Build
- Concern: Yarn workspaces, lerna overhead
Does ChatWelcomeMessageProvider rebind work in monorepo?
- Test: Local build with branding integration
- Concern: Module resolution differences
What is the built output directory for theia-ide?
- Current (theia-app): lib/backend/main.js
- Unknown (theia-ide): Need to verify
How do theia-ide extensions differ from theia-app?
- theia-app uses theiaExtensions in package.json
- theia-ide might use different extension system

Operational Questions

Should we keep theia-app as fallback?
- Yes: Maintain both until theia-ide proven in production
- No: Clean migration, delete theia-app
When to migrate plugins?
- Phase 3 (after branding integration works)
- Phase 5 (after GKE deployment)
How to handle build failures?
- Keep theia-app in Docker until theia-ide stable
- Use feature flag to switch between theia-app and theia-ide

Success Criteria

Phase 2 Success (Branding Integration)

✅ theia-ide builds successfully with Coditect branding
✅ "Coditect AI Agents" welcome message appears
✅ Robot logo displays correctly
✅ Theme colors work (CSS variables)
✅ Agent instructions visible
✅ Documentation link functional

Phase 4 Success (Docker Integration)

✅ Docker build completes without errors
✅ Container starts successfully
✅ theia IDE loads at http://localhost:3000
✅ Coditect branding preserved in container

Phase 5 Success (GKE Deployment)

✅ Build #11 completes successfully
✅ GKE deployment updates without downtime
✅ https://coditect.ai/theia loads with Coditect branding
✅ All plugins functional
✅ AI features work (LM Studio integration)

Appendix

File Locations

theia-app (Current)

theia-app/
├── package.json
├── src/
│   └── browser/
│       ├── coditect-chat-welcome-provider.tsx
│       └── coditect-branding-frontend-module.ts
├── lib/              # Compiled output
├── src-gen/          # Generated theia code
└── plugins/          # Downloaded VSCode extensions

theia-ide (Target)

theia-ide/
├── applications/
│   ├── browser/
│   │   ├── package.json
│   │   ├── src/
│   │   │   └── browser/
│   │   │       ├── coditect-chat-welcome-provider.tsx (COPY HERE)
│   │   │       └── coditect-branding-frontend-module.ts (COPY HERE)
│   │   └── lib/      # Build output
│   └── electron/
├── packages/         # theia packages monorepo
└── plugins/          # Plugin directory

Build Commands Summary

# theia-app (Current)
cd theia-app
npm ci
npm run prepare

# theia-ide (Target)
cd theia-ide/applications/browser
yarn install --frozen-lockfile
yarn build:prod

Docker Stage Comparison

# BEFORE (theia-app)
FROM node:20 AS theia-builder
WORKDIR /app/theia-app
COPY theia-app/package*.json ./
RUN npm ci
COPY theia-app/ .
RUN npm run prepare

# AFTER (theia-ide)
FROM node:20 AS theia-builder
WORKDIR /app
COPY theia-ide/package*.json theia-ide/yarn.lock ./
COPY theia-ide/applications/browser/package*.json ./applications/browser/
RUN yarn install --frozen-lockfile
COPY theia-ide/ .
WORKDIR /app/applications/browser
RUN yarn build:prod

Document Status: DRAFT Next Update: After Build #10 completion Owner: Migration team Reviewers: Architecture, DevOps, QA

Executive Summary​

Current State​

Migration Goal​

Key Differences​

Detailed Component Analysis​

1. Package Dependencies​

theia-app Dependencies (20 packages)​

theia-ide Dependencies (70+ packages)​

2. Branding Implementation​

Current Branding Files (theia-app)​

3. Build System Differences​

theia-app Build Process​

theia-ide Build Process​

4. Configuration Differences​

theia-app Configuration​

theia-ide Configuration​

5. Plugin System​

theia-app Plugins (30+)​

theia-ide Plugins​

Migration Strategy​

Phase 1: Preparation (No Code Changes)​

Phase 2: Branding Integration​

Phase 3: Plugin Migration​

Phase 4: Docker Integration​

Phase 5: GKE Deployment​

Branding Preservation Checklist​

Required Elements​

Integration Points​

Testing Verification​

Risk Assessment​

High Risk Items​

Medium Risk Items​

Low Risk Items​

Next Steps (Immediate Actions)​

1. Wait for Build #10 Completion​

2. Examine theia-ide Structure​

3. Create Branding Integration Branch​

4. Test Local theia-ide Build​

5. Plan Build #11 Strategy​

Questions to Resolve​

Technical Questions​

Operational Questions​

Success Criteria​

Phase 2 Success (Branding Integration)​

Phase 4 Success (Docker Integration)​

Phase 5 Success (GKE Deployment)​

Appendix​

File Locations​

theia-app (Current)​

theia-ide (Target)​

Build Commands Summary​

Docker Stage Comparison​

Executive Summary

Current State

Migration Goal

Key Differences

Detailed Component Analysis

1. Package Dependencies

theia-app Dependencies (20 packages)

theia-ide Dependencies (70+ packages)

2. Branding Implementation

Current Branding Files (theia-app)

3. Build System Differences

theia-app Build Process

theia-ide Build Process

4. Configuration Differences

theia-app Configuration

theia-ide Configuration

5. Plugin System

theia-app Plugins (30+)

theia-ide Plugins

Migration Strategy

Phase 1: Preparation (No Code Changes)

Phase 2: Branding Integration

Phase 3: Plugin Migration

Phase 4: Docker Integration

Phase 5: GKE Deployment

Branding Preservation Checklist

Required Elements

Integration Points

Testing Verification

Risk Assessment

High Risk Items

Medium Risk Items

Low Risk Items

Next Steps (Immediate Actions)

1. Wait for Build #10 Completion

2. Examine theia-ide Structure

3. Create Branding Integration Branch

4. Test Local theia-ide Build

5. Plan Build #11 Strategy

Questions to Resolve

Technical Questions

Operational Questions

Success Criteria

Phase 2 Success (Branding Integration)

Phase 4 Success (Docker Integration)

Phase 5 Success (GKE Deployment)

Appendix

File Locations

theia-app (Current)

theia-ide (Target)

Build Commands Summary

Docker Stage Comparison