feat(install): npm-global installer, Claude Code plugin, and dist/index.js back-compat shim#160
Merged
Merged
Conversation
…ex.js shim Three distribution/install hardening changes, all motivated by a real breakage: a hand-written MCP config pinned `node <pkg>/dist/index.js`, which the v1.0 entry-point move to `dist/surface/cli.js` silently orphaned on a routine `npm i -g` upgrade. - Back-compat entry shim: `src/index.ts` compiles to `dist/index.js` and re-runs the real CLI (surface/cli calls program.parse() on load), so any config still pinning the old path keeps working. Provably identical to the bin on the `mcp` path. - Claude Code plugin (`.claude-plugin/plugin.json`): registers the MCP server by bin name (path-drift-proof) and bundles the root SKILL.md, giving Claude Code users a one-step, config-free install. Manifest version is propagated by scripts/sync-version.ts. - Installer reform: the curl|iex one-liners now `npm i -g clawdcursor` instead of git-clone + npm install + npm run build, dropping the git/build-toolchain requirement and matching the README's advertised install. macOS still gets a built+signed native helper via the package postinstall (ad-hoc is build.sh's default). VERSION=vX.Y.Z pinning preserved as clawdcursor@X.Y.Z. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…ite) + guard plugin.json drift Addresses review of #160: - .claude-plugin/plugin.json: launch the MCP server with `npx -y clawdcursor mcp --compact` instead of the bare `clawdcursor` bin. npx resolves the package's `bin` (so it keeps the entry-path-refactor immunity the bin-name approach was chosen for) AND needs no prior `npm i -g` — it fetches on demand, or uses a global install if present. This makes the plugin genuinely one-step / config-free. Description and README plugin section updated to match (Node 20+ is the only prerequisite); dropped the now-obsolete Windows bin-shim fallback note. - tests/version-drift.test.ts: extend the inverse drift guard to .claude-plugin/plugin.json (sync-version already writes it; now a manual package.json edit that skips sync is caught, like SKILL/docs/install). Skill bundling needed no change: a root-level SKILL.md IS auto-loaded as the plugin's skill (Claude Code v2.1.142+) precisely because there is no skills/ subdir, and SKILL.md already carries a `name:` field for stable invocation. Verified: both `node dist/index.js --version` (back-compat shim) and `node dist/surface/cli.js --version` print 1.5.3. Gate: 0 lint errors, 1077 tests (version-drift now 2), build OK. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
AmrDab
added a commit
that referenced
this pull request
Jun 15, 2026
…ble uninstall Releases the #160 install work (npm-global installer, npx-launched Claude Code plugin + bundled skill, dist/index.js back-compat shim) and closes the last onboarding dead-end: - uninstall now prints the reinstall one-liner (`npm i -g clawdcursor`, plus the OS turnkey installer). It removes the global `clawdcursor` command, so `clawdcursor install` can't follow it — the old message only said how to delete more. No more "uninstalled, now what?" wall. Version bumped 1.5.3 -> 1.5.4 across every surface (package.json, package-lock, SKILL.md, server.json, .claude-plugin/plugin.json, docs/index.html [website], docs/install.{sh,ps1}) via npm version + sync-version; version-drift guard green (now also covers plugin.json). Gate: 0 lint errors, 1077 tests, build OK. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
A hand-written MCP config that pinned
node <pkg>/dist/index.jssilently broke on a routinenpm i -g clawdcursorupgrade, because the v1.0 entry-point move todist/surface/cli.jsorphaned that path. This PR fixes that class of fragility and cleans up the install/distribution story around it.What
1. Back-compat entry shim —
src/index.ts→dist/index.jsRe-runs the real CLI (
surface/clicallsprogram.parse()on load), so any host still pinning the olddist/index.jspath keeps working across the move. Verified byte-identical to the bin on themcppath.2. Claude Code plugin —
.claude-plugin/plugin.jsonRegisters the MCP server by bin name (
clawdcursor mcp --compact, so it can't be broken by an entry-path refactor) and bundles the rootSKILL.md. One-step, config-free install for Claude Code — no hand-editedmcpServersblock. Manifest version is kept in sync byscripts/sync-version.ts(new target added).3. Installer reform —
docs/install.sh+docs/install.ps1The
curl … | bash/irm … | iexone-liners nownpm install -g clawdcursorinstead of git-clone +npm install+npm run build. This drops the git + build-toolchain requirement and matches the install the README already advertises. macOS still gets a built and ad-hoc-signed native helper via the packagepostinstall(ad-hoc isbuild.sh's default, so no TCC regression).VERSION=vX.Y.Zpinning is preserved (nowclawdcursor@X.Y.Z).Net: −212 lines — most of it the removal of fragile clone/build logic from the installers.
Validation
tscbuild clean;node dist/index.js --version→1.5.3;node dist/index.js mcp --helpisdiff-identical to the bin.bash -n docs/install.shand the PowerShell parser both pass on the rewritten installers.tsx scripts/sync-version.tsmatches all targets including the new plugin manifest.Notes
#3from the planning discussion (collapsing a duplicate curl capability surface onto MCP) was investigated and found already done in 1.5.3 — MCP is the sole capability surface — so it's intentionally not part of this PR.[Unreleased].🤖 Generated with Claude Code