context-plugins 0.2.0 → 0.4.0

package/README.md

@@ -23,11 +23,42 @@ context-plugins uninstall <plugin> [options]   # remove it again
 context-plugins update                         # refresh everything already installed
 context-plugins list                           # what the marketplace offers
 context-plugins installed                      # what this machine has
+context-plugins doctor                         # check this machine can install
 ```
 
+## Something not working?
+
+`doctor` checks everything an install depends on and says which part is unhappy:
+
+```
+$ npx context-plugins doctor
+
+Environment
+  ✓   Node.js          v20.11.0
+  ✓   git              git version 2.43.0
+
+Editors
+  ✓   Claude Code      claude on PATH
+  ✓   Cursor           ~/.cursor
+  !   VS Code          not installed (looked in ~/.config/Code/User)
+
+Marketplace
+  ✓   Reachable        raw.githubusercontent.com
+  ✓   Registry         context-plugins, 44 plugins
+  ✓   API budget       59 of 60 requests left
+
+Local state
+  ✓   State directory  ~/.context-plugins (writable)
+  ✓   Installed        2 plugins
+```
+
+`✓` fine, `!` works but worth knowing, `x` blocks an install. It exits non-zero
+only when something blocks, so it can be used in a script; add `--json` for machine-readable
+output.
+
 | Option | Default | Description |
 | --- | --- | --- |
-| `--repo <owner/repo>` | `context-plugins/plugin-marketplace` | Marketplace repository |
+| `--repo <owner/repo>` | the bundled marketplace | Install from a different marketplace |
 | `--ref <branch\|tag\|sha>` | `main` | Version to install from |
 | `--marketplace <name>` | read from `marketplace.json` | Marketplace name |
 | `--targets <list>` | ask | `claude`, `cursor`, `vscode`, or `all` — skips the prompt |

package/bin/cli.js

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
 'use strict';
 
+// Checked before anything else loads. Node below 18 has no global fetch and no
+// node:readline/promises, so without this the failure is a bare
+// "fetch is not defined" from somewhere deep in the fetch path.
+require('../src/require-node')();
+
 require('../src/cli')
   .run(process.argv.slice(2))
   .then((code) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-plugins",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Install a plugin from a plugin marketplace into Claude Code, Cursor, and VS Code with one command.",
   "keywords": [
     "claude-code",

package/run.js

@@ -8,6 +8,7 @@
  * variables still take precedence over it.
  */
 module.exports = function runWithProfile(profile = {}, argv = process.argv.slice(2)) {
+  require('./src/require-node')();
   return require('./src/cli')
     .run(argv, profile)
     .then((code) => {

package/src/brand.js

@@ -49,6 +49,13 @@ function resolveBrand({
 } = {}) {
   const rc = readRc(cwd) || readRc(home) || {};
 
+  const displayName = firstSet(
+    env.CP_DISPLAY_NAME,
+    rc.displayName,
+    profile.displayName,
+    DEFAULT_PROFILE.displayName,
+  );
+
   const brand = {
     repo: firstSet(flags.repo, env.CP_REPO, rc.repo, profile.repo, DEFAULT_PROFILE.repo),
     ref: firstSet(flags.ref, env.CP_REF, rc.ref, profile.ref, DEFAULT_PROFILE.ref),
@@ -60,11 +67,14 @@ function resolveBrand({
         profile.id,
         DEFAULT_PROFILE.id,
       ) || null,
-    displayName: firstSet(
-      env.CP_DISPLAY_NAME,
-      rc.displayName,
-      profile.displayName,
-      DEFAULT_PROFILE.displayName,
+    displayName,
+    // What the user sees in place of the repository. The repository is an
+    // implementation detail of where plugins are stored.
+    label: firstSet(
+      env.CP_MARKETPLACE_LABEL,
+      rc.marketplaceLabel,
+      profile.label,
+      `${displayName} Marketplace`,
     ),
     bin: firstSet(profile.bin, DEFAULT_PROFILE.bin),
   };

package/src/catalog.js

@@ -1,11 +1,14 @@
 'use strict';
 
-const { UserError, assertRepo, assertRef, stripBom } = require('./util');
+const { UserError, assertRepo, assertRef, stripBom, suggest } = require('./util');
 
 // Claude Code and Cursor read the same registry shape from different folders.
 // We prefer the Claude one and fall back to Cursor's.
 const REGISTRY_FILES = ['.claude-plugin/marketplace.json', '.cursor-plugin/marketplace.json'];
 
+// Claude Code's marketplace schema: kebab-case identifier, no spaces.
+const MARKETPLACE_RE = /^[a-z0-9]+(?:[-_.][a-z0-9]+)*$/i;
+
 const rawUrl = (repo, ref, filePath) =>
   `https://raw.githubusercontent.com/${repo}/${ref}/${filePath}`;
 
@@ -16,13 +19,29 @@ function ghHeaders(env = process.env) {
   return headers;
 }
 
+/**
+ * Node's built-in fetch ignores HTTP_PROXY / HTTPS_PROXY, so on a network that
+ * requires a proxy this fails even though `git` - which does read the proxy
+ * settings - would succeed. Worth saying, because the raw error is just a
+ * connect timeout.
+ */
+function networkHint(env = process.env) {
+  const proxied = env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy;
+  if (proxied) {
+    return 'A proxy is configured, but Node does not apply it to its own requests. Check your network, or see the docs for NODE_USE_ENV_PROXY.';
+  }
+  return 'Check your network connection, or whether access to github.com is blocked.';
+}
+
 /** GET JSON, returning null for 404 so a missing registry is not an error. */
 async function getJson(url, { env = process.env, fetchImpl = fetch } = {}) {
   let res;
   try {
     res = await fetchImpl(url, { headers: ghHeaders(env), redirect: 'follow' });
   } catch (err) {
-    throw new UserError(`Network request failed: ${url}`, { hint: err.message });
+    throw new UserError(`Could not reach ${new URL(url).host}: ${err.message}`, {
+      hint: networkHint(env),
+    });
   }
   if (res.status === 404) return null;
   if (!res.ok) {
@@ -83,7 +102,9 @@ function sourcePathFor(entry, plugin) {
  * Resolve everything the installers need for one plugin:
  * the marketplace name (derived unless overridden) and the folder inside the repo.
  */
-async function resolvePlugin({ repo, ref, plugin, marketplace = null, deps = {} }) {
+async function resolvePlugin({ repo, ref, plugin, marketplace = null, label, deps = {} }) {
+  // `label` is what the user sees; the repository stays an internal detail.
+  const shown = label || `${repo}@${ref}`;
   const catalog = await loadCatalog({ repo, ref, deps });
   const entry = entryFor(catalog, plugin);
 
@@ -91,18 +112,33 @@ async function resolvePlugin({ repo, ref, plugin, marketplace = null, deps = {}
     const known = catalog.plugins
       .map((p) => (typeof p === 'string' ? p : p && p.name))
       .filter(Boolean);
-    throw new UserError(`Plugin '${plugin}' is not listed in ${repo}@${ref}.`, {
-      hint: known.length ? `Available: ${known.slice(0, 12).join(', ')}` : undefined,
+    const close = suggest(plugin, known);
+    throw new UserError(`Plugin '${plugin}' is not listed in ${shown}.`, {
+      hint: close.length
+        ? `Did you mean: ${close.join(', ')}?  Run 'list' to see all ${known.length}.`
+        : `Run 'list' to see the ${known.length} available plugins.`,
     });
   }
 
   const resolvedMarketplace = marketplace || (catalog && catalog.marketplace);
   if (!resolvedMarketplace) {
-    throw new UserError(`Could not determine the marketplace name for ${repo}@${ref}.`, {
+    throw new UserError(`Could not determine the marketplace name for ${shown}.`, {
       hint: `No 'name' in ${REGISTRY_FILES[0]}. Pass --marketplace <name>.`,
     });
   }
 
+  // Claude Code requires a kebab-case marketplace id. Catching it here names the
+  // real problem; otherwise the failure surfaces much later as a bare
+  // "plugin not found in marketplace" from the Claude CLI.
+  if (!MARKETPLACE_RE.test(resolvedMarketplace)) {
+    throw new UserError(
+      `Marketplace name '${resolvedMarketplace}' is not a valid identifier.`,
+      {
+        hint: `It must be kebab-case with no spaces (e.g. my-marketplace). Fix 'name' in ${REGISTRY_FILES[0]}.`,
+      },
+    );
+  }
+
   return {
     plugin,
     repo,

package/src/cli.js

@@ -4,13 +4,17 @@ const log = require('./log');
 const paths = require('./paths');
 const manifest = require('./manifest');
 const { resolveBrand } = require('./brand');
-const { NAMES } = require('./harness');
+const { NAMES, byName } = require('./harness');
 const { UserError } = require('./util');
 const { installPlugin, uninstallPlugin, updateAll, listPlugins } = require('./install');
+const { diagnose } = require('./doctor');
 const pkg = require('../package.json');
 
 const VALUE_FLAGS = new Set(['repo', 'ref', 'marketplace', 'targets']);
-const BOOL_FLAGS = new Set(['force', 'yes', 'verbose', 'quiet', 'json', 'help', 'version']);
+const BOOL_FLAGS = new Set(['force', 'yes', 'long', 'verbose', 'quiet', 'json', 'help', 'version']);
+
+// A plugin id longer than this is treated as an outlier when sizing the list grid.
+const OUTLIER_NAME = 36;
 
 const camel = (s) => s.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
 const lowerFirst = (s) => s.charAt(0).toLowerCase() + s.slice(1);
@@ -83,14 +87,16 @@ Usage
   ${bin} update
   ${bin} list
   ${bin} installed
+  ${bin} doctor
 
 Options
-  --repo <owner/repo>   Marketplace repository        (default: ${brand.repo})
+  --repo <owner/repo>   Use a different marketplace   (default: ${brand.label})
   --ref <branch|tag|sha> Version to install from       (default: ${brand.ref})
-  --marketplace <name>  Marketplace name              (default: read from marketplace.json)
+  --marketplace <name>  Marketplace name              (default: read from the marketplace)
   --targets <list>      Comma-separated: ${NAMES.join(', ')}, all   (skips the prompt)
   -y, --yes             Accept every detected harness without asking
   --force               Replace a plugin installed from another marketplace
+  --long                Show plugin descriptions (list)
   --json                Machine-readable output (list, installed)
   --verbose             Show underlying git / CLI detail
   --quiet               Suppress progress output
@@ -196,15 +202,78 @@ async function run(argv = process.argv.slice(2), profile = {}) {
           log.plain(JSON.stringify(result, null, 2));
           return 0;
         }
-        log.banner(`${result.plugins.length} plugin(s) in ${result.repo} (marketplace: ${result.marketplace})`);
-        for (const p of result.plugins) {
-          log.plain(`  ${p.installed ? '*' : ' '} ${p.name}`);
-          if (p.description) log.info(p.description);
+        const plugins = [...result.plugins].sort((a, b) => a.name.localeCompare(b.name));
+        log.banner(`${log.plural(plugins.length, 'plugin')} in ${result.label}`);
+        log.plain('');
+
+        if (flags.long) {
+          // Full detail, one plugin per block.
+          for (const p of plugins) {
+            const mark = p.installed ? log.MARK : ' ';
+            log.plain(`  ${mark} ${log.bold(p.name)}`);
+            if (p.description) log.info(p.description);
+          }
+        } else {
+          // A grid of names. Descriptions in a marketplace are long and largely
+          // boilerplate, so a truncated column of them shows the same prefix on
+          // every row and crowds out the one thing that differs.
+          // Sized to the longest name that is not an outlier. Using the true
+          // maximum lets one very long id set the width for every column and
+          // collapse the grid; using a percentile makes a third of the rows
+          // ragged. Ignoring only the outliers keeps every ordinary row aligned.
+          const lengths = plugins.map((p) => p.name.length);
+          const cell = Math.max(16, ...lengths.filter((l) => l <= OUTLIER_NAME)) + 3;
+          const cols = Math.max(1, Math.floor((log.width(120) - 2) / cell));
+          const rows = Math.ceil(plugins.length / cols);
+          for (let r = 0; r < rows; r += 1) {
+            let line = '  ';
+            for (let c = 0; c < cols; c += 1) {
+              const p = plugins[c * rows + r]; // column-major keeps A-Z reading down
+              if (!p) continue;
+              line += `${p.installed ? log.MARK : ' '} ${p.name.padEnd(cell - 2)}`;
+            }
+            log.plain(line.trimEnd());
+          }
         }
+
         log.plain('');
-        log.info('* = installed on this machine');
+        const count = plugins.filter((p) => p.installed).length;
+        if (count) log.info(`${log.MARK} installed on this machine (${count})`);
+        if (!flags.long) log.info(`Run \`${bin} list --long\` for descriptions.`);
+        log.info(`Install one with \`${bin} install <plugin>\`.`);
         return 0;
       }
+      case 'doctor': {
+        const report = await diagnose({ brand });
+        if (flags.json) {
+          log.plain(JSON.stringify(report, null, 2));
+          return report.ok ? 0 : 1;
+        }
+
+        const labels = report.groups.flatMap((g) => g.checks.map((c) => c.label.length));
+        const labelWidth = Math.min(Math.max(...labels, 8), 22);
+        for (const group of report.groups) {
+          log.step(group.title);
+          for (const c of group.checks) {
+            const symbol = { ok: log.MARK, warn: '!', fail: 'x' }[c.status];
+            const paint = c.status === 'ok' ? log.dim : (s) => s;
+            log.plain(`  ${symbol}   ${c.label.padEnd(labelWidth)}  ${paint(c.detail)}`);
+            if (c.hint) log.info(c.hint);
+          }
+        }
+
+        log.plain('');
+        log.rule();
+        if (report.failures) {
+          log.error(`${log.plural(report.failures, 'problem')} found.`);
+        } else if (report.warnings) {
+          log.ok(`No problems. ${log.plural(report.warnings, 'warning')}.`);
+        } else {
+          log.ok('Everything checks out.');
+        }
+        log.plain('');
+        return report.ok ? 0 : 1;
+      }
       case 'installed': {
         const entries = manifest.list(paths.manifestPath());
         if (flags.json) {
@@ -212,14 +281,19 @@ async function run(argv = process.argv.slice(2), profile = {}) {
           return 0;
         }
         if (!entries.length) {
-          log.info('No plugins installed by this tool yet.');
+          log.info('No plugins installed yet.');
+          log.info(`Browse what is available with:  ${bin} list`);
           return 0;
         }
-        log.banner(`${entries.length} plugin(s) installed`);
+        log.banner(`${log.plural(entries.length, 'plugin')} installed`);
+        log.plain('');
+        const idWidth = Math.min(Math.max(...entries.map((e) => e.plugin.length), 4), 42);
         for (const e of entries) {
-          log.plain(`  ${e.plugin}  [${(e.targets || []).join(', ')}]`);
-          log.info(`${e.repo}@${e.ref}  (marketplace: ${e.marketplace})`);
+          const where = (e.targets || []).map((n) => (byName(n) ? byName(n).title : n));
+          log.plain(`    ${e.plugin.padEnd(idWidth)}  ${log.dim(where.join(', '))}`);
+          log.debug(`${e.repo}@${e.ref}  (marketplace: ${e.marketplace})`);
         }
+        log.plain('');
         return 0;
       }
       default:

package/src/doctor.js

@@ -0,0 +1,171 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const paths = require('./paths');
+const manifest = require('./manifest');
+const { HARNESSES } = require('./harness');
+const { loadCatalog, ghHeaders, rawUrl, REGISTRY_FILES } = require('./catalog');
+const { which, run, shortPath, ensureDir, rmrf } = require('./util');
+
+const MIN_NODE = 18;
+const MARKETPLACE_RE = /^[a-z0-9]+(?:[-_.][a-z0-9]+)*$/i;
+
+const ok = (label, detail) => ({ status: 'ok', label, detail });
+const warn = (label, detail, hint) => ({ status: 'warn', label, detail, hint });
+const fail = (label, detail, hint) => ({ status: 'fail', label, detail, hint });
+
+async function checkEnvironment(deps) {
+  const whichImpl = deps.which || which;
+  const runImpl = deps.run || run;
+  const env = deps.env || process.env;
+  const checks = [];
+
+  const version = process.versions.node;
+  const major = parseInt(version.split('.')[0], 10);
+  checks.push(
+    major >= MIN_NODE
+      ? ok('Node.js', `v${version}`)
+      : fail('Node.js', `v${version}`, `Version ${MIN_NODE} or newer is required.`),
+  );
+
+  const git = whichImpl('git', env);
+  if (git) {
+    let detail = shortPath(git);
+    try {
+      const res = await runImpl(git, ['--version']);
+      if (res.code === 0 && res.stdout.trim()) detail = res.stdout.trim();
+    } catch {
+      /* the path alone is enough */
+    }
+    checks.push(ok('git', detail));
+  } else {
+    checks.push(
+      warn('git', 'not found', 'Plugins download through the GitHub API instead, which is rate limited to 60 requests an hour.'),
+    );
+  }
+
+  const proxy = env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy;
+  if (proxy) {
+    checks.push(
+      warn(
+        'Proxy',
+        'configured for the shell',
+        'Node does not apply HTTP_PROXY or HTTPS_PROXY to its own requests, so downloads may fail here even where git succeeds.',
+      ),
+    );
+  }
+
+  return checks;
+}
+
+function checkEditors(pathOpts) {
+  const checks = HARNESSES.map((h) =>
+    h.detect(pathOpts)
+      ? ok(h.title, h.location(pathOpts))
+      : warn(h.title, `not installed (looked in ${h.location(pathOpts)})`),
+  );
+  if (!checks.some((c) => c.status === 'ok')) {
+    checks.push(
+      fail(
+        'Any editor',
+        'none found',
+        'Install Claude Code, Cursor, or VS Code - there is nowhere to install a plugin.',
+      ),
+    );
+  }
+  return checks;
+}
+
+async function checkMarketplace(brand, deps) {
+  const fetchImpl = deps.fetchImpl || fetch;
+  const env = deps.env || process.env;
+  const checks = [];
+
+  let catalog = null;
+  try {
+    catalog = await loadCatalog({ repo: brand.repo, ref: brand.ref, deps });
+    checks.push(ok('Reachable', new URL(rawUrl(brand.repo, brand.ref, REGISTRY_FILES[0])).host));
+  } catch (err) {
+    checks.push(fail('Reachable', err.message, err.hint));
+    return checks;
+  }
+
+  if (!catalog) {
+    checks.push(fail('Registry', `no ${REGISTRY_FILES[0]} found`, 'Check --repo and --ref.'));
+    return checks;
+  }
+
+  const name = catalog.marketplace;
+  checks.push(
+    name && MARKETPLACE_RE.test(name)
+      ? ok('Registry', `${name}, ${catalog.plugins.length} plugins`)
+      : fail(
+          'Registry',
+          `name ${JSON.stringify(name)} is not a valid identifier`,
+          `It must be kebab-case with no spaces. Fix 'name' in ${REGISTRY_FILES[0]}.`,
+        ),
+  );
+
+  // Only meaningful when the API is the download path; with git it is unused.
+  try {
+    const res = await fetchImpl('https://api.github.com/rate_limit', { headers: ghHeaders(env) });
+    if (res.ok) {
+      const body = await res.json();
+      const core = body.resources && body.resources.core;
+      if (core) {
+        const detail = `${core.remaining} of ${core.limit} requests left`;
+        checks.push(core.remaining > 10 ? ok('API budget', detail) : warn('API budget', detail, 'Set GITHUB_TOKEN, or install git to avoid the API entirely.'));
+      }
+    }
+  } catch {
+    /* advisory only */
+  }
+
+  return checks;
+}
+
+function checkState(pathOpts) {
+  const dir = paths.stateDir(pathOpts);
+  const checks = [];
+  try {
+    ensureDir(dir);
+    const probe = path.join(dir, `.write-probe-${process.pid}`);
+    fs.writeFileSync(probe, 'ok');
+    rmrf(probe);
+    checks.push(ok('State directory', `${shortPath(dir)} (writable)`));
+  } catch (err) {
+    checks.push(
+      fail('State directory', `${shortPath(dir)} is not writable`, err.message),
+    );
+  }
+
+  try {
+    const entries = manifest.list(paths.manifestPath(pathOpts));
+    const detail = entries.length ? `${entries.length} ${entries.length === 1 ? 'plugin' : 'plugins'}` : 'none yet';
+    checks.push(ok('Installed', detail));
+  } catch (err) {
+    checks.push(warn('Installed', 'could not read installed.json', err.message));
+  }
+  return checks;
+}
+
+/** Collect every check, grouped for display. Never throws: a broken check is a result. */
+async function diagnose({ brand, deps = {}, pathOpts } = {}) {
+  const groups = [
+    { title: 'Environment', checks: await checkEnvironment(deps) },
+    { title: 'Editors', checks: checkEditors(pathOpts) },
+    { title: 'Marketplace', checks: await checkMarketplace(brand, deps) },
+    { title: 'Local state', checks: checkState(pathOpts) },
+  ];
+  const all = groups.flatMap((g) => g.checks);
+  return {
+    groups,
+    failures: all.filter((c) => c.status === 'fail').length,
+    warnings: all.filter((c) => c.status === 'warn').length,
+    ok: !all.some((c) => c.status === 'fail'),
+  };
+}
+
+module.exports = { diagnose, MIN_NODE };

package/src/fetch.js

@@ -52,7 +52,8 @@ async function materialize({ repo, ref, sourcePath, deps = {} }) {
 async function viaGit({ git, repo, ref, sourcePath, work }) {
   const clone = path.join(work, 'repo');
   const url = `https://github.com/${repo}.git`;
-  log.info(`Fetching marketplace via git (${repo}@${ref}) ...`);
+  log.info('Fetching marketplace via git ...');
+  log.debug(`${url} (${ref}), sparse path ${sourcePath}`);
 
   const base = ['clone', '--quiet', '--depth', '1', '--filter=blob:none', '--sparse'];
 

package/src/harness/claude.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const log = require('../log');
-const { which, run, UserError } = require('../util');
+const { which, run, UserError, stripBom } = require('../util');
 
 // Claude Code installs from the marketplace itself - no local copy needed.
 const name = 'claude';
@@ -15,6 +15,26 @@ const detect = (opts) => Boolean(cli(opts));
 const tail = (res) =>
   (res.stderr || res.stdout || '').trim().split('\n').slice(-3).join(' ').trim();
 
+/**
+ * The name Claude Code knows this marketplace by.
+ *
+ * Claude keys a marketplace by the name it carried when it was added, which can
+ * drift from the current `name` in marketplace.json. Installing with the name
+ * from the file then fails with a bare "plugin not found in marketplace", so ask
+ * Claude what it calls the entry for this repository.
+ */
+async function registeredName(claude, repo) {
+  const res = await run(claude, ['plugin', 'marketplace', 'list', '--json']);
+  if (res.code !== 0) return null;
+  try {
+    const entries = JSON.parse(stripBom(res.stdout));
+    const hit = entries.find((m) => m.repo === repo || String(m.url || '').includes(repo));
+    return hit && hit.name ? hit.name : null;
+  } catch {
+    return null; // older CLI without --json
+  }
+}
+
 async function install({ plugin, marketplace, repo }, opts) {
   const claude = cli(opts);
   if (!claude) {
@@ -24,10 +44,14 @@ async function install({ plugin, marketplace, repo }, opts) {
 
   const added = await run(claude, ['plugin', 'marketplace', 'add', repo]);
   if (added.code !== 0) {
-    log.info(`marketplace add returned ${added.code} (likely already added) - continuing.`);
+    log.debug(`marketplace add returned ${added.code} (likely already added) - continuing.`);
   }
 
-  const target = `${plugin}@${marketplace}`;
+  const known = await registeredName(claude, repo);
+  if (known && known !== marketplace) {
+    log.debug(`Claude knows this marketplace as '${known}', not '${marketplace}'.`);
+  }
+  const target = `${plugin}@${known || marketplace}`;
   const res = await run(claude, ['plugin', 'install', target, '--scope', 'user']);
   if (res.code !== 0) {
     throw new UserError(`claude plugin install ${target} failed (exit ${res.code}). ${tail(res)}`.trim());
@@ -37,13 +61,14 @@ async function install({ plugin, marketplace, repo }, opts) {
   return true;
 }
 
-async function uninstall({ plugin, marketplace }, opts) {
+async function uninstall({ plugin, marketplace, repo }, opts) {
   const claude = cli(opts);
   if (!claude) {
     log.warn("'claude' CLI not on PATH - skipping Claude Code.");
     return false;
   }
-  const target = `${plugin}@${marketplace}`;
+  const known = await registeredName(claude, repo);
+  const target = `${plugin}@${known || marketplace}`;
   const res = await run(claude, ['plugin', 'uninstall', target, '--scope', 'user']);
   if (res.code !== 0) {
     log.warn(`claude plugin uninstall ${target} returned ${res.code}. ${tail(res)}`.trim());
@@ -54,4 +79,6 @@ async function uninstall({ plugin, marketplace }, opts) {
   return true;
 }
 
-module.exports = { name, title, detect, install, uninstall, needsSource: false };
+const location = () => 'claude on PATH';
+
+module.exports = { name, title, detect, location, install, uninstall, needsSource: false };

package/src/harness/cursor.js

@@ -5,7 +5,7 @@ const path = require('path');
 
 const log = require('../log');
 const paths = require('../paths');
-const { replaceDir, rmrf, exists } = require('../util');
+const { replaceDir, rmrf, exists, shortPath } = require('../util');
 
 const name = 'cursor';
 const title = 'Cursor';
@@ -27,7 +27,7 @@ async function install({ plugin, srcDir }, opts) {
   fs.mkdirSync(path.dirname(dest), { recursive: true });
   replaceDir(srcDir, dest);
 
-  log.ok(`Installed -> ${dest}`);
+  log.ok(`Installed -> ${shortPath(dest)}`);
   log.info('Please reload Cursor: Ctrl+Shift+P (Cmd+Shift+P) -> Developer: Reload Window');
   return true;
 }
@@ -35,13 +35,15 @@ async function install({ plugin, srcDir }, opts) {
 async function uninstall({ plugin }, opts) {
   const dest = destFor(plugin, opts);
   if (!exists(dest)) {
-    log.info(`Nothing to remove at ${dest}`);
+    log.info(`Nothing to remove at ${shortPath(dest)}`);
     return false;
   }
   rmrf(dest);
-  log.ok(`Removed -> ${dest}`);
+  log.ok(`Removed -> ${shortPath(dest)}`);
   log.info('Please reload Cursor: Ctrl+Shift+P (Cmd+Shift+P) -> Developer: Reload Window');
   return true;
 }
 
-module.exports = { name, title, detect, install, uninstall, needsSource: true, destFor };
+const location = (opts) => shortPath(paths.cursorRoot(opts));
+
+module.exports = { name, title, detect, location, install, uninstall, needsSource: true, destFor };

package/src/harness/vscode.js

@@ -5,7 +5,7 @@ const path = require('path');
 const log = require('../log');
 const paths = require('../paths');
 const { addPluginLocation, removePluginLocation } = require('../settings-merge');
-const { replaceDir, rmrf, exists } = require('../util');
+const { replaceDir, rmrf, exists, shortPath } = require('../util');
 
 // VS Code loads a plugin from anywhere on disk once the folder is listed in
 // `chat.pluginLocations`, so we keep our own copy under the state dir rather
@@ -19,7 +19,7 @@ const destFor = (plugin, opts) => path.join(paths.vscodeStoreDir(opts), plugin);
 
 async function install({ plugin, srcDir }, opts) {
   if (!detect(opts)) {
-    log.warn(`${paths.vscodeUserDir(opts)} not found - VS Code not installed, skipping.`);
+    log.warn(`${shortPath(paths.vscodeUserDir(opts))} not found - VS Code not installed, skipping.`);
     return false;
   }
 
@@ -29,9 +29,9 @@ async function install({ plugin, srcDir }, opts) {
   const settings = paths.vscodeSettingsPath(opts);
   const result = addPluginLocation(settings, dest);
 
-  log.ok(`Installed -> ${dest}`);
-  if (result.action === 'already') log.info(`Already registered in ${settings}`);
-  else log.info(`Registered in chat.pluginLocations (${settings})`);
+  log.ok(`Installed -> ${shortPath(dest)}`);
+  if (result.action === 'already') log.info(`Already registered in ${shortPath(settings)}`);
+  else log.info(`Registered in chat.pluginLocations (${shortPath(settings)})`);
   // The backup always happens; it is only worth mentioning when asked for detail.
   if (result.backup) log.debug(`Backed up settings.json -> ${path.basename(result.backup)}`);
   log.info('Please reload VS Code: Ctrl+Shift+P (Cmd+Shift+P) -> Developer: Reload Window');
@@ -46,14 +46,16 @@ async function uninstall({ plugin }, opts) {
   if (had) rmrf(dest);
 
   if (!had && result.action !== 'removed') {
-    log.info(`Nothing to remove at ${dest}`);
+    log.info(`Nothing to remove at ${shortPath(dest)}`);
     return false;
   }
-  log.ok(`Removed -> ${dest}`);
-  if (result.action === 'removed') log.info(`Unregistered from chat.pluginLocations (${settings})`);
+  log.ok(`Removed -> ${shortPath(dest)}`);
+  if (result.action === 'removed') log.info(`Unregistered from chat.pluginLocations (${shortPath(settings)})`);
   if (result.backup) log.debug(`Backed up settings.json -> ${path.basename(result.backup)}`);
   log.info('Please reload VS Code: Ctrl+Shift+P (Cmd+Shift+P) -> Developer: Reload Window');
   return true;
 }
 
-module.exports = { name, title, detect, install, uninstall, needsSource: true, destFor };
+const location = (opts) => shortPath(paths.vscodeUserDir(opts));
+
+module.exports = { name, title, detect, location, install, uninstall, needsSource: true, destFor };

package/src/install.js

@@ -5,7 +5,7 @@ const paths = require('./paths');
 const manifest = require('./manifest');
 const { resolvePlugin, loadCatalog } = require('./catalog');
 const { materialize } = require('./fetch');
-const { byName, resolveTargets } = require('./harness');
+const { byName, resolveTargets, NAMES } = require('./harness');
 const { isInteractive, createPrompter } = require('./prompt');
 const { assertPlugin, UserError } = require('./util');
 
@@ -55,10 +55,9 @@ function assertNoMarketplaceConflict(manifestFile, { plugin, repo }, force) {
     .list(manifestFile)
     .find((p) => p.plugin === plugin && (p.repo || '') !== repo);
   if (clash) {
-    throw new UserError(
-      `'${plugin}' is already installed from a different marketplace (${clash.repo}).`,
-      { hint: `Uninstall it first, or re-run with --force to replace it.` },
-    );
+    throw new UserError(`'${plugin}' is already installed from a different marketplace.`, {
+      hint: 'Uninstall it first, or re-run with --force to replace it.',
+    });
   }
 }
 
@@ -81,29 +80,51 @@ async function installPlugin({
     ref: effectiveRef,
     plugin,
     marketplace: brand.id,
+    label: brand.label,
     deps,
   });
 
   const requested = resolveTargets(targets);
   assertNoMarketplaceConflict(manifestFile, { plugin, repo: brand.repo }, force);
 
-  log.banner(`Installing '${plugin}'  (marketplace: ${resolved.marketplace}, repo: ${brand.repo}@${effectiveRef})`);
+  const from = effectiveRef === 'main' ? brand.label : `${brand.label} (${effectiveRef})`;
+  log.banner(`Installing '${plugin}' from ${from}`);
+  log.debug(`source: ${brand.repo}@${effectiveRef}, marketplace: ${resolved.marketplace}`);
   if (resolved.description) log.info(resolved.description);
   log.rule();
 
   log.step('[Harnesses]');
+  const explicit = Array.isArray(targets) && targets.length > 0;
   const available = requested.filter((name) => byName(name).detect(pathOpts));
-  for (const name of requested) {
-    if (!available.includes(name)) log.info(`${byName(name).title} not detected - skipping.`);
+  const missing = requested.filter((name) => !available.includes(name));
+
+  for (const name of missing) {
+    const h = byName(name);
+    log.info(`${h.title} is not installed (looked in ${h.location(pathOpts)}).`);
   }
+
+  // Nothing to install into is a failure, not a quiet no-op. Saying which
+  // editor was asked for beats a generic "no harness found" when the user
+  // named one explicitly.
   if (!available.length) {
-    log.plain('');
-    log.warn('No supported harness found. Install Claude Code, Cursor, or VS Code first.');
-    return { plugin, targets: [], marketplace: resolved.marketplace, ref: effectiveRef };
+    const names = missing.map((n) => byName(n).title);
+    throw new UserError(
+      explicit
+        ? `${names.join(' and ')} ${names.length === 1 ? 'is' : 'are'} not installed on this machine.`
+        : 'No supported editor found on this machine.',
+      {
+        hint: explicit
+          ? `Install it first, or choose another with --targets ${NAMES.join(',')}.`
+          : 'Install Claude Code, Cursor, or VS Code, then run this again.',
+      },
+    );
+  }
+  if (missing.length) {
+    log.info(`Continuing with ${available.map((n) => byName(n).title).join(', ')}.`);
   }
 
   const want = await chooseHarnesses(available, {
-    explicit: Array.isArray(targets) && targets.length > 0,
+    explicit,
     assumeYes,
     confirm: deps.confirm,
   });
@@ -180,7 +201,7 @@ async function uninstallPlugin({ brand, plugin, targets, deps = {}, pathOpts } =
     ).marketplace;
   }
 
-  log.banner(`Uninstalling '${plugin}'  (repo: ${brand.repo})`);
+  log.banner(`Uninstalling '${plugin}' from ${brand.label}`);
   log.info(`Removing from: ${want.map((n) => byName(n).title).join(', ')}`);
   log.rule();
 
@@ -209,13 +230,19 @@ async function updateAll({ brand, force = false, deps = {}, pathOpts } = {}) {
   const manifestFile = paths.manifestPath(pathOpts);
   const entries = manifest.list(manifestFile);
   if (!entries.length) {
-    log.warn(`Nothing recorded in ${manifestFile} - install a plugin first.`);
+    log.warn('No plugins installed yet - nothing to update.');
     return { updated: [], failed: [] };
   }
 
-  log.banner(`Updating ${entries.length} plugin(s) from ${manifestFile}`);
+  log.banner(`Updating ${log.plural(entries.length, 'plugin')}`);
+  log.plain('');
   const updated = [];
   const failed = [];
+  // Each plugin would otherwise print a full install report; at five plugins
+  // that is sixty lines of scrollback to find one failure in. Collapse to a
+  // line each unless --verbose asked for the detail.
+  const collapse = !log.isVerbose && !log.isQuiet;
+  const idWidth = Math.min(Math.max(...entries.map((e) => e.plugin.length), 4), 42);
 
   for (const entry of entries) {
     const entryBrand = Object.freeze({
@@ -224,8 +251,9 @@ async function updateAll({ brand, force = false, deps = {}, pathOpts } = {}) {
       ref: entry.ref || brand.ref,
       id: entry.marketplace || brand.id,
     });
+    if (collapse) log.setQuiet(true);
     try {
-      await installPlugin({
+      const result = await installPlugin({
         brand: entryBrand,
         plugin: entry.plugin,
         ref: entry.ref,
@@ -235,23 +263,32 @@ async function updateAll({ brand, force = false, deps = {}, pathOpts } = {}) {
         deps,
         pathOpts,
       });
+      if (collapse) log.setQuiet(false);
       updated.push(entry.plugin);
+      const where = (result.targets || []).map((n) => byName(n).title).join(', ');
+      if (collapse) log.ok(`${entry.plugin.padEnd(idWidth)}  ${log.dim(where)}`);
     } catch (err) {
+      if (collapse) log.setQuiet(false);
       failed.push({ plugin: entry.plugin, error: err.message });
-      log.error(`${entry.plugin}: ${err.message}`);
+      log.error(`${entry.plugin.padEnd(idWidth)}  ${err.message}`);
     }
   }
 
+  log.plain('');
   log.rule();
-  log.ok(`Updated ${updated.length}/${entries.length}`);
-  if (failed.length) log.warn(`Failed: ${failed.map((f) => f.plugin).join(', ')}`);
+  if (failed.length) {
+    log.warn(`Updated ${updated.length} of ${entries.length}; failed: ${failed.map((f) => f.plugin).join(', ')}`);
+  } else {
+    log.ok(`Updated ${log.plural(updated.length, 'plugin')}`);
+  }
+  log.plain('');
   return { updated, failed };
 }
 
 async function listPlugins({ brand, deps = {}, pathOpts } = {}) {
   const catalog = await loadCatalog({ repo: brand.repo, ref: brand.ref, deps });
   if (!catalog) {
-    throw new UserError(`No marketplace registry found in ${brand.repo}@${brand.ref}.`, {
+    throw new UserError(`Could not read ${brand.label}.`, {
       hint: 'Check --repo, or the branch you pointed at with --ref.',
     });
   }
@@ -262,6 +299,7 @@ async function listPlugins({ brand, deps = {}, pathOpts } = {}) {
       .map((p) => p.plugin),
   );
   return {
+    label: brand.label,
     marketplace: catalog.marketplace,
     repo: brand.repo,
     plugins: catalog.plugins.map((p) => {

package/src/log.js

@@ -20,9 +20,72 @@ function unicodeSupported() {
 }
 
 // Every prefix is padded to the same width so continuation lines line up.
+const INDENT = 6;
 const TICK = unicodeSupported() ? `  ${String.fromCharCode(0x2713)}   ` : '  OK  ';
 const BANG = '  !!  ';
 const CROSS = '  XX  ';
+const MARK = unicodeSupported() ? String.fromCharCode(0x2713) : '*';
+
+/**
+ * Terminal width, clamped: prose past ~78 columns is harder to read, not easier.
+ * COLUMNS is honoured so redirected output and tests can pin a width.
+ */
+function width(max = 78) {
+  const cols = process.stdout.columns || Number(process.env.COLUMNS) || 80;
+  return Math.max(40, Math.min(cols - 1, max));
+}
+
+const ASCII_MAP = {
+  '—': '-', // em dash
+  '–': '-', // en dash
+  '‘': "'",
+  '’': "'",
+  '“': '"',
+  '”': '"',
+  '…': '...',
+  '•': '*',
+  '→': '->',
+  ' ': ' ',
+};
+
+/**
+ * Marketplace descriptions are third-party text and routinely contain em dashes
+ * and smart quotes. On a console that cannot render them they arrive as
+ * mojibake, so downgrade to ASCII rather than print garbage.
+ */
+function toAscii(text) {
+  let out = String(text).replace(/[—–‘’“”…•→ ]/g, (c) => ASCII_MAP[c]);
+  out = out.normalize('NFD').replace(/[̀-ͯ]/g, ''); // strip diacritics
+  // ESC is kept: colour codes must survive, they are not text.
+  return out.replace(/[^\x1b\x20-\x7e\t\r\n]/g, '?');
+}
+
+const ascii = (text) => (unicodeSupported() ? text : toAscii(text));
+
+/** Wrap to the terminal, keeping long unbreakable tokens (paths, URLs) intact. */
+function wrap(text, indent = INDENT, max = width()) {
+  const room = Math.max(20, max - indent);
+  const lines = [];
+  let line = '';
+  for (const word of String(text).split(/\s+/).filter(Boolean)) {
+    if (!line) line = word;
+    else if (line.length + 1 + word.length <= room) line += ` ${word}`;
+    else {
+      lines.push(line);
+      line = word;
+    }
+  }
+  if (line) lines.push(line);
+  return lines.length ? lines : [''];
+}
+
+function truncate(text, max) {
+  const clean = String(text).trim();
+  if (clean.length <= max) return clean;
+  return `${clean.slice(0, Math.max(1, max - 3)).trimEnd()}...`;
+}
+
+const plural = (n, word, suffix = 's') => `${n} ${word}${n === 1 ? '' : suffix}`;
 
 function colorEnabled() {
   if (process.env.NO_COLOR !== undefined) return false;
@@ -44,33 +107,57 @@ const log = {
   get isVerbose() {
     return state.verbose;
   },
+  get isQuiet() {
+    return state.quiet;
+  },
   banner(msg) {
-    if (!state.quiet) console.log(`\n${paint('36', msg)}`);
+    if (!state.quiet) console.log(`\n${paint('36', ascii(msg))}`);
   },
   rule() {
-    if (!state.quiet) console.log(paint('90', '-'.repeat(64)));
+    if (!state.quiet) console.log(paint('90', '-'.repeat(width())));
   },
   step(msg) {
-    if (!state.quiet) console.log(`\n${paint('1', msg)}`);
+    if (!state.quiet) console.log(`\n${paint('1', ascii(msg))}`);
   },
   ok(msg) {
-    if (!state.quiet) console.log(`${paint('32', TICK)}${msg}`);
+    if (!state.quiet) console.log(`${paint('32', TICK)}${ascii(msg)}`);
   },
+  /** Wrapped and indented, so long descriptions stay readable at any width. */
   info(msg) {
-    if (!state.quiet) console.log(paint('90', `      ${msg}`));
+    if (state.quiet) return;
+    for (const line of wrap(ascii(msg))) console.log(paint('90', `      ${line}`));
   },
   warn(msg) {
-    if (!state.quiet) console.log(`${paint('33', BANG)}${msg}`);
+    if (state.quiet) return;
+    const [first, ...rest] = wrap(ascii(msg));
+    console.log(`${paint('33', BANG)}${first}`);
+    for (const line of rest) console.log(paint('33', `      ${line}`));
   },
   error(msg) {
-    console.error(`${paint('31', CROSS)}${msg}`);
+    const [first, ...rest] = wrap(ascii(msg));
+    console.error(`${paint('31', CROSS)}${first}`);
+    for (const line of rest) console.error(paint('31', `      ${line}`));
   },
   debug(msg) {
-    if (state.verbose && !state.quiet) console.log(paint('90', `  ..  ${msg}`));
+    if (state.verbose && !state.quiet) console.log(paint('90', `  ..  ${ascii(msg)}`));
   },
   plain(msg = '') {
-    if (!state.quiet) console.log(msg);
+    if (!state.quiet) console.log(ascii(msg));
+  },
+  dim(msg) {
+    return paint('90', msg);
+  },
+  bold(msg) {
+    return paint('1', msg);
   },
+  MARK,
+  width,
+  wrap,
+  truncate,
+  plural,
+  ascii,
+  toAscii,
+  unicodeSupported,
 };
 
 module.exports = log;

package/src/require-node.js

@@ -0,0 +1,23 @@
+'use strict';
+
+// Deliberately plain, old-syntax JavaScript with no imports: this has to parse
+// and run on whatever ancient Node the user happens to have.
+
+var MINIMUM = 18;
+
+module.exports = function requireNode(exit) {
+  var version = process.versions.node;
+  var major = parseInt(version.split('.')[0], 10);
+  if (major >= MINIMUM) return true;
+
+  process.stderr.write(
+    'context-plugins requires Node.js ' +
+      MINIMUM +
+      ' or newer, but this is Node.js ' +
+      version +
+      '.\n' +
+      'Install a newer Node.js from https://nodejs.org and run this again.\n',
+  );
+  (exit || process.exit)(1);
+  return false;
+};

package/src/util.js

@@ -36,7 +36,7 @@ function assertPlugin(id) {
 function assertRepo(repo) {
   if (typeof repo !== 'string' || !REPO_RE.test(repo)) {
     throw new UserError(`Invalid repo: ${JSON.stringify(repo)}`, {
-      hint: 'Expected owner/repo, e.g. context-plugins/plugin-marketplace',
+      hint: 'Expected owner/repo, e.g. acme/plugin-marketplace',
     });
   }
   return repo;
@@ -208,6 +208,63 @@ function timestamp(date = new Date()) {
 
 const stripBom = (s) => (s.charCodeAt(0) === 0xfeff ? s.slice(1) : s);
 
+/** Display form of a path: `~` beats repeating the user's home directory back at them. */
+function shortPath(target, home = require('os').homedir()) {
+  if (!target || !home) return target;
+  const normalized = String(target);
+  if (normalized.toLowerCase().startsWith(home.toLowerCase())) {
+    const rest = normalized.slice(home.length);
+    return `~${rest.startsWith(path.sep) || rest.startsWith('/') ? '' : path.sep}${rest}`;
+  }
+  return normalized;
+}
+
+/** Edit distance, capped work for the short strings we compare (plugin ids). */
+function editDistance(a, b) {
+  const rows = a.length + 1;
+  const cols = b.length + 1;
+  let prev = Array.from({ length: cols }, (_v, i) => i);
+  for (let i = 1; i < rows; i += 1) {
+    const curr = [i];
+    for (let j = 1; j < cols; j += 1) {
+      curr[j] = Math.min(
+        prev[j] + 1,
+        curr[j - 1] + 1,
+        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    prev = curr;
+  }
+  return prev[cols - 1];
+}
+
+const sharedPrefix = (a, b) => {
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i += 1;
+  return i;
+};
+
+/**
+ * Closest names to `query`. Substring hits rank first, then names sharing a
+ * substantial prefix - plugin ids in a marketplace tend to share a suffix, so
+ * plain edit distance alone rates `azure-cognitve` as too far from
+ * `azure-cognitive-sdk` to be worth offering.
+ */
+function suggest(query, candidates, limit = 3) {
+  const q = String(query).toLowerCase();
+  const threshold = Math.max(3, Math.ceil(q.length * 0.4));
+  const scored = candidates
+    .map((name) => {
+      const n = String(name).toLowerCase();
+      if (n.includes(q) || q.includes(n)) return { name, score: 0 };
+      if (sharedPrefix(q, n) >= Math.max(4, Math.ceil(q.length * 0.6))) return { name, score: 1 };
+      return { name, score: editDistance(q, n) };
+    })
+    .filter((c) => c.score <= threshold)
+    .sort((a, b) => a.score - b.score || a.name.length - b.name.length);
+  return scored.slice(0, limit).map((c) => c.name);
+}
+
 module.exports = {
   UserError,
   assertPlugin,
@@ -226,4 +283,7 @@ module.exports = {
   pool,
   timestamp,
   stripBom,
+  shortPath,
+  editDistance,
+  suggest,
 };