@shell-shock/plugin-help 0.1.2

package/dist/components/display.mjs

@@ -0,0 +1,254 @@
+import { kebabCase } from "../node_modules/.pnpm/@stryke_string-format@0.17.4/node_modules/@stryke/string-format/dist/kebab-case.mjs";
+import { snakeCase } from "../node_modules/.pnpm/@stryke_string-format@0.17.4/node_modules/@stryke/string-format/dist/snake-case.mjs";
+import { createComponent, createIntrinsic, memo } from "@alloy-js/core/jsx-runtime";
+import { For, Show, code, computed } from "@alloy-js/core";
+import { formatDescription, formatShortDescription, getAppBin, getAppTitle, getDynamicPathSegmentName, isDynamicPathSegment, sortOptions } from "@shell-shock/core/plugin-utils";
+import { Spacing } from "@powerlines/plugin-alloy/core/components/spacing";
+import { usePowerlines } from "@powerlines/plugin-alloy/core/contexts/context";
+import { CommandParameterKinds } from "@shell-shock/core";
+import { useTheme } from "@shell-shock/plugin-theme/contexts/theme";
+
+//#region src/components/display.tsx
+/**
+* A component that generates the usage display for a command.
+*/
+function HelpUsageDisplay(props) {
+	const { command, indent = 2 } = props;
+	const context = usePowerlines();
+	const theme = useTheme();
+	return [createComponent(For, {
+		get each() {
+			return Object.keys(context.config.bin);
+		},
+		hardline: true,
+		children: (bin) => [memo(() => code`
+      writeLine(
+        colors.text.body.secondary(\`\$ \${colors.text.usage.bin("${bin}")}${command.segments.length > 0 ? ` ${command.segments.map((segment) => `\${colors.text.usage.${isDynamicPathSegment(segment) ? "dynamic" : "command"}("${isDynamicPathSegment(segment) ? `[${snakeCase(getDynamicPathSegmentName(segment))}]` : segment}")}`).join(" ")}` : ""}${Object.values(command.children).length > 0 ? ` \${colors.text.usage.dynamic("[command]")}` : ""}${command.args.length > 0 ? ` ${command.args.map((arg) => `\${colors.text.usage.args("<${snakeCase((arg.kind === CommandParameterKinds.string || arg.kind === CommandParameterKinds.number) && arg.choices && arg.choices.length > 0 ? arg.choices.join("|") : arg.kind === CommandParameterKinds.string && arg.format ? arg.format : arg.name)}${(arg.kind === CommandParameterKinds.string || arg.kind === CommandParameterKinds.number) && arg.variadic ? "..." : ""}>")}`).join(" ")}` : ""} \${colors.text.usage.options("[options]")}\`), { padding: ${theme.padding.app * indent} }
+      );`), createIntrinsic("hbr", {})]
+	}), createComponent(Show, {
+		get when() {
+			return command.args.length > 0;
+		},
+		get children() {
+			return [createIntrinsic("hbr", {}), createComponent(For, {
+				get each() {
+					return Object.keys(context.config.bin);
+				},
+				hardline: true,
+				children: (bin) => [memo(() => code`
+      writeLine(
+        colors.text.body.secondary(\`\$ \${colors.text.usage.bin("${bin}")}${command.segments.length > 0 ? ` ${command.segments.map((segment) => `\${colors.text.usage.${isDynamicPathSegment(segment) ? "dynamic" : "command"}("${isDynamicPathSegment(segment) ? `[${snakeCase(getDynamicPathSegmentName(segment))}]` : segment}")}`).join(" ")}` : ""}${Object.values(command.children).length > 0 ? ` \${colors.text.usage.dynamic("[command]")}` : ""} \${colors.text.usage.options("[options]")}${command.args.length > 0 ? ` ${command.args.map((arg) => `\${colors.text.usage.args("<${snakeCase((arg.kind === CommandParameterKinds.string || arg.kind === CommandParameterKinds.number) && arg.choices && arg.choices.length > 0 ? arg.choices.join("|") : arg.kind === CommandParameterKinds.string && arg.format ? arg.format : arg.name)}${(arg.kind === CommandParameterKinds.string || arg.kind === CommandParameterKinds.number) && arg.variadic ? "..." : ""}>")}`).join(" ")}` : ""}\`), { padding: ${theme.padding.app * indent} }
+      );`), createIntrinsic("hbr", {})]
+			})];
+		}
+	})];
+}
+/**
+* A component that generates the options table display for a command.
+*/
+function HelpOptionsDisplay(props) {
+	const { options } = props;
+	const context = usePowerlines();
+	return [
+		code`table([ `,
+		createIntrinsic("hbr", {}),
+		createComponent(For, {
+			get each() {
+				return sortOptions(options);
+			},
+			hardline: true,
+			children: (option) => {
+				const flags = [];
+				const names = [];
+				if (option.name.length === 1) flags.push(`-${option.name}`);
+				else names.push(`--${kebabCase(option.name)}`);
+				option.alias.forEach((alias) => {
+					if (alias.length === 1) flags.push(`-${alias}`);
+					else names.push(`--${kebabCase(alias)}`);
+				});
+				return code`[{ value: colors.text.body.primary("${flags.length > 0 ? `${flags.sort().join(", ")}${names.length > 0 ? ", " : ""}` : ""}${names.length > 0 ? names.sort().join(", ") : ""}${option.kind === CommandParameterKinds.string ? ` <${snakeCase(option.choices && option.choices.length > 0 ? option.choices.join("|") : option.format ? option.format : option.name)}${option.variadic ? "..." : ""}>` : option.kind === CommandParameterKinds.number ? ` <${snakeCase(option.choices && option.choices.length > 0 ? option.choices.join("|") : option.name)}${option.variadic ? "..." : ""}>` : ""}"), align: "right", border: "none", maxWidth: "1/3" }, { value: colors.text.body.tertiary(\`${formatShortDescription(option.description).replace(/\.+$/, "").trim()}${option.env || option.default !== void 0 ? ` (${option.env ? `env: ${context.config.appSpecificEnvPrefix}_${option.env}${option.default !== void 0 ? ", " : ""}` : ""}${option.default !== void 0 ? `default: ${JSON.stringify(option.default).replace(/"/g, "\\\"")}` : ""})` : ""}.\`), align: "left", border: "none" }], `;
+			}
+		}),
+		createIntrinsic("hbr", {}),
+		code` ]); `
+	];
+}
+/**
+* A component that generates the commands table display for a command.
+*/
+function HelpCommandsDisplay(props) {
+	const { commands } = props;
+	return [
+		code`table([ `,
+		createIntrinsic("hbr", {}),
+		createComponent(For, {
+			get each() {
+				return Object.values(commands);
+			},
+			hardline: true,
+			children: (child) => code`[{ value: colors.text.body.primary("${child.name}"), align: "right", border: "none" }, { value: colors.text.body.tertiary(\`${formatShortDescription(child.description).replace(/\.+$/, "").trim()}.\`), align: "left", border: "none" }], `
+		}),
+		createIntrinsic("hbr", {}),
+		code` ]); `
+	];
+}
+/**
+* A component that generates the `help` function declaration for a command.
+*/
+function BaseHelpDisplay(props) {
+	const { command, indent = 1, filterGlobalOptions = false } = props;
+	const theme = useTheme();
+	const context = usePowerlines();
+	const options = computed(() => filterGlobalOptions ? Object.values(command.options).filter((option) => !context.options.some((globalOption) => globalOption.name === option.name || option.alias.includes(globalOption.name) || globalOption.alias?.includes(option.name) || globalOption.alias?.some((alias) => option.alias.includes(alias)))) : Object.values(command.options));
+	return [
+		memo(() => code`writeLine(colors.bold(colors.text.heading.secondary("Usage:"))${indent > 1 ? `, { padding: ${theme.padding.app * indent} }` : ""});`),
+		createIntrinsic("hbr", {}),
+		createComponent(HelpUsageDisplay, {
+			command,
+			indent
+		}),
+		createComponent(Spacing, {}),
+		createComponent(Show, {
+			get when() {
+				return options.value.length > 0;
+			},
+			get children() {
+				return [
+					memo(() => code`writeLine("");
+      writeLine(colors.bold(colors.text.heading.secondary("Options:"))${indent > 1 ? `, { padding: ${theme.padding.app * indent} }` : ""});`),
+					createIntrinsic("hbr", {}),
+					createComponent(HelpOptionsDisplay, { get options() {
+						return options.value;
+					} }),
+					createComponent(Spacing, {})
+				];
+			}
+		}),
+		createComponent(Show, {
+			get when() {
+				return Object.keys(command.children).length > 0;
+			},
+			get children() {
+				return [
+					memo(() => code`writeLine("");
+      writeLine(colors.bold(colors.text.heading.secondary("Commands:"))${indent > 1 ? `, { padding: ${theme.padding.app * indent} }` : ""});`),
+					createIntrinsic("hbr", {}),
+					createComponent(HelpCommandsDisplay, { get commands() {
+						return command.children;
+					} }),
+					createComponent(Spacing, {})
+				];
+			}
+		})
+	];
+}
+/**
+* A component that generates the invocation of the `help` function for a command.
+*/
+function VirtualCommandHelpDisplay(props) {
+	const { options, segments, commands } = props;
+	const context = usePowerlines();
+	return [
+		createIntrinsic("hbr", {}),
+		code`writeLine(colors.bold(colors.text.heading.secondary("Global Options:")));`,
+		createIntrinsic("hbr", {}),
+		createComponent(HelpOptionsDisplay, { options }),
+		code`writeLine(""); `,
+		createComponent(Spacing, {}),
+		createComponent(Show, {
+			get when() {
+				return Object.keys(commands).length > 0;
+			},
+			get children() {
+				return [
+					memo(() => code`writeLine(colors.text.body.secondary("The following commands are available through the ${getAppTitle(context, true)} command-line interface:"));
+        writeLine(""); `),
+					createComponent(Spacing, {}),
+					createComponent(For, {
+						get each() {
+							return Object.values(commands);
+						},
+						doubleHardline: true,
+						joiner: code`writeLine(""); `,
+						ender: code`writeLine(""); `,
+						children: (child) => [
+							memo(() => code`
+                writeLine(colors.text.heading.primary(${child.icon ? `(isUnicodeSupported ? " ${child.icon}  " : "") + ` : ""}"${child.title} ${child.isVirtual ? "" : "Command"}"));
+                writeLine("");
+                writeLine(colors.text.body.secondary(splitText(\`${formatDescription(child.description).replace(/\.+$/, "").trim()}.\`)));
+                writeLine("");
+                `),
+							createIntrinsic("hbr", {}),
+							createComponent(BaseHelpDisplay, {
+								command: child,
+								indent: 2,
+								filterGlobalOptions: true
+							}),
+							createIntrinsic("hbr", {})
+						]
+					}),
+					memo(() => code`help("Running a specific command with the help flag (via: '${getAppBin(context)}${segments && segments.length > 0 ? ` ${segments.join(" ")}` : ""} <specific command> --help') will provide additional information that is specific to that command.");
+        writeLine("");`)
+				];
+			}
+		})
+	];
+}
+/**
+* A component that generates the invocation of the `help` function for a command.
+*/
+function CommandHelpDisplay(props) {
+	const { command } = props;
+	const context = usePowerlines();
+	return [
+		code`writeLine(""); `,
+		createComponent(Spacing, {}),
+		createComponent(BaseHelpDisplay, {
+			command,
+			filterGlobalOptions: false
+		}),
+		code`writeLine(""); `,
+		createComponent(Spacing, {}),
+		createComponent(Show, {
+			get when() {
+				return Object.keys(command.children).length > 0;
+			},
+			get children() {
+				return [
+					code`writeLine(colors.text.body.secondary("The following sub-commands are available:"));
+        writeLine(""); `,
+					createComponent(Spacing, {}),
+					createComponent(For, {
+						get each() {
+							return Object.values(command.children);
+						},
+						doubleHardline: true,
+						joiner: code`writeLine(""); `,
+						ender: code`writeLine(""); `,
+						children: (child) => [
+							memo(() => code`
+                writeLine(colors.text.heading.primary(${child.icon ? `(isUnicodeSupported ? " ${child.icon}  " : "") + ` : ""}"${child.title} ${child.isVirtual ? "" : "Command"}"));
+                writeLine("");
+                writeLine(colors.text.body.secondary(splitText(\`${formatDescription(child.description).replace(/\.+$/, "").trim()}.\`)));
+                writeLine("");
+                `),
+							createIntrinsic("hbr", {}),
+							createComponent(BaseHelpDisplay, {
+								command: child,
+								indent: 2,
+								filterGlobalOptions: true
+							}),
+							createIntrinsic("hbr", {})
+						]
+					}),
+					memo(() => code`help("Running a specific command with the help flag (via: '${getAppBin(context)} ${command.segments.join(" ")} <specific command> --help') will provide additional information that is specific to that command.");
+        writeLine("");`)
+				];
+			}
+		})
+	];
+}
+
+//#endregion
+export { BaseHelpDisplay, CommandHelpDisplay, HelpCommandsDisplay, HelpOptionsDisplay, HelpUsageDisplay, VirtualCommandHelpDisplay };
+//# sourceMappingURL=display.mjs.map

package/dist/components/display.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"display.mjs","names":[],"sources":["../../src/components/display.tsx"],"sourcesContent":["/* -------------------------------------------------------------------\n\n                  ⚡ Storm Software - Shell Shock\n\n This code was released as part of the Shell Shock project. Shell Shock\n is maintained by Storm Software under the Apache-2.0 license, and is\n free for commercial and private use. For more information, please visit\n our licensing page at https://stormsoftware.com/licenses/projects/shell-shock.\n\n Website:                  https://stormsoftware.com\n Repository:               https://github.com/storm-software/shell-shock\n Documentation:            https://docs.stormsoftware.com/projects/shell-shock\n Contact:                  https://stormsoftware.com/contact\n\n SPDX-License-Identifier:  Apache-2.0\n\n ------------------------------------------------------------------- */\n\nimport { code, computed, For, Show } from \"@alloy-js/core\";\nimport { Spacing } from \"@powerlines/plugin-alloy/core/components/spacing\";\nimport { usePowerlines } from \"@powerlines/plugin-alloy/core/contexts/context\";\nimport type { CommandOption, CommandTree } from \"@shell-shock/core\";\nimport { CommandParameterKinds } from \"@shell-shock/core\";\nimport {\n  formatDescription,\n  formatShortDescription,\n  getAppBin,\n  getAppTitle,\n  getDynamicPathSegmentName,\n  isDynamicPathSegment,\n  sortOptions\n} from \"@shell-shock/core/plugin-utils\";\nimport { useTheme } from \"@shell-shock/plugin-theme/contexts/theme\";\nimport { kebabCase } from \"@stryke/string-format/kebab-case\";\nimport { snakeCase } from \"@stryke/string-format/snake-case\";\nimport type { HelpPluginContext } from \"../types/plugin\";\n\nexport interface HelpUsageDisplayProps {\n  /**\n   * The command to generate help for.\n   */\n  command: CommandTree;\n\n  /**\n   * The padding scale to apply to the help display headings.\n   *\n   * @remarks\n   * This value is multiplied by the theme's app padding to determine the final padding.\n   *\n   * @defaultValue 2\n   */\n  indent?: number;\n}\n\n/**\n * A component that generates the usage display for a command.\n */\nexport function HelpUsageDisplay(props: HelpUsageDisplayProps) {\n  const { command, indent = 2 } = props;\n\n  const context = usePowerlines<HelpPluginContext>();\n  const theme = useTheme();\n\n  return (\n    <>\n      <For each={Object.keys(context.config.bin)} hardline>\n        {bin => (\n          <>\n            {code`\n      writeLine(\n        colors.text.body.secondary(\\`\\$ \\${colors.text.usage.bin(\"${bin}\")}${\n          command.segments.length > 0\n            ? ` ${command.segments\n                .map(\n                  segment =>\n                    `\\${colors.text.usage.${isDynamicPathSegment(segment) ? \"dynamic\" : \"command\"}(\"${\n                      isDynamicPathSegment(segment)\n                        ? `[${snakeCase(getDynamicPathSegmentName(segment))}]`\n                        : segment\n                    }\")}`\n                )\n                .join(\" \")}`\n            : \"\"\n        }${Object.values(command.children).length > 0 ? ` \\${colors.text.usage.dynamic(\"[command]\")}` : \"\"}${\n          command.args.length > 0\n            ? ` ${command.args\n                .map(\n                  arg =>\n                    `\\${colors.text.usage.args(\"<${snakeCase(\n                      (arg.kind === CommandParameterKinds.string ||\n                        arg.kind === CommandParameterKinds.number) &&\n                        arg.choices &&\n                        arg.choices.length > 0\n                        ? arg.choices.join(\"|\")\n                        : arg.kind === CommandParameterKinds.string &&\n                            arg.format\n                          ? arg.format\n                          : arg.name\n                    )}${\n                      (arg.kind === CommandParameterKinds.string ||\n                        arg.kind === CommandParameterKinds.number) &&\n                      arg.variadic\n                        ? \"...\"\n                        : \"\"\n                    }>\")}`\n                )\n                .join(\" \")}`\n            : \"\"\n        } \\${colors.text.usage.options(\"[options]\")}\\`), { padding: ${theme.padding.app * indent} }\n      );`}\n            <hbr />\n          </>\n        )}\n      </For>\n      <Show when={command.args.length > 0}>\n        <hbr />\n        <For each={Object.keys(context.config.bin)} hardline>\n          {bin => (\n            <>\n              {code`\n      writeLine(\n        colors.text.body.secondary(\\`\\$ \\${colors.text.usage.bin(\"${bin}\")}${\n          command.segments.length > 0\n            ? ` ${command.segments\n                .map(\n                  segment =>\n                    `\\${colors.text.usage.${isDynamicPathSegment(segment) ? \"dynamic\" : \"command\"}(\"${\n                      isDynamicPathSegment(segment)\n                        ? `[${snakeCase(getDynamicPathSegmentName(segment))}]`\n                        : segment\n                    }\")}`\n                )\n                .join(\" \")}`\n            : \"\"\n        }${Object.values(command.children).length > 0 ? ` \\${colors.text.usage.dynamic(\"[command]\")}` : \"\"} \\${colors.text.usage.options(\"[options]\")}${\n          command.args.length > 0\n            ? ` ${command.args\n                .map(\n                  arg =>\n                    `\\${colors.text.usage.args(\"<${snakeCase(\n                      (arg.kind === CommandParameterKinds.string ||\n                        arg.kind === CommandParameterKinds.number) &&\n                        arg.choices &&\n                        arg.choices.length > 0\n                        ? arg.choices.join(\"|\")\n                        : arg.kind === CommandParameterKinds.string &&\n                            arg.format\n                          ? arg.format\n                          : arg.name\n                    )}${\n                      (arg.kind === CommandParameterKinds.string ||\n                        arg.kind === CommandParameterKinds.number) &&\n                      arg.variadic\n                        ? \"...\"\n                        : \"\"\n                    }>\")}`\n                )\n                .join(\" \")}`\n            : \"\"\n        }\\`), { padding: ${theme.padding.app * indent} }\n      );`}\n              <hbr />\n            </>\n          )}\n        </For>\n      </Show>\n    </>\n  );\n}\n\nexport interface HelpOptionsDisplayProps {\n  /**\n   * The options to display help for.\n   */\n  options: CommandOption[];\n}\n\n/**\n * A component that generates the options table display for a command.\n */\nexport function HelpOptionsDisplay(props: HelpOptionsDisplayProps) {\n  const { options } = props;\n\n  const context = usePowerlines<HelpPluginContext>();\n\n  return (\n    <>\n      {code`table([ `}\n      <hbr />\n      <For each={sortOptions(options)} hardline>\n        {option => {\n          const flags = [] as string[];\n          const names = [] as string[];\n          if (option.name.length === 1) {\n            flags.push(`-${option.name}`);\n          } else {\n            names.push(`--${kebabCase(option.name)}`);\n          }\n\n          option.alias.forEach((alias: string) => {\n            if (alias.length === 1) {\n              flags.push(`-${alias}`);\n            } else {\n              names.push(`--${kebabCase(alias)}`);\n            }\n          });\n\n          return code`[{ value: colors.text.body.primary(\"${\n            flags.length > 0\n              ? `${flags.sort().join(\", \")}${names.length > 0 ? \", \" : \"\"}`\n              : \"\"\n          }${names.length > 0 ? names.sort().join(\", \") : \"\"}${\n            option.kind === CommandParameterKinds.string\n              ? ` <${snakeCase(\n                  option.choices && option.choices.length > 0\n                    ? option.choices.join(\"|\")\n                    : option.format\n                      ? option.format\n                      : option.name\n                )}${option.variadic ? \"...\" : \"\"}>`\n              : option.kind === CommandParameterKinds.number\n                ? ` <${snakeCase(\n                    option.choices && option.choices.length > 0\n                      ? option.choices.join(\"|\")\n                      : option.name\n                  )}${option.variadic ? \"...\" : \"\"}>`\n                : \"\"\n          }\"), align: \"right\", border: \"none\", maxWidth: \"1/3\" }, { value: colors.text.body.tertiary(\\`${formatShortDescription(\n            option.description\n          )\n            .replace(/\\.+$/, \"\")\n            .trim()}${\n            option.env || option.default !== undefined\n              ? ` (${\n                  option.env\n                    ? `env: ${context.config.appSpecificEnvPrefix}_${option.env}${\n                        option.default !== undefined ? \", \" : \"\"\n                      }`\n                    : \"\"\n                }${\n                  option.default !== undefined\n                    ? `default: ${JSON.stringify(option.default).replace(/\"/g, '\\\\\"')}`\n                    : \"\"\n                })`\n              : \"\"\n          }.\\`), align: \"left\", border: \"none\" }], `;\n        }}\n      </For>\n      <hbr />\n      {code` ]); `}\n    </>\n  );\n}\n\nexport interface HelpCommandsDisplayProps {\n  /**\n   * A mapping of command names to their command definitions.\n   */\n  commands: Record<string, CommandTree>;\n}\n\n/**\n * A component that generates the commands table display for a command.\n */\nexport function HelpCommandsDisplay(props: HelpCommandsDisplayProps) {\n  const { commands } = props;\n\n  return (\n    <>\n      {code`table([ `}\n      <hbr />\n      <For each={Object.values(commands)} hardline>\n        {child =>\n          code`[{ value: colors.text.body.primary(\"${\n            child.name\n          }\"), align: \"right\", border: \"none\" }, { value: colors.text.body.tertiary(\\`${formatShortDescription(\n            child.description\n          )\n            .replace(/\\.+$/, \"\")\n            .trim()}.\\`), align: \"left\", border: \"none\" }], `\n        }\n      </For>\n      <hbr />\n      {code` ]); `}\n    </>\n  );\n}\n\nexport interface BaseHelpDisplayProps {\n  /**\n   * The command to generate help for.\n   */\n  command: CommandTree;\n\n  /**\n   * Whether to filter out global options from the help display.\n   *\n   * @remarks\n   * When enabled, any options that are present in the global options context will be filtered out from the help display. This is useful for sub-commands to avoid displaying global options that are not relevant to the specific command.\n   *\n   * @defaultValue false\n   */\n  filterGlobalOptions?: boolean;\n\n  /**\n   * The padding scale to apply to the help display headings.\n   *\n   * @remarks\n   * This value is multiplied by the theme's app padding to determine the final padding.\n   *\n   * @defaultValue 1\n   */\n  indent?: number;\n}\n\n/**\n * A component that generates the `help` function declaration for a command.\n */\nexport function BaseHelpDisplay(props: BaseHelpDisplayProps) {\n  const { command, indent = 1, filterGlobalOptions = false } = props;\n\n  const theme = useTheme();\n  const context = usePowerlines<HelpPluginContext>();\n\n  const options = computed(() =>\n    filterGlobalOptions\n      ? Object.values(command.options).filter(\n          option =>\n            !context.options.some(\n              globalOption =>\n                globalOption.name === option.name ||\n                option.alias.includes(globalOption.name) ||\n                globalOption.alias?.includes(option.name) ||\n                globalOption.alias?.some(alias => option.alias.includes(alias))\n            )\n        )\n      : Object.values(command.options)\n  );\n\n  return (\n    <>\n      {code`writeLine(colors.bold(colors.text.heading.secondary(\"Usage:\"))${\n        indent > 1 ? `, { padding: ${theme.padding.app * indent} }` : \"\"\n      });`}\n      <hbr />\n      <HelpUsageDisplay command={command} indent={indent} />\n      <Spacing />\n      <Show when={options.value.length > 0}>\n        {code`writeLine(\"\");\n      writeLine(colors.bold(colors.text.heading.secondary(\"Options:\"))${\n        indent > 1 ? `, { padding: ${theme.padding.app * indent} }` : \"\"\n      });`}\n        <hbr />\n        <HelpOptionsDisplay options={options.value} />\n        <Spacing />\n      </Show>\n      <Show when={Object.keys(command.children).length > 0}>\n        {code`writeLine(\"\");\n      writeLine(colors.bold(colors.text.heading.secondary(\"Commands:\"))${\n        indent > 1 ? `, { padding: ${theme.padding.app * indent} }` : \"\"\n      });`}\n        <hbr />\n        <HelpCommandsDisplay commands={command.children} />\n        <Spacing />\n      </Show>\n    </>\n  );\n}\n\nexport interface VirtualCommandHelpDisplayProps {\n  /**\n   * The options to display help for.\n   */\n  options: CommandOption[];\n\n  /**\n   * A mapping of command names to their command definitions.\n   */\n  commands: Record<string, CommandTree>;\n\n  /**\n   * The command path to generate help for, used for generating the help invocation instructions.\n   *\n   * @remarks\n   * This is optional since the virtual command entry component can be used for both the global binary executable and virtual commands (there will be no command definition for the binary executable).\n   */\n  segments?: string[];\n}\n\n/**\n * A component that generates the invocation of the `help` function for a command.\n */\nexport function VirtualCommandHelpDisplay(\n  props: VirtualCommandHelpDisplayProps\n) {\n  const { options, segments, commands } = props;\n\n  const context = usePowerlines<HelpPluginContext>();\n\n  return (\n    <>\n      <hbr />\n      {code`writeLine(colors.bold(colors.text.heading.secondary(\"Global Options:\")));`}\n      <hbr />\n      <HelpOptionsDisplay options={options} />\n      {code`writeLine(\"\"); `}\n      <Spacing />\n      <Show when={Object.keys(commands).length > 0}>\n        {code`writeLine(colors.text.body.secondary(\"The following commands are available through the ${getAppTitle(\n          context,\n          true\n        )} command-line interface:\"));\n        writeLine(\"\"); `}\n        <Spacing />\n        <For\n          each={Object.values(commands)}\n          doubleHardline\n          joiner={code`writeLine(\"\"); `}\n          ender={code`writeLine(\"\"); `}>\n          {child => (\n            <>\n              {code`\n                writeLine(colors.text.heading.primary(${\n                  child.icon\n                    ? `(isUnicodeSupported ? \" ${child.icon}  \" : \"\") + `\n                    : \"\"\n                }\"${child.title} ${child.isVirtual ? \"\" : \"Command\"}\"));\n                writeLine(\"\");\n                writeLine(colors.text.body.secondary(splitText(\\`${formatDescription(\n                  child.description\n                )\n                  .replace(/\\.+$/, \"\")\n                  .trim()}.\\`)));\n                writeLine(\"\");\n                `}\n              <hbr />\n              <BaseHelpDisplay command={child} indent={2} filterGlobalOptions />\n              <hbr />\n            </>\n          )}\n        </For>\n        {code`help(\"Running a specific command with the help flag (via: '${getAppBin(\n          context\n        )}${\n          segments && segments.length > 0 ? ` ${segments.join(\" \")}` : \"\"\n        } <specific command> --help') will provide additional information that is specific to that command.\");\n        writeLine(\"\");`}\n      </Show>\n    </>\n  );\n}\n\nexport interface CommandHelpDisplayProps {\n  /**\n   * A mapping of command names to their command definitions.\n   */\n  command: CommandTree;\n}\n\n/**\n * A component that generates the invocation of the `help` function for a command.\n */\nexport function CommandHelpDisplay(props: CommandHelpDisplayProps) {\n  const { command } = props;\n\n  const context = usePowerlines<HelpPluginContext>();\n\n  return (\n    <>\n      {code`writeLine(\"\"); `}\n      <Spacing />\n      <BaseHelpDisplay command={command} filterGlobalOptions={false} />\n      {code`writeLine(\"\"); `}\n      <Spacing />\n      <Show when={Object.keys(command.children).length > 0}>\n        {code`writeLine(colors.text.body.secondary(\"The following sub-commands are available:\"));\n        writeLine(\"\"); `}\n        <Spacing />\n        <For\n          each={Object.values(command.children)}\n          doubleHardline\n          joiner={code`writeLine(\"\"); `}\n          ender={code`writeLine(\"\"); `}>\n          {child => (\n            <>\n              {code`\n                writeLine(colors.text.heading.primary(${\n                  child.icon\n                    ? `(isUnicodeSupported ? \" ${child.icon}  \" : \"\") + `\n                    : \"\"\n                }\"${child.title} ${child.isVirtual ? \"\" : \"Command\"}\"));\n                writeLine(\"\");\n                writeLine(colors.text.body.secondary(splitText(\\`${formatDescription(\n                  child.description\n                )\n                  .replace(/\\.+$/, \"\")\n                  .trim()}.\\`)));\n                writeLine(\"\");\n                `}\n              <hbr />\n              <BaseHelpDisplay command={child} indent={2} filterGlobalOptions />\n              <hbr />\n            </>\n          )}\n        </For>\n        {code`help(\"Running a specific command with the help flag (via: '${getAppBin(\n          context\n        )} ${command.segments.join(\n          \" \"\n        )} <specific command> --help') will provide additional information that is specific to that command.\");\n        writeLine(\"\");`}\n      </Show>\n    </>\n  );\n}\n"],"mappings":"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"}

package/dist/components/help-builtin.cjs

@@ -0,0 +1,113 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_runtime = require('../_virtual/_rolldown/runtime.cjs');
+const require_components_display = require('./display.cjs');
+let _alloy_js_core_jsx_runtime = require("@alloy-js/core/jsx-runtime");
+let _alloy_js_core = require("@alloy-js/core");
+let _shell_shock_core_plugin_utils = require("@shell-shock/core/plugin-utils");
+let defu = require("defu");
+defu = require_runtime.__toESM(defu);
+let _powerlines_plugin_alloy_core_components_spacing = require("@powerlines/plugin-alloy/core/components/spacing");
+let _powerlines_plugin_alloy_core_contexts_context = require("@powerlines/plugin-alloy/core/contexts/context");
+let _alloy_js_typescript = require("@alloy-js/typescript");
+let _powerlines_plugin_alloy_typescript = require("@powerlines/plugin-alloy/typescript");
+let _powerlines_plugin_alloy_typescript_components_builtin_file = require("@powerlines/plugin-alloy/typescript/components/builtin-file");
+let _stryke_path = require("@stryke/path");
+
+//#region src/components/help-builtin.tsx
+/**
+* The `updateVersionCheckFile` handler function declaration code for the Shell Shock project.
+*/
+function HelpFunctionDeclaration() {
+	return [(0, _alloy_js_core_jsx_runtime.createComponent)(_powerlines_plugin_alloy_typescript.TSDoc, {
+		heading: "A helper function that updates the version check file.",
+		get children() {
+			return [
+				(0, _alloy_js_core_jsx_runtime.createComponent)(_powerlines_plugin_alloy_typescript.TSDocRemarks, { children: `This function is used to update the version check file with the current timestamp. It can be used in the CLI upgrade command to record the last time a check for updates was performed. The function writes a "version-check.json" file in the data directory, which contains a timestamp of the last check for updates.` }),
+				(0, _alloy_js_core_jsx_runtime.createComponent)(_powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+				(0, _alloy_js_core_jsx_runtime.createComponent)(_powerlines_plugin_alloy_typescript.TSDocReturns, { children: `A promise that resolves to a boolean indicating whether a check for updates is required.` })
+			];
+		}
+	}), (0, _alloy_js_core_jsx_runtime.createComponent)(_alloy_js_typescript.FunctionDeclaration, {
+		"export": true,
+		async: true,
+		name: "updateVersionCheckFile",
+		returnType: "void",
+		get children() {
+			return [(0, _alloy_js_core_jsx_runtime.createComponent)(_alloy_js_typescript.IfStatement, {
+				condition: _alloy_js_core.code`!existsSync(paths.data)`,
+				children: _alloy_js_core.code`await mkdir(paths.data, { recursive: true }); `
+			}), _alloy_js_core.code`await writeFile(join(paths.data, "version-check.json"), JSON.stringify({ timestamp: new Date().getTime() }), "utf8"); `];
+		}
+	})];
+}
+/**
+* A built-in help module for Shell Shock.
+*/
+function HelpBuiltin(props) {
+	const [{ command, children }, rest] = (0, _alloy_js_core.splitProps)(props, ["command", "children"]);
+	const context = (0, _powerlines_plugin_alloy_core_contexts_context.usePowerlines)();
+	return (0, _alloy_js_core_jsx_runtime.createComponent)(_powerlines_plugin_alloy_typescript_components_builtin_file.BuiltinFile, (0, _alloy_js_core_jsx_runtime.mergeProps)({
+		get id() {
+			return (0, _stryke_path.joinPaths)("help", ...command.segments.filter((segment) => !(0, _shell_shock_core_plugin_utils.isDynamicPathSegment)(segment)));
+		},
+		get description() {
+			return (0, _alloy_js_core_jsx_runtime.memo)(() => !!command.path)() ? `A collection of utility functions that assist in displaying help information for the ${command.title} command.` : `A collection of utility functions that assist in displaying help information for the ${(0, _shell_shock_core_plugin_utils.getAppTitle)(context, true)} command-line interface application.`;
+		}
+	}, rest, {
+		get builtinImports() {
+			return (0, defu.default)(rest.builtinImports ?? {}, {
+				utils: ["isUnicodeSupported"],
+				console: [
+					"splitText",
+					"writeLine",
+					"colors",
+					"help",
+					"table"
+				]
+			});
+		},
+		get children() {
+			return [
+				(0, _alloy_js_core_jsx_runtime.createComponent)(_alloy_js_typescript.FunctionDeclaration, {
+					"export": true,
+					name: "showHelp",
+					get doc() {
+						return `Display help information for the ${command.path ? `${command.title} command` : `${(0, _shell_shock_core_plugin_utils.getAppTitle)(context, true)} application`}.`;
+					},
+					parameters: [],
+					get children() {
+						return (0, _alloy_js_core_jsx_runtime.createComponent)(_alloy_js_core.Show, {
+							get when() {
+								return !command.isVirtual;
+							},
+							get fallback() {
+								return (0, _alloy_js_core_jsx_runtime.createComponent)(require_components_display.VirtualCommandHelpDisplay, {
+									get options() {
+										return Object.values(command.options);
+									},
+									get commands() {
+										return command.children ?? {};
+									}
+								});
+							},
+							get children() {
+								return (0, _alloy_js_core_jsx_runtime.createComponent)(require_components_display.CommandHelpDisplay, { command });
+							}
+						});
+					}
+				}),
+				(0, _alloy_js_core_jsx_runtime.createComponent)(_powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+				(0, _alloy_js_core_jsx_runtime.createComponent)(_alloy_js_core.Show, {
+					get when() {
+						return Boolean(children);
+					},
+					children
+				})
+			];
+		}
+	}));
+}
+
+//#endregion
+exports.HelpBuiltin = HelpBuiltin;
+exports.HelpFunctionDeclaration = HelpFunctionDeclaration;

package/dist/components/help-builtin.d.cts

@@ -0,0 +1,22 @@
+import * as _alloy_js_core0 from "@alloy-js/core";
+import { CommandTree } from "@shell-shock/core";
+import { BuiltinFileProps } from "@powerlines/plugin-alloy/typescript/components/builtin-file";
+
+//#region src/components/help-builtin.d.ts
+/**
+ * The `updateVersionCheckFile` handler function declaration code for the Shell Shock project.
+ */
+declare function HelpFunctionDeclaration(): _alloy_js_core0.Children;
+interface HelpBuiltinProps extends Omit<BuiltinFileProps, "id" | "description"> {
+  /**
+   * The command to generate the `help` function declaration for.
+   */
+  command: CommandTree;
+}
+/**
+ * A built-in help module for Shell Shock.
+ */
+declare function HelpBuiltin(props: HelpBuiltinProps): _alloy_js_core0.Children;
+//#endregion
+export { HelpBuiltin, HelpBuiltinProps, HelpFunctionDeclaration };
+//# sourceMappingURL=help-builtin.d.cts.map

package/dist/components/help-builtin.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-builtin.d.cts","names":[],"sources":["../../src/components/help-builtin.tsx"],"mappings":";;;;;;;;iBA0CgB,uBAAA,CAAA,GAAuB,eAAA,CAAA,QAAA;AAAA,UA0BtB,gBAAA,SAAyB,IAAA,CACxC,gBAAA;;;;EAMA,OAAA,EAAS,WAAA;AAAA;;;;iBAMK,WAAA,CAAY,KAAA,EAAO,gBAAA,GAAgB,eAAA,CAAA,QAAA"}

package/dist/components/help-builtin.d.mts

@@ -0,0 +1,22 @@
+import * as _alloy_js_core0 from "@alloy-js/core";
+import { CommandTree } from "@shell-shock/core";
+import { BuiltinFileProps } from "@powerlines/plugin-alloy/typescript/components/builtin-file";
+
+//#region src/components/help-builtin.d.ts
+/**
+ * The `updateVersionCheckFile` handler function declaration code for the Shell Shock project.
+ */
+declare function HelpFunctionDeclaration(): _alloy_js_core0.Children;
+interface HelpBuiltinProps extends Omit<BuiltinFileProps, "id" | "description"> {
+  /**
+   * The command to generate the `help` function declaration for.
+   */
+  command: CommandTree;
+}
+/**
+ * A built-in help module for Shell Shock.
+ */
+declare function HelpBuiltin(props: HelpBuiltinProps): _alloy_js_core0.Children;
+//#endregion
+export { HelpBuiltin, HelpBuiltinProps, HelpFunctionDeclaration };
+//# sourceMappingURL=help-builtin.d.mts.map

package/dist/components/help-builtin.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-builtin.d.mts","names":[],"sources":["../../src/components/help-builtin.tsx"],"mappings":";;;;;;;;iBA0CgB,uBAAA,CAAA,GAAuB,eAAA,CAAA,QAAA;AAAA,UA0BtB,gBAAA,SAAyB,IAAA,CACxC,gBAAA;;;;EAMA,OAAA,EAAS,WAAA;AAAA;;;;iBAMK,WAAA,CAAY,KAAA,EAAO,gBAAA,GAAgB,eAAA,CAAA,QAAA"}

package/dist/components/help-builtin.mjs

@@ -0,0 +1,110 @@
+import { CommandHelpDisplay, VirtualCommandHelpDisplay } from "./display.mjs";
+import { createComponent, memo, mergeProps } from "@alloy-js/core/jsx-runtime";
+import { Show, code, splitProps } from "@alloy-js/core";
+import { getAppTitle, isDynamicPathSegment } from "@shell-shock/core/plugin-utils";
+import defu from "defu";
+import { Spacing } from "@powerlines/plugin-alloy/core/components/spacing";
+import { usePowerlines } from "@powerlines/plugin-alloy/core/contexts/context";
+import { FunctionDeclaration, IfStatement } from "@alloy-js/typescript";
+import { TSDoc, TSDocRemarks, TSDocReturns } from "@powerlines/plugin-alloy/typescript";
+import { BuiltinFile } from "@powerlines/plugin-alloy/typescript/components/builtin-file";
+import { joinPaths } from "@stryke/path";
+
+//#region src/components/help-builtin.tsx
+/**
+* The `updateVersionCheckFile` handler function declaration code for the Shell Shock project.
+*/
+function HelpFunctionDeclaration() {
+	return [createComponent(TSDoc, {
+		heading: "A helper function that updates the version check file.",
+		get children() {
+			return [
+				createComponent(TSDocRemarks, { children: `This function is used to update the version check file with the current timestamp. It can be used in the CLI upgrade command to record the last time a check for updates was performed. The function writes a "version-check.json" file in the data directory, which contains a timestamp of the last check for updates.` }),
+				createComponent(Spacing, {}),
+				createComponent(TSDocReturns, { children: `A promise that resolves to a boolean indicating whether a check for updates is required.` })
+			];
+		}
+	}), createComponent(FunctionDeclaration, {
+		"export": true,
+		async: true,
+		name: "updateVersionCheckFile",
+		returnType: "void",
+		get children() {
+			return [createComponent(IfStatement, {
+				condition: code`!existsSync(paths.data)`,
+				children: code`await mkdir(paths.data, { recursive: true }); `
+			}), code`await writeFile(join(paths.data, "version-check.json"), JSON.stringify({ timestamp: new Date().getTime() }), "utf8"); `];
+		}
+	})];
+}
+/**
+* A built-in help module for Shell Shock.
+*/
+function HelpBuiltin(props) {
+	const [{ command, children }, rest] = splitProps(props, ["command", "children"]);
+	const context = usePowerlines();
+	return createComponent(BuiltinFile, mergeProps({
+		get id() {
+			return joinPaths("help", ...command.segments.filter((segment) => !isDynamicPathSegment(segment)));
+		},
+		get description() {
+			return memo(() => !!command.path)() ? `A collection of utility functions that assist in displaying help information for the ${command.title} command.` : `A collection of utility functions that assist in displaying help information for the ${getAppTitle(context, true)} command-line interface application.`;
+		}
+	}, rest, {
+		get builtinImports() {
+			return defu(rest.builtinImports ?? {}, {
+				utils: ["isUnicodeSupported"],
+				console: [
+					"splitText",
+					"writeLine",
+					"colors",
+					"help",
+					"table"
+				]
+			});
+		},
+		get children() {
+			return [
+				createComponent(FunctionDeclaration, {
+					"export": true,
+					name: "showHelp",
+					get doc() {
+						return `Display help information for the ${command.path ? `${command.title} command` : `${getAppTitle(context, true)} application`}.`;
+					},
+					parameters: [],
+					get children() {
+						return createComponent(Show, {
+							get when() {
+								return !command.isVirtual;
+							},
+							get fallback() {
+								return createComponent(VirtualCommandHelpDisplay, {
+									get options() {
+										return Object.values(command.options);
+									},
+									get commands() {
+										return command.children ?? {};
+									}
+								});
+							},
+							get children() {
+								return createComponent(CommandHelpDisplay, { command });
+							}
+						});
+					}
+				}),
+				createComponent(Spacing, {}),
+				createComponent(Show, {
+					get when() {
+						return Boolean(children);
+					},
+					children
+				})
+			];
+		}
+	}));
+}
+
+//#endregion
+export { HelpBuiltin, HelpFunctionDeclaration };
+//# sourceMappingURL=help-builtin.mjs.map

package/dist/components/help-builtin.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-builtin.mjs","names":[],"sources":["../../src/components/help-builtin.tsx"],"sourcesContent":["/* -------------------------------------------------------------------\n\n                  ⚡ Storm Software - Shell Shock\n\n This code was released as part of the Shell Shock project. Shell Shock\n is maintained by Storm Software under the Apache-2.0 license, and is\n free for commercial and private use. For more information, please visit\n our licensing page at https://stormsoftware.com/licenses/projects/shell-shock.\n\n Website:                  https://stormsoftware.com\n Repository:               https://github.com/storm-software/shell-shock\n Documentation:            https://docs.stormsoftware.com/projects/shell-shock\n Contact:                  https://stormsoftware.com/contact\n\n SPDX-License-Identifier:  Apache-2.0\n\n ------------------------------------------------------------------- */\n\nimport { code, Show, splitProps } from \"@alloy-js/core\";\nimport { FunctionDeclaration, IfStatement } from \"@alloy-js/typescript\";\nimport { Spacing } from \"@powerlines/plugin-alloy/core/components/spacing\";\nimport { usePowerlines } from \"@powerlines/plugin-alloy/core/contexts/context\";\nimport {\n  TSDoc,\n  TSDocRemarks,\n  TSDocReturns\n} from \"@powerlines/plugin-alloy/typescript\";\nimport type { BuiltinFileProps } from \"@powerlines/plugin-alloy/typescript/components/builtin-file\";\nimport { BuiltinFile } from \"@powerlines/plugin-alloy/typescript/components/builtin-file\";\nimport type { CommandTree } from \"@shell-shock/core\";\nimport {\n  getAppTitle,\n  isDynamicPathSegment\n} from \"@shell-shock/core/plugin-utils\";\nimport { joinPaths } from \"@stryke/path\";\nimport defu from \"defu\";\nimport type { HelpPluginContext } from \"../types\";\nimport { CommandHelpDisplay, VirtualCommandHelpDisplay } from \"./display\";\n\n/**\n * The `updateVersionCheckFile` handler function declaration code for the Shell Shock project.\n */\nexport function HelpFunctionDeclaration() {\n  return (\n    <>\n      <TSDoc heading=\"A helper function that updates the version check file.\">\n        <TSDocRemarks>\n          {`This function is used to update the version check file with the current timestamp. It can be used in the CLI upgrade command to record the last time a check for updates was performed. The function writes a \"version-check.json\" file in the data directory, which contains a timestamp of the last check for updates.`}\n        </TSDocRemarks>\n        <Spacing />\n        <TSDocReturns>\n          {`A promise that resolves to a boolean indicating whether a check for updates is required.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        async\n        name=\"updateVersionCheckFile\"\n        returnType=\"void\">\n        <IfStatement condition={code`!existsSync(paths.data)`}>\n          {code`await mkdir(paths.data, { recursive: true }); `}\n        </IfStatement>\n        {code`await writeFile(join(paths.data, \"version-check.json\"), JSON.stringify({ timestamp: new Date().getTime() }), \"utf8\"); `}\n      </FunctionDeclaration>\n    </>\n  );\n}\n\nexport interface HelpBuiltinProps extends Omit<\n  BuiltinFileProps,\n  \"id\" | \"description\"\n> {\n  /**\n   * The command to generate the `help` function declaration for.\n   */\n  command: CommandTree;\n}\n\n/**\n * A built-in help module for Shell Shock.\n */\nexport function HelpBuiltin(props: HelpBuiltinProps) {\n  const [{ command, children }, rest] = splitProps(props, [\n    \"command\",\n    \"children\"\n  ]);\n  const context = usePowerlines<HelpPluginContext>();\n\n  return (\n    <BuiltinFile\n      id={joinPaths(\n        \"help\",\n        ...command.segments.filter(segment => !isDynamicPathSegment(segment))\n      )}\n      description={\n        command.path\n          ? `A collection of utility functions that assist in displaying help information for the ${\n              command.title\n            } command.`\n          : `A collection of utility functions that assist in displaying help information for the ${getAppTitle(\n              context,\n              true\n            )} command-line interface application.`\n      }\n      {...rest}\n      builtinImports={defu(rest.builtinImports ?? {}, {\n        utils: [\"isUnicodeSupported\"],\n        console: [\"splitText\", \"writeLine\", \"colors\", \"help\", \"table\"]\n      })}>\n      <FunctionDeclaration\n        export\n        name=\"showHelp\"\n        doc={`Display help information for the ${\n          command.path\n            ? `${command.title} command`\n            : `${getAppTitle(context, true)} application`\n        }.`}\n        parameters={[]}>\n        <Show\n          when={!command.isVirtual}\n          fallback={\n            <VirtualCommandHelpDisplay\n              options={Object.values(command.options)}\n              commands={command.children ?? {}}\n            />\n          }>\n          <CommandHelpDisplay command={command} />\n        </Show>\n      </FunctionDeclaration>\n      <Spacing />\n      <Show when={Boolean(children)}>{children}</Show>\n    </BuiltinFile>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAoCA,SAAc,0BAA4B;AAC1C,QAAS,CAAA,gBAAmB,OAAC;;EAE3B,IAAA,WAAA;AACI,UAAE;IAAA,gBAAwB,cAAQ,EACtC,UAAA,4TACK,CAAA;IAAA,gBAAS,SAAA,EAAuB,CAAC;IAAE,gBAAA,cAAA,EAClC,UAAC,4FACJ,CAAA;IAAA;;EAEF,CAAC,EAAE,gBAAe,qBAAA;EACjB,UAAQ;EACR,OAAM;EACN,MAAK;EACL,YAAK;EACL,IAAI,WAAM;AACR,UAAI,CAAA,gBAAY,aAAA;IACd,WAAK,IAAA;IACN,UAAA,IAAA;IACA,CAAC,EAAA,IAAA,yHAAA;;EAEL,CAAC,CAAC;;;;;AAYL,SAAE,YAAgB,OAAA;CAChB,MAAM,CAAC,EACP,SACE,YACC,QAAI,WAAW,OAAS,CAAG,WAAQ,WAAS,CAAA;CAC/C,MAAE,UAAA,eAAA;AACF,QAAO,gBAAa,aAAA,WAAA;EACtB,IAAA,KAAA;;;EAGI,IAAC,cAAc;AACjB,UAAA,WAAA,CAAA,CAAA,QAAA,KAAA,EAAA,GAAA,wFAAA,QAAA,MAAA,aAAA,wFAAA,YAAA,SAAA,KAAA,CAAA;;EAEA,EAAA,MAAS;EACP,IAAC,iBAAQ;AACR,UAAQ,KAAA,KAAA,kBAAA,EAAA,EAAA;IACT,OAAA,CAAA,qBAAA;IACI,SAAS;KAAC;KAAa;KAAC;KAAoB;KAAA;KAAA;;;EAGhD,IAAC,WAAA;AACC,UAAI;IAAA,gBAAS,qBAAA;KACX,UAAM;KACN,MAAG;KACJ,IAAA,MAAA;AACD,aAAW,oCAAC,QAAA,OAAA,GAAA,QAAA,MAAA,YAAA,GAAA,YAAA,SAAA,KAAA,CAAA,cAAA;;KAEV,YAAO,EAAA;KACP,IAAI,WAAU;AACZ,aAAI,gBAAQ,MAAA;OACV,IAAG,OAAA;AACD,eAAO,CAAA,QAAA;;OAET,IAAG,WAAY;AACrB,eAAA,gBAAA,2BAAA;SACQ,IAAA,UAAA;AACR,iBAAgB,OAAU,OAAA,QAAe,QAAO;;SAEtC,IAAG,WAAY;AACtB,iBAAA,QAAA,YAAA,EAAA;;SAED,CAAA;;OAEI,IAAE,WAAa;AACjB,eAAQ,gBAAA,oBAAA,EACO,SACV,CAAC;;OAER,CAAA;;KAED,CAAC;IAAE,gBAAe,SAAS,EAAA,CAAA;IAAA,gBAAA,MAAA;KAC1B,IAAE,OAAS;AACT,aAAG,QAAA,SAAA;;KAEC;KACP,CAAC;IAAC;;EAEN,CAAC,CAAC"}