Skip to main content

Upgrading to MoLOS v1.0.0

This guide helps you upgrade your MoLOS installation from pre-v1.0.0 versions to v1.0.0.

📋 What Changed in v1.0.0​

Module System​

  • Modules moved from external_modules/ to monorepo modules/ directory
  • Module discovery now works with workspace dependencies
  • Production builds use build-time module resolution

Database Migrations​

  • New migration system v2.1 with automatic backups and rollback support
  • Manual migration creation is now required (no auto-generation)

Import Patterns​

  • Module-internal imports must use $module alias instead of relative paths
  • Main app imports continue to use $lib alias

Components​

  • New modules must use Svelte 5 runes ($state, $derived, $props)
  • Existing modules may continue using Svelte 4 stores (migration recommended)

🔄 Pre-Migration Checklist​

Before starting migration, verify:

  • You have a backup of your current database
  • You have a backup of any custom modules
  • You're running Node.js >= 18 or Bun >= 1.0.0
  • You've read the v1.0.0 Release Notes

📦 Migrating Module Imports​

For Module Developers​

If you have custom modules or are developing new ones:

Before (Pre-v1.0.0):

// Fragile relative paths
import { TaskRepository } from '../../../../../server/repositories/task-repository.js';
import { TaskStatus } from '../../../../models/index.js';

After (v1.0.0):

// ✅ Use $module alias for module-internal imports
import { TaskRepository } from '$module/server/repositories/task-repository.js';
import { TaskStatus } from '$module/models/index.js';
import { mySchema } from '$module/server/database/schema.js';

// ✅ Use $lib alias for main app imports
import { db } from '$lib/server/db';
import { Button } from '$lib/components/ui/button';
import { auth } from '$lib/server/auth';

For Main App Developers​

Before (Pre-v1.0.0):

// Sometimes used relative paths
import { db } from '../../../../../src/lib/server/db';

After (v1.0.0):

// ✅ Always use $lib alias
import { db } from '$lib/server/db';
import { Button } from '$lib/components/ui/button';

🗄️ Database Migration Changes​

Migration Command Updates​

Before (Pre-v1.0.0):

# Auto-generate migrations (FORBIDDEN in v1.0.0)
bun run db:generate

After (v1.0.0):

# Create migration manually with descriptive name
bun run db:migration:create --name add_new_feature --module MoLOS-MyModule --reversible

# Edit the generated SQL file
vim modules/MoLOS-MyModule/drizzle/0001_add_new_feature.sql

# Apply migrations safely (auto-backup + transaction)
bun run db:migrate

Migration File Structure​

New (v1.0.0) - Reversible Migrations:

Forward migration (0001_add_feature.sql):

-- Migration: add_feature
-- Module: MoLOS-MyModule
-- Created: 2026-03-17

CREATE TABLE MoLOS-MyModule_items (
    id TEXT PRIMARY KEY,
    user_id TEXT NOT NULL,
    name TEXT NOT NULL
);

--> statement-breakpoint

CREATE INDEX idx_my_module_items_user_id ON MoLOS-MyModule_items(user_id);

Rollback migration (0001_add_feature.down.sql):

-- Rollback: add_feature
-- Module: MoLOS-MyModule
-- Created: 2026-03-17

DROP INDEX IF EXISTS idx_my_module_items_user_id;

--> statement-breakpoint

DROP TABLE IF EXISTS MoLOS-MyModule_items;

🚀 Upgrade Steps​

Step 1: Update Repository​

# Backup your current state
git branch backup-before-v1-upgrade

# Pull latest changes
git fetch origin
git checkout v1.0.0

Step 2: Update Dependencies​

# Update package manager
bun install

# Verify all packages installed correctly
bun check  # Should show no errors

Step 3: Update Module Code​

For each custom module you have:

  1. Update imports - Replace relative paths with $module alias
  2. Update migration creation - Use manual db:migration:create instead of db:generate
  3. Update component props - Use $props() for new components

Step 4: Run Database Migration​

# Apply all pending migrations (safe with auto-backup)
bun run db:migrate

# Validate schema integrity
bun run db:validate

Step 5: Start Development Server​

# Start dev server (auto-discovers and syncs modules)
bun run dev

# Verify all modules appear in sidebar
# Expected: ai, MoLOS-Tasks, MoLOS-AI-Knowledge, MoLOS-LLM-Council

🐛 Common Migration Issues​

Issue: "Could not resolve '$module/server/...'"​

Cause: Not using $module alias for module-internal imports

Solution:

// ❌ Wrong
import { repo } from '../server/repositories/file.js';

// ✅ Correct
import { repo } from '$module/server/repositories/file.js';

Issue: "Module not appearing in sidebar"​

Cause: Module not discovered or sync not run

Solution:

# Sync modules
bun run module:sync

# Check config.ts exists
ls modules/YourModule/src/config.ts

Issue: "Checksum mismatch" on migrations​

Cause: Migration file was modified after being applied

Solution:

# Option 1: Revert changes
git checkout modules/YourModule/drizzle/0001_name.sql

# Option 2: Create new migration
bun run db:migration:create --name fix_name_v2 --module YourModule

🔄 Rollback Procedure​

If migration fails:

# Stop application
pkill -f "vite|node|bun"

# Restore database from backup
cp data/molos.db.backup data/molos.db

# Rollback code changes
git checkout backup-before-v1-upgrade

# Reinstall dependencies
bun install

# Restart
bun run dev

📞 Getting Help​

If you encounter issues during migration:

  1. Check logs: tail -f logs/migrations.log
  2. Run diagnostics: bun run db:repair
  3. Review issues: GitHub Issues
  4. Ask for help: GitHub Discussions

📚 Related Documentation​

Last Updated: March 17, 2026