@gjsify/cli 0.3.13 → 0.3.15

package/lib/commands/flatpak/utils.d.ts

@@ -0,0 +1,32 @@
+import type { ConfigDataFlatpak } from '../../types/config-data.js';
+/**
+ * Default GNOME-Platform runtime version. Bumped per release window.
+ * GNOME 50 = April 2026 stable; tracked in
+ * https://docs.flathub.org/docs/for-app-authors/requirements.
+ */
+export declare const DEFAULT_GNOME_RUNTIME_VERSION = "50";
+/** Default Freedesktop-Platform runtime version (LTS-ish). */
+export declare const DEFAULT_FREEDESKTOP_RUNTIME_VERSION = "24.08";
+/** Permissive GUI defaults for GTK4 + Adwaita apps. */
+export declare const DEFAULT_GUI_FINISH_ARGS: string[];
+/** Lean defaults for headless CLI tools — no display, no GPU. */
+export declare const DEFAULT_CLI_FINISH_ARGS: string[];
+/** Read package.json from a directory. Throws a helpful error if missing/invalid. */
+export declare function readPackageJson(dir: string): Record<string, unknown>;
+/** True if a name string looks like a reverse-DNS Flatpak app id. */
+export declare function looksLikeAppId(value: unknown): value is string;
+/**
+ * Pick the runtime + sdk + version triple from config + CLI overrides.
+ * `--runtime` and `--runtime-version` flags win over config values.
+ */
+export declare function resolveRuntime(flatpak: ConfigDataFlatpak | undefined, overrides: {
+    runtime?: string;
+    runtimeVersion?: string;
+}): {
+    runtime: 'gnome' | 'freedesktop';
+    runtimeId: string;
+    sdk: string;
+    runtimeVersion: string;
+};
+/** Default container image for the GitHub Actions workflow. */
+export declare function defaultCiContainer(runtime: 'gnome' | 'freedesktop', runtimeVersion: string): string;

package/lib/commands/flatpak/utils.js

@@ -0,0 +1,63 @@
+// Shared helpers for the `gjsify flatpak <sub>` subcommand group.
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+/**
+ * Default GNOME-Platform runtime version. Bumped per release window.
+ * GNOME 50 = April 2026 stable; tracked in
+ * https://docs.flathub.org/docs/for-app-authors/requirements.
+ */
+export const DEFAULT_GNOME_RUNTIME_VERSION = '50';
+/** Default Freedesktop-Platform runtime version (LTS-ish). */
+export const DEFAULT_FREEDESKTOP_RUNTIME_VERSION = '24.08';
+/** Permissive GUI defaults for GTK4 + Adwaita apps. */
+export const DEFAULT_GUI_FINISH_ARGS = [
+    '--device=dri',
+    '--share=ipc',
+    '--socket=fallback-x11',
+    '--socket=wayland',
+];
+/** Lean defaults for headless CLI tools — no display, no GPU. */
+export const DEFAULT_CLI_FINISH_ARGS = [];
+/** Read package.json from a directory. Throws a helpful error if missing/invalid. */
+export function readPackageJson(dir) {
+    const path = resolve(dir, 'package.json');
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch {
+        throw new Error(`gjsify flatpak: no package.json found at ${path}`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`gjsify flatpak: package.json at ${path} is not valid JSON: ${err.message}`);
+    }
+}
+/** True if a name string looks like a reverse-DNS Flatpak app id. */
+export function looksLikeAppId(value) {
+    return typeof value === 'string' && /^[A-Za-z][A-Za-z0-9_-]*(\.[A-Za-z][A-Za-z0-9_-]*){2,}$/.test(value);
+}
+/**
+ * Pick the runtime + sdk + version triple from config + CLI overrides.
+ * `--runtime` and `--runtime-version` flags win over config values.
+ */
+export function resolveRuntime(flatpak, overrides) {
+    const runtime = (overrides.runtime ?? flatpak?.runtime ?? 'gnome');
+    if (runtime !== 'gnome' && runtime !== 'freedesktop') {
+        throw new Error(`gjsify flatpak: unknown runtime "${runtime}" (expected "gnome" or "freedesktop")`);
+    }
+    const runtimeVersion = overrides.runtimeVersion ??
+        flatpak?.runtimeVersion ??
+        (runtime === 'gnome' ? DEFAULT_GNOME_RUNTIME_VERSION : DEFAULT_FREEDESKTOP_RUNTIME_VERSION);
+    if (runtime === 'gnome') {
+        return { runtime, runtimeId: 'org.gnome.Platform', sdk: 'org.gnome.Sdk', runtimeVersion };
+    }
+    return { runtime, runtimeId: 'org.freedesktop.Platform', sdk: 'org.freedesktop.Sdk', runtimeVersion };
+}
+/** Default container image for the GitHub Actions workflow. */
+export function defaultCiContainer(runtime, runtimeVersion) {
+    const tag = `${runtime}-${runtimeVersion}`;
+    return `ghcr.io/flathub-infra/flatpak-github-actions:${tag}`;
+}

package/lib/commands/gsettings.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from '../types/index.js';
+interface GSettingsOptions {
+    schemadir: string;
+    targetdir?: string;
+    strict?: boolean;
+    verbose?: boolean;
+}
+export declare const gsettingsCommand: Command<any, GSettingsOptions>;
+export {};

package/lib/commands/gsettings.js

@@ -0,0 +1,72 @@
+import { execFile } from 'node:child_process';
+import { mkdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export const gsettingsCommand = {
+    command: 'gsettings <schemadir>',
+    description: 'Compile GSettings schema XML files into a binary gschemas.compiled (wraps `glib-compile-schemas`).',
+    builder: (yargs) => {
+        return yargs
+            .positional('schemadir', {
+            description: 'Directory containing *.gschema.xml descriptors',
+            type: 'string',
+            normalize: true,
+            demandOption: true,
+        })
+            .option('targetdir', {
+            alias: 't',
+            description: 'Directory to write gschemas.compiled (default: <schemadir>)',
+            type: 'string',
+            normalize: true,
+        })
+            .option('strict', {
+            description: 'Abort on any schema warning (passes --strict to glib-compile-schemas)',
+            type: 'boolean',
+            default: true,
+        })
+            .option('verbose', {
+            description: 'Print the underlying glib-compile-schemas invocation',
+            type: 'boolean',
+            default: false,
+        });
+    },
+    handler: async (args) => {
+        const schemadir = resolve(args.schemadir);
+        const targetdir = args.targetdir
+            ? resolve(args.targetdir)
+            : schemadir;
+        const cmdArgs = [];
+        if (args.strict)
+            cmdArgs.push('--strict');
+        cmdArgs.push(`--targetdir=${targetdir}`);
+        cmdArgs.push(schemadir);
+        if (args.verbose) {
+            console.log(`[gjsify gsettings] glib-compile-schemas ${cmdArgs.join(' ')}`);
+        }
+        // glib-compile-schemas writes a temporary file in `targetdir` before
+        // renaming to gschemas.compiled — fails with ENOENT if missing.
+        await mkdir(targetdir, { recursive: true });
+        try {
+            const { stdout, stderr } = await execFileAsync('glib-compile-schemas', cmdArgs);
+            if (stdout)
+                process.stdout.write(stdout);
+            if (stderr)
+                process.stderr.write(stderr);
+            if (args.verbose) {
+                console.log(`[gjsify gsettings] wrote ${targetdir}/gschemas.compiled`);
+            }
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT') {
+                console.error('[gjsify gsettings] glib-compile-schemas not found. Install it via your distro (package: glib2-devel / libglib2.0-dev).');
+            }
+            else {
+                if (err?.stderr)
+                    process.stderr.write(err.stderr);
+                console.error(`[gjsify gsettings] glib-compile-schemas failed${err?.code !== undefined ? ` (exit ${err.code})` : ''}`);
+            }
+            process.exitCode = typeof err?.code === 'number' ? err.code : 1;
+        }
+    },
+};

package/lib/commands/index.d.ts

@@ -6,5 +6,7 @@ export * from './showcase.js';
 export * from './create.js';
 export * from './gresource.js';
 export * from './gettext.js';
+export * from './gsettings.js';
+export { flatpakCommand } from './flatpak/index.js';
 export * from './dlx.js';
 export * from './install.js';

package/lib/commands/index.js

@@ -6,5 +6,7 @@ export * from './showcase.js';
 export * from './create.js';
 export * from './gresource.js';
 export * from './gettext.js';
+export * from './gsettings.js';
+export { flatpakCommand } from './flatpak/index.js';
 export * from './dlx.js';
 export * from './install.js';

package/lib/commands/install.d.ts

@@ -1,6 +1,7 @@
 import type { Command } from '../types/index.js';
 interface InstallOptions {
     packages?: string[];
+    global?: boolean;
     'save-dev'?: boolean;
     'save-peer'?: boolean;
     'save-optional'?: boolean;

package/lib/commands/install.js

@@ -1,36 +1,65 @@
-// `gjsify install [pkg...]` — thin npm wrapper with gjsify-aware post-checks.
-//
-// The actual install is delegated to `npm install` in the user's project root
-// (no `--prefix` rewrite, unlike `gjsify dlx`). After install completes we run
-// `runMinimalChecks()` so missing system deps (gjs, gtk4, libsoup, ...) surface
-// immediately, and report any installed `@gjsify/*` packages that ship native
-// prebuilds so users know they can use `gjsify run` to wire `LD_LIBRARY_PATH` /
-// `GI_TYPELIB_PATH` automatically.
+// `gjsify install [pkg...]` — install packages with gjsify-aware post-checks.
 //
 // Modes:
 //   gjsify install                    → project install (npm install)
-//   gjsify install <pkg> [<pkg>...]   → add package(s) (npm install <pkg>...)
+//   gjsify install <pkg> [<pkg>...]   → add package(s) to project (npm install <pkg>...)
+//   gjsify install -g <pkg> [...]     → user-global install (XDG, GJS-runnable bin)
+//
+// Project mode delegates to `npm install` in cwd and runs `runMinimalChecks()`
+// + `detectNativePackages()` to surface missing system deps and `@gjsify/*`
+// packages with native prebuilds.
+//
+// Global mode is the GJS equivalent of `npm i -g`: extracts the package tree
+// into `${XDG_DATA_HOME}/gjsify/global/node_modules/<pkg>/` via the native
+// install backend (no Node/npm required at runtime), then symlinks the bins
+// declared by `gjsify.bin` (preferred) or `bin` (fallback) into
+// `~/.local/bin/`. Subsequent commands invoked by name resolve to the
+// extracted package, so package-relative assets like `@ts-for-gir/cli`'s
+// `dist-templates/` are found by ordinary `__dirname/..` resolution — no
+// embedded asset stores, no separate release tarballs.
 import { spawn } from 'node:child_process';
+import { mkdirSync } from 'node:fs';
 import { buildInstallCommand, detectPackageManager, runMinimalChecks, } from '../utils/check-system-deps.js';
 import { detectNativePackages } from '../utils/detect-native-packages.js';
+import { installPackages } from '../utils/install-backend.js';
+import { binDirOnPath, defaultGlobalLayout, linkGlobalBins, specToPackageName, } from '../utils/install-global.js';
 export const installCommand = {
     command: 'install [packages..]',
-    description: 'Install npm dependencies in the current project, then run gjsify-aware post-checks.',
+    description: 'Install npm dependencies in the current project (or globally with -g), then run gjsify-aware post-checks.',
     builder: (yargs) => yargs
         .positional('packages', {
         description: 'Optional package specs. With none, runs a full project install.',
         type: 'string',
         array: true,
+    })
+        .option('global', {
+        description: 'Install into the user-global XDG location and symlink bins into ~/.local/bin.',
+        type: 'boolean',
+        alias: 'g',
+        default: false,
     })
         .option('save-dev', { type: 'boolean', alias: 'D' })
         .option('save-peer', { type: 'boolean' })
         .option('save-optional', { type: 'boolean', alias: 'O' })
         .option('verbose', {
-        description: 'Verbose npm logging.',
+        description: 'Verbose install logging.',
         type: 'boolean',
         default: false,
     }),
     handler: async (args) => {
+        if (args.global) {
+            if (!args.packages || args.packages.length === 0) {
+                console.error('gjsify install --global requires at least one <pkg> argument.');
+                process.exit(1);
+            }
+            for (const flag of ['save-dev', 'save-peer', 'save-optional']) {
+                if (args[flag]) {
+                    console.warn(`gjsify install --global ignores --${flag}: global installs do not modify a project package.json.`);
+                }
+            }
+            await installGlobalAndLink(args.packages, { verbose: args.verbose });
+            return;
+        }
         const npmArgs = ['install'];
         if (args['save-dev'])
             npmArgs.push('--save-dev');
@@ -68,6 +97,32 @@ async function spawnNpm(npmArgs) {
         process.exit(1);
     });
 }
+async function installGlobalAndLink(specs, opts) {
+    const layout = defaultGlobalLayout();
+    mkdirSync(layout.prefix, { recursive: true });
+    console.log(`gjsify install --global  → ${layout.prefix}`);
+    console.log(`                  bins → ${layout.binDir}`);
+    await installPackages({
+        prefix: layout.prefix,
+        specs,
+        verbose: opts.verbose,
+    });
+    const packageNames = specs.map(specToPackageName);
+    const created = linkGlobalBins(packageNames, layout);
+    if (created.length === 0) {
+        console.warn('\nNo bins declared (neither `gjsify.bin` nor `bin` in package.json) — nothing was symlinked.');
+    }
+    else {
+        console.log(`\nLinked ${created.length} bin(s):`);
+        for (const e of created) {
+            console.log(`  • ${e.link}  →  ${e.target}`);
+        }
+    }
+    if (created.length > 0 && !binDirOnPath(layout.binDir)) {
+        console.warn(`\nNote: ${layout.binDir} is not on your PATH.\n` +
+            `Add it to your shell rc file:\n  export PATH="${layout.binDir}:$PATH"`);
+    }
+}
 async function runPostInstallChecks() {
     console.log('\n--- gjsify post-install checks ---');
     // 1. System deps that GJS apps typically need.

package/lib/config.js

@@ -43,6 +43,23 @@ function merge(target, ...sources) {
 function isPlainObject(val) {
     return typeof val === 'object' && val !== null && !Array.isArray(val) && Object.getPrototypeOf(val) === Object.prototype;
 }
+/**
+ * Read a dotted path (`a.b.c`) from a plain object. Returns `undefined` for
+ * any missing segment. Intentionally narrow — only used for surfacing
+ * `package.json` fields into compile-time defines, not for arbitrary deep
+ * traversal.
+ */
+function readDottedPath(obj, path) {
+    if (!path.includes('.'))
+        return obj[path];
+    let cursor = obj;
+    for (const segment of path.split('.')) {
+        if (cursor === null || cursor === undefined || typeof cursor !== 'object')
+            return undefined;
+        cursor = cursor[segment];
+    }
+    return cursor;
+}
 export class Config {
     loadOptions = {};
     constructor(loadOptions = {}) {
@@ -84,7 +101,7 @@ export class Config {
         if (fileResult?.config && isPlainObject(fileResult.config)) {
             merge(merged, fileResult.config);
         }
-        merged.esbuild ||= {};
+        merged.bundler ||= {};
         merged.library ||= {};
         merged.typescript ||= {};
         return {
@@ -155,16 +172,91 @@ export class Config {
         if (Object.keys(aliasMap).length) {
             configData.aliases = { ...(configData.aliases ?? {}), ...aliasMap };
         }
-        merge(configData.esbuild ??= {}, {
-            format: cliArgs.format,
-            minify: cliArgs.minify,
-            entryPoints: cliArgs.entryPoints,
-            outfile: cliArgs.outfile,
-            outdir: cliArgs.outdir,
-            logLevel: cliArgs.logLevel || 'warning',
-            ...(cliArgs.external?.length ? { external: cliArgs.external } : {}),
-            ...(Object.keys(defineMap).length ? { define: defineMap } : {}),
-        });
+        // Resolve `defineFromPackageJson` / `defineFromEnv` into raw
+        // KEY=<JSON-stringified value> entries that get merged into the
+        // bundler's `transform.define` map below. Both produce JS expressions
+        // (the value side of a Rolldown define is substituted at the call
+        // site, not stringified again) — so a missing env variable resolves
+        // to the literal `undefined`, letting consumer code use
+        // `typeof X === 'undefined'` or `X ?? fallback` guards.
+        const fromPkgDefines = {};
+        if (configData.defineFromPackageJson) {
+            for (const [name, spec] of Object.entries(configData.defineFromPackageJson)) {
+                if (!spec || typeof spec.field !== 'string' || !spec.field) {
+                    throw new Error(`gjsify config: defineFromPackageJson["${name}"] is missing a "field" string`);
+                }
+                const value = readDottedPath(pkg, spec.field);
+                fromPkgDefines[name] = value === undefined ? 'undefined' : JSON.stringify(value);
+            }
+        }
+        const fromEnvDefines = {};
+        if (configData.defineFromEnv) {
+            for (const [name, spec] of Object.entries(configData.defineFromEnv)) {
+                if (!spec || typeof spec.env !== 'string' || !spec.env) {
+                    throw new Error(`gjsify config: defineFromEnv["${name}"] is missing an "env" string`);
+                }
+                const raw = process.env[spec.env];
+                const value = raw !== undefined ? raw : spec.default;
+                fromEnvDefines[name] = value === undefined ? 'undefined' : JSON.stringify(value);
+            }
+        }
+        // Merge CLI flags into the Rolldown-shape `bundler` field. Mappings:
+        //   --entry-points  → bundler.input
+        //   --outfile       → bundler.output.file
+        //   --outdir        → bundler.output.dir
+        //   --format        → bundler.output.format
+        //   --minify        → bundler.output.minify
+        //   --log-level     → bundler.logLevel
+        //   --external      → bundler.external
+        //   --define        → bundler.transform.define
+        const bundler = (configData.bundler ??= {});
+        const output = (bundler.output ??= {});
+        const transform = (bundler.transform ??= {});
+        if (cliArgs.entryPoints?.length)
+            bundler.input = cliArgs.entryPoints;
+        if (cliArgs.outfile !== undefined)
+            output.file = cliArgs.outfile;
+        if (cliArgs.outdir !== undefined)
+            output.dir = cliArgs.outdir;
+        if (cliArgs.format !== undefined)
+            output.format = cliArgs.format;
+        if (cliArgs.minify !== undefined)
+            output.minify = cliArgs.minify;
+        if (cliArgs.logLevel) {
+            // Map esbuild log levels to Rolldown's narrower set:
+            //   esbuild   → rolldown
+            //   silent    → silent
+            //   error     → warn   (rolldown has no error-only)
+            //   warning   → warn
+            //   info      → info
+            //   debug     → debug
+            //   verbose   → debug  (rolldown has no verbose)
+            const map = {
+                silent: 'silent',
+                error: 'warn',
+                warning: 'warn',
+                warn: 'warn',
+                info: 'info',
+                debug: 'debug',
+                verbose: 'debug',
+            };
+            const level = map[cliArgs.logLevel] ?? 'warn';
+            bundler.logLevel = level;
+        }
+        if (cliArgs.external?.length) {
+            const userExternal = Array.isArray(bundler.external) ? bundler.external : [];
+            bundler.external = [...userExternal, ...cliArgs.external];
+        }
+        if (Object.keys(defineMap).length || Object.keys(fromPkgDefines).length || Object.keys(fromEnvDefines).length) {
+            // CLI --define wins over package.json/env (manual overrides during
+            // debugging beat declarative config).
+            transform.define = {
+                ...(transform.define ?? {}),
+                ...fromPkgDefines,
+                ...fromEnvDefines,
+                ...defineMap,
+            };
+        }
         if (configData.verbose)
             console.debug("configData", configData);
         return configData;

package/lib/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
-import { buildCommand as build, runCommand as run, infoCommand as info, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, dlxCommand as dlx, installCommand as install, } from './commands/index.js';
+import { buildCommand as build, runCommand as run, infoCommand as info, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, dlxCommand as dlx, installCommand as install, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 void yargs(hideBin(process.argv))
     .scriptName(APP_NAME)
@@ -16,5 +16,7 @@ void yargs(hideBin(process.argv))
     .command(showcase.command, showcase.description, showcase.builder, showcase.handler)
     .command(gresource.command, gresource.description, gresource.builder, gresource.handler)
     .command(gettext.command, gettext.description, gettext.builder, gettext.handler)
+    .command(gsettings.command, gsettings.description, gsettings.builder, gsettings.handler)
+    .command(flatpak.command, flatpak.description, flatpak.builder, flatpak.handler)
     .demandCommand(1)
     .help().argv;

package/lib/types/cli-build-options.d.ts

@@ -1,4 +1,4 @@
-import type { App } from '@gjsify/esbuild-plugin-gjsify';
+import type { App } from '@gjsify/rolldown-plugin-gjsify';
 export interface CliBuildOptions {
     /**
      * This is an array of files that each serve as an input to the bundling algorithm.