@gtkx/cli 1.4.0 → 1.6.0

package/src/builder.ts

@@ -10,6 +10,7 @@ import { gtkxWorker } from "./vite-plugins/worker.js";
 
 type BuildOptions = {
     entry: string;
+    shouldPreserveI18nMetadata?: boolean | undefined;
     vite?: InlineConfig | undefined;
 };
 
@@ -32,14 +33,14 @@ const buildDefaults: InlineConfig = {
 };
 
 const build = async (options: BuildOptions): Promise<string> => {
-    const { entry, vite: viteConfig } = options;
+    const { entry, shouldPreserveI18nMetadata = true, vite: viteConfig } = options;
     const root = viteConfig?.root ?? process.cwd();
     const assetsDir = viteConfig?.build?.assetsDir ?? DEFAULT_ASSETS_DIR;
     const buildManifest = createBuildManifestCollector();
 
     const forced: InlineConfig = {
         plugins: [
-            ...gtkxVitePlugins(BUILD_MODE, undefined, buildManifest),
+            ...gtkxVitePlugins(BUILD_MODE, entry, buildManifest, shouldPreserveI18nMetadata),
             gtkxWorker(),
             gtkxNative(root),
             gtkxBuildManifest(root, buildManifest),

package/src/cli.ts

@@ -38,6 +38,11 @@ const main = defineCommand({
 
             return withErrorBoundary(docs);
         },
+        mcp: async () => {
+            const { mcp } = await import("./commands/mcp.js");
+
+            return withErrorBoundary(mcp);
+        },
         create: async () => {
             const { scaffoldCommand } = await import("create-gtkx");
 

package/src/codegen/freshness.ts

@@ -1,5 +1,6 @@
 import type { Config } from "@gtkx/config";
 import { resolveGirPath, resolveLibraries } from "@gtkx/codegen";
+import { resolveFuture } from "@gtkx/config/internal";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { type CodegenStore, resolveCodegenStore } from "./store-resolver.js";
@@ -14,7 +15,7 @@ const REACT_GENERATED_MODULES: string[] = ["index.js", "metadata.js", join("gtk"
 
 const resolveCodegenInputs = (cwd: string, config: Config): CodegenInputs => {
     const girPath = resolveGirPath(config.girPath);
-    const libraries = resolveLibraries(config.libraries, girPath);
+    const libraries = resolveLibraries(config.libraries, girPath, resolveFuture(config.future).isAdwaitaDefault);
     const store = resolveCodegenStore(cwd);
 
     return { girPath, libraries, store };

package/src/codegen/reference.ts

@@ -0,0 +1,59 @@
+import type { Config } from "@gtkx/config";
+import { mergeOmittedProps } from "@gtkx/codegen";
+import { writeDocs } from "@gtkx/codegen/internal";
+import { isAgentReferenceEnabled, resolveOmittedProps } from "@gtkx/config/internal";
+import { join } from "node:path";
+import { resolveDocsElements } from "../internal/docs-elements.js";
+
+type WriteReferenceOptions = {
+    root: string;
+    config: Config;
+    girPath: string[];
+    libraries: string[];
+    isForced?: boolean;
+};
+
+type ReferenceResult = {
+    isRegenerated: boolean;
+    elements: number;
+    namespaces: number;
+};
+
+const REFERENCE_PATH = ".gtkx/reference";
+const SKIPPED: ReferenceResult = { isRegenerated: false, elements: 0, namespaces: 0 };
+
+const resolveReferenceDir = (root: string): string => join(root, ".gtkx", "reference");
+
+const writeReference = async (options: WriteReferenceOptions): Promise<ReferenceResult> => {
+    const { root, config, girPath, libraries } = options;
+
+    if (!isAgentReferenceEnabled(config) || girPath.length === 0 || libraries.length === 0) {
+        return SKIPPED;
+    }
+
+    const builtin = await resolveDocsElements(root);
+
+    const { isRegenerated, namespaces } = writeDocs({
+        libraries,
+        girPath,
+        outDir: resolveReferenceDir(root),
+        basePath: REFERENCE_PATH,
+        linkStyle: "file",
+        props: builtin.props,
+        omittedProps: mergeOmittedProps(builtin.omittedProps, resolveOmittedProps(config.elements)),
+        isForced: options.isForced === true,
+        isByteArrayTyped: config.future?.v2ByteArrays === true,
+        isValueUnwrapped: config.future?.v2ValueReturns === true,
+        isFinishTrimmed: config.future?.v2FinishResults === true,
+        isInoutInPlace: config.future?.v2InoutReturns === true,
+        isTreeShaken: config.future?.v2TreeShaking === true,
+    });
+
+    return {
+        isRegenerated,
+        elements: namespaces.reduce((total, namespace) => total + namespace.elements.length, 0),
+        namespaces: namespaces.length,
+    };
+};
+
+export { REFERENCE_PATH, writeReference, type ReferenceResult };

package/src/codegen/report.ts

@@ -1,8 +1,9 @@
 import type { RunCodegenResult } from "./run-codegen.js";
+import { REFERENCE_PATH } from "./reference.js";
 
 const PREFIX = "codegen: ";
 
-const formatCodegenResult = (result: RunCodegenResult, totalMs: number): string[] => {
+const contextDetails = (result: RunCodegenResult): string[] => {
     const details: string[] = [];
 
     if (result.configFile) {
@@ -21,10 +22,24 @@ const formatCodegenResult = (result: RunCodegenResult, totalMs: number): string[
         details.push(`future=${result.future.join(", ")}`);
     }
 
-    details.push(
+    return details;
+};
+
+const referenceDetails = (result: RunCodegenResult): string[] => {
+    if (result.reference?.isRegenerated !== true) {
+        return [];
+    }
+
+    return [`${String(result.reference.elements)} reference pages in ${REFERENCE_PATH}`];
+};
+
+const formatCodegenResult = (result: RunCodegenResult, totalMs: number): string[] => {
+    const details = [
+        ...contextDetails(result),
         `${String(result.namespaces)} namespaces, ${String(result.intrinsicElements)} intrinsic elements ` +
         `in ${String(result.duration)}ms (total ${String(totalMs)}ms)`,
-    );
+        ...referenceDetails(result),
+    ];
 
     return details.map((detail) => PREFIX + detail);
 };

package/src/codegen/run-codegen.ts

@@ -1,18 +1,33 @@
 import { runCodegen as runCodegenCore } from "@gtkx/codegen";
-import { getShadowingStorePaths, sweepProjectStaging } from "@gtkx/codegen/internal";
+import {
+    getShadowingStorePaths,
+    LIBRARIES_WILDCARD,
+    redundantLibraries,
+    sweepProjectStaging,
+} from "@gtkx/codegen/internal";
 import { type Config, loadConfig } from "@gtkx/config";
 import {
+    isAgentRulesEnabled,
+    type ResolvedFuture,
     resolveElementComponents,
     resolveElementProps,
+    resolveFuture,
     resolveLazyElements,
     resolveOmittedProps,
+    unknownFutureKeys,
 } from "@gtkx/config/internal";
 import { info, warn } from "@gtkx/utils";
-import { rmSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { resolveCatalogProject, synchronizeCatalogs } from "../i18n/catalogs.js";
+import { extractSourceCatalog } from "../i18n/source-messages.js";
+import { emitI18nTypes } from "../i18n/types.js";
+import { upsertAgentRules } from "../internal/agent-rules.js";
 import { resolveDataDir } from "../internal/data-dir.js";
+import { discoverSourceFiles } from "../internal/source-imports.js";
 import { emitSchemaEnv } from "../settings/schema.js";
 import { type CodegenInputs, isCodegenStale, resolveCodegenInputs } from "./freshness.js";
+import { type ReferenceResult, writeReference } from "./reference.js";
 import { type CodegenContext, type CodegenStore, resolveCodegenContext } from "./store-resolver.js";
 
 type RunCodegenOptions = {
@@ -21,6 +36,7 @@ type RunCodegenOptions = {
     isForced?: boolean;
     inputs?: CodegenInputs;
     resolved?: LoadedConfig;
+    shouldPreserveI18nMetadata?: boolean | undefined;
 };
 
 type LoadedConfig = {
@@ -38,6 +54,7 @@ type RunCodegenResult = {
     configFile?: string | undefined;
     libraries?: string[] | undefined;
     future?: string[] | undefined;
+    reference?: ReferenceResult | undefined;
 };
 
 type CodegenOptionsInput = {
@@ -45,20 +62,23 @@ type CodegenOptionsInput = {
     libraries: string[];
     girPath: string[];
     elements: Config["elements"];
-    isByteArrayTyped: boolean;
-    isValueUnwrapped: boolean;
-    isFinishTrimmed: boolean;
-    isInoutInPlace: boolean;
+    future: ResolvedFuture;
 };
 
 type PreparedCodegen = CodegenInputs & { isForced: boolean };
-type EnsureGeneratedOptions = { shouldAnnounce?: boolean; mode?: string };
+
+type EnsureGeneratedOptions = {
+    shouldAnnounce?: boolean;
+    mode?: string;
+    shouldPreserveI18nMetadata?: boolean | undefined;
+};
 
 type RunOptionsInput = {
     root: string;
     mode: string | undefined;
     inputs: CodegenInputs | null;
     resolved: LoadedConfig;
+    shouldPreserveI18nMetadata: boolean | undefined;
 };
 
 const GIR_PATH_MISSING_MESSAGE =
@@ -77,13 +97,14 @@ const removeShadowingStores = (cwd: string): void => {
     removeStores(getShadowingStorePaths(cwd));
 };
 
-const codegenOptions = ({ store, libraries, girPath, elements, ...future }: CodegenOptionsInput) => ({
+const codegenOptions = ({ store, libraries, girPath, elements, future }: CodegenOptionsInput) => ({
     libraries,
     girPath,
     isByteArrayTyped: future.isByteArrayTyped,
     isValueUnwrapped: future.isValueUnwrapped,
     isFinishTrimmed: future.isFinishTrimmed,
     isInoutInPlace: future.isInoutInPlace,
+    isTreeShaken: future.isTreeShaken,
     gi: {
         storeDir: store.giStoreDir,
         linkDir: store.giLinkDir,
@@ -104,16 +125,19 @@ const codegenOptions = ({ store, libraries, girPath, elements, ...future }: Code
     userOmittedProps: resolveOmittedProps(elements),
 });
 
-const enabledFutureFlags = (config: Config): string[] =>
-    Object.entries(config.future ?? {})
-        .filter(([, value]) => value === true)
+const enabledFutureFlags = (config: Config): string[] => {
+    const unknown: Set<string> = new Set(unknownFutureKeys(config.future));
+
+    return Object.entries(config.future ?? {})
+        .filter(([name, value]) => value === true && !unknown.has(name))
         .map(([name]) => name);
+};
 
-const disabledCodegenResult = (configFile: string): RunCodegenResult => ({
+const disabledCodegenResult = (configFile: string, notices: string[]): RunCodegenResult => ({
     isRegenerated: false,
     namespaces: 0,
     intrinsicElements: 0,
-    notices: [],
+    notices,
     duration: 0,
     girPath: [],
     configFile,
@@ -126,6 +150,46 @@ const warnNotices = (notices: string[]): void => {
     }
 };
 
+const unknownFutureNotice = (keys: string[]): string[] => {
+    if (keys.length === 0) {
+        return [];
+    }
+
+    return [
+        `gtkx.config.ts: \`future\` has no ${keys.join(", ")} flag, so the key is ignored. Check it against ` +
+        "the flags the configuration guide lists.",
+    ];
+};
+
+const redundantLibraryNotice = (entries: string[]): string[] => {
+    if (entries.length === 0) {
+        return [];
+    }
+
+    return [
+        `gtkx.config.ts: \`future.v2DefaultLibraries\` binds ${entries.join(", ")} on its own, so naming them ` +
+        "in `libraries` changes nothing. Drop them; naming them becomes a configuration error in GTKX 2.0.",
+    ];
+};
+
+const wildcardLibrariesNotice = (libraries: Config["libraries"]): string[] => {
+    if (libraries !== LIBRARIES_WILDCARD) {
+        return [];
+    }
+
+    return [
+        'gtkx.config.ts: `libraries: "*"` binds whatever the build host happens to have installed, so the ' +
+        "store changes with the machine. Instead, list the libraries the project needs; the wildcard is " +
+        "removed in GTKX 2.0.",
+    ];
+};
+
+const configNotices = (config: Config, future: ResolvedFuture): string[] => [
+    ...unknownFutureNotice(unknownFutureKeys(config.future)),
+    ...wildcardLibrariesNotice(config.libraries),
+    ...redundantLibraryNotice(redundantLibraries(config.libraries, future.isAdwaitaDefault)),
+];
+
 const regeneratedStorePaths = (store: CodegenStore): string[] => {
     if (store.react === null) {
         return [store.giStoreDir, store.giLinkDir];
@@ -156,12 +220,16 @@ const prepareCodegen = (options: RunCodegenOptions, cwd: string, config: Config)
 const runCodegen = async (options: RunCodegenOptions = {}): Promise<RunCodegenResult> => {
     const cwd = options.cwd ?? process.cwd();
     const { config, configFile } = await resolveLoadedConfig(options, cwd);
-    syncSchemaEnv(cwd, config.future?.v2ResourceImports === true);
+    const future = resolveFuture(config.future);
+    const configured = configNotices(config, future);
+    warnNotices(configured);
+    await syncI18n(cwd, config.applicationId, options.shouldPreserveI18nMetadata);
+    syncSchemaEnv(cwd, future.isResourceImported);
 
     if (config.codegen === false) {
         removeShadowingStores(cwd);
 
-        return disabledCodegenResult(configFile);
+        return disabledCodegenResult(configFile, configured);
     }
 
     const { girPath, libraries, store, isForced } = prepareCodegen(options, cwd, config);
@@ -171,34 +239,55 @@ const runCodegen = async (options: RunCodegenOptions = {}): Promise<RunCodegenRe
     }
 
     const result = await runCodegenCore({
-        ...codegenOptions({
-            store,
-            libraries,
-            girPath,
-            elements: config.elements,
-            isByteArrayTyped: config.future?.v2ByteArrays === true,
-            isValueUnwrapped: config.future?.v2ValueReturns === true,
-            isFinishTrimmed: config.future?.v2FinishResults === true,
-            isInoutInPlace: config.future?.v2InoutReturns === true,
-        }),
+        ...codegenOptions({ store, libraries, girPath, elements: config.elements, future }),
         isForced,
     });
 
     warnNotices(result.notices);
+    const notices = [...configured, ...result.notices];
+    const reference = await writeReference({ root: cwd, config, girPath, libraries, isForced });
+    syncAgentRules(cwd, config);
 
     return {
         isRegenerated: result.isRegenerated,
         namespaces: result.namespaces,
         intrinsicElements: result.intrinsicElements,
-        notices: result.notices,
+        notices,
         duration: result.duration,
         girPath,
         configFile,
         libraries,
         future: enabledFutureFlags(config),
+        reference,
     };
 };
 
+const syncAgentRules = (root: string, config: Config): void => {
+    if (isAgentRulesEnabled(config)) {
+        upsertAgentRules(root);
+    }
+};
+
+const syncI18n = async (
+    root: string,
+    applicationId: string,
+    shouldPreserveMetadataMessages = true,
+): Promise<void> => {
+    const project = resolveCatalogProject(root, applicationId);
+
+    if (project === null) {
+        emitI18nTypes(root, [], false);
+
+        return;
+    }
+
+    const srcDir = join(root, "src");
+    const sourceFiles = discoverSourceFiles(existsSync(srcDir) ? srcDir : root);
+    const catalog = await extractSourceCatalog(project, sourceFiles, shouldPreserveMetadataMessages);
+    synchronizeCatalogs(project);
+    emitI18nTypes(root, catalog.messages);
+};
+
 const isCodegenDisabled = async (cwd: string, mode?: string): Promise<boolean> => {
     try {
         const { config } = await loadConfig(cwd, { mode });
@@ -232,12 +321,18 @@ const maybeAnnounceStale = (shouldAnnounce: boolean | undefined, inputs: Codegen
     }
 };
 
-const getRunOptions = ({ root, mode, inputs, resolved }: RunOptionsInput): RunCodegenOptions => {
+const getRunOptions = ({
+    root,
+    mode,
+    inputs,
+    resolved,
+    shouldPreserveI18nMetadata,
+}: RunOptionsInput): RunCodegenOptions => {
     if (inputs === null) {
-        return { cwd: root, mode, resolved };
+        return { cwd: root, mode, resolved, shouldPreserveI18nMetadata };
     }
 
-    return { cwd: root, mode, inputs, resolved };
+    return { cwd: root, mode, inputs, resolved, shouldPreserveI18nMetadata };
 };
 
 const isPreflightSkipped = (options: EnsureGeneratedOptions): boolean =>
@@ -250,6 +345,7 @@ const generate = async (context: CodegenContext, options: EnsureGeneratedOptions
             cwd: context.root,
             mode: options.mode,
             resolved: { config: context.config, configFile: context.configFile },
+            shouldPreserveI18nMetadata: options.shouldPreserveI18nMetadata,
         });
 
         return result.isRegenerated;
@@ -258,7 +354,14 @@ const generate = async (context: CodegenContext, options: EnsureGeneratedOptions
     const inputs = resolveInputsOrNull(context.root, context.config);
     maybeAnnounceStale(options.shouldAnnounce, inputs);
     const resolved = { config: context.config, configFile: context.configFile };
-    const result = await runCodegen(getRunOptions({ root: context.root, mode: options.mode, inputs, resolved }));
+
+    const result = await runCodegen(getRunOptions({
+        root: context.root,
+        mode: options.mode,
+        inputs,
+        resolved,
+        shouldPreserveI18nMetadata: options.shouldPreserveI18nMetadata,
+    }));
 
     return result.isRegenerated;
 };

package/src/commands/codegen.ts

@@ -12,7 +12,7 @@ const FORCED_WHILE_DISABLED_MESSAGE =
 const codegen = defineCommand({
     meta: {
         name: "codegen",
-        description: "Generate TypeScript bindings for the GIR libraries declared in gtkx.config.ts",
+        description: "Generate project bindings, translation catalogs, and TypeScript declarations",
     },
     args: {
         force: {

package/src/commands/docs.ts

@@ -1,19 +1,11 @@
-import {
-    type ElementProps,
-    mergeOmittedProps,
-    type OmittedProps,
-    readBuiltinElements,
-    resolveGirPath,
-    resolveLibraries,
-    resolveStore,
-} from "@gtkx/codegen";
+import { mergeOmittedProps, resolveGirPath, resolveLibraries } from "@gtkx/codegen";
 import { writeDocs } from "@gtkx/codegen/internal";
 import { loadConfig } from "@gtkx/config";
-import { resolveOmittedProps } from "@gtkx/config/internal";
+import { resolveFuture, resolveOmittedProps } from "@gtkx/config/internal";
 import { info } from "@gtkx/utils";
 import { defineCommand } from "citty";
-import { existsSync } from "node:fs";
 import { isAbsolute, relative, resolve, sep } from "node:path";
+import { resolveDocsElements } from "../internal/docs-elements.js";
 import { cwdArg, resolveCwd } from "../internal/entry-arg.js";
 
 const docs = defineCommand({
@@ -65,7 +57,8 @@ const docs = defineCommand({
             );
         }
 
-        const libraries = resolveLibraries(config.libraries, girPath);
+        const future = resolveFuture(config.future);
+        const libraries = resolveLibraries(config.libraries, girPath, future.isAdwaitaDefault);
         const startedAt = Date.now();
         const outDir = resolveOutDir(cwd, args.out);
         const builtin = await resolveDocsElements(cwd);
@@ -78,10 +71,11 @@ const docs = defineCommand({
             props: builtin.props,
             omittedProps: mergeOmittedProps(builtin.omittedProps, resolveOmittedProps(config.elements)),
             isForced: args.force,
-            isByteArrayTyped: config.future?.v2ByteArrays === true,
-            isValueUnwrapped: config.future?.v2ValueReturns === true,
-            isFinishTrimmed: config.future?.v2FinishResults === true,
-            isInoutInPlace: config.future?.v2InoutReturns === true,
+            isByteArrayTyped: future.isByteArrayTyped,
+            isValueUnwrapped: future.isValueUnwrapped,
+            isFinishTrimmed: future.isFinishTrimmed,
+            isInoutInPlace: future.isInoutInPlace,
+            isTreeShaken: future.isTreeShaken,
         });
 
         if (!isRegenerated) {
@@ -130,16 +124,4 @@ const resolveOutDir = (cwd: string, out: string): string => {
     );
 };
 
-const resolveDocsElements = async (cwd: string): Promise<{ props: ElementProps; omittedProps: OmittedProps }> => {
-    const { gi, reactSubexports } = resolveStore(cwd);
-
-    if (!existsSync(gi.storeDir)) {
-        return { props: {}, omittedProps: {} };
-    }
-
-    const { props, omittedProps } = await readBuiltinElements(reactSubexports, gi.storeDir);
-
-    return { props, omittedProps };
-};
-
 export { docs };

package/src/commands/mcp.ts

@@ -0,0 +1,81 @@
+import { info } from "@gtkx/utils";
+import { defineCommand } from "citty";
+import { cwdArg, resolveCwd } from "../internal/entry-arg.js";
+import { type ClientName, type ClientResult, CLIENTS, isClientName, writeClientConfig } from "../mcp/client-config.js";
+
+const clientList = CLIENTS.map((client) => client.name).join(", ");
+
+const init = defineCommand({
+    meta: {
+        name: "init",
+        description: "Write the gtkx MCP server into an editor's configuration file",
+    },
+    args: {
+        client: {
+            type: "string",
+            description: `Which editor to configure: one of ${clientList}`,
+            required: true,
+        },
+        ...cwdArg,
+    },
+    run({ args }) {
+        const cwd = resolveCwd(args);
+        const name = args.client;
+
+        if (!isClientName(name)) {
+            throw new Error(`Unknown --client "${name}". Pass one of ${clientList}.`);
+        }
+
+        report(name, writeClientConfig(cwd, name));
+    },
+});
+
+const mcp = defineCommand({
+    meta: {
+        name: "mcp",
+        description: "Run the MCP server that exposes this project's running app and generated API reference",
+    },
+    args: {
+        tools: {
+            type: "string",
+            description:
+                "Comma-separated tool name patterns to register, `*` matching any run of characters and a " +
+                "leading `!` excluding. Overrides `mcp.tools` in gtkx.config.ts",
+        },
+        "read-only": {
+            type: "boolean",
+            description: "Register only the tools that read state, leaving out the ones that drive the app",
+        },
+        ...cwdArg,
+    },
+    subCommands: { init },
+    async run({ args }) {
+        const { runMcpServer } = await import("@gtkx/mcp/server");
+
+        await runMcpServer({
+            cwd: resolveCwd(args),
+            ...(args.tools !== undefined && { tools: splitPatterns(args.tools) }),
+            ...(args["read-only"] !== undefined && { isReadOnly: args["read-only"] }),
+        });
+    },
+});
+
+const splitPatterns = (value: string): string[] =>
+    value.split(",").map((pattern) => pattern.trim()).filter((pattern) => pattern.length > 0);
+
+const report = (name: ClientName, result: ClientResult): void => {
+    if (result.kind === "manual") {
+        info(`mcp: ${name} keeps its servers in ${result.path}, which is outside this project. Add:`);
+
+        for (const line of result.snippet.split("\n")) {
+            info(`mcp:   ${line}`);
+        }
+
+        return;
+    }
+
+    info(`mcp: ${result.isCreated ? "created" : "updated"} ${result.path} for ${name}`);
+    info("mcp: restart the editor for it to pick the server up");
+};
+
+export { mcp };