@gtkx/cli 1.5.0 → 1.6.0

package/src/deploy/notices/libraries.ts

@@ -36,7 +36,8 @@ const SUMMARY = [
     "their own terms; this package does not distribute them at all.",
     "The GTKX native addon does link GLib, GObject and GIO dynamically against the copies already installed",
     "on the system, which makes the addon a work that uses those libraries, and section 6 of the LGPL asks",
-    "such a work to carry three things. This is the notice it asks for. The license itself is published at",
+    "such a work to carry a notice, the license, and the copyright notices. This is the notice it asks for,",
+    "and the license itself is published at",
     `${LGPL_URL},`,
     "and the copyright notice of each library is published with its sources, at the address listed beside",
     "it below. Linking against an installed shared library is the mechanism section 6(b) allows, so the",

package/src/deploy/settings/libraries.ts

@@ -6,15 +6,13 @@ import {
     resolveGirPath,
     resolveStore,
 } from "@gtkx/codegen";
+import { resolveFuture } from "@gtkx/config/internal";
 
 type ResolvedLibraries = {
     libraries: string[];
     minimumLibraryVersions: Record<string, string>;
 };
 
-const DEFAULT_LIBRARY = "Gtk-4.0";
-const DEFAULT_LIBRARY_PREFIX = "Gtk-";
-
 const generatedLibraries = (root: string): GeneratedLibraries | null => {
     try {
         return readGeneratedLibraries(resolveStore(root).gi.storeDir);
@@ -23,24 +21,23 @@ const generatedLibraries = (root: string): GeneratedLibraries | null => {
     }
 };
 
-const discoveredLibraries = (config: Config): string[] | null => {
+const discoveredLibraries = (config: Config, isAdwaitaDefault: boolean): string[] | null => {
     try {
-        return expandLibraries(config.libraries, resolveGirPath(config.girPath));
+        return expandLibraries(config.libraries, resolveGirPath(config.girPath), isAdwaitaDefault);
     } catch {
         return null;
     }
 };
 
 const configLibraries = (config: Config): string[] => {
+    const { isAdwaitaDefault } = resolveFuture(config.future);
     const libraries = config.libraries;
 
-    if (!Array.isArray(libraries)) {
-        return discoveredLibraries(config) ?? [DEFAULT_LIBRARY];
+    if (Array.isArray(libraries)) {
+        return expandLibraries(libraries, [], isAdwaitaDefault);
     }
 
-    return libraries.some((library) => library.startsWith(DEFAULT_LIBRARY_PREFIX))
-        ? [...libraries]
-        : [DEFAULT_LIBRARY, ...libraries];
+    return discoveredLibraries(config, isAdwaitaDefault) ?? expandLibraries(undefined, [], isAdwaitaDefault);
 };
 
 const resolveLibraries = (root: string, config: Config): ResolvedLibraries => {

package/src/deploy/tools.ts

@@ -145,11 +145,9 @@ const toolLines = (tool: DeployTool, hints: string[]): string[] => [
 const missingToolsMessage = (report: ToolReport): string => {
     const family = detectPackageFamily();
     const required = report.missingRequired.flatMap((tool) => toolLines(tool, installHints(tool.command, family)));
-    const count = report.missingRequired.length;
-    const plural = count === 1 ? "tool is" : "tools are";
 
     return [
-        `Cannot deploy: ${String(count)} required ${plural} missing.`,
+        "Cannot deploy without these tools:",
         "",
         ...required,
         "",

package/src/dev/runner-main.ts

@@ -1,4 +1,5 @@
 import { loadConfig } from "@gtkx/config";
+import { resolveFuture } from "@gtkx/config/internal";
 import { error } from "@gtkx/utils";
 import { resolve } from "node:path";
 import { DEV_ENTRY_ENV } from "./entry-env.js";
@@ -24,7 +25,7 @@ const main = async (): Promise<void> => {
 
     const { config, root } = await loadConfig(cwd, { mode: "development" });
     prepareDevLocaleDir(root, config.applicationId);
-    prepareDevSchemaDir(root, config.future?.v2ResourceImports === true);
+    prepareDevSchemaDir(root, resolveFuture(config.future).isResourceImported);
     prepareDevIconDir(root, config.applicationId, config.applicationIcon);
     const entryPath = resolve(cwd, entryArg);
     const { defaultDevRunnerDeps } = await import("./runner-deps.js");

package/src/internal/agent-rules.ts

@@ -0,0 +1,135 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { REFERENCE_PATH } from "../codegen/reference.js";
+
+type AgentRulesResult = {
+    isWritten: boolean;
+    files: string[];
+};
+
+const AGENTS_FILENAME = "AGENTS.md";
+const CLAUDE_FILENAME = "CLAUDE.md";
+const CLAUDE_CONTENTS = `@${AGENTS_FILENAME}\n`;
+const BEGIN_MARKER = "<!-- BEGIN:gtkx-agent-rules -->";
+const END_MARKER = "<!-- END:gtkx-agent-rules -->";
+const BLOCK_PATTERN = /<!-- BEGIN:gtkx-agent-rules -->[\s\S]*?<!-- END:gtkx-agent-rules -->/;
+const TOP_LEVEL_HEADING = /^# /m;
+
+const rulesBody = (heading: string): string[] => [
+    `${heading} GTKX`,
+    "",
+    "This is not the GTK you have seen before. Most GTK code in your training data is C, PyGObject, Vala or " +
+    "GJS, and almost none of it is valid here. Check the rules below against what you are about to write.",
+    "",
+    "- Children are JSX, never `.append()`, `pack_start()`, `set_child()` or `add()`.",
+    '- Signals are props: `onClicked`, not `widget.connect("clicked", ...)`.',
+    "- Props are camelCase: `marginTop`, not `margin-top` or `margin_top`.",
+    "- There is no `Gtk.Template`, no `.ui` XML, and no `GtkBuilder`. The JSX tree is the definition.",
+    "- Elements come from `@gtkx/jsx/<namespace>` and classes, enums and functions from " +
+    "`@gtkx/gi/<namespace>`. Both are generated for this project by `gtkx codegen`, not installed from npm, " +
+    "so they match the GIR libraries this project declares.",
+    "",
+    `Read \`${REFERENCE_PATH}/index.md\` before writing widget code. It is generated from this project's own ` +
+    "GIR libraries and is the authority on which props, signals and methods exist. Do not infer a prop from " +
+    "another toolkit, from a C function name, or from a similar element.",
+    "",
+    "| Command | What it does |",
+    "| --- | --- |",
+    "| `gtkx dev` | Run the app with fast refresh |",
+    "| `gtkx codegen` | Regenerate bindings and this reference |",
+    "| `tsc --noEmit` | Typecheck |",
+    "| `vitest run` | Run the tests |",
+    "",
+    "Never call UI work done without looking at the running app. With `gtkx dev` up, the gtkx MCP server " +
+    "exposes the live widget tree, queries, clicks and screenshots; use them to confirm the change landed.",
+    "",
+    "This block is written by `gtkx codegen`. Anything outside the markers is yours and is left alone, and " +
+    "committing the block with your work keeps the tree clean.",
+];
+
+const renderBlock = (heading: string): string =>
+    [BEGIN_MARKER, "", ...rulesBody(heading), "", END_MARKER].join("\n");
+
+const headingFor = (contents: string): string => (TOP_LEVEL_HEADING.test(contents) ? "##" : "#");
+const withTrailingNewline = (contents: string): string => (contents.endsWith("\n") ? contents : `${contents}\n`);
+
+const appendBlock = (contents: string, block: string): string => {
+    if (contents.trim() === "") {
+        return `${block}\n`;
+    }
+
+    return `${withTrailingNewline(contents)}\n${block}\n`;
+};
+
+const replaceBlock = (contents: string, block: string): string => {
+    const match = BLOCK_PATTERN.exec(contents);
+
+    if (match === null) {
+        return appendBlock(contents, block);
+    }
+
+    return contents.slice(0, match.index) + block + contents.slice(match.index + match[0].length);
+};
+
+const nextContents = (contents: string): string => {
+    const heading = headingFor(contents.replace(BLOCK_PATTERN, ""));
+
+    return replaceBlock(contents, renderBlock(heading));
+};
+
+const errorCode = (error: unknown): string | undefined =>
+    error instanceof Error ? (error as NodeJS.ErrnoException).code : undefined;
+
+const readOrUndefined = (path: string): string | undefined => {
+    try {
+        return readFileSync(path, "utf8");
+    } catch (error) {
+        if (errorCode(error) === "ENOENT") {
+            return undefined;
+        }
+
+        throw error;
+    }
+};
+
+const hasWritten = (path: string, contents: string): boolean => {
+    if (readOrUndefined(path) === contents) {
+        return false;
+    }
+
+    writeFileSync(path, contents);
+
+    return true;
+};
+
+const hasWrittenClaudeImport = (root: string): boolean => {
+    try {
+        writeFileSync(join(root, CLAUDE_FILENAME), CLAUDE_CONTENTS, { flag: "wx" });
+
+        return true;
+    } catch (error) {
+        if (errorCode(error) === "EEXIST") {
+            return false;
+        }
+
+        throw error;
+    }
+};
+
+const upsertAgentRules = (root: string): AgentRulesResult => {
+    const agentsPath = join(root, AGENTS_FILENAME);
+    const existing = readOrUndefined(agentsPath) ?? "";
+    const files: string[] = [];
+
+    if (hasWritten(agentsPath, nextContents(existing))) {
+        files.push(AGENTS_FILENAME);
+    }
+
+    if (hasWrittenClaudeImport(root)) {
+        files.push(CLAUDE_FILENAME);
+    }
+
+    return { isWritten: files.length > 0, files };
+};
+
+export { upsertAgentRules };

package/src/internal/docs-elements.ts

@@ -0,0 +1,21 @@
+import { type ElementProps, type OmittedProps, readBuiltinElements, resolveStore } from "@gtkx/codegen";
+import { existsSync } from "node:fs";
+
+type DocsElements = {
+    props: ElementProps;
+    omittedProps: OmittedProps;
+};
+
+const resolveDocsElements = async (cwd: string): Promise<DocsElements> => {
+    const { gi, reactSubexports } = resolveStore(cwd);
+
+    if (!existsSync(gi.storeDir)) {
+        return { props: {}, omittedProps: {} };
+    }
+
+    const { props, omittedProps } = await readBuiltinElements(reactSubexports, gi.storeDir);
+
+    return { props, omittedProps };
+};
+
+export { resolveDocsElements };

package/src/internal/source-imports.ts

@@ -24,8 +24,6 @@ const SOURCE_LANGUAGES: Map<string, SourceLanguage> = new Map([
 ]);
 
 const EXCLUDED_DIRECTORIES: Set<string> = new Set([
-    ".git",
-    ".gtkx",
     "build",
     "coverage",
     "dist",
@@ -41,11 +39,13 @@ const sourceLanguage = (path: string): SourceLanguage | undefined => {
     return SOURCE_LANGUAGES.get(extname(path).toLowerCase());
 };
 
+const isWalkableDirectory = (name: string): boolean => !name.startsWith(".") && !EXCLUDED_DIRECTORIES.has(name);
+
 const collectSourceEntry = (dir: string, entry: Dirent, found: string[]): void => {
     const path = join(dir, entry.name);
 
     if (entry.isDirectory()) {
-        if (!EXCLUDED_DIRECTORIES.has(entry.name)) {
+        if (isWalkableDirectory(entry.name)) {
             sourceFilesIn(path, found);
         }
 

package/src/mcp/client-config.ts

@@ -0,0 +1,130 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+type ClientName = "claude" | "cursor" | "vscode" | "opencode" | "codex";
+type ServerEntry = Record<string, unknown>;
+
+type Client = {
+    name: ClientName;
+    file: string;
+    key: string;
+    entry: ServerEntry;
+};
+
+type ClientResult =
+    | { kind: "written"; path: string; isCreated: boolean } |
+    { kind: "manual"; path: string; snippet: string };
+
+const SERVER_NAME = "gtkx";
+const COMMAND = "npx";
+const ARGS = ["gtkx", "mcp"];
+const CODEX_PATH = "~/.codex/config.toml";
+
+const CODEX_SNIPPET = [
+    `[mcp_servers.${SERVER_NAME}]`,
+    `command = ${JSON.stringify(COMMAND)}`,
+    `args = ${JSON.stringify(ARGS)}`,
+].join("\n");
+
+const CLIENTS: Client[] = [
+    {
+        name: "claude",
+        file: ".mcp.json",
+        key: "mcpServers",
+        entry: { command: COMMAND, args: ARGS },
+    },
+    {
+        name: "cursor",
+        file: join(".cursor", "mcp.json"),
+        key: "mcpServers",
+        entry: { command: COMMAND, args: ARGS },
+    },
+    {
+        name: "vscode",
+        file: join(".vscode", "mcp.json"),
+        key: "servers",
+        entry: { type: "stdio", command: COMMAND, args: ARGS },
+    },
+    {
+        name: "opencode",
+        file: "opencode.json",
+        key: "mcp",
+        entry: { type: "local", command: [COMMAND, ...ARGS], enabled: true },
+    },
+    {
+        name: "codex",
+        file: CODEX_PATH,
+        key: "mcp_servers",
+        entry: {},
+    },
+];
+
+const CLIENT_NAMES: Set<string> = new Set(CLIENTS.map((client) => client.name));
+
+const isClientName = (value: string): value is ClientName => CLIENT_NAMES.has(value);
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+    typeof value === "object" && value !== null && !Array.isArray(value);
+
+const readOrUndefined = (path: string): string | undefined => {
+    try {
+        return readFileSync(path, "utf8");
+    } catch (error) {
+        if (error instanceof Error && (error as NodeJS.ErrnoException).code === "ENOENT") {
+            return undefined;
+        }
+
+        throw error;
+    }
+};
+
+const readJson = (path: string): Record<string, unknown> | undefined => {
+    const source = readOrUndefined(path);
+
+    if (source === undefined) {
+        return undefined;
+    }
+
+    const parsed: unknown = JSON.parse(source);
+
+    if (!isRecord(parsed)) {
+        throw new Error(`Refusing to edit ${path}: its contents are not a JSON object.`);
+    }
+
+    return parsed;
+};
+
+const getSection = (document: Record<string, unknown>, key: string): Record<string, unknown> => {
+    const section = document[key];
+
+    return isRecord(section) ? section : {};
+};
+
+const clientFor = (name: ClientName): Client => {
+    const client = CLIENTS.find((candidate) => candidate.name === name);
+
+    if (client === undefined) {
+        throw new Error(`Unknown MCP client "${name}".`);
+    }
+
+    return client;
+};
+
+const writeClientConfig = (root: string, name: ClientName): ClientResult => {
+    const client = clientFor(name);
+
+    if (name === "codex") {
+        return { kind: "manual", path: CODEX_PATH, snippet: CODEX_SNIPPET };
+    }
+
+    const path = join(root, client.file);
+    const existing = readJson(path);
+    const document = existing ?? {};
+    const section = { ...getSection(document, client.key), [SERVER_NAME]: client.entry };
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify({ ...document, [client.key]: section }, null, 4)}\n`);
+
+    return { kind: "written", path, isCreated: existing === undefined };
+};
+
+export { CLIENTS, isClientName, writeClientConfig, type ClientName, type ClientResult };