@gtkx/cli 2.0.0-beta.1 → 2.0.0-beta.10

package/src/internal/agent-rules.ts

@@ -18,9 +18,13 @@ 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.",
+    "GTKX applications are Adwaita-first, with GTK4 underneath. Most GNOME UI 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.",
     "",
+    "- Start application shells with `AdwApplication` and `AdwApplicationWindow`. Freeform windows normally use " +
+    "`AdwToolbarView` and `AdwHeaderBar`; navigation containers own their Adwaita chrome. Prefer Adwaita for " +
+    "structure, navigation, dialogs, rows, and adaptive patterns; use GTK4 for lower-level primitives.",
     "- 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`.",
@@ -37,6 +41,7 @@ const rulesBody = (heading: string): string[] => [
     "| --- | --- |",
     "| `gtkx dev` | Run the app with fast refresh |",
     "| `gtkx codegen` | Regenerate bindings and this reference |",
+    "| `gtkx cleanup` | Remove stale headless runtime and compile cache directories |",
     "| `tsc --noEmit` | Typecheck |",
     "| `vitest run` | Run the tests |",
     "",

package/src/internal/banner.ts

@@ -1,13 +1,34 @@
 import type { Rollup } from "vite";
+import { posix } from "node:path";
 
-const prependBanner = (options: Rollup.OutputOptions, banner: string): Rollup.OutputOptions => {
+type Banner = string | Rollup.AddonFunction;
+
+const renderBanner = async (banner: Banner, chunk: Rollup.RenderedChunk): Promise<string> =>
+    typeof banner === "function" ? banner(chunk) : banner;
+
+const prependBanner = (options: Rollup.OutputOptions, banner: Banner): Rollup.OutputOptions => {
     const existing = options.banner;
 
-    if (typeof existing === "function") {
-        return { ...options, banner: async (chunk) => `${banner}\n${await existing(chunk)}` };
-    }
+    return {
+        ...options,
+        banner: async (chunk) => {
+            const prefix = await renderBanner(banner, chunk);
+            const suffix = existing === undefined ? "" : await renderBanner(existing, chunk);
+
+            if (prefix.length === 0) {
+                return suffix;
+            }
+
+            return suffix.length === 0 ? prefix : `${prefix}\n${suffix}`;
+        },
+    };
+};
+
+const outputRootUrlExpression = (chunk: Rollup.RenderedChunk): string => {
+    const relativeRoot = posix.relative(posix.dirname(chunk.fileName), ".");
+    const specifier = relativeRoot.length === 0 ? "./" : `${relativeRoot}/`;
 
-    return { ...options, banner: existing ? `${banner}\n${existing}` : banner };
+    return `decodeURIComponent(new URL(${JSON.stringify(specifier)}, import.meta.url).pathname)`;
 };
 
-export { prependBanner };
+export { outputRootUrlExpression, prependBanner };

package/src/internal/build-manifest.ts

@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+
 type RecordedPackage = {
     name: string;
     version: string | null;
@@ -7,6 +9,8 @@ type RecordedPackage = {
 type BuildManifest = {
     generator: typeof BUILD_MANIFEST_GENERATOR;
     formatVersion: typeof BUILD_MANIFEST_FORMAT_VERSION;
+    configFile: string;
+    configDigest: string;
     schemas: string[];
     packages: RecordedPackage[];
 };
@@ -17,7 +21,26 @@ type BuildManifestCollector = {
 
 const BUILD_MANIFEST_FILENAME = "gtkx-schemas.json";
 const BUILD_MANIFEST_GENERATOR = "gtkx-build";
-const BUILD_MANIFEST_FORMAT_VERSION = 1;
+const BUILD_MANIFEST_FORMAT_VERSION = 2;
+
+const canonicalConfig = (value: unknown): unknown => {
+    if (Array.isArray(value)) {
+        return value.map((entry) => canonicalConfig(entry));
+    }
+
+    if (typeof value !== "object" || value === null) {
+        return value;
+    }
+
+    return Object.fromEntries(
+        Object.entries(value)
+            .toSorted(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => [key, canonicalConfig(entry)]),
+    );
+};
+
+const configDigest = (config: unknown): string =>
+    createHash("sha256").update(JSON.stringify(canonicalConfig(config))).digest("hex");
 
 const createBuildManifestCollector = (): BuildManifestCollector => ({ schemas: [] });
 
@@ -25,6 +48,7 @@ export {
     BUILD_MANIFEST_FILENAME,
     BUILD_MANIFEST_FORMAT_VERSION,
     BUILD_MANIFEST_GENERATOR,
+    configDigest,
     createBuildManifestCollector,
     type BuildManifest,
     type BuildManifestCollector,

package/src/internal/build-output.ts

@@ -0,0 +1,171 @@
+import { isPathInside, isRecord } from "@gtkx/utils";
+import { lstatSync, readdirSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import {
+    BUILD_MANIFEST_FILENAME,
+    BUILD_MANIFEST_GENERATOR,
+} from "./build-manifest.js";
+import {
+    type OutputDirectoryTransaction,
+    prepareOutputDirectory,
+    readRegularFile,
+} from "./output-directory.js";
+
+const DEFAULT_BUILD_OUT_DIR = "dist";
+const PRESERVED_BUILD_ENTRIES: ReadonlySet<string> = new Set([".git"]);
+
+type PreparedBuildOutDir = Disposable & { commit: () => void; path: string };
+
+const hasSymlinkComponent = (root: string, target: string): boolean => {
+    let current = root;
+
+    for (const segment of relative(root, target).split(sep)) {
+        current = join(current, segment);
+
+        if (lstatSync(current, { throwIfNoEntry: false })?.isSymbolicLink() === true) {
+            return true;
+        }
+    }
+
+    return false;
+};
+
+const isGtkxBuildDirectory = (path: string): boolean => {
+    const manifest = join(path, BUILD_MANIFEST_FILENAME);
+    const contents = readRegularFile(manifest);
+
+    try {
+        const parsed: unknown = contents === null ? null : JSON.parse(contents);
+
+        return isRecord(parsed) && parsed.generator === BUILD_MANIFEST_GENERATOR;
+    } catch {
+        return false;
+    }
+};
+
+const isReusableBuildDirectory = (path: string): boolean => {
+    const stats = lstatSync(path, { throwIfNoEntry: false });
+
+    if (stats === undefined) {
+        return true;
+    }
+
+    return stats.isDirectory() && (readdirSync(path).length === 0 || isGtkxBuildDirectory(path));
+};
+
+const outputName = (root: string, path: string): string => relative(root, path) || ".";
+
+const gtkxBuildAncestor = (root: string, outDir: string): string | null => {
+    let ancestor = dirname(outDir);
+
+    while (isPathInside(root, ancestor)) {
+        if (isGtkxBuildDirectory(ancestor)) {
+            return ancestor;
+        }
+
+        ancestor = dirname(ancestor);
+    }
+
+    return null;
+};
+
+const childDirectories = (parent: string): string[] =>
+    readdirSync(parent, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => join(parent, entry.name));
+
+const gtkxBuildDescendant = (root: string): string | null => {
+    const pending = childDirectories(root);
+
+    while (pending.length > 0) {
+        const path = pending.pop();
+
+        if (path === undefined) {
+            return null;
+        }
+
+        if (isGtkxBuildDirectory(path)) {
+            return path;
+        }
+
+        pending.push(...childDirectories(path));
+    }
+
+    return null;
+};
+
+const assertSafeBuildLocation = (root: string, outDir: string): void => {
+    if (!isPathInside(root, outDir)) {
+        throw new Error(`Build output ${outDir} must be below the project root ${root}`);
+    }
+
+    if (hasSymlinkComponent(root, outDir)) {
+        throw new Error(`Build output ${outputName(root, outDir)} passes through a symbolic link`);
+    }
+
+    const ancestor = gtkxBuildAncestor(root, outDir);
+
+    if (ancestor !== null) {
+        throw new Error(
+            `Build output ${outputName(root, outDir)} is nested inside the earlier GTKX build ` +
+            outputName(root, ancestor),
+        );
+    }
+};
+
+const nonReusableBuildOutputError = (root: string, outDir: string): Error => {
+    const stats = lstatSync(outDir, { throwIfNoEntry: false });
+
+    if (stats?.isDirectory() !== true) {
+        return new Error(`Build output ${outputName(root, outDir)} exists and is not a directory`);
+    }
+
+    const descendant = gtkxBuildDescendant(outDir);
+
+    if (descendant !== null) {
+        return new Error(
+            `Build output ${outputName(root, outDir)} contains the earlier GTKX build ` +
+            outputName(root, descendant),
+        );
+    }
+
+    return new Error(
+        `Build output ${outputName(root, outDir)} is nonempty and is not an earlier GTKX build`,
+    );
+};
+
+const resolveBuildOutDir = (root: string, configured?: string): string => {
+    const selected = configured ?? DEFAULT_BUILD_OUT_DIR;
+    const outDir = resolve(root, selected);
+
+    assertSafeBuildLocation(root, outDir);
+
+    if (!isReusableBuildDirectory(outDir)) {
+        throw nonReusableBuildOutputError(root, outDir);
+    }
+
+    return outDir;
+};
+
+const prepareBuildOutDir = (root: string, outDir: string): PreparedBuildOutDir => {
+    assertSafeBuildLocation(root, outDir);
+    const prepared = prepareOutputDirectory(root, outDir, isReusableBuildDirectory);
+
+    if (prepared.status === "unsafe") {
+        throw new Error(`Build output ${outputName(root, outDir)} became unsafe while preparing it`);
+    }
+
+    const transaction: OutputDirectoryTransaction = prepared.transaction;
+
+    return {
+        path: transaction.path,
+        commit: () => {
+            transaction.commit(PRESERVED_BUILD_ENTRIES, isGtkxBuildDirectory);
+        },
+        [Symbol.dispose]: () => {
+            transaction[Symbol.dispose]();
+        },
+    };
+};
+
+export { prepareBuildOutDir, resolveBuildOutDir };

package/src/internal/cache-root.ts

@@ -0,0 +1,12 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const CACHE_NAMESPACE = "gtkx";
+
+const cacheRoot = (): string => {
+    const base = process.env.XDG_CACHE_HOME;
+
+    return join(base !== undefined && base.length > 0 ? base : join(homedir(), ".cache"), CACHE_NAMESPACE);
+};
+
+export { cacheRoot };

package/src/internal/compile-cache-store.ts

@@ -0,0 +1,50 @@
+import { readdirSync, rmSync } from "node:fs";
+import * as nodeModule from "node:module";
+import { basename, join } from "node:path";
+import { cacheRoot } from "./cache-root.js";
+import { COMPILE_CACHE_SEGMENT } from "./compile-cache.js";
+
+const RUNTIME_PREFIX = `v${process.versions.node}-${process.arch}-`;
+
+const currentNamespace = (): string | undefined => {
+    if (typeof nodeModule.getCompileCacheDir !== "function") {
+        return undefined;
+    }
+
+    const dir = nodeModule.getCompileCacheDir();
+
+    return dir === undefined ? undefined : basename(dir);
+};
+
+const isStale = (name: string, namespace: string | undefined): boolean =>
+    namespace === undefined ? !name.startsWith(RUNTIME_PREFIX) : name !== namespace;
+
+const findStaleCompileCaches = (): string[] => {
+    const namespace = currentNamespace();
+    const dir = join(cacheRoot(), COMPILE_CACHE_SEGMENT);
+
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && isStale(entry.name, namespace))
+            .map((entry) => join(dir, entry.name));
+    } catch {
+        return [];
+    }
+};
+
+const reapStaleCompileCaches = (candidates: string[]): string[] => {
+    const removed: string[] = [];
+
+    for (const candidate of candidates) {
+        try {
+            rmSync(candidate, { recursive: true, force: true });
+            removed.push(candidate);
+        } catch {
+            continue;
+        }
+    }
+
+    return removed;
+};
+
+export { findStaleCompileCaches, reapStaleCompileCaches };

package/src/internal/compile-cache.ts

@@ -0,0 +1,20 @@
+import * as nodeModule from "node:module";
+import { join } from "node:path";
+import { cacheRoot } from "./cache-root.js";
+
+const COMPILE_CACHE_SEGMENT = "compile-cache";
+const DISABLE_COMPILE_CACHE_ENV = "GTKX_DISABLE_COMPILE_CACHE";
+
+const enableToolchainCompileCache = (): void => {
+    if (process.env[DISABLE_COMPILE_CACHE_ENV] === "1") {
+        return;
+    }
+
+    if (typeof nodeModule.enableCompileCache !== "function") {
+        return;
+    }
+
+    nodeModule.enableCompileCache(join(cacheRoot(), COMPILE_CACHE_SEGMENT));
+};
+
+export { COMPILE_CACHE_SEGMENT, enableToolchainCompileCache };

package/src/internal/deploy-out-dir.ts

@@ -0,0 +1,8 @@
+import { resolve } from "node:path";
+
+const DEFAULT_DEPLOY_OUT_DIR = "build";
+
+const deployOutDirFor = (root: string, configured: string | undefined): string =>
+    resolve(root, configured ?? DEFAULT_DEPLOY_OUT_DIR);
+
+export { DEFAULT_DEPLOY_OUT_DIR, deployOutDirFor };

package/src/internal/docs-elements.ts

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

package/src/internal/entry-arg.ts

@@ -14,6 +14,13 @@ const cwdArg: { cwd: StringArgDef } = {
     },
 };
 
+const configArg: { config: StringArgDef } = {
+    config: {
+        type: "string",
+        description: "Project-relative configuration file (default: gtkx.config.*)",
+    },
+};
+
 const entryArg: { entry: PositionalArgDef; cwd: StringArgDef } = {
     entry: {
         type: "positional",
@@ -57,4 +64,4 @@ const resolveGivenEntry = (cwd: string, entry: string): string => {
 const resolveEntry = (cwd: string, entry: string | undefined): string =>
     entry ? resolveGivenEntry(cwd, entry) : resolveDefaultEntry(cwd);
 
-export { cwdArg, entryArg, resolveCwd, resolveEntry };
+export { configArg, cwdArg, entryArg, resolveCwd, resolveEntry };

package/src/internal/errors.ts

@@ -33,4 +33,4 @@ const withErrorBoundary = <T extends ArgsDef>(command: CommandDef<T>): CommandDe
     };
 };
 
-export { withErrorBoundary };
+export { printError, withErrorBoundary };

package/src/internal/font-path.ts

@@ -0,0 +1,15 @@
+import { createHash } from "node:crypto";
+import { basename, extname } from "node:path";
+
+const FONTS_DIR = "fonts";
+const DIGEST_LENGTH = 8;
+
+const fontFileName = (sourcePath: string, content: Buffer): string => {
+    const extension = extname(sourcePath).toLowerCase();
+    const stem = basename(sourcePath, extname(sourcePath));
+    const digest = createHash("sha1").update(content).digest("hex").slice(0, DIGEST_LENGTH);
+
+    return `${stem}-${digest}${extension}`;
+};
+
+export { fontFileName, FONTS_DIR };

package/src/internal/font-staging.ts

@@ -0,0 +1,131 @@
+import { sortStrings } from "@gtkx/utils";
+import { lstatSync, mkdirSync, readFileSync, symlinkSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { parseFontSpecifier } from "../vite-plugins/asset-specifier.js";
+import { fontFileName, FONTS_DIR } from "./font-path.js";
+import { discoverSourceFiles, importsIn, type SourceImport, sourceLanguage } from "./source-imports.js";
+import { createRetainedStagingDir } from "./staging-dir.js";
+
+type FontStagingStatus = "absent" | "staged" | "unmanaged";
+
+const FONT_DIR_ENV = "GTKX_DEV_FONT_DIR";
+const FONT_QUERY = "?font";
+const fontStaging = createRetainedStagingDir("fonts");
+
+const isRelativeImport = (source: string): boolean => source.startsWith("./") || source.startsWith("../");
+
+const existingPath = (path: string): string | null =>
+    lstatSync(path, { throwIfNoEntry: false }) === undefined ? null : path;
+
+const resolveRelativeImport = (importer: string, assetSource: string): string | null =>
+    existingPath(resolve(dirname(importer), assetSource));
+
+const resolveAbsoluteImport = (root: string, assetSource: string): string | null =>
+    existingPath(assetSource) ?? existingPath(join(root, assetSource));
+
+const resolvePackageImport = (importer: string, assetSource: string): string | null => {
+    try {
+        return createRequire(importer).resolve(assetSource);
+    } catch {
+        return null;
+    }
+};
+
+const resolveFontImport = (root: string, importer: string, assetSource: string): string | null => {
+    if (isRelativeImport(assetSource)) {
+        return resolveRelativeImport(importer, assetSource);
+    }
+
+    if (isAbsolute(assetSource)) {
+        return resolveAbsoluteImport(root, assetSource);
+    }
+
+    return resolvePackageImport(importer, assetSource);
+};
+
+const fontFileFor = (root: string, { importer, source }: SourceImport): string | null => {
+    const specifier = parseFontSpecifier(source);
+
+    return specifier === null ? null : resolveFontImport(root, importer, specifier.assetSource);
+};
+
+const hasFontImportMention = (filePath: string): boolean => {
+    if (sourceLanguage(filePath) === undefined) {
+        return false;
+    }
+
+    try {
+        return readFileSync(filePath, "utf8").includes(FONT_QUERY);
+    } catch {
+        return false;
+    }
+};
+
+const projectFontFiles = (root: string): string[] => {
+    const files = discoverSourceFiles(root)
+        .filter((path) => hasFontImportMention(path))
+        .flatMap((path) => importsIn(path))
+        .map((entry) => fontFileFor(root, entry))
+        .filter((path): path is string => path !== null);
+
+    return sortStrings(new Set(files));
+};
+
+const stagedPath = (fontsDir: string, sourcePath: string, content: Buffer): string =>
+    join(fontsDir, fontFileName(sourcePath, content));
+
+const stageFont = (fontsDir: string, sourcePath: string): void => {
+    const target = stagedPath(fontsDir, sourcePath, readFileSync(sourcePath));
+
+    if (existingPath(target) !== null) {
+        return;
+    }
+
+    symlinkSync(sourcePath, target, "file");
+};
+
+const stagedFontsDir = (): string | null => {
+    const shareDir = process.env[FONT_DIR_ENV];
+
+    return shareDir === undefined || shareDir.length === 0 ? null : join(shareDir, FONTS_DIR);
+};
+
+const stagedFontStatus = (sourcePath: string, content: Buffer): FontStagingStatus => {
+    const fontsDir = stagedFontsDir();
+
+    if (fontsDir === null) {
+        return "unmanaged";
+    }
+
+    return existingPath(stagedPath(fontsDir, sourcePath, content)) === null ? "absent" : "staged";
+};
+
+const isUnstagedFont = (fontsDir: string, sourcePath: string): boolean =>
+    existingPath(stagedPath(fontsDir, sourcePath, readFileSync(sourcePath))) === null;
+
+const hasUnstagedFontImport = (root: string, filePath: string): boolean => {
+    const fontsDir = stagedFontsDir();
+
+    if (fontsDir === null || !hasFontImportMention(filePath)) {
+        return false;
+    }
+
+    return projectFontFiles(root).some((sourcePath) => isUnstagedFont(fontsDir, sourcePath));
+};
+
+const stageProjectFonts = (root: string): string => {
+    const shareDir = fontStaging.retain();
+    const fontsDir = join(shareDir, FONTS_DIR);
+    mkdirSync(fontsDir, { recursive: true });
+
+    for (const sourcePath of projectFontFiles(root)) {
+        stageFont(fontsDir, sourcePath);
+    }
+
+    process.env[FONT_DIR_ENV] = shareDir;
+
+    return shareDir;
+};
+
+export { hasUnstagedFontImport, stagedFontStatus, stageProjectFonts };

package/src/internal/icon-staging.ts

@@ -0,0 +1,58 @@
+import { mkdirSync, rmSync, symlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { relativeIconPath, resolveApplicationIcon, type ResolvedApplicationIcon } from "./icon-path.js";
+import { createRetainedStagingDir, type RetainedStagingDir } from "./staging-dir.js";
+
+const ICONS_DIR = "icons";
+const stagingDirs: Map<string, RetainedStagingDir> = new Map();
+
+const stagingFor = (root: string): RetainedStagingDir => {
+    const existing = stagingDirs.get(root);
+
+    if (existing !== undefined) {
+        return existing;
+    }
+
+    const staging = createRetainedStagingDir("icons");
+    stagingDirs.set(root, staging);
+
+    return staging;
+};
+
+const resetIconsDir = (shareDir: string): string => {
+    const iconsDir = join(shareDir, ICONS_DIR);
+    rmSync(iconsDir, { recursive: true, force: true });
+
+    return iconsDir;
+};
+
+const stageIconSource = (
+    iconsDir: string,
+    applicationId: string,
+    source: Exclude<ResolvedApplicationIcon, { kind: "none" }>,
+): void => {
+    if (source.kind === "theme") {
+        symlinkSync(source.path, iconsDir, "dir");
+
+        return;
+    }
+
+    const target = join(iconsDir, relativeIconPath(applicationId, source.path));
+    mkdirSync(dirname(target), { recursive: true });
+    symlinkSync(source.path, target, "file");
+};
+
+const stageProjectIcons = (root: string, applicationId: string, configured: string | undefined): string | null => {
+    const source = resolveApplicationIcon(root, applicationId, configured);
+
+    if (source.kind === "none") {
+        return null;
+    }
+
+    const shareDir = stagingFor(root).retain();
+    stageIconSource(resetIconsDir(shareDir), applicationId, source);
+
+    return shareDir;
+};
+
+export { stageProjectIcons };