saeeol 1.4.2 → 1.4.3

package/src/overlay/docs/migration.md

@@ -1,398 +0,0 @@
-# Saeeol Migration
-
-This document explains how Saeeol configurations are automatically migrated to Opencode.
-
-## Table of Contents
-
-- [Modes Migration](#modes-migration)
-- [Skills Discovery](#skills-discovery)
-- [Rules Migration](#rules-migration)
-- [Workflows Migration](#workflows-migration)
-- [MCP Migration](#mcp-migration)
-- [Saeeol Notifications](#saeeol-notifications)
-
----
-
-# Modes Migration
-
-This section explains how Saeeol custom modes are automatically migrated to Opencode agents.
-
-## Overview
-
-Saeeol stores custom modes in YAML files. When Opencode starts, it reads these files and converts them to Opencode's agent format, injecting them via the `SAEEOL_CONFIG_CONTENT` mechanism.
-
-## Source Locations
-
-The migrator reads custom modes from these locations (in order, later entries override earlier ones):
-
-### Global Modes (VSCode Extension Storage)
-
-| Platform | Path |
-|---|---|
-| macOS | `~/Library/Application Support/Code/User/globalStorage/saeeol.saeeol/settings/custom_modes.yaml` |
-| Windows | `%APPDATA%/Code/User/globalStorage/saeeol.saeeol/settings/custom_modes.yaml` |
-| Linux | `~/.config/Code/User/globalStorage/saeeol.saeeol/settings/custom_modes.yaml` |
-
-### Project Modes
-
-| Location | Description |
-|---|---|
-| `.saeeolmodes` | Project-specific modes in the workspace root |
-
-## Field Mapping
-
-### Migrated Fields
-
-| Saeeol Field | Opencode Field | Notes |
-|---|---|---|
-| `slug` | Agent key | Used as the agent identifier |
-| `roleDefinition` | `prompt` | Combined with `customInstructions` |
-| `customInstructions` | `prompt` | Appended after `roleDefinition` with `\n\n` separator |
-| `groups` | `permission` | See permission mapping below |
-| `description` | `description` | Primary source for description |
-| `whenToUse` | `description` | Fallback if no `description` |
-| `name` | `description` | Final fallback |
-
-### Permission Mapping
-
-Saeeol uses "groups" to define what tools a mode can access. These are converted to Opencode's permission system:
-
-| Saeeol Group | Opencode Permission | Notes |
-|---|---|---|
-| `read` | `read: "allow"` | File reading |
-| `edit` | `edit: "allow"` | File editing |
-| `command` | `bash: "allow"` | Shell commands |
-| `browser` | `bash: "allow"` | Browser actions (via bash) |
-| `mcp` | `mcp: "allow"` | MCP server access |
-
-**Important:** Permissions that are NOT in the groups list are explicitly set to `"deny"`. This ensures that a mode with only `read` and `edit` groups cannot run shell commands or access MCP servers.
-
-### File Restrictions
-
-Saeeol supports restricting edit access to specific file patterns:
-
-```yaml
-groups:
-  - read
-  - - edit
-    - fileRegex: "\\.md$"
-      description: "Markdown files only"
-```
-
-This converts to:
-
-```json
-{
-  "permission": {
-    "read": "allow",
-    "edit": {
-      "\\.md$": "allow",
-      "*": "deny"
-    },
-    "bash": "deny",
-    "mcp": "deny"
-  }
-}
-```
-
-Note: `bash` and `mcp` are explicitly denied because they weren't in the original groups list.
-
-## Default Modes
-
-The following Saeeol default modes are **skipped** during migration because Opencode has native equivalents:
-
-| Saeeol Mode | Reason |
-|---|---|
-| `code` | Maps to Opencode's `build` agent |
-| `architect` | Maps to Opencode's `plan` agent |
-| `ask` | Read-only exploration (use `explore` subagent) |
-| `debug` | Debugging workflow (use `build` with debug instructions) |
-| `orchestrator` | Redundant - all Opencode agents can spawn subagents |
-
-## Example Conversion
-
-### Saeeol Mode (YAML)
-
-```yaml
-customModes:
-  - slug: translate
-    name: Translate
-    roleDefinition: You are a linguistic specialist focused on translation.
-    customInstructions: |
-      When translating:
-      - Maintain consistent terminology
-      - Preserve formatting
-    groups:
-      - read
-      - - edit
-        - fileRegex: "src/i18n/.*\\.json$"
-          description: "Translation files only"
-    description: Translate content between languages
-```
-
-### Opencode Agent (JSON)
-
-```json
-{
-  "agent": {
-    "translate": {
-      "mode": "primary",
-      "description": "Translate content between languages",
-      "prompt": "You are a linguistic specialist focused on translation.\n\nWhen translating:\n- Maintain consistent terminology\n- Preserve formatting",
-      "permission": {
-        "read": "allow",
-        "edit": {
-          "src/i18n/.*\\.json$": "allow",
-          "*": "deny"
-        }
-      }
-    }
-  }
-}
-```
-
-## Not Migrated (Future Phases)
-
-The following Saeeol features are not yet migrated:
-
-| Feature | Status | Notes |
-|---|---|---|
-| Rules (`.saeeol/rules/`) | Phase 2 | Will map to `instructions` array |
-| Workflows (`.saeeol/workflows/`) | Phase 2 | Will map to custom commands |
-| MCP Servers (`mcp_settings.json`) | Phase 2 | Will map to `mcp` config |
-| Provider Settings | Phase 2 | Will map to `provider` config |
-| Mode-specific API configs | Phase 2 | Different models per mode |
-| Organization modes | Not planned | `source: organization` not preserved |
-
-## Troubleshooting
-
-### Mode not appearing
-
-1. Check the file exists at the expected location
-2. Verify YAML syntax is valid
-3. Ensure the mode has a unique `slug`
-4. Check it's not a default mode (which are skipped)
-
-### Permissions not working
-
-1. Verify the `groups` array is correctly formatted
-2. For file restrictions, ensure `fileRegex` is a valid regex
-3. Check the permission mapping table above
-
-## Related Files
-
-- [`modes-migrator.ts`](../modes-migrator.ts) - Core migration logic
-- [`config-injector.ts`](../config-injector.ts) - Config building and injection
-
----
-
-# Skills Discovery
-
-Saeeol skills are automatically discovered and made available in Opencode. This is **not a migration** - skills remain in their original locations and can be managed independently by the Saeeol VSCode extension.
-
-## How It Works
-
-Opencode scans additional directories for skills alongside its native `.saeeol/skill/` locations. The `SaeeolPaths.skillDirectories()` function provides these paths.
-
-## Source Locations
-
-Skills are discovered from these locations (in order, later entries override earlier ones):
-
-### Project Skills (Walk-up Discovery)
-
-The scanner walks up from the current directory to the git worktree root, finding all `.saeeol/skills/` directories:
-
-```
-your-project/
-├── .saeeol/
-│   └── skills/
-│       └── project-skill/
-│           └── SKILL.md
-└── packages/
-    └── my-package/           # If you run from here
-        └── .saeeol/
-            └── skills/
-                └── package-skill/
-                    └── SKILL.md
-```
-
-Running from `packages/my-package/` discovers both `package-skill` and `project-skill`.
-
-### Global Skills
-
-| Platform | Path |
-|---|---|
-| All | `~/.saeeol/skills/` |
-
-### VSCode Extension Storage (Marketplace Skills)
-
-| Platform | Path |
-|---|---|
-| macOS | `~/Library/Application Support/Code/User/globalStorage/saeeol.saeeol/skills/` |
-| Windows | `%APPDATA%/Code/User/globalStorage/saeeol.saeeol/skills/` |
-| Linux | `~/.config/Code/User/globalStorage/saeeol.saeeol/skills/` |
-
-## Skill File Format
-
-Skills use the same `SKILL.md` format as Opencode:
-
-```markdown
----
-name: my-skill
-description: When to use this skill
----
-
-# Instructions
-
-Detailed instructions for the agent...
-```
-
-## Priority / Override Behavior
-
-When the same skill name exists in multiple locations, **last one wins**:
-
-1. `.claude/skills/` (lowest priority)
-2. `.saeeol/skills/` (walk-up)
-3. `~/.saeeol/skills/`
-4. VSCode extension storage
-5. `.saeeol/skill/` (walk-up)
-6. `~/.saeeol/skill/` (highest priority)
-
-This means Opencode native skills take precedence over Saeeol skills with the same name.
-
-## Mode-Specific Skills
-
-Saeeol supports mode-specific skills in `skills-{mode}/` directories (e.g., `skills-code/`, `skills-architect/`). These are **not currently migrated** to Opencode.
-
-If you need mode-specific behavior, use Opencode's agent permission system:
-
-```json
-{
-  "agent": {
-    "build": {
-      "permission": {
-        "skill": {
-          "translation": "deny"
-        }
-      }
-    }
-  }
-}
-```
-
-## Symlink Support
-
-Skills can be symlinked from a shared location:
-
-```
-.agents/skills/shared-skill/          # Actual skill
-.saeeol/skills/shared-skill -> ...  # Symlink
-.saeeol/skill/shared-skill -> ...   # Symlink
-```
-
-The scanner follows symlinks, so a skill installed once can be available to both Saeeol VSCode and Opencode CLI.
-
-## Related Files
-
-- [`paths.ts`](../paths.ts) - `skillDirectories()` function
-- [`skill.ts`](../../skill/skill.ts) - Skill scanning logic
-
----
-
-# Rules Migration
-
-Saeeol rules are migrated to Opencode's `instructions` array. See [`rules-migrator.ts`](../rules-migrator.ts).
-
-## Source Locations
-
-| Location | Description |
-|---|---|
-| `.saeeolrules` | Legacy project rules file |
-| `.saeeol/rules/*.md` | Project rules directory |
-| `~/.saeeol/rules/*.md` | Global rules directory |
-| `.saeeolrules-{mode}` | Mode-specific legacy rules |
-| `.saeeol/rules-{mode}/*.md` | Mode-specific rules directory |
-
----
-
-# Workflows Migration
-
-Saeeol workflows are migrated to Opencode commands. See [`workflows-migrator.ts`](../workflows-migrator.ts).
-
-## Source Locations
-
-| Location | Description |
-|---|---|
-| `.saeeol/workflows/*.md` | Project workflows |
-| `~/.saeeol/workflows/*.md` | Global workflows |
-| VSCode extension storage | Marketplace-installed workflows |
-
----
-
-# MCP Migration
-
-Saeeol MCP server configurations are migrated to Opencode's `mcp` config. See [`mcp-migrator.ts`](../mcp-migrator.ts).
-
-## Config file location
-
-The CLI reads global config from `~/.config/saeeol/` (see [`global/index.ts`](../../global/index.ts): `Global.Path.config` = `xdgConfig` + `"saeeol"`). It merges, in order, `config.json`, `saeeol.json`, and `saeeol.jsonc` in that directory. You can put MCP config in **`saeeol.json`** or **`saeeol.jsonc`**.
-
-- **macOS / Linux:** `~/.config/saeeol/saeeol.json` (or `saeeol.jsonc`)
-- **Windows:** Config directory depends on `xdg-basedir` (often under `%LOCALAPPDATA%` or `%USERPROFILE%`); filename is still `saeeol.json` or `saeeol.jsonc`.
-
-Use a top-level `"mcp"` object. Each key is the server name. For a local server, value must have `type: "local"` and `command: ["executable", "arg1", ...]`. Optional: `environment` (env vars), `enabled` (boolean), `timeout` (ms). See `Config.McpLocal` in [`config.ts`](../../config/config.ts). Restart the CLI after editing.
-
-## Source Location (migration from Saeeol)
-
-| Location | Description |
-|---|---|
-| VSCode extension storage `settings/cline_mcp_settings.json` | MCP server configurations |
-
----
-
-# Saeeol Notifications
-
-When connected to Saeeol Gateway, the CLI fetches and displays notifications from the Saeeol API. This allows Saeeol to communicate important announcements, feature updates, and tips to users.
-
-## How It Works
-
-1. **On startup**, if the user is authenticated with Saeeol Gateway, the CLI fetches notifications from `https://api.saeeol.ai/api/users/notifications`
-2. **Filtering**: Only notifications with `showIn` containing `"cli"` (or no `showIn` restriction) are displayed
-3. **Display**: The first notification is shown as a toast notification after a 2-second delay
-
-## Notification Data Structure
-
-```typescript
-interface SaeeolNotification {
-  id: string // Unique identifier
-  title: string // Notification title (e.g., "Agent skills now supported!")
-  message: string // Description text
-  action?: {
-    actionText: string // Link text (e.g., "Learn More")
-    actionURL: string // URL destination
-  }
-  showIn?: string[] // Target platforms: ["cli", "vscode"]
-}
-```
-
-## Example Notification
-
-```
-Title: Agent skills now supported!
-Message: Define reusable skills and workflows for your AI agent.
-Action: Learn More -> https://docs.saeeol.ai/skills
-```
-
-## Display Conditions
-
-| Condition | Notifications Shown |
-|---|---|
-| Connected to Saeeol Gateway | Yes |
-| Not connected to Saeeol | No |
-| No notifications from API | No |
-
-## Related Files
-
-- [`notifications.ts`](../../../../saeeol-gateway/src/api/notifications.ts) - Fetch function and types
-- [`routes.ts`](../../../../saeeol-gateway/src/server/routes.ts) - Server endpoint `/saeeol/notifications`
-- [`app.tsx`](../../cli/cmd/tui/app.tsx) - TUI notification display logic

package/src/overlay/docs/rules-migration.md

@@ -1,137 +0,0 @@
-# Saeeol Rules Migration
-
-This document explains how Saeeol rules are automatically migrated to Opencode's `instructions` config array.
-
-## Overview
-
-Saeeol stores rules in various file locations. When Opencode starts, it reads these files and injects their paths into the `instructions` config array, which Opencode then loads as part of the system prompt.
-
-## Key Guarantees
-
-### 1. Read-Only Migration
-
-The migration **never modifies project files**. We only:
-
-- Read existing rule files from disk
-- Inject file paths into the config's `instructions` array
-- Never write to the project or modify any files
-
-### 2. Combines with Existing Config (Never Overwrites)
-
-If you have existing saeeol config with `instructions`, the Saeeol rules are **combined**, not replaced:
-
-```typescript
-// Example: User has saeeol.json with:
-{ "instructions": ["AGENTS.md", "custom-rules.md"] }
-
-// Saeeol rules add:
-{ "instructions": [".saeeolrules", ".saeeol/rules/coding.md"] }
-
-// Result (combined, deduplicated):
-{ "instructions": ["AGENTS.md", "custom-rules.md", ".saeeolrules", ".saeeol/rules/coding.md"] }
-```
-
-### 3. Restart to Pick Up Changes
-
-If you change your Saeeol configuration (e.g., edit `.saeeolrules`), simply restart saeeol-cli to pick up the new config. No manual migration or conversion needed.
-
-## Source Locations
-
-The migrator reads rules from these locations:
-
-### Project Rules
-
-| Location | Description |
-|---|---|
-| `.saeeolrules` | Legacy single-file rules in project root |
-| `.saeeol/rules/*.md` | Directory-based rules (multiple markdown files) |
-| `.saeeolrules-{mode}` | Mode-specific legacy rules (e.g., `.saeeolrules-code`) |
-| `.saeeol/rules-{mode}/*.md` | Mode-specific rule directories |
-
-### Global Rules
-
-| Location | Description |
-|---|---|
-| `~/.saeeol/rules/*.md` | Global rules directory |
-
-## File Mapping
-
-| Saeeol Location | Opencode Equivalent |
-|---|---|
-| `.saeeolrules` | `instructions: [".saeeolrules"]` |
-| `.saeeolrules-{mode}` | `instructions: [".saeeolrules-{mode}"]` |
-| `.saeeol/rules/*.md` | `instructions: [".saeeol/rules/file.md", ...]` |
-| `.saeeol/rules-{mode}/*.md` | `instructions: [".saeeol/rules-{mode}/file.md", ...]` |
-| `~/.saeeol/rules/*.md` | `instructions: ["~/.saeeol/rules/file.md", ...]` |
-
-## AGENTS.md Compatibility
-
-`AGENTS.md` is loaded **natively** by Opencode - no migration needed. Opencode automatically loads:
-
-- `AGENTS.md` in project root
-- `CLAUDE.md` in project root
-- `~/.saeeol/AGENTS.md` (global)
-
-## Not Migrated
-
-The following are **not** migrated:
-
-- `.roorules` - Roo-specific rules
-- `.clinerules` - Cline-specific rules
-
-Only Saeeol-specific files (`.saeeolrules`, `.saeeol/rules/`) are migrated.
-
-## Mode-Specific Rules
-
-Mode-specific rules (e.g., `.saeeolrules-code`, `.saeeol/rules-architect/`) are included by default. All mode-specific rules are loaded regardless of the current mode.
-
-## Warnings
-
-The migrator generates warnings for:
-
-- **Legacy files**: When `.saeeolrules` is found, a warning suggests migrating to `.saeeol/rules/` directory structure
-
-## Example
-
-### Before (Saeeol)
-
-```
-project/
-├── .saeeolrules           # Legacy rules
-├── .saeeolrules-code      # Code-mode specific
-└── .saeeol/
-    └── rules/
-        ├── coding.md        # Coding standards
-        └── testing.md       # Testing guidelines
-```
-
-### After (Opencode Config)
-
-```json
-{
-  "instructions": [
-    "/path/to/project/.saeeol/rules/coding.md",
-    "/path/to/project/.saeeol/rules/testing.md",
-    "/path/to/project/.saeeolrules",
-    "/path/to/project/.saeeolrules-code"
-  ]
-}
-```
-
-## Troubleshooting
-
-### Rules not appearing
-
-1. Check the file exists at the expected location
-2. Ensure markdown files have `.md` extension
-3. Restart saeeol-cli to pick up changes
-
-### Duplicate rules
-
-The `mergeConfigConcatArrays` function automatically deduplicates the `instructions` array using `Array.from(new Set([...]))`.
-
-## Related Files
-
-- [`rules-migrator.ts`](../rules-migrator.ts) - Core migration logic
-- [`config-injector.ts`](../config-injector.ts) - Config building and injection
-- [`modes-migration.md`](./modes-migration.md) - Modes migration documentation

package/src/overlay/editor-context.ts

@@ -1,65 +0,0 @@
-export interface EditorContext {
-  directory?: string
-  worktree?: string
-  visibleFiles?: string[]
-  openTabs?: string[]
-  activeFile?: string
-  shell?: string
-}
-
-/**
- * Build static <env> lines from editor context.
- * These rarely change during a session and belong in the system prompt
- * so they benefit from prompt caching.
- */
-export function staticEnvLines(ctx?: EditorContext): string[] {
-  const lines: string[] = []
-  if (ctx?.shell) {
-    lines.push(`  Default shell: ${ctx.shell}`)
-  }
-  return lines
-}
-
-/**
- * Build a per-message <environment_details> block from editor context.
- * These change frequently (user switches files/tabs) and belong in the
- * user message so the model always has fresh context.
- * Always includes at least the current timestamp.
- */
-function timestamp(): string {
-  const now = new Date()
-  const offset = -now.getTimezoneOffset()
-  const sign = offset >= 0 ? "+" : "-"
-  const h = Math.floor(Math.abs(offset) / 60)
-    .toString()
-    .padStart(2, "0")
-  const m = (Math.abs(offset) % 60).toString().padStart(2, "0")
-  const pad = (n: number) => n.toString().padStart(2, "0")
-  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}T${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}${sign}${h}:${m}`
-}
-
-export function environmentDetails(ctx?: EditorContext): string {
-  const lines: string[] = [`Current time: ${timestamp()}`]
-  if (ctx?.directory) {
-    lines.push(`Working directory: ${ctx.directory}`)
-  }
-  if (ctx?.worktree) {
-    lines.push(`Workspace root folder: ${ctx.worktree}`)
-  }
-  if (ctx?.activeFile) {
-    lines.push(`Active file: ${ctx.activeFile}`)
-  }
-  if (ctx?.visibleFiles?.length) {
-    lines.push(`Visible files:`)
-    for (const f of ctx.visibleFiles) {
-      lines.push(`  ${f}`)
-    }
-  }
-  if (ctx?.openTabs?.length) {
-    lines.push(`Open tabs:`)
-    for (const f of ctx.openTabs) {
-      lines.push(`  ${f}`)
-    }
-  }
-  return ["<environment_details>", ...lines, "</environment_details>"].join("\n")
-}