@shell-shock/plugin-upgrade 0.1.4 → 0.1.6

package/dist/components/upgrade-builtin.cjs

@@ -1,30 +1,41 @@
 const require_rolldown_runtime = require('../_virtual/rolldown_runtime.cjs');
 let __alloy_js_core_jsx_runtime = require("@alloy-js/core/jsx-runtime");
+let defu = require("defu");
+defu = require_rolldown_runtime.__toESM(defu);
 let __alloy_js_core = require("@alloy-js/core");
 let __alloy_js_typescript = require("@alloy-js/typescript");
 let __powerlines_plugin_alloy_core_components_spacing = require("@powerlines/plugin-alloy/core/components/spacing");
+let __powerlines_plugin_alloy_core_contexts_context = require("@powerlines/plugin-alloy/core/contexts/context");
 let __powerlines_plugin_alloy_typescript = require("@powerlines/plugin-alloy/typescript");
 let __powerlines_plugin_alloy_typescript_components_builtin_file = require("@powerlines/plugin-alloy/typescript/components/builtin-file");
-let defu = require("defu");
-defu = require_rolldown_runtime.__toESM(defu);
 
 //#region src/components/upgrade-builtin.tsx
 /**
 * The `locatePackageJson` handler function declaration code for the Shell Shock project.
 */
 function LocatePackageJsonFunctionDeclaration() {
+	const context = (0, __powerlines_plugin_alloy_core_contexts_context.usePowerlines)();
 	return [
 		(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.InterfaceDeclaration, {
 			"export": true,
 			name: "LocatePackageJsonOptions",
 			doc: "Options for the `locatePackageJson` handler function.",
 			get children() {
-				return (0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.InterfaceMember, {
-					name: "cwd",
-					optional: true,
-					type: "string",
-					doc: "The current working directory to use. If not provided, the process's current working directory will be used."
-				});
+				return [
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.InterfaceMember, {
+						name: "cwd",
+						optional: true,
+						type: "string",
+						doc: "The current working directory to use. If not provided, the process's current working directory will be used."
+					}),
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.InterfaceMember, {
+						name: "isDependencyRequired",
+						optional: true,
+						type: "boolean",
+						doc: "Whether to only locate a package.json file if it contains the application as a dependency. If set to `true`, the function will check if the located package.json file has the application listed as a dependency in its dependencies, devDependencies, peerDependencies, or optionalDependencies before returning its path. This can be useful in monorepo setups where multiple package.json files may exist, but only the one that includes the application as a dependency is relevant for upgrade purposes."
+					})
+				];
 			}
 		}),
 		(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
@@ -68,11 +79,32 @@ function LocatePackageJsonFunctionDeclaration() {
 					}),
 					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
 					__alloy_js_core.code`while (parentPath !== currentPath && currentPath !== homePath && currentPath !== tempPath) { `,
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.VarDeclaration, {
+						"const": true,
+						name: "packageJsonPath",
+						initializer: __alloy_js_core.code`join(currentPath, "package.json"); `
+					}),
 					(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.IfStatement, {
-						condition: __alloy_js_core.code`existsSync(join(currentPath, "package.json"))`,
-						children: __alloy_js_core.code`return join(currentPath, "package.json"); `
+						condition: __alloy_js_core.code`existsSync(packageJsonPath)`,
+						get children() {
+							return [(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.IfStatement, {
+								condition: __alloy_js_core.code`options.isDependencyRequired`,
+								get children() {
+									return [(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.VarDeclaration, {
+										"const": true,
+										name: "packageJson",
+										initializer: __alloy_js_core.code`JSON.parse(await readFile(packageJsonPath, "utf8")); `
+									}), (0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.IfStatement, {
+										get condition() {
+											return __alloy_js_core.code`Object.keys(packageJson.dependencies || {}).concat(Object.keys(packageJson.devDependencies || {})).concat(Object.keys(packageJson.peerDependencies || {})).concat(Object.keys(packageJson.optionalDependencies || {})).some(dep => dep === "${context.packageJson.name}" || dep.startsWith("${context.packageJson.name}@"))`;
+										},
+										children: __alloy_js_core.code`return packageJsonPath; `
+									})];
+								}
+							}), (0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.ElseClause, { children: __alloy_js_core.code`return packageJsonPath; ` })];
+						}
 					}),
-					(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.ElseClause, { children: __alloy_js_core.code`currentPath = pathParent;
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.ElseClause, { children: __alloy_js_core.code`currentPath = parentPath;
           parentPath = resolve(currentPath, ".."); ` }),
 					__alloy_js_core.code` }
 
@@ -117,7 +149,6 @@ function LocateLockfileFunctionDeclaration() {
 		}),
 		(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.FunctionDeclaration, {
 			"export": true,
-			async: true,
 			name: "locateLockfile",
 			parameters: [{
 				name: "options",
@@ -162,7 +193,7 @@ function LocateLockfileFunctionDeclaration() {
 						condition: __alloy_js_core.code`lockfile`,
 						children: __alloy_js_core.code`return lockfile; `
 					}),
-					(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.ElseClause, { children: __alloy_js_core.code`currentPath = pathParent;
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.ElseClause, { children: __alloy_js_core.code`currentPath = parentPath;
           parentPath = resolve(currentPath, ".."); ` }),
 					__alloy_js_core.code` }
 
@@ -177,6 +208,15 @@ function LocateLockfileFunctionDeclaration() {
 */
 function GetPackageManagerFunctionDeclaration() {
 	return [
+		__alloy_js_core.code`declare global {
+        var Bun: any;
+        namespace NodeJS {
+          interface ProcessVersions {
+            bun?: string;
+          }
+        }
+      } `,
+		(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
 		(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TypeDeclaration, {
 			"export": true,
 			name: "GetPackageManagerOptions",
@@ -207,7 +247,7 @@ function GetPackageManagerFunctionDeclaration() {
 				type: "GetPackageManagerOptions",
 				default: "{}"
 			}],
-			returnType: __alloy_js_core.code`Promise<"npm" | "yarn" | "deno" | "pnpm" | "bun">`,
+			returnType: __alloy_js_core.code`"npm" | "yarn" | "deno" | "pnpm" | "bun"`,
 			get children() {
 				return [
 					(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.VarDeclaration, {
@@ -265,7 +305,7 @@ function GetPackageManagerFunctionDeclaration() {
 									(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.VarDeclaration, {
 										"const": true,
 										name: "packageJsonPath",
-										initializer: __alloy_js_core.code`locatePackageJson(options); `
+										initializer: __alloy_js_core.code`await locatePackageJson(options); `
 									}),
 									(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.IfStatement, {
 										condition: __alloy_js_core.code`packageJsonPath && existsSync(packageJsonPath)`,
@@ -492,7 +532,7 @@ function FetchNpmPackageFunctionDeclaration() {
 				name: "packageName",
 				type: "string"
 			}],
-			returnType: __alloy_js_core.code`Promise<NpmPackage | undefined>`,
+			returnType: __alloy_js_core.code`NpmPackage | undefined`,
 			get children() {
 				return [
 					(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.VarDeclaration, {
@@ -512,9 +552,10 @@ function FetchNpmPackageFunctionDeclaration() {
 	];
 }
 /**
-* The `getLatest` handler function declaration code for the Shell Shock project.
+* The `getLatestVersion` handler function declaration code for the Shell Shock project.
 */
-function GetLatestFunctionDeclaration() {
+function GetLatestVersionFunctionDeclaration() {
+	const context = (0, __powerlines_plugin_alloy_core_contexts_context.usePowerlines)();
 	return [(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDoc, {
 		heading: "Get the latest version of the application from the npm registry.",
 		get children() {
@@ -531,45 +572,124 @@ function GetLatestFunctionDeclaration() {
 	}), (0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.FunctionDeclaration, {
 		"export": true,
 		async: true,
-		name: "getLatest",
+		name: "getLatestVersion",
+		get parameters() {
+			return [{
+				name: "packageName",
+				default: `"${context.packageJson.name}"`
+			}];
+		},
+		returnType: __alloy_js_core.code`string | undefined`,
+		get children() {
+			return [
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.VarDeclaration, {
+					"const": true,
+					name: "result",
+					initializer: __alloy_js_core.code`await fetchNpmPackage(packageName); `
+				}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+				__alloy_js_core.code`return result?.version; `
+			];
+		}
+	})];
+}
+/**
+* The `upgrade` handler function declaration code for the Shell Shock project.
+*/
+function GetUpgradeCommandFunctionDeclaration() {
+	const context = (0, __powerlines_plugin_alloy_core_contexts_context.usePowerlines)();
+	return [(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDoc, {
+		heading: "A function to get the upgrade command for a specific package manager.",
+		get children() {
+			return [
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDocRemarks, { children: `This function is used to get the appropriate upgrade command for a specific package manager. It can be used in the CLI upgrade command to determine which command to run based on the package manager being used by the application.` }),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDocParam, {
+					name: "packageManager",
+					children: `The name of the package manager to get the upgrade command for. This should be one of "npm", "yarn", "pnpm", "deno", or "bun".`
+				}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDocParam, {
+					name: "cwd",
+					children: `The current working directory to use when determining the upgrade command. This can be used to locate the appropriate package.json and lockfile to determine how to run the upgrade command. If not provided, the process's current working directory will be used.`
+				}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDocReturns, { children: `An array of strings representing the command and its arguments to run in order to upgrade the application dependencies using the specified package manager.` })
+			];
+		}
+	}), (0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.FunctionDeclaration, {
+		"export": true,
+		async: true,
+		name: "getUpgradeCommand",
 		parameters: [{
-			name: "packageName",
+			name: "packageManager",
 			type: "string"
+		}, {
+			name: "cwd",
+			type: "string",
+			default: "process.cwd()"
 		}],
+		returnType: "string[]",
 		get children() {
 			return [
 				(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.VarDeclaration, {
 					"const": true,
-					name: "package",
-					initializer: __alloy_js_core.code`await fetchNpmPackage(packageName); `
+					name: "version",
+					get initializer() {
+						return __alloy_js_core.code`(await getLatestVersion("${context.packageJson.name}")) || "latest"; `;
+					}
 				}),
 				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
-				__alloy_js_core.code`return package?.version; `
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.IfStatement, {
+					condition: __alloy_js_core.code`packageManager === "yarn"`,
+					get children() {
+						return __alloy_js_core.code`return ["upgrade", \`${context.packageJson.name}@\${version}\`]; `;
+					}
+				}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.ElseIfClause, {
+					condition: __alloy_js_core.code`packageManager === "pnpm"`,
+					get children() {
+						return __alloy_js_core.code`return ["update", \`${context.packageJson.name}@\${version}\`]; `;
+					}
+				}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.ElseIfClause, {
+					condition: __alloy_js_core.code`packageManager === "deno"`,
+					get children() {
+						return __alloy_js_core.code`return ["outdated", "--update", \`${context.packageJson.name}@\${version}\`]; `;
+					}
+				}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.ElseIfClause, {
+					condition: __alloy_js_core.code`packageManager === "bun"`,
+					get children() {
+						return __alloy_js_core.code`return ["update", "--save",  \`${context.packageJson.name}@\${version}\`]; `;
+					}
+				}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.ElseClause, { get children() {
+					return __alloy_js_core.code`return ["update", "--save", "--bin-links", \`${context.packageJson.name}@\${version}\`]; `;
+				} })
 			];
 		}
 	})];
 }
 /**
-* The `install` handler function declaration code for the Shell Shock project.
+* The `upgrade` handler function declaration code for the Shell Shock project.
 */
-function InstallFunctionDeclaration() {
+function UpgradeFunctionDeclaration() {
 	return [
 		(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.InterfaceDeclaration, {
-			name: "InstallBaseOptions",
-			doc: "Options for the `install` handler function.",
+			name: "UpgradeBaseOptions",
+			doc: "Options for the `upgrade` handler function.",
 			get children() {
 				return [
 					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.InterfaceMember, {
 						name: "stdout",
 						optional: true,
-						type: "(string) => void",
+						type: "(data: string) => void",
 						doc: "A callback function that is called with the stdout output of the command."
 					}),
 					(0, __alloy_js_core_jsx_runtime.createIntrinsic)("hbr", {}),
 					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.InterfaceMember, {
 						name: "stderr",
 						optional: true,
-						type: "(string) => void",
+						type: "(err: string) => void",
 						doc: "A callback function that is called with the stderr output of the command."
 					})
 				];
@@ -578,32 +698,32 @@ function InstallFunctionDeclaration() {
 		(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
 		(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TypeDeclaration, {
 			"export": true,
-			name: "InstallOptions",
-			doc: "Options for the `install` handler function.",
-			children: __alloy_js_core.code`InstallBaseOptions & Parameters<typeof spawn>[2];`
+			name: "UpgradeOptions",
+			doc: "Options for the `upgrade` handler function.",
+			children: __alloy_js_core.code`UpgradeBaseOptions & GetPackageManagerOptions & Parameters<typeof spawn>[2];`
 		}),
 		(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
 		(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDoc, {
-			heading: "Install the application dependencies.",
+			heading: "Upgrade the application dependencies.",
 			get children() {
 				return [
-					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDocRemarks, { children: `This function is used to install the application dependencies. It can be used in the CLI upgrade command to ensure that all necessary dependencies are installed.` }),
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDocRemarks, { children: `This function is used to upgrade the application dependencies. It can be used in the CLI upgrade command to ensure that all necessary dependencies are up-to-date.` }),
 					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
 					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDocParam, {
 						name: "options",
-						children: `The options for the \`install\` function. Currently, there are no options available, but this parameter is included for future extensibility.`
+						children: `The options for the \`upgrade\` function. Currently, there are no options available, but this parameter is included for future extensibility.`
 					}),
-					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDocReturns, { children: `A promise that resolves when the installation of dependencies is complete.` })
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDocReturns, { children: `A promise that resolves when the upgrade of dependencies is complete.` })
 				];
 			}
 		}),
 		(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.FunctionDeclaration, {
 			"export": true,
 			async: true,
-			name: "install",
+			name: "upgrade",
 			parameters: [{
 				name: "options",
-				type: "InstallOptions",
+				type: "UpgradeOptions",
 				default: "{}"
 			}],
 			get children() {
@@ -611,9 +731,15 @@ function InstallFunctionDeclaration() {
 					(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.VarDeclaration, {
 						"const": true,
 						name: "packageManager",
-						initializer: __alloy_js_core.code`getPackageManager(); `
+						initializer: __alloy_js_core.code`await getPackageManager(options); `
 					}),
 					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.VarDeclaration, {
+						"const": true,
+						name: "args",
+						initializer: __alloy_js_core.code`await getUpgradeCommand(packageManager, options.cwd); `
+					}),
+					(0, __alloy_js_core_jsx_runtime.createIntrinsic)("hbr", {}),
 					(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.VarDeclaration, {
 						"let": true,
 						name: "output",
@@ -622,9 +748,9 @@ function InstallFunctionDeclaration() {
 					(0, __alloy_js_core_jsx_runtime.createIntrinsic)("hbr", {}),
 					__alloy_js_core.code`await spawn(
           \`\${packageManager}\${isWindows && packageManager !== "bun" ? ".cmd" : ""}\`,
-          ["install"],
+          [args.join(" ")],
           {
-            ...options
+            ...options,
             env: {
               ...options.env,
               ...(packageManager === "pnpm" ? { npm_config_strict_peer_dependencies: false } : null),
@@ -644,6 +770,240 @@ function InstallFunctionDeclaration() {
 	];
 }
 /**
+* The `updateVersionCheckFile` handler function declaration code for the Shell Shock project.
+*/
+function UpdateVersionCheckFileFunctionDeclaration() {
+	return [(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDoc, {
+		heading: "A helper function that updates the version check file.",
+		get children() {
+			return [
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDocRemarks, { children: `This function is used to update the version check file with the current timestamp. It can be used in the CLI upgrade command to record the last time a check for updates was performed. The function writes a "version-check.json" file in the data directory, which contains a timestamp of the last check for updates.` }),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDocReturns, { children: `A promise that resolves to a boolean indicating whether a check for updates is required.` })
+			];
+		}
+	}), (0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.FunctionDeclaration, {
+		"export": true,
+		async: true,
+		name: "updateVersionCheckFile",
+		returnType: "void",
+		get children() {
+			return [(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.IfStatement, {
+				condition: __alloy_js_core.code`!existsSync(paths.data)`,
+				children: __alloy_js_core.code`await mkdir(paths.data, { recursive: true }); `
+			}), __alloy_js_core.code`await writeFile(join(paths.data, "version-check.json"), JSON.stringify({ timestamp: new Date().getTime() }), "utf8"); `];
+		}
+	})];
+}
+/**
+* The `isCheckForUpdatesRequired` handler function declaration code for the Shell Shock project.
+*/
+function IsCheckForUpdatesRequiredFunctionDeclaration() {
+	const context = (0, __powerlines_plugin_alloy_core_contexts_context.usePowerlines)();
+	return [(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDoc, {
+		heading: "A helper function that verifies if a check for updates is required.",
+		get children() {
+			return [
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDocRemarks, { children: `This function is used to determine if a check for updates is required based on the last time a check was performed. It can be used in the CLI upgrade command to avoid unnecessary checks for updates if one was recently performed. The function checks for the existence of a "version-check.json" file in the data directory, which contains a timestamp of the last check for updates. If the file does not exist or if the timestamp is older than a specified stale time, the function will return true, indicating that a check for updates is required. Otherwise, it will return false.` }),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDocReturns, { children: `A promise that resolves to a boolean indicating whether a check for updates is required.` })
+			];
+		}
+	}), (0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.FunctionDeclaration, {
+		"export": true,
+		async: true,
+		name: "isCheckForUpdatesRequired",
+		get children() {
+			return [
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.IfStatement, {
+					condition: __alloy_js_core.code`!isInteractive || isCI || env.SKIP_VERSION_CHECK`,
+					children: __alloy_js_core.code`return false; `
+				}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.VarDeclaration, {
+					"const": true,
+					name: "filePath",
+					initializer: __alloy_js_core.code`join(paths.data, "version-check.json"); `
+				}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.IfStatement, {
+					condition: __alloy_js_core.code`existsSync(filePath)`,
+					get children() {
+						return [
+							(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.VarDeclaration, {
+								"const": true,
+								name: "file",
+								type: "{ timestamp: number; }",
+								initializer: __alloy_js_core.code` JSON.parse(await readFile(filePath, "utf8")); `
+							}),
+							(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.IfStatement, {
+								condition: __alloy_js_core.code`!file.timestamp`,
+								children: __alloy_js_core.code`await updateVersionCheckFile();
+            return true; `
+							}),
+							(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.ElseIfClause, {
+								get condition() {
+									return __alloy_js_core.code`new Date().getTime() - file.timestamp < ${context.config.upgrade.staleTime}`;
+								},
+								children: __alloy_js_core.code`return false; `
+							})
+						];
+					}
+				}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.ElseClause, { children: __alloy_js_core.code`await updateVersionCheckFile();
+          return true; ` })
+			];
+		}
+	})];
+}
+/**
+* The `checkForUpdates` handler function declaration code for the Shell Shock project.
+*/
+function CheckForUpdatesFunctionDeclaration() {
+	const context = (0, __powerlines_plugin_alloy_core_contexts_context.usePowerlines)();
+	return [
+		(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.InterfaceDeclaration, {
+			"export": true,
+			name: "CheckForUpdatesOptions",
+			"extends": "GetPackageManagerOptions",
+			doc: "Options for the `checkForUpdates` handler function.",
+			get children() {
+				return (0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.InterfaceMember, {
+					name: "force",
+					optional: true,
+					type: "boolean",
+					doc: "Whether to force a check for updates regardless of the last check timestamp. If set to `true`, the function will bypass the timestamp check and perform a check for updates, updating the timestamp in the process. This can be useful if you want to ensure that a check for updates is performed even if one was recently done, such as when the user explicitly requests it or when certain conditions are met that warrant an immediate check."
+				});
+			}
+		}),
+		(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+		(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.InterfaceDeclaration, {
+			name: "CheckForUpdatesBaseResult",
+			get children() {
+				return (0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.InterfaceMember, {
+					name: "isError",
+					type: "boolean",
+					optional: true,
+					doc: "Indicates whether an error occurred while checking for updates."
+				});
+			}
+		}),
+		(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+		(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.InterfaceDeclaration, {
+			name: "CheckForUpdatesSuccessResult",
+			"extends": "CheckForUpdatesBaseResult",
+			get children() {
+				return [
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.InterfaceMember, {
+						name: "latestVersion",
+						type: "string",
+						doc: "The latest version of the application dependencies."
+					}),
+					(0, __alloy_js_core_jsx_runtime.createIntrinsic)("hbr", {}),
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.InterfaceMember, {
+						name: "currentVersion",
+						type: "string",
+						doc: "The current version of the application dependencies."
+					}),
+					(0, __alloy_js_core_jsx_runtime.createIntrinsic)("hbr", {}),
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.InterfaceMember, {
+						name: "isUpToDate",
+						type: "boolean",
+						doc: "Indicates whether the application dependencies are up-to-date."
+					}),
+					(0, __alloy_js_core_jsx_runtime.createIntrinsic)("hbr", {}),
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.InterfaceMember, {
+						name: "package",
+						type: "NpmPackage",
+						optional: true,
+						doc: "The npm package that was checked for updates."
+					})
+				];
+			}
+		}),
+		(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+		(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.InterfaceDeclaration, {
+			name: "CheckForUpdatesErrorResult",
+			"extends": "CheckForUpdatesBaseResult",
+			get children() {
+				return (0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.InterfaceMember, {
+					name: "error",
+					type: "Error",
+					doc: "The error that occurred while checking for updates."
+				});
+			}
+		}),
+		(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+		(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TypeDeclaration, {
+			"export": true,
+			name: "CheckForUpdatesResult",
+			doc: "The result for the `checkForUpdates` handler function.",
+			children: __alloy_js_core.code`CheckForUpdatesSuccessResult | CheckForUpdatesErrorResult;`
+		}),
+		(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+		(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDoc, {
+			heading: "Check for updates to the application dependencies.",
+			get children() {
+				return [
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDocRemarks, { children: `This function is used to check for updates to the application dependencies. It can be used in the CLI upgrade command to ensure that all necessary dependencies are up-to-date.` }),
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDocParam, {
+						name: "options",
+						children: `The options for the \`checkForUpdates\` function. Currently, there are no options available, but this parameter is included for future extensibility.`
+					}),
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_typescript.TSDocReturns, { children: `A promise that resolves when the check for updates is complete or undefined if the check was not performed.` })
+				];
+			}
+		}),
+		(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.FunctionDeclaration, {
+			"export": true,
+			async: true,
+			name: "checkForUpdates",
+			parameters: [{
+				name: "options",
+				type: "CheckForUpdatesOptions",
+				default: "{}"
+			}],
+			returnType: "CheckForUpdatesResult",
+			get children() {
+				return [
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.IfStatement, {
+						condition: __alloy_js_core.code`!options.force && !(await isCheckForUpdatesRequired())`,
+						get children() {
+							return __alloy_js_core.code`return {
+            latestVersion: "${context.packageJson.version}",
+            currentVersion: "${context.packageJson.version}",
+            isUpToDate: true,
+            isError: false,
+          }; `;
+						}
+					}),
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+					__alloy_js_core.code`try { `,
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_typescript.VarDeclaration, {
+						"const": true,
+						name: "pkg",
+						get initializer() {
+							return __alloy_js_core.code`await fetchNpmPackage("${context.packageJson.name}"); `;
+						}
+					}),
+					(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+					(0, __alloy_js_core_jsx_runtime.memo)(() => __alloy_js_core.code`
+          return {
+            latestVersion: pkg?.version || "${context.packageJson.version}",
+            currentVersion: "${context.packageJson.version}",
+            isUpToDate: pkg ? "${context.packageJson.version}" === pkg.version : true,
+            package: pkg,
+            isError: false,
+          };
+        } catch (err) {
+          return { isError: true, error: err instanceof Error ? err : new Error(String(err)) };
+        } `)
+				];
+			}
+		})
+	];
+}
+/**
 * A built-in upgrade module for Shell Shock.
 */
 function UpgradeBuiltin(props) {
@@ -657,7 +1017,11 @@ function UpgradeBuiltin(props) {
 				"node:os": "os",
 				"node:path": ["join", "resolve"],
 				"node:fs": ["existsSync"],
-				"node:fs/promises": ["readFile", "writeFile"],
+				"node:fs/promises": [
+					"readFile",
+					"writeFile",
+					"mkdir"
+				],
 				"node:process": "process"
 			});
 		},
@@ -668,8 +1032,17 @@ function UpgradeBuiltin(props) {
 					"verbose",
 					"writeLine"
 				],
-				env: ["paths", "isWindows"],
-				utils: ["isColorSupported", "spawn"]
+				env: [
+					"paths",
+					"isWindows",
+					"isCI",
+					"env"
+				],
+				utils: [
+					"isColorSupported",
+					"isInteractive",
+					"spawn"
+				]
 			});
 		},
 		get children() {
@@ -688,15 +1061,25 @@ function UpgradeBuiltin(props) {
 					initializer: __alloy_js_core.code`os.tmpdir(); `
 				}),
 				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(LocatePackageJsonFunctionDeclaration, {}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
 				(0, __alloy_js_core_jsx_runtime.createComponent)(LocateLockfileFunctionDeclaration, {}),
 				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
 				(0, __alloy_js_core_jsx_runtime.createComponent)(GetPackageManagerFunctionDeclaration, {}),
 				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
 				(0, __alloy_js_core_jsx_runtime.createComponent)(FetchNpmPackageFunctionDeclaration, {}),
 				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
-				(0, __alloy_js_core_jsx_runtime.createComponent)(GetLatestFunctionDeclaration, {}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(GetLatestVersionFunctionDeclaration, {}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(GetUpgradeCommandFunctionDeclaration, {}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(UpgradeFunctionDeclaration, {}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(CheckForUpdatesFunctionDeclaration, {}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(IsCheckForUpdatesRequiredFunctionDeclaration, {}),
 				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
-				(0, __alloy_js_core_jsx_runtime.createComponent)(InstallFunctionDeclaration, {}),
+				(0, __alloy_js_core_jsx_runtime.createComponent)(UpdateVersionCheckFileFunctionDeclaration, {}),
 				(0, __alloy_js_core_jsx_runtime.createComponent)(__powerlines_plugin_alloy_core_components_spacing.Spacing, {}),
 				(0, __alloy_js_core_jsx_runtime.createComponent)(__alloy_js_core.Show, {
 					get when() {
@@ -710,10 +1093,14 @@ function UpgradeBuiltin(props) {
 }
 
 //#endregion
+exports.CheckForUpdatesFunctionDeclaration = CheckForUpdatesFunctionDeclaration;
 exports.FetchNpmPackageFunctionDeclaration = FetchNpmPackageFunctionDeclaration;
-exports.GetLatestFunctionDeclaration = GetLatestFunctionDeclaration;
+exports.GetLatestVersionFunctionDeclaration = GetLatestVersionFunctionDeclaration;
 exports.GetPackageManagerFunctionDeclaration = GetPackageManagerFunctionDeclaration;
-exports.InstallFunctionDeclaration = InstallFunctionDeclaration;
+exports.GetUpgradeCommandFunctionDeclaration = GetUpgradeCommandFunctionDeclaration;
+exports.IsCheckForUpdatesRequiredFunctionDeclaration = IsCheckForUpdatesRequiredFunctionDeclaration;
 exports.LocateLockfileFunctionDeclaration = LocateLockfileFunctionDeclaration;
 exports.LocatePackageJsonFunctionDeclaration = LocatePackageJsonFunctionDeclaration;
-exports.UpgradeBuiltin = UpgradeBuiltin;
+exports.UpdateVersionCheckFileFunctionDeclaration = UpdateVersionCheckFileFunctionDeclaration;
+exports.UpgradeBuiltin = UpgradeBuiltin;
+exports.UpgradeFunctionDeclaration = UpgradeFunctionDeclaration;