✨ Add hidden CLI app command for future SDKs

packages/cli-app/LICENSE

@@ -0,0 +1,18 @@
+Copyright © Perceptual Inc.
+
+The MIT License (MIT)
+
+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.

packages/cli-app/README.md

@@ -0,0 +1,38 @@
+# @percy/cli-app
+
+Percy CLI commands for running Percy with native apps.
+
+## Commands
+<!-- commands -->
+* [`percy app:exec`](#percy-appexec)
+
+### `percy app:exec`
+
+Start and stop Percy around a supplied command for native apps
+
+```
+Usage:
+  $ percy app:exec [options] -- <command>
+
+Subcommands:
+  app:exec:start [options]  Starts a locally running Percy process for native apps
+  app:exec:stop [options]   Stops a locally running Percy process
+  app:exec:ping [options]   Pings a locally running Percy process
+  help [command]            Display command help
+
+Options:
+  --parallel                Marks the build as one of many parallel builds
+  --partial                 Marks the build as a partial build
+
+Percy options:
+  -c, --config <file>       Config file path
+  -d, --dry-run             Print snapshot names only
+  -P, --port [number]       Local CLI server port (default: 5338)
+
+Global options:
+  -v, --verbose             Log everything
+  -q, --quiet               Log errors only
+  -s, --silent              Log nothing
+  -h, --help                Display command help
+```
+<!-- commandsstop -->

packages/cli-app/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@percy/cli-app",
+  "version": "1.9.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/percy/cli",
+    "directory": "packages/cli-app"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "type": "module",
+  "exports": "./dist/index.js",
+  "scripts": {
+    "build": "node ../../scripts/build",
+    "lint": "eslint --ignore-path ../../.gitignore .",
+    "readme": "percy-cli-readme",
+    "test": "node ../../scripts/test",
+    "test:coverage": "yarn test --coverage"
+  },
+  "@percy/cli": {
+    "commands": [
+      "./dist/app.js"
+    ]
+  },
+  "dependencies": {
+    "@percy/cli-command": "1.9.1",
+    "@percy/cli-exec": "1.9.1"
+  }
+}

packages/cli-app/src/app.js

@@ -0,0 +1,10 @@
+import command from '@percy/cli-command';
+import exec from './exec.js';
+
+export const app = command('app', {
+  description: 'Create Percy builds for native app snapshots',
+  hidden: 'This command is still in development and may not work as expected',
+  commands: [exec]
+});
+
+export default app;

packages/cli-app/src/exec.js

@@ -0,0 +1,32 @@
+import command from '@percy/cli-command';
+import * as ExecPlugin from '@percy/cli-exec';
+
+export const ping = ExecPlugin.ping;
+export const stop = ExecPlugin.stop;
+
+export const start = command('start', {
+  description: 'Starts a locally running Percy process for native apps',
+  examples: ['$0 &> percy.log'],
+
+  percy: {
+    server: true,
+    skipDiscovery: true
+  }
+}, ExecPlugin.start.callback);
+
+export const exec = command('exec', {
+  description: 'Start and stop Percy around a supplied command for native apps',
+  usage: '[options] -- <command>',
+  commands: [start, stop, ping],
+
+  flags: ExecPlugin.default.definition
+  // grouped flags are built-in flags
+    .flags.filter(f => !f.group),
+
+  percy: {
+    server: true,
+    skipDiscovery: true
+  }
+}, ExecPlugin.default.callback);
+
+export default exec;

packages/cli-app/src/index.js

@@ -0,0 +1,2 @@
+export { default, app } from './app.js';
+export { exec, start, stop, ping } from './exec.js';

packages/cli-app/test/.eslintrc

@@ -0,0 +1,6 @@
+env:
+  jasmine: true
+rules:
+  import/no-extraneous-dependencies: off
+  no-return-assign: off
+  no-sequences: off

packages/cli-app/test/exec.test.js

@@ -0,0 +1,26 @@
+import { setupTest } from '@percy/cli-command/test/helpers';
+import * as ExecPlugin from '@percy/cli-exec';
+import { exec, start, stop, ping } from '@percy/cli-app';
+
+describe('percy app:exec', () => {
+  beforeEach(async () => {
+    await setupTest();
+  });
+
+  it('has shared exec commands with differing definitions', async () => {
+    expect(exec.callback).toEqual(ExecPlugin.default.callback);
+    expect(exec.definition).not.toEqual(ExecPlugin.default.definition);
+    expect(start.callback).toEqual(ExecPlugin.start.callback);
+    expect(start.definition).not.toEqual(ExecPlugin.start.definition);
+    // stop and ping are actually exact references
+    expect(stop).toEqual(ExecPlugin.stop);
+    expect(ping).toEqual(ExecPlugin.ping);
+  });
+
+  it('does not accept asset discovery options', async () => {
+    await expectAsync(exec(['--allowed-hostname', 'percy.io']))
+      .toBeRejectedWithError("Unknown option '--allowed-hostname'");
+    await expectAsync(start(['--network-idle-timeout', '500']))
+      .toBeRejectedWithError("Unknown option '--network-idle-timeout'");
+  });
+});

packages/cli-exec/README.md

@@ -18,19 +18,19 @@ Usage:
   $ percy exec [options] -- <command>
 
 Subcommands:
-  exec:start [options]               Starts a local Percy snapshot server
-  exec:stop [options]                Stops a local running Percy snapshot server
-  exec:ping [options]                Pings a local running Percy snapshot server
+  exec:start [options]               Starts a locally running Percy process
+  exec:stop [options]                Stops a locally running Percy process
+  exec:ping [options]                Pings a locally running Percy process
   help [command]                     Display command help
 
 Options:
-  -P, --port [number]                Local CLI server port (default: 5338)
   --parallel                         Marks the build as one of many parallel builds
   --partial                          Marks the build as a partial build
 
 Percy options:
   -c, --config <file>                Config file path
   -d, --dry-run                      Print snapshot names only
+  -P, --port [number]                Local CLI server port (default: 5338)
   -h, --allowed-hostname <hostname>  Allowed hostnames to capture in asset discovery
   --disallowed-hostname <hostname>   Disallowed hostnames to abort in asset discovery
   -t, --network-idle-timeout <ms>    Asset discovery network idle timeout
@@ -50,18 +50,16 @@ Examples:
 
 ### `percy exec:start`
 
-Starts a local Percy snapshot server
+Starts a locally running Percy process
 
 ```
 Usage:
   $ percy exec:start [options]
 
-Options:
-  -P, --port [number]                Local CLI server port (default: 5338)
-
 Percy options:
   -c, --config <file>                Config file path
   -d, --dry-run                      Print snapshot names only
+  -P, --port [number]                Local CLI server port (default: 5338)
   -h, --allowed-hostname <hostname>  Allowed hostnames to capture in asset discovery
   --disallowed-hostname <hostname>   Disallowed hostnames to abort in asset discovery
   -t, --network-idle-timeout <ms>    Asset discovery network idle timeout
@@ -80,13 +78,13 @@ Examples:
 
 ### `percy exec:stop`
 
-Stops a local running Percy snapshot server
+Stops a locally running Percy process
 
 ```
 Usage:
   $ percy exec:stop [options]
 
-Options:
+Percy options:
   -P, --port [number]  Local CLI server port (default: 5338)
 
 Global options:
@@ -98,13 +96,13 @@ Global options:
 
 ### `percy exec:ping`
 
-Pings a local running Percy snapshot server
+Pings a locally running Percy process
 
 ```
 Usage:
   $ percy exec:ping [options]
 
-Options:
+Percy options:
   -P, --port [number]  Local CLI server port (default: 5338)
 
 Global options:

packages/cli-exec/src/ping.js

@@ -2,7 +2,7 @@ import command from '@percy/cli-command';
 import flags from '@percy/cli-command/flags';
 
 export const ping = command('ping', {
-  description: 'Pings a local running Percy snapshot server',
+  description: 'Pings a locally running Percy process',
   flags: [flags.port],
   percy: true
 }, async ({ flags, percy, log, exit }) => {

packages/cli-exec/src/start.js

@@ -1,7 +1,7 @@
 import command from '@percy/cli-command';
 
 export const start = command('start', {
-  description: 'Starts a local Percy snapshot server',
+  description: 'Starts a locally running Percy process',
   examples: ['$0 &> percy.log'],
   percy: { server: true }
 }, async function*({ percy, exit }) {

packages/cli-exec/src/stop.js

@@ -2,7 +2,7 @@ import command from '@percy/cli-command';
 import flags from '@percy/cli-command/flags';
 
 export const stop = command('stop', {
-  description: 'Stops a local running Percy snapshot server',
+  description: 'Stops a locally running Percy process',
   flags: [flags.port],
   percy: true
 }, async ({ flags, percy, log, exit }) => {

packages/cli/package.json

@@ -30,6 +30,7 @@
     "test:coverage": "yarn test --coverage"
   },
   "dependencies": {
+    "@percy/cli-app": "1.9.1",
     "@percy/cli-build": "1.9.1",
     "@percy/cli-command": "1.9.1",
     "@percy/cli-config": "1.9.1",