mirror of
https://github.com/morluto/rea.git
synced 2026-11-16 11:43:20 +00:00
* refactor(kernel): migrate the remaining one-shot SHA-256 hex digests to sha256Hex * refactor(kernel): move isRecord into src/kernel and replace its inline copies (#11574) * fix(scripts): import isRecord from src/kernel in the managed manifest parser
1491 lines
47 KiB
TypeScript
1491 lines
47 KiB
TypeScript
import type { ArtifactResourceScope } from "../resources/index.js";
|
|
import { HOST_PLATFORM } from "../platform/HostPlatform.js";
|
|
import { readClientPolicyBlock } from "./GeminiClientSettings.js";
|
|
import {
|
|
readClientConfigurationFiles,
|
|
inlineRegistrationEnvironment,
|
|
inlineRegistrationOrigins,
|
|
inlineRegistrationOverride,
|
|
clientConfigurationForWrite,
|
|
clientWriteDialect,
|
|
effectiveClientConfiguration,
|
|
readConfigurationText,
|
|
type ClientConfigurationSource,
|
|
type ClientConfigurationFileError,
|
|
} from "./ClientConfigurationFiles.js";
|
|
import { err, ok, type Result } from "../domain/result.js";
|
|
import { ConfigurationError } from "../domain/configurationErrors.js";
|
|
import {
|
|
clientConfigurationValuesEqual,
|
|
effectiveClientServer,
|
|
clientServerListedDisabled,
|
|
clientServerPath,
|
|
legacyClientServerPath,
|
|
shadowedClientServers,
|
|
OMP_DISABLED_SERVERS_KEY,
|
|
parseClientConfiguration,
|
|
parseZcodeFallbackConfiguration,
|
|
serializeClientConfiguration,
|
|
withClientServers,
|
|
type ClientConfigurationDocument,
|
|
type ClientInlineConfiguration,
|
|
type ClientRegistrationDialect,
|
|
} from "./ClientConfigurationDocument.js";
|
|
import { DISCOVERED_REGISTRATION_SETTINGS } from "./SetupRegistrationEnvironment.js";
|
|
import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
|
|
import { dshDocument, DshCordisDocument } from "./DshCordisPatch.js";
|
|
import { mkdir } from "node:fs/promises";
|
|
import { dirname } from "node:path";
|
|
import {
|
|
PRIVATE_PROFILE_MODES,
|
|
privateProfileModesCurrent,
|
|
securePrivateDirectory,
|
|
} from "./ClientPrivateProfile.js";
|
|
import { RegularFileChangedError } from "../filesystem/RegularFile.js";
|
|
import { withClientConfigurationTransaction } from "./ClientConfigurationTransaction.js";
|
|
import { isClientConfigurationCleanupFailure } from "./ClientConfigurationCleanup.js";
|
|
import {
|
|
ClientConfigurationPublication,
|
|
ClientConfigurationWriteError,
|
|
} from "./ClientConfigurationPublication.js";
|
|
import {
|
|
clientRegistrationEnvironment,
|
|
clientRegistrationEnvironmentDetailsWithBudget,
|
|
type ProviderRequestBudgetResolver,
|
|
} from "./ClientRegistrationEnvironment.js";
|
|
|
|
import {
|
|
clientRegistrationOwnership,
|
|
clientRegistrationOwnershipRemediation,
|
|
refreshClientRegistration,
|
|
} from "./ClientRegistration.js";
|
|
|
|
import { PRODUCT_IDENTITY } from "../identity.js";
|
|
import { currentClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
|
|
import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
|
|
import { packageReadTargetChanged } from "./MsixPackageStorage.js";
|
|
import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js";
|
|
import {
|
|
readRegularFileText,
|
|
readRegularFileTextSnapshot,
|
|
InvalidUtf8FileError,
|
|
} from "../process/RegularFileRead.js";
|
|
import {
|
|
preserveCurrentRecoveryBackup,
|
|
selectCurrentRecoveryBackup,
|
|
} from "./SetupRecoveryBackup.js";
|
|
import { preservePrivateRecoveryBackup } from "./ClientRegistrationBackup.js";
|
|
import type {
|
|
ClientConfigurationInspection,
|
|
ClientConfigurationResult,
|
|
SetupProviderEnvironment,
|
|
} from "./SetupTypes.js";
|
|
import {
|
|
registrationWriteBlocker,
|
|
type SetupClient,
|
|
} from "./SupportedClients.js";
|
|
import { errorMessage } from "../kernel/errorMessage.js";
|
|
import { isRecord } from "../kernel/isRecord.js";
|
|
|
|
export class ClientConfigurationCleanupRollbackFailure extends RegularFileCleanupFailure<string> {
|
|
constructor(
|
|
failure: RegularFileCleanupFailure<string>,
|
|
readonly configurationFailure: Extract<
|
|
ClientConfigurationResult,
|
|
{ readonly status: "failed" }
|
|
>,
|
|
) {
|
|
super({
|
|
...failure,
|
|
cleanupCause: new AggregateError(
|
|
[failure.cleanupCause, configurationFailure],
|
|
`Configuration readback cleanup and rollback failed: ${failure.path}`,
|
|
),
|
|
});
|
|
}
|
|
}
|
|
|
|
/** Configure one supported client's native stdio MCP registration shape. */
|
|
export const configureClientConfiguration = async (
|
|
client: SetupClient,
|
|
environment: SetupProviderEnvironment = {},
|
|
command: readonly string[] = currentClientRegistrationCommand(),
|
|
resolveProviderRequestBudget?: ProviderRequestBudgetResolver,
|
|
// Setup writes the running host's client files unless its host selects one.
|
|
platform: NodeJS.Platform = HOST_PLATFORM.platform,
|
|
): Promise<ClientConfigurationResult> => {
|
|
if (command.length === 0)
|
|
return {
|
|
status: "failed",
|
|
reason: "registration_ownership",
|
|
detail:
|
|
"The running REA entrypoint could not be identified; run setup from an installed REA command.",
|
|
};
|
|
if (client.configPathError !== undefined)
|
|
return { status: "failed", reason: "path" };
|
|
const transactionPath = await resolveClientConfigTransactionPath(
|
|
client.configPath,
|
|
);
|
|
if (transactionPath === undefined)
|
|
return { status: "failed", reason: "path" };
|
|
try {
|
|
return await withClientConfigurationTransaction(transactionPath, () =>
|
|
configureClientDocument(
|
|
{ client, transactionPath, platform },
|
|
environment,
|
|
command,
|
|
resolveProviderRequestBudget,
|
|
),
|
|
);
|
|
} catch (cause: unknown) {
|
|
if (cause instanceof ConfigurationError && !cause.cleanupIncomplete)
|
|
return { status: "failed", reason: "readback" };
|
|
throw cause;
|
|
}
|
|
};
|
|
|
|
/** An error that still owns an unreleased resource must reach the caller. */
|
|
const cleanupIncomplete = (cause: unknown): boolean =>
|
|
cause instanceof ConfigurationError && cause.cleanupIncomplete;
|
|
|
|
const configureClientDocument = async (
|
|
{
|
|
client,
|
|
transactionPath,
|
|
platform,
|
|
}: {
|
|
readonly client: SetupClient;
|
|
readonly transactionPath: string;
|
|
readonly platform: NodeJS.Platform;
|
|
},
|
|
environment: SetupProviderEnvironment,
|
|
command: readonly string[],
|
|
resolveProviderRequestBudget?: ProviderRequestBudgetResolver,
|
|
): Promise<ClientConfigurationResult> => {
|
|
const format = client.format;
|
|
if (format === undefined || format === "unsupported")
|
|
return { status: "failed", reason: "readback" };
|
|
const files = await readClientConfigurationFiles(
|
|
client,
|
|
undefined,
|
|
platform,
|
|
environment,
|
|
);
|
|
if (!files.ok) {
|
|
throwCleanupFailure(files.error);
|
|
return { status: "failed", reason: "readback" };
|
|
}
|
|
const existing = files.value.find(
|
|
({ sourcePath }) => sourcePath === client.configPath,
|
|
);
|
|
const editabilityError =
|
|
existing?.dialect === "dsh"
|
|
? dshDocument(existing.document).editabilityError
|
|
: undefined;
|
|
if (editabilityError !== undefined)
|
|
return { status: "failed", reason: "readback" };
|
|
// Policy admission belongs to the transaction snapshot below, not the
|
|
// earlier layered discovery document.
|
|
let snapshot:
|
|
| Awaited<ReturnType<typeof readRegularFileTextSnapshot>>
|
|
| undefined;
|
|
try {
|
|
snapshot = await readRegularFileTextSnapshot(transactionPath, {
|
|
symlinks: "reject",
|
|
});
|
|
} catch (cause: unknown) {
|
|
if (cause instanceof RegularFileCleanupFailure) throw cause;
|
|
if (!isMissing(cause)) return { status: "failed", reason: "readback" };
|
|
}
|
|
const original = snapshot?.text;
|
|
let parsed: ClientConfigurationDocument;
|
|
try {
|
|
parsed = parseClientConfiguration(
|
|
original ??
|
|
(format === "toml" || format === "grok" || format === "dsh"
|
|
? ""
|
|
: "{}"),
|
|
format,
|
|
);
|
|
parsed = clientConfigurationForWrite(parsed, files.value);
|
|
const ownershipBlocker = registrationOwnershipBlocker(
|
|
client,
|
|
parsed,
|
|
original ?? "",
|
|
files.value,
|
|
platform,
|
|
);
|
|
if (ownershipBlocker !== undefined)
|
|
return {
|
|
status: "failed",
|
|
reason: "registration_ownership",
|
|
detail: ownershipBlocker,
|
|
};
|
|
const policy = await readClientPolicyBlock(
|
|
client,
|
|
parsed,
|
|
await clientConfigurationDesired(
|
|
client,
|
|
environment,
|
|
command,
|
|
parsed,
|
|
files.value,
|
|
platform,
|
|
resolveProviderRequestBudget,
|
|
),
|
|
);
|
|
if (!policy.ok) {
|
|
throwCleanupFailure(policy.error);
|
|
return { status: "failed", reason: "readback" };
|
|
}
|
|
if (policy.value !== undefined)
|
|
return { status: "failed", reason: "readback" };
|
|
} catch (cause: unknown) {
|
|
if (cause instanceof RegularFileCleanupFailure) throw cause;
|
|
// Malformed existing configuration fails the readback gate.
|
|
void cause;
|
|
return { status: "failed", reason: "readback" };
|
|
}
|
|
const fallback = await readZcodeFallbackServers(client, platform, parsed);
|
|
if (!fallback.ok) {
|
|
if (fallback.error.kind !== "registration_ownership")
|
|
throwCleanupFailure(fallback.error);
|
|
return fallback.error.kind === "registration_ownership"
|
|
? {
|
|
status: "failed",
|
|
reason: "registration_ownership",
|
|
detail: fallback.error.detail,
|
|
}
|
|
: { status: "failed", reason: "readback" };
|
|
}
|
|
const desired = await clientConfigurationDesired(
|
|
client,
|
|
environment,
|
|
command,
|
|
{
|
|
...parsed,
|
|
servers: { ...fallback.value, ...parsed.servers },
|
|
},
|
|
files.value,
|
|
platform,
|
|
resolveProviderRequestBudget,
|
|
);
|
|
// The settings written now can differ from the ones inspection admitted,
|
|
// for example a Hopper path set by an installation earlier in this setup.
|
|
const override = inlineOverrideBlocker(
|
|
client,
|
|
files.value,
|
|
desired,
|
|
platform,
|
|
);
|
|
if (override !== undefined)
|
|
return { status: "failed", reason: "read_only_override", detail: override };
|
|
if (
|
|
registrationCurrent(parsed, desired) &&
|
|
(await privateProfileCurrent(client, original))
|
|
)
|
|
return { status: "unchanged" };
|
|
return persistClientConfiguration({
|
|
client,
|
|
transactionPath,
|
|
snapshot,
|
|
format,
|
|
original,
|
|
parsed,
|
|
desired,
|
|
fallbackServers: fallback.value,
|
|
platform,
|
|
});
|
|
};
|
|
|
|
interface ClientConfigurationUpdate {
|
|
readonly client: SetupClient;
|
|
readonly transactionPath: string;
|
|
readonly snapshot:
|
|
| Awaited<ReturnType<typeof readRegularFileTextSnapshot>>
|
|
| undefined;
|
|
readonly format: NonNullable<SetupClient["format"]>;
|
|
readonly original: string | undefined;
|
|
readonly parsed: ClientConfigurationDocument;
|
|
readonly desired: unknown;
|
|
readonly fallbackServers: Readonly<Record<string, unknown>>;
|
|
readonly platform: NodeJS.Platform;
|
|
}
|
|
|
|
const persistClientConfiguration = async ({
|
|
client,
|
|
transactionPath,
|
|
snapshot,
|
|
format,
|
|
original,
|
|
parsed,
|
|
desired,
|
|
fallbackServers,
|
|
platform,
|
|
}: ClientConfigurationUpdate): Promise<ClientConfigurationResult> => {
|
|
// The plan chose this file; an MSIX package may have switched to its
|
|
// private copy since, for example when it quit.
|
|
if (client.msixPackage !== undefined) {
|
|
const target = await packageReadTargetChanged(
|
|
client.msixPackage,
|
|
client.configPath,
|
|
);
|
|
if (!target.ok)
|
|
return {
|
|
status: "failed",
|
|
reason: "target_unavailable",
|
|
failure: {
|
|
kind: "inspect",
|
|
path: target.error.path,
|
|
detail: target.error.detail,
|
|
},
|
|
};
|
|
if (target.value) return { status: "failed", reason: "target_changed" };
|
|
}
|
|
// A native OpenCode V2 entry replaces REA's legacy V1 entry, which would
|
|
// otherwise conflict with it.
|
|
const legacyPath = legacyClientServerPath(
|
|
parsed,
|
|
PRODUCT_IDENTITY.mcpServerKey,
|
|
);
|
|
const registered = withClientServers(
|
|
parsed,
|
|
{
|
|
...fallbackServers,
|
|
...parsed.servers,
|
|
[PRODUCT_IDENTITY.mcpServerKey]: desired,
|
|
},
|
|
platform,
|
|
PRODUCT_IDENTITY.mcpServerKey,
|
|
);
|
|
// OMP's denylist would hide the registration; keep every other listed name.
|
|
const ompDisabled =
|
|
parsed.dialect === "omp"
|
|
? parsed.document[OMP_DISABLED_SERVERS_KEY]
|
|
: undefined;
|
|
const enableOmp =
|
|
Array.isArray(ompDisabled) &&
|
|
ompDisabled.includes(PRODUCT_IDENTITY.mcpServerKey);
|
|
const document =
|
|
enableOmp && Array.isArray(ompDisabled)
|
|
? {
|
|
...registered,
|
|
[OMP_DISABLED_SERVERS_KEY]: ompDisabled.filter(
|
|
(name: unknown) => name !== PRODUCT_IDENTITY.mcpServerKey,
|
|
),
|
|
}
|
|
: registered;
|
|
let serialized: ReturnType<typeof serializeClientConfiguration>;
|
|
try {
|
|
serialized = serializeClientConfiguration(
|
|
document,
|
|
format,
|
|
original,
|
|
[
|
|
...Object.keys(fallbackServers)
|
|
.filter((name) => name !== PRODUCT_IDENTITY.mcpServerKey)
|
|
.map((name) => clientServerPath(parsed, name)),
|
|
clientServerPath(parsed, PRODUCT_IDENTITY.mcpServerKey),
|
|
...(legacyPath === undefined ? [] : [legacyPath]),
|
|
...(enableOmp ? [[OMP_DISABLED_SERVERS_KEY]] : []),
|
|
],
|
|
// Ownership admission above covers every legacy member removed here.
|
|
{ removeShadowedMembersAt: legacyPath === undefined ? [] : [legacyPath] },
|
|
);
|
|
} catch (cause: unknown) {
|
|
// An unserializable edit is reported before any file is written.
|
|
return {
|
|
status: "failed",
|
|
reason: "write",
|
|
failure: new ClientConfigurationWriteError(
|
|
client.configPath,
|
|
"serialize",
|
|
cause,
|
|
).problem,
|
|
};
|
|
}
|
|
if (!serialized.ok)
|
|
return {
|
|
status: "failed",
|
|
reason: "shadowed_member",
|
|
path: serialized.error.path,
|
|
};
|
|
let recoveryBackupPath: string | undefined;
|
|
if (original !== undefined) {
|
|
// A private profile's backup stays owner-only even when it sits beside
|
|
// a requested link outside the secured target directory.
|
|
const preserved = await (
|
|
client.privateProfile === undefined
|
|
? preserveCurrentRecoveryBackup
|
|
: preservePrivateRecoveryBackup
|
|
)(`${client.configPath}.rea.backup`, transactionPath, original);
|
|
if (!preserved.ok) return { status: "failed", reason: "backup" };
|
|
recoveryBackupPath = preserved.value;
|
|
}
|
|
let publication: ClientConfigurationPublication;
|
|
try {
|
|
await mkdir(dirname(client.configPath), {
|
|
recursive: true,
|
|
...(client.privateProfile !== undefined
|
|
? { mode: PRIVATE_PROFILE_MODES.directory }
|
|
: {}),
|
|
});
|
|
// File modes are this host's, whatever platform the registration targets.
|
|
if (
|
|
client.privateProfile !== undefined &&
|
|
HOST_PLATFORM.platform !== "win32"
|
|
)
|
|
await securePrivateDirectory(
|
|
dirname(transactionPath),
|
|
client.privateProfile.home,
|
|
() => {},
|
|
undefined,
|
|
);
|
|
publication = await ClientConfigurationPublication.write(
|
|
transactionPath,
|
|
serialized.value,
|
|
original,
|
|
{
|
|
requestedPath: client.configPath,
|
|
state: snapshot?.state,
|
|
...(client.privateProfile !== undefined
|
|
? { requiredMode: PRIVATE_PROFILE_MODES.file }
|
|
: {}),
|
|
},
|
|
);
|
|
} catch (cause: unknown) {
|
|
if (isClientConfigurationCleanupFailure(cause) || cleanupIncomplete(cause))
|
|
throw cause;
|
|
if (isConfigurationConflict(cause))
|
|
return conflictFailure(recoveryBackupPath);
|
|
return {
|
|
status: "failed",
|
|
reason: "write",
|
|
failure: (cause instanceof ClientConfigurationWriteError
|
|
? cause
|
|
: new ClientConfigurationWriteError(client.configPath, "publish", cause)
|
|
).problem,
|
|
...(recoveryBackupPath === undefined
|
|
? {}
|
|
: { backupPath: recoveryBackupPath }),
|
|
};
|
|
}
|
|
return publication.verify(async () => {
|
|
try {
|
|
const text = await readRegularFileText(publication.path);
|
|
await publication.assertCurrent(text);
|
|
const readback = parseClientConfiguration(text, format);
|
|
if (
|
|
!registrationCurrent(readback, desired) ||
|
|
Object.entries(fallbackServers).some(
|
|
([name, entry]) =>
|
|
name !== PRODUCT_IDENTITY.mcpServerKey &&
|
|
!clientConfigurationValuesEqual(readback.servers[name], entry),
|
|
)
|
|
) {
|
|
return await rollbackOrReadbackFailure(
|
|
publication,
|
|
original,
|
|
recoveryBackupPath,
|
|
);
|
|
}
|
|
} catch (cause: unknown) {
|
|
if (isConfigurationConflict(cause) || isMissing(cause))
|
|
return conflictFailure(recoveryBackupPath);
|
|
if (cause instanceof RegularFileCleanupFailure) {
|
|
const rollback = await restoreConfig(publication, original);
|
|
if (!rollback.ok)
|
|
throw new ClientConfigurationCleanupRollbackFailure(
|
|
cause,
|
|
rollbackFailure(rollback.error, recoveryBackupPath),
|
|
);
|
|
throw cause;
|
|
}
|
|
// Readback failure restores the transaction before reporting.
|
|
void cause;
|
|
return rollbackOrReadbackFailure(
|
|
publication,
|
|
original,
|
|
recoveryBackupPath,
|
|
);
|
|
}
|
|
return {
|
|
status: "configured",
|
|
...(recoveryBackupPath === undefined
|
|
? {}
|
|
: { backupPath: recoveryBackupPath }),
|
|
};
|
|
});
|
|
};
|
|
|
|
/** What setup would write into a client's target file, from one read. */
|
|
interface ClientRefresh {
|
|
readonly original: string | undefined;
|
|
readonly parsed: ClientConfigurationDocument | undefined;
|
|
readonly desired: unknown;
|
|
/** The layers the registration was read from. */
|
|
readonly sources: readonly ClientConfigurationSource[];
|
|
/** The inline layer whose override is the refusal, when it is. */
|
|
readonly overrideOrigin?: ClientInlineConfiguration["origin"];
|
|
/** Why setup refuses this write: write-target ownership, a client policy or an overriding inline layer. */
|
|
readonly refusal: string | undefined;
|
|
}
|
|
|
|
/**
|
|
* Read a client's layers and compute the registration setup would write,
|
|
* with setup's own refusal checks. An unreadable or malformed layer is a typed
|
|
* failure that keeps its path and recovery.
|
|
*/
|
|
const readClientRefresh = async (
|
|
client: SetupClient,
|
|
providerEnvironment: SetupProviderEnvironment,
|
|
command: readonly string[],
|
|
{
|
|
platform,
|
|
resolveProviderRequestBudget,
|
|
resources,
|
|
currentCommandPath,
|
|
}: {
|
|
readonly platform: NodeJS.Platform;
|
|
readonly resolveProviderRequestBudget?: ProviderRequestBudgetResolver;
|
|
readonly resources?: ArtifactResourceScope;
|
|
/** The entry point whose registrations setup owns; update names the new one. */
|
|
readonly currentCommandPath?: string;
|
|
},
|
|
): Promise<Result<ClientRefresh, ClientConfigurationFileError>> => {
|
|
const files = await readClientConfigurationFiles(
|
|
client,
|
|
resources,
|
|
platform,
|
|
providerEnvironment,
|
|
);
|
|
if (!files.ok) {
|
|
throwCleanupFailure(files.error);
|
|
return files;
|
|
}
|
|
let original: string | undefined;
|
|
try {
|
|
original = await readRegularFileText(
|
|
client.configPath,
|
|
resources === undefined ? {} : { resources },
|
|
);
|
|
} catch (cause: unknown) {
|
|
if (!isMissing(cause)) throw cause;
|
|
}
|
|
const parsed =
|
|
original === undefined
|
|
? undefined
|
|
: clientConfigurationForWrite(
|
|
parseClientConfiguration(original, client.format),
|
|
files.value,
|
|
);
|
|
const desired = await clientConfigurationDesired(
|
|
client,
|
|
providerEnvironment,
|
|
command,
|
|
parsed,
|
|
files.value,
|
|
platform,
|
|
resolveProviderRequestBudget,
|
|
);
|
|
const target =
|
|
dshEditabilityBlocker(client, files.value) ??
|
|
writeTargetOwnershipBlocker(
|
|
client,
|
|
files.value,
|
|
parsed,
|
|
original,
|
|
platform,
|
|
currentCommandPath,
|
|
);
|
|
if (target !== undefined)
|
|
return ok({
|
|
original,
|
|
parsed,
|
|
desired,
|
|
sources: files.value,
|
|
refusal: target,
|
|
});
|
|
const overrideOrigin = inlineRegistrationOverride(
|
|
client,
|
|
files.value,
|
|
desired,
|
|
platform,
|
|
);
|
|
if (overrideOrigin !== undefined)
|
|
return ok({
|
|
original,
|
|
parsed,
|
|
desired,
|
|
sources: files.value,
|
|
overrideOrigin,
|
|
refusal: inlineOverrideRemediation(client, overrideOrigin),
|
|
});
|
|
const policy = await readClientPolicyBlock(
|
|
client,
|
|
parsed,
|
|
desired,
|
|
resources,
|
|
);
|
|
if (!policy.ok) {
|
|
throwCleanupFailure(policy.error);
|
|
return ok({
|
|
original,
|
|
parsed,
|
|
desired,
|
|
sources: files.value,
|
|
refusal: policy.error.detail,
|
|
});
|
|
}
|
|
return ok({
|
|
original,
|
|
parsed,
|
|
desired,
|
|
sources: files.value,
|
|
refusal: policy.value,
|
|
});
|
|
};
|
|
|
|
/** Determine whether an existing client configuration matches the desired registration. */
|
|
export const clientConfigurationAligned = async (
|
|
client: SetupClient,
|
|
providerEnvironment: SetupProviderEnvironment,
|
|
command: readonly string[],
|
|
resolveProviderRequestBudget?: ProviderRequestBudgetResolver,
|
|
// Setup reads the running host's client files unless its host selects one.
|
|
platform: NodeJS.Platform = HOST_PLATFORM.platform,
|
|
): Promise<boolean> => {
|
|
if (client.configPathError !== undefined) return false;
|
|
try {
|
|
const refresh = await readClientRefresh(
|
|
client,
|
|
providerEnvironment,
|
|
command,
|
|
resolveProviderRequestBudget === undefined
|
|
? { platform }
|
|
: { platform, resolveProviderRequestBudget },
|
|
);
|
|
return (
|
|
refresh.ok &&
|
|
refresh.value.original !== undefined &&
|
|
refresh.value.parsed !== undefined &&
|
|
refresh.value.refusal === undefined &&
|
|
registrationCurrent(refresh.value.parsed, refresh.value.desired) &&
|
|
(await privateProfileCurrent(client, refresh.value.original))
|
|
);
|
|
} catch (cause: unknown) {
|
|
if (cause instanceof RegularFileCleanupFailure) throw cause;
|
|
// Unreadable configuration is treated as not aligned so setup repairs it.
|
|
void cause;
|
|
return false;
|
|
}
|
|
};
|
|
|
|
/** Why maintenance leaves a client to setup, with whether alignment is known. */
|
|
export interface ClientRefreshRefusal {
|
|
readonly alignment: "refused" | "unknown";
|
|
readonly remediation: string;
|
|
}
|
|
|
|
/**
|
|
* Why update maintenance cannot refresh a client with `command`: setup's
|
|
* refusal (a client policy, an unreadable layer, or a read-only inline layer
|
|
* that would override the refreshed entry), or `unknown` alignment when the
|
|
* inline layer differs only in settings setup discovers from the installed
|
|
* providers. Maintenance has only the explicitly selected settings and does
|
|
* not run that discovery, so such a client needs `rea setup`. One refused
|
|
* client blocks the whole setup plan, so maintenance asks before selecting a
|
|
* client. Registration ownership is not checked here; the caller has already
|
|
* established it. A supplied scope retains the owner of a file whose cleanup
|
|
* failed.
|
|
*/
|
|
export const clientRefreshRefusal = async (
|
|
client: SetupClient,
|
|
providerEnvironment: SetupProviderEnvironment,
|
|
command: readonly string[],
|
|
{
|
|
platform,
|
|
currentCommandPath,
|
|
resources,
|
|
}: {
|
|
readonly platform: NodeJS.Platform;
|
|
/** The entry point the refreshing setup runs from. */
|
|
readonly currentCommandPath: string;
|
|
readonly resources?: ArtifactResourceScope;
|
|
},
|
|
): Promise<ClientRefreshRefusal | undefined> => {
|
|
const refused = (remediation: string): ClientRefreshRefusal => ({
|
|
alignment: "refused",
|
|
remediation,
|
|
});
|
|
if (client.configPathError !== undefined)
|
|
return refused(client.configPathError);
|
|
try {
|
|
const refresh = await readClientRefresh(
|
|
client,
|
|
providerEnvironment,
|
|
command,
|
|
{
|
|
platform,
|
|
currentCommandPath,
|
|
...(resources === undefined ? {} : { resources }),
|
|
},
|
|
);
|
|
// An unreadable or malformed layer is a refusal too: setup's preflight
|
|
// reports it the same way.
|
|
if (!refresh.ok) return refused(refresh.error.detail);
|
|
const discovered = await discoveredInlineSettings(
|
|
client,
|
|
providerEnvironment,
|
|
command,
|
|
refresh.value,
|
|
platform,
|
|
);
|
|
if (discovered !== undefined)
|
|
return {
|
|
alignment: "unknown",
|
|
remediation: `${discovered.origin} sets ${discovered.settings.join(", ")} in REA's ${PRODUCT_IDENTITY.mcpServerKey} registration for ${client.configPath}; setup discovers ${discovered.settings.length === 1 ? "that setting" : "those settings"} from the installed providers and update does not, so REA cannot tell whether this registration is current. Run ${PRODUCT_IDENTITY.cliBinary} setup to check and refresh it.`,
|
|
};
|
|
return refresh.value.refusal === undefined
|
|
? undefined
|
|
: refused(refresh.value.refusal);
|
|
} catch (cause: unknown) {
|
|
if (cause instanceof RegularFileCleanupFailure) throw cause;
|
|
if (cause instanceof ConfigurationError)
|
|
return refused(
|
|
`${cause.message}: ${cause.settings.map(({ setting, constraint }) => `${setting}: ${constraint}`).join("; ")}`,
|
|
);
|
|
return refused(
|
|
`The configuration could not be read. Check its permissions before rerunning setup. ${errorMessage(cause)}`,
|
|
);
|
|
}
|
|
};
|
|
|
|
/**
|
|
* The read-only inline layer's settings that setup discovers and the caller
|
|
* did not select, when they decide this client's refresh: setup may write a
|
|
* different discovered value than the layer holds (the layer would then
|
|
* override it), so an entry that matches now is not known to stay current, and
|
|
* an override those values alone explain is not known to remain. Another
|
|
* refusal (ownership, policy, or an override other settings cause) does not
|
|
* depend on discovery.
|
|
*/
|
|
const discoveredInlineSettings = async (
|
|
client: SetupClient,
|
|
providerEnvironment: SetupProviderEnvironment,
|
|
command: readonly string[],
|
|
refresh: ClientRefresh,
|
|
platform: NodeJS.Platform,
|
|
): Promise<
|
|
| {
|
|
readonly origin: ClientInlineConfiguration["origin"];
|
|
readonly settings: readonly string[];
|
|
}
|
|
| undefined
|
|
> => {
|
|
const [origin] = inlineRegistrationOrigins(client);
|
|
if (origin === undefined) return undefined;
|
|
if (refresh.refusal !== undefined && refresh.overrideOrigin === undefined)
|
|
return undefined;
|
|
// Setting names are matched by the platform's environment identity, so a
|
|
// Windows layer's `Java_Home` is the discovered `JAVA_HOME`.
|
|
const declared = snapshotEnvironment(
|
|
inlineRegistrationEnvironment(refresh.sources),
|
|
platform,
|
|
);
|
|
const selected = snapshotEnvironment(providerEnvironment, platform);
|
|
const adopted = Object.fromEntries(
|
|
DISCOVERED_REGISTRATION_SETTINGS.flatMap((setting) => {
|
|
const value = declared[setting];
|
|
return Object.hasOwn(selected, setting) || value === undefined
|
|
? []
|
|
: [[setting, value]];
|
|
}),
|
|
);
|
|
const settings = Object.keys(adopted);
|
|
if (settings.length === 0) return undefined;
|
|
if (refresh.overrideOrigin === undefined) return { origin, settings };
|
|
const desired = await clientConfigurationDesired(
|
|
client,
|
|
{ ...providerEnvironment, ...adopted },
|
|
command,
|
|
refresh.parsed,
|
|
refresh.sources,
|
|
platform,
|
|
);
|
|
return inlineRegistrationOverride(
|
|
client,
|
|
refresh.sources,
|
|
desired,
|
|
platform,
|
|
) === undefined
|
|
? { origin, settings }
|
|
: undefined;
|
|
};
|
|
|
|
/** Preflight one client configuration before setup presents any mutations. */
|
|
export const inspectClientConfiguration = async (
|
|
client: SetupClient,
|
|
providerEnvironment: SetupProviderEnvironment,
|
|
command: readonly string[],
|
|
resolveProviderRequestBudget?: ProviderRequestBudgetResolver,
|
|
// Setup reads the running host's client files unless its host selects one.
|
|
platform: NodeJS.Platform = HOST_PLATFORM.platform,
|
|
): Promise<ClientConfigurationInspection> => {
|
|
let inspection: ClientConfigurationInspection;
|
|
try {
|
|
inspection = await inspectClientDocument(
|
|
client,
|
|
providerEnvironment,
|
|
command,
|
|
platform,
|
|
resolveProviderRequestBudget,
|
|
);
|
|
} catch (cause: unknown) {
|
|
if (!(cause instanceof ConfigurationError)) throw cause;
|
|
return {
|
|
status: "invalid",
|
|
remediation: `${cause.message}: ${cause.settings.map(({ setting, constraint }) => `${setting}: ${constraint}`).join("; ")}`,
|
|
};
|
|
}
|
|
if (inspection.status !== "create" && inspection.status !== "update")
|
|
return inspection;
|
|
// A change the running client would overwrite is not a persisted registration.
|
|
const blocker = registrationWriteBlocker(client, "setup");
|
|
return blocker === undefined
|
|
? inspection
|
|
: { status: "invalid", remediation: blocker };
|
|
};
|
|
|
|
const inspectClientDocument = async (
|
|
client: SetupClient,
|
|
providerEnvironment: SetupProviderEnvironment,
|
|
command: readonly string[],
|
|
platform: NodeJS.Platform,
|
|
resolveProviderRequestBudget?: ProviderRequestBudgetResolver,
|
|
): Promise<ClientConfigurationInspection> => {
|
|
if (client.configPathError !== undefined)
|
|
return { status: "invalid", remediation: client.configPathError };
|
|
if (client.format === "unsupported") return { status: "already_current" };
|
|
const files = await readClientConfigurationFiles(
|
|
client,
|
|
undefined,
|
|
platform,
|
|
providerEnvironment,
|
|
);
|
|
if (!files.ok) {
|
|
throwCleanupFailure(files.error);
|
|
return {
|
|
status: "invalid",
|
|
remediation: files.error.detail,
|
|
};
|
|
}
|
|
const editabilityError = dshEditabilityBlocker(client, files.value);
|
|
if (editabilityError !== undefined)
|
|
return { status: "invalid", remediation: editabilityError };
|
|
const transactionPath = await resolveClientConfigTransactionPath(
|
|
client.configPath,
|
|
);
|
|
if (transactionPath === undefined)
|
|
return {
|
|
status: "invalid",
|
|
remediation:
|
|
"The configuration path is unsafe or unresolved. Check ownership and symbolic links before rerunning setup.",
|
|
};
|
|
let original: string;
|
|
try {
|
|
original = await readRegularFileText(transactionPath);
|
|
} catch (cause: unknown) {
|
|
if (cause instanceof RegularFileCleanupFailure) throw cause;
|
|
if (isMissing(cause)) {
|
|
const ownershipBlocker = writeTargetOwnershipBlocker(
|
|
client,
|
|
files.value,
|
|
undefined,
|
|
undefined,
|
|
platform,
|
|
);
|
|
if (ownershipBlocker !== undefined)
|
|
return { status: "invalid", remediation: ownershipBlocker };
|
|
const desired = await clientConfigurationDesired(
|
|
client,
|
|
providerEnvironment,
|
|
command,
|
|
undefined,
|
|
files.value,
|
|
platform,
|
|
resolveProviderRequestBudget,
|
|
);
|
|
const override = inlineOverrideBlocker(
|
|
client,
|
|
files.value,
|
|
desired,
|
|
platform,
|
|
);
|
|
if (override !== undefined)
|
|
return { status: "invalid", remediation: override };
|
|
// This read establishes absence; do not reuse an earlier user-file policy.
|
|
const policy = await readClientPolicyBlock(client, undefined, desired);
|
|
if (!policy.ok) {
|
|
throwCleanupFailure(policy.error);
|
|
return {
|
|
status: "invalid",
|
|
remediation: policy.error.detail,
|
|
};
|
|
}
|
|
if (policy.value !== undefined)
|
|
return { status: "invalid", remediation: policy.value };
|
|
const fallback = await readZcodeFallbackServers(client, platform);
|
|
if (!fallback.ok) {
|
|
if (fallback.error.kind !== "registration_ownership")
|
|
throwCleanupFailure(fallback.error);
|
|
return { status: "invalid", remediation: fallback.error.detail };
|
|
}
|
|
return { status: "create" };
|
|
}
|
|
return {
|
|
status: "invalid",
|
|
remediation: `The configuration file could not be read. Check its permissions before rerunning setup. ${errorMessage(cause)}`,
|
|
};
|
|
}
|
|
try {
|
|
const parsed = clientConfigurationForWrite(
|
|
parseClientConfiguration(original, client.format),
|
|
files.value,
|
|
);
|
|
const ownershipBlocker = writeTargetOwnershipBlocker(
|
|
client,
|
|
files.value,
|
|
parsed,
|
|
original,
|
|
platform,
|
|
);
|
|
if (ownershipBlocker !== undefined)
|
|
return { status: "invalid", remediation: ownershipBlocker };
|
|
const desired = await clientConfigurationDesired(
|
|
client,
|
|
providerEnvironment,
|
|
command,
|
|
parsed,
|
|
files.value,
|
|
platform,
|
|
resolveProviderRequestBudget,
|
|
);
|
|
const override = inlineOverrideBlocker(
|
|
client,
|
|
files.value,
|
|
desired,
|
|
platform,
|
|
);
|
|
if (override !== undefined)
|
|
return { status: "invalid", remediation: override };
|
|
const policy = await readClientPolicyBlock(client, parsed, desired);
|
|
if (!policy.ok) {
|
|
throwCleanupFailure(policy.error);
|
|
return {
|
|
status: "invalid",
|
|
remediation: policy.error.detail,
|
|
};
|
|
}
|
|
if (policy.value !== undefined)
|
|
return { status: "invalid", remediation: policy.value };
|
|
if (
|
|
registrationCurrent(parsed, desired) &&
|
|
(await privateProfileCurrent(client, original))
|
|
)
|
|
return { status: "already_current" };
|
|
const fallback = await readZcodeFallbackServers(client, platform, parsed);
|
|
if (!fallback.ok) {
|
|
if (fallback.error.kind !== "registration_ownership")
|
|
throwCleanupFailure(fallback.error);
|
|
return { status: "invalid", remediation: fallback.error.detail };
|
|
}
|
|
} catch (cause: unknown) {
|
|
if (
|
|
cause instanceof RegularFileCleanupFailure ||
|
|
cause instanceof ConfigurationError
|
|
)
|
|
throw cause;
|
|
// Malformed configuration is reported with the invalid remediation.
|
|
void cause;
|
|
return {
|
|
status: "invalid",
|
|
remediation:
|
|
"The existing configuration is malformed. Repair it before setup applies any other changes.",
|
|
};
|
|
}
|
|
const backupSelection = await selectCurrentRecoveryBackup(
|
|
`${client.configPath}.rea.backup`,
|
|
original,
|
|
);
|
|
if (!backupSelection.ok)
|
|
return {
|
|
status: "invalid",
|
|
remediation: backupSelection.error.detail,
|
|
};
|
|
return {
|
|
status: "update",
|
|
backupPath: backupSelection.value.backupPath,
|
|
};
|
|
};
|
|
|
|
const isMissing = (cause: unknown): boolean =>
|
|
cause instanceof Error && "code" in cause && cause.code === "ENOENT";
|
|
|
|
const throwCleanupFailure = (error: ClientConfigurationFileError): void => {
|
|
if (error.cleanupFailure !== undefined) throw error.cleanupFailure;
|
|
};
|
|
|
|
/** Setup cannot write around a read-only inline layer that overrides REA. */
|
|
const inlineOverrideBlocker = (
|
|
client: SetupClient,
|
|
sources: readonly ClientConfigurationSource[],
|
|
desired: unknown,
|
|
platform: NodeJS.Platform,
|
|
): string | undefined => {
|
|
const origin = inlineRegistrationOverride(client, sources, desired, platform);
|
|
return origin === undefined
|
|
? undefined
|
|
: inlineOverrideRemediation(client, origin);
|
|
};
|
|
|
|
const inlineOverrideRemediation = (
|
|
client: SetupClient,
|
|
origin: ClientInlineConfiguration["origin"],
|
|
): string =>
|
|
`${origin} overrides REA's ${PRODUCT_IDENTITY.mcpServerKey} registration in ${client.configPath}, and REA does not edit it. Remove the ${PRODUCT_IDENTITY.mcpServerKey} server from ${origin} or make it match, then rerun setup.`;
|
|
|
|
/** A Cordis document setup cannot edit. */
|
|
const dshEditabilityBlocker = (
|
|
client: SetupClient,
|
|
sources: readonly ClientConfigurationSource[],
|
|
): string | undefined => {
|
|
const existing = sources.find(
|
|
({ sourcePath }) => sourcePath === client.configPath,
|
|
);
|
|
return existing?.dialect === "dsh"
|
|
? dshDocument(existing.document).editabilityError?.message
|
|
: undefined;
|
|
};
|
|
|
|
/**
|
|
* Setup's ownership check of the row it would replace: the target file's own
|
|
* row, or, when the file is absent, the row the lower layers supply.
|
|
*/
|
|
const writeTargetOwnershipBlocker = (
|
|
client: SetupClient,
|
|
sources: readonly ClientConfigurationSource[],
|
|
parsed: ClientConfigurationDocument | undefined,
|
|
original: string | undefined,
|
|
platform: NodeJS.Platform,
|
|
currentCommandPath?: string,
|
|
): string | undefined => {
|
|
if (parsed !== undefined)
|
|
return registrationOwnershipBlocker(
|
|
client,
|
|
parsed,
|
|
original ?? "",
|
|
sources,
|
|
platform,
|
|
currentCommandPath,
|
|
);
|
|
const inherited = effectiveClientConfiguration(
|
|
sources,
|
|
{ client, document: undefined },
|
|
platform,
|
|
);
|
|
return inherited === undefined
|
|
? undefined
|
|
: registrationOwnershipBlocker(
|
|
client,
|
|
inherited,
|
|
"",
|
|
sources,
|
|
platform,
|
|
currentCommandPath,
|
|
);
|
|
};
|
|
|
|
/** Admit only absent or proven-owned rows that this setup would replace. */
|
|
const registrationOwnershipBlocker = (
|
|
client: SetupClient,
|
|
parsed: ClientConfigurationDocument,
|
|
original: string,
|
|
sources: readonly ClientConfigurationSource[],
|
|
platform: NodeJS.Platform,
|
|
currentCommandPath?: string,
|
|
): string | undefined => {
|
|
// Cordis owns registrations by stable entry ID, including malformed launchers.
|
|
if (parsed.dialect === "dsh") return undefined;
|
|
const name = PRODUCT_IDENTITY.mcpServerKey;
|
|
const entries: { value: unknown; paths: readonly string[] }[] = [];
|
|
const effective = effectiveClientConfiguration(
|
|
sources,
|
|
{ client, document: parsed },
|
|
platform,
|
|
);
|
|
if (effective !== undefined && Object.hasOwn(effective.servers, name))
|
|
entries.push({
|
|
value: effective.servers[name],
|
|
// An inline layer is named by its origin; it has no path.
|
|
paths: [
|
|
...(client.configPaths ?? [client.configPath]),
|
|
...inlineRegistrationOrigins(client),
|
|
],
|
|
});
|
|
const fragment = parsed.servers[name];
|
|
// A layered policy fragment inherits its launcher. Classify the effective
|
|
// launcher above, but also admit any explicit command this write replaces.
|
|
const inheritsLauncher =
|
|
effective !== undefined &&
|
|
effective !== parsed &&
|
|
isRecord(fragment) &&
|
|
!Object.hasOwn(fragment, "command");
|
|
if (Object.hasOwn(parsed.servers, name) && !inheritsLauncher)
|
|
entries.push({ value: parsed.servers[name], paths: [client.configPath] });
|
|
if (legacyClientServerPath(parsed, name) !== undefined) {
|
|
entries.push({
|
|
value: parsed.legacyServers[name],
|
|
paths: [client.configPath],
|
|
});
|
|
entries.push(
|
|
...shadowedClientServers(original, parsed, name).legacyServers.map(
|
|
(value) => ({ value, paths: [client.configPath] }),
|
|
),
|
|
);
|
|
}
|
|
for (const entry of entries) {
|
|
const ownership =
|
|
currentCommandPath === undefined
|
|
? clientRegistrationOwnership(entry.value, client)
|
|
: clientRegistrationOwnership(entry.value, client, currentCommandPath);
|
|
if (ownership !== "owned")
|
|
return clientRegistrationOwnershipRemediation(ownership, entry.paths);
|
|
}
|
|
return undefined;
|
|
};
|
|
|
|
/** Admit the fallback only when the first native ZCode server would suppress it. */
|
|
const readZcodeFallbackServers = async (
|
|
client: SetupClient,
|
|
platform: NodeJS.Platform,
|
|
parsed?: ClientConfigurationDocument,
|
|
): Promise<
|
|
Result<
|
|
Readonly<Record<string, unknown>>,
|
|
| ClientConfigurationFileError
|
|
| {
|
|
readonly kind: "registration_ownership";
|
|
readonly path: string;
|
|
readonly detail: string;
|
|
}
|
|
>
|
|
> => {
|
|
if (
|
|
client.format !== "zcode" ||
|
|
(parsed !== undefined && Object.keys(parsed.servers).length > 0)
|
|
)
|
|
return ok({});
|
|
const path = client.zcodeFallbackPath;
|
|
const detail = `The ZCode fallback configuration ${path ?? "path"} is unresolved, malformed or unreadable. Repair it before rerunning setup: the first native server would suppress that fallback.`;
|
|
if (path === undefined)
|
|
return err({ kind: "unreadable", path: client.configPath, detail });
|
|
const transactionPath = await resolveClientConfigTransactionPath(path);
|
|
if (transactionPath === undefined)
|
|
return err({ kind: "unreadable", path, detail });
|
|
const source = await readConfigurationText(transactionPath);
|
|
if (!source.ok)
|
|
return err({ ...source.error, detail: `${detail} ${source.error.detail}` });
|
|
if (source.value === undefined) return ok({});
|
|
try {
|
|
const parsed = parseZcodeFallbackConfiguration(source.value);
|
|
const ownershipBlocker = registrationOwnershipBlocker(
|
|
{ ...client, configPath: path, format: "zcode_fallback" },
|
|
parsed,
|
|
source.value,
|
|
[],
|
|
platform,
|
|
);
|
|
if (ownershipBlocker !== undefined)
|
|
return err({
|
|
kind: "registration_ownership",
|
|
path,
|
|
detail: ownershipBlocker,
|
|
});
|
|
const environment = clientRegistrationEnvironment(parsed, client, platform);
|
|
if (!environment.ok)
|
|
return err({
|
|
kind: "malformed",
|
|
path,
|
|
detail: `${detail} ${environment.error.settings.map(({ setting, constraint }) => `${setting}: ${constraint}`).join("; ")}`,
|
|
});
|
|
return ok(parsed.servers);
|
|
} catch (cause: unknown) {
|
|
return err({
|
|
kind: "malformed",
|
|
path,
|
|
detail: `${detail} ${errorMessage(cause)}`,
|
|
});
|
|
}
|
|
};
|
|
|
|
type ConfigurationRestoreFailure =
|
|
| { readonly kind: "conflict" }
|
|
| {
|
|
readonly kind: "restore";
|
|
readonly path: string;
|
|
readonly detail: string;
|
|
};
|
|
|
|
const restoreConfig = async (
|
|
publication: ClientConfigurationPublication,
|
|
original: string | undefined,
|
|
): Promise<Result<void, ConfigurationRestoreFailure>> => {
|
|
try {
|
|
await publication.restore(original);
|
|
return ok(undefined);
|
|
} catch (cause: unknown) {
|
|
if (isConfigurationConflict(cause) || isMissing(cause))
|
|
return err({ kind: "conflict" });
|
|
return err({
|
|
kind: "restore",
|
|
path: publication.path,
|
|
detail: errorMessage(cause),
|
|
});
|
|
}
|
|
};
|
|
|
|
const rollbackOrReadbackFailure = async (
|
|
publication: ClientConfigurationPublication,
|
|
original: string | undefined,
|
|
backupPath: string | undefined,
|
|
): Promise<ClientConfigurationResult> => {
|
|
const rollback = await restoreConfig(publication, original);
|
|
return rollback.ok
|
|
? {
|
|
status: "failed",
|
|
reason: "readback",
|
|
...(backupPath === undefined ? {} : { backupPath }),
|
|
}
|
|
: rollbackFailure(rollback.error, backupPath);
|
|
};
|
|
|
|
const rollbackFailure = (
|
|
failure: ConfigurationRestoreFailure,
|
|
backupPath?: string,
|
|
): Extract<ClientConfigurationResult, { readonly status: "failed" }> =>
|
|
failure.kind === "conflict"
|
|
? conflictFailure(backupPath)
|
|
: {
|
|
status: "failed",
|
|
reason: "rollback",
|
|
failure,
|
|
...(backupPath === undefined ? {} : { backupPath }),
|
|
};
|
|
|
|
const isConfigurationConflict = (cause: unknown): boolean =>
|
|
cause instanceof RegularFileChangedError ||
|
|
cause instanceof InvalidUtf8FileError;
|
|
|
|
const conflictFailure = (
|
|
backupPath?: string,
|
|
): Extract<ClientConfigurationResult, { readonly status: "failed" }> => ({
|
|
status: "failed",
|
|
reason: "conflict",
|
|
...(backupPath === undefined ? {} : { backupPath }),
|
|
});
|
|
|
|
/** Whether REA's entry matches, no legacy entry remains, and no client disable list suppresses it. */
|
|
const registrationCurrent = (
|
|
parsed: ClientConfigurationDocument,
|
|
desired: unknown,
|
|
): boolean =>
|
|
parsed.requiresRewrite !== true &&
|
|
(parsed.dialect !== "dsh" || dshDocument(parsed.document).ready) &&
|
|
clientConfigurationValuesEqual(
|
|
parsed.servers[PRODUCT_IDENTITY.mcpServerKey],
|
|
desired,
|
|
) &&
|
|
!Object.hasOwn(parsed.legacyServers, PRODUCT_IDENTITY.mcpServerKey) &&
|
|
!clientServerListedDisabled(parsed, PRODUCT_IDENTITY.mcpServerKey);
|
|
|
|
/**
|
|
* A private profile with the wrong modes needs publication even when its row
|
|
* is current. Modes belong to the host holding the file, not to the platform
|
|
* the registration is written for.
|
|
*/
|
|
const privateProfileCurrent = async (
|
|
client: SetupClient,
|
|
original: string | undefined,
|
|
): Promise<boolean> =>
|
|
client.privateProfile === undefined ||
|
|
(original !== undefined &&
|
|
(await privateProfileModesCurrent(
|
|
client.configPath,
|
|
HOST_PLATFORM.platform,
|
|
)));
|
|
|
|
const clientConfigurationDesired = async (
|
|
client: SetupClient,
|
|
providerEnvironment: SetupProviderEnvironment,
|
|
command: readonly string[],
|
|
parsed: ClientConfigurationDocument | undefined,
|
|
sources: readonly ClientConfigurationSource[],
|
|
platform: NodeJS.Platform,
|
|
resolveProviderRequestBudget?: ProviderRequestBudgetResolver,
|
|
): Promise<unknown> => {
|
|
const effective = effectiveClientConfiguration(
|
|
sources,
|
|
{ client, document: parsed },
|
|
platform,
|
|
);
|
|
const format = clientWriteDialect(
|
|
parsed?.dialect ?? client.format ?? "json",
|
|
sources,
|
|
);
|
|
const launcher =
|
|
command.length === 0 ? [PRODUCT_IDENTITY.cliBinary, "mcp"] : command;
|
|
if (format === "dsh") {
|
|
const validated = clientRegistrationEnvironment(
|
|
effective,
|
|
client,
|
|
platform,
|
|
providerEnvironment,
|
|
);
|
|
if (!validated.ok) throw validated.error;
|
|
const desired = (
|
|
parsed === undefined
|
|
? new DshCordisDocument("")
|
|
: dshDocument(parsed.document)
|
|
).desired(launcher, providerEnvironment, platform);
|
|
if (!desired.ok) throw desired.error;
|
|
return desired.value;
|
|
}
|
|
const validated = await clientRegistrationEnvironmentDetailsWithBudget(
|
|
effective,
|
|
client,
|
|
providerEnvironment,
|
|
"effective",
|
|
client.name === "codex" || client.name === "kimi"
|
|
? resolveProviderRequestBudget
|
|
: undefined,
|
|
platform,
|
|
);
|
|
if (!validated.ok) throw validated.error;
|
|
// Preserve explicitly configured server settings, never the ambient process
|
|
// environment. The effective layered view validates precedence and supplies
|
|
// timeout facts; the target file's fragment remains the value being written.
|
|
const environment = clientRegistrationEnvironment(
|
|
parsed,
|
|
client,
|
|
platform,
|
|
providerEnvironment,
|
|
"fragment",
|
|
);
|
|
if (!environment.ok) throw environment.error;
|
|
const registration = refreshClientRegistration(
|
|
client,
|
|
format,
|
|
launcher,
|
|
environment.value,
|
|
parsed === undefined
|
|
? undefined
|
|
: effectiveClientServer(parsed, PRODUCT_IDENTITY.mcpServerKey),
|
|
validated.value.timeoutInputs,
|
|
);
|
|
if (!registration.ok) throw registration.error;
|
|
return withInheritedGooseSettings(
|
|
registration.value,
|
|
format,
|
|
client,
|
|
parsed,
|
|
sources,
|
|
effective,
|
|
providerEnvironment,
|
|
platform,
|
|
);
|
|
};
|
|
|
|
/**
|
|
* Goose replaces `envs` as a whole map per layer, so a user map must carry the
|
|
* inherited one. When the user entry declares no environment and a lower layer
|
|
* does, setup writes no map unless a setting is requested, and then writes the
|
|
* inherited map with the requested settings applied last. Other settings only a
|
|
* lower layer declares are left to that layer.
|
|
*/
|
|
const GOOSE_INHERITABLE_SETTINGS: readonly string[] = [
|
|
"name",
|
|
"description",
|
|
"enabled",
|
|
"timeout",
|
|
];
|
|
|
|
const withInheritedGooseSettings = (
|
|
withoutInherited: Record<string, unknown>,
|
|
format: ClientRegistrationDialect,
|
|
client: SetupClient,
|
|
parsed: ClientConfigurationDocument | undefined,
|
|
sources: readonly ClientConfigurationSource[],
|
|
effective: ClientConfigurationDocument | undefined,
|
|
providerEnvironment: SetupProviderEnvironment,
|
|
platform: NodeJS.Platform,
|
|
): Record<string, unknown> => {
|
|
if (format !== "goose") return withoutInherited;
|
|
// The layers below the user file, which the user entry overlays field by field.
|
|
const lower = effectiveClientConfiguration(
|
|
sources,
|
|
{ client, document: undefined },
|
|
platform,
|
|
);
|
|
const declares = (
|
|
document: ClientConfigurationDocument | undefined,
|
|
keys: readonly string[],
|
|
) => {
|
|
const entry =
|
|
document === undefined
|
|
? undefined
|
|
: effectiveClientServer(document, PRODUCT_IDENTITY.mcpServerKey);
|
|
return (
|
|
typeof entry === "object" &&
|
|
entry !== null &&
|
|
keys.some((key) => Object.hasOwn(entry, key))
|
|
);
|
|
};
|
|
// Goose merges each field separately, so a user map must use the spelling a
|
|
// lower layer declares: `envs` beside an inherited `env` alias would leave
|
|
// both in force, which Goose's readers reject as ambiguous.
|
|
const spelled = (
|
|
registration: Record<string, unknown>,
|
|
): Record<string, unknown> => {
|
|
if (!declares(lower, ["env"]) || !Object.hasOwn(registration, "envs"))
|
|
return registration;
|
|
const { envs, ...rest } = registration;
|
|
return { ...rest, env: envs };
|
|
};
|
|
const userDeclares = (keys: readonly string[]) => declares(parsed, keys);
|
|
// A setting only a lower layer declares stays in effect: writing setup's
|
|
// default into the user entry would override that caller's choice.
|
|
const registration = Object.fromEntries(
|
|
Object.entries(withoutInherited).filter(
|
|
([key]) =>
|
|
!GOOSE_INHERITABLE_SETTINGS.includes(key) ||
|
|
userDeclares([key]) ||
|
|
!declares(lower, [key]),
|
|
),
|
|
);
|
|
const environmentKeys = ["envs", "env"];
|
|
if (userDeclares(environmentKeys) || !declares(lower, environmentKeys))
|
|
return spelled(registration);
|
|
const { envs: _generated, ...rest } = registration;
|
|
if (Object.keys(providerEnvironment).length === 0) return rest;
|
|
const inherited = clientRegistrationEnvironment(
|
|
effective,
|
|
client,
|
|
platform,
|
|
providerEnvironment,
|
|
"fragment",
|
|
);
|
|
if (!inherited.ok) throw inherited.error;
|
|
return spelled({ ...rest, envs: { ...inherited.value } });
|
|
};
|