Document required non-interactive theme flags

[gonzaloriestra]

Related: https://github.com/shop/issues-develop/issues/22928

Summary

• Apply non-interactive flag requirements to theme selection, confirmation, naming, and live-theme safety flows.
• Cover delete, duplicate, open, publish, pull, push, and rename commands.
• Include alternative and conditional requirements, tests,

Testing

See #8223

[gonzaloriestra]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• Document other required non-interactive flags #8223
• Document required non-interactive store flags #8222
• Document required non-interactive theme flags #8221 👈 (View in Graphite)
• Document required non-interactive app flags #8220
• Add infrastructure for required non-interactive flags #8207
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

We found no new type declarations in this PR

Existing type declarations

packages/cli-kit/dist/public/node/base-command.d.ts

@@ -2,8 +2,15 @@ import { Command } from '@oclif/core';
 import { OutputFlags, Input, ParserOutput, FlagInput, OutputArgs } from '@oclif/core/parser';
 export type ArgOutput = OutputArgs<any>;
 export type FlagOutput = OutputFlags<any>;
+export interface NonTTYFlagRequirement {
+    /** At least one of these flags must be present when the requirement applies. */
+    flags: string[];
+    /** Determines whether the requirement applies to the parsed flags. */
+    when?: (flags: FlagOutput) => boolean;
+}
 declare abstract class BaseCommand extends Command {
     static baseFlags: FlagInput<{}>;
+    static nonTTYFlagRequirements(_flags: FlagOutput): NonTTYFlagRequirement[];
     static descriptionWithoutMarkdown(): string | undefined;
     static analyticsNameOverride(): string | undefined;
     static analyticsStopCommand(): string | undefined;
@@ -22,6 +29,8 @@ declare abstract class BaseCommand extends Command {
     }>;
     protected environmentsFilename(): string | undefined;
     protected failMissingNonTTYFlags(flags: FlagOutput, requiredFlags: string[]): void;
+    private failMissingNonTTYFlagRequirements;
+    private applicableNonTTYFlagRequirements;
     private resultWithEnvironment;
     /**
      * Tries to load an environment to forward to the command. If no environment

packages/cli-kit/dist/public/node/cli.d.ts

@@ -55,6 +55,19 @@ export declare const portFlag: (options?: {
     env?: string;
     hidden?: boolean;
 }) => import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+/**
+ * Marks a flag as required when the CLI cannot prompt for a value.
+ *
+ * The flag remains optional in interactive terminals. In non-interactive environments,
+ * `BaseCommand` validates the flag automatically and the requirement is shown in `--help`.
+ * Use `BaseCommand.nonTTYFlagRequirements` for conditional or alternative requirements.
+ *
+ * @param flag - An oclif flag definition.
+ * @returns A new flag definition annotated for non-interactive validation and help output.
+ */
+export declare function requiredIfNonInteractive<TFlag extends {
+    description?: string;
+}>(flag: TFlag): TFlag;
 /**
  * Clear the CLI cache, used to store some API responses and handle notifications status
  */

[graygilmore]

(nit) The language on this is a little awkward to me. What about something like:

Suggested change

	"description": "Include other development themes in the theme list. In non-interactive environments, provide this flag, --development, or --theme.",
	"description": "Include other development themes in the theme list. Use --show-all, --development, or --theme in non-interactive environments.",

(applies to other descriptions, too)