cocoapods-lynx-capacitor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7ed75fbedf98ec911a750917b50637db0c6c9eb60b21f2bca8a8d894c7f39e0b
+  data.tar.gz: 7df28de26c637d5981fa419f820b5935ff41bea782a4231d439d3439bb2daee7
+SHA512:
+  metadata.gz: 4876b9361ec1c6546dd097d90823cf4ada7e9041bdf45c52efc7d62ee457fe135acf5f35fd40ece738c2e14cace70e0a0ec94ef0d01faba8881f0e1706ca3c2a
+  data.tar.gz: 9f7641bf54fe442937cd8e2d7030b7ea5e707fecfab727eb1bc180a818c7de6b22418cb75a5dff77efd21082c98497ab096513f775db92e43858c449198d4dd2

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xuan Huang and contributors
+
+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,86 @@
+# cocoapods-lynx-capacitor
+
+A CocoaPods plugin that links Capacitor plugin pods out of `node_modules`, so a
+Lynx app running [lynx-capacitor](../../README.md) never names them in its
+Podfile.
+
+```ruby
+plugin 'cocoapods-lynx-library'
+plugin 'cocoapods-lynx-capacitor'
+
+target 'App' do
+  use_lynx_library!        # the Capacitor bridge, as a Lynx native library
+  use_capacitor_plugins!   # the Capacitor plugins it dispatches to
+end
+```
+
+`npm install @capacitor/camera` + `pod install` is now the whole install
+procedure for a new plugin.
+
+## Why this exists
+
+Lynx Autolink links Lynx native libraries. lynx-capacitor is exactly one of
+those, so `use_lynx_library!` covers the bridge. It does not cover the plugin
+pods the bridge dispatches to, and two constraints keep them out of
+`LynxCapacitorRuntime.podspec`:
+
+- **A podspec cannot declare `:path` dependencies.** External sources are only
+  expressible in a Podfile. So plugin pods must be declared there.
+- **CocoaPods trunk is not a usable substitute.** As of Capacitor 8,
+  `CapacitorBarcodeScanner`, `CapacitorFileTransfer`, `CapacitorFileViewer`,
+  `CapacitorInappbrowser`, `CapacitorLocalLlm` and `CapacitorPrivacyScreen` are
+  not on trunk at all; `CapacitorBackgroundRunner` is at 1.0.5 against npm
+  3.0.0 and `CapacitorGoogleMaps` at 5.3.2 against npm 8.0.1; and none of the
+  `@capacitor-community/*` plugins are published. npm is the real distribution
+  channel, which is why the Capacitor CLI generates `:path` lines too.
+
+So something has to walk `node_modules` and emit those lines. Capacitor's CLI
+does it by rewriting the text between `def capacitor_pods` and `end` during
+`npx cap sync`. Doing it as a CocoaPods plugin instead means the Podfile is
+never rewritten, there is no marker block to preserve, and `pod install` stays
+the only command.
+
+## Behaviour
+
+**Detection** matches the Capacitor CLI: a package is a plugin when its
+`package.json` has a `capacitor` key. Official and community plugins are
+treated identically, and a plugin written in your own repo is picked up as soon
+as it is a dependency.
+
+**Podspec resolution** looks for `*.podspec` at the package root, where
+Capacitor plugins put it, then falls back to the `capacitor.ios.src` directory.
+The pod name is read from `s.name` inside the podspec, not from the filename.
+
+**The runtime** — `Capacitor` and `CapacitorCordova` from `@capacitor/ios` — is
+linked by default, since every plugin podspec carries `s.dependency 'Capacitor'`
+and that can only be satisfied by a local path. Pass `:runtime => false` to
+declare it yourself.
+
+**Paths** are the `node_modules` paths, not symlink targets. Under pnpm the real
+path embeds the version and a dependency hash
+(`.pnpm/@capacitor+device@8.0.3_@capacitor+core@8.4.2/…`), which would rewrite
+`Podfile.lock` on every bump. Symlinks are still resolved for identity, so one
+package reachable under two names is declared once.
+
+**Nothing is dropped silently.** A package with a `capacitor` key but no iOS
+podspec (`@capacitor/motion` today), a missing `@capacitor/ios`, or two distinct
+packages claiming one pod name each produce a warning naming the package and the
+reason.
+
+## Options
+
+| Option | Default | Meaning |
+|--------|---------|---------|
+| `:root` | Podfile directory | Where to start looking for `node_modules`. Walks up 6 levels, matching `cocoapods-lynx-library`. Pass this when the app's `package.json` is not on the Podfile's ancestor path. |
+| `:include` | all | Allowlist of npm package names. Mirrors Capacitor's `ios.includePlugins`. |
+| `:exclude` | none | Denylist of npm package names. |
+| `:runtime` | `true` | Also link `Capacitor` and `CapacitorCordova`. |
+
+## Tests
+
+```bash
+ruby spec/autolink_spec.rb
+```
+
+No CocoaPods or macOS needed — the suite builds `node_modules` fixtures in a
+temp dir and asserts against a fake Podfile.

data/lib/capacitor/lynx/autolink.rb

@@ -0,0 +1,251 @@
+# Resolves Capacitor plugin pods out of node_modules so a Podfile does not have
+# to name them one by one.
+#
+# This is the Capacitor half of the lynx-capacitor autolink story.
+# `cocoapods-lynx-library` links the Lynx native library that hosts the bridge;
+# this plugin links the Capacitor plugin pods the bridge dispatches to. Neither
+# can do the other's job: a podspec cannot declare `:path` dependencies, so the
+# plugin pods have to be named in the Podfile, and most Capacitor 8 plugins are
+# either missing from CocoaPods trunk or lag npm badly, so a version-based
+# dependency is not a substitute.
+#
+# Plugin detection matches the Capacitor CLI: a package is a plugin when its
+# package.json carries a `capacitor` key.
+
+require 'json'
+
+module Capacitor
+  module Lynx
+    # package_dir is the path as found under node_modules and is what lands in
+    # the Podfile. resolved_dir follows symlinks and is used only for identity:
+    # under pnpm the real path embeds the version and a dependency hash, so
+    # declaring it would rewrite Podfile.lock on every version bump.
+    PluginInfo = Struct.new(:npm_name, :package_dir, :resolved_dir, :pod_name, :podspec_path)
+    SkippedPackage = Struct.new(:npm_name, :reason)
+
+    # How far up from the starting directory to look for node_modules. Matches
+    # cocoapods-lynx-library so both plugins agree on what "the app" is.
+    NODE_MODULES_SEARCH_DEPTH = 6
+
+    # @capacitor/ios is the runtime, not a plugin: it has no `capacitor` key in
+    # package.json and ships two podspecs at its package root.
+    RUNTIME_PACKAGE = '@capacitor/ios'.freeze
+    RUNTIME_POD_NAMES = %w[Capacitor CapacitorCordova].freeze
+
+    class Autolink
+      class << self
+        # Declares every discovered Capacitor pod on the given Podfile.
+        #
+        # @param podfile [Pod::Podfile::TargetDefinition] receives `pod` calls
+        # @option options [String] :root where to start looking for node_modules
+        # @option options [Array<String>] :include only link these npm packages
+        # @option options [Array<String>] :exclude never link these npm packages
+        # @option options [Boolean] :runtime also link Capacitor/CapacitorCordova
+        # @return [Array<PluginInfo>] what was linked, in declaration order
+        def install!(podfile, options = {})
+          root = File.expand_path(options[:root] || Dir.pwd)
+          resolution = resolve(root, options)
+
+          resolution[:skipped].each do |skipped|
+            warn_once("[lynx-capacitor] skipping #{skipped.npm_name}: #{skipped.reason}")
+          end
+
+          resolution[:pods].each do |plugin|
+            podfile.pod plugin.pod_name, :path => plugin.package_dir
+          end
+          resolution[:pods]
+        end
+
+        # The pure half of install!, so callers (and tests) can inspect what
+        # would be declared without a Podfile.
+        #
+        # @return [Hash] :pods => Array<PluginInfo>, :skipped => Array<SkippedPackage>
+        def resolve(root, options = {})
+          root = File.expand_path(root)
+          packages = discover_packages(root)
+
+          pods = []
+          skipped = []
+
+          if options.fetch(:runtime, true)
+            runtime = packages[RUNTIME_PACKAGE]
+            if runtime
+              pods.concat(runtime_pods(runtime))
+            else
+              skipped << SkippedPackage.new(
+                RUNTIME_PACKAGE,
+                'not installed; declare `pod \'Capacitor\'` yourself or pass :runtime => false'
+              )
+            end
+          end
+
+          plugin_packages(packages, options).each do |npm_name, package_dir|
+            podspec_path = find_podspec(package_dir)
+            if podspec_path.nil?
+              # @capacitor/motion is the standing example: published with a
+              # `capacitor` key but no iOS implementation yet.
+              skipped << SkippedPackage.new(npm_name, 'no iOS podspec in the package')
+              next
+            end
+            pods << PluginInfo.new(npm_name, package_dir, real_path(package_dir),
+                                   pod_name_from(podspec_path), podspec_path)
+          end
+
+          { :pods => dedupe(pods, skipped), :skipped => skipped }
+        end
+
+        private
+
+        def plugin_packages(packages, options)
+          included = normalize_list(options[:include])
+          excluded = normalize_list(options[:exclude])
+
+          packages.reject { |npm_name, _dir| npm_name == RUNTIME_PACKAGE }
+                  .select { |npm_name, dir| capacitor_plugin?(dir) && npm_name != RUNTIME_PACKAGE }
+                  .reject { |npm_name, _dir| excluded.include?(npm_name) }
+                  .select { |npm_name, _dir| included.empty? || included.include?(npm_name) }
+                  .sort_by { |npm_name, _dir| npm_name }
+        end
+
+        def normalize_list(value)
+          Array(value).map(&:to_s)
+        end
+
+        # A package is a Capacitor plugin when package.json has a `capacitor`
+        # key -- the same test the Capacitor CLI applies.
+        def capacitor_plugin?(package_dir)
+          manifest = read_package_json(package_dir)
+          return false if manifest.nil?
+
+          capacitor = manifest['capacitor']
+          return false unless capacitor.is_a?(Hash)
+
+          # An `ios` entry is not required to be present for the pod to exist,
+          # but a package that opts out of iOS entirely has nothing to link.
+          !capacitor.key?('ios') || capacitor['ios'].is_a?(Hash)
+        end
+
+        def runtime_pods(package_dir)
+          RUNTIME_POD_NAMES.filter_map do |pod_name|
+            podspec_path = File.join(package_dir, "#{pod_name}.podspec")
+            next unless File.file?(podspec_path)
+            PluginInfo.new(RUNTIME_PACKAGE, package_dir, real_path(package_dir),
+                           pod_name, podspec_path)
+          end
+        end
+
+        # Capacitor plugins put `<PodName>.podspec` at the package root. The
+        # `capacitor.ios.src` directory holds sources, not the podspec, but it
+        # is checked as a fallback for plugins that lay themselves out that way.
+        def find_podspec(package_dir)
+          candidates = Dir[File.join(package_dir, '*.podspec')].sort
+          return candidates.first if candidates.any?
+
+          manifest = read_package_json(package_dir)
+          src = manifest && manifest.dig('capacitor', 'ios', 'src')
+          return nil if src.nil?
+
+          src_dir = File.expand_path(src, package_dir)
+          return nil unless File.directory?(src_dir)
+
+          Dir[File.join(src_dir, '*.podspec')].sort.first
+        end
+
+        def pod_name_from(podspec_path)
+          match = File.read(podspec_path).match(/\.name\s*=\s*['"]([^'"]+)['"]/)
+          match ? match[1] : File.basename(podspec_path, '.podspec')
+        end
+
+        # CocoaPods raises on a duplicate pod name, and the same plugin can be
+        # reachable through more than one node_modules. Nearest wins.
+        def dedupe(pods, skipped)
+          seen = {}
+          pods.each_with_object([]) do |plugin, kept|
+            existing = seen[plugin.pod_name]
+            if existing
+              if existing.resolved_dir != plugin.resolved_dir
+                skipped << SkippedPackage.new(
+                  plugin.npm_name,
+                  "#{plugin.pod_name} already linked from #{existing.package_dir}"
+                )
+              end
+              next
+            end
+            seen[plugin.pod_name] = plugin
+            kept << plugin
+          end
+        end
+
+        # Maps npm package name => realpath of its directory, nearest first.
+        def discover_packages(start_dir)
+          packages = {}
+          node_modules_dirs(start_dir).each do |node_modules|
+            each_package_dir(node_modules) do |npm_name, package_dir|
+              packages[npm_name] ||= package_dir
+            end
+          end
+          packages
+        end
+
+        def node_modules_dirs(start_dir)
+          dirs = []
+          current = File.expand_path(start_dir)
+          NODE_MODULES_SEARCH_DEPTH.times do
+            candidate = File.join(current, 'node_modules')
+            dirs << candidate if File.directory?(candidate)
+            parent = File.dirname(current)
+            break if parent == current
+            current = parent
+          end
+          dirs.uniq
+        end
+
+        def each_package_dir(node_modules)
+          Dir.children(node_modules).sort.each do |name|
+            next if name.start_with?('.')
+            path = File.join(node_modules, name)
+            next unless File.directory?(path)
+
+            if name.start_with?('@')
+              Dir.children(path).sort.each do |scoped_name|
+                scoped_path = File.join(path, scoped_name)
+                next unless File.directory?(scoped_path)
+                yield "#{name}/#{scoped_name}", scoped_path
+              end
+            else
+              yield name, path
+            end
+          end
+        end
+
+        # Identity only -- see PluginInfo. pnpm and npm workspaces symlink
+        # packages, so two node_modules entries can be the same package.
+        def real_path(path)
+          File.realpath(path)
+        rescue SystemCallError
+          File.expand_path(path)
+        end
+
+        def read_package_json(package_dir)
+          manifest_path = File.join(package_dir, 'package.json')
+          return nil unless File.file?(manifest_path)
+          JSON.parse(File.read(manifest_path))
+        rescue JSON::ParserError
+          nil
+        end
+
+        def warn_once(message)
+          @warned ||= {}
+          return if @warned[message]
+          @warned[message] = true
+
+          if defined?(Pod::UI)
+            Pod::UI.warn(message)
+          else
+            Kernel.warn(message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cocoapods-lynx-capacitor.rb

@@ -0,0 +1 @@
+require 'capacitor/lynx/autolink'

data/lib/cocoapods_plugin.rb

@@ -0,0 +1,35 @@
+require 'cocoapods-lynx-capacitor'
+
+module Pod
+  class Podfile
+    module CapacitorLynxDSL
+      # Links every Capacitor plugin found in node_modules.
+      #
+      #   plugin 'cocoapods-lynx-capacitor'
+      #
+      #   target 'App' do
+      #     use_lynx_library!         # the bridge
+      #     use_capacitor_plugins!    # the plugins it dispatches to
+      #   end
+      #
+      # @option options [String] :root where to start looking for node_modules.
+      #   Defaults to the Podfile's directory. Pass this when the app's
+      #   package.json does not sit on the Podfile's ancestor path.
+      # @option options [Array<String>] :include only link these npm packages
+      # @option options [Array<String>] :exclude never link these npm packages
+      # @option options [Boolean] :runtime also link Capacitor and
+      #   CapacitorCordova from @capacitor/ios. Defaults to true; every plugin
+      #   podspec depends on Capacitor, and that dependency can only be
+      #   satisfied by a local path.
+      def use_capacitor_plugins!(options = {})
+        ::Capacitor::Lynx::Autolink.install!(self, options)
+      end
+    end
+
+    include CapacitorLynxDSL
+
+    module DSL
+      include CapacitorLynxDSL
+    end
+  end
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: cocoapods-lynx-capacitor
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Xuan Huang
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: cocoapods
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.16'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.16'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: |
+  A CocoaPods plugin that resolves Capacitor plugin pods out of node_modules,
+  so a Lynx app running lynx-capacitor does not have to name each plugin in
+  its Podfile. Companion to cocoapods-lynx-library, which links the Lynx
+  native library hosting the Capacitor bridge.
+email:
+- 5563315+Huxpro@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/capacitor/lynx/autolink.rb
+- lib/cocoapods-lynx-capacitor.rb
+- lib/cocoapods_plugin.rb
+homepage: https://github.com/huxpro/lynx-capacitor
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/huxpro/lynx-capacitor
+  rubygems_mfa_required: 'true'
+post_install_message:
+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: 3.3.15
+signing_key:
+specification_version: 4
+summary: Links Capacitor plugin pods from node_modules into a Lynx app.
+test_files: []