refactor: share install flows across hooks and plugins

src/infra/install-flow.ts

@@ -0,0 +1,61 @@
+import type { Stats } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveUserPath } from "../utils.js";
+import { type ArchiveLogger, extractArchive, fileExists, resolvePackedRootDir } from "./archive.js";
+import { withTempDir } from "./install-source-utils.js";
+
+export type ExistingInstallPathResult =
+  | {
+      ok: true;
+      resolvedPath: string;
+      stat: Stats;
+    }
+  | {
+      ok: false;
+      error: string;
+    };
+
+export async function resolveExistingInstallPath(
+  inputPath: string,
+): Promise<ExistingInstallPathResult> {
+  const resolvedPath = resolveUserPath(inputPath);
+  if (!(await fileExists(resolvedPath))) {
+    return { ok: false, error: `path not found: ${resolvedPath}` };
+  }
+  const stat = await fs.stat(resolvedPath);
+  return { ok: true, resolvedPath, stat };
+}
+
+export async function withExtractedArchiveRoot<TResult extends { ok: boolean }>(params: {
+  archivePath: string;
+  tempDirPrefix: string;
+  timeoutMs: number;
+  logger?: ArchiveLogger;
+  onExtracted: (rootDir: string) => Promise<TResult>;
+}): Promise<TResult | { ok: false; error: string }> {
+  return await withTempDir(params.tempDirPrefix, async (tmpDir) => {
+    const extractDir = path.join(tmpDir, "extract");
+    await fs.mkdir(extractDir, { recursive: true });
+
+    params.logger?.info?.(`Extracting ${params.archivePath}…`);
+    try {
+      await extractArchive({
+        archivePath: params.archivePath,
+        destDir: extractDir,
+        timeoutMs: params.timeoutMs,
+        logger: params.logger,
+      });
+    } catch (err) {
+      return { ok: false, error: `failed to extract archive: ${String(err)}` };
+    }
+
+    let rootDir = "";
+    try {
+      rootDir = await resolvePackedRootDir(extractDir);
+    } catch (err) {
+      return { ok: false, error: String(err) };
+    }
+    return await params.onExtracted(rootDir);
+  });
+}

src/infra/install-mode-options.ts

@@ -0,0 +1,42 @@
+export type InstallMode = "install" | "update";
+
+export type InstallModeOptions<TLogger> = {
+  logger?: TLogger;
+  mode?: InstallMode;
+  dryRun?: boolean;
+};
+
+export type TimedInstallModeOptions<TLogger> = InstallModeOptions<TLogger> & {
+  timeoutMs?: number;
+};
+
+export function resolveInstallModeOptions<TLogger>(
+  params: InstallModeOptions<TLogger>,
+  defaultLogger: TLogger,
+): {
+  logger: TLogger;
+  mode: InstallMode;
+  dryRun: boolean;
+} {
+  return {
+    logger: params.logger ?? defaultLogger,
+    mode: params.mode ?? "install",
+    dryRun: params.dryRun ?? false,
+  };
+}
+
+export function resolveTimedInstallModeOptions<TLogger>(
+  params: TimedInstallModeOptions<TLogger>,
+  defaultLogger: TLogger,
+  defaultTimeoutMs = 120_000,
+): {
+  logger: TLogger;
+  timeoutMs: number;
+  mode: InstallMode;
+  dryRun: boolean;
+} {
+  return {
+    ...resolveInstallModeOptions(params, defaultLogger),
+    timeoutMs: params.timeoutMs ?? defaultTimeoutMs,
+  };
+}

src/infra/npm-pack-install.ts

@@ -21,6 +21,58 @@ export type NpmSpecArchiveInstallFlowResult<TResult extends { ok: boolean }> =
       integrityDrift?: NpmIntegrityDrift;
     };
 
+export async function installFromNpmSpecArchiveWithInstaller<
+  TResult extends { ok: boolean },
+  TArchiveInstallParams extends { archivePath: string },
+>(params: {
+  tempDirPrefix: string;
+  spec: string;
+  timeoutMs: number;
+  expectedIntegrity?: string;
+  onIntegrityDrift?: (payload: NpmIntegrityDriftPayload) => boolean | Promise<boolean>;
+  warn?: (message: string) => void;
+  installFromArchive: (params: TArchiveInstallParams) => Promise<TResult>;
+  archiveInstallParams: Omit<TArchiveInstallParams, "archivePath">;
+}): Promise<NpmSpecArchiveInstallFlowResult<TResult>> {
+  return await installFromNpmSpecArchive({
+    tempDirPrefix: params.tempDirPrefix,
+    spec: params.spec,
+    timeoutMs: params.timeoutMs,
+    expectedIntegrity: params.expectedIntegrity,
+    onIntegrityDrift: params.onIntegrityDrift,
+    warn: params.warn,
+    installFromArchive: async ({ archivePath }) =>
+      await params.installFromArchive({
+        archivePath,
+        ...params.archiveInstallParams,
+      } as TArchiveInstallParams),
+  });
+}
+
+export type NpmSpecArchiveFinalInstallResult<TResult extends { ok: boolean }> =
+  | { ok: false; error: string }
+  | Exclude<TResult, { ok: true }>
+  | (Extract<TResult, { ok: true }> & {
+      npmResolution: NpmSpecResolution;
+      integrityDrift?: NpmIntegrityDrift;
+    });
+
+export function finalizeNpmSpecArchiveInstall<TResult extends { ok: boolean }>(
+  flowResult: NpmSpecArchiveInstallFlowResult<TResult>,
+): NpmSpecArchiveFinalInstallResult<TResult> {
+  if (!flowResult.ok) {
+    return flowResult;
+  }
+  if (!flowResult.installResult.ok) {
+    return flowResult.installResult;
+  }
+  return {
+    ...flowResult.installResult,
+    npmResolution: flowResult.npmResolution,
+    integrityDrift: flowResult.integrityDrift,
+  };
+}
+
 export async function installFromNpmSpecArchive<TResult extends { ok: boolean }>(params: {
   tempDirPrefix: string;
   spec: string;