@mirrowel/opencode-souk 0.1.0

package/docs/CONFIG.md

@@ -0,0 +1,67 @@
+# OpenCode Souk Configuration
+
+Souk stores its sidecar config at:
+
+```text
+~/.config/opencode/souk.jsonc
+```
+
+The cache is stored at:
+
+```text
+~/.config/opencode/souk-cache.json
+```
+
+Backups and debug logs are stored at:
+
+```text
+~/.config/opencode/souk.backup.json
+~/.config/opencode/souk.debug.log
+```
+
+See `souk.example.jsonc` for a commented starter config.
+
+## Top-Level Fields
+
+- `debug`: enables best-effort debug logging. Logging is hot-read and never fatal.
+- `ui`: dialog sizing. `width` is `medium`, `large`, or `xlarge`; `height` is a preset; `height_percent` is clamped to 25-100.
+- `ui.browser`: item browser table sizing. It has its own `width` so the browser can be wider than normal menus.
+- `cache`: fetch/cache policy. Souk fetches on empty cache and manual refresh by default.
+- `install`: native install preferences. Conflict policy is intentionally `refuse`.
+- `forge`: experimental Kāf installer-agent settings.
+- `sources`: community source URLs and enablement.
+- `hidden`: item IDs hidden from normal browsing.
+
+Debug and UI-only saves do not create backup entries. Meaningful settings saves create reverse-patch restore points.
+
+## Forge
+
+Forge mode is experimental and disabled by default.
+
+```jsonc
+{
+  "forge": {
+    "enabled": false,
+    "agent": {
+      "model": "opencode/big-pickle",
+      "personality": "curio-shelf"
+    }
+  }
+}
+```
+
+When enabled, Forge opens a dedicated Kāf session for selected items.
+
+Native installs do not require Forge. Forge remains useful for custom installs, ambiguous sources, batch reasoning, or extra security review.
+
+Kāf model and provider variant are selected from OpenCode's provider catalog when available. Souk intentionally does not use named model shortcuts.
+
+## Sources
+
+Souk fetches only when the cache is empty or when the user refreshes manually.
+
+Default sources:
+
+- `opencode.cafe`
+- `awesome-opencode`
+- OpenCode ecosystem docs

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@mirrowel/opencode-souk",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "OpenCode Souk: a TUI marketplace and Forge for plugins, MCPs, agents, commands, themes, and extensions",
+  "license": "MIT",
+  "author": "Mirrowel",
+  "homepage": "https://github.com/Mirrowel/opencode-souk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mirrowel/opencode-souk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Mirrowel/opencode-souk/issues"
+  },
+  "main": "dist/server.js",
+  "types": "dist/server.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./tui": {
+      "types": "./dist/tui.d.ts",
+      "import": "./src/tui.tsx"
+    }
+  },
+  "files": [
+    "dist",
+    "src/tui.tsx",
+    "src/skill",
+    "docs",
+    "README.md",
+    "souk.example.jsonc",
+    "IMPLEMENTATION_PLAN.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "mcp",
+    "marketplace",
+    "tui"
+  ],
+  "oc-plugin": [
+    "server",
+    "tui"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc --outDir dist --declaration",
+    "commit:check": "npm run ci",
+    "hooks:install": "node scripts/install-git-hooks.mjs",
+    "release:intent": "node scripts/set-release-intent.mjs",
+    "release:intent:check": "node scripts/check-release-intent.mjs",
+    "typecheck": "tsc --noEmit",
+    "verify:registry:live": "npm run build && node scripts/verify-registry-live.mjs",
+    "verify:install-plans": "npm run build && node scripts/verify-install-plans.mjs",
+    "pack:dry-run": "npm pack --dry-run",
+    "ci": "npm run release:intent:check && npm run typecheck && npm run build && npm pack --dry-run",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": ">=1.14.0",
+    "comment-json": "^4.2.5",
+    "solid-js": "^1.9.12",
+    "zod": "^4.1.8"
+  },
+  "devDependencies": {
+    "@opentui/solid": "^0.2.16",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.14.0"
+  }
+}

package/souk.example.jsonc

@@ -0,0 +1,68 @@
+{
+  // Enables best-effort debug logging to ~/.config/opencode/souk.debug.log.
+  // Debug logging is hot-read and never fatal.
+  "debug": false,
+
+  // Souk TUI display preferences. These can be changed from Debug & advanced.
+  "ui": {
+    "width": "large",
+    "height": "tall",
+    "height_percent": 68,
+
+    // Item browser table width. This is separate so the browser can be wider
+    // than normal Souk menus and info windows.
+    "browser": {
+      "width": "xlarge"
+    }
+  },
+
+  // Cache policy. Souk fetches only when cache is empty or when you refresh manually.
+  "cache": {
+    "fetch_on_empty": true,
+    "refresh_manually": true,
+    "stale_after_hours": 168
+  },
+
+  // Native install defaults.
+  "install": {
+    "default_scope": "ask",
+    "conflict_policy": "refuse",
+    "allow_claude_mcp_conversion": "ask",
+    "runtime_mcp_connect": true
+  },
+
+  // Experimental Kāf Forge mode. Forge is hidden from install choices unless enabled;
+  // advanced settings remain available so you can configure it before enabling.
+  "forge": {
+    "enabled": false,
+    "bulk": true,
+    "require_typed_high_risk": true,
+    "agent": {
+      "model": "opencode/big-pickle",
+      // Optional provider-specific variant. Leave unset for provider default.
+      // "variant": "high",
+      "temperature": 0.2,
+      "top_p": 0.95,
+      "options": {},
+      "personality": "curio-shelf"
+    }
+  },
+
+  "sources": {
+    "opencode_cafe": {
+      "enabled": true,
+      "url": "https://curious-quail-727.convex.cloud/api/query"
+    },
+    "awesome_opencode": {
+      "enabled": true,
+      "url": "https://raw.githubusercontent.com/awesome-opencode/awesome-opencode/main/dist/registry.json"
+    },
+    "opencode_docs": {
+      "enabled": true,
+      "url": "https://raw.githubusercontent.com/anomalyco/opencode/dev/packages/web/src/content/docs/ecosystem.mdx"
+    }
+  },
+
+  // Item IDs hidden from normal marketplace browsing.
+  "hidden": {}
+}

package/src/skill/souk-installer/SKILL.md

@@ -0,0 +1,313 @@
+---
+name: souk-installer
+description: Use when Kāf or Souk is installing, appraising, converting, or securing OpenCode extensions including plugins, MCPs, agents, commands, themes, skills, tools, and ecosystem projects.
+---
+
+# Souk Installer
+
+You are helping OpenCode Souk inspect, appraise, plan, or install an OpenCode extension. Treat every install as a security-sensitive config change.
+
+## First Rule
+
+Prefer Souk's deterministic native tools when they clearly support the item. Use manual installation when native tools are incomplete, ambiguous, likely to fail, or unable to preserve the intended install semantics.
+
+Native tools are helpers, not a cage. Many real ecosystem items require manual install steps, repository inspection, package-specific configuration, generated files, OAuth setup, external service credentials, or custom commands. If the native preview looks uncertain, partial, lossy, or wrong, explain that and plan a manual install instead.
+
+## Backup Requirement
+
+Before any install action, make or verify a backup.
+
+- Souk native installs create a pre-install backup automatically. Confirm the tool result reports the backup path.
+- Manual installs must create a backup before writing config, copying files, installing packages, or running setup commands.
+- Back up every file or directory that may be modified, plus nearby OpenCode config likely to be affected.
+- For global installs, back up relevant files under the global OpenCode config directory: `opencode.json(c)`, `tui.json(c)`, `agent(s)`, `command(s)`, `skill(s)`, `theme(s)`, and plugin directories as applicable.
+- For project installs, back up the project `opencode.json(c)`, `tui.json(c)`, and `.opencode/**` as applicable.
+- If a manual install uses shell commands or package managers that write outside OpenCode config, identify those locations and back them up when feasible.
+- Toggling an already-installed plugin active/inactive does not require a backup.
+
+If you cannot create a meaningful backup, stop and ask the user before proceeding.
+
+In plan mode:
+
+- Use `souk_registry_search` to resolve marketplace items and inspect merged source provenance.
+- Use `souk_native_preview` to preview deterministic native writes/actions.
+- If native preview is unsupported, partial, suspicious, or likely to install the wrong thing, plan a manual install instead.
+- Do not write files, patch config, run install commands, or mutate state.
+- When the plan is concrete, call `souk_request_action` with security risks and planned actions.
+
+In action mode:
+
+- Use `souk_native_install` for supported native installs.
+- For manual installs, create backups first, then perform only the approved writes/commands.
+- Execute only the approved plan.
+- Stop and ask again if scope, files, commands, permissions, or risks change.
+- Do not silently expand from one item to more items.
+
+## Mandatory Security Analysis
+
+Before proposing or executing any install, analyze all of the following:
+
+- Provenance: every source record, repository owner, package publisher, source URL, source recency, and whether the source is official or community-maintained.
+- Source agreement: whether opencode.cafe, awesome-opencode, OpenCode docs, package metadata, and repository contents agree on name, kind, and install method.
+- Install method: native OpenCode config, npm package, file copy, shell command, clone/build, curl pipe, custom script, OAuth flow, or remote service setup.
+- File writes: every file or directory that will be created, modified, overwritten, or removed.
+- Config writes: `opencode.json`, `opencode.jsonc`, `tui.json`, `tui.jsonc`, `.opencode/**`, and global config under the OpenCode config directory.
+- Tool/permission impact: plugin hooks, MCP tools, shell access, edit/write access, network access, auth headers, environment variables, tokens, and OAuth.
+- Runtime effects: whether the change hot-loads or requires a full OpenCode restart.
+- Ambiguity: stale docs, missing package names, non-native config formats, unclear repo subpaths, generated files, or unclear setup steps.
+
+If confidence is not complete, say plainly: "The souk can make mistakes." Explain what is uncertain.
+
+## OpenCode Native Install Shapes
+
+Use these shapes both for native-tool verification and for manual installs.
+
+### Plugins
+
+Runtime/server plugin config lives in `opencode.json` or `opencode.jsonc`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "npm-package-name",
+    "@scope/npm-package",
+    ["npm-package-with-options", { "key": "value" }],
+    "./relative/plugin.ts",
+    "file:///absolute/plugin.ts"
+  ]
+}
+```
+
+TUI plugin config lives in `tui.json` or `tui.jsonc`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["@scope/opencode-tui-plugin"],
+  "plugin_enabled": {
+    "plugin-id": true
+  }
+}
+```
+
+Package inspection checklist:
+
+- `oc-plugin` should include `server`, `tui`, or both.
+- Server entry is usually `exports["./server"]` or `main`.
+- TUI entry is usually `exports["./tui"]`.
+- Theme-only packages may expose `oc-themes`.
+- Check `engines.opencode` when present.
+- Do not assume a display name is an npm package name.
+
+### MCP Servers
+
+Native OpenCode MCP config lives in `opencode.json(c)` under `mcp`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "local-name": {
+      "type": "local",
+      "command": ["npx", "-y", "package"],
+      "environment": { "TOKEN": "{env:TOKEN}" },
+      "enabled": true,
+      "timeout": 30000
+    },
+    "remote-name": {
+      "type": "remote",
+      "url": "https://example.com/mcp",
+      "headers": { "Authorization": "Bearer {env:TOKEN}" },
+      "oauth": false,
+      "enabled": true
+    }
+  }
+}
+```
+
+Rules:
+
+- `type` is required for native OpenCode MCP config.
+- Local `command` must be an array of strings.
+- Use `environment`, not Claude's `env`, in native OpenCode config.
+- Runtime connect/auth is best-effort; persistent config is the source of truth.
+- MCPs add tools and context load. Review token/env/OAuth handling carefully.
+
+### Claude MCP Conversion
+
+Claude-style `mcpServers` is not OpenCode's native shape. Never convert silently.
+
+Ask before converting and preview the converted shape:
+
+- Claude `command` plus `args` maps to OpenCode `type: "local", command: [command, ...args]`.
+- Claude `env` maps to OpenCode `environment`.
+- Remote URL entries map to OpenCode `type: "remote", url`.
+- Preserve headers only when they are explicit and safe.
+- Do not invent tokens or secret values.
+
+### Agents
+
+Inline config:
+
+```jsonc
+{
+  "agent": {
+    "review": {
+      "description": "Reviews code.",
+      "mode": "subagent",
+      "model": "provider/model",
+      "permission": { "edit": "deny" },
+      "prompt": "You are a reviewer."
+    }
+  }
+}
+```
+
+Markdown file locations:
+
+- Project: `.opencode/agent/<name>.md` or `.opencode/agents/<name>.md`
+- Global: `<config>/agent/<name>.md` or `<config>/agents/<name>.md`
+
+Markdown shape:
+
+```markdown
+---
+description: Reviews code.
+mode: subagent
+model: provider/model
+permission:
+  edit: deny
+---
+
+Prompt body.
+```
+
+Allowed fields include `name`, `model`, `variant`, `description`, `mode`, `hidden`, `color`, `steps`, `options`, `permission`, `disable`, `temperature`, and `top_p`.
+
+### Commands
+
+Inline config:
+
+```jsonc
+{
+  "command": {
+    "test": {
+      "template": "Run tests for $ARGUMENTS",
+      "description": "Run tests",
+      "agent": "build",
+      "model": "provider/model",
+      "subtask": false
+    }
+  }
+}
+```
+
+Markdown file locations:
+
+- Project: `.opencode/command/<name>.md` or `.opencode/commands/<name>.md`
+- Global: `<config>/command/<name>.md` or `<config>/commands/<name>.md`
+
+The markdown body becomes the command template. Frontmatter supplies optional metadata.
+
+### Skills
+
+Skill files live in a folder containing `SKILL.md`:
+
+- Project: `.opencode/skills/<name>/SKILL.md`
+- Global: `<config>/skills/<name>/SKILL.md`
+- External OpenCode scans may also see `.claude/skills` and `.agents/skills`.
+
+Recommended `SKILL.md` shape:
+
+```markdown
+---
+name: my-skill
+description: Use when the user asks for the exact capability this skill provides.
+---
+
+# My Skill
+
+Instructions.
+```
+
+Check companion files before installing a skill folder. Do not copy unrelated repository files into a skill directory.
+
+### Themes
+
+Theme files live under `themes` and selection lives in `tui.json(c)`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "theme": "theme-name"
+}
+```
+
+Theme file shape:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/theme.json",
+  "defs": {},
+  "theme": {
+    "primary": "#ffffff"
+  }
+}
+```
+
+Validate theme JSON before writing. Ask before activating a theme.
+
+## Scope Rules
+
+Both native installs and Forge installs must ask for scope before persistent writes.
+
+- Global scope writes to the global OpenCode config directory.
+- Project scope writes under the selected project's `.opencode` directory/config.
+- If project scope is selected, identify the exact project root before writing.
+
+## Source Interpretation Rules
+
+- opencode.cafe usually has the richest install instructions and reviewed entries.
+- awesome-opencode has broad coverage but no installation field; treat entries as repo metadata, not verified install specs.
+- OpenCode docs are curated but usually lack install instructions.
+- A merged Souk combo item may have multiple source records. Inspect all of them before deciding kind, confidence, and install path.
+- Prefer repository/package metadata over display names for package specs.
+- Shell installers such as `curl | bash`, `sudo`, and destructive commands require direct warnings and explicit user approval.
+
+## Manual Install Procedure
+
+Use manual installation when Souk native tools are unsupported, uncertain, or insufficient.
+
+1. Inspect all available source records, repository files, package manifests, README instructions, release notes, and OpenCode docs.
+2. Decide whether the item is truly an OpenCode plugin, TUI plugin, MCP, agent, command, skill, theme, tool, app, project, or resource. Preserve alternate interpretations in the explanation.
+3. Identify the exact scope and target paths before writing.
+4. Create backups before the first write or install command.
+5. Prefer minimal native OpenCode file/config writes over shell installers when equivalent.
+6. If shell commands are necessary, explain what they install, where they write, and why native config/file copy is not enough.
+7. Never run `curl | sh`, `curl | bash`, `sudo`, destructive commands, or token/OAuth setup without explicit user approval after explaining risk.
+8. Preserve existing config and comments where possible. Refuse conflicting overwrites unless the user explicitly approves a diff.
+9. Validate written shapes against OpenCode config expectations.
+10. Report the backup path, exact changes, skipped steps, and restart requirements.
+
+Manual install examples:
+
+- A repo has `.opencode/agents/reviewer.md`: copy that file into the selected scope's agent directory after backing up the target directory.
+- A repo has a `SKILL.md` plus reference files: copy only the skill folder contents required by the skill, not the whole repository.
+- A plugin package has unusual options: patch `opencode.json(c)` or `tui.json(c)` with the documented tuple form after backing up the config file.
+- An MCP README shows Claude `mcpServers`: convert only after approval and show the OpenCode `mcp` diff.
+- A web app or tool is not a native OpenCode extension: do not pretend it is. Explain the manual setup and risks.
+
+## Planning Output
+
+Your plan should include:
+
+- Selected item IDs and all source records considered.
+- Chosen native kind and any alternate kinds.
+- Exact scope.
+- Exact files/config keys that will change.
+- Whether Souk native tools can perform the install.
+- Security risks and uncertainty.
+- Restart/hot-load expectations.
+
+If approval is denied, continue planning and propose switching again only when the plan is refined or the user's concern is addressed.