context-plugins 0.3.0 → 0.4.0

package/README.md

@@ -23,8 +23,39 @@ 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>` | the bundled marketplace | Install from a different marketplace |

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.3.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/catalog.js

@@ -6,6 +6,9 @@ const { UserError, assertRepo, assertRef, stripBom, suggest } = require('./util'
 // 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) {
@@ -108,6 +127,18 @@ async function resolvePlugin({ repo, ref, plugin, marketplace = null, label, dep
     });
   }
 
+  // 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

@@ -7,6 +7,7 @@ const { resolveBrand } = require('./brand');
 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']);
@@ -86,6 +87,7 @@ Usage
   ${bin} update
   ${bin} list
   ${bin} installed
+  ${bin} doctor
 
 Options
   --repo <owner/repo>   Use a different marketplace   (default: ${brand.label})
@@ -241,6 +243,37 @@ async function run(argv = process.argv.slice(2), profile = {}) {
         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) {

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/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

@@ -44,4 +44,6 @@ async function uninstall({ plugin }, opts) {
   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

@@ -56,4 +56,6 @@ async function uninstall({ plugin }, opts) {
   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');
 
@@ -94,18 +94,37 @@ async function installPlugin({
   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,
   });

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;
+};