saeeol 1.1.0 → 1.1.1

package/src/saeeol/docs/migration.md

@@ -0,0 +1,398 @@
+# 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/saeeol/docs/rules-migration.md

@@ -0,0 +1,137 @@
+# 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/saeeol/editor-context.ts

@@ -0,0 +1,65 @@
+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")
+}