@shell-shock/core 0.16.1 → 0.16.2

package/dist/components/state-builtin.cjs

@@ -43,7 +43,7 @@ function GlobalTypeDefinitions() {
 			typeParameters: [{
 				name: "THandler",
 				extends: "(...params: any[]) => any",
-				default: "(...params: any[]) => any"
+				default: "any"
 			}],
 			get children() {
 				return [
@@ -478,8 +478,8 @@ return result;`;
 			name: "withCommand",
 			typeParameters: [{
 				name: "THandler",
-				extends: "(...params: any[]) => any",
-				default: "(...params: any[]) => any"
+				extends: "(this: CommandContext, ...params: any[]) => any",
+				default: "(this: CommandContext, ...params: any[]) => any"
 			}],
 			parameters: [
 				{
@@ -503,7 +503,7 @@ return result;`;
 			children: _alloy_js_core.code`setState({ status: "preparing", isError: false });
 
         const ctx = { path, segments, params } as CommandContext<THandler>;
-        const result = await Promise.resolve(unstable_commandStore.run(ctx, Reflect.apply(ctx, handler, params)));
+        const result = await Promise.resolve(unstable_commandStore.run(ctx, Reflect.apply(handler, ctx, params)));
         if (result instanceof Error || (typeof result === "object" && ((result as { error: unknown }).error instanceof Error || typeof (result as { error: unknown }).error === "string"))) {
           setState({ status: "completed", isError: true });
           return { error: result instanceof Error ? result : (result as { error: Error | string }).error };
@@ -524,7 +524,13 @@ function StateBuiltin(props) {
 		description: "A module that provides context hooks and utilities for accessing the application state."
 	}, rest, {
 		get imports() {
-			return (0, defu.default)(rest.imports ?? {}, { "node:async_hooks": ["AsyncLocalStorage"] });
+			return (0, defu.default)(rest.imports ?? {}, {
+				"node:async_hooks": ["AsyncLocalStorage"],
+				"node:crypto": ["randomUUID"]
+			});
+		},
+		get builtinImports() {
+			return (0, defu.default)(rest.builtinImports ?? {}, { env: ["isCI"] });
 		},
 		get children() {
 			return [

package/dist/components/state-builtin.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"state-builtin.cjs","names":[],"sources":["../../src/components/state-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, computed, For, Show, splitProps } from \"@alloy-js/core\";\nimport {\n  FunctionDeclaration,\n  InterfaceDeclaration,\n  InterfaceMember,\n  TypeDeclaration,\n  VarDeclaration\n} from \"@alloy-js/typescript\";\nimport { Spacing } from \"@powerlines/plugin-alloy/core/components/spacing\";\nimport { usePowerlines } from \"@powerlines/plugin-alloy/core/contexts/context\";\nimport type { BuiltinFileProps } from \"@powerlines/plugin-alloy/typescript/components/builtin-file\";\nimport { BuiltinFile } from \"@powerlines/plugin-alloy/typescript/components/builtin-file\";\nimport {\n  TSDoc,\n  TSDocInternal,\n  TSDocLink,\n  TSDocParam,\n  TSDocRemarks,\n  TSDocReturns\n} from \"@powerlines/plugin-alloy/typescript/components/tsdoc\";\nimport defu from \"defu\";\nimport { computedOptions } from \"../contexts/options\";\nimport { getAppBin } from \"../plugin-utils\";\nimport { getAppTitle } from \"../plugin-utils/context-helpers\";\nimport type { Context } from \"../types\";\nimport { OptionsMember } from \"./options-parser-logic\";\n\nexport function GlobalTypeDefinitions() {\n  const context = usePowerlines<Context>();\n\n  const options = computed(() => computedOptions(context.options));\n\n  return (\n    <>\n      <TSDoc\n        heading={`An object representing the global options available for every command in the ${getAppTitle(\n          context,\n          true\n        )} command-line application.`}\n      />\n      <InterfaceDeclaration export name=\"GlobalOptions\">\n        <For each={Object.values(options.value)} hardline>\n          {option => <OptionsMember option={option} />}\n        </For>\n      </InterfaceDeclaration>\n      <Spacing />\n      <TSDoc heading=\"The context object for the current command execution, containing the command path and segments.\" />\n      <InterfaceDeclaration\n        export\n        name=\"CommandContext\"\n        typeParameters={[\n          {\n            name: \"THandler\",\n            extends: \"(...params: any[]) => any\",\n            default: \"(...params: any[]) => any\"\n          }\n        ]}>\n        <TSDoc\n          heading={`The full command path as a string. For example, if the user runs \\`${getAppBin(\n            context\n          )} foo bar\\`, this would be \\`foo bar\\`. This is useful for commands that need to know their full invocation path, such as for help text or for commands that have dynamic behavior based on their position in the command hierarchy.`}\n        />\n        <InterfaceMember name=\"path\" type=\"string\" />\n        <Spacing />\n        <TSDoc\n          heading={`An array of command path segments. For example, if the user runs \\`${getAppBin(\n            context\n          )} foo bar\\`, this would be \\`[\"foo\", \"bar\"]\\`. This is useful for commands that need to know their individual path segments, such as for dynamic routing or for commands that have behavior based on specific segments in the command hierarchy.`}\n        />\n        <InterfaceMember name=\"segments\" type=\"string[]\" />\n        <Spacing />\n        <TSDoc\n          heading={`The parameters for the current command's handler function.`}\n        />\n        <InterfaceMember name=\"params\" type=\"Parameters<THandler>\" />\n      </InterfaceDeclaration>\n      <Spacing />\n      <TypeDeclaration export name=\"GlobalContextStatus\">\n        {code`\"initializing\" | \"preparing\" | \"executing\" | \"completed\"`}\n      </TypeDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`The state object for the ${getAppTitle(context)} application context.`}\n      />\n      <InterfaceDeclaration export name=\"GlobalContextState\">\n        <TSDoc heading=\"The unique identifier for the current execution context.\" />\n        <InterfaceMember name=\"executionId\" type=\"string\" />\n        <Spacing />\n        <TSDoc heading=\"The status of the current execution context.\" />\n        <InterfaceMember name=\"status\" type=\"GlobalContextStatus\" />\n        <Spacing />\n        <TSDoc heading=\"Indicates whether the current execution context has encountered an error.\" />\n        <InterfaceMember name=\"isError\" type=\"boolean\" />\n        <Spacing />\n        <TSDoc heading=\"A map containing arbitrary data associated with the current execution context.\" />\n        <InterfaceMember name=\"meta\" type=\"Map<string, unknown>\" />\n      </InterfaceDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`The context object for the ${getAppTitle(context)} application.`}\n      />\n      <InterfaceDeclaration export name=\"GlobalContext\">\n        <TSDoc heading=\"The global options shared across all commands in the application.\" />\n        <InterfaceMember name=\"options\" type=\"GlobalOptions\" />\n        <Spacing />\n        <TSDoc heading=\"The raw command-line arguments passed to the application.\" />\n        <InterfaceMember name=\"inputArgs\" type=\"string[]\" />\n        <Spacing />\n        <TSDoc heading=\"The state of the current execution context.\" />\n        <InterfaceMember name=\"state\" type=\"GlobalContextState\" />\n      </InterfaceDeclaration>\n    </>\n  );\n}\n\n/**\n * Generates utilities for detecting terminal color support.\n */\nexport function ArgsUtilities() {\n  return (\n    <>\n      <TSDoc heading=\"Retrieves the command-line arguments from Deno or Node.js environments.\">\n        <TSDocRemarks>\n          {`This function is only intended for internal use. Please use \\`useArgs()\\` instead.`}\n        </TSDocRemarks>\n        <Spacing />\n        <TSDocInternal />\n        <Spacing />\n        <TSDocReturns>\n          {`An array of command-line arguments from Deno or Node.js environments.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration name=\"getInputArgs\" returnType=\"string[]\">\n        {code`return ((globalThis as { Deno?: { args: string[] } })?.Deno?.args ?? process.argv ?? []) as string[];`}\n      </FunctionDeclaration>\n    </>\n  );\n}\n\nexport function ContextUtilities() {\n  const context = usePowerlines<Context>();\n\n  return (\n    <>\n      <Spacing />\n\n      <TSDoc\n        heading={`The global ${getAppTitle(context)} application context store instance.`}>\n        <TSDocInternal />\n      </TSDoc>\n      <VarDeclaration export const name=\"unstable_globalStore\">\n        {code`  new AsyncLocalStorage<GlobalContext>({ name: \"globalStore\" }); `}\n      </VarDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`Get the ${getAppTitle(\n          context\n        )} application context for the current application.`}>\n        <TSDocParam name=\"options\">\n          {`The options to use when getting the context. This can include parameters for how to handle missing contexts, such as whether to throw an error or return undefined. By default, if the context is not available, this function will return undefined.`}\n        </TSDocParam>\n        <TSDocReturns>\n          {`The ${getAppTitle(\n            context\n          )} application context for the current application or undefined if the context is not available.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useGlobal\" returnType=\"GlobalContext\">\n        {code`return unstable_globalStore.getStore() as GlobalContext;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the command-line arguments from the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocReturns>\n          {\"An array of command-line arguments from the application context.\"}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useArgs\" returnType=\"string[]\">\n        {code`return useGlobal()?.inputArgs ?? getInputArgs();`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the state of the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocReturns>{\"The state of the application context.\"}</TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"useState\"\n        returnType=\"GlobalContextState\">\n        {code`return useGlobal()?.state;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility function to update the state of the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocRemarks>\n          {`This function will throw an error if the global context is not available, so it should only be used within a valid context scope, such as within a command handler or within the \\`withGlobal()\\` function.`}\n        </TSDocRemarks>\n        <Spacing />\n        <TSDocParam name=\"update\">\n          {`The new state or a function that receives the previous state and returns the new state. This allows for both direct state updates and functional updates based on the previous state.`}\n        </TSDocParam>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"setState\"\n        parameters={[\n          {\n            name: \"update\",\n            type: \"Partial<GlobalContextState> | ((prev: GlobalContextState) => GlobalContextState)\"\n          }\n        ]}>\n        {code`const prev = useGlobal()?.state;\n        if (!prev) {\n          throw new Error(\n            \\`The ${getAppTitle(\n              context\n            )} application context is not available. Make sure to call setState() within a valid context scope.\\`\n          );\n        }\n\n        useGlobal().state = typeof update === \"function\" ? update(prev) : { ...prev, ...update }; `}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the execution ID of the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocReturns>\n          {\"The execution ID of the application context.\"}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useExecutionId\" returnType=\"string\">\n        {code`return useState().executionId;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the metadata of the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocReturns>\n          {\"The metadata of the application context.\"}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"useMeta\"\n        returnType=\"Map<string, unknown>\">\n        {code`return useState().meta;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the current status of the ${getAppTitle(\n          context\n        )} application.`}>\n        <TSDocReturns>{\"The current status of the application.\"}</TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"useStatus\"\n        returnType=\"GlobalContextStatus\">\n        {code`return useState().status;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`The global ${getAppTitle(context)} - command context store instance.`}>\n        <TSDocInternal />\n      </TSDoc>\n      <VarDeclaration export name=\"unstable_commandStore\">\n        {code`new AsyncLocalStorage<CommandContext>({ name: \"commandStore\" });`}\n      </VarDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`Get the ${getAppTitle(context)} - command context for the current application.`}>\n        <TSDocReturns>\n          {`The ${getAppTitle(context)} - command context for the current application.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useCommand\" returnType=\"CommandContext\">\n        {code`const result = unstable_commandStore.getStore();\nif (!result) {\n  throw new Error(\n    \\`The ${getAppTitle(context)} - command context is not available. Make sure to call useCommand() within a valid context scope.\\`\n  );\n}\nreturn result;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc heading=\"A utility hook function to get the individual segments of the current command path.\">\n        <TSDocReturns>{\"An array of command path segments.\"}</TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useSegments\" returnType=\"string[]\">\n        {code`return useCommand().segments;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc heading=\"A utility hook function to get the full command path as a string.\">\n        <TSDocReturns>\n          {`The full command path as a string. For example, if the user runs \\`${getAppBin(\n            context\n          )} foo bar\\`, this would return \\`\"foo bar\"\\`. This is useful for commands that need to know their full invocation path, such as for help text or for commands that have dynamic behavior based on their position in the command hierarchy.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"usePath\" returnType=\"string\">\n        {code`return useCommand().path;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc heading=\"Checks if a specific flag is present in the command-line arguments.\">\n        <TSDocLink>\n          {\"https://github.com/sindresorhus/has-flag/blob/main/index.js\"}\n        </TSDocLink>\n        <TSDocParam name=\"flag\">\n          {\n            'The flag (or an array of flags/aliases) to check for, e.g., \"color\", \"no-color\".'\n          }\n        </TSDocParam>\n        <TSDocParam name=\"argv\">\n          {\n            \"The command-line arguments to check against. Defaults to global Deno args or process args.\"\n          }\n        </TSDocParam>\n        <TSDocReturns>\n          {\"True if the flag is present, false otherwise.\"}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"hasFlag\"\n        parameters={[\n          { name: \"flag\", type: \"string | string[]\" },\n          {\n            name: \"argv\",\n            type: \"string[]\",\n            default: \"useArgs()\"\n          }\n        ]}>\n        <VarDeclaration\n          const\n          name=\"position\"\n          type=\"number\"\n          initializer={code`(Array.isArray(flag) ? flag : [flag]).reduce((ret, f) => {\n            const pos = argv.findIndex(arg => (f.startsWith(\"-\") ? \"\" : (f.length === 1 ? \"-\" : \"--\") + f)?.toLowerCase() === arg?.toLowerCase() || arg?.toLowerCase().startsWith((f.length === 1 ? \"-\" : \"--\") + f + \"=\"));\n            return pos !== -1 ? pos : ret;\n          }, -1);`}\n        />\n        <hbr />\n        {code`return position !== -1 && argv.indexOf(\"--\") === -1 || position < argv.indexOf(\"--\");`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc heading=\"A utility function to determine if the help flag is present or if the command is in an error state during preparation.\">\n        <TSDocReturns>\n          {`True if the help flag is present or if the command is in an error state during preparation, false otherwise. This can be used to conditionally display help text or to alter command behavior when the user is likely seeking help.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"isHelp\" returnType=\"boolean\">\n        {code`return !isCI && (hasFlag([\"help\", \"h\", \"?\"]) || (useStatus() === \"preparing\" && useState().isError)); `}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility function to wrap the ${getAppTitle(\n          context\n        )} application within the global context scope.`}>\n        <TSDocParam name=\"handler\">\n          {`The callback function to run within the global context scope. This function will receive the global context as its argument, allowing it to access any properties or utilities defined on the context. The callback function can be asynchronous and can return a value or a promise.`}\n        </TSDocParam>\n        <TSDocReturns>\n          {`The result of the callback function, which can be a value or a promise that resolves to a value.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        async\n        name=\"withGlobal\"\n        parameters={[{ name: \"handler\", type: \"() => any\" }]}\n        returnType=\"Promise<void>\">\n        {code`\n        return unstable_globalStore.run({ options: {} as unknown as GlobalOptions, inputArgs: getInputArgs(), state: { executionId: randomUUID(), status: \"initializing\", isError: false, meta: new Map() } as GlobalContextState }, handler);`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility function to wrap a ${getAppTitle(\n          context\n        )} application command handler within the command context scope.`}>\n        <TSDocParam name=\"handler\">\n          {`The callback function to run within the command context scope. This function will receive the command context as its argument, allowing it to access any properties or utilities defined on the context. The callback function can be asynchronous and can return a value or a promise.`}\n        </TSDocParam>\n        <TSDocReturns>\n          {`The result of the callback function, which can be a value or a promise that resolves to a value.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        async\n        name=\"withCommand\"\n        typeParameters={[\n          {\n            name: \"THandler\",\n            extends: \"(...params: any[]) => any\",\n            default: \"(...params: any[]) => any\"\n          }\n        ]}\n        parameters={[\n          { name: \"path\", type: \"string\" },\n          { name: \"segments\", type: \"string[]\" },\n          { name: \"params\", type: \"Parameters<THandler>\" },\n          { name: \"handler\", type: \"THandler\" }\n        ]}\n        returnType=\"Promise<{ error: string | Error | null }>\">\n        {code`setState({ status: \"preparing\", isError: false });\n\n        const ctx = { path, segments, params } as CommandContext<THandler>;\n        const result = await Promise.resolve(unstable_commandStore.run(ctx, Reflect.apply(ctx, handler, params)));\n        if (result instanceof Error || (typeof result === \"object\" && ((result as { error: unknown }).error instanceof Error || typeof (result as { error: unknown }).error === \"string\"))) {\n          setState({ status: \"completed\", isError: true });\n          return { error: result instanceof Error ? result : (result as { error: Error | string }).error };\n        }\n\n        setState({ status: \"completed\", isError: false });\n        return { error: null }; `}\n      </FunctionDeclaration>\n    </>\n  );\n}\n\nexport interface StateBuiltinProps extends Omit<\n  BuiltinFileProps,\n  \"id\" | \"description\"\n> {}\n\n/**\n * A built-in module for handling application state utilities in Shell Shock.\n */\nexport function StateBuiltin(props: StateBuiltinProps) {\n  const [{ children }, rest] = splitProps(props, [\"children\"]);\n\n  return (\n    <BuiltinFile\n      id=\"state\"\n      description=\"A module that provides context hooks and utilities for accessing the application state.\"\n      {...rest}\n      imports={defu(rest.imports ?? {}, {\n        \"node:async_hooks\": [\"AsyncLocalStorage\"]\n      })}>\n      <GlobalTypeDefinitions />\n      <Spacing />\n      <ArgsUtilities />\n      <Spacing />\n      <ContextUtilities />\n      <Spacing />\n      <Show when={Boolean(children)}>{children}</Show>\n    </BuiltinFile>\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"state-builtin.cjs","names":[],"sources":["../../src/components/state-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, computed, For, Show, splitProps } from \"@alloy-js/core\";\nimport {\n  FunctionDeclaration,\n  InterfaceDeclaration,\n  InterfaceMember,\n  TypeDeclaration,\n  VarDeclaration\n} from \"@alloy-js/typescript\";\nimport { Spacing } from \"@powerlines/plugin-alloy/core/components/spacing\";\nimport { usePowerlines } from \"@powerlines/plugin-alloy/core/contexts/context\";\nimport type { BuiltinFileProps } from \"@powerlines/plugin-alloy/typescript/components/builtin-file\";\nimport { BuiltinFile } from \"@powerlines/plugin-alloy/typescript/components/builtin-file\";\nimport {\n  TSDoc,\n  TSDocInternal,\n  TSDocLink,\n  TSDocParam,\n  TSDocRemarks,\n  TSDocReturns\n} from \"@powerlines/plugin-alloy/typescript/components/tsdoc\";\nimport defu from \"defu\";\nimport { computedOptions } from \"../contexts/options\";\nimport { getAppBin } from \"../plugin-utils\";\nimport { getAppTitle } from \"../plugin-utils/context-helpers\";\nimport type { Context } from \"../types\";\nimport { OptionsMember } from \"./options-parser-logic\";\n\nexport function GlobalTypeDefinitions() {\n  const context = usePowerlines<Context>();\n\n  const options = computed(() => computedOptions(context.options));\n\n  return (\n    <>\n      <TSDoc\n        heading={`An object representing the global options available for every command in the ${getAppTitle(\n          context,\n          true\n        )} command-line application.`}\n      />\n      <InterfaceDeclaration export name=\"GlobalOptions\">\n        <For each={Object.values(options.value)} hardline>\n          {option => <OptionsMember option={option} />}\n        </For>\n      </InterfaceDeclaration>\n      <Spacing />\n      <TSDoc heading=\"The context object for the current command execution, containing the command path and segments.\" />\n      <InterfaceDeclaration\n        export\n        name=\"CommandContext\"\n        typeParameters={[\n          {\n            name: \"THandler\",\n            extends: \"(...params: any[]) => any\",\n            default: \"any\"\n          }\n        ]}>\n        <TSDoc\n          heading={`The full command path as a string. For example, if the user runs \\`${getAppBin(\n            context\n          )} foo bar\\`, this would be \\`foo bar\\`. This is useful for commands that need to know their full invocation path, such as for help text or for commands that have dynamic behavior based on their position in the command hierarchy.`}\n        />\n        <InterfaceMember name=\"path\" type=\"string\" />\n        <Spacing />\n        <TSDoc\n          heading={`An array of command path segments. For example, if the user runs \\`${getAppBin(\n            context\n          )} foo bar\\`, this would be \\`[\"foo\", \"bar\"]\\`. This is useful for commands that need to know their individual path segments, such as for dynamic routing or for commands that have behavior based on specific segments in the command hierarchy.`}\n        />\n        <InterfaceMember name=\"segments\" type=\"string[]\" />\n        <Spacing />\n        <TSDoc\n          heading={`The parameters for the current command's handler function.`}\n        />\n        <InterfaceMember name=\"params\" type=\"Parameters<THandler>\" />\n      </InterfaceDeclaration>\n      <Spacing />\n      <TypeDeclaration export name=\"GlobalContextStatus\">\n        {code`\"initializing\" | \"preparing\" | \"executing\" | \"completed\"`}\n      </TypeDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`The state object for the ${getAppTitle(context)} application context.`}\n      />\n      <InterfaceDeclaration export name=\"GlobalContextState\">\n        <TSDoc heading=\"The unique identifier for the current execution context.\" />\n        <InterfaceMember name=\"executionId\" type=\"string\" />\n        <Spacing />\n        <TSDoc heading=\"The status of the current execution context.\" />\n        <InterfaceMember name=\"status\" type=\"GlobalContextStatus\" />\n        <Spacing />\n        <TSDoc heading=\"Indicates whether the current execution context has encountered an error.\" />\n        <InterfaceMember name=\"isError\" type=\"boolean\" />\n        <Spacing />\n        <TSDoc heading=\"A map containing arbitrary data associated with the current execution context.\" />\n        <InterfaceMember name=\"meta\" type=\"Map<string, unknown>\" />\n      </InterfaceDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`The context object for the ${getAppTitle(context)} application.`}\n      />\n      <InterfaceDeclaration export name=\"GlobalContext\">\n        <TSDoc heading=\"The global options shared across all commands in the application.\" />\n        <InterfaceMember name=\"options\" type=\"GlobalOptions\" />\n        <Spacing />\n        <TSDoc heading=\"The raw command-line arguments passed to the application.\" />\n        <InterfaceMember name=\"inputArgs\" type=\"string[]\" />\n        <Spacing />\n        <TSDoc heading=\"The state of the current execution context.\" />\n        <InterfaceMember name=\"state\" type=\"GlobalContextState\" />\n      </InterfaceDeclaration>\n    </>\n  );\n}\n\n/**\n * Generates utilities for detecting terminal color support.\n */\nexport function ArgsUtilities() {\n  return (\n    <>\n      <TSDoc heading=\"Retrieves the command-line arguments from Deno or Node.js environments.\">\n        <TSDocRemarks>\n          {`This function is only intended for internal use. Please use \\`useArgs()\\` instead.`}\n        </TSDocRemarks>\n        <Spacing />\n        <TSDocInternal />\n        <Spacing />\n        <TSDocReturns>\n          {`An array of command-line arguments from Deno or Node.js environments.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration name=\"getInputArgs\" returnType=\"string[]\">\n        {code`return ((globalThis as { Deno?: { args: string[] } })?.Deno?.args ?? process.argv ?? []) as string[];`}\n      </FunctionDeclaration>\n    </>\n  );\n}\n\nexport function ContextUtilities() {\n  const context = usePowerlines<Context>();\n\n  return (\n    <>\n      <Spacing />\n\n      <TSDoc\n        heading={`The global ${getAppTitle(context)} application context store instance.`}>\n        <TSDocInternal />\n      </TSDoc>\n      <VarDeclaration export const name=\"unstable_globalStore\">\n        {code`  new AsyncLocalStorage<GlobalContext>({ name: \"globalStore\" }); `}\n      </VarDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`Get the ${getAppTitle(\n          context\n        )} application context for the current application.`}>\n        <TSDocParam name=\"options\">\n          {`The options to use when getting the context. This can include parameters for how to handle missing contexts, such as whether to throw an error or return undefined. By default, if the context is not available, this function will return undefined.`}\n        </TSDocParam>\n        <TSDocReturns>\n          {`The ${getAppTitle(\n            context\n          )} application context for the current application or undefined if the context is not available.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useGlobal\" returnType=\"GlobalContext\">\n        {code`return unstable_globalStore.getStore() as GlobalContext;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the command-line arguments from the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocReturns>\n          {\"An array of command-line arguments from the application context.\"}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useArgs\" returnType=\"string[]\">\n        {code`return useGlobal()?.inputArgs ?? getInputArgs();`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the state of the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocReturns>{\"The state of the application context.\"}</TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"useState\"\n        returnType=\"GlobalContextState\">\n        {code`return useGlobal()?.state;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility function to update the state of the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocRemarks>\n          {`This function will throw an error if the global context is not available, so it should only be used within a valid context scope, such as within a command handler or within the \\`withGlobal()\\` function.`}\n        </TSDocRemarks>\n        <Spacing />\n        <TSDocParam name=\"update\">\n          {`The new state or a function that receives the previous state and returns the new state. This allows for both direct state updates and functional updates based on the previous state.`}\n        </TSDocParam>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"setState\"\n        parameters={[\n          {\n            name: \"update\",\n            type: \"Partial<GlobalContextState> | ((prev: GlobalContextState) => GlobalContextState)\"\n          }\n        ]}>\n        {code`const prev = useGlobal()?.state;\n        if (!prev) {\n          throw new Error(\n            \\`The ${getAppTitle(\n              context\n            )} application context is not available. Make sure to call setState() within a valid context scope.\\`\n          );\n        }\n\n        useGlobal().state = typeof update === \"function\" ? update(prev) : { ...prev, ...update }; `}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the execution ID of the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocReturns>\n          {\"The execution ID of the application context.\"}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useExecutionId\" returnType=\"string\">\n        {code`return useState().executionId;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the metadata of the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocReturns>\n          {\"The metadata of the application context.\"}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"useMeta\"\n        returnType=\"Map<string, unknown>\">\n        {code`return useState().meta;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the current status of the ${getAppTitle(\n          context\n        )} application.`}>\n        <TSDocReturns>{\"The current status of the application.\"}</TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"useStatus\"\n        returnType=\"GlobalContextStatus\">\n        {code`return useState().status;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`The global ${getAppTitle(context)} - command context store instance.`}>\n        <TSDocInternal />\n      </TSDoc>\n      <VarDeclaration export name=\"unstable_commandStore\">\n        {code`new AsyncLocalStorage<CommandContext>({ name: \"commandStore\" });`}\n      </VarDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`Get the ${getAppTitle(context)} - command context for the current application.`}>\n        <TSDocReturns>\n          {`The ${getAppTitle(context)} - command context for the current application.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useCommand\" returnType=\"CommandContext\">\n        {code`const result = unstable_commandStore.getStore();\nif (!result) {\n  throw new Error(\n    \\`The ${getAppTitle(context)} - command context is not available. Make sure to call useCommand() within a valid context scope.\\`\n  );\n}\nreturn result;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc heading=\"A utility hook function to get the individual segments of the current command path.\">\n        <TSDocReturns>{\"An array of command path segments.\"}</TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useSegments\" returnType=\"string[]\">\n        {code`return useCommand().segments;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc heading=\"A utility hook function to get the full command path as a string.\">\n        <TSDocReturns>\n          {`The full command path as a string. For example, if the user runs \\`${getAppBin(\n            context\n          )} foo bar\\`, this would return \\`\"foo bar\"\\`. This is useful for commands that need to know their full invocation path, such as for help text or for commands that have dynamic behavior based on their position in the command hierarchy.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"usePath\" returnType=\"string\">\n        {code`return useCommand().path;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc heading=\"Checks if a specific flag is present in the command-line arguments.\">\n        <TSDocLink>\n          {\"https://github.com/sindresorhus/has-flag/blob/main/index.js\"}\n        </TSDocLink>\n        <TSDocParam name=\"flag\">\n          {\n            'The flag (or an array of flags/aliases) to check for, e.g., \"color\", \"no-color\".'\n          }\n        </TSDocParam>\n        <TSDocParam name=\"argv\">\n          {\n            \"The command-line arguments to check against. Defaults to global Deno args or process args.\"\n          }\n        </TSDocParam>\n        <TSDocReturns>\n          {\"True if the flag is present, false otherwise.\"}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"hasFlag\"\n        parameters={[\n          { name: \"flag\", type: \"string | string[]\" },\n          {\n            name: \"argv\",\n            type: \"string[]\",\n            default: \"useArgs()\"\n          }\n        ]}>\n        <VarDeclaration\n          const\n          name=\"position\"\n          type=\"number\"\n          initializer={code`(Array.isArray(flag) ? flag : [flag]).reduce((ret, f) => {\n            const pos = argv.findIndex(arg => (f.startsWith(\"-\") ? \"\" : (f.length === 1 ? \"-\" : \"--\") + f)?.toLowerCase() === arg?.toLowerCase() || arg?.toLowerCase().startsWith((f.length === 1 ? \"-\" : \"--\") + f + \"=\"));\n            return pos !== -1 ? pos : ret;\n          }, -1);`}\n        />\n        <hbr />\n        {code`return position !== -1 && argv.indexOf(\"--\") === -1 || position < argv.indexOf(\"--\");`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc heading=\"A utility function to determine if the help flag is present or if the command is in an error state during preparation.\">\n        <TSDocReturns>\n          {`True if the help flag is present or if the command is in an error state during preparation, false otherwise. This can be used to conditionally display help text or to alter command behavior when the user is likely seeking help.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"isHelp\" returnType=\"boolean\">\n        {code`return !isCI && (hasFlag([\"help\", \"h\", \"?\"]) || (useStatus() === \"preparing\" && useState().isError)); `}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility function to wrap the ${getAppTitle(\n          context\n        )} application within the global context scope.`}>\n        <TSDocParam name=\"handler\">\n          {`The callback function to run within the global context scope. This function will receive the global context as its argument, allowing it to access any properties or utilities defined on the context. The callback function can be asynchronous and can return a value or a promise.`}\n        </TSDocParam>\n        <TSDocReturns>\n          {`The result of the callback function, which can be a value or a promise that resolves to a value.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        async\n        name=\"withGlobal\"\n        parameters={[{ name: \"handler\", type: \"() => any\" }]}\n        returnType=\"Promise<void>\">\n        {code`\n        return unstable_globalStore.run({ options: {} as unknown as GlobalOptions, inputArgs: getInputArgs(), state: { executionId: randomUUID(), status: \"initializing\", isError: false, meta: new Map() } as GlobalContextState }, handler);`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility function to wrap a ${getAppTitle(\n          context\n        )} application command handler within the command context scope.`}>\n        <TSDocParam name=\"handler\">\n          {`The callback function to run within the command context scope. This function will receive the command context as its argument, allowing it to access any properties or utilities defined on the context. The callback function can be asynchronous and can return a value or a promise.`}\n        </TSDocParam>\n        <TSDocReturns>\n          {`The result of the callback function, which can be a value or a promise that resolves to a value.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        async\n        name=\"withCommand\"\n        typeParameters={[\n          {\n            name: \"THandler\",\n            extends: \"(this: CommandContext, ...params: any[]) => any\",\n            default: \"(this: CommandContext, ...params: any[]) => any\"\n          }\n        ]}\n        parameters={[\n          { name: \"path\", type: \"string\" },\n          { name: \"segments\", type: \"string[]\" },\n          { name: \"params\", type: \"Parameters<THandler>\" },\n          { name: \"handler\", type: \"THandler\" }\n        ]}\n        returnType=\"Promise<{ error: string | Error | null }>\">\n        {code`setState({ status: \"preparing\", isError: false });\n\n        const ctx = { path, segments, params } as CommandContext<THandler>;\n        const result = await Promise.resolve(unstable_commandStore.run(ctx, Reflect.apply(handler, ctx, params)));\n        if (result instanceof Error || (typeof result === \"object\" && ((result as { error: unknown }).error instanceof Error || typeof (result as { error: unknown }).error === \"string\"))) {\n          setState({ status: \"completed\", isError: true });\n          return { error: result instanceof Error ? result : (result as { error: Error | string }).error };\n        }\n\n        setState({ status: \"completed\", isError: false });\n        return { error: null }; `}\n      </FunctionDeclaration>\n    </>\n  );\n}\n\nexport interface StateBuiltinProps extends Omit<\n  BuiltinFileProps,\n  \"id\" | \"description\"\n> {}\n\n/**\n * A built-in module for handling application state utilities in Shell Shock.\n */\nexport function StateBuiltin(props: StateBuiltinProps) {\n  const [{ children }, rest] = splitProps(props, [\"children\"]);\n\n  return (\n    <BuiltinFile\n      id=\"state\"\n      description=\"A module that provides context hooks and utilities for accessing the application state.\"\n      {...rest}\n      imports={defu(rest.imports ?? {}, {\n        \"node:async_hooks\": [\"AsyncLocalStorage\"],\n        \"node:crypto\": [\"randomUUID\"]\n      })}\n      builtinImports={defu(rest.builtinImports ?? {}, {\n        env: [\"isCI\"]\n      })}>\n      <GlobalTypeDefinitions />\n      <Spacing />\n      <ArgsUtilities />\n      <Spacing />\n      <ContextUtilities />\n      <Spacing />\n      <Show when={Boolean(children)}>{children}</Show>\n    </BuiltinFile>\n  );\n}\n"],"mappings":"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"}

package/dist/components/state-builtin.mjs

@@ -40,7 +40,7 @@ function GlobalTypeDefinitions() {
 			typeParameters: [{
 				name: "THandler",
 				extends: "(...params: any[]) => any",
-				default: "(...params: any[]) => any"
+				default: "any"
 			}],
 			get children() {
 				return [
@@ -475,8 +475,8 @@ return result;`;
 			name: "withCommand",
 			typeParameters: [{
 				name: "THandler",
-				extends: "(...params: any[]) => any",
-				default: "(...params: any[]) => any"
+				extends: "(this: CommandContext, ...params: any[]) => any",
+				default: "(this: CommandContext, ...params: any[]) => any"
 			}],
 			parameters: [
 				{
@@ -500,7 +500,7 @@ return result;`;
 			children: code`setState({ status: "preparing", isError: false });
 
         const ctx = { path, segments, params } as CommandContext<THandler>;
-        const result = await Promise.resolve(unstable_commandStore.run(ctx, Reflect.apply(ctx, handler, params)));
+        const result = await Promise.resolve(unstable_commandStore.run(ctx, Reflect.apply(handler, ctx, params)));
         if (result instanceof Error || (typeof result === "object" && ((result as { error: unknown }).error instanceof Error || typeof (result as { error: unknown }).error === "string"))) {
           setState({ status: "completed", isError: true });
           return { error: result instanceof Error ? result : (result as { error: Error | string }).error };
@@ -521,7 +521,13 @@ function StateBuiltin(props) {
 		description: "A module that provides context hooks and utilities for accessing the application state."
 	}, rest, {
 		get imports() {
-			return defu$1(rest.imports ?? {}, { "node:async_hooks": ["AsyncLocalStorage"] });
+			return defu$1(rest.imports ?? {}, {
+				"node:async_hooks": ["AsyncLocalStorage"],
+				"node:crypto": ["randomUUID"]
+			});
+		},
+		get builtinImports() {
+			return defu$1(rest.builtinImports ?? {}, { env: ["isCI"] });
 		},
 		get children() {
 			return [

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

@@ -1 +1 @@
-{"version":3,"file":"state-builtin.mjs","names":[],"sources":["../../src/components/state-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, computed, For, Show, splitProps } from \"@alloy-js/core\";\nimport {\n  FunctionDeclaration,\n  InterfaceDeclaration,\n  InterfaceMember,\n  TypeDeclaration,\n  VarDeclaration\n} from \"@alloy-js/typescript\";\nimport { Spacing } from \"@powerlines/plugin-alloy/core/components/spacing\";\nimport { usePowerlines } from \"@powerlines/plugin-alloy/core/contexts/context\";\nimport type { BuiltinFileProps } from \"@powerlines/plugin-alloy/typescript/components/builtin-file\";\nimport { BuiltinFile } from \"@powerlines/plugin-alloy/typescript/components/builtin-file\";\nimport {\n  TSDoc,\n  TSDocInternal,\n  TSDocLink,\n  TSDocParam,\n  TSDocRemarks,\n  TSDocReturns\n} from \"@powerlines/plugin-alloy/typescript/components/tsdoc\";\nimport defu from \"defu\";\nimport { computedOptions } from \"../contexts/options\";\nimport { getAppBin } from \"../plugin-utils\";\nimport { getAppTitle } from \"../plugin-utils/context-helpers\";\nimport type { Context } from \"../types\";\nimport { OptionsMember } from \"./options-parser-logic\";\n\nexport function GlobalTypeDefinitions() {\n  const context = usePowerlines<Context>();\n\n  const options = computed(() => computedOptions(context.options));\n\n  return (\n    <>\n      <TSDoc\n        heading={`An object representing the global options available for every command in the ${getAppTitle(\n          context,\n          true\n        )} command-line application.`}\n      />\n      <InterfaceDeclaration export name=\"GlobalOptions\">\n        <For each={Object.values(options.value)} hardline>\n          {option => <OptionsMember option={option} />}\n        </For>\n      </InterfaceDeclaration>\n      <Spacing />\n      <TSDoc heading=\"The context object for the current command execution, containing the command path and segments.\" />\n      <InterfaceDeclaration\n        export\n        name=\"CommandContext\"\n        typeParameters={[\n          {\n            name: \"THandler\",\n            extends: \"(...params: any[]) => any\",\n            default: \"(...params: any[]) => any\"\n          }\n        ]}>\n        <TSDoc\n          heading={`The full command path as a string. For example, if the user runs \\`${getAppBin(\n            context\n          )} foo bar\\`, this would be \\`foo bar\\`. This is useful for commands that need to know their full invocation path, such as for help text or for commands that have dynamic behavior based on their position in the command hierarchy.`}\n        />\n        <InterfaceMember name=\"path\" type=\"string\" />\n        <Spacing />\n        <TSDoc\n          heading={`An array of command path segments. For example, if the user runs \\`${getAppBin(\n            context\n          )} foo bar\\`, this would be \\`[\"foo\", \"bar\"]\\`. This is useful for commands that need to know their individual path segments, such as for dynamic routing or for commands that have behavior based on specific segments in the command hierarchy.`}\n        />\n        <InterfaceMember name=\"segments\" type=\"string[]\" />\n        <Spacing />\n        <TSDoc\n          heading={`The parameters for the current command's handler function.`}\n        />\n        <InterfaceMember name=\"params\" type=\"Parameters<THandler>\" />\n      </InterfaceDeclaration>\n      <Spacing />\n      <TypeDeclaration export name=\"GlobalContextStatus\">\n        {code`\"initializing\" | \"preparing\" | \"executing\" | \"completed\"`}\n      </TypeDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`The state object for the ${getAppTitle(context)} application context.`}\n      />\n      <InterfaceDeclaration export name=\"GlobalContextState\">\n        <TSDoc heading=\"The unique identifier for the current execution context.\" />\n        <InterfaceMember name=\"executionId\" type=\"string\" />\n        <Spacing />\n        <TSDoc heading=\"The status of the current execution context.\" />\n        <InterfaceMember name=\"status\" type=\"GlobalContextStatus\" />\n        <Spacing />\n        <TSDoc heading=\"Indicates whether the current execution context has encountered an error.\" />\n        <InterfaceMember name=\"isError\" type=\"boolean\" />\n        <Spacing />\n        <TSDoc heading=\"A map containing arbitrary data associated with the current execution context.\" />\n        <InterfaceMember name=\"meta\" type=\"Map<string, unknown>\" />\n      </InterfaceDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`The context object for the ${getAppTitle(context)} application.`}\n      />\n      <InterfaceDeclaration export name=\"GlobalContext\">\n        <TSDoc heading=\"The global options shared across all commands in the application.\" />\n        <InterfaceMember name=\"options\" type=\"GlobalOptions\" />\n        <Spacing />\n        <TSDoc heading=\"The raw command-line arguments passed to the application.\" />\n        <InterfaceMember name=\"inputArgs\" type=\"string[]\" />\n        <Spacing />\n        <TSDoc heading=\"The state of the current execution context.\" />\n        <InterfaceMember name=\"state\" type=\"GlobalContextState\" />\n      </InterfaceDeclaration>\n    </>\n  );\n}\n\n/**\n * Generates utilities for detecting terminal color support.\n */\nexport function ArgsUtilities() {\n  return (\n    <>\n      <TSDoc heading=\"Retrieves the command-line arguments from Deno or Node.js environments.\">\n        <TSDocRemarks>\n          {`This function is only intended for internal use. Please use \\`useArgs()\\` instead.`}\n        </TSDocRemarks>\n        <Spacing />\n        <TSDocInternal />\n        <Spacing />\n        <TSDocReturns>\n          {`An array of command-line arguments from Deno or Node.js environments.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration name=\"getInputArgs\" returnType=\"string[]\">\n        {code`return ((globalThis as { Deno?: { args: string[] } })?.Deno?.args ?? process.argv ?? []) as string[];`}\n      </FunctionDeclaration>\n    </>\n  );\n}\n\nexport function ContextUtilities() {\n  const context = usePowerlines<Context>();\n\n  return (\n    <>\n      <Spacing />\n\n      <TSDoc\n        heading={`The global ${getAppTitle(context)} application context store instance.`}>\n        <TSDocInternal />\n      </TSDoc>\n      <VarDeclaration export const name=\"unstable_globalStore\">\n        {code`  new AsyncLocalStorage<GlobalContext>({ name: \"globalStore\" }); `}\n      </VarDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`Get the ${getAppTitle(\n          context\n        )} application context for the current application.`}>\n        <TSDocParam name=\"options\">\n          {`The options to use when getting the context. This can include parameters for how to handle missing contexts, such as whether to throw an error or return undefined. By default, if the context is not available, this function will return undefined.`}\n        </TSDocParam>\n        <TSDocReturns>\n          {`The ${getAppTitle(\n            context\n          )} application context for the current application or undefined if the context is not available.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useGlobal\" returnType=\"GlobalContext\">\n        {code`return unstable_globalStore.getStore() as GlobalContext;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the command-line arguments from the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocReturns>\n          {\"An array of command-line arguments from the application context.\"}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useArgs\" returnType=\"string[]\">\n        {code`return useGlobal()?.inputArgs ?? getInputArgs();`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the state of the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocReturns>{\"The state of the application context.\"}</TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"useState\"\n        returnType=\"GlobalContextState\">\n        {code`return useGlobal()?.state;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility function to update the state of the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocRemarks>\n          {`This function will throw an error if the global context is not available, so it should only be used within a valid context scope, such as within a command handler or within the \\`withGlobal()\\` function.`}\n        </TSDocRemarks>\n        <Spacing />\n        <TSDocParam name=\"update\">\n          {`The new state or a function that receives the previous state and returns the new state. This allows for both direct state updates and functional updates based on the previous state.`}\n        </TSDocParam>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"setState\"\n        parameters={[\n          {\n            name: \"update\",\n            type: \"Partial<GlobalContextState> | ((prev: GlobalContextState) => GlobalContextState)\"\n          }\n        ]}>\n        {code`const prev = useGlobal()?.state;\n        if (!prev) {\n          throw new Error(\n            \\`The ${getAppTitle(\n              context\n            )} application context is not available. Make sure to call setState() within a valid context scope.\\`\n          );\n        }\n\n        useGlobal().state = typeof update === \"function\" ? update(prev) : { ...prev, ...update }; `}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the execution ID of the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocReturns>\n          {\"The execution ID of the application context.\"}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useExecutionId\" returnType=\"string\">\n        {code`return useState().executionId;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the metadata of the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocReturns>\n          {\"The metadata of the application context.\"}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"useMeta\"\n        returnType=\"Map<string, unknown>\">\n        {code`return useState().meta;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the current status of the ${getAppTitle(\n          context\n        )} application.`}>\n        <TSDocReturns>{\"The current status of the application.\"}</TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"useStatus\"\n        returnType=\"GlobalContextStatus\">\n        {code`return useState().status;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`The global ${getAppTitle(context)} - command context store instance.`}>\n        <TSDocInternal />\n      </TSDoc>\n      <VarDeclaration export name=\"unstable_commandStore\">\n        {code`new AsyncLocalStorage<CommandContext>({ name: \"commandStore\" });`}\n      </VarDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`Get the ${getAppTitle(context)} - command context for the current application.`}>\n        <TSDocReturns>\n          {`The ${getAppTitle(context)} - command context for the current application.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useCommand\" returnType=\"CommandContext\">\n        {code`const result = unstable_commandStore.getStore();\nif (!result) {\n  throw new Error(\n    \\`The ${getAppTitle(context)} - command context is not available. Make sure to call useCommand() within a valid context scope.\\`\n  );\n}\nreturn result;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc heading=\"A utility hook function to get the individual segments of the current command path.\">\n        <TSDocReturns>{\"An array of command path segments.\"}</TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useSegments\" returnType=\"string[]\">\n        {code`return useCommand().segments;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc heading=\"A utility hook function to get the full command path as a string.\">\n        <TSDocReturns>\n          {`The full command path as a string. For example, if the user runs \\`${getAppBin(\n            context\n          )} foo bar\\`, this would return \\`\"foo bar\"\\`. This is useful for commands that need to know their full invocation path, such as for help text or for commands that have dynamic behavior based on their position in the command hierarchy.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"usePath\" returnType=\"string\">\n        {code`return useCommand().path;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc heading=\"Checks if a specific flag is present in the command-line arguments.\">\n        <TSDocLink>\n          {\"https://github.com/sindresorhus/has-flag/blob/main/index.js\"}\n        </TSDocLink>\n        <TSDocParam name=\"flag\">\n          {\n            'The flag (or an array of flags/aliases) to check for, e.g., \"color\", \"no-color\".'\n          }\n        </TSDocParam>\n        <TSDocParam name=\"argv\">\n          {\n            \"The command-line arguments to check against. Defaults to global Deno args or process args.\"\n          }\n        </TSDocParam>\n        <TSDocReturns>\n          {\"True if the flag is present, false otherwise.\"}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"hasFlag\"\n        parameters={[\n          { name: \"flag\", type: \"string | string[]\" },\n          {\n            name: \"argv\",\n            type: \"string[]\",\n            default: \"useArgs()\"\n          }\n        ]}>\n        <VarDeclaration\n          const\n          name=\"position\"\n          type=\"number\"\n          initializer={code`(Array.isArray(flag) ? flag : [flag]).reduce((ret, f) => {\n            const pos = argv.findIndex(arg => (f.startsWith(\"-\") ? \"\" : (f.length === 1 ? \"-\" : \"--\") + f)?.toLowerCase() === arg?.toLowerCase() || arg?.toLowerCase().startsWith((f.length === 1 ? \"-\" : \"--\") + f + \"=\"));\n            return pos !== -1 ? pos : ret;\n          }, -1);`}\n        />\n        <hbr />\n        {code`return position !== -1 && argv.indexOf(\"--\") === -1 || position < argv.indexOf(\"--\");`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc heading=\"A utility function to determine if the help flag is present or if the command is in an error state during preparation.\">\n        <TSDocReturns>\n          {`True if the help flag is present or if the command is in an error state during preparation, false otherwise. This can be used to conditionally display help text or to alter command behavior when the user is likely seeking help.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"isHelp\" returnType=\"boolean\">\n        {code`return !isCI && (hasFlag([\"help\", \"h\", \"?\"]) || (useStatus() === \"preparing\" && useState().isError)); `}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility function to wrap the ${getAppTitle(\n          context\n        )} application within the global context scope.`}>\n        <TSDocParam name=\"handler\">\n          {`The callback function to run within the global context scope. This function will receive the global context as its argument, allowing it to access any properties or utilities defined on the context. The callback function can be asynchronous and can return a value or a promise.`}\n        </TSDocParam>\n        <TSDocReturns>\n          {`The result of the callback function, which can be a value or a promise that resolves to a value.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        async\n        name=\"withGlobal\"\n        parameters={[{ name: \"handler\", type: \"() => any\" }]}\n        returnType=\"Promise<void>\">\n        {code`\n        return unstable_globalStore.run({ options: {} as unknown as GlobalOptions, inputArgs: getInputArgs(), state: { executionId: randomUUID(), status: \"initializing\", isError: false, meta: new Map() } as GlobalContextState }, handler);`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility function to wrap a ${getAppTitle(\n          context\n        )} application command handler within the command context scope.`}>\n        <TSDocParam name=\"handler\">\n          {`The callback function to run within the command context scope. This function will receive the command context as its argument, allowing it to access any properties or utilities defined on the context. The callback function can be asynchronous and can return a value or a promise.`}\n        </TSDocParam>\n        <TSDocReturns>\n          {`The result of the callback function, which can be a value or a promise that resolves to a value.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        async\n        name=\"withCommand\"\n        typeParameters={[\n          {\n            name: \"THandler\",\n            extends: \"(...params: any[]) => any\",\n            default: \"(...params: any[]) => any\"\n          }\n        ]}\n        parameters={[\n          { name: \"path\", type: \"string\" },\n          { name: \"segments\", type: \"string[]\" },\n          { name: \"params\", type: \"Parameters<THandler>\" },\n          { name: \"handler\", type: \"THandler\" }\n        ]}\n        returnType=\"Promise<{ error: string | Error | null }>\">\n        {code`setState({ status: \"preparing\", isError: false });\n\n        const ctx = { path, segments, params } as CommandContext<THandler>;\n        const result = await Promise.resolve(unstable_commandStore.run(ctx, Reflect.apply(ctx, handler, params)));\n        if (result instanceof Error || (typeof result === \"object\" && ((result as { error: unknown }).error instanceof Error || typeof (result as { error: unknown }).error === \"string\"))) {\n          setState({ status: \"completed\", isError: true });\n          return { error: result instanceof Error ? result : (result as { error: Error | string }).error };\n        }\n\n        setState({ status: \"completed\", isError: false });\n        return { error: null }; `}\n      </FunctionDeclaration>\n    </>\n  );\n}\n\nexport interface StateBuiltinProps extends Omit<\n  BuiltinFileProps,\n  \"id\" | \"description\"\n> {}\n\n/**\n * A built-in module for handling application state utilities in Shell Shock.\n */\nexport function StateBuiltin(props: StateBuiltinProps) {\n  const [{ children }, rest] = splitProps(props, [\"children\"]);\n\n  return (\n    <BuiltinFile\n      id=\"state\"\n      description=\"A module that provides context hooks and utilities for accessing the application state.\"\n      {...rest}\n      imports={defu(rest.imports ?? {}, {\n        \"node:async_hooks\": [\"AsyncLocalStorage\"]\n      })}>\n      <GlobalTypeDefinitions />\n      <Spacing />\n      <ArgsUtilities />\n      <Spacing />\n      <ContextUtilities />\n      <Spacing />\n      <Show when={Boolean(children)}>{children}</Show>\n    </BuiltinFile>\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"state-builtin.mjs","names":[],"sources":["../../src/components/state-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, computed, For, Show, splitProps } from \"@alloy-js/core\";\nimport {\n  FunctionDeclaration,\n  InterfaceDeclaration,\n  InterfaceMember,\n  TypeDeclaration,\n  VarDeclaration\n} from \"@alloy-js/typescript\";\nimport { Spacing } from \"@powerlines/plugin-alloy/core/components/spacing\";\nimport { usePowerlines } from \"@powerlines/plugin-alloy/core/contexts/context\";\nimport type { BuiltinFileProps } from \"@powerlines/plugin-alloy/typescript/components/builtin-file\";\nimport { BuiltinFile } from \"@powerlines/plugin-alloy/typescript/components/builtin-file\";\nimport {\n  TSDoc,\n  TSDocInternal,\n  TSDocLink,\n  TSDocParam,\n  TSDocRemarks,\n  TSDocReturns\n} from \"@powerlines/plugin-alloy/typescript/components/tsdoc\";\nimport defu from \"defu\";\nimport { computedOptions } from \"../contexts/options\";\nimport { getAppBin } from \"../plugin-utils\";\nimport { getAppTitle } from \"../plugin-utils/context-helpers\";\nimport type { Context } from \"../types\";\nimport { OptionsMember } from \"./options-parser-logic\";\n\nexport function GlobalTypeDefinitions() {\n  const context = usePowerlines<Context>();\n\n  const options = computed(() => computedOptions(context.options));\n\n  return (\n    <>\n      <TSDoc\n        heading={`An object representing the global options available for every command in the ${getAppTitle(\n          context,\n          true\n        )} command-line application.`}\n      />\n      <InterfaceDeclaration export name=\"GlobalOptions\">\n        <For each={Object.values(options.value)} hardline>\n          {option => <OptionsMember option={option} />}\n        </For>\n      </InterfaceDeclaration>\n      <Spacing />\n      <TSDoc heading=\"The context object for the current command execution, containing the command path and segments.\" />\n      <InterfaceDeclaration\n        export\n        name=\"CommandContext\"\n        typeParameters={[\n          {\n            name: \"THandler\",\n            extends: \"(...params: any[]) => any\",\n            default: \"any\"\n          }\n        ]}>\n        <TSDoc\n          heading={`The full command path as a string. For example, if the user runs \\`${getAppBin(\n            context\n          )} foo bar\\`, this would be \\`foo bar\\`. This is useful for commands that need to know their full invocation path, such as for help text or for commands that have dynamic behavior based on their position in the command hierarchy.`}\n        />\n        <InterfaceMember name=\"path\" type=\"string\" />\n        <Spacing />\n        <TSDoc\n          heading={`An array of command path segments. For example, if the user runs \\`${getAppBin(\n            context\n          )} foo bar\\`, this would be \\`[\"foo\", \"bar\"]\\`. This is useful for commands that need to know their individual path segments, such as for dynamic routing or for commands that have behavior based on specific segments in the command hierarchy.`}\n        />\n        <InterfaceMember name=\"segments\" type=\"string[]\" />\n        <Spacing />\n        <TSDoc\n          heading={`The parameters for the current command's handler function.`}\n        />\n        <InterfaceMember name=\"params\" type=\"Parameters<THandler>\" />\n      </InterfaceDeclaration>\n      <Spacing />\n      <TypeDeclaration export name=\"GlobalContextStatus\">\n        {code`\"initializing\" | \"preparing\" | \"executing\" | \"completed\"`}\n      </TypeDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`The state object for the ${getAppTitle(context)} application context.`}\n      />\n      <InterfaceDeclaration export name=\"GlobalContextState\">\n        <TSDoc heading=\"The unique identifier for the current execution context.\" />\n        <InterfaceMember name=\"executionId\" type=\"string\" />\n        <Spacing />\n        <TSDoc heading=\"The status of the current execution context.\" />\n        <InterfaceMember name=\"status\" type=\"GlobalContextStatus\" />\n        <Spacing />\n        <TSDoc heading=\"Indicates whether the current execution context has encountered an error.\" />\n        <InterfaceMember name=\"isError\" type=\"boolean\" />\n        <Spacing />\n        <TSDoc heading=\"A map containing arbitrary data associated with the current execution context.\" />\n        <InterfaceMember name=\"meta\" type=\"Map<string, unknown>\" />\n      </InterfaceDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`The context object for the ${getAppTitle(context)} application.`}\n      />\n      <InterfaceDeclaration export name=\"GlobalContext\">\n        <TSDoc heading=\"The global options shared across all commands in the application.\" />\n        <InterfaceMember name=\"options\" type=\"GlobalOptions\" />\n        <Spacing />\n        <TSDoc heading=\"The raw command-line arguments passed to the application.\" />\n        <InterfaceMember name=\"inputArgs\" type=\"string[]\" />\n        <Spacing />\n        <TSDoc heading=\"The state of the current execution context.\" />\n        <InterfaceMember name=\"state\" type=\"GlobalContextState\" />\n      </InterfaceDeclaration>\n    </>\n  );\n}\n\n/**\n * Generates utilities for detecting terminal color support.\n */\nexport function ArgsUtilities() {\n  return (\n    <>\n      <TSDoc heading=\"Retrieves the command-line arguments from Deno or Node.js environments.\">\n        <TSDocRemarks>\n          {`This function is only intended for internal use. Please use \\`useArgs()\\` instead.`}\n        </TSDocRemarks>\n        <Spacing />\n        <TSDocInternal />\n        <Spacing />\n        <TSDocReturns>\n          {`An array of command-line arguments from Deno or Node.js environments.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration name=\"getInputArgs\" returnType=\"string[]\">\n        {code`return ((globalThis as { Deno?: { args: string[] } })?.Deno?.args ?? process.argv ?? []) as string[];`}\n      </FunctionDeclaration>\n    </>\n  );\n}\n\nexport function ContextUtilities() {\n  const context = usePowerlines<Context>();\n\n  return (\n    <>\n      <Spacing />\n\n      <TSDoc\n        heading={`The global ${getAppTitle(context)} application context store instance.`}>\n        <TSDocInternal />\n      </TSDoc>\n      <VarDeclaration export const name=\"unstable_globalStore\">\n        {code`  new AsyncLocalStorage<GlobalContext>({ name: \"globalStore\" }); `}\n      </VarDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`Get the ${getAppTitle(\n          context\n        )} application context for the current application.`}>\n        <TSDocParam name=\"options\">\n          {`The options to use when getting the context. This can include parameters for how to handle missing contexts, such as whether to throw an error or return undefined. By default, if the context is not available, this function will return undefined.`}\n        </TSDocParam>\n        <TSDocReturns>\n          {`The ${getAppTitle(\n            context\n          )} application context for the current application or undefined if the context is not available.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useGlobal\" returnType=\"GlobalContext\">\n        {code`return unstable_globalStore.getStore() as GlobalContext;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the command-line arguments from the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocReturns>\n          {\"An array of command-line arguments from the application context.\"}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useArgs\" returnType=\"string[]\">\n        {code`return useGlobal()?.inputArgs ?? getInputArgs();`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the state of the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocReturns>{\"The state of the application context.\"}</TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"useState\"\n        returnType=\"GlobalContextState\">\n        {code`return useGlobal()?.state;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility function to update the state of the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocRemarks>\n          {`This function will throw an error if the global context is not available, so it should only be used within a valid context scope, such as within a command handler or within the \\`withGlobal()\\` function.`}\n        </TSDocRemarks>\n        <Spacing />\n        <TSDocParam name=\"update\">\n          {`The new state or a function that receives the previous state and returns the new state. This allows for both direct state updates and functional updates based on the previous state.`}\n        </TSDocParam>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"setState\"\n        parameters={[\n          {\n            name: \"update\",\n            type: \"Partial<GlobalContextState> | ((prev: GlobalContextState) => GlobalContextState)\"\n          }\n        ]}>\n        {code`const prev = useGlobal()?.state;\n        if (!prev) {\n          throw new Error(\n            \\`The ${getAppTitle(\n              context\n            )} application context is not available. Make sure to call setState() within a valid context scope.\\`\n          );\n        }\n\n        useGlobal().state = typeof update === \"function\" ? update(prev) : { ...prev, ...update }; `}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the execution ID of the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocReturns>\n          {\"The execution ID of the application context.\"}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useExecutionId\" returnType=\"string\">\n        {code`return useState().executionId;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the metadata of the ${getAppTitle(\n          context\n        )} application context.`}>\n        <TSDocReturns>\n          {\"The metadata of the application context.\"}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"useMeta\"\n        returnType=\"Map<string, unknown>\">\n        {code`return useState().meta;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility hook function to get the current status of the ${getAppTitle(\n          context\n        )} application.`}>\n        <TSDocReturns>{\"The current status of the application.\"}</TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"useStatus\"\n        returnType=\"GlobalContextStatus\">\n        {code`return useState().status;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`The global ${getAppTitle(context)} - command context store instance.`}>\n        <TSDocInternal />\n      </TSDoc>\n      <VarDeclaration export name=\"unstable_commandStore\">\n        {code`new AsyncLocalStorage<CommandContext>({ name: \"commandStore\" });`}\n      </VarDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`Get the ${getAppTitle(context)} - command context for the current application.`}>\n        <TSDocReturns>\n          {`The ${getAppTitle(context)} - command context for the current application.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useCommand\" returnType=\"CommandContext\">\n        {code`const result = unstable_commandStore.getStore();\nif (!result) {\n  throw new Error(\n    \\`The ${getAppTitle(context)} - command context is not available. Make sure to call useCommand() within a valid context scope.\\`\n  );\n}\nreturn result;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc heading=\"A utility hook function to get the individual segments of the current command path.\">\n        <TSDocReturns>{\"An array of command path segments.\"}</TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"useSegments\" returnType=\"string[]\">\n        {code`return useCommand().segments;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc heading=\"A utility hook function to get the full command path as a string.\">\n        <TSDocReturns>\n          {`The full command path as a string. For example, if the user runs \\`${getAppBin(\n            context\n          )} foo bar\\`, this would return \\`\"foo bar\"\\`. This is useful for commands that need to know their full invocation path, such as for help text or for commands that have dynamic behavior based on their position in the command hierarchy.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"usePath\" returnType=\"string\">\n        {code`return useCommand().path;`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc heading=\"Checks if a specific flag is present in the command-line arguments.\">\n        <TSDocLink>\n          {\"https://github.com/sindresorhus/has-flag/blob/main/index.js\"}\n        </TSDocLink>\n        <TSDocParam name=\"flag\">\n          {\n            'The flag (or an array of flags/aliases) to check for, e.g., \"color\", \"no-color\".'\n          }\n        </TSDocParam>\n        <TSDocParam name=\"argv\">\n          {\n            \"The command-line arguments to check against. Defaults to global Deno args or process args.\"\n          }\n        </TSDocParam>\n        <TSDocReturns>\n          {\"True if the flag is present, false otherwise.\"}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        name=\"hasFlag\"\n        parameters={[\n          { name: \"flag\", type: \"string | string[]\" },\n          {\n            name: \"argv\",\n            type: \"string[]\",\n            default: \"useArgs()\"\n          }\n        ]}>\n        <VarDeclaration\n          const\n          name=\"position\"\n          type=\"number\"\n          initializer={code`(Array.isArray(flag) ? flag : [flag]).reduce((ret, f) => {\n            const pos = argv.findIndex(arg => (f.startsWith(\"-\") ? \"\" : (f.length === 1 ? \"-\" : \"--\") + f)?.toLowerCase() === arg?.toLowerCase() || arg?.toLowerCase().startsWith((f.length === 1 ? \"-\" : \"--\") + f + \"=\"));\n            return pos !== -1 ? pos : ret;\n          }, -1);`}\n        />\n        <hbr />\n        {code`return position !== -1 && argv.indexOf(\"--\") === -1 || position < argv.indexOf(\"--\");`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc heading=\"A utility function to determine if the help flag is present or if the command is in an error state during preparation.\">\n        <TSDocReturns>\n          {`True if the help flag is present or if the command is in an error state during preparation, false otherwise. This can be used to conditionally display help text or to alter command behavior when the user is likely seeking help.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration export name=\"isHelp\" returnType=\"boolean\">\n        {code`return !isCI && (hasFlag([\"help\", \"h\", \"?\"]) || (useStatus() === \"preparing\" && useState().isError)); `}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility function to wrap the ${getAppTitle(\n          context\n        )} application within the global context scope.`}>\n        <TSDocParam name=\"handler\">\n          {`The callback function to run within the global context scope. This function will receive the global context as its argument, allowing it to access any properties or utilities defined on the context. The callback function can be asynchronous and can return a value or a promise.`}\n        </TSDocParam>\n        <TSDocReturns>\n          {`The result of the callback function, which can be a value or a promise that resolves to a value.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        async\n        name=\"withGlobal\"\n        parameters={[{ name: \"handler\", type: \"() => any\" }]}\n        returnType=\"Promise<void>\">\n        {code`\n        return unstable_globalStore.run({ options: {} as unknown as GlobalOptions, inputArgs: getInputArgs(), state: { executionId: randomUUID(), status: \"initializing\", isError: false, meta: new Map() } as GlobalContextState }, handler);`}\n      </FunctionDeclaration>\n      <Spacing />\n      <TSDoc\n        heading={`A utility function to wrap a ${getAppTitle(\n          context\n        )} application command handler within the command context scope.`}>\n        <TSDocParam name=\"handler\">\n          {`The callback function to run within the command context scope. This function will receive the command context as its argument, allowing it to access any properties or utilities defined on the context. The callback function can be asynchronous and can return a value or a promise.`}\n        </TSDocParam>\n        <TSDocReturns>\n          {`The result of the callback function, which can be a value or a promise that resolves to a value.`}\n        </TSDocReturns>\n      </TSDoc>\n      <FunctionDeclaration\n        export\n        async\n        name=\"withCommand\"\n        typeParameters={[\n          {\n            name: \"THandler\",\n            extends: \"(this: CommandContext, ...params: any[]) => any\",\n            default: \"(this: CommandContext, ...params: any[]) => any\"\n          }\n        ]}\n        parameters={[\n          { name: \"path\", type: \"string\" },\n          { name: \"segments\", type: \"string[]\" },\n          { name: \"params\", type: \"Parameters<THandler>\" },\n          { name: \"handler\", type: \"THandler\" }\n        ]}\n        returnType=\"Promise<{ error: string | Error | null }>\">\n        {code`setState({ status: \"preparing\", isError: false });\n\n        const ctx = { path, segments, params } as CommandContext<THandler>;\n        const result = await Promise.resolve(unstable_commandStore.run(ctx, Reflect.apply(handler, ctx, params)));\n        if (result instanceof Error || (typeof result === \"object\" && ((result as { error: unknown }).error instanceof Error || typeof (result as { error: unknown }).error === \"string\"))) {\n          setState({ status: \"completed\", isError: true });\n          return { error: result instanceof Error ? result : (result as { error: Error | string }).error };\n        }\n\n        setState({ status: \"completed\", isError: false });\n        return { error: null }; `}\n      </FunctionDeclaration>\n    </>\n  );\n}\n\nexport interface StateBuiltinProps extends Omit<\n  BuiltinFileProps,\n  \"id\" | \"description\"\n> {}\n\n/**\n * A built-in module for handling application state utilities in Shell Shock.\n */\nexport function StateBuiltin(props: StateBuiltinProps) {\n  const [{ children }, rest] = splitProps(props, [\"children\"]);\n\n  return (\n    <BuiltinFile\n      id=\"state\"\n      description=\"A module that provides context hooks and utilities for accessing the application state.\"\n      {...rest}\n      imports={defu(rest.imports ?? {}, {\n        \"node:async_hooks\": [\"AsyncLocalStorage\"],\n        \"node:crypto\": [\"randomUUID\"]\n      })}\n      builtinImports={defu(rest.builtinImports ?? {}, {\n        env: [\"isCI\"]\n      })}>\n      <GlobalTypeDefinitions />\n      <Spacing />\n      <ArgsUtilities />\n      <Spacing />\n      <ContextUtilities />\n      <Spacing />\n      <Show when={Boolean(children)}>{children}</Show>\n    </BuiltinFile>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;AAgCA,SAAe,wBAAA;CACb,MAAA,UAAS,eAAA;CACT,MAAA,UAAU,eAAA,gBAAA,QAAA,QAAA,CAAA;AACV,QAAA;EAAA,gBAAY,OAAA,EACZ,IAAA,UAAA;AACI,UAAG,gFAAoD,YAAA,SAAA,KAAA,CAAA;KAE7D,CAAA;EAAM,gBAAkB,sBAAqB;GAC7C,UAAS;GACT,MAAS;GACT,IAAO,WAAO;AACR,WAAG,gBAAsB,KAAE;;AAE1B,aAAS,OAAA,OAAA,QAAuB,MAAC;;;KAGhC,WAAU,WAAU,gBAAK,eAAwB,UAEhD,CAAA;KACJ,CAAA;;GAEF,CAAC;EAAE,gBAAe,SAAO,EAAA,CAAA;EAAA,gBAAwB,OAAQ,EACxD,SAAM,mGACP,CAAC;EAAE,gBAAI,sBAAA;GACN,UAAO;GACP,MAAG;GACH,gBAAG,CAAA;IACD,MAAM;IACN,SAAK;IACL,SAAO;IACR,CAAC;GACF,IAAG,WAAS;AACV,WAAO;KAAA,gBAAa,OAAQ,EAC3B,IAAA,UAAA;AACC,aAAA,sEAAA,UAAA,QAAA,CAAA;QAED,CAAC;KAAA,gBAAgB,iBAAA;MAChB,MAAE;MACF,MAAI;MACL,CAAC;KAAE,gBAAgB,SAAW,EAAE,CAAC;KAAE,gBAAM,OAAA,EACxC,IAAI,UAAU;AACZ,aAAA,sEAAA,UAAA,QAAA,CAAA;QAEH,CAAC;KAAC,gBAAA,iBAAA;MACD,MAAE;MACF,MAAI;MACL,CAAC;KAAE,gBAAkB,SAAS,EAAE,CAAC;KAAA,gBAAmB,OAAO,EAC1D,SAAC,8DACF,CAAC;KAAC,gBAAgB,iBAAkB;MACnC,MAAC;MACD,MAAC;MACF,CAAC;KAAC;;GAEN,CAAC;EAAE,gBAAkB,SAAK,EAAM,CAAA;EAAG,gBAAkB,iBAAiB;GACrE,UAAK;GACL,MAAK;GACL,UAAK,IAAS;GACf,CAAC;EAAE,gBAAG,SAAA,EAAA,CAAA;EAAA,gBAAA,OAAA,EACL,IAAI,UAAU;AACZ,UAAG,4BAAA,YAAA,QAAA,CAAA;KAEN,CAAC;EAAE,gBAAE,sBAAoB;GACxB,UAAU;GACV,MAAG;GACH,IAAI,WAAO;AACT,WAAE;KAAA,gBAAe,OAAA,EAChB,SAAS,4DACT,CAAA;KAAA,gBAAA,iBAAA;MACC,MAAA;MACD,MAAA;MACA,CAAA;KAAA,gBAAqB,SAAO,EAAI,CAAC;KAAC,gBAAmB,OAAA,EACpD,SAAO,gDACR,CAAC;KAAC,gBAAgB,iBAAmB;MACpC,MAAC;MACD,MAAM;MACP,CAAC;KAAC,gBAAgB,SAAY,EAAE,CAAA;KAAA,gBAAM,OAAsB,EAC3D,SAAS,6EACV,CAAC;KAAC,gBAAe,iBAAqB;MACrC,MAAC;MACD,MAAC;MACF,CAAC;KAAC,gBAAiB,SAAI,EAAA,CAAU;KAAC,gBAAe,OAAW,EAC3D,SAAC,kFACF,CAAC;KAAA,gBAAoB,iBAAA;MACrB,MAAO;MACP,MAAA;MACA,CAAC;KAAA;;GAEL,CAAC;EAAE,gBAAC,SAAqB,EAAO,CAAA;EAAA,gBAAoB,OAAA,EACnD,IAAI,UAAO;AACT,UAAG,8BAA+B,YAAM,QAAgB,CAAA;KAE3D,CAAC;EAAE,gBAAkB,sBAAqB;GACzC,UAAK;GACL,MAAK;GACL,IAAI,WAAO;AACT,WAAG;KAAA,gBAAsB,OAAO,EAC9B,SAAA,qEACF,CAAA;KAAA,gBAAA,iBAAA;MACH,MAAA;MACH,MAAA;;;8BAEE,SAAA,6DACC,CAAA;KAAA,gBAAwB,iBAAkB;MAC3C,MAAA;MACK,MAAA;MACL,CAAM;KAAC,gBAAA,SAAA,EAAA,CAAA;KAAA,gBAAA,OAAA,EACJ,SAAA,+CACE,CAAA;KAAA,gBAAe,iBAAsB;MACpC,MAAC;MACD,MAAI;MACL,CAAC;KAAC;;GAEN,CAAC;EAAC;;;;;AAML,SAAO,gBAAyB;AAC9B,QAAO,CAAA,gBAAc,OAAW;EAC9B,SAAI;EACJ,IAAE,WAAA;AACH,UAAA;IAAA,gBAAA,cAAA,EACH,UAAA;;;;oCAEO,UAAS,yEACT,CAAC;IAAA;;EAEN,CAAA,EAAA,gBAAO,qBAAA;EACL,MAAC;EACD,YAAY;;EAEb,CAAC,CAAC;;AAEL,SAAS,mBAAe;CACtB,MAAM,UAAK,eAAA;AACX,QAAK;EAAA,gBAAqB,SAAO,EAAI,CAAC;EAAC,gBAAA,OAAqB;GAC1D,IAAI,UAAQ;AACV,WAAE,cAAc,YAAA,QAAA,CAAA;;GAElB,IAAG,WAAA;AACD,WAAE,gBAAoB,eAAW,EAAA,CAAA;;GAEpC,CAAC;EAAE,gBAAiB,gBAAgB;GACnC,UAAK;GACL,SAAQ;GACR,MAAM;GACN,UAAK,IAAA;GACN,CAAC;EAAE,gBAAY,SAAW,EAAA,CAAA;EAAA,gBAAA,OAAA;GACzB,IAAI,UAAI;AACN,WAAO,WAAW,YAAY,QAAK,CAAA;;GAErC,IAAI,WAAK;AACP,WAAC,CAAA,gBAAoB,YAAa;KAChC,MAAM;KACN,UAAA;KACD,CAAA,EAAA,gBAAS,cAAA,EACT,IAAA,WAAA;AACC,YAAS,OAAG,YAAa,QAAW,CAAC;OAEtC,CAAC,CAAC;;GAEN,CAAC;EAAE,gBAAkB,qBAAa;GACjC,UAAM;GACN,MAAI;GACJ,YAAG;GACH,UAAU,IAAA;GACX,CAAC;EAAE,gBAAE,SAAmB,EAAA,CAAA;EAAA,gBAAA,OAAA;GACvB,IAAG,UAAS;AACV,WAAC,sEAAA,YAAA,QAAA,CAAA;;GAEH,IAAI,WAAE;AACJ,WAAK,gBAAoB,cAAE,EACzB,UAAC,oEACF,CAAC;;GAEL,CAAC;EAAE,gBAAE,qBAAA;GACJ,UAAU;GACV,MAAI;GACJ,YAAU;GACV,UAAI,IAAA;GACL,CAAC;EAAE,gBAAU,SAAA,EAAA,CAAA;EAAA,gBAAA,OAAA;GACZ,IAAG,UAAA;AACD,WAAE,mDAAwD,YAAE,QAAW,CAAA;;GAEzE,IAAI,WAAG;AACL,WAAG,gBAAY,cAAA,EACb,UAAS,yCACV,CAAC;;GAEL,CAAC;EAAE,gBAAkB,qBAAS;GAC7B,UAAQ;GACR,MAAM;GACN,YAAS;GACT,UAAG,IAAA;GACJ,CAAC;EAAE,gBAAE,SAAA,EAAA,CAAA;EAAA,gBAAA,OAAA;GACJ,IAAI,UAAM;AACR,WAAE,iDAAY,YAAA,QAAA,CAAA;;GAEhB,IAAI,WAAW;AACb,WAAM;KAAA,gBAAe,cAAmB,EACtC,UAAE,+MACH,CAAC;KAAE,gBAAA,SAAA,EAAA,CAAA;KAAA,gBAAA,YAAA;MACF,MAAM;MACN,UAAU;MACX,CAAC;KAAC;;GAEN,CAAC;EAAE,gBAAQ,qBAAA;GACV,UAAU;GACV,MAAM;GACN,YAAI,CAAA;;IAEF,MAAE;IACH,CAAC;GACF,IAAG,WAAS;AACV,WAAC,IAAA;;;oBAGI,YAAqB,QAAC,CAAA;;;;;;GAM9B,CAAC;EAAE,gBAAe,SAAW,EAAA,CAAA;EAAA,gBAAa,OAAA;GACzC,IAAI,UAAA;AACF,WAAC,0DAAS,YAAA,QAAA,CAAA;;GAEZ,IAAI,WAAW;AACb,WAAI,gBAAA,cAAA,EACF,UAAG,gDACJ,CAAC;;GAEL,CAAC;EAAE,gBAAgB,qBAAA;GAClB,UAAS;GACT,MAAG;GACH,YAAI;GACJ,UAAU,IAAA;GACX,CAAC;EAAE,gBAAkB,SAAQ,EAAA,CAAA;EAAA,gBAAS,OAAA;GACrC,IAAI,UAAM;AACR,WAAE,sDAAmB,YAAA,QAAA,CAAA;;GAEvB,IAAG,WAAA;AACD,WAAE,gBAAoB,cAAiB,EACrC,UAAE,4CACH,CAAC;;GAEL,CAAC;EAAE,gBAAO,qBAAA;GACT,UAAG;GACH,MAAI;GACJ,YAAU;GACV,UAAI,IAAU;GACf,CAAC;EAAE,gBAAe,SAAW,EAAA,CAAA;EAAM,gBAAE,OAAA;GACpC,IAAI,UAAA;AACF,WAAC,4DAAS,YAAA,QAAA,CAAA;;GAEZ,IAAI,WAAU;AACZ,WAAG,gBAAe,cAAA,EAChB,UAAK,0CACN,CAAA;;GAEJ,CAAC;EAAE,gBAAgB,qBAAA;GAClB,UAAU;GACV,MAAG;GACH,YAAY;GACZ,UAAK,IAAA;GACN,CAAC;EAAE,gBAAY,SAAY,EAAA,CAAA;EAAQ,gBAAY,OAAY;GAC1D,IAAI,UAAE;AACJ,WAAO,cAAA,YAAA,QAAA,CAAA;;GAET,IAAI,WAAW;AACd,WAAQ,gBAAA,eAAA,EAAA,CAAA;;GAEV,CAAC;EAAE,gBAAkB,gBAAY;GACjC,UAAA;GACH,MAAA;GACA,UAAc,IAAC;GACZ,CAAC;EAAE,gBAAE,SAAmB,EAAA,CAAA;EAAA,gBAAA,OAAA;GACvB,IAAG,UAAS;AACV,WAAO,WAAW,YAAY,QAAC,CAAQ;;GAEzC,IAAI,WAAK;AACP,WAAC,gBAAoB,cAAa,EAChC,IAAC,WAAY;AACb,YAAA,OAAA,YAAmB,QAAA,CAAA;OAEpB,CAAA;;GAEJ,CAAC;EAAE,gBAAe,qBAAwB;GACzC,UAAQ;GACR,MAAM;GACN,YAAM;GACN,IAAI,WAAK;AACP,WAAC,IAAA;;;YAGA,YAAS,QAAA,CAAA;;;;;GAKb,CAAC;EAAE,gBAAkB,SAAO,EAAA,CAAA;EAAA,gBAAA,OAAA;GAC3B,SAAM;GACN,IAAI,WAAS;AACX,WAAI,gBAAA,cAAA,EACF,UAAE,sCACH,CAAC;;GAEL,CAAC;EAAE,gBAAkB,qBAAmB;GACvC,UAAM;GACN,MAAM;GACN,YAAK;GACL,UAAQ,IAAK;GACd,CAAC;EAAE,gBAAgB,SAAA,EAAA,CAAA;EAAA,gBAAA,OAAA;GAClB,SAAS;GACT,IAAG,WAAA;AACD,WAAE,gBAAA,cAAA,EACA,IAAI,WAAS;AACb,YAAA,sEAAY,UAAA,QAAA,CAAA;OAEb,CAAC;;GAEL,CAAC;EAAE,gBAAa,qBAAS;GACxB,UAAQ;GACR,MAAM;GACN,YAAM;GACN,UAAK,IAAA;GACN,CAAC;EAAE,gBAAI,SAAA,EAAA,CAAA;EAAA,gBAAA,OAAA;GACN,SAAM;GACN,IAAI,WAAQ;AACV,WAAI;KAAA,gBAAmB,WAAc,EACnC,UAAU,+DACX,CAAC;KAAE,gBAAkB,YAAU;MAC9B,MAAM;MACN,UAAC;MACF,CAAC;KAAC,gBAAK,YAAA;MACN,MAAM;MACN,UAAA;MACD,CAAA;KAAA,gBAAS,cAAA,EACT,UAAM,iDACN,CAAC;KAAC;;GAEN,CAAC;EAAE,gBAAgB,qBAAA;GAClB,UAAS;GACT,MAAG;GACH,YAAU,CAAA;IACR,MAAE;IACF,MAAC;IACF,EAAE;IACD,MAAE;IACF,MAAI;IACJ,SAAK;IACN,CAAC;GACF,IAAI,WAAQ;AACV,WAAI;KAAA,gBAAU,gBAAA;MACZ,SAAC;MACD,MAAI;MACJ,MAAE;MACF,aAAK,IAAA;;;;MAIN,CAAC;KAAA,gBAAgB,OAAA,EAAA,CAAA;KAAA,IAAA;KAAA;;GAErB,CAAC;EAAE,gBAAc,SAAa,EAAC,CAAA;EAAA,gBAAA,OAAA;GAC9B,SAAS;GACT,IAAI,WAAO;AACT,WAAE,gBAAmB,cAAA,EACpB,UAAS,uOACT,CAAA;;GAEJ,CAAC;EAAE,gBAAI,qBAAA;GACN,UAAO;GACP,MAAK;GACL,YAAY;GACZ,UAAM,IAAA;GACP,CAAC;EAAE,gBAAe,SAAA,EAAA,CAAA;EAAA,gBAAA,OAAA;GACjB,IAAI,UAAQ;AACV,WAAI,kCAAY,YAAA,QAAA,CAAA;;GAElB,IAAG,WAAA;AACD,WAAE,CAAA,gBAAA,YAAA;KACA,MAAA;KACA,UAAM;KACP,CAAC,EAAA,gBAAgB,cAAA,EAChB,UAAE,oGACH,CAAC,CAAC;;GAEN,CAAC;EAAE,gBAAiB,qBAAsB;GACzC,UAAM;GACN,OAAK;GACL,MAAI;GACJ,YAAY,CAAC;IACX,MAAM;IACN,MAAM;IACP,CAAC;GACF,YAAK;GACL,UAAI,IAAU;;;;;GAGd,IAAI,UAAU;AACZ,WAAO,gCAAgC,YAAA,QAAA,CAAqB;;GAE9D,IAAI,WAAW;AACb,WAAI,CAAA,gBAAsB,YAAY;KACpC,MAAA;;KAED,CAAC,EAAA,gBAAoB,cAAY,EAChC,UAAS,oGACV,CAAC,CAAA;;GAEL,CAAA;EAAA,gBAAA,qBAAA;GACH,UAAA;;GAEA,MAAO;GACL,gBAAgB,CAAA;IACZ,MAAI;IACP,SAAA;;IAED,CAAA;GACE,YAAU;IAAA;KACZ,MAAA;KACI,MAAC;KACL;IAAK;;KAEL,MAAO;KACJ;IAAA;KACC,MAAI;KACJ,MAAA;KACD;IAAE;KACD,MAAA;KACA,MAAG;KACJ;IAAC;GACF,YAAI;GACJ,UAAE,IAAA;;;;;;;;;;;GAWH,CAAA;EAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shell-shock/core",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "private": false,
   "description": "A package containing the core Shell Shock functionality used to build and manage a command-line application.",
   "keywords": ["shell-shock", "powerlines", "storm-software"],
@@ -398,5 +398,5 @@
   "peerDependencies": { "powerlines": ">=0.42.10", "zod": "^3.25.0 || ^4.0.0" },
   "peerDependenciesMeta": { "zod": { "optional": true } },
   "publishConfig": { "access": "public" },
-  "gitHead": "5620dfed15a7d3ff47ad3f1665f6fdd8c6fd5d08"
+  "gitHead": "c1b938503f5de35ab59e58638029def62257a504"
 }