dsh-claude-compat 0.3.0 → 0.6.2

package/src/lib.js

@@ -0,0 +1,123 @@
+// Shared helpers for dsh-claude-compat (path resolution, sync/async root
+// discovery, reader utilities, frontmatter parsing). Extracted from index.js
+// so mcp.js / hooks.js / agents.js can reuse them without circular imports.
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { parse } from 'yaml';
+
+export function resolveUserClaudeDir(dir) {
+  if (dir === undefined || dir === null || dir === '') return join(homedir(), '.claude');
+  if (dir === '~') return homedir();
+  if (dir.startsWith('~/')) return join(homedir(), dir.slice(2));
+  return resolve(dir);
+}
+
+export async function findProjectRoot(cwd, markers = ['.git']) {
+  let current = resolve(cwd);
+  while (true) {
+    for (const marker of markers) {
+      if (await pathExists(join(current, marker))) return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+export function findProjectRootSync(cwd, markers = ['.git']) {
+  let current = resolve(cwd);
+  while (true) {
+    for (const marker of markers) {
+      if (existsSync(join(current, marker))) return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+export async function pathExists(path) {
+  try { await stat(path); return true; } catch { return false; }
+}
+
+export async function readTextSafe(path) {
+  try { return await readFile(path, { encoding: 'utf8' }); }
+  catch { return undefined; }
+}
+
+export function readTextSafeSync(path) {
+  try { return readFileSync(path, 'utf8'); } catch { return undefined; }
+}
+
+export async function listMdFiles(dir) {
+  let entries;
+  try { entries = await readdir(dir, { withFileTypes: true, encoding: 'utf8' }); }
+  catch { return []; }
+  const files = [];
+  for (const e of entries) {
+    if (e.isFile() && e.name.endsWith('.md')) files.push(join(dir, e.name));
+  }
+  files.sort();
+  return files;
+}
+
+export function listMdFilesSync(dir) {
+  let entries;
+  try { entries = readdirSync(dir); } catch { return []; }
+  const files = [];
+  for (const name of entries) {
+    if (!name.endsWith('.md')) continue;
+    const p = join(dir, name);
+    try { if (statSync(p).isFile()) files.push(p); } catch {}
+  }
+  files.sort();
+  return files;
+}
+
+// Frontmatter: `---` line, YAML block, closing `---` line, body after. Returns
+// { data, body } on success, undefined on anything malformed.
+export function parseFrontmatter(raw) {
+  const firstLineEnd = raw.indexOf('\n');
+  if (firstLineEnd < 0) return undefined;
+  if (raw.slice(0, firstLineEnd).replace(/\r$/, '') !== '---') return undefined;
+  const start = firstLineEnd + 1;
+  const closing = findClosingFrontmatter(raw, start);
+  if (closing === undefined) return undefined;
+  let parsed;
+  try { parsed = parse(raw.slice(start, closing.start)); }
+  catch { return undefined; }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return undefined;
+  return { data: parsed, body: raw.slice(closing.bodyStart) };
+}
+
+export function stringField(data, key) {
+  const v = data[key];
+  return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+
+export function truthy(v) {
+  if (typeof v === 'boolean') return v;
+  if (typeof v === 'string') {
+    const s = v.toLowerCase();
+    return s === 'true' || s === 'yes' || s === 'on' || s === '1';
+  }
+  if (typeof v === 'number') return v !== 0;
+  return false;
+}
+
+function findClosingFrontmatter(raw, start) {
+  let lineStart = start;
+  while (lineStart <= raw.length) {
+    const nextNewline = raw.indexOf('\n', lineStart);
+    const lineEnd = nextNewline < 0 ? raw.length : nextNewline;
+    if (raw.slice(lineStart, lineEnd).replace(/\r$/, '') === '---') {
+      return { start: lineStart, bodyStart: nextNewline < 0 ? raw.length : nextNewline + 1 };
+    }
+    if (nextNewline < 0) return undefined;
+    lineStart = nextNewline + 1;
+  }
+  return undefined;
+}

package/src/mcp.js

@@ -0,0 +1,133 @@
+// dsh-claude-compat: MCP servers from <projectRoot>/.mcp.json (Claude Code
+// format). Read once at DSH startup from the launch workspace; each server is
+// mounted as an @deepseek-ai/dsh-mcp-client plugin instance (stdio for
+// `command` entries, streamable-http for `url`/`type:'http'|'sse'` entries).
+//
+// Failure handling is deliberately non-fatal: an unreadable/malformed .mcp.json
+// or an absent dsh-mcp-client package logs a warning and skips, never crashing
+// the harness. failOnStartupError only forwards to the mcp-client plugin.
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  findProjectRootSync,
+  pathExists,
+} from './lib.js';
+
+// Pure translation of Claude Code's .mcp.json body into dsh-mcp-client plugin
+// configs, keyed by server name. Malformed entries are skipped and reported.
+export function translateMcpServers(rawJson, { failOnStartupError = false } = {}) {
+  let parsed;
+  try { parsed = JSON.parse(rawJson); }
+  catch {
+    return { servers: [], warns: [`invalid-json: ${String(rawJson).slice(0, 100)}`] };
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return { servers: [], warns: ['invalid-json: root must be an object'] };
+  }
+  const servers = parsed.mcpServers;
+  if (typeof servers !== 'object' || servers === null || Array.isArray(servers)) {
+    return { servers: [], warns: ['mcpServers: missing or not an object'] };
+  }
+  const out = [];
+  const warns = [];
+  for (const [name, entry] of Object.entries(servers)) {
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+      warns.push(`${name}: malformed entry, skipped`);
+      continue;
+    }
+    // serverName must match /^[A-Za-z0-9_-]{1,32}$/ (dsh-mcp-client contract).
+    const serverName = name.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 32);
+    if (serverName.length === 0) {
+      warns.push(`${name}: empty server name, skipped`);
+      continue;
+    }
+    const base = {
+      serverName,
+      toolCallTimeoutMs: 60_000,
+      failOnStartupError,
+    };
+    if (typeof entry.command === 'string' && entry.command.length > 0) {
+      out.push({
+        ...base,
+        transport: 'stdio',
+        command: entry.command,
+        args: Array.isArray(entry.args) ? entry.args.filter((a) => typeof a === 'string') : [],
+        env: stringDict(entry.env),
+        cwd: typeof entry.cwd === 'string' ? entry.cwd : '',
+      });
+    } else if (typeof entry.url === 'string' && entry.url.length > 0) {
+      out.push({
+        ...base,
+        transport: 'streamable-http',
+        url: entry.url,
+        headers: stringDict(entry.headers),
+      });
+    } else if (entry.type === 'http' || entry.type === 'sse') {
+      warns.push(`${name}: type '${entry.type}' without a url, skipped`);
+    } else {
+      warns.push(`${name}: neither command nor url, skipped`);
+    }
+  }
+  return { servers: out, warns };
+}
+
+function stringDict(v) {
+  if (typeof v !== 'object' || v === null || Array.isArray(v)) return {};
+  const out = {};
+  for (const [k, val] of Object.entries(v)) {
+    if (typeof val === 'string') out[k] = val;
+    else if (typeof val === 'number' || typeof val === 'boolean') out[k] = String(val);
+  }
+  return out;
+}
+
+// Mount one mcp-client per server listed in <projectRoot>/.mcp.json. Lifecycle:
+// process-lifetime by design — the file is read once at DSH startup from the
+// launch workspace via process.cwd()-based root discovery; deviating from the
+// per-session cwd rules (which are session-scoped) is intended and documented.
+export async function mountMcpServers(ctx, config) {
+  const projectRoot = findProjectRootSync(process.cwd(), config.projectRootMarkers);
+  if (projectRoot === undefined) return;
+  const mcpPath = join(projectRoot, '.mcp.json');
+  if (!(await pathExists(mcpPath))) return;
+  let raw;
+  try { raw = readFileSync(mcpPath, 'utf8'); } catch (error) {
+    console.warn(`dsh-claude-compat: .mcp.json unreadable: ${error?.message ?? error}`, '(skipping MCP)');
+    return;
+  }
+  const { servers, warns } = translateMcpServers(raw, {
+    failOnStartupError: config.mcpFailOnStartupError ?? false,
+  });
+  warns.forEach((w) => console.warn(`dsh-claude-compat: .mcp.json: ${w}`));
+  await mountMcpConfigs(ctx, servers);
+}
+
+// Mount pre-translated server configs (shared by .mcp.json and plugin MCP).
+export async function mountMcpConfigs(ctx, servers) {
+  if (servers.length === 0) return;
+  let mcpClientModule;
+  try {
+    mcpClientModule = await import('@deepseek-ai/dsh-mcp-client');
+  } catch (error) {
+    console.warn('dsh-claude-compat: @deepseek-ai/dsh-mcp-client not installed', '(MCP disabled)', error?.message ?? error);
+    return;
+  }
+  const mcpClient = mcpClientModule.default ?? mcpClientModule;
+  const mounted = new Set();
+  for (const server of servers) {
+    if (mounted.has(server.serverName)) {
+      console.warn(`dsh-claude-compat: duplicate serverName "${server.serverName}" skipped`);
+      continue;
+    }
+    mounted.add(server.serverName);
+    // ctx.plugin returns a Fiber (PromiseLike) in real cordis; guard for
+    // non-promise returns in tests/embeddings.
+    const fiber = ctx.plugin(mcpClient, server);
+    if (fiber && typeof fiber.catch === 'function') {
+      fiber.catch((error) => {
+        console.warn(`dsh-claude-compat: server "${server.serverName}" failed to mount: ${error?.message ?? error}`);
+      });
+    }
+  }
+}

package/src/plugin-manager.js

@@ -0,0 +1,305 @@
+// dsh-claude-compat: /plugin management skill (v0.6.0).
+//
+// Full Claude-Code-equivalent plugin management surfaced as a user-invocable
+// DSH skill named "plugin". Execution engine: claude CLI first (`claude
+// plugin ...`, present on PATH in most Claude Code setups), self-implemented
+// JSON+git fallback when the CLI is unavailable. All state lives in the
+// Claude-native locations (~/.claude/plugins/*, settings.json enabledPlugins)
+// so both Claude Code and this plugin's discovery bridge read the same truth.
+//
+// Commands (mirroring `claude plugin` semantics):
+//   /plugin                                  — list installed (status incl. enabled/disabled)
+//   /plugin <name>[@market]                  — one-shot install
+//   /plugin install <name>[@market]
+//   /plugin uninstall|remove <name>
+//   /plugin enable <name>
+//   /plugin disable <name>
+//   /plugin update [name]                    — one or all
+//   /plugin search <term>                    — scan known marketplaces
+//   /plugin marketplace list|add|remove|update [...]
+//
+// Safety: never mutates installed_plugins.json / known_marketplaces.json /
+// settings.json directly without a timestamped backup beside the file; the
+// claude-CLI path performs no direct mutation at all (CLI owns the writes).
+
+import { execFile } from 'node:child_process';
+import { copyFileSync, existsSync, readFileSync, readdirSync, writeFileSync, cpSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+const HELP = `# Claude Code Plugin Manager (dsh-claude-compat)
+
+Manage Claude Code plugins and marketplaces. State is stored in Claude-native
+locations (~/.claude/plugins, ~/.claude/settings.json enabledPlugins), so
+Claude Code and DSH see the same plugins. Newly installed plugin content
+appears in the DSH skill catalog on next reconcile (MCP servers need a DSH restart).
+
+## Commands (invoked as /cc-plugin <args>)
+- \`/plugin\` — list installed plugins with enable/disable status
+- \`/plugin <name>[@marketplace]\` — one-shot install (e.g. \`/plugin ralph@omc\`)
+- \`/plugin install <name>[@marketplace]\`
+- \`/plugin uninstall <name>\` (alias: remove)
+- \`/plugin enable <name>\` / \`/plugin disable <name>\`
+- \`/plugin update [name]\` — update one plugin or all
+- \`/plugin search <term>\` — search all known marketplaces
+- \`/plugin marketplace list\`
+- \`/plugin marketplace add <github-repo-or-url>\`
+- \`/plugin marketplace remove <name>\`
+- \`/plugin marketplace update [name]\`
+
+## Execution
+Prefers the \`claude plugin\` CLI when available; falls back to direct
+JSON/git manipulation (with automatic timestamped backups of every file it
+touches). Report which engine ran in the result.`;
+
+/** Run `claude plugin ...` args; resolve {ok, stdout} or {ok:false, error}. */
+async function claudePlugin(args, timeoutMs = 120_000) {
+  return execFileAsync('claude', ['plugin', ...args], { timeout: timeoutMs, encoding: 'utf8' })
+    .then(({ stdout }) => ({ ok: true, stdout: stdout ?? '' }))
+    .catch((error) => ({ ok: false, error: error?.message ?? String(error) }));
+}
+
+function pluginsRoot() {
+  return join(homedir(), '.claude', 'plugins');
+}
+
+function backupFile(path) {
+  if (!existsSync(path)) return undefined;
+  const backup = `${path}.bak-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+  copyFileSync(path, backup);
+  return backup;
+}
+
+function readJson(path, fallback) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); }
+  catch { return fallback; }
+}
+
+/** Pure: parse `claude plugin list` output into [{name, marketplace, version, scope, enabled}]. */
+export function parsePluginList(output) {
+  const plugins = [];
+  const lines = String(output ?? '').split('\n');
+  let current;
+  for (const line of lines) {
+    const entry = line.match(/^\s*❯\s*(\S+)@(\S+)\s*$/);
+    if (entry) {
+      if (current) plugins.push(current);
+      current = { name: entry[1], marketplace: entry[2] };
+      continue;
+    }
+    if (!current) continue;
+    const version = line.match(/^\s*Version:\s*(\S+)/);
+    if (version) current.version = version[1];
+    const scope = line.match(/^\s*Scope:\s*(\S+)/);
+    if (scope) current.scope = scope[1];
+    const status = line.match(/^\s*Status:\s*(✔|✘)\s*(\S+)/);
+    if (status) current.enabled = status[2] === 'enabled';
+  }
+  if (current) plugins.push(current);
+  return plugins;
+}
+
+/** Pure: list plugin entries from installed_plugins.json + enabledPlugins map. */
+export function listFromDisk(pluginsDir = pluginsRoot(), settingsPath = join(homedir(), '.claude', 'settings.json')) {
+  const installed = readJson(join(pluginsDir, 'installed_plugins.json'), { version: 2, plugins: {} });
+  const settings = readJson(settingsPath, {});
+  const enabledMap = settings.enabledPlugins ?? {};
+  const out = [];
+  for (const [key, entries] of Object.entries(installed.plugins ?? {})) {
+    const last = Array.isArray(entries) ? entries[entries.length - 1] : entries;
+    if (!last) continue;
+    const [name, marketplace] = key.split('@');
+    const installedEnabled = enabledMap[key];
+    out.push({
+      name,
+      marketplace,
+      version: last.version,
+      scope: last.scope,
+      // enabledPlugins is authoritative when the key exists; default enabled.
+      enabled: installedEnabled === undefined ? true : Boolean(installedEnabled),
+    });
+  }
+  return out;
+}
+
+/** Pure: search marketplace.json catalogs under marketplaces/ for a term. */
+export function searchMarketplaces(term, pluginsDir = pluginsRoot()) {
+  const marketRoot = join(pluginsDir, 'marketplaces');
+  const needle = String(term ?? '').toLowerCase();
+  const hits = [];
+  let dirs = [];
+  try { dirs = readdirSync(marketRoot, { withFileTypes: true }); } catch { return hits; }
+  for (const dir of dirs) {
+    if (!dir.isDirectory()) continue;
+    const manifest = join(marketRoot, dir.name, '.claude-plugin', 'marketplace.json');
+    if (!existsSync(manifest)) continue;
+    const json = readJson(manifest, null);
+    for (const plugin of json?.plugins ?? []) {
+      const haystack = `${plugin.name} ${plugin.description ?? ''} ${(plugin.tags ?? []).join(' ')}`.toLowerCase();
+      if (needle === '' || haystack.includes(needle)) {
+        hits.push({
+          name: plugin.name,
+          marketplace: dir.name,
+          description: plugin.description ?? '',
+          version: plugin.version,
+          installId: `${plugin.name}@${dir.name}`,
+        });
+      }
+    }
+  }
+  return hits;
+}
+
+/**
+ * Fallback install for no-CLI environments: clone the marketplace repo is
+ * already present under marketplaces/<name>; copy plugin source into cache and
+ * register in installed_plugins.json + enabledPlugins.
+ */
+export async function fallbackInstall(installId, pluginsDir = pluginsRoot(), settingsPath = join(homedir(), '.claude', 'settings.json')) {
+  const [pluginName, marketName] = String(installId).split('@');
+  if (!marketName) return { ok: false, error: 'fallback install needs name@marketplace (marketplace repo must already be cloned)' };
+  const marketJson = join(pluginsDir, 'marketplaces', marketName, '.claude-plugin', 'marketplace.json');
+  const catalog = readJson(marketJson, null);
+  const entry = (catalog?.plugins ?? []).find((p) => p.name === pluginName);
+  if (!entry) return { ok: false, error: `plugin "${pluginName}" not found in marketplace "${marketName}"` };
+  const version = entry.version ?? 'unknown';
+  const sourceRel = String(entry.source ?? './').replace(/^\.\//, '');
+  const from = join(pluginsDir, 'marketplaces', marketName, sourceRel);
+  if (!existsSync(from)) return { ok: false, error: `plugin source missing in marketplace clone: ${sourceRel}` };
+  const dest = join(pluginsDir, 'cache', marketName, pluginName, version);
+  mkdirSync(dest, { recursive: true });
+  cpSync(from, dest, { recursive: true });
+  const installedPath = join(pluginsDir, 'installed_plugins.json');
+  backupFile(installedPath);
+  const installed = readJson(installedPath, { version: 2, plugins: {} });
+  const key = `${pluginName}@${marketName}`;
+  installed.plugins[key] = installed.plugins[key] ?? [];
+  installed.plugins[key].push({
+    scope: 'user',
+    installPath: dest,
+    version,
+    installedAt: new Date().toISOString(),
+    lastUpdated: new Date().toISOString(),
+  });
+  writeFileSync(installedPath, JSON.stringify(installed, null, 2) + '\n');
+  backupFile(settingsPath);
+  const settings = readJson(settingsPath, {});
+  settings.enabledPlugins = settings.enabledPlugins ?? {};
+  settings.enabledPlugins[key] = true;
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  return { ok: true, engine: 'fallback', installPath: dest, version };
+}
+
+/** Fallback enable/disable: flip enabledPlugins in settings.json (backed up). */
+export function fallbackToggle(pluginRef, enable, pluginsDir = pluginsRoot(), settingsPath = join(homedir(), '.claude', 'settings.json')) {
+  const installed = readJson(join(pluginsDir, 'installed_plugins.json'), { plugins: {} });
+  const keys = Object.keys(installed.plugins ?? {});
+  const key = keys.find((k) => k === pluginRef || k.startsWith(`${pluginRef}@`));
+  if (!key) return { ok: false, error: `plugin not found: ${pluginRef}` };
+  backupFile(settingsPath);
+  const settings = readJson(settingsPath, {});
+  settings.enabledPlugins = settings.enabledPlugins ?? {};
+  settings.enabledPlugins[key] = Boolean(enable);
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  return { ok: true, engine: 'fallback', key, enabled: Boolean(enable) };
+}
+
+/**
+ * Main dispatcher. Input: the raw argument string after "/plugin".
+ * Returns markdown text for the model to present.
+ */
+export async function runPluginCommand(input, deps = {}) {
+  const claudeFn = deps.claude ?? claudePlugin;
+  const args = String(input ?? '').trim().split(/\s+/).filter(Boolean);
+  if (args.length === 0 || args[0] === 'help') return HELP;
+
+  const [cmd, ...rest] = args;
+
+  // `/plugin <name>[@market]` one-shot install.
+  const isOneShot = !['install', 'uninstall', 'remove', 'enable', 'disable',
+    'update', 'search', 'marketplace', 'list'].includes(cmd);
+  if (isOneShot) return doInstall(cmd, claudeFn);
+
+  if (cmd === 'list') {
+    const res = await claudeFn(['list']);
+    if (res.ok) {
+      const parsed = parsePluginList(res.stdout);
+      if (parsed.length === 0) return 'No plugins installed.';
+      return ['Installed plugins:', '',
+        ...parsed.map((p) => `- **${p.name}@${p.marketplace}** v${p.version} [${p.scope}] ${p.enabled ? '✔ enabled' : '✘ disabled'}`),
+        '', 'Enable/disable with `/plugin enable|disable <name>`; install with `/plugin <name>@<marketplace>`.'].join('\n');
+    }
+    const parsed = listFromDisk();
+    if (parsed.length === 0) return 'No plugins installed (CLI unavailable, disk scan found none).';
+    return ['Installed plugins (disk scan; claude CLI unavailable):', '',
+      ...parsed.map((p) => `- **${p.name}@${p.marketplace}** v${p.version} [${p.scope}] ${p.enabled ? '✔ enabled' : '✘ disabled'}`)].join('\n');
+  }
+
+  if (cmd === 'search') {
+    if (rest.length === 0) return 'Usage: `/plugin search <term>`';
+    const hits = searchMarketplaces(rest.join(' '));
+    if (hits.length === 0) return `No marketplace plugin matches "${rest.join(' ')}".`;
+    return [`Marketplace matches for "${rest.join(' ')}":`, '',
+      ...hits.slice(0, 30).map((h) => `- **${h.installId}** v${h.version ?? '?'} — ${h.description.slice(0, 100)}`),
+      '', 'Install with `/plugin <name>@<marketplace>`.'].join('\n');
+  }
+
+  if (cmd === 'marketplace') {
+    const [sub, ...mrest] = rest;
+    const subArgs = { list: ['marketplace', 'list'], add: ['marketplace', 'add', ...mrest], remove: ['marketplace', 'remove', ...mrest], rm: ['marketplace', 'remove', ...mrest], update: ['marketplace', 'update', ...mrest] }[sub];
+    if (!subArgs) return 'Usage: `/plugin marketplace list|add|remove|update [...]`';
+    const res = await claudeFn(subArgs, 300_000);
+    if (res.ok) return `Marketplace ${sub} OK (engine: claude CLI):\n\n${res.stdout.trim()}`;
+    return `Marketplace ${sub} failed. Engine: claude CLI (unavailable or errored).\n\n${res.error}\n\nFallback for marketplace mutation is not implemented (manual: git clone into ~/.claude/plugins/marketplaces/<name> and register in known_marketplaces.json).`;
+  }
+
+  const passThrough = {
+    install: ['install', ...rest],
+    uninstall: ['uninstall', ...rest],
+    remove: ['uninstall', ...rest],
+    enable: ['enable', ...rest],
+    disable: ['disable', ...rest],
+  }[cmd];
+
+  if (cmd === 'update') {
+    const res = await claudeFn(['update', ...rest], 300_000);
+    if (res.ok) return `Update OK (engine: claude CLI):\n\n${res.stdout.trim()}\n\nRestart DSH to apply MCP changes; skills refresh automatically.`;
+    return `Update failed (engine: claude CLI):\n\n${res.error}`;
+  }
+
+  if (passThrough) {
+    if (passThrough[0] === 'install') return doInstall(rest.join(' '), claudeFn);
+    const res = await claudeFn(passThrough, 300_000);
+    if (res.ok) return `\`${cmd} ${rest.join(' ')}\` OK (engine: claude CLI):\n\n${res.stdout.trim()}`;
+    if ((cmd === 'enable' || cmd === 'disable') && /ENOENT|not found|spawn/i.test(res.error)) {
+      const fb = fallbackToggle(rest[0], cmd === 'enable');
+      if (fb.ok) return `\`${cmd} ${rest[0]}\` OK (engine: fallback, settings.json backed up): ${fb.key} → ${fb.enabled ? 'enabled' : 'disabled'}`;
+      return `Both engines failed:\n- claude CLI: ${res.error}\n- fallback: ${fb.error}`;
+    }
+    return `\`${cmd} ${rest.join(' ')}\` failed (engine: claude CLI):\n\n${res.error}`;
+  }
+
+  return HELP;
+}
+
+async function doInstall(installId, claudeFn) {
+  if (!installId) return 'Usage: `/plugin <name>[@marketplace]`';
+  const res = await claudeFn(['install', installId], 300_000);
+  if (res.ok) {
+    return [`Installed **${installId}** (engine: claude CLI).`, '', res.stdout.trim(),
+      '', 'Skills/commands appear in the catalog on next reconcile; restart DSH if the plugin ships MCP servers.'].join('\n');
+  }
+  const fb = await fallbackInstall(installId);
+  if (fb.ok) {
+    return [`Installed **${installId}** (engine: fallback; installed_plugins.json + settings.json backed up).`,
+      '', `installPath: ${fb.installPath}`, '',
+      'Skills/commands appear in the catalog on next reconcile; restart DSH if the plugin ships MCP servers.'].join('\n');
+  }
+  return [`Install failed for **${installId}**:`, '', `- claude CLI: ${res.error}`, `- fallback: ${fb.error}`].join('\n');
+}
+
+export const PLUGIN_SKILL_NAME = 'plugin';
+export const PLUGIN_SKILL_BODY = HELP;