@viasat/beam-react-claude-plugin 2.46.0 → 2.47.1

package/.claude-plugin/hooks/check-version.mjs

@@ -0,0 +1,49 @@
+import { existsSync, writeFileSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+// Fires once per day (lock file) to avoid an npm registry call on every prompt.
+const stamp = new Date().toISOString().slice(0, 10).replace(/-/g, '');
+const cache = join(tmpdir(), `beam-version-check-${stamp}.lock`);
+if (existsSync(cache)) process.exit(0);
+
+// Write the lock before the network call so a failure still throttles to
+// once/day instead of re-hitting npm on every prompt (worst-latency case).
+writeFileSync(cache, '');
+
+const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+let installed, latest;
+try {
+  const pkgPath = join(
+    process.env.CLAUDE_PROJECT_DIR ?? process.cwd(),
+    'node_modules/@viasat/beam-react/package.json',
+  );
+  installed = JSON.parse(readFileSync(pkgPath, 'utf8')).version;
+  latest = execFileSync(
+    npm,
+    [
+      'view',
+      '@viasat/beam-react',
+      'version',
+      '--@viasat:registry=https://registry.npmjs.org',
+      '--fetch-timeout=3000',
+      '--fetch-retries=0',
+    ],
+    { encoding: 'utf8' },
+  ).trim();
+} catch {
+  process.exit(0);
+}
+
+if (installed !== latest) {
+  process.stdout.write(
+    JSON.stringify({
+      systemMessage: `⚠️  beam-react ${installed} installed, ${latest} available. Run /beam-update to upgrade.`,
+      hookSpecificOutput: {
+        hookEventName: 'UserPromptSubmit',
+        additionalContext: `@viasat/beam-react is out of date (${installed} installed, ${latest} latest). Tell the user once, at the start of your very next response, that they should run /beam-update to upgrade. This is a one-time notice: if you have already mentioned it earlier in this conversation, do not bring it up again.`,
+      },
+    }) + '\n',
+  );
+}

package/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "beam-react-claude-plugin",
   "displayName": "Beam React Claude Plugin",
   "description": "Equips AI tools with Beam Design System context for building, auditing, and answering implementation questions across tokens, components and data sources in React.",
-  "version": "2.46.0",
+  "version": "2.47.1",
   "author": {
     "name": "Viasat",
     "url": "https://git.viasat.com/vega/beam"
@@ -15,8 +15,20 @@
       "command": "npx",
       "args": [
         "-y",
-        "@viasat/beam-react-mcp@2.46.0"
+        "@viasat/beam-react-mcp@2.47.1"
       ]
     }
+  },
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/.claude-plugin/hooks/check-version.mjs\""
+          }
+        ]
+      }
+    ]
   }
 }

package/README.md

@@ -8,9 +8,10 @@ sources.
 
 Inside any project that depends on `@viasat/beam-react`, the plugin adds:
 
-| Skill     | Type         | Purpose                                                                                                              |
-| --------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
-| `beam-ui` | Auto-invoked | Build, modify, refactor, or debug UI using Beam components — and answer questions or give recommendations about Beam |
+| Skill       | Type         | Purpose                                                                                                              |
+| ----------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `beam-ui`   | Auto-invoked | Build, modify, refactor, or debug UI using Beam components, and answer questions or give recommendations about Beam |
+| `/beam-update` | User-invoked | Detect version drift, surface the changelog, and update beam-react + the plugin in one step                       |
 
 Each skill carries a short critical-rules block (the source-of-truth hierarchy,
 token rules, and composition rules) and defers to
@@ -22,59 +23,54 @@ props, stories, and concept docs.
 
 > **Note:** `/plugin` commands are Claude Code slash commands. Run them inside the Claude Code CLI, not in a raw terminal, the desktop app, or the VS Code Claude extension.
 
-### 🏢 Via Beam internal Claude plugin marketplace
+Before installing, make sure `@viasat/beam-react` is in your project and updated to the latest version. The plugin ships pinned to the same version as `@viasat/beam-react`, so installing it against an outdated `@viasat/beam-react` gives you an outdated plugin and MCP.
 
-On VPN, add the Beam repo as a marketplace:
-
-```
-/plugin marketplace add git@git.viasat.com:vega/beam.git
-/plugin install beam-react-claude-plugin
-```
-
-### 📦 Via npm
-
-Off VPN, install the npm package in your terminal first:
-
-```bash
-npm install --save-dev @viasat/beam-react-claude-plugin
-```
-
-Then run these commands inside the Claude Code CLI:
+The plugin ships as a declared dependency of `@viasat/beam-react`, so no separate `npm install` is needed. Once `@viasat/beam-react` is in your project, run these two commands inside the Claude Code CLI:
 
 ```
 /plugin marketplace add ./node_modules/@viasat/beam-react-claude-plugin
 /plugin install beam-react-claude-plugin@beam
 ```
 
-## 🔄 Updating
-
-### 🏢 Via Beam internal Claude plugin marketplace
+Then run `/reload-plugins`.
 
-To update on VPN use:
+> **Migrating from the git marketplace path?** If you previously used
+> `/plugin marketplace add git@git.viasat.com:vega/beam.git`, remove that
+> marketplace entry and follow the steps above. The npm path is now the only
+> supported path.
 
-```
-/plugin update beam-react-claude-plugin
-```
+## 🔄 Updating
 
-Then run `/reload-plugins` in the Claude Code CLI.
+Run `/beam-update` inside the Claude Code CLI. Claude detects whether an update is
+available, surfaces what changed, and handles the npm + plugin cache update. The
+only step you take is `/reload-plugins` at the end to pick up the new version.
 
-### 📦 Via npm
+When the update crosses a version with a migration guide, Claude also surfaces the
+relevant guides, scans your code for anything the migration affects, and offers to
+apply the necessary changes for you before you reload, so you're not left to work
+out the impact on your own.
 
-Off VPN, update the npm package and then the marketplace:
+To update manually without the skill:
 
 ```bash
-npm i @viasat/beam-react-claude-plugin@latest
-```
-
-```
-/plugin marketplace update beam
+npm update @viasat/beam-react          # updates beam-react + plugin as its dep
+claude plugin marketplace update beam  # refreshes marketplace cache
+claude plugin update beam-react-claude-plugin@beam  # updates plugin cache
 ```
 
 Then run `/reload-plugins` in the Claude Code CLI.
 
+### Automatic drift detection
+
+Once per day, the plugin quietly checks the npm registry for a newer
+`@viasat/beam-react`. If one is available, it surfaces a short notice at the top of
+Claude's next response suggesting you run `/beam-update`. No prompt data leaves your
+machine; the only outbound call is a version lookup to the public npm registry, and
+the check is throttled to once per day even when it can't reach the network.
+
 ## 🖥️ Non Claude Code users
 
-On a different editor? The MCP runs on its own, no plugin required — see
+On a different editor? The MCP runs on its own, no plugin required. See
 [`@viasat/beam-react-mcp`](https://www.npmjs.com/package/@viasat/beam-react-mcp).
 
 ## ✅ Requirements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viasat/beam-react-claude-plugin",
-  "version": "2.46.0",
+  "version": "2.47.1",
   "description": "Claude Code plugin that reduces AI hallucinations on Beam usage. Ships skills, reference docs, and a user-invocable token audit command.",
   "license": "MIT",
   "author": "Viasat",

package/skills/beam-update/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: beam-update
+description: Use when the user invokes /beam-update or asks to update beam-react, the Beam plugin, or the Beam MCP. Detects version drift, surfaces the changelog, and automates the npm + plugin cache update. The only manual step left for the user is /reload-plugins.
+---
+
+# beam-update
+
+> **Network access:** this skill fetches migration guides from `https://react.beam.viasat.com` via `curl`. This is the one authorized outbound request the skill makes.
+
+Step 7 may involve editing Beam component usage to apply migration steps. When it does, follow the canonical rules in `references/rules-preamble.md` (token rule, composition rule, honesty rule).
+
+## Activation gate
+
+Read `package.json`. If `@viasat/beam-react` is not in `dependencies` or `devDependencies`, tell the user this skill requires a project that depends on `@viasat/beam-react` and stop.
+
+## Checklist
+
+1. **Check versions.** Run both commands via Bash:
+
+   ```bash
+   node -p "require('./node_modules/@viasat/beam-react/package.json').version"
+   npm view @viasat/beam-react version --@viasat:registry=https://registry.npmjs.org
+   ```
+
+   If installed matches latest, tell the user they're already up to date and stop.
+
+2. **Surface the changelog.** The changelog is bundled at the root of the installed package. Read exactly `./node_modules/@viasat/beam-react/CHANGELOG.md` via Bash (do not look elsewhere or fetch it remotely). Extract the entries for versions between installed (exclusive) and latest (inclusive). Present them in a brief summary, breaking changes first, then notable additions.
+
+   If the file is absent (installed versions predating changelog bundling won't ship it), note that the changelog couldn't be found locally and continue. Do not block the update on this.
+
+3. **Check migration guides.** The running MCP is pinned to the *installed* version and cannot see guides published in the target version, so fetch from the public prod site with `curl` (not WebFetch):
+
+   ```bash
+   curl -s https://react.beam.viasat.com/llms.txt
+   ```
+
+   Extract the `## Migrations` section. Each entry looks like `- [<title>](llms/<slug>.txt): <description>` (e.g. `[v2.35.0 to v2.36.0](llms/migrations-v2-35-0-to-v2-36-0.txt)`). Titles use inconsistent granularity (point-release vs major-span), so judge which entries' version span intersects installed (exclusive) → target (inclusive). For each applicable guide, fetch the full body:
+
+   ```bash
+   curl -s https://react.beam.viasat.com/llms/<slug>.txt
+   ```
+
+   Summarize the required migration steps, breaking/manual changes (renamed tokens, API changes) first. If no guide applies, say so and continue. If either `curl` fails (offline / VPN), note that migration guides could not be fetched and continue. Never block the update on this.
+
+4. **Assess real impact on this codebase.** Do not tell the user to grep for themselves. You do the read-only scan and report exactly what applies to them. For each applicable guide, translate its concrete changes into searchable signals.
+
+   Search the user's source with Grep/Glob (exclude `node_modules`, `dist`, and build output). Report actual exposure grouped by change: the impacted files with `file:line` references, or, if nothing matches, state plainly that this migration does not affect their code. This scan is read-only and runs **before** the update so it can inform the decision.
+
+5. **Confirm with the user.** Present the installed → latest delta, the migration summary from step 3, and the concrete impact from step 4 (which files change, or "no impact found"), then ask: "Update from X to Y? (yes / no)"
+
+   Make clear that confirming commits them to applying the migration steps (with your help, or manually). The update creates a window where their code and the installed package disagree until the migration is done. If step 4 found no impact, note that the update is expected to be a clean bump. Do not proceed until the user explicitly confirms.
+
+6. **Update, then verify the bump.** Run via Bash and report each command's output. If a command fails, stop, show the error, and do not continue.
+
+   ```bash
+   npm update @viasat/beam-react
+   ```
+
+   Re-read the installed version and confirm it actually reached the target latest from step 1:
+
+   ```bash
+   node -p "require('./node_modules/@viasat/beam-react/package.json').version"
+   ```
+
+   `npm update` respects the semver range in `package.json`, so if the range is too narrow it is a silent no-op and the version stays put. If the installed version is still not the target, fall back to an explicit install (this also rewrites the `@viasat/beam-react` range in `package.json`):
+
+   ```bash
+   npm install @viasat/beam-react@<latest>
+   ```
+
+   Re-read the version once more. If it still has not reached the target, stop and report the mismatch instead of proceeding; something is wrong (lockfile, workspace constraint, or registry) and the plugin cache must not be refreshed against a stale install. Only once the install is confirmed at the target version, refresh the plugin cache:
+
+   ```bash
+   claude plugin marketplace update beam
+   claude plugin update beam-react-claude-plugin@beam
+   ```
+
+7. **Apply migration steps (interactive).** If step 4 found impacted sites, offer to apply the changes to exactly those sites now, *after* the update, so edits are made against the newly installed version and can be verified. Walk each change (renamed tokens, API updates) with per-change approval, and verify as you go (typecheck / lint) where practical. If step 4 found no impact, there is nothing to apply, so skip. Skip too if the user declines. This must happen **before** the reload, since `/reload-plugins` restarts the session.
+
+8. **Tell the user to reload.** Respond with:
+
+   > Update complete. Run `/reload-plugins` to pick up the new version in this session.
+
+   Explain that `/reload-plugins` is required because Claude loads plugins into memory at session start; the update takes effect only after reload.
+
+## Red flags, STOP and re-check
+
+| Rationalization | Reality |
+|---|---|
+| "npm update might break other deps, skip it" | `npm update @viasat/beam-react` respects semver ranges in `package.json`; it won't arbitrarily upgrade unrelated packages. |
+| "Just update the plugin cache, skip npm" | The plugin's assets (skills, references) live in the npm package. Without the npm update the cache still holds the old content. |
+| "Skip `claude plugin update`, marketplace update is enough" | The marketplace update refreshes the index; `claude plugin update` applies the new version to Claude's plugin cache. Both steps are required. |
+| "Skip the migration check, the changelog covers it" | The changelog lists *what* changed; the migration guide lists *what the user must do* (renamed tokens, API changes). They are not interchangeable. |
+| "Apply migration edits before running the update" | Migration guides target the new version's API. Editing before the update writes to code that isn't installed yet and can't be verified. Update first, then migrate. |
+| "Use the MCP `getConcept` for migration guides" | The running MCP is pinned to the *installed* version and won't have guides published in the target version. Fetch from `react.beam.viasat.com` via `curl`. |
+| "Tell the user to grep for impacted usages themselves" | You have read access to their source, so scan it and report the exact `file:line` sites. Handing the user a command to run is the UX this skill exists to remove. |
+| "The guide lists changes, so it must affect them" | A guide is generic; the user may use none of the changed tokens/APIs. Scan first: a migration with zero matches is a clean bump, and saying so is valuable. |
+| "`npm update` exited cleanly, so it upgraded" | `npm update` is a silent no-op when the range in `package.json` does not allow the new version. Always re-read the installed version after; if it did not move, run `npm install @viasat/beam-react@<latest>` and verify again before touching the plugin cache. |
+
+## Not in scope
+
+Upgrading unrelated dependencies, modifying `package.json` version ranges for anything other than `@viasat/beam-react`, resolving peer dependency conflicts, or updating other `@viasat/*` packages independently.