proscenium 0.26.0-x86_64-linux-gnu → 0.27.0-x86_64-linux-gnu

data/lib/proscenium/contexts/map.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require 'bundler'
+require 'json'
+require_relative '../app_package'
+require_relative '../bundled_gems'
+require_relative '../yaml_tree'
+
+module Proscenium
+  module Contexts
+    # What the engine passes Go about gem dependency contexts (#154): which gems resolve their
+    # bare imports from `.proscenium/packages/<gem>/`, and which of the app's own packages keep
+    # their link paths. Built from committed files and Bundler only. Like BundledGems, it loads
+    # nothing the `proscenium` CLI may not.
+    module Map
+      CONTEXTS = File.join('.proscenium', 'packages')
+      REGISTRATION = '.proscenium/packages/*'
+
+      module_function
+
+      # Where the `proscenium` CLI keeps contexts, its lock and its marker: the bundle's root, which
+      # need not be Rails.root.
+      def project_root = Bundler.root.to_s
+
+      # The config keys Go reads, for the app at `root`. Read once per mapping generation: a value
+      # read during an older one is kept under that one's key, never handed to the next.
+      def config(root, generation = 0)
+        @config ||= {}
+        @config[[root, generation]] ||= { DependencyContexts: contexts(root),
+                                          AppLocalPackages: AppPackage.local_packages(root) }.freeze
+      end
+
+      def reset! = @config = {}
+
+      # Each registering file, with the lockfile and the name of the manager that reads it.
+      REGISTRARS = { 'pnpm-workspace.yaml' => %w[pnpm-lock.yaml pnpm],
+                     'package.json' => %w[bun.lock bun] }.freeze
+
+      # Whether the app at `root` adopted gem dependency contexts: pnpm's workspace file registers
+      # them, or package.json does in a Bun app. Each counts only where its manager installs: when
+      # packageManager names no other manager, and with that manager's lockfile or no other
+      # manager's, as an app missing its lockfile is an incomplete checkout, which must not silently
+      # switch the contexts off.
+      def adopted?(root) = !registrar(root).nil?
+
+      # The file whose registration makes the app at `root` adopted, or nil.
+      def registrar(root)
+        named = AppPackage.package_manager(root)
+        REGISTRARS.find do |file, (own, manager)|
+          # bun.lockb is Bun's too, until bun.lock replaces it.
+          others = [*UNSUPPORTED.keys, *REGISTRARS.values.map(&:first)] - [own] +
+                   (manager == 'bun' ? [] : ['bun.lockb'])
+          registers?(root, file) && [nil, manager].include?(named) &&
+            (File.exist?(File.join(root, own)) || others.none? { File.exist?(File.join(root, it)) })
+        end&.first
+      end
+
+      # Whether `file` lists the contexts: pnpm-workspace.yaml's `packages`, or package.json's
+      # `workspaces` (an array, or an object's `packages`). Parsed, so a commented-out line does not
+      # count. For the engine a file that does not parse counts if it names them, so a parse failure
+      # never silently switches off the context map and the stale check; `strict` (the CLI, which
+      # must register a file its manager can read) counts only a file that parses.
+      def registers?(root, file)
+        path = File.join(root, file)
+        File.exist?(path) && registered_in?(file, File.read(path))
+      end
+
+      def registered_in?(file, text, strict: false)
+        text = utf8(text).delete_prefix(BOM)
+        list = file.end_with?('.yaml') ? yaml_packages(text) : json_workspaces(text)
+        list.is_a?(Array) && list.any? { registration?(it) } && !excludes?(list)
+      rescue Psych::SyntaxError, JSON::ParserError
+        return false if strict
+
+        file.end_with?('.yaml') ? text.include?(REGISTRATION) : AppPackage.workspaces?(text)
+      end
+
+      # Whether the list has a `!` pattern that takes a context out: pnpm and Bun apply one whatever
+      # its order, so the contexts would never be installed. Generous: `*` crosses `/`, and any
+      # segment of the pattern may be a gem's directory.
+      def excludes?(list)
+        Array(list).grep(/\A!/).any? do |entry|
+          pattern = entry[1..].delete_prefix('./').chomp('/')
+          # A segment with a wildcard, class or brace, such as `[ah]ue`, may match any gem.
+          wide = pattern.split('/').map { it.match?(/[*?\[{]/) ? '*' : it }.join('/')
+          ['gem', *pattern.split('/')].product([pattern, wide]).any? do |name, glob|
+            File.fnmatch?(glob, "#{CONTEXTS}/#{name}", GLOB)
+          end
+        end
+      end
+
+      GLOB = File::FNM_EXTGLOB | File::FNM_DOTMATCH
+
+      def json_workspaces(text)
+        parsed = JSON.parse(text)
+        list = parsed['workspaces'] if parsed.is_a?(Hash)
+        list.is_a?(Hash) ? list['packages'] : list
+      end
+
+      # pnpm-workspace.yaml's `packages`: each entry's scalar text, or nil for one that is not a
+      # scalar; nil when the document is not a mapping or the key is missing or not a list. Read
+      # from the parse tree and never built into Ruby objects, so no alias can make it slow and no
+      # tag or date can raise. Raises Psych::SyntaxError.
+      def yaml_packages(text)
+        list, anchors = YamlTree.value(text, 'packages')
+        return unless list.is_a?(Psych::Nodes::Sequence)
+
+        list.children.map do |entry|
+          entry = YamlTree.node(entry, anchors)
+          entry.value if entry.is_a?(Psych::Nodes::Scalar)
+        end
+      end
+
+      # pnpm and Bun read `./<pattern>` and `<pattern>/` as the pattern.
+      def registration?(entry)
+        entry.is_a?(String) && entry.delete_prefix('./').chomp('/') == REGISTRATION
+      end
+
+      BOM = "\uFEFF"
+
+      # A JSON file as Node, pnpm and Bun read it, a leading byte order mark included.
+      def read_json(path) = parse_json(File.read(path))
+      def parse_json(text) = JSON.parse(utf8(text).delete_prefix(BOM))
+
+      # Text as UTF-8, whatever encoding the caller's locale gave it.
+      def utf8(text) = text.dup.force_encoding(Encoding::UTF_8)
+
+      # Gem name => absolute context directory for each participating gem, when the app at `root`
+      # adopted dependency contexts; empty before. A gem whose context is missing is mapped all the
+      # same: its imports then fail by name rather than fall back to the app's packages.
+      def contexts(root, specs = BundledGems.installed_specs)
+        return {} unless adopted?(root)
+
+        BundledGems.participating(specs, overrides: BundledGems.overrides(root)).keys.to_h do |gem|
+          [gem, File.join(root, CONTEXTS, gem)]
+        end
+      rescue BundledGems::ConfigError
+        {} # Stale reports it, so every build is refused with the reason
+      end
+
+      INSTALLING = File.join('.proscenium', 'installing')
+      LOCK = File.join('.proscenium', 'lock')
+      INSTALLING_MESSAGE = '`bundle exec proscenium install` is running, or stopped before it ' \
+                           'finished. Wait for it, or run it again.'
+
+      # Whether an install is under way in the app at `root`, or stopped before it finished: its
+      # marker is there, or another process holds the project lock. The engine refuses to build or
+      # resolve meanwhile (C34). The probe takes a shared lock, so it never stops an install
+      # starting; the CLI retries a lock it finds taken for a moment. About 16 µs.
+      def installing?(root)
+        return true if File.exist?(File.join(root, INSTALLING))
+
+        lock = File.join(root, LOCK)
+        File.exist?(lock) && File.open(lock, File::RDONLY) { !it.flock(File::LOCK_SH | File::LOCK_NB) }
+      end
+
+      # Each file that says the app uses an unsupported manager, as Manager.select reads them.
+      UNSUPPORTED = { 'yarn.lock' => 'Yarn', '.yarnrc.yml' => 'Yarn', 'package-lock.json' => 'npm',
+                      'npm-shrinkwrap.json' => 'npm' }.freeze
+
+      # The one notice a process logs at boot when gems opt in but the app has not adopted
+      # dependency contexts, or nil. Those gems' imports keep resolving as they always have, so
+      # upgrading Proscenium never breaks an app that has not run `proscenium install` (C52).
+      def adoption_notice(root, specs = BundledGems.installed_specs)
+        return if adopted?(root)
+
+        gems = BundledGems.participating(specs, overrides: BundledGems.overrides(root)).keys
+        return if gems.empty?
+
+        opted = "#{gems.join(', ')} opt in to installing their NPM dependencies " \
+                'through Proscenium'
+        manager = UNSUPPORTED.find { |file, _| File.exist?(File.join(root, file)) }&.last
+        if manager
+          "#{opted}, but #{manager} is not supported, so the app keeps managing them."
+        else
+          "#{opted}. Run `bundle exec proscenium install` to install them."
+        end
+      rescue BundledGems::ConfigError => e
+        e.message
+      end
+    end
+  end
+end

data/lib/proscenium/contexts/mapping_generation.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative '../bundled_gems'
+require_relative 'map'
+require_relative 'stale'
+
+module Proscenium
+  module Contexts
+    # Which mapping generation a build uses (#154). A generation is the context map and the
+    # staleness verdict, read once and kept, so every build sees one consistent view. In production
+    # a generation lasts the process: restart after a deploy. In development and test, `refresh`
+    # looks at most once a second for a change to the files the map is built from, and starts a new
+    # generation when one changed, such as `proscenium install` finishing.
+    #
+    # Gemfile.lock is watched, but a gem added or upgraded still needs a restart: Bundler loads the
+    # bundle once per process.
+    module MappingGeneration
+      # The lockfiles too: with contexts adopted, resolved paths carry each package's version.
+      WATCHED = ['Gemfile.lock', 'package.json', 'pnpm-workspace.yaml', '.npmrc',
+                 'bunfig.toml', 'pnpm-lock.yaml', 'bun.lock', Map::INSTALLING].freeze
+      EVERY = 1.0
+      LOCK = Mutex.new
+
+      module_function
+
+      # The current generation number, starting a new one first if a watched file changed and the
+      # last look was at least `every` seconds ago. Returns [number, whether it just changed].
+      def refresh(root, every: EVERY)
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        LOCK.synchronize do
+          @looked ||= {}
+          @number ||= 0
+          at, before = @looked[root]
+          return [@number, false] if at && now - at < every
+
+          after = signature(root)
+          @looked[root] = [now, after]
+          return [@number, false] if before.nil? || before == after
+
+          Map.reset!
+          Stale.reset!
+          [@number += 1, true]
+        end
+      end
+
+      # The modification time of every file the map is built from, by path, nil for a missing one.
+      def signature(root)
+        files = WATCHED.map { File.join(root, it) } +
+                Dir.glob(File.join(root, Map::CONTEXTS, '*', 'package.json')) +
+                manifests(root)
+        files.sort.to_h { [it, File.exist?(it) ? File.mtime(it).to_f : nil] }
+      end
+
+      # Each participating gem's package.json: editing a path gem's manifest makes its context
+      # stale.
+      def manifests(root)
+        participating = BundledGems.participating(BundledGems.installed_specs,
+                                                  overrides: BundledGems.overrides(root))
+        participating.values.filter_map { BundledGems.manifest_root(it) }
+                     .map { File.join(it, 'package.json') }
+      rescue BundledGems::ConfigError
+        []
+      end
+
+      def reset! = LOCK.synchronize { @looked = {} }
+    end
+  end
+end

data/lib/proscenium/contexts/messages.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+module Proscenium
+  module Contexts
+    # The text of every Proscenium error and warning, by code: the problem, its cause and the fix.
+    # Templates take keyword arguments. The model reports a problem as a `[code, args]` pair and
+    # renders it here; the CLI's Error adds the exit status (cli/error.rb). Golden-output tests pin
+    # the text of each entry (test/cli/golden/).
+    class Messages
+      # code => [message template, fix template].
+      TEXT = {
+        'PSM-E-USAGE' => [
+          '%<detail>s',
+          'Run `bundle exec proscenium --help` to see the commands and their options.'
+        ],
+        'PSM-E-GEMSPEC' => [
+          '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' => [
+          '%<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' => [
+          "%<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' => [
+          "%<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' => [
+          "%<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' => [
+          "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' => [
+          "%<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' => [
+          '%<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' => [
+          "%<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' => [
+          "%<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' => [
+          "%<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' => [
+          '%<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' => [
+          "%<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' => [
+          "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' => [
+          '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' => [
+          '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' => [
+          "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' => [
+          "%<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' => [
+          "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' => [
+          "--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' => [
+          "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' => [
+          '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' => [
+          "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' => [
+          '%<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' => [
+          '%<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' => [
+          '`%<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' => [
+          '`%<command>s` was stopped before it finished.',
+          'Run `bundle exec proscenium install` again to finish.'
+        ],
+        'PSM-E-CROSS-GEM-TARGET' => [
+          "%<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' => [
+          "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' => [
+          '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' => [
+          "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' => [
+          "%<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' => [
+          ".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' => [
+          '%<lockfile>s is missing.',
+          'Run `bundle exec proscenium install`, then commit %<lockfile>s.'
+        ],
+        'PSM-E-NOT-INSTALLED' => [
+          "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' => [
+          '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' => [
+          "%<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' => [
+          '%<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' => [
+          "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' => [
+          "`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' => [
+          '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' => [
+          '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' => [
+          "%<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' => [
+          '%<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' => [
+          ".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' => [
+          '%<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' => [
+          '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
+
+      def self.message(code, **args) = format(TEXT.fetch(code).first, **args)
+
+      def self.fix(code, **args) = format(TEXT.fetch(code).last, **args)
+    end
+  end
+end

data/lib/proscenium/{cli/contexts.rb → contexts/plan.rb}

@@ -1,18 +1,18 @@
 # frozen_string_literal: true
 
 require 'json'
-require_relative '../context_map'
+require_relative 'map'
 require_relative '../bundled_gems'
-require_relative '../dependency_context'
+require_relative 'projection'
 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')
+  module Contexts
+    # 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.
+    # Shared by the engine (Stale) and the CLI (install, inspect), so it loads nothing of the
+    # CLI; problems are `[code, args]` pairs, rendered by whoever reports them.
+    class Plan
       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."
@@ -36,7 +36,7 @@ module Proscenium
 
       # The committed context directories under the app, by gem name.
       def self.committed(root)
-        dir = File.join(root, DIR)
+        dir = File.join(root, Map::CONTEXTS)
         return {} unless Dir.exist?(dir)
 
         Dir.children(dir).select { File.directory?(File.join(dir, it)) }.sort
@@ -61,8 +61,8 @@ module Proscenium
         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),
+        context = Projection.project(gem, manifest)
+        @contexts[gem] = Context.new(gem:, json: Projection.to_json(context),
                                      git_and_url: git_and_url(context))
       end
 
@@ -75,7 +75,7 @@ module Proscenium
           return problem('PSM-E-MANIFEST', gem:, path: 'package.json', cause:)
         end
 
-        manifest = ContextMap.read_json(path)
+        manifest = Map.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')

data/lib/proscenium/contexts/projection.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+
+module Proscenium
+  module Contexts
+    # A participating gem's dependency context (#154): its package.json through the
+    # `dependency-context-v1` projection, which keeps installation metadata only and is committed at
+    # `.proscenium/packages/<gem>/package.json`.
+    #
+    # The one owner of the projection and its hash, shared by the CLI and the engine, so it must not
+    # load ActiveSupport or anything else the CLI may not.
+    module Projection
+      PROJECTION = 'dependency-context-v1'
+
+      # The manifest fields a context keeps, in the order it writes them. Everything else (scripts,
+      # devDependencies, version, entry points, workspaces) is left in the gem's own package.json.
+      FIELDS = %w[dependencies peerDependencies peerDependenciesMeta optionalDependencies engines os
+                  cpu libc].freeze
+
+      module_function
+
+      def name_for(gem) = "@rubygems/#{gem}"
+
+      def description_for(gem)
+        "Generated by Proscenium from the #{gem} gem. Do not edit; " \
+          'run bundle exec proscenium install.'
+      end
+
+      # The context for `gem` from its parsed `manifest`. An empty field is left out, as an absent
+      # one is: the two install the same, so they hash the same.
+      def project(gem, manifest)
+        fields = FIELDS.each_with_object({}) do |key, kept|
+          value = manifest[key]
+          kept[key] = value unless value.nil? || (value.respond_to?(:empty?) && value.empty?)
+        end
+
+        { 'name' => name_for(gem), 'private' => true, 'description' => description_for(gem),
+          **fields,
+          'proscenium' => { 'projection' => PROJECTION,
+                            'projectionSha256' => digest(gem, fields) } }
+      end
+
+      # The bytes committed for a context: fixed key order, two-space indent, a trailing newline,
+      # and nothing that varies by host or time.
+      def to_json(context) = "#{JSON.pretty_generate(context)}\n"
+
+      # The projection hash. It hashes a fixed-field encoding of the projected fields, not JSON, so
+      # it does not move with the json gem's output, key order, whitespace or escaping, and an edit
+      # to anything the projection drops leaves it alone.
+      def digest(gem, fields)
+        Digest::SHA256.hexdigest("#{PROJECTION}\n#{encode(name_for(gem))}#{encode(fields)}")
+      end
+
+      # A self-delimiting encoding: a type tag, a length where there is one, then the value. Hash
+      # keys are sorted by their bytes, so key order in the manifest does not matter; array order
+      # does, as it does to npm.
+      def encode(value)
+        case value
+        when String then "s#{value.bytesize}:#{value.b}"
+        when true then 't'
+        when false then 'f'
+        when nil then 'n'
+        when Integer then "i#{value};"
+        when Float then "d#{value};"
+        when Array then "a#{value.size}:#{value.map { encode(it) }.join}"
+        when Hash
+          pairs = value.sort_by { |key, _| key.to_s.b }
+          "h#{value.size}:#{pairs.map { |key, val| encode(key.to_s) + encode(val) }.join}"
+        else
+          raise ArgumentError, "cannot encode #{value.class} in a dependency context"
+        end
+      end
+    end
+  end
+end