proscenium 0.25.3 → 0.26.1

data/lib/proscenium/cli/collisions.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+require_relative 'registration'
+
+module Proscenium
+  module CLI
+    # The app's own packages that already take a gem context's name, `@rubygems/<gem>` (#154,
+    # C05): a dependency on it that is not the context, such as the GitHub pin an app used before
+    # adopting, and a workspace package so named. Install reads them before it writes anything.
+    module Collisions
+      module_function
+
+      DEPENDENCY_FIELDS = %w[dependencies devDependencies optionalDependencies
+                             peerDependencies].freeze
+
+      # One line for each package of the app's own taking a context's name.
+      def find(root, manager, gems)
+        names = gems.to_h { ["@rubygems/#{it}", it] }
+        app = read_json(File.join(root, 'package.json')) || {}
+        pinned = DEPENDENCY_FIELDS.flat_map do |field|
+          (app[field] || {}).filter_map do |name, spec|
+            next if !names.key?(name) || context_workspace?(spec, name) ||
+                    context_link?(root, spec, names[name])
+
+            "package.json #{field} has #{name} as \"#{spec}\""
+          end
+        end
+        pinned + workspace_packages(root, manager, app).filter_map do |file, name|
+          "#{file} is named #{name}" if names.key?(name)
+        end
+      end
+
+      # Whether `spec` is the workspace package `name`, the context: `workspace:<range>`, not an
+      # alias to another package, `workspace:<other>@<range>`.
+      def context_workspace?(spec, name)
+        range = spec.to_s.delete_prefix('workspace:')
+        return false if range == spec.to_s
+
+        aliased = range[/\A(@?[^@]+)@/, 1]
+        aliased.nil? || aliased == name
+      end
+
+      # Whether `spec` links to the gem's own context, however the path is spelled.
+      def context_link?(root, spec, gem)
+        return false unless spec.to_s.start_with?('link:')
+
+        context = File.join(File.expand_path(root), ContextMap::CONTEXTS, gem)
+        File.expand_path(spec.to_s.delete_prefix('link:'), root) == context
+      end
+
+      # [package.json path, package name] for each workspace package the app declares, other than
+      # the contexts. A pattern starting with `!` excludes. `./` is dropped from each, as pnpm and
+      # Bun read `./packages/*` and `packages/*` alike.
+      def workspace_packages(root, manager, app)
+        excluded, included = workspace_patterns(root, manager, app)
+                             .grep(String).reject { ContextMap.registration?(it) }
+                             .map { it.sub(%r{\A(!?)\./}, '\\1') }
+                             .partition { it.start_with?('!') }
+        files = included.flat_map { Dir.glob(File.join(it, 'package.json'), base: root) }.uniq
+        files.filter_map do |file|
+          dir = File.dirname(file)
+          next if dir.split('/').include?('node_modules')
+
+          # FNM_EXTGLOB for braces, which pnpm and Bun expand, as Dir.glob does for the inclusions.
+          flags = File::FNM_PATHNAME | File::FNM_EXTGLOB
+          next if excluded.any? { File.fnmatch?(it[1..], dir, flags) }
+
+          [file, read_json(File.join(root, file))&.dig('name')]
+        end
+      end
+
+      def workspace_patterns(root, manager, app)
+        if manager == 'bun'
+          workspaces = app['workspaces']
+          Array(workspaces.is_a?(Hash) ? workspaces['packages'] : workspaces)
+        else
+          path = File.join(root, 'pnpm-workspace.yaml')
+          File.exist?(path) ? Array(ContextMap.yaml_packages(File.read(path))) : []
+        end
+      rescue Psych::SyntaxError
+        [] # the manager reports it
+      end
+
+      def read_json(path)
+        json = File.exist?(path) && ContextMap.read_json(path)
+        json.is_a?(Hash) ? json : nil
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/proscenium/cli/contexts.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../context_map'
+require_relative '../bundled_gems'
+require_relative '../dependency_context'
+require_relative 'rules'
+
+module Proscenium
+  module CLI
+    # The contexts the bundle calls for (#154): one per participating, installed gem, projected
+    # from its package.json after the author contract and the gem-to-gem rules. Computes; never
+    # writes.
+    class Contexts
+      DIR = File.join('.proscenium', 'packages')
+      ESCAPE = "Or, to install %<gem>s's NPM dependencies yourself, opt it out with " \
+               '`"proscenium": {"gemOverrides": {"%<gem>s": {"participate": false}}}` in ' \
+               "package.json, then add the packages it needs to your app's own dependencies."
+
+      # A gem's context: its JSON text, and the Git and URL dependencies it introduces.
+      Context = Struct.new(:gem, :json, :git_and_url, keyword_init: true)
+
+      attr_reader :contexts, :problems, :warnings
+
+      # `specs` are the participating installed specs by name; `root` is the app.
+      def initialize(root, specs)
+        @root = root
+        @specs = specs
+        @contexts = {}
+        @problems = []
+        @warnings = []
+        specs.each_value { add(it) }
+      end
+
+      def ok? = @problems.empty?
+
+      # The committed context directories under the app, by gem name.
+      def self.committed(root)
+        dir = File.join(root, DIR)
+        return {} unless Dir.exist?(dir)
+
+        Dir.children(dir).select { File.directory?(File.join(dir, it)) }.sort
+           .to_h { [it, File.join(dir, it, 'package.json')] }
+      end
+
+      private
+
+      def add(spec)
+        gem = spec.name
+        manifest_root = BundledGems.manifest_root(spec)
+        unless manifest_root
+          return problem('PSM-E-FRONTEND-ROOT', gem:,
+                                                root: spec.metadata['proscenium.frontend_root'])
+        end
+
+        manifest = read_manifest(gem, manifest_root, spec.full_gem_path) or return
+        fatal = Rules.check(gem, manifest, root: manifest_root)
+        warnings, fatal = fatal.partition { Rules::WARNINGS.include?(it.first) }
+        @warnings.concat(warnings)
+        fatal.each { |code, args| problem(code, **args) }
+        return unless fatal.empty?
+
+        manifest = link_gems(gem, spec, manifest) or return
+        context = DependencyContext.project(gem, manifest)
+        @contexts[gem] = Context.new(gem:, json: DependencyContext.to_json(context),
+                                     git_and_url: git_and_url(context))
+      end
+
+      def read_manifest(gem, manifest_root, gem_root)
+        path = File.join(manifest_root, 'package.json')
+        unless File.exist?(path)
+          return problem('PSM-E-MANIFEST', gem:, path: 'package.json', cause: 'it is missing')
+        end
+        if (cause = Rules.manifest_file_problem(path, gem_root))
+          return problem('PSM-E-MANIFEST', gem:, path: 'package.json', cause:)
+        end
+
+        manifest = ContextMap.read_json(path)
+        return manifest if manifest.is_a?(Hash)
+
+        problem('PSM-E-MANIFEST', gem:, path: 'package.json', cause: 'it is not a JSON object')
+      rescue JSON::ParserError
+        problem('PSM-E-MANIFEST', gem:, path: 'package.json', cause: 'it is not valid JSON')
+      end
+
+      # Rewrites references to other gems' contexts to `workspace:*`. A reference is kept only if
+      # the gemspec depends on the other gem and that gem participates: Bundler then guarantees it
+      # is locked at a compatible version. An optional peer whose gem does not participate is left
+      # out, as an absent optional peer would be.
+      def link_gems(gem, spec, manifest)
+        runtime = spec.runtime_dependencies.map(&:name)
+        optional = (manifest['peerDependenciesMeta'] || {}).select do |_, meta|
+          meta.is_a?(Hash) && meta['optional']
+        end.keys
+        ok = true
+        linked = Rules::DEPENDENCY_FIELDS.to_h do |field|
+          deps = (manifest[field] || {}).filter_map do |name, version|
+            next [name, version] unless name.start_with?('@rubygems/')
+
+            other = name.delete_prefix('@rubygems/')
+            participates = @specs.key?(other)
+            if field == 'peerDependencies' && optional.include?(name) && !participates
+              nil
+            elsif !runtime.include?(other)
+              ok = false
+              problem('PSM-E-CROSS-GEM', gem:, other:)
+            elsif !participates
+              ok = false
+              problem('PSM-E-CROSS-GEM-TARGET', gem:, other:)
+            else
+              [name, 'workspace:*']
+            end
+          end
+          [field, deps.to_h]
+        end
+        ok ? manifest.merge(linked) : nil
+      end
+
+      def git_and_url(context)
+        Rules::DEPENDENCY_FIELDS.flat_map { (context[it] || {}).to_a }
+                                .select { |_, spec| spec.to_s.match?(%r{\A(?:github:|git\+|https://)}) }
+                                .map { |name, spec| "#{name}@#{spec}" }
+      end
+
+      # Records a problem with the gem's own manifest, with the consumer's way out. Returns nil,
+      # so a caller can `return problem(...)` to stop.
+      def problem(code, **args)
+        @problems << [code, args.merge(escape: format(ESCAPE, gem: args.fetch(:gem)))]
+        nil
+      end
+    end
+  end
+end

data/lib/proscenium/cli/diff.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Proscenium
+  module CLI
+    # A unified diff of a small text file's edit, which `install` prints before it writes one of
+    # the app's files. Line-based, over a longest common subsequence: fine for the files it is
+    # used on, which are a few dozen lines.
+    module Diff
+      MARKS = { same: ' ', del: '-', add: '+' }.freeze
+
+      module_function
+
+      # The diff of `before` to `after`, headed with `path`; empty when they are the same.
+      def unified(path, before, after, context: 3)
+        ops = lcs_ops(before.lines(chomp: true), after.lines(chomp: true))
+        hunks = hunks(ops, context)
+        return '' if hunks.empty?
+
+        header = "--- #{path}\n+++ #{path}\n"
+        header + hunks.map { |hunk| format_hunk(hunk) }.join
+      end
+
+      # Each line as [:same | :del | :add, text, line in old, line in new].
+      def lcs_ops(old, new)
+        table = lcs_table(old, new)
+        ops = []
+        i = j = 0
+        while i < old.size || j < new.size
+          if i < old.size && j < new.size && old[i] == new[j]
+            ops << [:same, old[i], i, j]
+            i += 1
+            j += 1
+          elsif j < new.size && (i == old.size || table[i][j + 1] >= table[i + 1][j])
+            ops << [:add, new[j], i, j]
+            j += 1
+          else
+            ops << [:del, old[i], i, j]
+            i += 1
+          end
+        end
+        ops
+      end
+
+      # The longest common subsequence lengths of every pair of suffixes.
+      def lcs_table(old, new)
+        table = Array.new(old.size + 1) { Array.new(new.size + 1, 0) }
+        (old.size - 1).downto(0) do |i|
+          (new.size - 1).downto(0) do |j|
+            table[i][j] = if old[i] == new[j]
+                            table[i + 1][j + 1] + 1
+                          else
+                            [table[i + 1][j], table[i][j + 1]].max
+                          end
+          end
+        end
+        table
+      end
+
+      def hunks(ops, context)
+        changed = ops.each_index.reject { ops[it][0] == :same }
+        return [] if changed.empty?
+
+        groups = changed.slice_when { |x, y| y - x > context * 2 }
+        groups.map do |group|
+          ops[[group.first - context, 0].max..[group.last + context, ops.size - 1].min]
+        end
+      end
+
+      def format_hunk(ops)
+        a_start = ops.first[2] + 1
+        b_start = ops.first[3] + 1
+        a_count = ops.count { it[0] != :add }
+        b_count = ops.count { it[0] != :del }
+        lines = ops.map { |op, text| "#{MARKS.fetch(op)}#{text}\n" }
+        "@@ -#{a_count.zero? ? a_start - 1 : a_start},#{a_count} " \
+          "+#{b_count.zero? ? b_start - 1 : b_start},#{b_count} @@\n#{lines.join}"
+      end
+    end
+  end
+end

data/lib/proscenium/cli/error.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module Proscenium
+  module CLI
+    # Every failure the CLI reports: a stable code, the exit status it maps to, and text that states
+    # the problem, its cause and the fix. The catalog is the single source; golden-output tests pin
+    # the human text and the JSON event for each entry (test/cli/golden/).
+    class Error < StandardError
+      EXIT = { success: 0, internal: 1, input: 2, unsupported: 3, drift: 4, integrity: 5,
+               native: 6, busy: 7, interrupted: 8 }.freeze
+
+      # code => [exit, message template, fix template]. Templates take keyword arguments.
+      CATALOG = {
+        'PSM-E-USAGE' => [
+          :input, '%<detail>s',
+          'Run `bundle exec proscenium --help` to see the commands and their options.'
+        ],
+        'PSM-E-GEMSPEC' => [
+          :input, 'Expected one gemspec in %<path>s, but found %<found>s.',
+          "Run `proscenium gem check` from the gem's own directory, or pass it that directory " \
+          'or a built .gem file.'
+        ],
+        'PSM-E-NOT-OPTED-IN' => [
+          :input, '%<gem>s has not opted in to having Proscenium install its NPM ' \
+                  'dependencies.',
+          "Add `spec.metadata['proscenium.dependencies'] = 'true'` to its gemspec."
+        ],
+        'PSM-E-FRONTEND-ROOT' => [
+          :input, "%<gem>s's proscenium.frontend_root (%<root>s) points outside the gem.",
+          "Set proscenium.frontend_root to a directory inside the gem, relative to the gem's root."
+        ],
+        'PSM-E-MANIFEST' => [
+          :input, "%<gem>s's %<path>s can't be used, because %<cause>s.",
+          'Ship a valid package.json there: a JSON object whose dependency fields map package ' \
+          'names to version strings.'
+        ],
+        'PSM-E-GEM-FILES' => [
+          :input, "%<gem>s's gemspec doesn't list %<files>s in spec.files, so the built gem " \
+                  "won't include it.",
+          'Add package.json, and every frontend file the gem serves, to spec.files.'
+        ],
+        'PSM-E-NAME' => [
+          :input, "The gem name %<gem>s can't be used as a JavaScript package name " \
+                  '(@rubygems/%<gem>s).',
+          'JavaScript package names use only lowercase letters, digits and - . _ ~, are at most ' \
+          "214 characters long, and can't end in a dot or be a Windows device name such as con " \
+          'or nul. The gem needs a valid name before Proscenium can install its dependencies.'
+        ],
+        'PSM-E-WORKSPACES' => [
+          :input, "%<gem>s's package.json declares workspaces, which a gem's package.json " \
+                  "can't do.",
+          "Remove \"workspaces\" from the gem's package.json."
+        ],
+        'PSM-E-HOOK' => [
+          :input, '%<gem>s needs build steps at install time (%<hooks>s), and Proscenium never ' \
+                  'runs them.',
+          "Ship the gem's assets already built, and remove those install-time hooks."
+        ],
+        'PSM-E-SPEC' => [
+          :input, "%<gem>s depends on %<name>s as \"%<spec>s\", which Proscenium doesn't allow.",
+          'Use a version range or tag, an npm:<package> alias, a github:, git+https: or git+ssh: ' \
+          'URL, or an https: tarball URL.'
+        ],
+        'PSM-E-CREDENTIAL' => [
+          :input, "%<gem>s's dependency %<name>s has a password or token in its URL, which " \
+                  'would be committed to your repository.',
+          'Remove it from the URL. Apps log in to private registries in their own .npmrc.'
+        ],
+        'PSM-E-ALIAS' => [
+          :input, "%<gem>s aliases %<name>s to \"%<spec>s\", which is another gem's " \
+                  'dependency context.',
+          "Add the other gem to the gemspec's dependencies, and use @rubygems/<gem> directly."
+        ],
+        'PSM-E-REACT' => [
+          :input, '%<gem>s lists %<packages>s as dependencies, so it would get its own copy and ' \
+                  'the page would load two.',
+          "List %<packages>s under peerDependencies instead, so the gem uses the app's copy."
+        ],
+        'PSM-E-CROSS-GEM' => [
+          :input, "%<gem>s's package.json uses @rubygems/%<other>s, but its gemspec doesn't " \
+                  'depend on the %<other>s gem.',
+          "Add `spec.add_dependency '%<other>s'` to the gemspec, or stop using " \
+          '@rubygems/%<other>s.'
+        ],
+        'PSM-E-NO-MANAGER' => [
+          :input, "Proscenium can't tell which package manager this app uses: there is no " \
+                  'packageManager field in package.json, and no pnpm-lock.yaml or bun.lock.',
+          'Run again with --manager pnpm or --manager bun, or add a packageManager field to ' \
+          'package.json.'
+        ],
+        'PSM-E-MANAGER-CONFLICT' => [
+          :input, 'This app points to more than one package manager: %<signals>s.',
+          'Keep just one: delete the other lockfile, or make packageManager in package.json ' \
+          'match the lockfile. (--manager only decides when nothing else does.)'
+        ],
+        'PSM-E-UNSUPPORTED-MANAGER' => [
+          :unsupported, 'This app uses %<manager>s, but Proscenium can only install ' \
+                        "gems' NPM dependencies with pnpm or Bun.",
+          "Switch the app to pnpm or Bun, or keep adding gems' NPM dependencies to " \
+          'package.json yourself.'
+        ],
+        'PSM-E-BUN-LOCKB' => [
+          :unsupported, "This app only has bun.lockb, Bun's older binary lockfile, which " \
+                        "Proscenium can't read.",
+          'Run `bun install --save-text-lockfile` to write bun.lock, then commit it.'
+        ],
+        'PSM-E-MANAGER-MISSING' => [
+          :unsupported, "%<manager>s isn't installed, or isn't on your PATH.",
+          'Install %<manager>s the way this project normally does (Corepack, mise, Volta or its ' \
+          'own installer), then try again.'
+        ],
+        'PSM-E-MANAGER-VERSION' => [
+          :unsupported, "Proscenium doesn't support %<manager>s %<version>s.",
+          'Use a supported version of %<manager>s (%<supported>s). To experiment locally with ' \
+          'another, add --experimental-manager-version.'
+        ],
+        'PSM-E-EXPERIMENTAL-FROZEN' => [
+          :unsupported, "--experimental-manager-version can't be combined with --frozen.",
+          'Use a supported package manager version wherever --frozen runs, such as CI.'
+        ],
+        'PSM-E-BUN-LINKER' => [
+          :unsupported, "bunfig.toml doesn't say which linker Bun uses (hoisted or isolated), " \
+                        'and adding gem dependency contexts could make Bun switch linkers.',
+          'Add `linker = "hoisted"` (or "isolated", whichever your app uses today) to the ' \
+          '`[install]` table in bunfig.toml, creating the table if there is none.'
+        ],
+        'PSM-E-NESTED-WORKSPACE' => [
+          :unsupported, 'This app is inside the JavaScript workspace at %<enclosing>s, and ' \
+                        "Proscenium doesn't support that yet.",
+          "Keep adding gems' NPM dependencies to that workspace yourself, as you do today."
+        ],
+        'PSM-E-REGISTRATION' => [
+          :input, "Proscenium couldn't add the gem dependency contexts to %<file>s without " \
+                  'rewriting the file.',
+          'Check that %<file>s is valid (package.json must be strict JSON, with no comments or ' \
+          'trailing commas). Then add ".proscenium/packages/*" yourself, to `packages` in ' \
+          'pnpm-workspace.yaml or `workspaces` in package.json, and run ' \
+          '`bundle exec proscenium install` again.'
+        ],
+        'PSM-E-REGISTRATION-EXCLUDED' => [
+          :input, '%<file>s excludes .proscenium/packages/ with a "!" pattern, so your package ' \
+                  'manager would never install the gem dependency contexts.',
+          'Remove that pattern from %<file>s, then run `bundle exec proscenium install` again.'
+        ],
+        'PSM-E-BUSY' => [
+          :busy, '%<holder>s is already running in this project.',
+          'Wait for it to finish, then run your command again. If nothing is actually ' \
+          'installing, delete .proscenium/manager, which an earlier run left behind.'
+        ],
+        'PSM-E-NATIVE' => [
+          :native, '`%<command>s` failed (exit status %<status>s).',
+          'Its output is above. Fix what it reports, then run `bundle exec proscenium install` ' \
+          "again. Proscenium hasn't changed your package manager or regenerated your lockfile."
+        ],
+        'PSM-E-INTERRUPTED' => [
+          :interrupted, '`%<command>s` was stopped before it finished.',
+          'Run `bundle exec proscenium install` again to finish.'
+        ],
+        'PSM-E-CROSS-GEM-TARGET' => [
+          :input, "%<gem>s's package.json uses @rubygems/%<other>s, but %<other>s hasn't " \
+                  'opted in to having Proscenium install its NPM dependencies.',
+          'Opt %<other>s in: its author adds proscenium.dependencies to its gemspec, or you add ' \
+          '`"proscenium": {"gemOverrides": {"%<other>s": {"participate": true}}}` to your ' \
+          'package.json.'
+        ],
+        'PSM-E-CONFIG' => [
+          :input, "Proscenium can't read its settings: %<detail>s.",
+          'Fix package.json. Proscenium reads one setting from it: ' \
+          '`"proscenium": {"gemOverrides": {"<gem>": {"participate": true}}}`, with true or ' \
+          'false for each gem.'
+        ],
+        'PSM-E-PROBLEMS' => [
+          :input, 'The install stopped because of the problems above. Nothing was changed.',
+          'Fix each one as it says, then run `bundle exec proscenium install` again.'
+        ],
+        'PSM-E-DRIFT' => [
+          :drift, "Some files are out of date with your bundle:\n%<list>s",
+          'Run `bundle exec proscenium install`, then commit the files it lists.'
+        ],
+        'PSM-E-NOT-REGISTERED' => [
+          :drift, "%<file>s doesn't list .proscenium/packages/*, so %<manager>s won't install " \
+                  "your gems' NPM dependencies.",
+          'Run `bundle exec proscenium install`, then commit %<file>s.'
+        ],
+        'PSM-E-GITIGNORE' => [
+          :drift, ".gitignore is missing some of Proscenium's lines, or a later rule hides the " \
+                  'dependency contexts you need to commit.',
+          'Run `bundle exec proscenium install` to add them, then commit .gitignore.'
+        ],
+        'PSM-E-LOCKFILE-MISSING' => [
+          :drift, '%<lockfile>s is missing.',
+          'Run `bundle exec proscenium install`, then commit %<lockfile>s.'
+        ],
+        'PSM-E-NOT-INSTALLED' => [
+          :drift, "Your NPM dependencies aren't installed: there is no node_modules " \
+                  'directory.',
+          'Run `bundle exec proscenium install`, or `bundle exec proscenium install --frozen` on ' \
+          'a fresh checkout or in CI.'
+        ],
+        'PSM-E-REGISTRY-TARBALL' => [
+          :integrity, 'The lockfile installs %<packages>s from a registry or Git, instead of ' \
+                      'from the gem itself.',
+          'Remove the registry or GitHub dependency on it from your package.json, since ' \
+          'Gemfile.lock provides the gem now, then run `bundle exec proscenium install`.'
+        ],
+        'PSM-E-WORKSPACE-MISSING' => [
+          :integrity, "%<manager>s didn't install the dependency contexts for %<gems>s.",
+          'Check that `packages` in pnpm-workspace.yaml, or `workspaces` in package.json, ' \
+          'lists ".proscenium/packages/*", then run `bundle exec proscenium install` again.'
+        ],
+        'PSM-E-PEER-SPLIT' => [
+          :integrity, '%<gem>s and your app use different copies of %<package>s, so the page ' \
+                      'would load it twice.',
+          "Change your app's %<package>s to a version within %<gem>s's peer range, then run " \
+          '`bundle exec proscenium install` again.'
+        ],
+        'PSM-E-COLLISION' => [
+          :input, "Some of your app's dependencies use a name a gem's dependency context " \
+                  "needs:\n%<list>s",
+          'Remove each one, since Gemfile.lock provides the gem now, or rename the package.'
+        ],
+        'PSM-E-BUN-DEFAULT-TRUSTED' => [
+          :unsupported, "`bun pm default-trusted` didn't print Bun's default list of trusted " \
+                        "packages, so Proscenium can't check whose install scripts Bun would run.",
+          'Add `"trustedDependencies": []` to package.json, listing any packages whose install ' \
+          'scripts your app needs, so Bun uses that list instead of its default.'
+        ],
+        'PSM-E-TRUSTED-SOURCE' => [
+          :input, 'Some gems install a package from Git, a URL or an alias to another package, ' \
+                  'under a name your package manager trusts to run install scripts, so that ' \
+                  "code's install script would run:\n%<list>s",
+          "Ask the gem's author to depend on the registry package instead, or opt the gem out " \
+          'with `"proscenium": {"gemOverrides": {"<gem>": {"participate": false}}}` in ' \
+          'package.json. pnpm trusts the packages pnpm-workspace.yaml approves builds for; Bun ' \
+          'trusts trustedDependencies in package.json, or its own default list without one.'
+        ],
+        'PSM-E-PLATFORM-VARIANT' => [
+          :unsupported, 'The platform-specific builds of %<variants>s differ from the one ' \
+                        'installed here in their NPM dependencies or whether they opt ' \
+                        "in, or don't pass `proscenium gem check`.",
+          'Make every platform build of the gem ship the same package.json dependencies and ' \
+          'proscenium.dependencies setting, each passing `proscenium gem check`. Your lockfile ' \
+          'can only hold one set.'
+        ],
+        'PSM-E-UNC-SHIM' => [
+          :unsupported, "%<manager>s is installed as a .cmd script, and cmd.exe can't run in " \
+                        "%<root>s because it's a network (UNC) path: it would run in " \
+                        'C:\\Windows instead.',
+          'Map a drive letter to the share (`net use Z: \\\\server\\share`) and run from that ' \
+          'drive, or install %<manager>s as a native executable.'
+        ],
+        'PSM-E-OWNED-LINK' => [
+          :input, '%<paths>s is a symbolic link, so installing would write outside your app.',
+          'Replace it with a real directory. Proscenium only writes inside .proscenium/.'
+        ],
+        'PSM-E-OWNED-DIR' => [
+          :input, ".proscenium/packages/ contains things Proscenium didn't create: %<entries>s.",
+          'Move them somewhere else. Proscenium manages that directory, and treats everything ' \
+          'in it as a gem dependency context.'
+        ],
+        'PSM-W-END-OF-LIFE' => [
+          :success, '%<manager>s %<version>s reaches end of life on %<eol>s, and a future ' \
+                    'Proscenium release may stop supporting it.',
+          'Plan an upgrade to a newer %<manager>s version; the upgrade guide explains the steps.'
+        ],
+        'PSM-E-INTERNAL' => [
+          :internal, 'Something went wrong inside Proscenium: %<detail>s',
+          'This is a bug in Proscenium. Please report it at ' \
+          'https://github.com/joelmoss/proscenium/issues, including the output above.'
+        ]
+      }.freeze
+
+      attr_reader :code, :fix, :details
+      # What the package manager printed, for a native failure: not shown, only searched.
+      attr_accessor :output
+
+      # `escape`, when given, is the consumer's way around a gem author's problem, appended to the
+      # fix.
+      def initialize(code, details: {}, escape: nil, **args)
+        @code = code
+        status, message, fix = CATALOG.fetch(code)
+        @status = status
+        @fix = [format(fix, **args), escape].compact.join(' ')
+        @details = details
+        super(format(message, **args))
+      end
+
+      def exit_status = EXIT.fetch(@status)
+    end
+  end
+end

data/lib/proscenium/cli/gem_archive.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'rubygems/package'
+require 'zlib'
+require_relative '../bundled_gems'
+require_relative 'rules'
+
+module Proscenium
+  module CLI
+    # A built gem's specification and package.json, read from its archive without unpacking it
+    # (#154). Nothing is extracted, so no entry name can write anywhere, and the manifest entry is
+    # read only if it is a regular file within the size limit (C29).
+    module GemArchive
+      module_function
+
+      # [spec, manifest text or nil, why it could not be read or nil].
+      def read(path)
+        spec = Gem::Package.new(path).spec
+        root = BundledGems.frontend_root(spec) || ''
+        wanted = root.empty? ? 'package.json' : File.join(root, 'package.json')
+        manifest = cause = nil
+        File.open(path, 'rb') do |io|
+          Gem::Package::TarReader.new(io).each do |entry|
+            next unless entry.full_name == 'data.tar.gz'
+
+            Zlib::GzipReader.wrap(entry) do |gz|
+              Gem::Package::TarReader.new(gz).each do |file|
+                manifest, cause = manifest_entry(file) if file.full_name == wanted
+              end
+            end
+          end
+        end
+        [spec, manifest, cause]
+      end
+
+      def manifest_entry(entry)
+        return [nil, 'it is not a regular file'] unless entry.file?
+        return [nil, 'it is larger than 1 MB'] if entry.header.size > Rules::MANIFEST_LIMIT
+
+        [entry.read, nil]
+      end
+    end
+  end
+end