Skip to content

SEED-SYSTEM.md

Latest commit

 

History

History
317 lines (257 loc) · 7.61 KB

SEED-SYSTEM.md

File metadata and controls

317 lines (257 loc) · 7.61 KB

WE Seed System

The seed system allows developers to build custom launchers by defining a we-seed.json file that specifies which applications to embed and how to configure the launcher.

Overview

A seed file is a JSON configuration that defines:

  • Project metadata (name, version, author)
  • Host customization (launcher UI, settings)
  • Embedded applications (paths, capabilities, commands)

The launcher automatically adapts based on the number of apps:

  • Single app: Full-screen layout (no sidebar)
  • Multiple apps: Sidebar navigation + app routing

Quick Start

1. Clone Required Repositories

# Clone the WE framework
git clone https://github.com/yourusername/we.git

# Clone applications you want to embed
git clone https://github.com/juntofoundation/flux.git
git clone https://github.com/yourusername/my-app.git

2. Create a Seed File

Create we/we-seed.json:

{
  "project": {
    "name": "My Custom Launcher",
    "version": "1.0.0",
    "description": "A custom launcher with my favorite apps",
    "author": "Your Name"
  },
  "host": {},
  "ad4m": {},
  "apps": [
    {
      "id": "flux",
      "name": "Flux",
      "route": "/flux",
      "capabilities": ["perspectives", "languages", "agents"],
      "paths": {
        "projectRoot": "../flux/app",
        "dist": "../flux/app/dist",
        "devServer": {
          "port": 3030,
          "host": "localhost"
        }
      },
      "commands": {
        "install": "yarn install",
        "build": "yarn build",
        "dev": "yarn dev"
      }
    }
  ]
}

3. Build and Run

cd we
pnpm install
pnpm build
cd apps/we-web
pnpm dev

Open http://localhost:3000 to see your launcher!

Seed File Schema

Project Section

{
  "project": {
    "name": "string", // Required: Display name
    "version": "string", // Required: Semantic version
    "description": "string", // Optional: Description
    "author": "string" // Required: Author name
  }
}

Host Section

{
  "host": {
    "ui": {
      "bootScreen": {}, // Optional: Custom boot screen schema
      "appSettings": {}, // Optional: Custom app settings schema
      "enableTemplateSwitching": true // Optional: Allow template switching
    }
  }
}

Note: The launcher shell UI (boot screen, app settings) can be fully customized via inline JSON schemas. See LAUNCHER-UI-CUSTOMIZATION.md for detailed examples and best practices.

Apps Section

Each app in the apps array:

{
  "id": "string", // Required: Unique identifier
  "name": "string", // Required: Display name
  "route": "/path", // Required: Route path (e.g., /flux)
  "capabilities": [], // Required: AD4M capabilities (see below)
  "paths": {
    "projectRoot": "string", // Path to app's project root
    "dist": "string", // Path to built app (production)
    "devServer": {
      "port": 3000, // Dev server port
      "host": "localhost" // Dev server host
    }
  },
  "commands": {
    "install": "string", // Install command (npm/yarn/pnpm)
    "build": "string", // Build command
    "dev": "string" // Dev server command
  }
}

Capabilities

Available AD4M capabilities:

  • perspectives - Access to AD4M perspectives
  • languages - Language management
  • agents - Agent operations
  • filesystem - File system access
  • network - Network requests

Capabilities automatically configure iframe permissions (camera, microphone, etc.).

Single vs Multi-App Mode

Single App (Full-Screen)

When apps array has 1 app:

  • App loads at root route /
  • No sidebar or navigation
  • 100% viewport width/height
  • Ideal for standalone launchers

Multiple Apps (Sidebar)

When apps array has 2+ apps:

  • Sidebar (100px) with navigation buttons
  • Each app has its own route
  • Click sidebar buttons to switch apps
  • Content area fills remaining space

Development Workflow

  1. Edit seed file: Modify we/we-seed.json
  2. Rebuild: cd packages/app-framework && pnpm build
  3. Restart dev server: cd apps/we-web && pnpm dev
  4. See changes: Refresh browser

Example: Flux-Only Launcher

{
  "project": {
    "name": "Flux Launcher",
    "version": "1.0.0",
    "author": "Your Name"
  },
  "host": {},
  "ad4m": {},
  "apps": [
    {
      "id": "flux",
      "name": "Flux",
      "route": "/",
      "capabilities": ["perspectives", "languages", "agents"],
      "paths": {
        "projectRoot": "../flux/app",
        "dist": "../flux/app/dist",
        "devServer": { "port": 3030, "host": "localhost" }
      },
      "commands": {
        "install": "yarn install",
        "build": "yarn build",
        "dev": "yarn dev"
      }
    }
  ]
}

Result: Full-screen Flux at http://localhost:3000

Example: Multi-App Launcher

{
  "project": {
    "name": "My Multi-App Workspace",
    "version": "1.0.0",
    "author": "Your Name"
  },
  "host": {},
  "ad4m": {},
  "apps": [
    {
      "id": "flux",
      "name": "Flux",
      "route": "/flux",
      "capabilities": ["perspectives", "languages", "agents"],
      "paths": {
        "projectRoot": "../flux/app",
        "dist": "../flux/app/dist",
        "devServer": { "port": 3030, "host": "localhost" }
      },
      "commands": {
        "install": "yarn install",
        "build": "yarn build",
        "dev": "yarn dev"
      }
    },
    {
      "id": "my-app",
      "name": "My App",
      "route": "/my-app",
      "capabilities": [],
      "paths": {
        "projectRoot": "../my-app",
        "dist": "../my-app/dist",
        "devServer": { "port": 3040, "host": "localhost" }
      },
      "commands": {
        "install": "npm install",
        "build": "npm run build",
        "dev": "npm run dev"
      }
    }
  ]
}

Result: Sidebar with Flux and My App navigation

Architecture

How It Works

  1. Build time: initializeIntegrations.ts imports we-seed.json via static import
  2. Module load: Seed is validated and launcher template is generated
  3. Template registration: Generated launcher replaces placeholder in templateRegistry
  4. Render time: Template store reads registry and renders launcher
  5. Runtime: Apps load in iframes with configured permissions

File Structure

we/
  we-seed.json                     ← Your seed file (REQUIRED)
  packages/app-framework/src/
    shared/
      initializeIntegrations.ts    ← Loads seed, generates launcher
      integrationComposer.ts       ← Generates template from seed
      seedLoader.ts                ← (unused) Future async loading
      registries/
        templateRegistry.ts        ← Stores generated launcher

Tips

  • Seed file location: Must be at we/we-seed.json (workspace root)
  • Requires rebuild: Changes require pnpm build in app-framework
  • Dev server ports: Ensure no conflicts (Flux: 3030, WE: 3000, etc.)
  • Path resolution: Relative paths are from workspace root (we/)

Troubleshooting

Launcher not updating?

  • Rebuild app-framework: cd packages/app-framework && pnpm build
  • Restart dev server: cd apps/we-web && pnpm dev
  • Hard refresh browser (Cmd/Ctrl + Shift + R)

App not loading in iframe?

  • Check dev server is running (e.g., cd flux/app && yarn dev)
  • Verify port in seed matches actual dev server port
  • Check browser console for CORS/permission errors

Sidebar not showing?

  • Ensure apps array has 2+ items
  • Check console for "Generating multi-app launcher" message
  • Verify each app has unique route value

Future Enhancements

  • Template forking (customize launcher UI beyond seed config)
  • Dynamic seed loading (hot-reload without rebuild)
  • Seed validation CLI tool
  • Production build support