feat(clients): register ZCode during setup (#1564)
* feat(clients): register ZCode during setup - SupportedClients: zcode definition (~/.zcode/cli/config.json, format zcode, personal skills at ~/.zcode/skills) - ClientConfigurationDocument: zcode dialect reads/writes the nested mcp.servers table; withClientServers now tolerates a missing outer table for fresh documents - docs: add ZCode to the supported-clients table with configuration notes - tests: zcodeClientConfiguration.test.ts (path resolution, nested upsert, fresh/empty configs, uninstall) Verified: tsc --noEmit clean; vitest run tests/boundary/filesystem/zcodeClientConfiguration.test.ts 6/6. * fix(clients): preserve ZCode fallback servers and honor enable flag Review follow-up (#1564), two integration gaps: - ZCode reads the user-scope ~/.agents/mcp.json fallback only while the native .zcode config defines no servers at all, with no merging. Setup now copies the fallback's mcpServers entries into the native table when writing the first native server, so registrations that only live in the fallback keep loading; the fallback file is left untouched. A malformed fallback fails setup closed (configure and preflight) instead of being silently suppressed. - ZCode disables a server with "enable": false on its entry, which the generic status parsing (disabled/enabled) did not recognize: doctor reported such a registration as aligned although ZCode never starts it. The ZCode dialect now treats enable: false as disabled (state stale) and setup rewrites the entry on rerun. Docs describe both behaviors; the bundled REA skill's supported client list includes zcode. Verified: tsc --noEmit clean; vitest run tests/boundary/filesystem/zcodeClientConfiguration.test.ts 10/10; npm run check:fast green; npm run verify:test-discovery 733 files. * fix(clients): reject non-regular ZCode fallback files before reading Resolve the fallback through the client-config transaction path and the regular-file admission before parsing it, so a FIFO or other non-regular file at ~/.agents/mcp.json fails setup closed instead of blocking the read indefinitely. Directory and FIFO fallback cases are covered in tests, and the preflight remediation names unreadable fallbacks too. --------- Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
This commit is contained in:
@@ -1,5 +1,9 @@
|
||||
import { readClientPolicyBlock } from "./GeminiClientSettings.js";
|
||||
import { readClientConfigurationFiles } from "./ClientConfigurationFiles.js";
|
||||
import {
|
||||
readClientConfigurationFiles,
|
||||
readConfigurationText,
|
||||
} from "./ClientConfigurationFiles.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
import {
|
||||
clientRegistrationEntry,
|
||||
clientConfigurationValuesEqual,
|
||||
@@ -8,6 +12,7 @@ import {
|
||||
legacyClientServerPath,
|
||||
OMP_DISABLED_SERVERS_KEY,
|
||||
parseClientConfiguration,
|
||||
parseZcodeFallbackConfiguration,
|
||||
serializeClientConfiguration,
|
||||
withClientServers,
|
||||
type ClientConfigurationDocument,
|
||||
@@ -120,12 +125,15 @@ const configureClientDocument = async (
|
||||
void cause;
|
||||
return { status: "failed", reason: "readback" };
|
||||
}
|
||||
const desired = clientConfigurationDesired(
|
||||
client,
|
||||
environment,
|
||||
command,
|
||||
parsed,
|
||||
);
|
||||
const fallback = await readZcodeFallbackServers(client, parsed);
|
||||
if (!fallback.ok) {
|
||||
throwCleanupFailure(fallback.error);
|
||||
return { status: "failed", reason: "readback" };
|
||||
}
|
||||
const desired = clientConfigurationDesired(client, environment, command, {
|
||||
...parsed,
|
||||
servers: { ...fallback.value, ...parsed.servers },
|
||||
});
|
||||
if (registrationCurrent(parsed, desired)) return { status: "unchanged" };
|
||||
return persistClientConfiguration({
|
||||
client,
|
||||
@@ -134,6 +142,7 @@ const configureClientDocument = async (
|
||||
original,
|
||||
parsed,
|
||||
desired,
|
||||
fallbackServers: fallback.value,
|
||||
});
|
||||
};
|
||||
|
||||
@@ -144,6 +153,7 @@ interface ClientConfigurationUpdate {
|
||||
readonly original: string | undefined;
|
||||
readonly parsed: ClientConfigurationDocument;
|
||||
readonly desired: unknown;
|
||||
readonly fallbackServers: Readonly<Record<string, unknown>>;
|
||||
}
|
||||
|
||||
const persistClientConfiguration = async ({
|
||||
@@ -153,6 +163,7 @@ const persistClientConfiguration = async ({
|
||||
original,
|
||||
parsed,
|
||||
desired,
|
||||
fallbackServers,
|
||||
}: ClientConfigurationUpdate): Promise<ClientConfigurationResult> => {
|
||||
const backupPath =
|
||||
original === undefined ? undefined : `${client.configPath}.rea.backup`;
|
||||
@@ -169,7 +180,11 @@ const persistClientConfiguration = async ({
|
||||
);
|
||||
const registered = withClientServers(
|
||||
parsed,
|
||||
{ ...parsed.servers, [PRODUCT_IDENTITY.mcpServerKey]: desired },
|
||||
{
|
||||
...fallbackServers,
|
||||
...parsed.servers,
|
||||
[PRODUCT_IDENTITY.mcpServerKey]: desired,
|
||||
},
|
||||
PRODUCT_IDENTITY.mcpServerKey,
|
||||
);
|
||||
// OMP's denylist would hide the registration; keep every other listed name.
|
||||
@@ -194,6 +209,9 @@ const persistClientConfiguration = async ({
|
||||
await writeFileAtomic(
|
||||
transactionPath,
|
||||
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]] : []),
|
||||
@@ -213,7 +231,14 @@ const persistClientConfiguration = async ({
|
||||
await readRegularFileText(transactionPath),
|
||||
format,
|
||||
);
|
||||
if (!registrationCurrent(readback, desired)) {
|
||||
if (
|
||||
!registrationCurrent(readback, desired) ||
|
||||
Object.entries(fallbackServers).some(
|
||||
([name, entry]) =>
|
||||
name !== PRODUCT_IDENTITY.mcpServerKey &&
|
||||
!clientConfigurationValuesEqual(readback.servers[name], entry),
|
||||
)
|
||||
) {
|
||||
await restoreConfig(transactionPath, original);
|
||||
return { status: "failed", reason: "readback" };
|
||||
}
|
||||
@@ -329,7 +354,14 @@ export const inspectClientConfiguration = async (
|
||||
original = await readRegularFileText(transactionPath);
|
||||
} catch (cause: unknown) {
|
||||
if (cause instanceof RegularFileCleanupFailure) throw cause;
|
||||
if (isMissing(cause)) return { status: "create" };
|
||||
if (isMissing(cause)) {
|
||||
const fallback = await readZcodeFallbackServers(client);
|
||||
if (!fallback.ok) {
|
||||
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. ${cause instanceof Error ? cause.message : String(cause)}`,
|
||||
@@ -359,6 +391,11 @@ export const inspectClientConfiguration = async (
|
||||
);
|
||||
if (registrationCurrent(parsed, desired))
|
||||
return { status: "already_current" };
|
||||
const fallback = await readZcodeFallbackServers(client, parsed);
|
||||
if (!fallback.ok) {
|
||||
throwCleanupFailure(fallback.error);
|
||||
return { status: "invalid", remediation: fallback.error.detail };
|
||||
}
|
||||
} catch (cause: unknown) {
|
||||
if (cause instanceof RegularFileCleanupFailure) throw cause;
|
||||
// Malformed configuration is reported with the invalid remediation.
|
||||
@@ -382,6 +419,48 @@ const throwCleanupFailure = (error: ClientConfigurationFileError): void => {
|
||||
if (error.cleanupFailure !== undefined) throw error.cleanupFailure;
|
||||
};
|
||||
|
||||
/** Admit the fallback only when the first native ZCode server would suppress it. */
|
||||
const readZcodeFallbackServers = async (
|
||||
client: SetupClient,
|
||||
parsed?: ClientConfigurationDocument,
|
||||
): Promise<
|
||||
Result<Readonly<Record<string, unknown>>, ClientConfigurationFileError>
|
||||
> => {
|
||||
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 environment = clientRegistrationEnvironment(parsed);
|
||||
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} ${cause instanceof Error ? cause.message : String(cause)}`,
|
||||
});
|
||||
}
|
||||
};
|
||||
|
||||
const preserveConfigBackup = async (
|
||||
source: string,
|
||||
destination: string,
|
||||
|
||||
Reference in New Issue
Block a user