@gjsify/cli 0.4.20 → 0.4.22

package/lib/commands/publish.js

@@ -57,6 +57,11 @@ export const publishCommand = {
         description: 'Treat "version already published" as success — covers both classic 409 Conflict and the npm OIDC-path 403 Forbidden + `"previously published"` body shape. Matches yarn `--tolerate-republish`.',
         type: 'boolean',
         default: false,
+    })
+        .option('tolerate-untrusted-new', {
+        description: 'Skip (exit 0) when OIDC token exchange returns `package not found` AND no fallback token is configured — i.e. a never-before-published `@scope/<name>` whose Trusted Publisher entry hasn\'t been set up on npmjs.com yet. Without this flag, one un-bootstrapped new package breaks the entire serialized `gjsify foreach publish` loop. Pair with `--tolerate-republish` in CI release workflows so a fresh-merged package gracefully skips its first CI publish, leaving the manual-bootstrap step to a maintainer (see AGENTS.md "New @gjsify/* package: first-publish + Trusted Publisher bootstrap").',
+        type: 'boolean',
+        default: false,
     })
         .option('provenance', {
         description: 'Pass-through flag — recorded in the payload but no signing happens (gjsify doesn\'t ship a sigstore signer yet).',
@@ -91,6 +96,7 @@ export const publishCommand = {
         const tag = args.tag ?? 'latest';
         const access = args.access;
         const tolerate = args['tolerate-republish'] === true;
+        const tolerateUntrustedNew = args['tolerate-untrusted-new'] === true;
         const provenance = args.provenance === true;
         const dryRun = args['dry-run'] === true;
         const checkTrustedOnly = args['check-trusted'] === true;
@@ -143,8 +149,17 @@ export const publishCommand = {
                 return;
             }
         }
-        // 1. Pack the workspace (rewrites workspace:^, computes integrity)
-        const packOpts = { dryRun: true };
+        // 1. Pack the workspace (rewrites workspace:^, computes integrity).
+        // Lifecycle scripts: `prepublishOnly` (publish-specific) runs before
+        // `prepack`. Matches `npm publish` semantics — packages that gate
+        // release-time validation on `prepublishOnly` (typecheck, smoke
+        // tests, version-tagging) get exactly that, and packages whose
+        // `prepack` generates build artifacts (process-templates,
+        // codegen, …) get those artifacts into the tarball.
+        const packOpts = {
+            dryRun: true,
+            lifecycleScripts: ['prepublishOnly', 'prepack'],
+        };
         const packed = await packWorkspace(wsDir, packOpts);
         // We need the raw bytes — re-run with destination=null and capture.
         // packWorkspace returns metadata only; for the bytes we re-pack into
@@ -243,6 +258,34 @@ export const publishCommand = {
                 }
             }
             catch (err) {
+                // Detect the "never-before-published @scope/pkg" shape:
+                // npm's OIDC exchange returns 404 with body
+                //   {"message":"OIDC token exchange error - package not found"}
+                // for any package that has no Trusted Publisher entry (which
+                // includes every package that doesn't exist on npm yet —
+                // see AGENTS.md "New @gjsify/* package: first-publish +
+                // Trusted Publisher bootstrap"). Skip such a package when
+                // --tolerate-untrusted-new is set so one un-bootstrapped
+                // package doesn't break the entire serialized publish loop.
+                const isUntrustedNewPackage = err instanceof OidcExchangeError &&
+                    err.status === 404 &&
+                    /package not found/i.test(err.body);
+                if (isUntrustedNewPackage && tolerateUntrustedNew) {
+                    const headerMsg = `${packed.name}@${packed.version} (skipped — no Trusted Publisher on npm, see AGENTS.md "New @gjsify/* package: first-publish + Trusted Publisher bootstrap")`;
+                    if (args.json) {
+                        process.stdout.write(`${JSON.stringify({
+                            ok: true,
+                            action: 'skipped-untrusted-new',
+                            name: packed.name,
+                            version: packed.version,
+                            reason: 'no-trusted-publisher',
+                        }, null, 2)}\n`);
+                    }
+                    else {
+                        process.stdout.write(`~ ${headerMsg}\n`);
+                    }
+                    return;
+                }
                 if (trustedFlag === true) {
                     // Explicit --trusted: bail with a clear error.
                     handleOidcFailure(err, packed.name, args.json === true);
@@ -317,9 +360,16 @@ export const publishCommand = {
 };
 async function packWorkspaceToBytes(wsDir) {
     // Cheap re-run that writes to a tempdir, then read back. Avoids
-    // duplicating the file-walking + tar-building logic here.
+    // duplicating the file-walking + tar-building logic here. Lifecycle
+    // scripts are already run by the outer publish flow's first pack
+    // call — passing `[]` here skips re-running them (idempotent for
+    // most projects but a needless cost otherwise).
     const tmp = `/tmp/gjsify-publish-${process.pid}-${Date.now()}`;
-    const res = await packWorkspace(wsDir, { destination: tmp, dryRun: false });
+    const res = await packWorkspace(wsDir, {
+        destination: tmp,
+        dryRun: false,
+        lifecycleScripts: [],
+    });
     if (!res.absolutePath)
         throw new Error('gjsify publish: pack did not produce a file');
     const bytes = new Uint8Array(readFileSync(res.absolutePath));

package/lib/commands/system-check.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from '../types/index.js';
+interface CheckOptions {
+    json: boolean;
+}
+export declare const systemCheckCommand: Command<any, CheckOptions>;
+export {};

package/lib/commands/system-check.js

@@ -0,0 +1,72 @@
+import { runAllChecks, detectPackageManager, buildInstallCommand } from '../utils/check-system-deps.js';
+export const systemCheckCommand = {
+    command: 'system-check',
+    description: 'Check that required system dependencies (GJS, GTK4, libsoup3, …) are installed. Optional dependencies are detected only when their @gjsify/* package is in your project. (Previously called `gjsify check`; the bare name now runs TypeScript checks across the workspace — see `gjsify check --help`.)',
+    builder: (yargs) => {
+        return yargs
+            .option('json', {
+            description: 'Output results as JSON',
+            type: 'boolean',
+            default: false,
+        });
+    },
+    handler: async (args) => {
+        const results = runAllChecks(process.cwd());
+        const pm = detectPackageManager();
+        const missingRequired = results.filter(r => !r.found && r.severity === 'required');
+        const missingOptional = results.filter(r => !r.found && r.severity === 'optional');
+        const allMissing = [...missingRequired, ...missingOptional];
+        if (args.json) {
+            console.log(JSON.stringify({ packageManager: pm, deps: results }, null, 2));
+            // Only required deps influence the exit code.
+            process.exit(missingRequired.length > 0 ? 1 : 0);
+            return;
+        }
+        console.log('System dependency check\n');
+        const required = results.filter(r => r.severity === 'required');
+        const optional = results.filter(r => r.severity === 'optional');
+        if (required.length > 0) {
+            console.log('Required:');
+            for (const dep of required) {
+                const icon = dep.found ? '✓' : '✗';
+                const ver = dep.version ? `  (${dep.version})` : '';
+                console.log(`  ${icon}  ${dep.name}${ver}`);
+            }
+        }
+        if (optional.length > 0) {
+            console.log('\nOptional:');
+            for (const dep of optional) {
+                // ⚠ for missing-but-needed-by-installed-packages, ○ for missing-but-not-needed (shouldn't appear in conditional mode)
+                const icon = dep.found ? '✓' : '⚠';
+                const ver = dep.version ? `  (${dep.version})` : '';
+                const requiredBy = dep.requiredBy && dep.requiredBy.length > 0
+                    ? `  — needed by ${dep.requiredBy.join(', ')}`
+                    : '';
+                console.log(`  ${icon}  ${dep.name}${ver}${requiredBy}`);
+            }
+        }
+        console.log(`\nPackage manager: ${pm}`);
+        if (allMissing.length === 0) {
+            console.log('\nAll dependencies found.');
+            return;
+        }
+        if (missingRequired.length > 0) {
+            console.log(`\nMissing required: ${missingRequired.map(d => d.name).join(', ')}`);
+        }
+        if (missingOptional.length > 0) {
+            console.log(`Missing optional: ${missingOptional.map(d => d.name).join(', ')}`);
+        }
+        const cmd = buildInstallCommand(pm, allMissing);
+        if (cmd) {
+            console.log(`\nTo install:\n  ${cmd}`);
+        }
+        else {
+            console.log('\nNo install command available for your package manager. Install manually.');
+        }
+        // Exit non-zero ONLY if a required dependency is missing.
+        // Optional deps that are missing but needed by an installed @gjsify/*
+        // package generate a warning but keep exit code 0 — the user can still
+        // build/run code paths that don't touch the optional library.
+        process.exit(missingRequired.length > 0 ? 1 : 0);
+    },
+};

package/lib/index.js

@@ -1,8 +1,27 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
-import { buildCommand as build, testCommand as test, 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, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, } from './commands/index.js';
+import { buildCommand as build, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, 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, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
+// Read the version from package.json adjacent to the bundle. yargs's
+// auto-version-discovery (its `pkg-up`-driven default) doesn't reach
+// through the bundled `dist/cli.gjs.mjs` path on GJS — falls back to
+// "unknown". Both layouts are covered:
+//   - dev (tsx, `yarn workspace`):  src/index.ts → ../package.json
+//   - bundled (install -g):         dist/cli.gjs.mjs → ../package.json
+function readBundleVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
 // `parseAsync()` instead of `.argv` so the top-level await keeps the
 // process alive until command handlers complete. Under Node this is
 // cosmetic — the event loop holds the process up — but under GJS the
@@ -11,6 +30,7 @@ import { APP_NAME } from './constants.js';
 const cli = yargs(hideBin(process.argv));
 await cli
     .scriptName(APP_NAME)
+    .version(readBundleVersion())
     .strict()
     // Use the full terminal width for help. yargs's default caps at 80
     // (`Math.min(80, process.stdout.columns)`); we explicitly opt into
@@ -28,6 +48,7 @@ await cli
     .command(run.command, run.description, run.builder, run.handler)
     .command(dlx.command, dlx.description, dlx.builder, dlx.handler)
     .command(info.command, info.description, info.builder, info.handler)
+    .command(systemCheck.command, systemCheck.description, systemCheck.builder, systemCheck.handler)
     .command(check.command, check.description, check.builder, check.handler)
     .command(showcase.command, showcase.description, showcase.builder, showcase.handler)
     .command(gresource.command, gresource.description, gresource.builder, gresource.handler)

package/lib/types/config-data.d.ts

@@ -253,6 +253,13 @@ export interface ConfigDataFlatpak {
     finishArgs?: string[];
     /** Extra Flatpak modules prepended before the app's own meson/simple module (e.g. `blueprint-compiler` build). */
     extraModules?: unknown[];
+    /**
+     * Full replacement for the manifest's `modules` array. When set, neither
+     * `extraModules` nor the meson default get added — the array is used
+     * verbatim. Right shape for CLI tools that ship a pre-built bundle and
+     * install via shell commands (`buildsystem: simple`) instead of meson.
+     */
+    modules?: unknown[];
     /** Cleanup glob patterns applied to the final manifest, e.g. `['/include', '/lib/pkgconfig']`. */
     cleanup?: string[];
     /** Source-of-truth lockfile for `gjsify flatpak deps` — `yarn.lock` or `package-lock.json`. */

package/lib/utils/check-system-deps.js

@@ -81,6 +81,14 @@ const OPTIONAL_DEPS = {
     pangocairo: { id: 'pangocairo', name: 'PangoCairo', pkgName: 'pangocairo' },
     webkitgtk: { id: 'webkitgtk', name: 'WebKitGTK', pkgName: 'webkitgtk-6.0' },
     cairo: { id: 'cairo', name: 'Cairo', pkgName: 'cairo' },
+    // Build-time deps for @gjsify/*-native Vala prebuilds. End-users with
+    // installed prebuilds don't need the -devel package — only contributors
+    // rebuilding from source via `yarn build:prebuilds`. We still surface
+    // them in the optional set so the "missing" diagnostic catches build-
+    // time failures with an actionable install-hint instead of a meson
+    // `Run-time dependency X found: NO` error mid-build.
+    gnutls: { id: 'gnutls', name: 'GnuTLS', pkgName: 'gnutls' },
+    nghttp2: { id: 'nghttp2', name: 'libnghttp2', pkgName: 'libnghttp2' },
 };
 /**
  * Map of @gjsify/* package name → ids of OPTIONAL_DEPS this package needs.
@@ -101,6 +109,12 @@ const PACKAGE_DEPS = {
     // runOptionalChecks. Mapping it here so its presence in the project's
     // dep tree triggers the check.
     '@gjsify/webgl': ['gwebgl'],
+    // Native Vala bridges with `dependency('gnutls')` / `dependency('libnghttp2')`
+    // in their meson.build. Optional because the shipped prebuild covers the
+    // common-arch user path; only contributors rebuilding from source hit the
+    // build-time dep.
+    '@gjsify/tls-native': ['gnutls'],
+    '@gjsify/http2-native': ['nghttp2'],
     // @gjsify/event-bridge only needs gtk4/gdk which are already in the
     // required set, so it doesn't need an optional entry.
 };
@@ -278,6 +292,8 @@ const PM_PACKAGES = {
         pango: 'libpango1.0-dev',
         pangocairo: 'libpango1.0-dev',
         cairo: 'libcairo2-dev',
+        gnutls: 'libgnutls28-dev',
+        nghttp2: 'libnghttp2-dev',
     },
     dnf: {
         gjs: 'gjs',
@@ -296,6 +312,8 @@ const PM_PACKAGES = {
         pango: 'pango-devel',
         pangocairo: 'pango-devel',
         cairo: 'cairo-devel',
+        gnutls: 'gnutls-devel',
+        nghttp2: 'libnghttp2-devel',
     },
     pacman: {
         gjs: 'gjs',
@@ -314,6 +332,8 @@ const PM_PACKAGES = {
         pango: 'pango',
         pangocairo: 'pango',
         cairo: 'cairo',
+        gnutls: 'gnutls',
+        nghttp2: 'libnghttp2',
     },
     zypper: {
         gjs: 'gjs',
@@ -332,6 +352,8 @@ const PM_PACKAGES = {
         pango: 'pango-devel',
         pangocairo: 'pango-devel',
         cairo: 'cairo-devel',
+        gnutls: 'libgnutls-devel',
+        nghttp2: 'libnghttp2-devel',
     },
     apk: {
         gjs: 'gjs',
@@ -350,6 +372,8 @@ const PM_PACKAGES = {
         pango: 'pango-dev',
         pangocairo: 'pango-dev',
         cairo: 'cairo-dev',
+        gnutls: 'gnutls-dev',
+        nghttp2: 'nghttp2-dev',
     },
     unknown: {},
 };

package/lib/utils/install-backend-native.d.ts

@@ -1,6 +1,14 @@
+import { type Packument } from "@gjsify/npm-registry";
 import type { InstallOptions } from "./install-backend.ts";
+interface ParsedSpec {
+    name: string;
+    range: string;
+}
 export interface InstalledTopLevel {
     name: string;
     version: string;
 }
 export declare function installPackagesNative(opts: InstallOptions): Promise<InstalledTopLevel[]>;
+export declare function parseSpec(raw: string): ParsedSpec;
+export declare function pickVersion(packument: Packument, range: string): string | null;
+export {};

package/lib/utils/install-backend-native.js

@@ -384,22 +384,36 @@ function describeLockfileDrift(lockfile, specs) {
         lines.push(`  - ${removed.sort().join("\n  - ")}`);
     return lines.join("\n");
 }
-function parseSpec(raw) {
+// Exported for unit-testing — keep the function name + signature
+// stable, the install-backend itself still calls it via the local
+// binding below. Internal API.
+export function parseSpec(raw) {
+    // Bare names without an explicit `@version` resolve to the `latest`
+    // dist-tag. This matches npm CLI behaviour (`npm install foo` →
+    // foo@latest) and — crucially — picks up prereleases when the
+    // publisher has tagged them as `latest`. Using semver `*` here
+    // would silently exclude any version with a `-` (rc, beta, alpha,
+    // …) suffix per semver §9 ("Pre-release versions have a lower
+    // precedence than the associated normal version"); ts-for-gir
+    // shipped only prereleases (4.0.0-rc.17 is the `latest` tag, no
+    // stable 4.x yet) and `*` was selecting the abandoned 3.3.0
+    // instead.
     if (raw.startsWith("@")) {
         const slash = raw.indexOf("/");
         if (slash < 0)
             throw new Error(`Invalid spec (scoped name without slash): ${raw}`);
         const at = raw.indexOf("@", slash);
         if (at < 0)
-            return { name: raw, range: "*" };
-        return { name: raw.slice(0, at), range: raw.slice(at + 1) || "*" };
+            return { name: raw, range: "latest" };
+        return { name: raw.slice(0, at), range: raw.slice(at + 1) || "latest" };
     }
     const at = raw.indexOf("@");
     if (at < 0)
-        return { name: raw, range: "*" };
-    return { name: raw.slice(0, at), range: raw.slice(at + 1) || "*" };
+        return { name: raw, range: "latest" };
+    return { name: raw.slice(0, at), range: raw.slice(at + 1) || "latest" };
 }
-function pickVersion(packument, range) {
+// Exported for unit-testing. Internal API.
+export function pickVersion(packument, range) {
     // dist-tag fast path: `latest`, `next`, ...
     if (packument["dist-tags"][range])
         return packument["dist-tags"][range];

package/lib/utils/run-lifecycle-script.d.ts

@@ -0,0 +1,14 @@
+export interface RunLifecycleScriptOptions {
+    /** When true, do not throw on missing scripts — return `false` instead. */
+    optional?: boolean;
+    /** Stdio inheritance. Defaults to `'inherit'` so output goes to the parent. */
+    stdio?: 'inherit' | 'pipe' | 'ignore';
+    /** Extra environment variables layered on top of the defaults. */
+    env?: Record<string, string>;
+}
+/**
+ * Run a lifecycle script defined in `pkg.scripts[name]` from `wsDir`.
+ * Returns `true` if the script existed and exited 0. Returns `false` if
+ * `optional: true` and the script is missing. Throws on non-zero exit.
+ */
+export declare function runLifecycleScript(wsDir: string, pkg: Record<string, unknown>, name: string, opts?: RunLifecycleScriptOptions): Promise<boolean>;

package/lib/utils/run-lifecycle-script.js

@@ -0,0 +1,74 @@
+// Run an npm-style lifecycle script (`prepack`, `prepare`, `prepublishOnly`,
+// `postpack`, `postpublish`, …) from inside a `gjsify pack` / `gjsify
+// publish` flow.
+//
+// Why this exists separately from `gjsify run`: `gjsify run <script>` ends
+// with `process.exit(<code>)` so it can be used as a CLI entrypoint that
+// behaves like `yarn run` / `npm run`. That's wrong for the embedded use
+// case where pack/publish needs the lifecycle script to finish, then keep
+// running its own logic. This helper resolves to a Promise that settles
+// when the child exits — no process.exit, no GLib-mainloop intermingling
+// from `ensureMainLoop`.
+//
+// Matches yarn / npm script semantics:
+//   - `shell: true` so `&&` / `|` / env-var refs work
+//   - PATH prepended with `<wsDir>/node_modules/.bin` + monorepo-root bin
+//   - `npm_lifecycle_event` / `npm_package_name` / `npm_package_version`
+//     env vars set
+//   - FORCE_COLOR=1 default unless caller overrides
+import { spawn } from 'node:child_process';
+import { delimiter, join } from 'node:path';
+import { findWorkspaceRoot } from './workspace-root.js';
+/**
+ * Run a lifecycle script defined in `pkg.scripts[name]` from `wsDir`.
+ * Returns `true` if the script existed and exited 0. Returns `false` if
+ * `optional: true` and the script is missing. Throws on non-zero exit.
+ */
+export async function runLifecycleScript(wsDir, pkg, name, opts = {}) {
+    const scripts = pkg.scripts ?? {};
+    const literal = scripts[name];
+    if (typeof literal !== 'string') {
+        if (opts.optional !== false)
+            return false;
+        throw new Error(`gjsify lifecycle-script: no "${name}" in ${wsDir}/package.json`);
+    }
+    const monorepoRoot = findWorkspaceRoot(wsDir);
+    const binDirs = [join(wsDir, 'node_modules', '.bin')];
+    if (monorepoRoot && monorepoRoot !== wsDir) {
+        binDirs.push(join(monorepoRoot, 'node_modules', '.bin'));
+    }
+    // Match yarn / npm color-forcing default — see runScript() in run.ts
+    // for the full reasoning. Without this, lifecycle scripts that call
+    // tools like biome / esbuild / tsc lose ANSI color in piped contexts
+    // (CI logs, redirected output) because `process.stdout.isTTY` is
+    // false for the spawned child.
+    const colorEnv = process.env.FORCE_COLOR !== undefined || process.env.NO_COLOR !== undefined
+        ? {}
+        : { FORCE_COLOR: '1' };
+    const env = {
+        ...process.env,
+        ...colorEnv,
+        PATH: [...binDirs, process.env.PATH ?? ''].filter(Boolean).join(delimiter),
+        npm_lifecycle_event: name,
+        npm_package_name: pkg.name ?? '',
+        npm_package_version: pkg.version ?? '',
+        ...(opts.env ?? {}),
+    };
+    await new Promise((resolveOk, reject) => {
+        const child = spawn(literal, [], {
+            cwd: wsDir,
+            env: env,
+            stdio: opts.stdio ?? 'inherit',
+            shell: true,
+        });
+        child.on('close', (code) => {
+            if (code === 0)
+                resolveOk();
+            else {
+                reject(new Error(`gjsify lifecycle-script: "${name}" in ${wsDir} exited with code ${code}`));
+            }
+        });
+        child.on('error', reject);
+    });
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.4.20",
+    "version": "0.4.22",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -12,6 +12,89 @@
     "gjsify": {
         "bin": {
             "gjsify": "./dist/cli.gjs.mjs"
+        },
+        "flatpak": {
+            "appId": "io.github.gjsify.Cli",
+            "kind": "cli",
+            "name": "gjsify",
+            "runtime": "gnome",
+            "runtimeVersion": "50",
+            "sdkExtensions": [
+                "org.freedesktop.Sdk.Extension.node24"
+            ],
+            "appendPath": [
+                "/usr/lib/sdk/node24/bin"
+            ],
+            "command": "gjsify",
+            "finishArgs": [
+                "--share=network",
+                "--filesystem=host"
+            ],
+            "developer": {
+                "id": "io.github.gjsify",
+                "name": "gjsify contributors",
+                "email": "pascal@artandcode.studio"
+            },
+            "summary": "Node.js + Web APIs for GJS — bundle, install, lint, format, flatpak-pack GJS apps",
+            "description": [
+                {
+                    "p": "gjsify is the build-and-tooling CLI for the gjsify project — a polyfill family + bundler that lets you write GNOME apps in Node-shaped TypeScript and run them on GJS (the GNOME JavaScript runtime) without Node.js at runtime."
+                },
+                {
+                    "p": "Use this Flatpak when you want gjsify available on any modern Linux distro without installing Node.js or a system-wide npm setup. The CLI ships its own GJS bundle and a pinned Node 24 SDK extension for the subcommands (`gjsify build`, `gjsify lint`, `gjsify format`) that still call out to Node tooling internally."
+                },
+                {
+                    "ul": [
+                        {
+                            "item": "`gjsify build` — bundle a TypeScript entry into a single GJS / Node / browser file via Rolldown"
+                        },
+                        {
+                            "item": "`gjsify install` — Node-free npm install with a lockfile (XDG-aware, native backend)"
+                        },
+                        {
+                            "item": "`gjsify dlx <pkg>` — fetch and run any npm package's GJS bundle without persisting it"
+                        },
+                        {
+                            "item": "`gjsify lint` / `gjsify format` — Biome-powered linter + formatter"
+                        },
+                        {
+                            "item": "`gjsify flatpak {init,build,check,deps,ci}` — pack a GJS app or CLI into a Flatpak end-to-end"
+                        },
+                        {
+                            "item": "`gjsify gresource` — bundle GResource XML files for GTK apps"
+                        },
+                        {
+                            "item": "`gjsify showcase` — run the bundled demo programs (Excalibur, three.js, WebRTC, …)"
+                        }
+                    ]
+                }
+            ],
+            "license": {
+                "metadata": "CC0-1.0",
+                "project": "MIT"
+            },
+            "categories": [
+                "Development"
+            ],
+            "homepageUrl": "https://gjsify.github.io/gjsify/",
+            "vcsBrowserUrl": "https://github.com/gjsify/gjsify",
+            "issueTrackerUrl": "https://github.com/gjsify/gjsify/issues",
+            "modules": [
+                {
+                    "name": "gjsify-cli",
+                    "buildsystem": "simple",
+                    "build-commands": [
+                        "install -Dm755 dist/cli.gjs.mjs /app/share/gjsify/cli.gjs.mjs",
+                        "install -Dm755 launcher.sh /app/bin/gjsify"
+                    ],
+                    "sources": [
+                        {
+                            "type": "dir",
+                            "path": "."
+                        }
+                    ]
+                }
+            ]
         }
     },
     "files": [
@@ -37,18 +120,18 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.4.20",
-        "@gjsify/create-app": "^0.4.20",
-        "@gjsify/node-globals": "^0.4.20",
-        "@gjsify/node-polyfills": "^0.4.20",
-        "@gjsify/npm-registry": "^0.4.20",
-        "@gjsify/resolve-npm": "^0.4.20",
-        "@gjsify/rolldown-plugin-gjsify": "^0.4.20",
-        "@gjsify/rolldown-plugin-pnp": "^0.4.20",
-        "@gjsify/semver": "^0.4.20",
-        "@gjsify/tar": "^0.4.20",
-        "@gjsify/web-polyfills": "^0.4.20",
-        "@gjsify/workspace": "^0.4.20",
+        "@gjsify/buffer": "^0.4.22",
+        "@gjsify/create-app": "^0.4.22",
+        "@gjsify/node-globals": "^0.4.22",
+        "@gjsify/node-polyfills": "^0.4.22",
+        "@gjsify/npm-registry": "^0.4.22",
+        "@gjsify/resolve-npm": "^0.4.22",
+        "@gjsify/rolldown-plugin-gjsify": "^0.4.22",
+        "@gjsify/rolldown-plugin-pnp": "^0.4.22",
+        "@gjsify/semver": "^0.4.22",
+        "@gjsify/tar": "^0.4.22",
+        "@gjsify/web-polyfills": "^0.4.22",
+        "@gjsify/workspace": "^0.4.22",
         "cosmiconfig": "^9.0.1",
         "get-tsconfig": "^4.14.0",
         "pkg-types": "^2.3.1",
@@ -56,12 +139,12 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.4.20",
+        "@gjsify/unit": "^0.4.22",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/rolldown-native": "^0.4.20"
+        "@gjsify/rolldown-native": "^0.4.22"
     },
     "peerDependenciesMeta": {
         "@gjsify/rolldown-native": {