Port app security flag descriptions from the shopify.dev docs

.changeset/app-security-flag-descriptions.md

@@ -0,0 +1,6 @@
+---
+'@shopify/app': patch
+'@shopify/cli': patch
+---
+
+Clarify the `--blocking` and `--skip-instructions` help text for `shopify app security`

docs-shopify.dev/generated/generated_docs_data_v2.json

@@ -3406,7 +3406,7 @@
           "syntaxKind": "PropertySignature",
           "name": "--blocking <value>",
           "value": "string",
-          "description": "The minimum finding severity that causes a non-zero exit code.",
+          "description": "The minimum finding severity that causes a non-zero exit code: high, medium, or low. Defaults to none, which never fails on findings.",
           "isOptional": true,
           "environmentValue": "SHOPIFY_FLAG_APP_SECURITY_BLOCKING"
         },
@@ -3494,7 +3494,7 @@
           "syntaxKind": "PropertySignature",
           "name": "--skip-instructions",
           "value": "''",
-          "description": "Don't offer to show coding-agent instructions.",
+          "description": "Don't offer the coding-agent instructions after the scan. Use it when you want only the deterministic scan results.",
           "isOptional": true,
           "environmentValue": "SHOPIFY_FLAG_APP_SECURITY_SKIP_INSTRUCTIONS"
         },
@@ -3535,7 +3535,7 @@
           "environmentValue": "SHOPIFY_FLAG_APP_CONFIG"
         }
       ],
-      "value": "export interface appsecuritycheck {\n  /**\n   * The minimum finding severity that causes a non-zero exit code.\n   * @environment SHOPIFY_FLAG_APP_SECURITY_BLOCKING\n   */\n  '--blocking <value>'?: string\n\n  /**\n   * The Client ID of your app.\n   * @environment SHOPIFY_FLAG_CLIENT_ID\n   */\n  '--client-id <value>'?: string\n\n  /**\n   * The name of the app configuration.\n   * @environment SHOPIFY_FLAG_APP_CONFIG\n   */\n  '-c, --config <value>'?: string\n\n  /**\n   * Skip paths that match this glob, relative to the working directory. Repeat the flag to add globs. The selected app configuration file can't be excluded.\n   *\n   */\n  '--exclude <value>'?: string\n\n  /**\n   * Also scan this directory, relative to the working directory. Repeat the flag to add directories. Use it for code that lives outside the app directory, such as a backend or a shared library.\n   *\n   */\n  '--include-dir <value>'?: string\n\n  /**\n   * Print the command's JSON schemas.\n   * @environment SHOPIFY_FLAG_JSON_SCHEMA\n   */\n  '--json-schema'?: ''\n\n  /**\n   * Print the files the check would gather, one path per line, and stop. Nothing is scanned, no results are written, and nothing is prompted for.\n   * @environment SHOPIFY_FLAG_LIST_FILES\n   */\n  '--list-files'?: ''\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Turn off Git ignore rules for every scanned directory, so files that Git ignores are scanned too. Files that Git tracks are always scanned.\n   * @environment SHOPIFY_FLAG_NO_GIT_IGNORE\n   */\n  '--no-git-ignore'?: ''\n\n  /**\n   * Disable interactive prompts and browser authentication.\n   * @environment SHOPIFY_FLAG_NO_INPUT\n   */\n  '--no-input'?: ''\n\n  /**\n   * The path to your app directory.\n   * @environment SHOPIFY_FLAG_PATH\n   */\n  '--path <value>'?: string\n\n  /**\n   * Don't offer to show coding-agent instructions.\n   * @environment SHOPIFY_FLAG_APP_SECURITY_SKIP_INSTRUCTIONS\n   */\n  '--skip-instructions'?: ''\n\n  /**\n   * Increase the verbosity of the output. May include sensitive data.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n\n  /**\n   * Scan --path as an app with no app configuration file. Config checks are skipped. Requires --client-id.\n   * @environment SHOPIFY_FLAG_WITHOUT_APP_CONFIG\n   */\n  '--without-app-config'?: ''\n\n  /**\n   * Print coding-agent instructions without prompting.\n   * @environment SHOPIFY_FLAG_YES\n   */\n  '--yes'?: ''\n}"
+      "value": "export interface appsecuritycheck {\n  /**\n   * The minimum finding severity that causes a non-zero exit code: high, medium, or low. Defaults to none, which never fails on findings.\n   * @environment SHOPIFY_FLAG_APP_SECURITY_BLOCKING\n   */\n  '--blocking <value>'?: string\n\n  /**\n   * The Client ID of your app.\n   * @environment SHOPIFY_FLAG_CLIENT_ID\n   */\n  '--client-id <value>'?: string\n\n  /**\n   * The name of the app configuration.\n   * @environment SHOPIFY_FLAG_APP_CONFIG\n   */\n  '-c, --config <value>'?: string\n\n  /**\n   * Skip paths that match this glob, relative to the working directory. Repeat the flag to add globs. The selected app configuration file can't be excluded.\n   *\n   */\n  '--exclude <value>'?: string\n\n  /**\n   * Also scan this directory, relative to the working directory. Repeat the flag to add directories. Use it for code that lives outside the app directory, such as a backend or a shared library.\n   *\n   */\n  '--include-dir <value>'?: string\n\n  /**\n   * Print the command's JSON schemas.\n   * @environment SHOPIFY_FLAG_JSON_SCHEMA\n   */\n  '--json-schema'?: ''\n\n  /**\n   * Print the files the check would gather, one path per line, and stop. Nothing is scanned, no results are written, and nothing is prompted for.\n   * @environment SHOPIFY_FLAG_LIST_FILES\n   */\n  '--list-files'?: ''\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Turn off Git ignore rules for every scanned directory, so files that Git ignores are scanned too. Files that Git tracks are always scanned.\n   * @environment SHOPIFY_FLAG_NO_GIT_IGNORE\n   */\n  '--no-git-ignore'?: ''\n\n  /**\n   * Disable interactive prompts and browser authentication.\n   * @environment SHOPIFY_FLAG_NO_INPUT\n   */\n  '--no-input'?: ''\n\n  /**\n   * The path to your app directory.\n   * @environment SHOPIFY_FLAG_PATH\n   */\n  '--path <value>'?: string\n\n  /**\n   * Don't offer the coding-agent instructions after the scan. Use it when you want only the deterministic scan results.\n   * @environment SHOPIFY_FLAG_APP_SECURITY_SKIP_INSTRUCTIONS\n   */\n  '--skip-instructions'?: ''\n\n  /**\n   * Increase the verbosity of the output. May include sensitive data.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n\n  /**\n   * Scan --path as an app with no app configuration file. Config checks are skipped. Requires --client-id.\n   * @environment SHOPIFY_FLAG_WITHOUT_APP_CONFIG\n   */\n  '--without-app-config'?: ''\n\n  /**\n   * Print coding-agent instructions without prompting.\n   * @environment SHOPIFY_FLAG_YES\n   */\n  '--yes'?: ''\n}"
     }
   },
   "appsecurityclean": {
@@ -3825,7 +3825,7 @@
           "syntaxKind": "PropertySignature",
           "name": "--blocking <value>",
           "value": "string",
-          "description": "The minimum finding severity that causes a non-zero exit code.",
+          "description": "The minimum finding severity that causes a non-zero exit code: high, medium, or low. Defaults to none, which never fails on findings.",
           "isOptional": true,
           "environmentValue": "SHOPIFY_FLAG_APP_SECURITY_BLOCKING"
         },
@@ -3911,7 +3911,7 @@
           "environmentValue": "SHOPIFY_FLAG_APP_CONFIG"
         }
       ],
-      "value": "export interface appsecurityreview {\n  /**\n   * The minimum finding severity that causes a non-zero exit code.\n   * @environment SHOPIFY_FLAG_APP_SECURITY_BLOCKING\n   */\n  '--blocking <value>'?: string\n\n  /**\n   * Show only this check. Repeat the flag to show several checks.\n   * @environment SHOPIFY_FLAG_CHECK_ID\n   */\n  '--check-id <value>'?: string\n\n  /**\n   * The Client ID of your app.\n   * @environment SHOPIFY_FLAG_CLIENT_ID\n   */\n  '--client-id <value>'?: string\n\n  /**\n   * The name of the app configuration.\n   * @environment SHOPIFY_FLAG_APP_CONFIG\n   */\n  '-c, --config <value>'?: string\n\n  /**\n   * Print the command's JSON schemas.\n   * @environment SHOPIFY_FLAG_JSON_SCHEMA\n   */\n  '--json-schema'?: ''\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Disable interactive prompts and browser authentication.\n   * @environment SHOPIFY_FLAG_NO_INPUT\n   */\n  '--no-input'?: ''\n\n  /**\n   * The path to your app directory.\n   * @environment SHOPIFY_FLAG_PATH\n   */\n  '--path <value>'?: string\n\n  /**\n   * Increase the verbosity of the output. May include sensitive data.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n\n  /**\n   * Scan --path as an app with no app configuration file. Config checks are skipped. Requires --client-id.\n   * @environment SHOPIFY_FLAG_WITHOUT_APP_CONFIG\n   */\n  '--without-app-config'?: ''\n}"
+      "value": "export interface appsecurityreview {\n  /**\n   * The minimum finding severity that causes a non-zero exit code: high, medium, or low. Defaults to none, which never fails on findings.\n   * @environment SHOPIFY_FLAG_APP_SECURITY_BLOCKING\n   */\n  '--blocking <value>'?: string\n\n  /**\n   * Show only this check. Repeat the flag to show several checks.\n   * @environment SHOPIFY_FLAG_CHECK_ID\n   */\n  '--check-id <value>'?: string\n\n  /**\n   * The Client ID of your app.\n   * @environment SHOPIFY_FLAG_CLIENT_ID\n   */\n  '--client-id <value>'?: string\n\n  /**\n   * The name of the app configuration.\n   * @environment SHOPIFY_FLAG_APP_CONFIG\n   */\n  '-c, --config <value>'?: string\n\n  /**\n   * Print the command's JSON schemas.\n   * @environment SHOPIFY_FLAG_JSON_SCHEMA\n   */\n  '--json-schema'?: ''\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Disable interactive prompts and browser authentication.\n   * @environment SHOPIFY_FLAG_NO_INPUT\n   */\n  '--no-input'?: ''\n\n  /**\n   * The path to your app directory.\n   * @environment SHOPIFY_FLAG_PATH\n   */\n  '--path <value>'?: string\n\n  /**\n   * Increase the verbosity of the output. May include sensitive data.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n\n  /**\n   * Scan --path as an app with no app configuration file. Config checks are skipped. Requires --client-id.\n   * @environment SHOPIFY_FLAG_WITHOUT_APP_CONFIG\n   */\n  '--without-app-config'?: ''\n}"
     }
   },
   "appsubscriptionmigrationscancel": {

packages/app/src/cli/commands/app/security/blocking-flag.ts

@@ -9,7 +9,8 @@ const blockingLevels: AppSecurityBlockingLevel[] = ['high', 'medium', 'low', 'no
  */
 export const appSecurityBlockingFlag = {
   blocking: Flags.custom<AppSecurityBlockingLevel>({
-    description: 'The minimum finding severity that causes a non-zero exit code.',
+    description:
+      'The minimum finding severity that causes a non-zero exit code: high, medium, or low. Defaults to none, which never fails on findings.',
     options: blockingLevels,
     default: 'none',
     env: 'SHOPIFY_FLAG_APP_SECURITY_BLOCKING',

packages/app/src/cli/commands/app/security/check.test.ts

@@ -176,7 +176,9 @@ describe('app security check command', () => {
 
   test('describes the artifacts it writes and how agent results are recorded', () => {
     expect(SecurityCheck.flags.yes.description).toBe('Print coding-agent instructions without prompting.')
-    expect(SecurityCheck.flags['skip-instructions'].description).toBe("Don't offer to show coding-agent instructions.")
+    expect(SecurityCheck.flags['skip-instructions'].description).toBe(
+      "Don't offer the coding-agent instructions after the scan. Use it when you want only the deterministic scan results.",
+    )
     expect(SecurityCheck.flags.yes.exclusive).toEqual(['skip-instructions'])
     expect(SecurityCheck.flags['skip-instructions'].exclusive).toEqual(['yes'])
     expect(SecurityCheck.summary).toContain('deterministic-findings.json')

packages/app/src/cli/commands/app/security/check.ts

@@ -59,7 +59,8 @@ In interactive terminals, the command offers to copy the coding-agent instructio
       env: 'SHOPIFY_FLAG_YES',
     }),
     'skip-instructions': Flags.boolean({
-      description: "Don't offer to show coding-agent instructions.",
+      description:
+        "Don't offer the coding-agent instructions after the scan. Use it when you want only the deterministic scan results.",
       default: false,
       exclusive: ['yes'],
       env: 'SHOPIFY_FLAG_APP_SECURITY_SKIP_INSTRUCTIONS',

packages/cli/README.md

@@ -3681,7 +3681,8 @@ FLAGS
       [env: SHOPIFY_FLAG_APP_CONFIG]
 
   --blocking=<option>
-      [default: none] The minimum finding severity that causes a non-zero exit code.
+      [default: none] The minimum finding severity that causes a non-zero exit code: high, medium, or low. Defaults to
+      none, which never fails on findings.
       [env: SHOPIFY_FLAG_APP_SECURITY_BLOCKING]
       <options: high|medium|low|none>
 
@@ -3724,7 +3725,7 @@ FLAGS
       [env: SHOPIFY_FLAG_PATH]
 
   --skip-instructions
-      Don't offer to show coding-agent instructions.
+      Don't offer the coding-agent instructions after the scan. Use it when you want only the deterministic scan results.
       [env: SHOPIFY_FLAG_APP_SECURITY_SKIP_INSTRUCTIONS]
 
   --verbose
@@ -3963,7 +3964,8 @@ FLAGS
       [env: SHOPIFY_FLAG_APP_CONFIG]
 
   --blocking=<option>
-      [default: none] The minimum finding severity that causes a non-zero exit code.
+      [default: none] The minimum finding severity that causes a non-zero exit code: high, medium, or low. Defaults to
+      none, which never fails on findings.
       [env: SHOPIFY_FLAG_APP_SECURITY_BLOCKING]
       <options: high|medium|low|none>
 

packages/cli/oclif.manifest.json

@@ -4034,7 +4034,7 @@
       "flags": {
         "blocking": {
           "default": "none",
-          "description": "The minimum finding severity that causes a non-zero exit code.",
+          "description": "The minimum finding severity that causes a non-zero exit code: high, medium, or low. Defaults to none, which never fails on findings.",
           "env": "SHOPIFY_FLAG_APP_SECURITY_BLOCKING",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -4135,7 +4135,7 @@
         },
         "skip-instructions": {
           "allowNo": false,
-          "description": "Don't offer to show coding-agent instructions.",
+          "description": "Don't offer the coding-agent instructions after the scan. Use it when you want only the deterministic scan results.",
           "env": "SHOPIFY_FLAG_APP_SECURITY_SKIP_INSTRUCTIONS",
           "exclusive": [
             "yes"
@@ -4520,7 +4520,7 @@
       "flags": {
         "blocking": {
           "default": "none",
-          "description": "The minimum finding severity that causes a non-zero exit code.",
+          "description": "The minimum finding severity that causes a non-zero exit code: high, medium, or low. Defaults to none, which never fails on findings.",
           "env": "SHOPIFY_FLAG_APP_SECURITY_BLOCKING",
           "hasDynamicHelp": false,
           "multiple": false,