@mirrowel/opencode-souk 0.1.0

package/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,176 @@
+# OpenCode Souk Implementation Plan
+
+Package: `@mirrowel/opencode-souk`
+
+UI title: `OpenCode Souk`
+
+Souk replaces the built-in OpenCode plugin manager with a TUI-native extension bazaar for plugins, MCP servers, agents, commands, themes, skills, and experimental ecosystem items.
+
+## Core Principles
+
+- Everything important is inspectable with `i`.
+- Native install paths are preferred when Souk can verify them.
+- Forge mode is available for any selected item, including verified items.
+- Low-confidence paths must say that the souk can make mistakes.
+- Persistent writes must be previewed or explicitly approved.
+- Security analysis is mandatory for Kāf and the `souk-installer` skill.
+- Claude-style MCP config conversion is never silent.
+- Native installs and Kāf installs must ask for scope: global or project. If project is selected, ask which project/path.
+
+## TUI Controls
+
+- `Enter`: select or unselect the current item.
+- `Space`: open the install menu for all selected items.
+- `i`: inspect/appraise the current item.
+- `r`: refresh community sources.
+- `Esc`: cancel/back.
+
+Install menu after `Space`:
+
+- `Safe install`: deterministic native installer where available.
+- `Forge with Kāf`: LLM-assisted install for all selected items.
+- `Preview`: proposed deterministic writes/actions.
+- `Scope`: choose global or project target.
+- `Cancel`.
+
+Appraisal/details are in the `i` panel, not a separate action.
+
+## Supported Categories
+
+- Plugins
+- MCP servers
+- Agents
+- Commands
+- Themes
+- Skills
+- Other ecosystem items through experimental Forge mode
+
+## Kāf
+
+Dedicated Souk installer agent title/name: `Kāf`.
+
+Internal agents:
+
+- `kāf-plan`: read/inspect/plan only. It may use MCP tools for research/appraisal, but not for writes or mutation.
+- `kāf-action`: approved action mode, can make changes with confirmation-oriented permissions.
+
+Default model: `opencode/big-pickle`.
+
+Kāf settings are hidden unless experimental Forge mode is enabled:
+
+- Model
+- Model variant
+- Temperature
+- Top P
+- Provider/model options
+- Personality preset
+- Permission preset
+- Bulk Forge enablement
+- High-risk typed confirmation policy
+
+Kāf always loads or is instructed to load:
+
+- `customize-opencode`
+- `souk-installer`
+
+## Personality Presets
+
+Default: `curio-shelf`.
+
+Available presets:
+
+- `curio-shelf`
+- `expedition-cataloguer`
+- `the-fence`
+- `wayfinder`
+- `quartermaster`
+- `appraiser`
+- `the-souk`
+- `wary-antiquarian`
+- `friendly-stallkeeper`
+- `contract-scribe`
+- `pragmatic-artisan`
+- `sober-host`
+
+Personality never hides risk. Warnings use plain language.
+
+## Forge Flow
+
+1. User selects one or more items.
+2. User presses `Space`.
+3. User chooses `Forge with Kāf`.
+4. Souk asks for scope: global or project, and asks which project/path for project scope.
+5. Souk shows a confirmation with count, confidence summary, and security warning.
+6. Souk creates a new dedicated session with `kāf-plan`.
+7. Initial prompt includes structured metadata for all selected items.
+8. Initial prompt instructs Kāf to load `customize-opencode` and `souk-installer`.
+9. Kāf performs security analysis and proposes a plan. MCP tools may be used during planning if they help inspect or verify the item, but Kāf must not use MCPs for mutation before approval.
+10. Kāf calls `souk_request_action` when it is appropriate to ask for action mode.
+11. The tool presents a minimal yes/no confirmation including security risks.
+12. If the user says no: nothing changes. The tool output must tell Kāf the user wishes to continue planning and that it should propose switching again only when appropriate.
+13. If the user says yes: the tool queues a same-session continuation using `kāf-action` and instructs Kāf to execute only the approved plan.
+
+## Kāf Approval Tool
+
+Tool: `souk_request_action`.
+
+Behavior:
+
+- Exclusive to Kāf agents through permissions where possible.
+- Runtime rejects calls from non-Kāf agents.
+- Shows yes/no approval only.
+- Includes security risks and planned writes/actions.
+- Does not install directly.
+- On rejection, tells Kāf to continue planning.
+- On approval, queues a `kāf-action` continuation in the same session.
+
+## Future Kāf Expansion
+
+Kāf may later receive native Souk tools for safe deterministic actions, such as:
+
+- Native plugin install/import.
+- Native MCP config add/connect/auth.
+- Native agent/command/theme/skill install.
+- Native config preview/diff generation.
+
+These tools should still respect scope prompts and preview/approval boundaries.
+
+## Deterministic Native Installer Rules
+
+Native installers should be complete for first-class installable categories:
+
+- Plugins use OpenCode's native plugin installer.
+- MCP servers patch persistent `mcp` config, convert Claude `mcpServers` only with approval, and best-effort add/connect at runtime.
+- Agents install from inline `agent` config, markdown snippets, or conventional `{agent,agents}/**/*.md` files in GitHub repos.
+- Commands install from inline `command` config, markdown snippets, or conventional `{command,commands}/**/*.md` files in GitHub repos.
+- Themes install valid theme JSON into `themes/*.json` and may optionally activate by patching `tui.jsonc`.
+- Skills install `SKILL.md` plus companion files from the skill folder.
+
+Native installers must refuse conflicting overwrites and tell the user to use Forge or manual review when source metadata is insufficient.
+
+## Sources
+
+Initial sources:
+
+- `opencode.cafe` Convex approved extension API.
+- `awesome-opencode` `dist/registry.json`.
+- OpenCode ecosystem docs markdown.
+
+Cache policy:
+
+- Fetch only when cache is empty or user asks refresh.
+- Keep stale cache on failure.
+- Cache raw source results separately from validation results.
+
+## Acceptance Criteria
+
+- `Plugins` and `Install plugin` open Souk.
+- Built-in `internal:plugin-manager` is disabled/replaced.
+- `Enter`, `Space`, and `i` work as specified.
+- Items show source, type, confidence, and security/appraisal info.
+- Native install asks scope and previews writes.
+- Forge asks scope and creates a dedicated Kāf session.
+- Kāf starts in plan mode and cannot use action mode without approval.
+- Approval tool is yes/no and Kāf-exclusive.
+- Security analysis is required by the skill and prompt.
+- Model/variant settings reuse the agent-variants style, without inheritance/routing.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mirrowel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# OpenCode Souk
+
+`@mirrowel/opencode-souk` replaces OpenCode's built-in plugin manager with a TUI marketplace for extensions.
+
+Souk can browse deduped community sources, show installed plugins separately, select multiple marketplace items, preview native installs, and optionally open an experimental Kāf Forge session for LLM-assisted installation.
+
+## Current Status
+
+Initial implementation. See `IMPLEMENTATION_PLAN.md` for the product and engineering plan.
+
+The marketplace fetches three sources by default: opencode.cafe, awesome-opencode, and the OpenCode ecosystem docs. Deduped combo items preserve all source records and choose the richest source for display.
+
+Native installers currently support:
+
+- OpenCode plugins through the native plugin installer.
+- MCP servers through persistent `mcp` config patching, Claude `mcpServers` conversion with explicit approval, and best-effort runtime add/connect.
+- Agents from inline config, markdown snippets, or conventional GitHub repo paths.
+- Commands from inline config, markdown snippets, or conventional GitHub repo paths.
+- Themes from theme JSON snippets or conventional GitHub repo paths, with optional activation.
+- Skills from `SKILL.md` snippets or conventional GitHub repo paths, including companion files under the skill folder.
+
+Native installs create a pre-install backup snapshot before supported install actions, then refuse to overwrite existing files or conflicting config entries.
+
+## Commands
+
+Souk deactivates OpenCode's built-in plugin manager and adds one palette entry:
+
+- Category: `Plugin Manager`
+- Command: `Souk`
+
+The built-in `Plugins` and `Install plugin` entries are intentionally removed while Souk is active.
+
+The palette command opens a normal Souk main menu. Item browsing/selection is one option; diagnostics, settings, debug tools, source refresh, and info are separate menu actions.
+
+## Local Install
+
+Build the local package:
+
+```powershell
+npm install
+npm run build
+```
+
+Then add the local package directory to both configs.
+
+`opencode.jsonc`:
+
+```jsonc
+{
+  "plugin": ["file:///C:/Projects/OC%20Plugins/plugin-repo"]
+}
+```
+
+`tui.jsonc`:
+
+```jsonc
+{
+  "plugin": ["file:///C:/Projects/OC%20Plugins/plugin-repo"]
+}
+```
+
+No `plugin_enabled` entry should be needed in normal use. Souk deactivates `internal:plugin-manager` during TUI startup and registers its own `Plugin Manager > Souk` palette command.
+
+## Controls
+
+- `Enter`: select/unselect item.
+- `Space`: install selected items.
+- `/`: search marketplace items.
+- `i`: inspect item details and security appraisal.
+- `r`: refresh sources.
+- `Shift+Up/Down` or `Ctrl+Up/Down`: jump kind groups.
+- `Shift+Left/Right`: jump tag groups.
+- `Esc`: close/back.
+
+Installed plugins are managed from the separate `Installed plugins` view. There, `Enter` toggles the highlighted plugin active/inactive; no batch install or Forge flow is available.
+
+## Verification
+
+```powershell
+npm run verify:registry:live
+npm run verify:install-plans
+npm run ci
+```
+
+The live registry check verifies source counts, parsing, classification, dedupe provenance, and the integrated `loadRegistry()` path. The install-plan check uses a temporary OpenCode config directory and verifies plugin, MCP, Claude MCP conversion, agent, command, skill, and theme plans.
+
+## Safety
+
+The souk can make mistakes. Low-confidence installs are marked, Forge mode is experimental, and Kāf is instructed to perform security analysis before proposing changes.
+
+Souk keeps sidecar config backups in `~/.config/opencode/souk.backup.json`, creates native install snapshots under `~/.config/opencode/souk-install-backups/`, and writes debug logs to `~/.config/opencode/souk.debug.log` when debug mode is enabled.