feat: run:function:start defaults to local mode (#343)

* feat: run:function:start now defaults to local

It is now an alias to run:function:start:local rather than
run:function:start:container.

* feat: hide deprecated/ignored arguments

* feat: add deprecation warnings for deprecated flags

* chore: test deprecation notices

* chore: fix deprecation note for --env

* chore: reuse local code from start

* chore: update snapshot with new argument

Author: joshwlewis

command-snapshot.json

@@ -114,6 +114,7 @@
       "debug-port",
       "descriptor",
       "env",
+      "language",
       "network",
       "no-build",
       "no-pull",

messages/run.function.start.md

@@ -6,4 +6,58 @@ Build and run a Salesforce Function.
 
 Run this command from the directory of your Salesforce Functions project.
 
-This command will run the target function in a container. In the future, this command will run the target function on the host operating system (locally) instead. If one mode is preferred over the other, consider using the `container` or `local` subcommand instead.
+This command will run the target function locally (on the same operating system as this CLI), just like the `local` subcommand.
+
+Previously, this command ran functions in a container. Container mode is still supported via the `container` subcommand. Arguments relevant to container mode are still accepted, but are deprecated, ignored, and will be dropped in a future release.
+
+# flags.language.summary
+
+The language that the function runs in.
+
+# flags.path.summary
+
+Path to function directory.
+
+# flags.port.summary
+
+Port for running the function.
+
+# flags.debug-port.summary
+
+Port for remote debugging.
+
+# flags.verbose.summary
+
+Output additional logs.
+
+# flags.builder.deprecation
+
+--builder is deprecated and will be removed in a future release. Please discontinue use of this flag or use the `container` subcommand instead.
+
+# flags.clear-cache.deprecation
+
+--clear-cache is deprecated and will be removed in a future release. Please discontinue use of this flag or use the `container` subcommand instead.
+
+# flags.descriptor.deprecation
+
+--descriptor is deprecated and will be removed in a future release. Please discontinue use of this flag or use the `container` subcommand instead.
+
+# flags.env.deprecation
+
+--env is deprecated and will be removed in a future release. Please discontinue use of this flag or use the `container` subcommand instead.
+
+# flags.network.deprecation
+
+--network is deprecated and will be removed in a future release. Please discontinue use of this flag or use the `container` subcommand instead.
+
+# flags.no-build.deprecation
+
+--no-build is deprecated and will be removed in a future release. Please discontinue use of this flag or use the `container` subcommand instead.
+
+# flags.no-pull.deprecation
+
+--no-pull is deprecated and will be removed in a future release. Please discontinue use of this flag or use the `container` subcommand instead.
+
+# flags.no-run.deprecation
+
+--no-run is deprecated and will be removed in a future release. Please discontinue use of this flag or use the `container` subcommand instead.

src/commands/run/function/start.ts

@@ -5,14 +5,91 @@
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 
+import * as path from 'path';
 import { Messages } from '@salesforce/core';
-import Container from './start/container';
+import { Flags } from '@oclif/core';
+import { LocalRun } from '@heroku/functions-core';
+
+import Local from './start/local';
 
 Messages.importMessagesDirectory(__dirname);
 const messages = Messages.loadMessages('@salesforce/plugin-functions', 'run.function.start');
 
-// run:function:start is an alias to run:function:start:container
-export default class Start extends Container {
+// run:function:start is an alias command to run:function:start:local.
+// run:function:start previously ran via container mode, so it still accepts
+// arguments applicable to the container subcommand, but ignores them and flags
+// them as deprecated. The additional flags may be removed after 04/30/2022.
+export default class Start extends Local {
   static summary = messages.getMessage('summary');
+
   static description = messages.getMessage('description');
+
+  static flags = {
+    builder: Flags.string({
+      hidden: true,
+    }),
+    'clear-cache': Flags.boolean({
+      hidden: true,
+    }),
+    'debug-port': Flags.integer({
+      char: 'b',
+      description: messages.getMessage('flags.debug-port.summary'),
+      default: 9229,
+    }),
+    descriptor: Flags.string({
+      hidden: true,
+    }),
+    env: Flags.string({
+      char: 'e',
+      multiple: true,
+      hidden: true,
+    }),
+    language: Flags.enum({
+      options: ['javascript', 'typescript', 'java', 'auto'],
+      char: 'l',
+      default: 'auto',
+    }),
+    network: Flags.string({
+      hidden: true,
+    }),
+    'no-build': Flags.boolean({
+      hidden: true,
+    }),
+    'no-pull': Flags.boolean({
+      hidden: true,
+    }),
+    'no-run': Flags.boolean({
+      hidden: true,
+    }),
+    path: Flags.string({
+      description: messages.getMessage('flags.path.summary'),
+      default: path.resolve('.'),
+      hidden: true,
+    }),
+    port: Flags.integer({
+      char: 'p',
+      description: messages.getMessage('flags.port.summary'),
+      default: 8080,
+    }),
+    verbose: Flags.boolean({
+      char: 'v',
+      description: messages.getMessage('flags.verbose.summary'),
+    }),
+  };
+
+  async run() {
+    const { flags } = await this.parse(Start);
+    Object.entries(flags).forEach(([flag, val]) => {
+      let msg: string | null = null;
+      try {
+        msg = messages.getMessage(`flags.${flag}.deprecation`);
+        if (val) {
+          this.warn(msg);
+        }
+      } catch {
+        // No deprecation message, flag is not deprecated
+      }
+    });
+    await this.runWithFlags(flags);
+  }
 }

src/commands/run/function/start/local.ts

@@ -43,6 +43,12 @@ export default class Local extends Command {
 
   async run() {
     const { flags } = await this.parse(Local);
+    await this.runWithFlags(flags);
+  }
+
+  async runWithFlags(
+    flags: { path: string; port: number; 'debug-port': number; language: string } & { json: boolean | undefined }
+  ) {
     const localRun = new LocalRun(flags.language, {
       path: flags.path,
       port: flags.port,

test/commands/run/function/start.test.ts

@@ -4,33 +4,46 @@
  * Licensed under the BSD 3-Clause license.
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
-import { test } from '@oclif/test';
+import { expect, test } from '@oclif/test';
 import * as sinon from 'sinon';
+import { LocalRun } from '@heroku/functions-core';
 
-import * as library from '@heroku/functions-core';
-import { Benny } from '@heroku/functions-core';
-
-describe('function:start', () => {
+describe('run:function:start', () => {
   let sandbox: sinon.SinonSandbox;
-  let bennyRunStub: sinon.SinonStub;
-  let bennyBuildStub: sinon.SinonStub;
+  let localRunExecStub: sinon.SinonStub;
   beforeEach(() => {
     sandbox = sinon.createSandbox();
-    bennyRunStub = sandbox.stub(Benny.prototype, 'run');
-    bennyBuildStub = sandbox.stub(Benny.prototype, 'build');
-    bennyRunStub.returns(true);
-    bennyBuildStub.returns(true);
-    sandbox
-      .stub(library, 'getProjectDescriptor')
-      .returns(Promise.resolve({ com: { salesforce: { id: 'allthethingsfunction' } } }));
+    localRunExecStub = sandbox.stub(LocalRun.prototype, 'exec');
+    localRunExecStub.resolves();
   });
 
   afterEach(() => {
     sandbox.restore();
   });
 
-  test.command(['run:function:start']).it('Should call the library methods', async () => {
-    sinon.assert.calledOnce(bennyBuildStub);
-    sinon.assert.calledOnce(bennyRunStub);
+  test.command(['run:function:start']).it('Should call LocalRun.exec', async () => {
+    sinon.assert.calledOnce(localRunExecStub);
+  });
+
+  ['--builder', '--network', '--env'].forEach((deprecatedArg) => {
+    describe(`with deprecated arg ${deprecatedArg}`, () => {
+      test
+        .stderr()
+        .command(['run:function:start', deprecatedArg, 'some:val'])
+        .it('will include a deprecation notice', (ctx) => {
+          expect(ctx.stderr).to.contain(`${deprecatedArg} is deprecated`);
+        });
+    });
+  });
+
+  ['--no-pull', '--no-run', '--no-build'].forEach((deprecatedArg) => {
+    describe(`with deprecated flag ${deprecatedArg}`, () => {
+      test
+        .stderr()
+        .command(['run:function:start', deprecatedArg])
+        .it('will include a deprecation notice', (ctx) => {
+          expect(ctx.stderr).to.contain(`${deprecatedArg} is deprecated`);
+        });
+    });
   });
 });