posh-bundler 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 309277cc095b3194722d4d32d7d2bbc9a2f05b215062341fd2c6707628a283db
+  data.tar.gz: a7fde107875690b842cfe2fe5a506e5affef3ad5a32d656a3d1d72240e410ce6
+SHA512:
+  metadata.gz: 728721cd026d187b172414a35c52ec19b730932ba4d8638adfaef537f7df69be33ecbba8001e416d8cc549c3cb615359a81a9990e68c542130e927ee6eecc367
+  data.tar.gz: e3590f45bd37b5302fba5e25e41c1029299b0a93a3065169686c8323f764f8b84d047ae6ce09da19c322e18828a2b2076b10ab3f752c721a25ba2e00839686c0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stanislav Katkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,137 @@
+# posh-bundler
+
+Automatically run [`posh sync`](https://poshtui.com) after `bundle install` and
+`bundle update`, so your local Ruby and gem documentation follows your project's
+resolved dependencies.
+
+This is an optional **local-development tool**. Install it on your development
+machine; it is not needed to run or deploy your application, or in CI.
+
+## Requirements
+
+- Ruby 2.7 or newer and Bundler >= 2.3.17, < 5.0.
+- The POSH executable installed separately and available on your `PATH`.
+- A Ruby project with a `Gemfile` and `Gemfile.lock`.
+
+This gem is a small Bundler plugin, not the POSH executable. See the
+[POSH setup guide](https://poshtui.com/docs) to install POSH.
+
+## Enable automatic sync
+
+On your development machine, from the Ruby project where you want automatic sync:
+
+```sh
+bundle plugin install posh-bundler
+```
+
+Bundler installs the plugin locally when you run this inside a project. To enable
+it for all of your projects, run the command outside any directory containing a
+Gemfile, including its parent directories. Global plugins are scoped to your
+user and Bundler's plugin configuration, not every Ruby installation on a machine.
+
+After enabling it, use Bundler normally:
+
+```sh
+bundle install
+bundle update
+bundle update rails
+```
+
+The plugin runs `posh sync --project /path/to/project` once after the installer
+succeeds and writes the lockfile. It also runs when all dependencies are already
+installed. POSH reuses installed docsets; syncing still uses the network and runs
+synchronously, so Bundler waits for it to finish.
+
+If POSH is missing, cannot download docs, or exits unsuccessfully, the plugin
+prints a warning and leaves Bundler's installation successful. Retry manually
+with `posh sync`. Failed dependency installations do not trigger a sync.
+
+The plugin does not add an application dependency or change your Gemfile. Do not
+add it with `gem "posh-bundler"`: Bundler plugins need explicit installation.
+For a shared, project-level opt-in, Bundler also supports this Gemfile directive:
+
+```ruby
+plugin "posh-bundler"
+```
+
+That installs and registers the plugin when contributors run `bundle install`.
+They still need to install POSH separately. The directive is not automatically
+limited to development: prefer the per-developer installation command above if
+you do not want Bundler to install the plugin in CI or production.
+
+## Disable or remove
+
+Skip automatic sync for one command, for example while offline, in CI, or during
+a production deployment:
+
+```sh
+POSH_AUTO_SYNC=0 bundle install
+```
+
+If the plugin is present in CI or production, set `POSH_AUTO_SYNC=0` in those
+environments. The plugin does not detect development or production automatically.
+This skips syncing; Bundler can still install a plugin declared in the Gemfile.
+Only the exact value `0` disables the hook. Manual `posh sync` commands are unaffected.
+
+Remove a locally installed plugin from the project where you installed it:
+
+```sh
+bundle plugin uninstall posh-bundler
+```
+
+For a global installation, uninstall from outside a project. If you declared the
+plugin in your Gemfile, remove that directive too, or Bundler will reinstall it.
+
+## Scope
+
+The plugin uses Bundler's project root even when Bundler is invoked from a
+subdirectory, and starts POSH outside Bundler's modified Ruby environment. It
+targets the standard `Gemfile.lock` that POSH discovers in that project.
+
+It does not run after `bundle lock`, `git pull`, or a branch switch. Run
+`posh sync` manually after those operations if your dependencies changed.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+bundle exec standardrb
+bundle exec rake build
+```
+
+Tests use isolated temporary projects and a fake POSH executable. They exercise
+real Bundler plugin installation, dependency installation, and updates without
+network access or changing your user-level plugin configuration.
+
+With Bundler 4, you can try the plugin in another project before publishing it:
+
+```sh
+bundle plugin install posh-bundler --path /absolute/path/to/posh-bundler
+```
+
+Bundler runs a path-installed plugin directly from that directory. Reinstall it
+after changing hook registrations in `plugins.rb`.
+
+## Releasing
+
+Set the release version in `lib/posh_bundler/version.rb` and commit all changes.
+Then run:
+
+```sh
+bundle exec rake test
+bundle exec standardrb
+bundle exec rake release
+```
+
+The release task uses Bundler's standard gem tasks. It builds the gem in `pkg/`,
+checks for uncommitted changes, creates a `vVERSION` tag (for example, `v0.1.0`),
+pushes the current branch and tag to its Git remote, and publishes the gem to
+RubyGems. You need Git push access and RubyGems authentication with MFA enabled.
+
+To build the gem without tagging, pushing, or publishing, use
+`bundle exec rake build` instead.
+
+## License
+
+[MIT](LICENSE).

data/lib/posh_bundler/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PoshBundler
+  VERSION = "0.1.0"
+end

data/lib/posh_bundler.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "posh_bundler/version"
+
+module PoshBundler
+  def self.sync
+    return if ENV["POSH_AUTO_SYNC"] == "0"
+
+    project = Bundler.root.to_s
+
+    Bundler.with_unbundled_env do
+      system("posh", "sync", "--project", project, exception: true)
+    end
+  rescue => error
+    Bundler.ui.warn("POSH: documentation sync failed (#{error.message}). Run `posh sync` to retry.")
+  end
+end

data/plugins.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/plugin/api"
+require "posh_bundler"
+
+Bundler::Plugin::API.hook("after-install-all") do |_dependencies|
+  PoshBundler.sync
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: posh-bundler
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stanislav Katkov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.3.17
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.3.17
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: A best-effort Bundler plugin that runs posh sync once after bundle install
+  or bundle update, using the project's resolved dependencies.
+email:
+- contact@poshtui.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/posh_bundler.rb
+- lib/posh_bundler/version.rb
+- plugins.rb
+homepage: https://poshtui.com
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/skatkov/posh-bundler
+  documentation_uri: https://poshtui.com/docs#automatic-sync-with-bundler-optional
+  bug_tracker_uri: https://github.com/skatkov/posh-bundler/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.19
+specification_version: 4
+summary: Keep POSH documentation in sync after Bundler installs and updates.
+test_files: []