@gtkx/config 1.5.0 → 2.0.0-beta.1

package/src/config.ts

@@ -2,22 +2,17 @@ import { createDefineConfig, type DefineConfig } from "c12";
 import { defu } from "defu";
 import { resolve } from "node:path";
 import { z } from "zod";
-import { configError, isRecord, rawIssue } from "./config-error.ts";
+import { configError, isRecord } from "./config-error.ts";
 import { deploySchema } from "./deploy.ts";
-import { isGirLibrary, text } from "./schema-text.ts";
+import { girLibrary, text } from "./schema-text.ts";
 import { resolveUserEventSignals } from "./user-event-signals.ts";
 
-/** Accepted `reactCompiler.compilationMode` values, choosing which functions the compiler processes. */
-type ReactCompilerCompilationMode = (typeof COMPILATION_MODES)[number];
-/** Accepted `reactCompiler.panicThreshold` values, choosing which compiler diagnostics fail the build. */
-type ReactCompilerPanicThreshold = (typeof PANIC_THRESHOLDS)[number];
-
-/** Object form of the `reactCompiler` config key, forwarded as-is to `babel-plugin-react-compiler`. */
+/** Object form of the `reactCompiler` config key, forwarded to `babel-plugin-react-compiler`. */
 type ReactCompilerOptions = {
-    /** Which functions the compiler processes; left to the compiler's own default when omitted. */
-    compilationMode?: ReactCompilerCompilationMode;
-    /** Which compiler diagnostics fail the build; left to the compiler's own default when omitted. */
-    panicThreshold?: ReactCompilerPanicThreshold;
+    /** Which functions the compiler processes. */
+    compilationMode?: (typeof COMPILATION_MODES)[number];
+    /** Which compiler diagnostics fail the build. */
+    panicThreshold?: (typeof PANIC_THRESHOLDS)[number];
 };
 
 /**
@@ -32,13 +27,18 @@ type ResolvedReactCompilerOptions = ReactCompilerOptions & {
 /**
  * User-facing configuration for a GTKX project, as authored in `gtkx.config.ts`: the GIR libraries
  * to bind and where to find them, the GApplication id, per-element configuration, the React
- * Compiler, codegen, and user event signal settings, and the `future` block opting into behavior
- * that becomes the default in the next major version.
+ * Compiler, codegen, and user event signal settings, and the `agents` and `mcp` blocks controlling
+ * what coding agents are given.
  */
 type Config = z.infer<typeof configSchema>;
 type ModuleExport = z.infer<typeof moduleExportSchema>;
 type ElementConfigEntry = z.infer<typeof elementConfigSchema>;
 
+type McpSettings = {
+    tools: string[];
+    isReadOnly: boolean;
+};
+
 /** Configuration reduced to the values the app runtime and the build need, with paths already resolved. */
 type ResolvedConfig = {
     /** The GApplication identifier the app registers under. */
@@ -56,92 +56,35 @@ type ResolvedConfig = {
     lazyElements: string[];
 };
 
-const LIBRARIES_WILDCARD = "*";
 const APPLICATION_ID_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*(\.[A-Za-z_][A-Za-z0-9_-]*)+$/;
 const APPLICATION_ID_MAX_LENGTH = 255;
+const DEFAULT_LIBRARIES: Set<string> = new Set(["Gtk-4.0", "Adw-1"]);
 /** Compilation modes `babel-plugin-react-compiler` accepts. */
 const COMPILATION_MODES = ["infer", "syntax", "annotation", "all"] as const;
 /** Panic thresholds `babel-plugin-react-compiler` accepts. */
 const PANIC_THRESHOLDS = ["none", "critical_errors", "all_errors"] as const;
 const REACT_COMPILER_TARGET = "19";
-const COMPILATION_MODE_SET: Set<string> = new Set(COMPILATION_MODES);
-const PANIC_THRESHOLD_SET: Set<string> = new Set(PANIC_THRESHOLDS);
 
-const librariesSchema = z.custom<typeof LIBRARIES_WILDCARD | string[]>().check((ctx) => {
-    const value = ctx.value;
+const librarySchema = girLibrary('must be of the form "Name-Version", such as "Gtk-4.0"')
+    .refine((library) => !DEFAULT_LIBRARIES.has(library), { error: "is bound by default; remove it" });
 
-    if (value === LIBRARIES_WILDCARD) {
-        return;
-    }
+const librariesSchema = z
+    .array(librarySchema, { error: "must be a non-empty string array or omitted" })
+    .min(1, { error: "must be a non-empty string array or omitted" });
 
-    if (!Array.isArray(value) || value.length === 0) {
-        ctx.issues.push(rawIssue(value, [], `must be "${LIBRARIES_WILDCARD}", a non-empty string array, or omitted`));
+const applicationIdSchema = z
+    .string({ error: "must satisfy g_application_id_is_valid" })
+    .refine((value) => isValidApplicationId(value), {
+        error: 'must satisfy g_application_id_is_valid, such as "org.example.MyApp"',
+    });
 
-        return;
-    }
-
-    for (const [index, entry] of value.entries()) {
-        ctx.issues.push(...libraryEntryIssues(value, index, entry));
-    }
-});
-
-const applicationIdSchema = z.custom<string>().check((ctx) => {
-    const value = ctx.value;
-
-    if (typeof value !== "string" || !isValidApplicationId(value)) {
-        ctx.issues.push(
-            rawIssue(
-                value,
-                [],
-                `invalid \`applicationId\` "${value}", must satisfy g_application_id_is_valid ` +
-                '(e.g. "org.example.MyApp")',
-                true,
-            ),
-        );
-    }
-});
-
-const reactCompilerSchema = z.custom<boolean | ReactCompilerOptions>().check((ctx) => {
-    const value = ctx.value;
-
-    if (typeof value === "boolean") {
-        return;
-    }
-
-    if (!isRecord(value)) {
-        ctx.issues.push(rawIssue(value, [], "must be a boolean or an options object"));
-
-        return;
-    }
-
-    const compilationMode = value.compilationMode;
-
-    if (!isValidReactCompilerOption(compilationMode, COMPILATION_MODE_SET)) {
-        ctx.issues.push(
-            rawIssue(
-                value,
-                [],
-                `invalid \`reactCompiler.compilationMode\` "${String(compilationMode)}", ` +
-                `must be one of ${COMPILATION_MODES.join(", ")}`,
-                true,
-            ),
-        );
-    }
-
-    const panicThreshold = value.panicThreshold;
-
-    if (!isValidReactCompilerOption(panicThreshold, PANIC_THRESHOLD_SET)) {
-        ctx.issues.push(
-            rawIssue(
-                value,
-                [],
-                `invalid \`reactCompiler.panicThreshold\` "${String(panicThreshold)}", ` +
-                `must be one of ${PANIC_THRESHOLDS.join(", ")}`,
-                true,
-            ),
-        );
-    }
-});
+const reactCompilerSchema = z.union([
+    z.boolean(),
+    z.object({
+        compilationMode: z.enum(COMPILATION_MODES).optional(),
+        panicThreshold: z.enum(PANIC_THRESHOLDS).optional(),
+    }),
+]);
 
 const userEventSignalsSchema = z.record(
     z.string(),
@@ -184,17 +127,42 @@ const elementsSchema = z.object({
     config: z.record(z.string(), elementConfigSchema).optional(),
 });
 
-const futureSchema = z.object({
-    v2ByteArrays: z.boolean({ error: "must be a boolean" }).optional(),
-    v2ValueReturns: z.boolean({ error: "must be a boolean" }).optional(),
-    v2FinishResults: z.boolean({ error: "must be a boolean" }).optional(),
-    v2InoutReturns: z.boolean({ error: "must be a boolean" }).optional(),
-    v2ResourceImports: z.boolean({ error: "must be a boolean" }).optional(),
+const agentsSchema = z.object({
+    rules: z.boolean({ error: "must be a boolean" }).optional(),
+    reference: z.boolean({ error: "must be a boolean" }).optional(),
+});
+
+const mcpSchema = z.object({
+    tools: z
+        .array(z.string({ error: "must be a tool name pattern" }).min(1, { error: "must be a tool name pattern" }), {
+            error: "must be an array of tool name patterns",
+        })
+        .optional(),
+    readOnly: z.boolean({ error: "must be a boolean" }).optional(),
+});
+
+const graduatedFutureSchema = z
+    .object({
+        v2ByteArrays: z.literal(true, { error: "can only be true; remove the flag" }).optional(),
+        v2ValueReturns: z.literal(true, { error: "can only be true; remove the flag" }).optional(),
+        v2FinishResults: z.literal(true, { error: "can only be true; remove the flag" }).optional(),
+        v2InoutReturns: z.literal(true, { error: "can only be true; remove the flag" }).optional(),
+        v2ResourceImports: z.literal(true, { error: "can only be true; remove the flag" }).optional(),
+        v2DefaultLibraries: z.literal(true, { error: "can only be true; remove the flag" }).optional(),
+        v2TreeShaking: z.literal(true, { error: "can only be true; remove the flag" }).optional(),
+    })
+    .strict();
+
+const deprecationsSchema = z.object({
+    silence: z
+        .array(z.never({ error: "does not name a current deprecation" }), {
+            error: "must be an array of current deprecation ids",
+        })
+        .optional(),
 });
 
 /** Schema every `gtkx.config.ts` is validated against, and the source of the {@link Config} type. */
 const configSchema = z.object({
-    future: futureSchema.optional(),
     libraries: librariesSchema.optional(),
     girPath: z.array(z.string(), { error: "must be an array of strings if provided" }).optional(),
     applicationId: applicationIdSchema,
@@ -204,6 +172,9 @@ const configSchema = z.object({
     elements: elementsSchema.optional(),
     applicationIcon: text("must be a path to an icon theme directory or a single icon file").optional(),
     deploy: deploySchema.optional(),
+    agents: agentsSchema.optional(),
+    mcp: mcpSchema.optional(),
+    deprecations: deprecationsSchema.optional(),
 });
 
 /**
@@ -211,34 +182,10 @@ const configSchema = z.object({
  * autocompletion and type checking.
  */
 const defineConfig: DefineConfig<Config> = createDefineConfig<Config>();
+const validationSchema = configSchema.extend({ future: graduatedFutureSchema.optional() });
 
-const libraryEntryIssues = (value: unknown[], index: number, entry: unknown): ReturnType<typeof rawIssue>[] => {
-    if (typeof entry === "string" && isGirLibrary(entry)) {
-        return [];
-    }
-
-    if (entry === LIBRARIES_WILDCARD) {
-        const message =
-            `to generate every library, set \`libraries: "${LIBRARIES_WILDCARD}"\` as a bare string, ` +
-            "not an array entry";
-
-        return [rawIssue(value, [index], message, true)];
-    }
-
-    const message =
-        `invalid library identifier "${String(entry)}", must be of the form "Name-Version" ` +
-        '(e.g. "Gtk-4.0")';
-
-    return [rawIssue(value, [index], message, true)];
-};
-
-const isValidApplicationId = (applicationId: string): boolean => {
-    if (applicationId.length === 0 || applicationId.length > APPLICATION_ID_MAX_LENGTH) {
-        return false;
-    }
-
-    return APPLICATION_ID_PATTERN.test(applicationId);
-};
+const isValidApplicationId = (applicationId: string): boolean =>
+    applicationId.length <= APPLICATION_ID_MAX_LENGTH && APPLICATION_ID_PATTERN.test(applicationId);
 
 const resolveReactCompilerOptions = (setting: Config["reactCompiler"]): ResolvedReactCompilerOptions | null => {
     if (setting === false) {
@@ -247,22 +194,31 @@ const resolveReactCompilerOptions = (setting: Config["reactCompiler"]): Resolved
 
     const overrides = setting === undefined || setting === true ? {} : setting;
 
-    return { ...overrides, target: REACT_COMPILER_TARGET };
+    return {
+        ...(overrides.compilationMode !== undefined && { compilationMode: overrides.compilationMode }),
+        ...(overrides.panicThreshold !== undefined && { panicThreshold: overrides.panicThreshold }),
+        target: REACT_COMPILER_TARGET,
+    };
 };
 
-const isValidReactCompilerOption = (value: unknown, allowed: Set<string>): boolean =>
-    value === undefined || (typeof value === "string" && allowed.has(value));
-
-const validateConfig = (config: Config): void => {
-    const result = configSchema.safeParse(config);
+const validateConfig = (config: unknown): void => {
+    const result = validationSchema.safeParse(config);
 
     if (!result.success) {
         throw configError(result.error);
     }
 };
 
+const graduatedFutureKeys = (config: unknown): string[] => {
+    if (!isRecord(config) || !isRecord(config.future)) {
+        return [];
+    }
+
+    return Object.keys(config.future).toSorted((first, second) => first.localeCompare(second));
+};
+
 /**
- * Deep-merges two configurations. `override` wins over `base` on conflicting scalar and object keys, while
+ * Deep-merges a configuration over a base. `override` wins over `base` on conflicting scalar and object keys, while
  * arrays are concatenated with the `override` entries first.
  */
 const mergeConfig = (base: Config, override: Config): Config => defu(override, base);
@@ -301,6 +257,14 @@ const resolveElementProps = (elements: Config["elements"]): Record<string, Modul
 const resolveOmittedProps = (elements: Config["elements"]): Record<string, string[]> =>
     elementEntryValues(elements, (entry) => entry.omittedProps);
 
+const isAgentRulesEnabled = (config: Config): boolean => config.agents?.rules !== false;
+const isAgentReferenceEnabled = (config: Config): boolean => config.agents?.reference !== false;
+
+const resolveMcpSettings = (config: Config): McpSettings => ({
+    tools: config.mcp?.tools ?? [],
+    isReadOnly: config.mcp?.readOnly === true,
+});
+
 const resolveConfig = (config: Config, root?: string): ResolvedConfig => ({
     applicationId: config.applicationId,
     reactCompiler: resolveReactCompilerOptions(config.reactCompiler),
@@ -312,14 +276,19 @@ const resolveConfig = (config: Config, root?: string): ResolvedConfig => ({
 export {
     APPLICATION_ID_MAX_LENGTH,
     defineConfig,
+    isAgentReferenceEnabled,
+    isAgentRulesEnabled,
     isValidApplicationId,
+    graduatedFutureKeys,
     validateConfig,
     mergeConfig,
     resolveLazyElements,
     resolveElementComponents,
     resolveElementProps,
+    resolveMcpSettings,
     resolveOmittedProps,
     resolveConfig,
+    type McpSettings,
     type ResolvedReactCompilerOptions,
     type Config,
     type ResolvedConfig,

package/src/deploy.ts

@@ -119,7 +119,7 @@ const extraFileEntrySchema = z.union([text(SOURCE_PATH_ERROR), extraFileSchema],
 
 const nodeRuntimeSchema = z.strictObject({
     source: z.enum(NODE_SOURCES, { error: "must be one of download, host, path" }).optional(),
-    version: text("must be a Node.js version such as 24.19.0").optional(),
+    version: text("must be a Node.js version such as 26.7.0").optional(),
     path: text("must be a path to a node binary").optional(),
     shouldStrip: flag(BOOLEAN_ERROR).optional(),
     shouldUseCompileCache: flag(BOOLEAN_ERROR).optional(),

package/src/index.ts

@@ -1,4 +1,2 @@
-/** @public */
 export { type Config, defineConfig, mergeConfig, type ResolvedConfig } from "./config.ts";
-/** @public */
 export { type ConfigLoader, type LoadedConfig, loadConfig } from "./loader.ts";

package/src/internal.ts

@@ -1,10 +1,13 @@
-export type { ResolvedReactCompilerOptions } from "./config.ts";
+export type { McpSettings, ResolvedReactCompilerOptions } from "./config.ts";
 export {
     APPLICATION_ID_MAX_LENGTH,
+    isAgentReferenceEnabled,
+    isAgentRulesEnabled,
     isValidApplicationId,
     resolveElementComponents,
     resolveElementProps,
     resolveLazyElements,
+    resolveMcpSettings,
     resolveOmittedProps,
 } from "./config.ts";
 export { createConfigLoader } from "./loader.ts";

package/src/loader.ts

@@ -1,9 +1,15 @@
-import { getOrInsert } from "@gtkx/utils";
+import { warn } from "@gtkx/utils";
 import { loadConfig as loadConfigFile } from "c12";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { missingConfigFileError } from "./config-error.ts";
-import { type Config, resolveConfig, type ResolvedConfig, validateConfig } from "./config.ts";
+import {
+    type Config,
+    graduatedFutureKeys,
+    resolveConfig,
+    type ResolvedConfig,
+    validateConfig,
+} from "./config.ts";
 
 /** Result of loading a project's `gtkx.config.ts` file. */
 type LoadedConfig = {
@@ -32,6 +38,26 @@ type ConfigLoader = {
     resolve: (cwd: string) => Promise<ResolvedConfig>;
 };
 
+const GRADUATED_FUTURE_ENV = "GTKX_GRADUATED_FUTURE_SHOWN";
+const graduatedFutureWarnings: Map<string, string> = new Map();
+
+const warnGraduatedFuture = (config: unknown, root: string): void => {
+    const keys = graduatedFutureKeys(config);
+    const signature = keys.join(",");
+
+    if (
+        keys.length === 0 ||
+        graduatedFutureWarnings.get(root) === signature ||
+        process.env[GRADUATED_FUTURE_ENV] === signature
+    ) {
+        return;
+    }
+
+    graduatedFutureWarnings.set(root, signature);
+    process.env[GRADUATED_FUTURE_ENV] = signature;
+    warn(`GTKX 2 ignores graduated future flags: ${keys.join(", ")}. Remove them from gtkx.config.ts.`);
+};
+
 /**
  * Loads and validates the `gtkx.config.ts` file for a project.
  * @param cwd Directory the configuration file is looked up in; parent directories are not searched.
@@ -58,12 +84,14 @@ const loadConfig = async (cwd: string, options: LoadConfigOptions = {}): Promise
     }
 
     const config = result.config;
+    const root = result.cwd ?? searched;
     validateConfig(config);
+    warnGraduatedFuture(config, root);
 
     return {
         config,
         configFile,
-        root: result.cwd ?? searched,
+        root,
     };
 };
 
@@ -72,7 +100,7 @@ const createConfigLoader = (options: LoadConfigOptions = {}): ConfigLoader => {
     const resolved: Map<string, Promise<ResolvedConfig>> = new Map();
 
     const load = (cwd: string): Promise<LoadedConfig> =>
-        getOrInsert(loaded, resolve(cwd), (root) => loadConfig(root, options));
+        loaded.getOrInsertComputed(resolve(cwd), (root) => loadConfig(root, options));
 
     const resolveAt = async (root: string): Promise<ResolvedConfig> => {
         const { config, root: configRoot } = await load(root);
@@ -82,7 +110,7 @@ const createConfigLoader = (options: LoadConfigOptions = {}): ConfigLoader => {
 
     return {
         load,
-        resolve: (cwd: string): Promise<ResolvedConfig> => getOrInsert(resolved, resolve(cwd), resolveAt),
+        resolve: (cwd: string): Promise<ResolvedConfig> => resolved.getOrInsertComputed(resolve(cwd), resolveAt),
     };
 };
 

package/src/schema-text.ts

@@ -40,4 +40,4 @@ const relativePathRecord = <Value extends z.ZodType>(
     recordMessage: string,
 ): z.ZodRecord<z.ZodString, Value> => z.record(relativePath(keyMessage), value, { error: recordMessage });
 
-export { fileExtension, flag, girLibrary, isGirLibrary, relativePathRecord, text, textList, textRecord, url };
+export { fileExtension, flag, girLibrary, relativePathRecord, text, textList, textRecord, url };

package/src/virtual.ts

@@ -5,11 +5,8 @@ const GTKX_CONFIG_VIRTUAL_ID = "virtual:gtkx-config";
 const RESOLVED_GTKX_CONFIG_VIRTUAL_ID = `\0${GTKX_CONFIG_VIRTUAL_ID}`;
 const METADATA_SPECIFIER = "@gtkx/jsx/metadata";
 
-const lazyElementConfig = (lazyElements: string[]): Record<string, { isLazy: boolean }> =>
-    Object.fromEntries(lazyElements.map((type) => [type, { isLazy: true }]));
-
 const renderConfigModule = (config: ResolvedConfig): string => {
-    const lazyJson = JSON.stringify(lazyElementConfig(config.lazyElements));
+    const lazyJson = JSON.stringify(Object.fromEntries(config.lazyElements.map((type) => [type, { isLazy: true }])));
 
     const behaviorImports =
         config.elements === null