better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/marketplace.md

@@ -0,0 +1,269 @@
+<!--
+source: https://omp.sh/docs/marketplace
+fetched: 2026-09-06
+-->
+
+# Marketplaces
+
+> Add plugin catalogs you trust, browse what they publish, and install plugins for one project or every project.
+
+Marketplaces let you install plugins by short name instead of managing each plugin's repository yourself. A marketplace is only a catalog: it tells omp which plugins exist and where their code comes from.
+
+Start by adding a catalog controlled by a publisher you trust, browse its entries, and install one plugin at **project** scope while you evaluate it:
+
+```text
+/marketplace add anthropics/claude-plugins-official
+/marketplace
+/marketplace install --scope project <plugin>@claude-plugins-official
+```
+
+In the interactive TUI, `/marketplace` opens a browser showing plugin names, versions, descriptions, and their marketplace. Select an entry to install it at the default user scope, or use the explicit install command above when you want project scope.
+
+## Choose and verify a source
+
+omp does not search a central store or certify marketplace publishers. `/marketplace discover` searches only catalogs you have already added. Obtain a source from the plugin publisher's own site or repository, then inspect it before adding it:
+
+1. Confirm the repository or domain belongs to the expected publisher.
+2. Inspect `.omp-plugin/marketplace.json` or `.claude-plugin/marketplace.json`.
+3. Follow each plugin's `source`; a trusted catalog can still point to another repository.
+4. Prefer entries pinned to a reviewed commit with `sha`, rather than a moving branch.
+
+Adding a source fetches and validates its catalog; it does not install a plugin. List configured sources at any time to catch an unexpected or renamed source:
+
+```text
+/marketplace list
+```
+
+From a shell:
+
+```sh
+omp plugin marketplace list
+```
+
+Accepted source forms are:
+
+| Source | Example | How omp treats it |
+| --- | --- | --- |
+| GitHub shorthand | `owner/repo` | Clones the GitHub repository |
+| Git URL | `https://github.com/org/repo`, `git@github.com:org/repo.git`, or `ssh://…` | Clones the repository |
+| Direct catalog URL | `https://plugins.example/marketplace.json` | Downloads that JSON catalog |
+| Local directory | `./marketplace`, `~/marketplace`, or an absolute path | Reads the directory without cloning it |
+
+Git and local sources must contain `.omp-plugin/marketplace.json` (preferred) or the Claude Code-compatible `.claude-plugin/marketplace.json` fallback. A direct catalog URL cannot use relative plugin sources such as `"./plugins/linter"`, because there is no accompanying repository tree.
+
+## Browse and install
+
+After adding a source, either open the TUI browser or print the available entries:
+
+```text
+/marketplace
+/marketplace discover
+/marketplace discover claude-plugins-official
+```
+
+The shell equivalents are:
+
+```sh
+omp plugin discover
+omp plugin discover claude-plugins-official
+```
+
+Install by the catalog ID `name@marketplace`:
+
+```text
+/marketplace install --scope project name@marketplace
+/marketplace install --scope user name@marketplace
+```
+
+```sh
+omp plugin install name@marketplace --scope project
+```
+
+The default scope is `user`. `--force` reinstalls an existing plugin:
+
+```text
+/marketplace install --force name@marketplace
+```
+
+For the shell command, the marketplace must already be configured. Otherwise, `omp plugin install name@marketplace` may interpret the argument as an npm package and version tag instead. Run `omp plugin marketplace list` and use the catalog's declared `name`, which may differ from its repository name.
+
+## Update, upgrade, and remove
+
+Refreshing a **marketplace** and upgrading a **plugin** are separate operations:
+
+```text
+/marketplace update marketplace-name   # refresh one catalog
+/marketplace update                    # refresh every catalog
+/marketplace upgrade name@marketplace  # reinstall one plugin from its current entry
+/marketplace upgrade                   # upgrade all eligible marketplace plugins
+```
+
+A catalog update does not change installed plugin code. An upgrade does. When upgrading all plugins, omp compares entries that declare a `version`; one failed plugin does not stop the others, so review the reported results.
+
+List or remove installed plugins with:
+
+```text
+/marketplace installed
+/marketplace uninstall --scope project name@marketplace
+/plugins list
+```
+
+In the TUI, `/marketplace uninstall` with no ID opens a selector. Shell equivalents are:
+
+```sh
+omp plugin list
+omp plugin uninstall name@marketplace --scope project
+omp plugin upgrade name@marketplace --scope project
+```
+
+Remove a catalog only after deciding what to do with its installed plugins:
+
+```text
+/marketplace remove marketplace-name
+```
+
+```sh
+omp plugin marketplace remove marketplace-name
+```
+
+Removing a marketplace deletes its registry entry and catalog cache, but does **not** uninstall plugins already recorded from it. Uninstall those explicitly if you no longer trust or need them.
+
+## Scopes and enable state
+
+| Scope | Visibility | Default storage |
+| --- | --- | --- |
+| `user` | Every project | `~/.omp/plugins/installed_plugins.json` |
+| `project` | Only the active project | The nearest project `.omp/plugins/installed_plugins.json` |
+
+An enabled project installation shadows the user installation of the same `name@marketplace`. A disabled project installation does not shadow the user copy. When a plugin is installed in both scopes, pass `--scope user` or `--scope project` to uninstall, upgrade, enable, or disable the intended copy.
+
+```text
+/plugins disable --scope project name@marketplace
+/plugins enable --scope project name@marketplace
+```
+
+```sh
+omp plugin disable name@marketplace --scope project
+omp plugin enable name@marketplace --scope project
+```
+
+Project scope limits where omp loads the plugin; it is **not** a security sandbox. Plugin code still runs with the same operating-system permissions as omp.
+
+On systems using omp's XDG layout, user registry and cache files live under the effective XDG data/cache roots instead of `~/.omp`. `omp config init-xdg` creates those directories but does not move existing data or set the XDG environment variables.
+
+## Reload the active session
+
+Marketplace commands in the interactive TUI update disk state and invalidate discovery caches, but they do not rebuild every part of the running session.
+
+After installing, upgrading, uninstalling, enabling, or disabling a plugin, run:
+
+```text
+/reload-plugins
+```
+
+This refreshes skills, slash commands, task agents, capability discovery, and MCP servers. Restart the omp session when the change includes custom tools, hooks, or extension modules; those initialized runtime surfaces are not fully rebuilt by `/reload-plugins`.
+
+Shell commands affect future sessions. An already-running session still needs the reload or restart described above.
+
+## Control automatic updates
+
+By default, `marketplace.autoUpdate` is `notify`. At startup omp refreshes stale catalogs and checks versions, but current `notify` mode reports availability only in the debug log; it does not display a TUI notification. Choose the behavior explicitly if that is not what you want:
+
+```sh
+omp config get marketplace.autoUpdate
+omp config set marketplace.autoUpdate off
+omp config set marketplace.autoUpdate auto
+```
+
+| Value | Startup behavior |
+| --- | --- |
+| `off` | Do not check marketplace plugins |
+| `notify` | Check and write available updates to the debug log; this is the default |
+| `auto` | Check and automatically upgrade available plugins |
+
+Use `off` or manual `/marketplace update` plus `/marketplace upgrade` when you need to review every code change before it runs. `auto` allows a publisher to deliver newer plugin code without a manual approval step.
+
+## Security model
+
+Marketplaces and plugins are not signed, sandboxed, or centrally reviewed by omp. Installing a plugin can add skills and commands, but it can also add hooks, custom tools, agents, MCP or LSP servers, and extension modules. Those surfaces may run processes, access files, make network requests, or act automatically during a session.
+
+Before installation:
+
+- review both the catalog entry and the resolved plugin source;
+- inspect hooks, server commands, extension modules, and package installation scripts;
+- verify a declared `sha` against the commit you reviewed;
+- use project scope to limit accidental loading elsewhere, without treating it as a permission boundary;
+- avoid automatic upgrades for sources whose future changes you cannot trust.
+
+`--force` only reinstalls a plugin. It does not perform additional verification.
+
+## Troubleshooting
+
+### A source adds successfully but no plugins appear
+
+Run `/marketplace update <name>` and then `/marketplace discover <name>`. The catalog's top-level `name` is the command name. Invalid plugin entries are skipped even when the rest of a catalog is usable, so inspect the logs and the entry's required `name` and `source` fields.
+
+### The catalog cannot be found
+
+For a repository or local directory, put the catalog at `.omp-plugin/marketplace.json` or `.claude-plugin/marketplace.json` at the repository root. Prefix a relative local path with `./`; a bare directory name is not recognized as a local source.
+
+### An install is not visible
+
+Run `/marketplace installed` to confirm the ID and scope, then `/reload-plugins`. Restart the session for tools, hooks, or extension modules. If both scopes contain the same ID, `/plugins list` shows which copy is active or shadowed.
+
+### Updating did not change the plugin
+
+`/marketplace update` refreshes only the catalog. Run `/marketplace upgrade name@marketplace` to update installed code, then reload or restart the session.
+
+## Publish a marketplace
+
+A marketplace author publishes a Git repository with a catalog and one or more installable [plugin trees](/docs/plugins):
+
+```text
+my-marketplace/
+  .omp-plugin/
+    marketplace.json
+  plugins/
+    my-plugin/
+```
+
+Use `.omp-plugin/marketplace.json` for omp. Use `.claude-plugin/marketplace.json` instead when you also need Claude Code compatibility; omp reads it when the `.omp-plugin` catalog is absent.
+
+The smallest valid catalog is:
+
+```json
+{
+  "name": "my-marketplace",
+  "owner": { "name": "Your Name" },
+  "plugins": [
+    {
+      "name": "my-plugin",
+      "description": "What this plugin adds",
+      "version": "1.0.0",
+      "source": "./plugins/my-plugin"
+    }
+  ]
+}
+```
+
+`name`, `owner.name`, and `plugins` are required at the top level. Each plugin requires `name` and `source`. Marketplace and plugin names must start and end with a lowercase letter or digit, contain only lowercase letters, digits, `-`, and `.`, and be at most 64 characters.
+
+Relative sources must begin with `./` and remain inside the marketplace repository. External plugins may use `github`, `url`, or `git-subdir` source objects with optional `ref` and `sha`; pin `sha` for reproducible installs. npm source objects are accepted by the catalog parser but are not currently installable.
+
+Test the exact consumer workflow locally before publishing:
+
+```text
+/marketplace add ./my-marketplace
+/marketplace discover my-marketplace
+/marketplace install --scope project my-plugin@my-marketplace
+/reload-plugins
+```
+
+Then push the repository and share its `owner/repo` shorthand. Consumers can inspect that repository, add it, and install by the catalog name.
+
+## Related
+
+- [Plugins](/docs/plugins) — plugin layout, loading, and lifecycle.
+- [Skills](/docs/skills) — on-demand playbooks that plugins can ship.
+- [Hooks](/docs/hooks) — automatic lifecycle code to inspect before installation.
+- [Custom tools](/docs/custom-tools) — executable capabilities a plugin can add.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/mcp-authoring.md

@@ -0,0 +1,243 @@
+<!--
+source: https://omp.sh/docs/mcp-authoring
+fetched: 2026-09-06
+-->
+
+# Authoring MCP servers
+
+> Build a standards-based tool server, connect it to omp, and verify the handshake and tool calls end to end.
+
+## Build once, use it from many clients
+
+An MCP server turns an API, local service, or workflow into tools that omp can discover and use. Choose MCP when the integration should also work with other MCP clients. For an omp-only integration, a [custom tool](/docs/custom-tools) is usually smaller.
+
+The quickest path is a local **stdio** server. The official SDK handles JSON-RPC framing, version negotiation, and the initialization sequence, so your code can focus on tool schemas and behavior.
+
+## Build a minimal stdio server
+
+Install the current TypeScript server SDK and Zod in your project:
+
+```bash
+npm install @modelcontextprotocol/server zod
+```
+
+Save this as `mcp/hello-server.mjs`:
+
+```js
+import { McpServer } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import * as z from "zod/v4";
+
+const server = new McpServer({
+  name: "hello",
+  version: "1.0.0",
+});
+
+server.registerTool(
+  "greet",
+  {
+    description: "Greet one person by name.",
+    inputSchema: z.object({
+      name: z.string().min(1).describe("The person's name"),
+    }),
+  },
+  async ({ name }) => ({
+    content: [{ type: "text", text: `Hello, ${name}!` }],
+  }),
+);
+
+await server.connect(new StdioServerTransport());
+```
+
+Do not print logs to stdout in a stdio server. stdout carries newline-delimited MCP messages; one debug line can corrupt the connection. Write diagnostics to stderr instead.
+
+### Connect it to omp
+
+Add a project config at `.omp/mcp.json`:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
+  "mcpServers": {
+    "hello": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["./mcp/hello-server.mjs"]
+    }
+  }
+}
+```
+
+Start omp in that project, then run:
+
+```text
+/mcp reload
+/mcp test hello
+```
+
+`/mcp test hello` creates a temporary connection, completes initialization, calls `tools/list`, and reports the server identity and discovered tool names. It does **not** call a tool. Exercise the handler with a normal request:
+
+> Use the hello server to greet Ada.
+
+You should see `Hello, Ada!`. The child process starts in the omp project directory unless the server config sets `cwd`, so relative `args` above resolve from the project root.
+
+## Choose a transport
+
+| Transport | Use it for | Server-side contract | omp config |
+| --- | --- | --- | --- |
+| **stdio** | A local server launched for one omp session | Read JSON-RPC from stdin, write newline-delimited JSON-RPC to stdout, and keep diagnostics off stdout | Omit `type` or use `"type": "stdio"`; set `command`, with optional `args`, `env`, and `cwd` |
+| **Streamable HTTP** | A daemon or hosted, shared service | Accept MCP JSON-RPC over HTTP POST; support JSON or SSE responses as required by the MCP transport spec | Use `"type": "http"` and `url`; `headers` and OAuth are optional |
+| **Legacy HTTP+SSE** | An existing server built for the 2024-11-05 transport | Open an SSE stream that announces the JSON-RPC POST endpoint | Use `"type": "sse"` and `url`; do not choose this for a new server |
+
+stdio is the default when `type` is absent. A remote entry without `"type": "http"` is therefore treated as stdio and fails because it has no `command`.
+
+### Publish the same tool over Streamable HTTP
+
+The current SDK can serve both current and 2025-era clients. For a small Node-hosted endpoint, install its Node adapter:
+
+```bash
+npm install @modelcontextprotocol/node
+```
+
+A minimal loopback server looks like this:
+
+```js
+import { createServer } from "node:http";
+import {
+  localhostHostValidation,
+  localhostOriginValidation,
+  toNodeHandler,
+} from "@modelcontextprotocol/node";
+import { createMcpHandler, McpServer } from "@modelcontextprotocol/server";
+import * as z from "zod/v4";
+
+const handler = createMcpHandler(() => {
+  const server = new McpServer({ name: "hello-http", version: "1.0.0" });
+  server.registerTool(
+    "greet",
+    {
+      description: "Greet one person by name.",
+      inputSchema: z.object({ name: z.string().min(1) }),
+    },
+    async ({ name }) => ({
+      content: [{ type: "text", text: `Hello, ${name}!` }],
+    }),
+  );
+  return server;
+});
+
+const nodeHandler = toNodeHandler(handler);
+const validateHost = localhostHostValidation();
+const validateOrigin = localhostOriginValidation();
+
+createServer((request, response) => {
+  if (!validateHost(request, response) || !validateOrigin(request, response)) return;
+  void nodeHandler(request, response);
+}).listen(3000, "127.0.0.1");
+```
+
+Configure the running endpoint:
+
+```json
+{
+  "mcpServers": {
+    "hello-http": {
+      "type": "http",
+      "url": "http://127.0.0.1:3000/mcp"
+    }
+  }
+}
+```
+
+For a public deployment, validate `Host` and `Origin`, authenticate before dispatching to the MCP handler, use TLS, and pass only verified identity to tool code. The handler does not authenticate requests for you. See the SDK's [HTTP serving guide](https://ts.sdk.modelcontextprotocol.io/v2/serving/http.html) and [MCP](/docs/mcp) for omp header and OAuth configuration.
+
+## Public protocol contract
+
+Using an MCP SDK is strongly recommended. If you implement the wire protocol yourself, these are the interoperability points omp relies on:
+
+| Phase | What the server must do |
+| --- | --- |
+| `initialize` | Accept a JSON-RPC 2.0 request. omp currently offers MCP protocol revision `2025-11-25`. Reply with the negotiated `protocolVersion`, `serverInfo`, and `capabilities`. |
+| `notifications/initialized` | Accept the notification before expecting later session traffic. Notifications have no request ID and receive no response. |
+| `tools/list` | When `capabilities.tools` is declared, return `{ "tools": [...] }`. If the result has `nextCursor`, omp follows it until all pages are loaded. |
+| `tools/call` | Accept `{ "name": string, "arguments"?: object }` and return a tool result. Echo each JSON-RPC request ID exactly; valid IDs may be numbers or strings. |
+| Server requests | omp answers `ping` and `roots/list`. `roots/list` returns the active project as a `file:` URI. Do not assume a client supports other server-to-client methods unless it advertised them. |
+| Tool changes | If tools can change, advertise `tools.listChanged` and send `notifications/tools/list_changed` after initialization. omp then reloads that server's tool list without a session restart. |
+
+For Streamable HTTP, preserve `Mcp-Session-Id` when you issue one and accept `MCP-Protocol-Version: 2025-11-25` on requests after initialization. Support the HTTP methods, status codes, media types, and optional SSE channel defined by the public MCP transport specification. The official SDK handles these details.
+
+omp sends numeric JSON-RPC request IDs by default. A server should accept both JSON-RPC-permitted forms; requiring one representation reduces compatibility with other clients.
+
+## Define tools that travel well
+
+A listed tool needs a stable `name`, a concrete `description`, and an `inputSchema` whose top level is a JSON Schema object. With the SDK above, a Standard Schema library such as Zod produces that schema for you.
+
+Good schemas help the client select the tool and construct valid arguments:
+
+- Describe the user-visible action and when it is appropriate.
+- Use explicit property descriptions, bounds, enums, and `required` fields.
+- Keep optional fields genuinely optional; do not require clients to send empty placeholders.
+- Validate permissions and inputs again in the handler. A schema is guidance and validation, not authorization.
+- Keep names stable once users depend on them.
+
+omp namespaces discovered tools by server, lowercases their names, replaces characters outside `[a-z_]` with underscores, and caps the mounted name at 64 characters with a stable hash suffix when needed. Distinct raw names that normalize identically collide; omp keeps one deterministic winner. Prefer short, distinct lowercase names such as `search_issues` or `create_invoice`. Users ask for the capability in natural language rather than typing the mounted name.
+
+## Return results and errors
+
+Every successful call should return `content`. Text is the most portable content type:
+
+```js
+return {
+  content: [{ type: "text", text: "Created invoice INV-1042." }],
+};
+```
+
+omp also accepts MCP image content (`data` as base64 plus `mimeType`) and embedded resource content. If you also return `structuredContent`, include a useful text representation in `content`; do not make the human-readable result depend on structured output support.
+
+Use `isError: true` for an expected, user-correctable failure. This keeps the failure attached to the tool call and gives the model information it can act on:
+
+```js
+return {
+  content: [{ type: "text", text: "Customer C-17 does not exist." }],
+  isError: true,
+};
+```
+
+Reserve thrown exceptions or JSON-RPC error responses for protocol violations, unavailable dependencies, and unexpected server faults. omp displays expected `isError` results as tool errors; transport and JSON-RPC failures surface as MCP errors. Do not include secrets, tokens, or private stack traces in either form.
+
+For protected HTTP tools, a standards-based authorization challenge may be returned with an error in `_meta["mcp/www_authenticate"]`. omp recognizes that public MCP challenge and can reauthorize before retrying when the server is configured for OAuth.
+
+## Debugging loop
+
+1. 
+2. 
+3. 
+4. 
+5. 
+
+| Symptom | Check |
+| --- | --- |
+| `ENOENT` or command not found | Verify `command`, the project-relative path, executable permissions, and `cwd`. |
+| Test hangs or times out | Ensure the server answers `initialize`, then accepts `notifications/initialized` and `tools/list`. The default request timeout is 30 seconds; fix the stall before increasing `timeout`. |
+| Invalid JSON or immediate disconnect | Remove every stdout log/banner. Check that each stdio frame is one complete JSON-RPC object followed by a newline. |
+| Test connects but a real call fails | `/mcp test` does not call tools. Reproduce with the Inspector and return an actionable `isError` result for domain failures. |
+| Tool changes do not appear | Reconnect a restarted stdio process, or advertise `tools.listChanged` and send `notifications/tools/list_changed`. |
+| HTTP 401 or 403 | Verify server-side token validation and the client's header/OAuth config; use `/mcp reauth <name>` for managed OAuth. |
+| Tool is missing although the server lists it | Look for a normalized-name collision, an invalid top-level input schema, or another server definition shadowing the same name. |
+
+## Ship checklist
+
+- The server negotiates `2025-11-25` with omp and does not send session traffic before initialization completes.
+- stdio stdout contains protocol frames only; hosted HTTP has TLS, authentication, and Host/Origin validation.
+- `tools/list` returns stable names, descriptions, object input schemas, and every pagination cursor correctly.
+- Every `tools/call` path returns useful `content`; expected failures return `isError: true`.
+- The Inspector can list and call each tool, and `/mcp test <name>` reports the same inventory.
+- A natural-language request in omp exercises the real handler successfully.
+
+## Related
+
+- [MCP](/docs/mcp) — config locations, discovery, transports, credentials, and lifecycle commands.
+- [Custom tools](/docs/custom-tools) — omp-only alternative when cross-client compatibility is unnecessary.
+- [Plugins](/docs/plugins) — package MCP config with skills, commands, and hooks.
+- [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25) — public protocol and transport contract.
+- [MCP TypeScript SDK](https://ts.sdk.modelcontextprotocol.io/v2/) — current server APIs and examples.