Merge remote-tracking branch 'origin/master' into end_user_docs

Rakefile

@@ -19,11 +19,13 @@ namespace :rdoc do
   intermediate = 'markdown_intermediate'
   file_to_doc = [
     'lib/shopify-cli/admin_api.rb',
+    'lib/shopify-cli/context.rb',
     'lib/shopify-cli/db.rb',
     'lib/shopify-cli/git.rb',
     'lib/shopify-cli/heroku.rb',
     'lib/shopify-cli/partners_api.rb',
     'lib/shopify-cli/process_supervision.rb',
+    'lib/shopify-cli/project.rb',
     'lib/shopify-cli/tunnel.rb',
   ]
 

lib/docgen/index_template.md.erb

@@ -0,0 +1,5 @@
+The Shopify App CLI has a set of core APIs that simplify the process of extending its functionality.
+
+<%- classes.each do |method| -%>
+- [<%= method.title %>](https://github.com/Shopify/shopify-app-cli/wiki/<%= method.filename %>)
+<%- end -%>

lib/docgen/markdown.rb

@@ -8,7 +8,7 @@ class Markdown
 
       DocClass = Struct.new(
         :title, :kind, :comment, :class_methods, :instance_methods, :attributes,
-        :constants, :extended, :included,
+        :constants, :extended, :included, :filename,
         keyword_init: true,
       )
       ClassMember = Struct.new(:title, :comment, :signature, :source_code, keyword_init: true)
@@ -17,8 +17,6 @@ def initialize(store, options)
         @options = options
         @store = store
         @converter = ::RDoc::Markup::ToMarkdown.new
-        template_path = File.join(File.dirname(__FILE__), 'class_template.md.erb')
-        @renderer = ERB.new(File.read(template_path), nil, '-')
       end
 
       def generate
@@ -28,20 +26,24 @@ def generate
       private
 
       def render(data)
+        class_template_path = File.join(File.dirname(__FILE__), 'class_template.md.erb')
+        class_renderer = ERB.new(File.read(class_template_path), nil, '-')
         data.each do |cls|
-          File.write(
-            "#{cls.kind}-#{cls.title}.md",
-            @renderer.result(cls.instance_eval { binding }),
-          )
+          File.write("#{cls.filename}.md", class_renderer.result(cls.instance_eval { binding }))
         end
+        index_template_path = File.join(File.dirname(__FILE__), 'index_template.md.erb')
+        index_renderer = ERB.new(File.read(index_template_path), nil, '-')
+        File.write("Core-APIs.md", index_renderer.result(OpenStruct.new(classes: data).instance_eval { binding }))
       end
 
       def build_classes
         classes = @store.all_classes_and_modules.map do |klass|
           is_class = @store.all_modules.find { |m| m.full_name == klass.full_name }.nil?
+          kind = is_class ? :class : :module
           DocClass.new(
+            filename: "#{kind}-#{klass.full_name}",
             title: klass.full_name,
-            kind: is_class ? :class : :module,
+            kind: kind,
             comment: @converter.convert(klass.comment.parse),
             constants: build_members(klass.constants),
             class_methods: build_members(klass.method_list.select { |m| m.type == 'class' }),

lib/project_types/node/commands/create.rb

@@ -11,7 +11,9 @@ class Create < ShopifyCli::SubCommand
       NPM_REQUIRED_NOTICE = "node is required to create an app project. Download at https://www.npmjs.com/get-npm."
 
       options do |parser, flags|
+        # backwards compatibility allow 'title' for now
         parser.on('--title=TITLE') { |t| flags[:title] = t }
+        parser.on('--name=NAME') { |t| flags[:title] = t }
         parser.on('--organization_id=ID') { |url| flags[:organization_id] = url }
         parser.on('--shop_domain=MYSHOPIFYDOMAIN') { |url| flags[:shop_domain] = url }
         parser.on('--type=APPTYPE') { |url| flags[:type] = url }
@@ -57,9 +59,9 @@ def self.help
         {{command:#{ShopifyCli::TOOL_NAME} create node}}: Creates an embedded nodejs app.
           Usage: {{command:#{ShopifyCli::TOOL_NAME} create node}}
           Options:
-            {{command:--title=TITLE}} App project title. Any string.
-            {{command:--app_url=APPURL}} App project URL. Must be valid URL.
-            {{command:--organization_id=ID}} App project Org ID. Must be existing org ID.
+            {{command:--name=NAME}} App name. Any string.
+            {{command:--app_url=APPURL}} App URL. Must be valid URL.
+            {{command:--organization_id=ID}} App Org ID. Must be existing org ID.
             {{command:--shop_domain=MYSHOPIFYDOMAIN }} Test store URL. Must be existing test store.
         HELP
       end
@@ -91,12 +93,12 @@ def build(name)
         JsDeps.install(@ctx)
 
         begin
-          @ctx.rm_r(File.join(@ctx.root, '.git'))
-          @ctx.rm_r(File.join(@ctx.root, '.github'))
-          @ctx.rm(File.join(@ctx.root, 'server', 'handlers', 'client.js'))
+          @ctx.rm_r('.git')
+          @ctx.rm_r('.github')
+          @ctx.rm(File.join('server', 'handlers', 'client.js'))
           @ctx.rename(
-            File.join(@ctx.root, 'server', 'handlers', 'client.cli.js'),
-            File.join(@ctx.root, 'server', 'handlers', 'client.js')
+            File.join('server', 'handlers', 'client.cli.js'),
+            File.join('server', 'handlers', 'client.js')
           )
         rescue Errno::ENOENT => e
           @ctx.debug(e)

lib/project_types/node/commands/deploy.rb

@@ -13,14 +13,14 @@ def call(*)
       def self.help
         <<~HELP
           Deploy the current Node project to a hosting service. Heroku ({{underline:https://www.heroku.com}}) is currently the only option, but more will be added in the future.
-            Usage: {{command:#{ShopifyCli::TOOL_NAME} deploy [heroku]}}
+            Usage: {{command:#{ShopifyCli::TOOL_NAME} deploy [ heroku ]}}
         HELP
       end
 
       def self.extended_help
         <<~HELP
-          Subcommands:
-          * heroku: Deploys the current Rails project to Heroku.
+        {{bold:Subcommands:}}
+          {{cyan:heroku}}: Deploys the current Node project to Heroku.
             Usage: {{command:#{ShopifyCli::TOOL_NAME} deploy heroku}}
         HELP
       end

lib/project_types/node/commands/deploy/heroku.rb

@@ -14,7 +14,6 @@ def self.help
 
         def call(_args, _name)
           spin_group = CLI::UI::SpinGroup.new
-          git_service = ShopifyCli::Git.new(@ctx)
           heroku_service = ShopifyCli::Heroku.new(@ctx)
 
           spin_group.add('Downloading Heroku CLI…') do |spinner|
@@ -28,23 +27,21 @@ def call(_args, _name)
             spinner.update_title('Installed Heroku CLI')
           end
           spin_group.add('Checking git repo…') do |spinner|
-            git_service.init
+            ShopifyCli::Git.init(@ctx)
             spinner.update_title('Git repo initialized')
           end
           spin_group.wait
 
           if (account = heroku_service.whoami)
-            spin_group.add("Authenticated with Heroku as `#{account}`") { true }
-            spin_group.wait
+            @ctx.puts("{{v}} Authenticated with Heroku as `#{account}`")
           else
             CLI::UI::Frame.open("Authenticating with Heroku…", success_text: '{{v}} Authenticated with Heroku') do
               heroku_service.authenticate
             end
           end
 
           if (app_name = heroku_service.app)
-            spin_group.add("Heroku app `#{app_name}` selected") { true }
-            spin_group.wait
+            @ctx.puts("{{v}} Heroku app `#{app_name}` selected")
           else
             app_type = CLI::UI::Prompt.ask('No existing Heroku app found. What would you like to do?') do |handler|
               handler.option('Create a new Heroku app') { :new }
@@ -66,11 +63,10 @@ def call(_args, _name)
             end
           end
 
-          branches = git_service.branches
+          branches = ShopifyCli::Git.branches(@ctx)
           if branches.length == 1
             branch_to_deploy = branches[0]
-            spin_group.add("Git branch `#{branch_to_deploy}` selected for deploy") { true }
-            spin_group.wait
+            @ctx.puts("{{v}} Git branch `#{branch_to_deploy}` selected for deploy")
           else
             branch_to_deploy = CLI::UI::Prompt.ask('What branch would you like to deploy?') do |handler|
               branches.each do |branch|

lib/project_types/node/commands/generate.rb

@@ -14,20 +14,26 @@ def call(*)
 
       def self.help
         <<~HELP
-          Generate code in your app project. Supports generating new pages, new billing API calls, or new webhooks.
-            Usage: {{command:#{ShopifyCli::TOOL_NAME} generate [ page | billing | webhook ]}}
+          Generate code in your Node project. Supports generating new billing API calls, new pages, or new webhooks.
+            Usage: {{command:#{ShopifyCli::TOOL_NAME} generate [ billing | page | webhook ]}}
         HELP
       end
 
       def self.extended_help
-        <<~HELP
-          {{bold:Subcommands:}}
-            {{cyan:webhook}}: Generate and register a new webhook that listens for the specified Shopify store event.
-              Usage: {{command:#{ShopifyCli::TOOL_NAME} generate webhook [type]}}
+        extended_help = "{{bold:Subcommands:}}\n"
+        subcommand_registry.resolved_commands.sort.each do |name, klass|
+          extended_help += "  {{cyan:#{name}}}: "
+
+          if (subcmd_help = klass.help)
+            extended_help += subcmd_help.gsub("\n  ", "\n    ")
+          end
+          extended_help += "\n"
+        end
+        extended_help += <<~EXAMPLES
           {{bold:Examples:}}
             {{cyan:#{ShopifyCli::TOOL_NAME} generate webhook PRODUCTS_CREATE}}
               Generate and register a new webhook that will be called every time a new product is created on your store.
-        HELP
+        EXAMPLES
       end
 
       def self.run_generate(script, name, ctx)

lib/project_types/node/commands/generate/billing.rb

@@ -33,7 +33,7 @@ def call(args, _name)
         def self.help
           <<~HELP
             Enable charging for your app. This command generates the necessary code to call Shopify’s billing API.
-              Usage: {{command:#{ShopifyCli::TOOL_NAME} generate billing recurring-billing | one-time-billing}}
+              Usage: {{command:#{ShopifyCli::TOOL_NAME} generate billing [ one-time-billing | recurring-billing ]}}
           HELP
         end
       end

lib/project_types/node/commands/populate.rb

@@ -3,34 +3,34 @@
 module Node
   module Commands
     class Populate < ShopifyCli::Command
-      subcommand :Product, 'products', Project.project_filepath('commands/populate/product')
       subcommand :Customer, 'customers', Project.project_filepath('commands/populate/customer')
       subcommand :DraftOrder, 'draftorders', Project.project_filepath('commands/populate/draft_order')
+      subcommand :Product, 'products', Project.project_filepath('commands/populate/product')
 
       def call(_args, _name)
         @ctx.puts(self.class.help)
       end
 
       def self.help
         <<~HELP
-          Populate your Shopify development store with example products, customers, or orders.
-            Usage: {{command:#{ShopifyCli::TOOL_NAME} populate [ products | customers | draftorders ]}}
+          Populate your Shopify development store with example customers, orders, or products.
+            Usage: {{command:#{ShopifyCli::TOOL_NAME} populate [ customers | draftorders | products ]}}
         HELP
       end
 
       def self.extended_help
         <<~HELP
           {{bold:Subcommands:}}
 
-            {{cyan:products [options]}}: Add dummy products to the specified development store.
-              Usage: {{command:#{ShopifyCli::TOOL_NAME} populate products}}
-
             {{cyan:customers [options]}}: Add dummy customers to the specified development store.
               Usage: {{command:#{ShopifyCli::TOOL_NAME} populate customers}}
 
             {{cyan:draftorders [options]}}: Add dummy orders to the specified development store.
               Usage: {{command:#{ShopifyCli::TOOL_NAME} populate draftorders}}
 
+            {{cyan:products [options]}}: Add dummy products to the specified development store.
+              Usage: {{command:#{ShopifyCli::TOOL_NAME} populate products}}
+
           {{bold:Options:}}
 
             {{cyan:--count [integer]}}: The number of dummy items to populate. Defaults to 5.

lib/project_types/node/commands/serve.rb

@@ -13,6 +13,7 @@ class Serve < ShopifyCli::Command
       def call(*)
         project = ShopifyCli::Project.current
         url = options.flags[:host] || ShopifyCli::Tunnel.start(@ctx)
+        @ctx.abort("{{red:HOST must be a HTTPS url.}}") if url.match(/^https/i).nil?
         project.env.update(@ctx, :host, url)
         ShopifyCli::Tasks::UpdateDashboardURLS.call(
           @ctx,
@@ -42,7 +43,7 @@ def self.help
       def self.extended_help
         <<~HELP
           {{bold:Options:}}
-            {{cyan:--host=HOST}}: Must be HTTPS url. Bypass running tunnel and use custom host.
+            {{cyan:--host=HOST}}: Bypass running tunnel and use custom host. HOST must be HTTPS url.
         HELP
       end
     end

lib/project_types/node/commands/tunnel.rb

@@ -12,7 +12,12 @@ def call(args, _name)
         case subcommand
         when 'auth'
           token = args.shift
-          ShopifyCli::Tunnel.auth(@ctx, token)
+          if token.nil?
+            @ctx.puts("{{x}} {{red:auth requires a token argument}}\n\n")
+            @ctx.puts("#{self.class.help}\n#{self.class.extended_help}")
+          else
+            ShopifyCli::Tunnel.auth(@ctx, token)
+          end
         when 'start'
           ShopifyCli::Tunnel.start(@ctx)
         when 'stop'
@@ -33,7 +38,7 @@ def self.extended_help
         <<~HELP
           {{bold:Subcommands:}}
 
-            {{cyan:auth}}: Writes an ngrok auth token to ~/.ngrok2/ngrok.yml to allow connecting with an ngrok account. Visit https://dashboard.ngrok.com/signup to sign up.
+            {{cyan:auth}}: Writes an ngrok auth token to ~/.ngrok2/ngrok.yml to connect with an ngrok account. Visit https://dashboard.ngrok.com/signup to sign up.
               Usage: {{command:#{ShopifyCli::TOOL_NAME} tunnel auth <token>}}
 
             {{cyan:start}}: Starts an ngrok tunnel, will print the URL for an existing tunnel if already running.

lib/project_types/rails/commands/create.rb

@@ -17,7 +17,9 @@ class Base < ActiveResource::Base
       MSG
 
       options do |parser, flags|
+        # backwards compatibility allow 'title' for now
         parser.on('--title=TITLE') { |t| flags[:title] = t }
+        parser.on('--name=NAME') { |t| flags[:title] = t }
         parser.on('--organization_id=ID') { |url| flags[:organization_id] = url }
         parser.on('--shop_domain=MYSHOPIFYDOMAIN') { |url| flags[:shop_domain] = url }
         parser.on('--type=APPTYPE') { |url| flags[:type] = url }
@@ -65,9 +67,9 @@ def self.help
         {{command:#{ShopifyCli::TOOL_NAME} create rails}}: Creates a ruby on rails app.
           Usage: {{command:#{ShopifyCli::TOOL_NAME} create rails}}
           Options:
-            {{command:--title=TITLE}} App project title. Any string.
-            {{command:--app_url=APPURL}} App project URL. Must be valid URL.
-            {{command:--organization_id=ID}} App project Org ID. Must be existing org ID.
+            {{command:--name=NAME}} App name. Any string.
+            {{command:--app_url=APPURL}} App URL. Must be valid URL.
+            {{command:--organization_id=ID}} App Org ID. Must be existing org ID.
             {{command:--shop_domain=MYSHOPIFYDOMAIN }} Test store URL. Must be existing test store.
         HELP
       end

lib/project_types/rails/commands/deploy.rb

@@ -13,14 +13,14 @@ def call(*)
       def self.help
         <<~HELP
           Deploy the current Rails project to a hosting service. Heroku ({{underline:https://www.heroku.com}}) is currently the only option, but more will be added in the future.
-            Usage: {{command:#{ShopifyCli::TOOL_NAME} deploy [heroku]}}
+            Usage: {{command:#{ShopifyCli::TOOL_NAME} deploy [ heroku ]}}
         HELP
       end
 
       def self.extended_help
         <<~HELP
-          Subcommands:
-          * heroku: Deploys the current Rails project to Heroku.
+        {{bold:Subcommands:}}
+          {{cyan:heroku}}: Deploys the current Rails project to Heroku.
             Usage: {{command:#{ShopifyCli::TOOL_NAME} deploy heroku}}
         HELP
       end

lib/project_types/rails/commands/deploy/heroku.rb

@@ -14,7 +14,6 @@ def self.help
 
         def call(_args, _name)
           spin_group = CLI::UI::SpinGroup.new
-          git_service = ShopifyCli::Git.new(@ctx)
           heroku_service = ShopifyCli::Heroku.new(@ctx)
 
           spin_group.add('Downloading Heroku CLI…') do |spinner|
@@ -28,23 +27,21 @@ def call(_args, _name)
             spinner.update_title('Installed Heroku CLI')
           end
           spin_group.add('Checking git repo…') do |spinner|
-            git_service.init
+            ShopifyCli::Git.init(@ctx)
             spinner.update_title('Git repo initialized')
           end
           spin_group.wait
 
           if (account = heroku_service.whoami)
-            spin_group.add("Authenticated with Heroku as `#{account}`") { true }
-            spin_group.wait
+            @ctx.puts("{{v}} Authenticated with Heroku as `#{account}`")
           else
             CLI::UI::Frame.open("Authenticating with Heroku…", success_text: '{{v}} Authenticated with Heroku') do
               heroku_service.authenticate
             end
           end
 
           if (app_name = heroku_service.app)
-            spin_group.add("Heroku app `#{app_name}` selected") { true }
-            spin_group.wait
+            @ctx.puts("{{v}} Heroku app `#{app_name}` selected")
           else
             app_type = CLI::UI::Prompt.ask('No existing Heroku app found. What would you like to do?') do |handler|
               handler.option('Create a new Heroku app') { :new }
@@ -66,11 +63,10 @@ def call(_args, _name)
             end
           end
 
-          branches = git_service.branches
+          branches = ShopifyCli::Git.branches(@ctx)
           if branches.length == 1
             branch_to_deploy = branches[0]
-            spin_group.add("Git branch `#{branch_to_deploy}` selected for deploy") { true }
-            spin_group.wait
+            @ctx.puts("{{v}} Git branch `#{branch_to_deploy}` selected for deploy")
           else
             branch_to_deploy = CLI::UI::Prompt.ask('What branch would you like to deploy?') do |handler|
               branches.each do |branch|