sailfork / t3code-github / packages/ provider-core/ src/ server/ maintenanceResolver.ts
export type {
ProviderMaintenanceCapabilities,
ProviderMaintenanceCommandAction,
} from "@t3tools/provider-core/server/maintenance";
import type {
ProviderMaintenanceCapabilities,
ProviderMaintenanceCommandAction,
} from "@t3tools/provider-core/server/maintenance";
import {
ProviderDriverKind,
type ServerProvider,
type ServerProviderVersionAdvisory,
} from "@t3tools/contracts";
import { compareSemverVersions, satisfiesSemverRange } from "@t3tools/shared/semver";
import * as HostProcess from "@t3tools/shared/HostProcess";
import { causeErrorTag } from "@t3tools/shared/observability";
import { resolveCommandPath, resolveSpawnCommand } from "@t3tools/shared/shell";
import * as Cache from "effect/Cache";
import * as Config from "effect/Config";
import * as DateTime from "effect/DateTime";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Option from "effect/Option";
import * as Path from "effect/Path";
import * as Schema from "effect/Schema";
import * as Stream from "effect/Stream";
import * as HttpClient from "effect/http/HttpClient";
import * as HttpClientRequest from "effect/http/HttpClientRequest";
import * as HttpClientResponse from "effect/http/HttpClientResponse";
import * as ChildProcess from "effect/process/ChildProcess";
import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
import { collectUint8StreamText } from "./collectStreamText.ts";
import * as ProviderLatestVersions from "./ProviderLatestVersions.ts";
const LATEST_VERSION_TIMEOUT_MS = 4_000;
const PROBE_TIMEOUT_MS = 10_000;
const PROBE_MAX_BYTES = 256 * 1_024;
const MISE_WRAPPER_MAX_BYTES = 16 * 1_024;
const PROVIDER_UPDATE_ACTION_TOAST_MESSAGE = "Install the update now or review provider settings.";
const MAINTENANCE_CAPABILITIES_CACHE_TTL = Duration.hours(1);
const compactEnv = (input: Record<string, Option.Option<string>>): NodeJS.ProcessEnv =>
Object.fromEntries(
Object.entries(input).flatMap(([key, value]) =>
Option.match(value, {
onNone: () => [],
onSome: (resolved) => [[key, resolved]],
}),
),
);
const CommandLookupEnvConfig = Config.all({
PATH: Config.String("PATH").pipe(Config.option),
Path: Config.String("Path").pipe(Config.option),
path: Config.String("path").pipe(Config.option),
PATHEXT: Config.String("PATHEXT").pipe(Config.option),
}).pipe(Config.map(compactEnv));
const readCommandLookupEnv = CommandLookupEnvConfig.pipe(Effect.orElseSucceed(() => ({})));
export interface ProviderMaintenanceResolutionContext {
readonly binaryPath: string;
readonly resolvedCommandPath: string;
readonly realCommandPath: string;
readonly env: NodeJS.ProcessEnv;
readonly platform: NodeJS.Platform;
}
export type ProviderMaintenanceResolverServices =
| FileSystem.FileSystem
| Path.Path
| ChildProcessSpawner.ChildProcessSpawner;
export interface ProviderMaintenanceCapabilitiesResolver {
readonly resolve: (
context: ProviderMaintenanceResolutionContext | null,
) => Effect.Effect<ProviderMaintenanceCapabilities, never, ProviderMaintenanceResolverServices>;
}
export interface PackageManagedProviderMaintenanceDefinition {
readonly provider: ProviderDriverKind;
readonly npmPackageName: string;
readonly nativeUpdate: {
readonly args: ReadonlyArray<string>;
readonly isCommandPath?: (commandPath: string) => boolean;
/** The updater cannot detect installs outside `isCommandPath`, so leave those manual-only. */
readonly requiresCommandPath?: boolean;
readonly env?:
| NodeJS.ProcessEnv
| ((context: ProviderMaintenanceResolutionContext) => NodeJS.ProcessEnv);
} | null;
}
const NpmLatestVersionResponse = Schema.Struct({
version: Schema.optional(Schema.String),
});
function nonEmptyString(value: unknown): string | null {
return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
}
function quoteShellWord(word: string, platform: NodeJS.Platform): string {
const safeWord = platform === "win32" ? /^[\w./:\\@=-]+$/ : /^[\w./:@=-]+$/;
if (safeWord.test(word)) return word;
return platform === "win32"
? `'${word.replace(/['\u2018\u2019]/g, "Loading Sailfork
amp;Loading Sailfork
amp;")}'`
: `'${word.replaceAll("'", "'\\''")}'`;
}
function quoteUpdateExecutable(executable: string, platform: NodeJS.Platform): string {
const quoted = quoteShellWord(executable, platform);
// Windows terminals default to PowerShell, where a quoted executable needs &.
return platform === "win32" && quoted !== executable ? `& ${quoted}` : quoted;
}
export function makeProviderMaintenanceCapabilities(input: {
readonly provider: ProviderDriverKind;
readonly packageName: string | null;
readonly updateExecutable: string | null;
readonly updateArgs: ReadonlyArray<string>;
readonly updateLockKey: string | null;
readonly updateCommand?: string;
readonly platform?: NodeJS.Platform;
readonly env?: NodeJS.ProcessEnv;
readonly latestVersion?: string | null;
readonly lookupLatestVersion?: Effect.Effect<string | null>;
}): ProviderMaintenanceCapabilities {
const platform = input.platform ?? HostProcess.Platform.defaultValue();
const update =
input.updateExecutable === null || input.updateLockKey === null
? null
: {
command:
input.updateCommand ??
[
quoteUpdateExecutable(input.updateExecutable, platform),
...input.updateArgs.map((arg) => quoteShellWord(arg, platform)),
].join(" "),
executable: input.updateExecutable,
args: input.updateArgs,
lockKey: input.updateLockKey,
...(input.env ? { env: input.env } : {}),
};
return {
provider: input.provider,
packageName: input.packageName,
update,
...("latestVersion" in input ? { latestVersion: input.latestVersion } : {}),
...(input.lookupLatestVersion ? { lookupLatestVersion: input.lookupLatestVersion } : {}),
};
}
export function makeTargetedProviderUpdateAction(
capabilities: ProviderMaintenanceCapabilities,
version: string,
): ProviderMaintenanceCommandAction | null {
if (!/^\d+\.\d+\.\d+$/.test(version)) return null;
const update = capabilities.update;
const packageName = capabilities.packageName;
if (!update || !packageName) return null;
if (
!/^(?:npm-global:|bun-global$|pnpm-global$|vite-plus-global$|yarn-global$|volta$)/.test(
update.lockKey,
)
)
return null;
const packageIndex = update.args.findIndex(
(arg) => arg === `${packageName}@latest` || arg === packageName,
);
if (packageIndex < 0) return null;
const args = update.args.map((arg, index) =>
index === packageIndex ? `${packageName}@${version}` : arg,
);
const previous = update.args[packageIndex]!;
const commandIndex = update.command.lastIndexOf(previous);
const command =
commandIndex < 0
? update.command
: `${update.command.slice(0, commandIndex)}${packageName}@${version}${update.command.slice(commandIndex + previous.length)}`;
return { ...update, args, command };
}
// pnpm 11 resolves `@latest` to the newest release older than `minimumReleaseAge`
// and exits 0, so a release advertised from the npm dist-tag would never install.
// An exact spec installs it and pnpm records it in `minimumReleaseAgeExclude`.
export function resolveLatestProviderUpdateAction(
capabilities: ProviderMaintenanceCapabilities,
latestVersion: string | null,
): ProviderMaintenanceCommandAction | null {
const update = capabilities.update;
if (update?.lockKey !== "pnpm-global" || latestVersion === null) return update;
return makeTargetedProviderUpdateAction(capabilities, latestVersion) ?? update;
}
export function makeManualOnlyProviderMaintenanceCapabilities(input: {
readonly provider: ProviderDriverKind;
readonly packageName: string | null;
readonly installPath?: string;
readonly lookupLatestVersion?: Effect.Effect<string | null>;
readonly manualCommand?: string;
}): ProviderMaintenanceCapabilities {
return {
...makeProviderMaintenanceCapabilities({
provider: input.provider,
packageName: input.packageName,
updateExecutable: null,
updateArgs: [],
updateLockKey: null,
...(input.lookupLatestVersion
? { latestVersion: null, lookupLatestVersion: input.lookupLatestVersion }
: {}),
}),
...(input.installPath ? { installPath: input.installPath } : {}),
...(input.manualCommand ? { manualCommand: input.manualCommand } : {}),
};
}
export function normalizeCommandPath(commandPath: string): string {
return commandPath.replaceAll("\\", "/").toLowerCase();
}
/**
* Vite+ shims live in `<VP_HOME>/bin`: `~/.vite-plus` by default,
* `~/.local/share/vite-plus` with the XDG layout, and `%LOCALAPPDATA%\vite-plus`
* on Windows.
*/
function isVitePlusGlobalCommandPath(commandPath: string): boolean {
return /\/(?:\.vite-plus|\.local\/share\/vite-plus|appdata\/local\/vite-plus)\/bin\//.test(
normalizeCommandPath(commandPath),
);
}
function isBunGlobalCommandPath(commandPath: string): boolean {
return normalizeCommandPath(commandPath).includes("/.bun/bin/");
}
function isYarnGlobalCommandPath(commandPath: string): boolean {
return /\/yarn\/(?:data\/)?global\/node_modules\//.test(normalizeCommandPath(commandPath));
}
/**
* Version-manager installs are pinned in its config, so updating them means editing that.
* A command wrapper is a symlink to the `mise` binary, which dispatches on argv[0].
*/
function isMiseCommandPath(commandPath: string): boolean {
const normalized = normalizeCommandPath(commandPath);
return (
normalized.includes("/mise/installs/") ||
normalized.includes("/mise/shims/") ||
normalized.includes("/mise/command-wrappers/") ||
/\/mise(?:\.exe)?$/.test(normalized)
);
}
const winGetClaudeCommandPath =
/^[a-z]:\/(?:users\/[^/]+\/appdata\/local\/microsoft|program files(?: \(x86\))?)\/winget\/(?:links|packages\/anthropic\.claudecode_[^/]+)\/claude\.exe$/;
function isWinGetClaudeCommandPath(commandPath: string): boolean {
return winGetClaudeCommandPath.test(normalizeCommandPath(commandPath));
}
const CHOCOLATEY_CLAUDE_PACKAGE_ID = "claude-code";
// Chocolatey's executable shim is not a symlink, so realpath cannot prove its owner.
const chocolateyClaudeCommandPath = /\/chocolatey\/(?:bin|lib\/claude-code\/tools)\/claude\.exe$/;
function isChocolateyClaudeCommandPath(commandPath: string, env: NodeJS.ProcessEnv): boolean {
const normalized = normalizeCommandPath(commandPath);
if (chocolateyClaudeCommandPath.test(normalized)) return true;
const root = nonEmptyString(env.ChocolateyInstall);
if (!root) return false;
const prefix = normalizeCommandPath(root.replace(/[\\/]+$/, ""));
return (
normalized === `${prefix}/bin/claude.exe` ||
normalized === `${prefix}/lib/claude-code/tools/claude.exe`
);
}
/** `choco search --exact --limit-output` prints `<id>|<version>` for a match and nothing otherwise. */
export function parseChocolateyLatestVersion(output: string, packageId: string): string | null {
for (const line of output.split(/\r?\n/)) {
const [id, version] = line.trim().split("|", 2);
if (id?.toLowerCase() === packageId.toLowerCase()) return nonEmptyString(version);
}
return null;
}
function isPnpmGlobalCommandPath(commandPath: string): boolean {
const normalized = normalizeCommandPath(commandPath);
return (
normalized.includes("/.local/share/pnpm/") ||
normalized.includes("/library/pnpm/") ||
normalized.includes("/local/share/pnpm/") ||
normalized.includes("/appdata/local/pnpm/") ||
normalized.includes("/pnpm/global/")
);
}
export function npmGlobalPrefixFromCommandPath(
realCommandPath: string,
packageName: string,
): string | null {
const slashPath = realCommandPath.replaceAll("\\", "/");
const normalized = slashPath.toLowerCase();
const packageSegment = `/lib/node_modules/${packageName.toLowerCase()}/`;
const packageIndex = normalized.lastIndexOf(packageSegment);
if (packageIndex < 0 || normalized.slice(0, packageIndex).includes("/node_modules/")) {
return null;
}
// Mise tool layouts resemble npm globals; only globals under its Node install belong to npm.
const miseTool = /\/mise\/installs\/([^/]+)\/[^/]+$/.exec(normalized.slice(0, packageIndex))?.[1];
if (miseTool && miseTool !== "node") {
return null;
}
return packageIndex === 0 ? "/" : slashPath.slice(0, packageIndex);
}
const HOMEBREW_KEG_PATTERN = /^(.*)\/(cellar|caskroom)\/([^/]+)\/[^/]+\//i;
export interface HomebrewOwnership {
readonly kind: "formula" | "cask";
readonly name: string;
readonly prefix: string;
}
export function homebrewOwnershipFromCommandPath(
realCommandPath: string,
): HomebrewOwnership | null {
const match = HOMEBREW_KEG_PATTERN.exec(realCommandPath.replaceAll("\\", "/"));
if (!match) {
return null;
}
return {
kind: match[2]!.toLowerCase() === "cellar" ? "formula" : "cask",
name: match[3]!,
prefix: match[1]!,
};
}
const HomebrewInfoResponse = Schema.Struct({
formulae: Schema.optional(
Schema.Array(
Schema.Struct({
versions: Schema.optional(Schema.Struct({ stable: Schema.optional(Schema.String) })),
}),
),
),
casks: Schema.optional(Schema.Array(Schema.Struct({ version: Schema.optional(Schema.String) }))),
});
const decodeHomebrewInfo = Schema.decodeUnknownOption(Schema.fromJsonString(HomebrewInfoResponse));
export function parseHomebrewLatestVersion(
infoJson: string,
ownership: HomebrewOwnership,
): string | null {
const decoded = decodeHomebrewInfo(infoJson);
if (Option.isNone(decoded)) {
return null;
}
const raw =
ownership.kind === "formula"
? decoded.value.formulae?.[0]?.versions?.stable
: decoded.value.casks?.[0]?.version?.split(",", 1)[0];
const version = nonEmptyString(raw);
return version === "latest" ? null : version;
}
const runProbe = Effect.fn("runProbe")(function* (
command: string,
args: ReadonlyArray<string>,
env: NodeJS.ProcessEnv,
okExitCodes: ReadonlyArray<number> = [0],
) {
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
const collect = Effect.gen(function* () {
// Windows package managers are `.cmd` shims that need the shell.
const resolved = yield* resolveSpawnCommand(command, args, { env, extendEnv: true });
const child = yield* spawner.spawn(
ChildProcess.make(resolved.command, resolved.args, {
env,
extendEnv: true,
shell: resolved.shell,
}),
);
yield* Effect.addFinalizer(() => child.kill().pipe(Effect.ignore));
// stderr is drained so a chatty tool cannot block on a full pipe.
const [stdout, exitCode] = yield* Effect.all(
[
collectUint8StreamText({ stream: child.stdout, maxBytes: PROBE_MAX_BYTES }),
child.exitCode,
Stream.runDrain(child.stderr),
],
{ concurrency: "unbounded" },
);
return !okExitCodes.includes(Number(exitCode)) || stdout.truncated ? null : stdout.text;
});
return yield* collect.pipe(
Effect.scoped,
Effect.timeoutOption(Duration.millis(PROBE_TIMEOUT_MS)),
Effect.map(Option.getOrNull),
Effect.catchCause((cause) =>
Effect.logWarning("Maintenance probe failed", {
command,
subcommand: args[0],
errorTag: causeErrorTag(cause),
}).pipe(Effect.as(null)),
),
);
});
const decodePnpmOutdated = Schema.decodeUnknownOption(
Schema.fromJsonString(
Schema.Record(Schema.String, Schema.Struct({ latest: Schema.optional(Schema.String) })),
),
);
const decodePnpmList = Schema.decodeUnknownOption(
Schema.fromJsonString(
Schema.Array(
Schema.Struct({
dependencies: Schema.optional(
Schema.Record(Schema.String, Schema.Struct({ version: Schema.optional(Schema.String) })),
),
}),
),
),
);
// Unlike npm's latest tag, pnpm outdated respects minimumReleaseAge and its excludes.
const resolvePnpmGlobalLatestVersion = Effect.fn("resolvePnpmGlobalLatestVersion")(function* (
packageName: string,
env: NodeJS.ProcessEnv,
) {
// Match the updater's pnpm and environment.
const pnpmPath = yield* resolveCommandPath("pnpm", {
env: { ...(yield* HostProcess.Environment), ...env },
});
if (!pnpmPath) return null;
// Silent reporting keeps project package-manager warnings out of the JSON.
const outdated = yield* runProbe(
pnpmPath,
["outdated", "-g", "--reporter=silent", "--format", "json", packageName],
env,
// pnpm outdated exits 1 when updates are available.
[0, 1],
);
const outdatedEntries = outdated
? Option.getOrUndefined(decodePnpmOutdated(outdated))
: undefined;
if (!outdatedEntries) return null;
const latest = nonEmptyString(outdatedEntries[packageName]?.latest);
if (latest) return latest;
// An empty result means the installed version is still the eligible release.
const listed = yield* runProbe(
pnpmPath,
["ls", "-g", "--reporter=silent", "--depth", "0", "--json", packageName],
env,
);
const listedEntries = listed ? Option.getOrUndefined(decodePnpmList(listed)) : undefined;
return nonEmptyString(listedEntries?.[0]?.dependencies?.[packageName]?.version);
});
export const resolvePackageManagedProviderMaintenance = Effect.fn(
"resolvePackageManagedProviderMaintenance",
)(function* (
definition: PackageManagedProviderMaintenanceDefinition,
context: ProviderMaintenanceResolutionContext | null,
) {
if (!context) {
return makeManualOnlyProviderMaintenanceCapabilities({
provider: definition.provider,
packageName: definition.npmPackageName,
});
}
const manual = makeManualOnlyProviderMaintenanceCapabilities({
provider: definition.provider,
packageName: definition.npmPackageName,
installPath: context.realCommandPath,
});
const commandPaths = [context.resolvedCommandPath, context.realCommandPath];
const packageName = definition.npmPackageName;
// WinGet-managed claude update exits 0 without updating; T3 does not run winget upgrade.
if (
definition.provider === "claudeAgent" &&
context.platform === "win32" &&
commandPaths.some(isWinGetClaudeCommandPath)
) {
return manual;
}
// Chocolatey's package directory is writable only by administrators, so an
// unelevated server cannot run `choco upgrade`; `claude update` through the
// shim installs a native copy elsewhere and leaves the shim's version alone.
if (
definition.provider === "claudeAgent" &&
context.platform === "win32" &&
commandPaths.some((commandPath) => isChocolateyClaudeCommandPath(commandPath, context.env))
) {
const services = yield* Effect.context<ProviderMaintenanceResolverServices>();
return makeManualOnlyProviderMaintenanceCapabilities({
provider: definition.provider,
packageName,
installPath: context.realCommandPath,
manualCommand: "choco upgrade claude-code",
lookupLatestVersion: runProbe(
"choco",
["search", CHOCOLATEY_CLAUDE_PACKAGE_ID, "--exact", "--limit-output"],
context.env,
).pipe(
Effect.map((output) =>
output ? parseChocolateyLatestVersion(output, CHOCOLATEY_CLAUDE_PACKAGE_ID) : null,
),
Effect.provideContext(services),
),
});
}
const nativeUpdate = definition.nativeUpdate;
const nativeEnv = nativeUpdate?.env;
const native = nativeUpdate
? makeProviderMaintenanceCapabilities({
provider: definition.provider,
packageName,
updateExecutable: context.resolvedCommandPath,
updateArgs: nativeUpdate.args,
updateLockKey: `${definition.provider}-native`,
platform: context.platform,
...(nativeEnv
? { env: typeof nativeEnv === "function" ? nativeEnv(context) : nativeEnv }
: {}),
})
: manual;
// A native-looking launcher can still delegate to an npm- or mise-owned install.
if (
nativeUpdate?.isCommandPath &&
commandPaths.some(nativeUpdate.isCommandPath) &&
!npmGlobalPrefixFromCommandPath(context.realCommandPath, packageName) &&
!commandPaths.some(isMiseCommandPath) &&
!(yield* isMiseWrapperScript(context))
) {
return native;
}
// A `node_modules` path not proven below belongs to another package or a
// project, so the provider's own updater could act on the wrong install.
const fallback =
nativeUpdate?.requiresCommandPath ||
commandPaths.some((commandPath) => normalizeCommandPath(commandPath).includes("/node_modules/"))
? manual
: native;
if (commandPaths.some(isVitePlusGlobalCommandPath)) {
return makeProviderMaintenanceCapabilities({
provider: definition.provider,
packageName,
updateExecutable: "vp",
updateArgs: ["i", "-g", packageName],
updateLockKey: "vite-plus-global",
env: context.env,
});
}
if (commandPaths.some(isBunGlobalCommandPath)) {
return makeProviderMaintenanceCapabilities({
provider: definition.provider,
packageName,
updateExecutable: "bun",
updateArgs: ["i", "-g", `${packageName}@latest`],
updateLockKey: "bun-global",
env: context.env,
});
}
if (commandPaths.some(isPnpmGlobalCommandPath)) {
// pnpm 10 skips unapproved scripts; the approval flag requires 10.4+.
const pnpmVersion = yield* runProbe("pnpm", ["--version"], context.env);
const allowBuild =
pnpmVersion !== null && satisfiesSemverRange(pnpmVersion, ">=10.4.0")
? [`--allow-build=${packageName}`]
: [];
const services = yield* Effect.context<ProviderMaintenanceResolverServices>();
return makeProviderMaintenanceCapabilities({
provider: definition.provider,
packageName,
updateExecutable: "pnpm",
updateArgs: ["add", "-g", ...allowBuild, `${packageName}@latest`],
updateLockKey: "pnpm-global",
env: context.env,
lookupLatestVersion: resolvePnpmGlobalLatestVersion(packageName, context.env).pipe(
Effect.provideContext(services),
),
});
}
if (commandPaths.some(isYarnGlobalCommandPath)) {
return makeProviderMaintenanceCapabilities({
provider: definition.provider,
packageName,
updateExecutable: "yarn",
updateArgs: ["global", "add", `${packageName}@latest`],
updateLockKey: "yarn-global",
env: context.env,
});
}
if (yield* isVoltaPackageInstall(context, packageName)) {
return makeProviderMaintenanceCapabilities({
provider: definition.provider,
packageName,
updateExecutable: "volta",
updateArgs: ["install", `${packageName}@latest`],
updateLockKey: "volta",
env: context.env,
});
}
// npm proof outranks a containing Homebrew keg; Homebrew Node globals still belong to npm.
const npmPrefix = yield* resolveNpmGlobalPrefix(context, packageName);
if (npmPrefix) {
// npm 12 requires script approval to install native binaries; older npm only warns about the flag.
return makeProviderMaintenanceCapabilities({
provider: definition.provider,
packageName,
updateExecutable: "npm",
updateArgs: [
"install",
"-g",
"--prefix",
npmPrefix,
`--allow-scripts=${packageName}`,
`${packageName}@latest`,
],
updateLockKey: `npm-global:${normalizeCommandPath(npmPrefix)}`,
env: context.env,
});
}
const homebrew = homebrewOwnershipFromCommandPath(context.realCommandPath);
if (
commandPaths.some(isMiseCommandPath) ||
// Mise shims resolve to the version manager's keg, not the provider's.
(homebrew?.kind === "formula" && homebrew.name.toLowerCase() === "mise") ||
(yield* isMiseWrapperScript(context))
) {
return manual;
}
if (homebrew) {
return (
(yield* resolveHomebrewProviderMaintenance(
{ provider: definition.provider, packageName },
homebrew,
context,
)) ?? fallback
);
}
return fallback;
});
/**
* `brew upgrade` capabilities once the keg's prefix is confirmed by a `brew`
* that reports it as its own. Version checks defer `brew info` until needed.
* Null when no `brew` is found or it owns another prefix.
*/
export const resolveHomebrewProviderMaintenance = Effect.fn("resolveHomebrewProviderMaintenance")(
function* (
input: { readonly provider: ProviderDriverKind; readonly packageName: string | null },
homebrew: HomebrewOwnership,
context: ProviderMaintenanceResolutionContext,
) {
const fileSystem = yield* FileSystem.FileSystem;
const path = yield* Path.Path;
// GUI servers may lack Homebrew on PATH; use the keg brew with the same prefix check.
const kegBrewPath = path.join(homebrew.prefix, "bin", "brew");
const brewPath = (yield* fileSystem.exists(kegBrewPath).pipe(Effect.orElseSucceed(() => false)))
? kegBrewPath
: yield* resolveCommandPath("brew", { env: context.env });
if (!brewPath) {
return null;
}
const brewPrefix = nonEmptyString(yield* runProbe(brewPath, ["--prefix"], context.env));
const realBrewPrefix = brewPrefix
? yield* fileSystem.realPath(brewPrefix).pipe(Effect.orElseSucceed(() => brewPrefix))
: null;
if (
!realBrewPrefix ||
normalizeCommandPath(realBrewPrefix) !== normalizeCommandPath(homebrew.prefix)
) {
return null;
}
const args =
homebrew.kind === "cask" ? ["upgrade", "--cask", homebrew.name] : ["upgrade", homebrew.name];
const services = yield* Effect.context<ProviderMaintenanceResolverServices>();
return makeProviderMaintenanceCapabilities({
provider: input.provider,
packageName: input.packageName,
updateExecutable: brewPath,
updateArgs: args,
updateLockKey: "homebrew",
updateCommand: ["brew", ...args].join(" "),
// Brew's release can lag npm; only its own channel can say what upgrade installs.
latestVersion: null,
lookupLatestVersion: runProbe(
brewPath,
["info", "--json=v2", homebrew.name],
context.env,
).pipe(
Effect.map((info) => (info ? parseHomebrewLatestVersion(info, homebrew) : null)),
Effect.provideContext(services),
),
});
},
);
const isMiseWrapperScript = Effect.fn("isMiseWrapperScript")(function* (
context: ProviderMaintenanceResolutionContext,
) {
const fileSystem = yield* FileSystem.FileSystem;
const size = yield* fileSystem.stat(context.realCommandPath).pipe(
Effect.map((info) => Number(info.size)),
Effect.orElseSucceed(() => Infinity),
);
if (size > MISE_WRAPPER_MAX_BYTES) {
return false;
}
const script = yield* fileSystem
.readFileString(context.realCommandPath)
.pipe(Effect.orElseSucceed(() => ""));
return script.startsWith("#!") && /\bmise\s+(?:x|exec)\b/.test(script);
});
// Volta bin links only identify its shim; the package image proves ownership.
const isVoltaPackageInstall = Effect.fn("isVoltaPackageInstall")(function* (
context: ProviderMaintenanceResolutionContext,
packageName: string,
) {
const path = yield* Path.Path;
if (
path.basename(normalizeCommandPath(context.realCommandPath)).replace(/\.exe$/, "") !==
"volta-shim"
) {
return false;
}
const voltaHome = path.dirname(path.dirname(context.resolvedCommandPath));
const packageDir = path.join(voltaHome, "tools", "image", "packages", ...packageName.split("/"));
const fileSystem = yield* FileSystem.FileSystem;
return yield* fileSystem.exists(packageDir).pipe(Effect.orElseSucceed(() => false));
});
const resolveNpmGlobalPrefix = Effect.fn("resolveNpmGlobalPrefix")(function* (
context: ProviderMaintenanceResolutionContext,
packageName: string,
) {
const fromRealPath = npmGlobalPrefixFromCommandPath(context.realCommandPath, packageName);
if (fromRealPath) {
return fromRealPath;
}
if ((yield* HostProcess.Platform) !== "win32") {
return null;
}
const fileSystem = yield* FileSystem.FileSystem;
const path = yield* Path.Path;
const shimDir = path.dirname(context.resolvedCommandPath);
const manifestPath = path.join(
shimDir,
"node_modules",
...packageName.split("/"),
"package.json",
);
// Windows npm shims sit beside node_modules; POSIX project checkouts can mimic this layout.
const hasManifest = yield* fileSystem
.exists(manifestPath)
.pipe(Effect.orElseSucceed(() => false));
return hasManifest ? shimDir : null;
});
export function makePackageManagedProviderMaintenanceResolver(
definition: PackageManagedProviderMaintenanceDefinition,
): ProviderMaintenanceCapabilitiesResolver {
return {
resolve: (context) => resolvePackageManagedProviderMaintenance(definition, context),
};
}
function makeManualProviderMaintenanceCapabilities(
provider: ProviderDriverKind,
): ProviderMaintenanceCapabilities {
return makeManualOnlyProviderMaintenanceCapabilities({
provider,
packageName: null,
});
}
const decodeNpmViewVersion = Schema.decodeUnknownOption(
Schema.fromJsonString(Schema.Union([Schema.String, Schema.Tuple([Schema.String])])),
);
const withConfiguredNpmVersionLookup = Effect.fn("withConfiguredNpmVersionLookup")(function* (
capabilities: ProviderMaintenanceCapabilities,
) {
const packageName = capabilities.packageName;
if (!packageName || capabilities.latestVersion !== undefined) {
return capabilities;
}
const env = { ...(yield* HostProcess.Environment), ...capabilities.update?.env };
const npmPath = yield* resolveCommandPath("npm", { env });
if (!npmPath) return capabilities;
const services = yield* Effect.context<ProviderMaintenanceResolverServices>();
const update = capabilities.update;
const prefixIndex = update?.lockKey.startsWith("npm-global:")
? update.args.indexOf("--prefix")
: -1;
const prefix = prefixIndex >= 0 ? update?.args[prefixIndex + 1] : undefined;
const lookup = runProbe(
npmPath,
[
"view",
"--global",
...(prefix ? ["--prefix", prefix] : []),
"--json",
`${packageName}@latest`,
"version",
],
env,
).pipe(
Effect.map((stdout) => {
const value = stdout ? Option.getOrNull(decodeNpmViewVersion(stdout.trim())) : null;
return nonEmptyString(typeof value === "string" ? value : value?.[0]);
}),
Effect.tap((version) =>
version === null
? Effect.logWarning("Configured npm version lookup failed", { packageName })
: Effect.void,
),
Effect.provideContext(services),
);
return {
...capabilities,
// npm owns registry, scoped auth and proxy configuration; failure must not retry public npm.
latestVersion: null,
lookupLatestVersion: capabilities.lookupLatestVersion
? capabilities.lookupLatestVersion.pipe(
Effect.filterOrElse(
(version) => version !== null,
() => lookup,
),
)
: lookup,
};
});
export const resolveProviderMaintenanceCapabilitiesEffect = Effect.fn(
"resolveProviderMaintenanceCapabilitiesEffect",
)(function* (
resolver: ProviderMaintenanceCapabilitiesResolver,
options?: {
readonly binaryPath?: string | null;
readonly env?: NodeJS.ProcessEnv;
},
) {
const binaryPath = nonEmptyString(options?.binaryPath);
if (!binaryPath) {
return yield* resolver.resolve(null);
}
const env = options?.env ?? (yield* readCommandLookupEnv);
const resolvedCommandPath = yield* resolveCommandPath(binaryPath, { env });
if (!resolvedCommandPath) {
return yield* resolver.resolve(null);
}
const fileSystem = yield* FileSystem.FileSystem;
const realCommandPath = yield* fileSystem
.realPath(resolvedCommandPath)
.pipe(Effect.orElseSucceed(() => null));
if (!realCommandPath) {
return yield* resolver.resolve(null);
}
return yield* resolver.resolve({
binaryPath,
resolvedCommandPath,
realCommandPath,
env,
platform: yield* HostProcess.Platform,
});
}, Effect.flatMap(withConfiguredNpmVersionLookup));
export const makeCachedProviderMaintenanceResolution = Effect.fn(
"makeCachedProviderMaintenanceResolution",
)(function* (resolve: Effect.Effect<ProviderMaintenanceCapabilities>) {
const cache = yield* Cache.make({
capacity: 1,
timeToLive: MAINTENANCE_CAPABILITIES_CACHE_TTL,
lookup: () => resolve,
});
const cached = Cache.get(cache, undefined);
return (options?: { readonly fresh?: boolean }) =>
options?.fresh ? Cache.invalidate(cache, undefined).pipe(Effect.andThen(cached)) : cached;
});
function manualUpdateMessage(latestVersion: string, installPath: string | undefined): string {
return installPath
? `Version ${latestVersion} is out. T3 Code runs ${installPath}; update it with the app or tool that installed it.`
: `Version ${latestVersion} is out. Update it with the app or tool that installed it.`;
}
function deriveVersionAdvisory(input: {
readonly currentVersion: string | null;
readonly latestVersion: string | null;
readonly capabilities: ProviderMaintenanceCapabilities;
}): Pick<ServerProviderVersionAdvisory, "status" | "message"> {
if (!input.currentVersion) {
return { status: "unknown", message: null };
}
if (!input.latestVersion) {
return { status: "unknown", message: null };
}
if (
(input.capabilities.compareVersions ?? compareSemverVersions)(
input.currentVersion,
input.latestVersion,
) < 0
) {
return {
status: "behind_latest",
message:
input.capabilities.update === null
? manualUpdateMessage(input.latestVersion, input.capabilities.installPath)
: PROVIDER_UPDATE_ACTION_TOAST_MESSAGE,
};
}
return { status: "current", message: null };
}
export function createProviderVersionAdvisory(input: {
readonly driver: ProviderDriverKind;
readonly currentVersion: string | null;
readonly latestVersion?: string | null;
readonly checkedAt?: string | null;
readonly maintenanceCapabilities?: ProviderMaintenanceCapabilities;
}): ServerProviderVersionAdvisory {
const capabilities =
input.maintenanceCapabilities ?? makeManualProviderMaintenanceCapabilities(input.driver);
const latestVersion = input.latestVersion ?? null;
const advisory = deriveVersionAdvisory({
currentVersion: input.currentVersion,
latestVersion,
capabilities,
});
return {
status: advisory.status,
currentVersion: input.currentVersion,
latestVersion,
updateCommand:
resolveLatestProviderUpdateAction(capabilities, latestVersion)?.command ??
capabilities.manualCommand ??
null,
canUpdate: capabilities.update !== null,
canInstallVersion: makeTargetedProviderUpdateAction(capabilities, "0.0.0") !== null,
checkedAt: input.checkedAt ?? null,
message: advisory.message,
};
}
const fetchNpmLatestVersion = Effect.fn("fetchNpmLatestVersion")(function* (packageName: string) {
const client = yield* HttpClient.HttpClient;
const request = HttpClientRequest.get(
`https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`,
).pipe(HttpClientRequest.setHeader("accept", "application/json"));
// The deadline covers the body too: headers can arrive before the JSON stalls.
const payload = yield* client.execute(request).pipe(
Effect.flatMap(HttpClientResponse.filterStatusOk),
Effect.flatMap(HttpClientResponse.schemaBodyJson(NpmLatestVersionResponse)),
Effect.timeoutOption(LATEST_VERSION_TIMEOUT_MS),
Effect.orElseSucceed(() => Option.none()),
);
return Option.isSome(payload) ? nonEmptyString(payload.value.version) : null;
});
/**
* The installer's own answer is cached apart from the npm registry entry. A
* manual-only install has no command to key on, so its executable stands in.
*/
function installerLatestVersionKey(capabilities: ProviderMaintenanceCapabilities) {
if (!capabilities.lookupLatestVersion) return null;
if (capabilities.latestVersionCacheKey) return capabilities.latestVersionCacheKey;
const update = capabilities.update;
if (update) return [update.lockKey, update.executable, ...update.args].join("\0");
return capabilities.installPath
? ["manual", capabilities.installPath].join("\0")
: capabilities.packageName && `npm-registry\0${capabilities.packageName}`;
}
export function latestProviderVersionCacheKeys(
capabilities: ProviderMaintenanceCapabilities,
): ReadonlyArray<string> {
return [capabilities.packageName, installerLatestVersionKey(capabilities)].filter(
(key) => key !== null,
);
}
export const resolveLatestProviderVersion = Effect.fn("resolveLatestProviderVersion")(function* (
maintenanceCapabilities: ProviderMaintenanceCapabilities,
) {
const latestVersions = yield* ProviderLatestVersions.ProviderLatestVersions;
const installerKey = installerLatestVersionKey(maintenanceCapabilities);
if (installerKey && maintenanceCapabilities.lookupLatestVersion) {
const installable = yield* latestVersions.cached(
installerKey,
maintenanceCapabilities.lookupLatestVersion,
);
if (installable !== null) return installable;
}
if (maintenanceCapabilities.latestVersion !== undefined) {
return maintenanceCapabilities.latestVersion;
}
const packageName = maintenanceCapabilities.packageName;
if (!packageName) {
return null;
}
return yield* latestVersions.cached(packageName, fetchNpmLatestVersion(packageName));
});
export const invalidateLatestProviderVersion = Effect.fn("invalidateLatestProviderVersion")(
function* (maintenanceCapabilities: ProviderMaintenanceCapabilities) {
const latestVersions = yield* ProviderLatestVersions.ProviderLatestVersions;
yield* Effect.forEach(
latestProviderVersionCacheKeys(maintenanceCapabilities),
latestVersions.invalidate,
{ discard: true },
);
},
);
export const enrichProviderSnapshotWithVersionAdvisory = Effect.fn(
"enrichProviderSnapshotWithVersionAdvisory",
)(function* (
snapshot: ServerProvider,
maintenanceCapabilities?: ProviderMaintenanceCapabilities,
options?: {
readonly enableProviderUpdateChecks: boolean | undefined;
},
) {
const capabilities =
maintenanceCapabilities ?? makeManualProviderMaintenanceCapabilities(snapshot.driver);
const currentVersion =
snapshot.installedVersion !== undefined ? snapshot.installedVersion : snapshot.version;
const shouldResolveLatestVersion =
options?.enableProviderUpdateChecks !== false &&
snapshot.enabled &&
snapshot.installed &&
Boolean(currentVersion);
if (!shouldResolveLatestVersion) {
return {
...snapshot,
versionAdvisory: createProviderVersionAdvisory({
driver: snapshot.driver,
currentVersion,
checkedAt: snapshot.checkedAt,
maintenanceCapabilities: capabilities,
}),
};
}
const latestVersion = yield* resolveLatestProviderVersion(capabilities);
return {
...snapshot,
versionAdvisory: createProviderVersionAdvisory({
driver: snapshot.driver,
currentVersion,
latestVersion,
checkedAt: DateTime.formatIso(yield* DateTime.now),
maintenanceCapabilities: capabilities,
}),
};
});