sf_cli 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea26ff0c7b396c91b431caf812ccc8e8cc702433205082ed68891b67bd82a910
-  data.tar.gz: 920c35bc989df4230a76f52256c01a98c13c8c9105e9ea7ea6819dd32ffa49b5
+  metadata.gz: 9416d015ec2952621fe3525a9ed7177a68b98a86d3bced475eacf19d3ad88ce0
+  data.tar.gz: 545bb5c54d345c194c5b62e8599492a45b13ba156b6ce195d3fb1fe38bb0d656
 SHA512:
-  metadata.gz: 995c401c9b9eb0d4fb076b70b6e6e74dde07272dbdb85117a767e746cf3f3995322d27b789ecf2df8a2b077ef7c78f9dac0bc5cf8d2ad5112fe50d4c07a5c7d3
-  data.tar.gz: 82f9bf6f26330c1219de3a9f7660236e8d3db61393957bb476413d86dc0d79d5627d847e0e5d6ed2605ef311efc9961cb6b99e39dac9b0d7c5bb7d4c7c7837a1
+  metadata.gz: bf7e32d0d73b0af136d8153b16b05cf837977f37bd2b95c0ab0cecd8fe23bef9cfcb64bda1a1b16dc1ae5ce92fbf239670c4282fd65df28ff0f4bd835f3810cc
+  data.tar.gz: 835a95c35ef507c44d5108b613f7300bd8723428fd897ffc64ce8b0d14d0837929dc416c8259e12b713814903f1e5d59e1832e5d57bb9785f3c9bc397d111f8a

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+## 0.0.4 - 2024-09-02
+- breaking change:
+  - Sf class doesn't exist anymore. You can not write like `sf = SfCli::Sf.new`. Instead of that,  global `sf` method is introduced. You can directly type like `sf.org.display`, which is as almost same usability as the original command. 
+- sf data query:
+  - support child-parent relationship
+  - support parent-children relationship
+  - add `--result-format` option
+- auto generation of Object Model (experimental)
+  - generates SF Object Classes automatically
+  - relationship is supported
+
+## 0.0.3 - 2024-08-25
+add command operations:
+
+- sf data get record
+- sf data create record
+- sf data update record
+- sf data delete record
+
+## 0.0.2 - 2024-08-18
+this version up was made by mistake.
+nothing was changed.
+
+## 0.0.1 - 2024-08-18
+support some command operations:
+
+- sf org login web
+- sf display
+- sf data query
+- sf sobject describe
+- sf sobject list
+- sf project generate
+- sf project generate manifest

data/README.rdoc

@@ -0,0 +1,96 @@
+= Salesforce CLI library
+https://badge.fury.io/rb/sf_cli.png
+
+This is a class library for introducing {Salesforce CLI}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_top.htm] to Ruby scripting.<br>
+It is designed to be similar usability to the original command.<br>
+Currently only *sf* command is the target of development.
+
+== prerequisite
+Salesforce CLI must be installed.<br>
+As of as of August in 2024, ver.2.54.6 is the development target.
+
+== install
+=== Rubygem
+  $ gem install sf_cli
+
+=== Bundler
+in Gemfile:
+  gem 'sf_cli'
+
+then,
+  $ bundle install
+
+== Examples
+=== Since 0.0.4
+  require 'sf_cli'
+  #
+  # login to org
+  #
+  sf.org.login_web
+  sf.org.login_web target_org: :dev  # if the org you login isn't the default one, you should give it alias name for later use. 
+
+  #
+  # get records
+  #
+  sf.data.query 'SELECT Id, Name FROM Account LIMIT 1' # => [{Id: "abc", Name: "account name"}]
+
+  Account = Struct.new(:Id, :Name) # you can manually prepare the object model
+  sf.data.query('SELECT Id, Name From Account Limit 3', model_class: Account)  # returns an array of Account
+
+  # child-parent relationship is supported
+  sf.data.query 'SELECT Id, Name, Account.Name From Contact Limit 1'  #  [{Id: "abc", Name: "contact name", Account: {Name: "account name"}}]
+
+  # parent-children relationship is supported
+  sf.data.query 'SELECT Id, Name, (SELECT Name From Contacts) FROM Account Limit 1'  #  [{Id: "abc", Name: "account name", Contacts: [{Name: "contact name"}]}]
+
+  #
+  # get sobject schema
+  #
+  sf.sobject.describe :Case  # get Case Object schema information
+
+  #
+  # generate a Salesforce DX project with manifest generation option
+  #
+  sf.project.generate 'MyProject', manifest: true
+
+=== Before 0.0.3
+  require 'sf_cli/sf'
+
+  sf = SfCli::Sf.new
+
+  # login to org
+  sf.org.login_web
+  sf.org.login_web target_org: :dev  # name an alias to the org, which you're going to log in, for later use. This is needed when you don't use the default org.
+
+  # get Account records
+  sf.data.query 'SELECT Id, Name FROM Account LIMIT 3' # => returns an array containing 3 records
+  
+  Account = Struct.new(:Id, :Name)
+  sf.data.query('SELECT Id, Name From Account Limit 3', model_class: Account)  # returns an array of Account struct object
+
+  # generate a Salesforce DX project
+  sf.project.generate 'MyProject'
+
+== \Object Model support (experimental, since 0.0.4)
+  require 'sf_cli'
+  require 'sf_cli/sf/model'
+
+  # generates Model Class for Contact and Account, accessing the org aliased as 'dev'
+  SfCli::Sf::Model.generate %w[Contact Account], target_org: :dev
+
+  c = Contact.new(:Name => "John Smith")
+  c.Name # => "John Smith"
+
+  rows = sf.data.query 'SELECT Id, Name, Account.Name From Contact Limit 1', model_class: Contact
+  rows.size # => 1
+  rows.first.Name # => Name of the Contact
+  rows.first.Account.Name # => Name of the Account
+
+== Documents
+The following steps generate *doc* directory, which all documents are generated in.
+  $ git clone https://github.com/tmkw/sf_cli.git
+  $ cd sf_cli
+  $ bundle install
+  $ bundle exec rake rdoc
+
+*Or*, you can read the same documents online at {rubygems.org}[https://rubygems.org/gems/sf_cli]

data/lib/sf_cli/sf/core/base.rb

@@ -0,0 +1,80 @@
+module SfCli
+  module Sf
+    module Core
+      module Base
+        attr_reader :varbose
+
+        private
+
+        def exec(action, flags: {}, switches: {}, redirection: nil, raw_output: false, format: :json) # :doc:
+          cmd = %|sf #{category} #{action}#{as_flag_options(flags)}#{as_switch_options(switches, format)}#{redirect redirection}|
+          puts cmd if varbose
+
+          return `#{cmd}` if raw_output
+
+          json = JSON.parse `#{cmd}`
+          puts json if varbose
+          raise StandardError.new(json['message']) if json['status'] != 0
+
+          json
+        end
+
+        def category
+          self.class.name.split('::')[-2].downcase
+        end
+
+        def field_value_pairs(hash)
+          return nil if hash.nil?
+          return nil if hash.empty?
+
+          hash.each_with_object([]) do|(k,v), arr|
+            value = v.instance_of?(String) ? %|'#{v}'| : v
+            arr << %(#{k}=#{value})
+          end
+          .join(' ')
+        end
+
+        def as_flag_options(hash)
+          flag_options   = hash.map{|k,v| flag k, v}.reject(&:nil?).join(' ')
+          flag_options   = ' ' + flag_options unless flag_options.empty?
+
+          flag_options
+        end
+
+        def as_switch_options(hash, format)
+          if format.to_sym == :json
+            ' ' + {json: true}.merge(hash).each_with_object([]){|(k,v), arr| arr << %(--#{k}) if v}.join(' ')
+          else
+            return '' if hash.empty?
+            hash.each_with_object([]){|(k,v), arr| arr << %(--#{k}) if v}.join(' ')
+          end
+        end
+
+        def flag(name, arg)
+          arg ? %(--#{name} #{arg}) : nil
+        end
+
+        def os
+          @os ||= ENV['OS']
+        end
+
+        def redirect(option)
+          case option
+          when :null_stderr
+            null_stderr_redirection
+          else
+          end
+        end
+
+        def null_stderr_redirection
+          @null_stderr_redirection ||=
+            if os.eql?('Windows_NT')
+              ' 2>nul'
+            else
+              ' 2> /dev/null'
+            end
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/data/core.rb

@@ -0,0 +1,179 @@
+require_relative '../core/base'
+require_relative './helper_methods'
+
+module SfCli
+  module Sf
+    module Data
+      #
+      # ==== description
+      # The class representing *sf* *data*
+      #
+      # https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm
+      #
+      class Core
+        include ::SfCli::Sf::Core::Base
+        include ::SfCli::Sf::Data::HelperMethods
+
+        # get object records using SQOL. (eqivalent to *sf* *data* *query*)
+        #
+        # *soql* --- SOQL<br>
+        # *target_org* --- an alias of paticular org, not default one<br>
+        # *model_class* --- the object model class<br>
+        #
+        # == examples
+        #   sf.data.query 'SELECT Id, Name FROM Account LIMIT 1' # => [{Id: "abc", Name: "account name"}]
+        #
+        #   Account = Struct.new(:Id, :Name)
+        #   sf.data.query('SELECT Id, Name From Account Limit 3', model_class: Account)  # returns an array of Account struct object
+        #
+        #   # child-parent relationship is supported
+        #   sf.data.query 'SELECT Id, Name, Account.Name From Contact Limit 1'  #  [{Id: "abc", Name: "contact name", Account: {Name: "account name"}}]
+        #
+        #   # parent-children relationship is supported
+        #   sf.data.query 'SELECT Id, Name, (SELECT Name From Contacts) FROM Account Limit 1'  #  [{Id: "abc", Name: "account name", Contacts: [{Name: "contact name"}]}]
+        #
+        #   Account = Struct.new(:Id, :Name) # you can manually prepare the object model
+        #   sf.data.query('SELECT Id, Name From Account Limit 3', model_class: Account)  # returns an array of Account
+        #
+        # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_query_unified]
+        #
+        # About querying with auto generated object model, see the section {"Object Model support"}[link://files/README_rdoc.html#label-Object+Model+support+-28experimental-2C+since+0.0.4-29] in README.
+        #
+        def query(soql, target_org: nil, format: nil, model_class: nil)
+          flags    = {
+            :"query"    => %("#{soql}"),
+            :"target-org" => target_org,
+            :"result-format" => format,
+          }
+
+          raw_output = format ? true : false
+          format = format || :json
+
+          result = exec(__method__, flags: flags, redirection: :null_stderr, raw_output: raw_output, format: format)
+          return result if raw_output
+
+          result['result']['records'].each_with_object([]) do |h, a|
+            record = prepare_record(h)
+            a << (model_class ? model_class.new(**record) : record)
+          end
+        end
+
+        # get a object record. (eqivalent to *sf* *data* *get* *record*)
+        #
+        # *object_type* --- \Object Type (ex. Account)<br>
+        # *record_id* --- id of the object<br>
+        # *where* --- hash object that is used to identify a record<br>
+        # *target_org* --- an alias of paticular org, not default one<br>
+        # *model_class* --- the object model class<br>
+        #
+        # ==== examples
+        #   sf.data.get_record :Account, record_id: 'xxxxxxx'
+        #   sf.data.get_record :Account, where: {Name: 'Jonny B.Good', Country: 'USA'}
+        #
+        #   CustomObject = Struct.new(:Id, :Name)
+        #   sf.data.get_record :TheCustomObject__c, record_id: 'xxxxx', model_class: CustomObject  # returns a CustomObject struct object
+        #
+        # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_get_record_unified]
+        #
+        def get_record(object_type, record_id: nil, where: nil, target_org: nil, model_class: nil)
+          where_conditions = field_value_pairs(where)
+          flags = {
+            :"sobject"    => object_type,
+            :"record-id"  => record_id,
+            :"where"      => (where_conditions.nil? ? nil : %|"#{where_conditions}"|),
+            :"target-org" => target_org,
+          }
+          action = __method__.to_s.tr('_', ' ')
+          json = exec(action, flags: flags, redirection: :null_stderr)
+
+          result = json['result']
+          result.delete 'attributes'
+
+          model_class ? model_class.new(**result) : result
+        end
+
+        # update a object record. (eqivalent to *sf* *data* *update* *record*)
+        #
+        # *object_type* --- \Object Type (ex. Account)<br>
+        # *record_id* --- id of the object<br>
+        # *where* --- field values that is used to identify a record<br>
+        # *values* --- field values for update<br>
+        # *target_org* --- an alias of paticular org, not default one<br>
+        #
+        # ==== examples
+        #   sf.data.update_record :Account, record_id: 'xxxxxxx', values: {Name: 'New Account Name'}
+        #   sf.data.update_record :Hoge__c, where: {Name: 'Jonny B.Good', Country: 'USA'}, values: {Phone: 'xxxxx', bar: 2000}
+        #
+        # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_update_record_unified]
+        #
+        def update_record(object_type, record_id: nil, where: nil, values: nil, target_org: nil)
+          where_conditions  = field_value_pairs(where)
+          field_values      = field_value_pairs(values)
+          flags = {
+            :"sobject"    => object_type,
+            :"record-id"  => record_id,
+            :"where"      => (where_conditions.nil? ? nil : %|"#{where_conditions}"|),
+            :"values"     => (field_values.nil? ? nil : %|"#{field_values}"|),
+            :"target-org" => target_org,
+          }
+          action = __method__.to_s.tr('_', ' ')
+          json = exec(action, flags: flags, redirection: :null_stderr)
+
+          json['result']['id']
+        end
+
+        # create a object record. (eqivalent to *sf* *data* *create* *record*)
+        #
+        # *object_type* --- \Object Type (ex. Account)<br>
+        # *values* --- field values to be assigned<br>
+        # *target_org* --- an alias of paticular org, not default one<br>
+        #
+        # ==== examples
+        #
+        #   sf.data.create_record :TheCustomObject__c, values: {Name: "John Smith", Age: 33} # creating a TheCustomObject record with name and age
+        #
+        # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_create_record_unified]
+        #
+        def create_record(object_type, values: {}, target_org: nil)
+          field_values = field_value_pairs(values)
+          flags = {
+            :"sobject"    => object_type,
+            :"values"      => (field_values.nil? ? nil : %|"#{field_values}"|),
+            :"target-org" => target_org,
+          }
+          action = __method__.to_s.tr('_', ' ')
+          json = exec(action, flags: flags, redirection: :null_stderr)
+
+          json['result']['id']
+        end
+
+        # delete a object record. (eqivalent to *sf* *data* *delete* *record*)
+        #
+        # *object_type* --- \Object Type (ex. Account)<br>
+        # *record_id* --- id of the object<br>
+        # *where* --- hash object that is used to identify a record<br>
+        # *target_org* --- an alias of paticular org, not default one<br>
+        #
+        # ==== examples
+        #   sf.data.delete_record :Hoge__c, record_id: 'xxxxxxx'
+        #   sf.data.delete_record :Hoge__c, where: {Name: 'Jonny B.Good', Country: 'USA'}
+        #
+        # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_delete_record_unified]
+        #
+        def delete_record(object_type, record_id: nil, where: nil, target_org: nil)
+          where_conditions = field_value_pairs(where)
+          flags = {
+            :"sobject"    => object_type,
+            :"record-id"  => record_id,
+            :"where"      => (where_conditions.nil? ? nil : %|"#{where_conditions}"|),
+            :"target-org" => target_org,
+          }
+          action = __method__.to_s.tr('_', ' ')
+          json = exec(action, flags: flags, redirection: :null_stderr)
+
+          json['result']['id']
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/data/helper_methods.rb

@@ -0,0 +1,35 @@
+module SfCli
+  module Sf
+    module Data
+      module HelperMethods
+        def prepare_record(hash) # :doc:
+          hash.delete 'attributes'
+
+          hash.keys.each do |k|
+            if parent?(hash[k])
+              hash[k] = prepare_record(hash[k])
+            elsif children?(hash[k])
+              hash[k] = hash[k]['records'].map{|h| prepare_record(h)}
+            end
+          end
+
+          hash
+        end
+
+        def children?(h)
+          return false unless h.instance_of?(Hash)
+
+          h.has_key? 'records'
+        end
+
+        def parent?(h)
+          return false unless h.instance_of?(Hash)
+
+          h.has_key?('records') == false
+        end
+
+        private :prepare_record, :children?, :parent?
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/main.rb

@@ -0,0 +1,31 @@
+require 'singleton'
+require 'json'
+
+module SfCli
+  module Sf
+    # ==== description
+    # The entry class of sf command. It is returned by sf method.
+    # With including Singleton module, the instance of this class is guaranteed as singleton.
+    #
+    # ==== examples
+    #   sf             # returns a instance of SfCli::Sf
+    #   sf.org.display # you can follow the similar syntax to the original command by using method chain.
+    #
+    class Main
+      include Singleton
+
+      OPERATION_CATEGORIES = %w[Org Sobject Data Project]
+
+      OPERATION_CATEGORIES.each do |category|
+        require_relative %(#{category.downcase}/core)
+        attr_reader category.downcase.to_sym
+      end
+
+      def initialize
+        OPERATION_CATEGORIES.each do |category|
+          instance_variable_set(:"@#{category.downcase}", Object.const_get(%|::SfCli::Sf::#{category}::Core|).new)
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/model/class_definition.rb

@@ -0,0 +1,112 @@
+require_relative './schema'
+
+module SfCli
+  module Sf
+    module Model
+      class ClassDefinition
+        attr_reader :schema
+
+        def initialize(schema)
+          @schema = Schema.new(schema)
+        end
+
+        def to_s
+          <<~Klass
+            Class.new do
+              #{ class_methods }
+
+              field_names.each do |name|
+                attr_accessor name
+              end
+
+              #{ parent_relation_methods }
+              #{ children_relation_methods }
+
+              #{ define_initialize }
+
+              #{ define_to_h }
+            end
+          Klass
+        end
+
+        def define_initialize
+          <<~EOS
+            def initialize(attributes = {})
+              attributes.each do |k, v|
+                field_name = k.to_sym
+                if self.class.field_names.include?(field_name)
+                  #instance_variable_set ('@' + field_name.to_s).to_sym, v
+                  __send__ (field_name.to_s + '='), v
+                elsif self.class.parent_relations.find{|r| r[:name] == field_name}
+                  __send__ (field_name.to_s + '='), v
+                elsif self.class.children_relations.find{|r| r[:name] == field_name}
+                  __send__ (field_name.to_s + '='), (v.nil? ? [] : v)
+                end
+              end
+            end
+          EOS
+        end
+
+        def define_to_h
+          <<~EOS
+            def to_h(keys: nil)
+              self.class.field_names.each_with_object({}) do |name, hash|
+                if keys&.instance_of?(Array)
+                  hash[name] = __send__(name) if keys.include?(name)
+                else
+                  hash[name] = __send__(name)
+                end
+              end
+            end
+          EOS
+        end
+
+        def class_methods
+          <<~EOS
+            class << self
+              def field_names
+                @field_names ||= #{ schema.field_names }
+              end
+
+              def parent_relations
+                @parent_relations ||= #{ schema.parent_relations }
+              end
+
+              def children_relations
+                @children_relations ||= #{ schema.children_relations }
+              end
+            end
+          EOS
+        end
+
+        def parent_relation_methods
+          schema.parent_relations.each_with_object('') do |r, s|
+            s << <<~EOS
+              def #{r[:name]}
+                @#{r[:name]}
+              end
+
+              def #{r[:name]}=(attributes)
+                @#{r[:name]} = #{r[:class_name]}.new(attributes)
+              end
+            EOS
+          end
+        end
+
+        def children_relation_methods
+          schema.children_relations.each_with_object('') do |r, s|
+            s << <<~EOS
+              def #{r[:name]}
+                @#{r[:name]}
+              end
+
+              def #{r[:name]}=(records)
+                @#{r[:name]} = records.map{|attributes| #{r[:class_name]}.new(attributes)}
+              end
+            EOS
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/model/generator.rb

@@ -0,0 +1,27 @@
+require_relative '../sobject/core'
+require_relative './class_definition'
+
+module SfCli
+  module Sf
+    module Model
+      class Generator
+        attr_reader :sf_sobject, :target_org
+
+        def initialize(target_org: nil)
+          @sf_sobject = ::SfCli::Sf::Sobject::Core.new
+          @target_org = target_org
+        end
+
+        def generate(object_name)
+          class_definition = ClassDefinition.new(describe object_name)
+
+          instance_eval "::#{object_name} = #{class_definition}"
+        end
+
+        def describe(object_name)
+          sf_sobject.describe object_name, target_org: target_org
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/model/schema.rb

@@ -0,0 +1,33 @@
+module SfCli
+  module Sf
+    module Model
+      class Schema
+        attr_reader :schema
+
+        def initialize(schema)
+          @schema = schema
+        end
+
+        def name
+          schema['name']
+        end
+
+        def field_names
+          schema['fields'].map{|f| f['name'].to_sym}
+        end
+
+        def children_relations
+          schema['childRelationships']
+            .select{|r| r['relationshipName'].nil? == false}
+            .map{|r| {name: r['relationshipName'].to_sym, class_name: r['childSObject'].to_sym}}
+        end
+
+        def parent_relations
+          schema['fields']
+            .select{|f| f['relationshipName'].nil? == false && f['referenceTo']&.size > 0}
+            .map{|f| {name: f['relationshipName'].to_sym, class_name: f['referenceTo'].first.to_sym}}
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/model.rb

@@ -0,0 +1,21 @@
+require_relative 'model/generator'
+
+module SfCli
+  module Sf
+    #
+    # ==== description
+    # The module for \Object \Model definition and generation
+    #
+    # see the section {"Object Model support"}[link://files/README_rdoc.html#label-Object+Model+support+-28experimental-2C+since+0.0.4-29] in README.
+    #
+    module Model
+      def self.generate(object_names, target_org: nil)
+        generator = Generator.new(target_org: target_org)
+
+        object_names.each do |object_name|
+          generator.generate(object_name)
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/org/core.rb

@@ -0,0 +1,61 @@
+require_relative '../core/base'
+
+module SfCli
+  module Sf
+    module Org
+      #
+      # ==== description
+      # The class representing *sf* *org*.
+      #
+      # https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_org_commands_unified.htm
+      #
+      class Core
+        include ::SfCli::Sf::Core::Base
+
+        ConnectionInfo = Struct.new(:id, :access_token, :alias, :instance_url, :user_name, :api_version, :status)
+
+        # login to the org by the browser. (equivalent to *sf* *org* *login* *web*)
+        #
+        # *target_org* --- an alias of paticular org, not default one<br>
+        # *instance_url* --- custom login url.
+        #
+        # == examples:
+        #   sf.org.login_web
+        #   sf.org.login_web target_org: :dev  # if the org you login isn't the default one, you should give it alias name for later use.
+        #
+        # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_org_commands_unified.htm#cli_reference_org_login_web_unified]
+        #
+        def login_web(target_org: nil, instance_url: nil)
+          flags    = {
+            :"alias"        => target_org,
+            :"instance-url" => instance_url,
+          }
+          action = __method__.to_s.tr('_', ' ')
+          exec(action, flags: flags)
+        end
+
+        #
+        # returns the org's connection information. (equivalent to *sf* *org* *display*)
+        #
+        # *target_org* --- an alias of paticular org, not default one<br>
+        #
+        # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_org_commands_unified.htm#cli_reference_org_display_unified]
+        #
+        def display(target_org: nil)
+          flags    = {:"target-org" => target_org}
+          json = exec(__method__, flags: flags, redirection: :null_stderr)
+
+          ConnectionInfo.new(
+            id:           json['result']['id'],
+            access_token: json['result']['accessToken'],
+            alias:        json['result']['alias'],
+            instance_url: json['result']['instanceUrl'],
+            user_name:    json['result']['username'],
+            api_version:  json['result']['apiVersion'],
+            status:       json['result']['connectedStatus']
+          )
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/project/core.rb

@@ -0,0 +1,76 @@
+require_relative '../core/base'
+
+module SfCli
+  module Sf
+    module Project
+      # ==== description
+      # The class representing *sf* *project*
+      #
+      # command reference: https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_project_commands_unified.htm
+      #
+      class Core
+        include ::SfCli::Sf::Core::Base
+
+        GenerateResult = Struct.new(:output_dir, :files, :raw_output, :warnings)
+
+        #
+        # generate a Salesforce project. (equivalent to *sf* *project* *generate*)
+        #
+        # *name*        --- project name<br>
+        # *template*    --- project template name<br>
+        # *output_dir*  --- output directory<br>
+        # *manifest*    --- switch to create manifest file in the project directory (manifest/package.xml). default: false
+        #
+        # For more command details, see the {reference document}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_project_commands_unified.htm#cli_reference_project_generate_unified]
+        #
+        def generate(name, manifest: false, template: nil, output_dir: nil)
+          flags    = {
+            :name         => name,
+            :template     => template,
+            :"output-dir" => output_dir,
+          }
+          switches = {
+            manifest: manifest,
+          }
+          json = exec(__method__, flags: flags, switches: switches, redirection: :null_stderr)
+
+          GenerateResult.new(
+            output_dir: json['result']['outputDir'],
+            files:      json['result']['created'],
+            raw_output: json['result']['rawOutput'],
+            warnings:   json['warnings']
+          )
+        end
+
+        # generate the manifest file of a Salesforce project. (equivalent to *sf* *project* *generate* *manifest*)
+        #
+        # *metadata*    --- an array that consists of metadata type like CustomObject, Layout and so on.  (default: [])<br>
+        # *api_verson*  --- api version (default: nil)<br>
+        # *output_dir*  --- manifest's output directory in the project directory. You can use relative path from the project root (default: nil)<br>
+        # *from_org*    --- username or alias of the org that contains the metadata components from which to build a manifest (default: nil)<br>
+        # *source_dir*  --- paths to the local source files to include in the manifest (default: nil)
+        #
+        # == examples
+        #  sf.project.generate_manifest metadata: %w[CustomObject Layout]  # creates a package.xml, which is initialized with CustomObject and Layout
+        #  sf.project.generate_manifest from_org: <org_name>               # creates a package.xml, which is initialized with all metadata types in the org
+        #
+        # For more command details, see the {reference document}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_project_commands_unified.htm#cli_reference_project_generate_manifest_unified]
+        #
+        def generate_manifest(name: nil, output_dir: nil, api_version: nil, metadata: [], from_org: nil, source_dir: nil)
+          flags    = {
+            :name           => name,
+            :"metadata"     => (metadata.empty? ? nil : metadata.join(' ')),
+            :"from-org"     => from_org,
+            :"source-dir"   => source_dir,
+            :"output-dir"   => output_dir,
+            :"api-version"  => api_version,
+          }
+          action = __method__.to_s.tr('_', ' ')
+          json = exec(action, flags: flags, redirection: :null_stderr)
+
+          json['result']['path']
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/sobject/core.rb

@@ -0,0 +1,48 @@
+require_relative '../core/base'
+
+module SfCli
+  module Sf
+    module Sobject
+      # ==== description
+      # The class representing *sf* *sobject*
+      #
+      # command reference: https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_sobject_commands_unified.htm
+      #
+      class Core
+        include ::SfCli::Sf::Core::Base
+
+        # returns a hash object containing the Salesforce object schema. (equivalent to *sf* *sobject* *describe*)
+        #
+        # *objectType* --- object type (ex: Account)<br>
+        # *target_org* --- an alias of paticular org, not default one<br>
+        #
+        # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_sobject_commands_unified.htm#cli_reference_sobject_describe_unified]
+        #
+        def describe(object_type, target_org: nil)
+          flags    = {
+            :"sobject"    => object_type,
+            :"target-org" => target_org,
+          }
+          json = exec(__method__, flags: flags, redirection: :null_stderr)
+          json['result']
+        end
+
+        # returns a list of Salesforce object API name. (equivalent to *sf* *sobject* *list*)
+        #
+        # *object_type* --- all or custom<br>
+        # *target_org* --- an alias of paticular org, not default one<br>
+        #
+        # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_sobject_commands_unified.htm#cli_reference_sobject_list_unified]
+        #
+        def list(object_type, target_org: nil)
+          flags    = {
+            :"sobject"    => (object_type.to_sym == :custom ? :custom : :all),
+            :"target-org" => target_org,
+          }
+          json = exec(__method__, flags: flags, redirection: :null_stderr)
+          json['result']
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli.rb

@@ -1 +1,16 @@
-require 'sf_cli/sf'
+require 'sf_cli/sf/main'
+#
+# the global method that represents *sf* command.
+# This is desgined as the syntax suger, which can use with similar usability to the original.
+#
+# For command details, see the {reference document}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_unified.htm]
+#
+# == examples
+#   # you can follow the similar syntax to the original command by using method chain.
+#
+#   sf.org.display                            # same as original command 'sf org display'
+#   sf.data.query "SELECT Name FROM Account"  # same as original command 'sf data query "SELECT Name FROM Account"`
+#
+def sf
+  SfCli::Sf::Main.instance
+end

metadata

@@ -1,35 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: sf_cli
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - Takanobu Maekawa
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-08-17 00:00:00.000000000 Z
+date: 2024-09-01 00:00:00.000000000 Z
 dependencies: []
-description: A thin wrapper classes representing salesforce CLI. Currenty only sf
-  command is implemented, but not all functions are supported.
+description: This is a class library for introducing Salesforce CLI to Ruby scripting.
+  Currenty only sf command is the target of development.
 email: 
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.rdoc
+- CHANGELOG.md
 files:
+- CHANGELOG.md
+- README.rdoc
 - lib/sf_cli.rb
-- lib/sf_cli/helper_methods.rb
-- lib/sf_cli/sf.rb
-- lib/sf_cli/sf/base.rb
-- lib/sf_cli/sf/data.rb
-- lib/sf_cli/sf/operations.rb
-- lib/sf_cli/sf/org.rb
-- lib/sf_cli/sf/project.rb
-- lib/sf_cli/sf/sobject.rb
+- lib/sf_cli/sf/core/base.rb
+- lib/sf_cli/sf/data/core.rb
+- lib/sf_cli/sf/data/helper_methods.rb
+- lib/sf_cli/sf/main.rb
+- lib/sf_cli/sf/model.rb
+- lib/sf_cli/sf/model/class_definition.rb
+- lib/sf_cli/sf/model/generator.rb
+- lib/sf_cli/sf/model/schema.rb
+- lib/sf_cli/sf/org/core.rb
+- lib/sf_cli/sf/project/core.rb
+- lib/sf_cli/sf/sobject/core.rb
 homepage: https://github.com/tmkw/sf_cli
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_url: https://github.com/tmkw/sf_cli
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -38,15 +46,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.3.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
-requirements: []
+requirements:
+- 'Salesforce CLI ( >= 2.54.0): https://developer.salesforce.com/tools/salesforcecli'
 rubygems_version: 3.5.11
 signing_key: 
 specification_version: 4
-summary: A wrapper class library for Salesforce CLI
+summary: A library for using Salesforce CLI in Ruby
 test_files: []

data/lib/sf_cli/helper_methods.rb

@@ -1,26 +0,0 @@
-module SfCli
-  module HelperMethods
-    def os
-      @os ||= ENV['OS']
-    end
-
-    def null_stderr_redirection
-      @null_stderr_redirection ||=
-        if os.nil? || os.eql?('Windows_NT')
-          '2>nul'
-        else
-          '2> dev/null'
-        end
-    end
-
-    def flag(name, arg = nil, use_argument: true, long_flag: true)
-      flag_indicator = long_flag ? '--' : '-'
-
-      if use_argument
-        arg ? %(#{flag_indicator}#{name} #{arg}) : ''
-      else
-        %(#{flag_indicator}#{name})
-      end
-    end
-  end
-end

data/lib/sf_cli/sf/base.rb

@@ -1,17 +0,0 @@
-require_relative '../helper_methods'
-
-module SfCli
-  class Sf
-    class Base
-      include ::SfCli::HelperMethods
-
-      attr_reader :target_org
-
-      # *target_org* --- an org alias name, which is used for sf command operations (default is nil). If it is nil, the command uses the default org.
-      #
-      def initialize(target_org = nil)
-        @target_org = target_org
-      end
-    end
-  end
-end

data/lib/sf_cli/sf/data.rb

@@ -1,38 +0,0 @@
-require 'json'
-require_relative './base'
-
-module SfCli
-  class Sf
-    #
-    # ==== description
-    # The class representing *sf* *data*
-    #
-    # https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm
-    #
-    class Data < Base
-
-      # get the object records. It's eqivalent to use *sf* *data* *query*
-      #
-      # *soql* --- SOQL
-      #
-      # *model_class* --- the data model class representing the record object.  
-      #
-      # ==== examples
-      #   sf.data.query('SELECT Id, Name From Account Limit 3') # returns an array of Hash object
-      #
-      #   Account = Struct.new(:Id, :Name)
-      #   sf.data.query('SELECT Id, Name From Account Limit 3', model_class: Account)  # returns an array of Account struct object
-      #
-      def query(soql, model_class: nil)
-        json = JSON.parse `sf data query --json --query "#{soql}" #{flag :"target-org", target_org} #{null_stderr_redirection}`
-        raise StandardError.new(%|sf data query: failed. (query: "#{soql}")|) if json['status'] != 0
-
-        json['result']['records'].each_with_object([]) do |h, a|
-          h.delete "attributes"
-          a << (model_class ? model_class.new(**h) : h)
-        end
-      end
-    end
-  end
-end
-

data/lib/sf_cli/sf/operations.rb

@@ -1,4 +0,0 @@
-require_relative './org'
-require_relative './data'
-require_relative './sobject'
-require_relative './project'

data/lib/sf_cli/sf/org.rb

@@ -1,56 +0,0 @@
-require_relative './base'
-
-module SfCli
-  class Sf
-    #
-    # ==== description
-    # The class representing *sf* *org*.
-    #
-    # https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_org_commands_unified.htm
-    #
-    class Org < Base
-      ConnectionInfo = Struct.new(:access_token, :alias, :instance_url, :api_version, :status)
-
-      # login to the org by the browser. It's equivalent to use *sf* *org* *login* *web*
-      #
-      # *instance_url* --- custom login url.
-      #
-      def login_web(instance_url: nil)
-        `sf org login web #{flag :alias, target_org} #{flag :"instance-url", instance_url}`
-      end
-
-      #
-      # returns the org's connection information. It's equivalent to use *sf* *org* *display*.
-      #
-      def display
-        lines = StringIO.new(`sf org display #{flag :"target-org", target_org} #{null_stderr_redirection}`).readlines
-
-        connection_info = ConnectionInfo.new(
-          access_token: nil,
-          alias:        nil,
-          instance_url: nil,
-          api_version:  nil,
-          status:       nil
-        )
-
-        lines.each do |line|
-          case line
-          when /Access Token/
-            connection_info.access_token = line.split(' ')[2]
-          when /Alias/
-            connection_info.alias = line.split(' ')[1]
-          when /Instance Url/
-            connection_info.instance_url = line.split(' ')[2]
-          when /Api Version/
-            connection_info.api_version = line.split(' ')[2]
-          when /Connected Status/
-            connection_info.status = line.split(' ')[2]
-          end
-        end
-
-        connection_info
-      end
-    end
-  end
-end
-

data/lib/sf_cli/sf/project.rb

@@ -1,74 +0,0 @@
-require 'pathname'
-require_relative './base'
-
-module SfCli
-  class Sf
-    # ==== description
-    # The class representing *sf* *project*
-    #
-    # command reference: https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_project_commands_unified.htm
-    #
-    class Project < Base
-
-      #
-      # generate a Salesforce project. It's equivalent to *sf* *project* *generate*.
-      #
-      # *name*        --- project name
-      #
-      # *template*    --- project template name
-      #
-      # *output_dir*  --- output directory
-      #
-      def generate(name, template: 'standard', output_dir: nil)
-        `sf project generate #{flag :name, name} #{flag :template, template} #{flag :"output-dir", output_dir} --manifest #{null_stderr_redirection}`
-        raise StandardError.new(%|command 'sf project generate' failed.|) unless $?.success?
-      end
-
-      # generate the manifest file of a Salesforce project.  It's equivalent to *sf* *project* *generate* *manifest*
-      #
-      # *metadata*    --- an array that consists of metadata type like CustomObject, Layout and so on.  (default: [])
-      # 
-      # *api_verson*  --- api version (default: nil)
-      # 
-      # *project_dir* --- project directory which you want to create the manifest  (default: nil)
-      # 
-      # *output_dir*  --- manifest's output directory in the project directory. You can use relative path from the project root (default: nil)
-      # 
-      # *from_org*    --- username or alias of the org that contains the metadata components from which to build a manifest (default: nil)
-      # 
-      # *source_dir*  --- paths to the local source files to include in the manifest (default: nil)
-      #
-      # ==== examples
-      #   sf.project.generate_manifest metadata: %w[CustomObject Layout]  # creates a package.xml, which is initialized with CustomObject and Layout
-      #   sf.project.generate_manifest from_org: <org_name>               # creates a package.xml, which is initialized with all metadata types in the org
-      #
-      def generate_manifest(metadata: [], api_version: nil, project_dir: nil, output_dir: nil, from_org: nil, source_dir: nil)
-        raise StandardError.new('Exactly one of the following must be provided: --from-org, --metadata, --source-dir') if metadata.empty? && from_org.nil? && source_dir.nil?
-        base_dir = Dir.pwd
-
-        if project_dir
-          raise StandardError.new('the project directory not found') unless FileTest.exist?(project_dir) && FileTest.directory?(project_dir)
-          Dir.chdir project_dir
-        end
-
-        Dir.mkdir(output_dir) if output_dir && FileTest.exist?(output_dir) == false
-
-        metdata_flags = metadata.empty? ? '' : metadata.map{|md| %|--metadata #{md}|}.join(' ')
-        cmd =
-          %|sf project generate manifest %{metdata} %{output_dir} %{api_version} %{from_org} %{source_dir}| %
-            {
-              metdata: metdata_flags,
-              output_dir:   flag(:"output-dir", output_dir),
-              api_version:  flag(:"api-version", api_version),
-              from_org:     flag(:"from-org", from_org),
-              source_dir:   flag(:"source-dir", source_dir),
-            }
-        `#{cmd} #{null_stderr_redirection}`
-
-        raise StandardError.new(%|command 'sf project generate manifest' failed.|) unless $?.success?
-      ensure 
-        Dir.chdir base_dir
-      end
-    end
-  end
-end

data/lib/sf_cli/sf/sobject.rb

@@ -1,36 +0,0 @@
-require 'json'
-require_relative './base'
-
-module SfCli
-  class Sf
-    # ==== description
-    # The class representing *sf* *sobject*
-    #
-    # command reference: https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_sobject_commands_unified.htm
-    #
-    class SObject < Base
-
-      # get the schema information of a Salesforce object and returns a hash object. It's equivalent to use *sf* *sobject* *describe*
-      #
-      # *objectType* --- object type (ex: Account)
-      #
-      def describe(objectType)
-        json = JSON.parse `sf sobject describe --json --sobject #{objectType} #{flag :"target-org", target_org}  #{null_stderr_redirection}`
-        raise StandardError.new(%|sf sobject describe: failed. (sobject: #{objectType})|) if json['status'] != 0
-
-        json['result']
-      end
-
-      # returns a list of Salesforce object name (object's API name). It's equivalent to *sf* *sobject* *list*
-      #
-      # *object_type* --- all or custom (default: all)
-      #
-      def list(object_type: 'all')
-        json = JSON.parse `sf sobject list --json --sobject #{object_type} #{flag :"target-org", target_org} #{null_stderr_redirection}`
-        raise StandardError.new(%|sf sobject list: failed.|) if json['status'] != 0
-
-        json['result']
-      end
-    end
-  end
-end

data/lib/sf_cli/sf.rb

@@ -1,33 +0,0 @@
-require_relative './sf/operations'
-
-module SfCli
-  # ==== description
-  # The main object class of *sf* command.
-  #
-  #
-  # https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_unified.htm
-  #
-  # ==== examples
-  #  sf = SfCli::Sf.new                     # use default org
-  #  sf = SfCli::Sf.new target_org: 'hoge'  # use an alias "hoge" as target org
-  #
-  #  # get the org connection infomation, which is equivalent to the result of 'sf org display'
-  #  sf.org.display 
-  #
-  #  # get Account records (equivalent to 'sf data query')
-  #  sf.data.query 'SELECT Id, Name FROM Account LIMIT 3' # => returns an array containing 3 records
-  #
-  class Sf
-    attr_reader :target_org, :org, :data, :sobject, :project
-
-    #
-    # *\target_org* --- an org alias name, which is used for sf command operations (default is nil). If it is nil, the command uses the default org.
-    #
-    def initialize(target_org: nil)
-      @org = Org.new(target_org)
-      @data = Data.new(target_org)
-      @sobject = SObject.new(target_org)
-      @project = Project.new
-    end
-  end
-end