@gjsify/cli 0.4.9 → 0.4.10

package/lib/commands/generate-installer.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from '../types/index.js';
+interface GenerateInstallerOptions {
+    target?: string;
+    'bin-name'?: string;
+    'bootstrap-url'?: string;
+    output: string;
+    force: boolean;
+}
+export declare const generateInstallerCommand: Command<any, GenerateInstallerOptions>;
+export {};

package/lib/commands/generate-installer.js

@@ -0,0 +1,113 @@
+// `gjsify generate-installer [target]` — scaffold an `install.mjs` for any
+// GJS-runnable npm package, modeled on gjsify's own installer.
+//
+// The generated `install.mjs` is a verbatim copy of gjsify's root `install.mjs`
+// with three constants substituted:
+//
+//   DEFAULT_TARGET      → the consumer's npm package name
+//   DEFAULT_BIN_NAME    → the consumer's bin name (key of `gjsify.bin` or `bin`)
+//   DEFAULT_BOOTSTRAP_URL → URL of a gjsify `cli.gjs.mjs` bootstrap bundle
+//
+// End-user workflow:
+//   cd my-gjs-app
+//   gjsify generate-installer
+//   git add install.mjs && git commit
+//   # README:
+//   #   curl -fsSL https://github.com/me/my-gjs-app/raw/main/install.mjs \
+//   #     -o /tmp/i.mjs && gjs -m /tmp/i.mjs && rm /tmp/i.mjs
+//
+// The template is read at build time (static-read-inliner inlines the file
+// contents into the bundled CLI), so the runtime cost is just a string
+// replace + write.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+// Lazy load. Reading at the top level breaks `gjsify run copy-templates`
+// (the bootstrap step that ships the template into `lib/templates/` after
+// `tsc`): the run script must first import this module to dispatch into
+// itself, which would then ENOENT on the not-yet-copied template file.
+// The static-read-inliner can still detect this shape inside the handler.
+function loadInstallerTemplate() {
+    return readFileSync(new URL('../templates/install.mjs.tmpl', import.meta.url), 'utf-8');
+}
+const DEFAULT_BOOTSTRAP_URL = 'https://github.com/gjsify/gjsify/releases/latest/download/cli.gjs.mjs';
+export const generateInstallerCommand = {
+    command: 'generate-installer [target]',
+    description: 'Scaffold an install.mjs in the current directory for a GJS-runnable npm package.',
+    builder: (yargs) => yargs
+        .positional('target', {
+        description: 'Npm package name to install (default: current package.json name).',
+        type: 'string',
+    })
+        .option('bin-name', {
+        description: 'Bin name produced by the installer (default: first key of `gjsify.bin` or `bin`).',
+        type: 'string',
+    })
+        .option('bootstrap-url', {
+        description: 'Override the cli.gjs.mjs bootstrap bundle URL (default: gjsify GitHub releases/latest).',
+        type: 'string',
+    })
+        .option('output', {
+        description: 'Where to write the generated installer.',
+        type: 'string',
+        default: 'install.mjs',
+    })
+        .option('force', {
+        description: 'Overwrite an existing output file.',
+        type: 'boolean',
+        default: false,
+    }),
+    handler: (args) => {
+        const outputPath = resolve(process.cwd(), args.output);
+        if (existsSync(outputPath) && !args.force) {
+            console.error(`${args.output} already exists. Re-run with --force to overwrite.`);
+            process.exit(1);
+            return;
+        }
+        const pkgJsonPath = resolve(process.cwd(), 'package.json');
+        let pkgJson = null;
+        if (existsSync(pkgJsonPath)) {
+            try {
+                pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+            }
+            catch {
+                /* no pkg.json or unparsable — fall back to flags */
+            }
+        }
+        const target = args.target ?? pkgJson?.name;
+        if (!target) {
+            console.error('No target package: pass `gjsify generate-installer <pkg>` or run inside a directory with a package.json.');
+            process.exit(1);
+            return;
+        }
+        const binName = args['bin-name'] ?? pickDefaultBinName(pkgJson, target);
+        const bootstrapUrl = args['bootstrap-url'] ?? DEFAULT_BOOTSTRAP_URL;
+        const rendered = loadInstallerTemplate()
+            .replace(/const DEFAULT_TARGET = '[^']+';/, `const DEFAULT_TARGET = ${JSON.stringify(target)};`)
+            .replace(/const DEFAULT_BIN_NAME = '[^']+';/, `const DEFAULT_BIN_NAME = ${JSON.stringify(binName)};`)
+            .replace(/const DEFAULT_BOOTSTRAP_URL =\s*'[^']+';/, `const DEFAULT_BOOTSTRAP_URL = ${JSON.stringify(bootstrapUrl)};`);
+        writeFileSync(outputPath, rendered, { mode: 0o755 });
+        console.log(`Wrote ${args.output} (target=${target}, bin=${binName}).`);
+        console.log('');
+        console.log('Install one-liner for your README:');
+        console.log(`  curl -fsSL https://github.com/<you>/<repo>/raw/main/${args.output} -o /tmp/i.mjs \\`);
+        console.log('    && gjs -m /tmp/i.mjs && rm /tmp/i.mjs');
+    },
+};
+function pickDefaultBinName(pkgJson, target) {
+    const gjsifyBin = pkgJson?.gjsify?.bin;
+    if (gjsifyBin && typeof gjsifyBin === 'object') {
+        const first = Object.keys(gjsifyBin)[0];
+        if (first)
+            return first;
+    }
+    const npmBin = pkgJson?.bin;
+    if (npmBin && typeof npmBin === 'object') {
+        const first = Object.keys(npmBin)[0];
+        if (first)
+            return first;
+    }
+    if (typeof npmBin === 'string') {
+        return target.startsWith('@') ? target.slice(target.indexOf('/') + 1) : target;
+    }
+    return target.startsWith('@') ? target.slice(target.indexOf('/') + 1) : target;
+}

package/lib/commands/index.d.ts

@@ -14,3 +14,5 @@ export * from './foreach.js';
 export * from './workspace.js';
 export * from './pack.js';
 export * from './publish.js';
+export * from './self-update.js';
+export * from './generate-installer.js';

package/lib/commands/index.js

@@ -14,3 +14,5 @@ export * from './foreach.js';
 export * from './workspace.js';
 export * from './pack.js';
 export * from './publish.js';
+export * from './self-update.js';
+export * from './generate-installer.js';

package/lib/commands/self-update.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from '../types/index.js';
+interface SelfUpdateOptions {
+    check?: boolean;
+    force?: boolean;
+    tag: string;
+}
+export declare const selfUpdateCommand: Command<any, SelfUpdateOptions>;
+export {};

package/lib/commands/self-update.js

@@ -0,0 +1,138 @@
+// `gjsify self-update` — refresh the installed @gjsify/cli to a newer release.
+//
+// Walks `import.meta.url` to find this CLI's own package.json (works whether
+// running from `lib/index.js` under Node or the published `dist/cli.gjs.mjs`
+// bundle under GJS). Compares against the latest version on the npm registry
+// (or the requested `--tag`); when an upgrade is needed, re-uses the existing
+// `installPackages` + `linkGlobalBins` pipeline to lay down the new tree at
+// the user-global XDG location.
+//
+// Limitation: only works when the current CLI is installed under
+// `defaultGlobalLayout().prefix` (i.e. via `gjsify install -g` or via the
+// `install.mjs` bootstrap). Installs from `npm install -g @gjsify/cli` land
+// elsewhere and we don't try to chase them — we print a warning and exit.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fetchPackument } from '@gjsify/npm-registry';
+import { installPackages } from '../utils/install-backend.js';
+import { defaultGlobalLayout, linkGlobalBins } from '../utils/install-global.js';
+const PACKAGE_NAME = '@gjsify/cli';
+export const selfUpdateCommand = {
+    command: 'self-update',
+    description: `Update the installed ${PACKAGE_NAME} to the latest release (or pinned --tag).`,
+    builder: (yargs) => yargs
+        .option('check', {
+        description: 'Only check whether a newer version is available; do not install.',
+        type: 'boolean',
+        default: false,
+    })
+        .option('force', {
+        description: 'Reinstall even when the current version already matches the target tag.',
+        type: 'boolean',
+        default: false,
+    })
+        .option('tag', {
+        description: 'npm dist-tag or pinned version to install (e.g. `latest`, `next`, `0.5.0`).',
+        type: 'string',
+        default: 'latest',
+    }),
+    handler: async (args) => {
+        const layout = defaultGlobalLayout();
+        const installedPkgDir = join(layout.prefix, 'node_modules', PACKAGE_NAME);
+        const installedPkgJson = join(installedPkgDir, 'package.json');
+        const currentVersion = readCurrentVersion();
+        const installedAtPrefix = existsSync(installedPkgJson);
+        console.log(`Current ${PACKAGE_NAME}: v${currentVersion ?? '(unknown)'}`);
+        if (!installedAtPrefix) {
+            console.warn(`\nWarning: no @gjsify/cli install found under ${layout.prefix}.\n` +
+                `self-update only manages installs created by install.mjs or \`gjsify install -g\`.\n` +
+                `If you installed via \`npm install -g\`, remove that and use:\n` +
+                `  curl -fsSL https://github.com/gjsify/gjsify/releases/latest/download/install.mjs -o /tmp/g.mjs && gjs -m /tmp/g.mjs && rm /tmp/g.mjs`);
+        }
+        console.log(`Fetching dist-tags for ${PACKAGE_NAME}@${args.tag} ...`);
+        let packument;
+        try {
+            packument = await fetchPackument(PACKAGE_NAME);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Failed to fetch packument: ${msg}`);
+            process.exit(1);
+            return;
+        }
+        const target = resolveTag(packument, args.tag);
+        if (!target) {
+            console.error(`Unknown dist-tag '${args.tag}' on ${PACKAGE_NAME}. ` +
+                `Known tags: ${Object.keys(packument['dist-tags'] ?? {}).join(', ') || '(none)'}`);
+            process.exit(1);
+            return;
+        }
+        console.log(`Latest matching --tag ${args.tag}: v${target}`);
+        if (currentVersion === target && !args.force) {
+            console.log(`Already up to date (v${target}).`);
+            if (!args.check)
+                console.log(`Run with --force to reinstall anyway.`);
+            return;
+        }
+        if (args.check) {
+            console.log(currentVersion
+                ? `Update available: v${currentVersion} → v${target}`
+                : `Install required: → v${target}`);
+            process.exit(1);
+            return;
+        }
+        console.log(`Installing ${PACKAGE_NAME}@${target} ...`);
+        await installPackages({
+            prefix: layout.prefix,
+            specs: [`${PACKAGE_NAME}@${target}`],
+            verbose: false,
+        });
+        const linked = linkGlobalBins([PACKAGE_NAME], layout);
+        if (linked.length === 0) {
+            console.warn('self-update: install completed but no bins were linked — package.json may be missing a `bin` field.');
+        }
+        else {
+            for (const bin of linked) {
+                console.log(`  • ${bin.link}  →  ${bin.target}`);
+            }
+        }
+        console.log(`\nUpdated ${PACKAGE_NAME} to v${target}.`);
+    },
+};
+/**
+ * Resolve the CLI's own `package.json#version`. Walks up from
+ * `import.meta.url` (the bundle file under GJS, or `lib/index.js` under
+ * Node) until it finds a package.json with `name === '@gjsify/cli'`.
+ */
+function readCurrentVersion() {
+    try {
+        const here = fileURLToPath(import.meta.url);
+        let dir = dirname(resolve(here));
+        for (let i = 0; i < 8 && dir !== dirname(dir); i++) {
+            const candidate = join(dir, 'package.json');
+            if (existsSync(candidate)) {
+                const pkg = JSON.parse(readFileSync(candidate, 'utf-8'));
+                if (pkg.name === PACKAGE_NAME && typeof pkg.version === 'string') {
+                    return pkg.version;
+                }
+            }
+            dir = dirname(dir);
+        }
+    }
+    catch {
+        /* not in a recognizable layout */
+    }
+    return null;
+}
+function resolveTag(packument, tag) {
+    const distTags = (packument['dist-tags'] ?? {});
+    if (distTags[tag])
+        return distTags[tag];
+    // Allow pinned versions via `--tag 0.5.0`
+    if (packument.versions && typeof packument.versions === 'object') {
+        if (packument.versions[tag])
+            return tag;
+    }
+    return null;
+}

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, gsettingsCommand as gsettings, flatpakCommand as flatpak, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, } 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, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 // `parseAsync()` instead of `.argv` so the top-level await keeps the
 // process alive until command handlers complete. Under Node this is
@@ -27,6 +27,8 @@ await yargs(hideBin(process.argv))
     .command(workspace.command, workspace.description, workspace.builder, workspace.handler)
     .command(pack.command, pack.description, pack.builder, pack.handler)
     .command(publish.command, publish.description, publish.builder, publish.handler)
+    .command(selfUpdate.command, selfUpdate.description, selfUpdate.builder, selfUpdate.handler)
+    .command(generateInstaller.command, generateInstaller.description, generateInstaller.builder, generateInstaller.handler)
     .demandCommand(1)
     .help()
     .parseAsync();

package/lib/templates/install.mjs.tmpl

@@ -0,0 +1,248 @@
+#!/usr/bin/env -S gjs -m
+/**
+ * gjsify universal installer — bootstraps `@gjsify/cli` (or any GJS app
+ * published to npm) on a system that has only `gjs` (and `curl`/`wget`)
+ * available, without requiring Node.js or `npm`.
+ *
+ * Usage:
+ *   gjs -m install.mjs                    # install / update @gjsify/cli
+ *   gjs -m install.mjs --target @scope/x  # install any other GJS-runnable npm package
+ *   gjs -m install.mjs --tag next         # pick an npm dist-tag or pinned version
+ *   gjs -m install.mjs --force            # reinstall even if already present
+ *   gjs -m install.mjs --help
+ *
+ * How it works (two-stage bootstrap):
+ *   1. Download a small self-contained GJS bundle of the @gjsify/cli
+ *      (`cli.gjs.mjs`) from this repo's GitHub releases. Verify SHA-256.
+ *   2. Spawn that bundle: `gjs -m <bundle> install -g <target>@<tag>`. The
+ *      bundle handles transitive dependency resolution, native prebuilds,
+ *      lockfiles, and the `~/.local/bin` launchers — all the things this
+ *      thin bootstrapper deliberately does NOT re-implement.
+ *
+ * Generated by `gjsify generate-installer` for end-user GJS apps: in that
+ * mode the constants below (BOOTSTRAP_URL, DEFAULT_TARGET, DEFAULT_BIN_NAME)
+ * are pre-substituted to the consumer's package + custom bootstrap URL.
+ *
+ * Test hooks (set by tests/e2e/install-script/run.mjs):
+ *   GJSIFY_INSTALL_BOOTSTRAP_URL  override the cli.gjs.mjs download origin
+ *                                 (accepts file:// for offline tests)
+ *   GJSIFY_INSTALL_BOOTSTRAP_SHA256_URL  override the .sha256 companion URL
+ *                                 (set to empty string to skip SHA-256)
+ *   GJSIFY_GLOBAL_PREFIX          override install prefix (forwarded to cli)
+ *   GJSIFY_GLOBAL_BIN_DIR         override bin dir (forwarded to cli)
+ *   GJSIFY_INSTALL_REGISTRY       override npm registry (forwarded as npm_config_registry)
+ *   GJSIFY_INSTALL_BOOTSTRAP_CACHE  override the bootstrap cache dir
+ */
+
+import GLib from 'gi://GLib';
+import Gio from 'gi://Gio';
+import Soup from 'gi://Soup?version=3.0';
+import system, { exit } from 'system';
+
+Gio._promisify(Soup.Session.prototype, 'send_and_read_async');
+Gio._promisify(Gio.Subprocess.prototype, 'wait_check_async');
+
+// Substituted by `gjsify generate-installer` for end-user apps.
+const DEFAULT_TARGET = '@gjsify/cli';
+const DEFAULT_BIN_NAME = 'gjsify';
+const DEFAULT_BOOTSTRAP_URL =
+    'https://github.com/gjsify/gjsify/releases/latest/download/cli.gjs.mjs';
+const DEFAULT_BOOTSTRAP_SHA256_URL = `${DEFAULT_BOOTSTRAP_URL}.sha256`;
+
+const USER_AGENT = 'gjsify-installer/1.0';
+
+function info(msg) { print(`[gjsify] ${msg}`); }
+function error(msg) { printerr(`[gjsify] ERROR: ${msg}`); }
+
+function parseArgs() {
+    const argv = system?.programArgs ?? [];
+    let target = DEFAULT_TARGET;
+    let tag = 'latest';
+    let force = false;
+    let help = false;
+    let bootstrapUrl = GLib.getenv('GJSIFY_INSTALL_BOOTSTRAP_URL') || DEFAULT_BOOTSTRAP_URL;
+    let bootstrapSha256Url = GLib.getenv('GJSIFY_INSTALL_BOOTSTRAP_SHA256_URL');
+    if (bootstrapSha256Url === null || bootstrapSha256Url === undefined) {
+        bootstrapSha256Url = bootstrapUrl === DEFAULT_BOOTSTRAP_URL
+            ? DEFAULT_BOOTSTRAP_SHA256_URL
+            : `${bootstrapUrl}.sha256`;
+    }
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--force' || a === '-f') force = true;
+        else if (a === '--help' || a === '-h') help = true;
+        else if (a === '--target') target = argv[++i];
+        else if (a.startsWith('--target=')) target = a.slice('--target='.length);
+        else if (a === '--tag') tag = argv[++i];
+        else if (a.startsWith('--tag=')) tag = a.slice('--tag='.length);
+        else if (a === '--bootstrap-url') bootstrapUrl = argv[++i];
+        else if (a.startsWith('--bootstrap-url=')) bootstrapUrl = a.slice('--bootstrap-url='.length);
+    }
+    return { target, tag, force, help, bootstrapUrl, bootstrapSha256Url };
+}
+
+function printUsage() {
+    print(`Usage: gjs -m install.mjs [options]
+
+Installs (or updates) ${DEFAULT_TARGET} into the user-global XDG location,
+using a self-contained GJS bundle of @gjsify/cli as a one-shot bootstrap.
+
+Options:
+  --target <pkg>     npm package to install   (default: ${DEFAULT_TARGET})
+  --tag <tag>        npm dist-tag or version  (default: latest)
+  --force, -f        Reinstall even when present.
+  --bootstrap-url <url>  Override the cli.gjs.mjs download URL.
+  --help, -h         Show this message.
+
+Env vars:
+  GJSIFY_INSTALL_BOOTSTRAP_URL   alternate bootstrap bundle URL (file:// OK)
+  GJSIFY_GLOBAL_PREFIX           install prefix (default: ~/.local/share/gjsify/global)
+  GJSIFY_GLOBAL_BIN_DIR          bin dir       (default: ~/.local/bin)
+  GJSIFY_INSTALL_REGISTRY        npm registry override
+
+Examples:
+  # Install / update the gjsify CLI itself:
+  gjs -m install.mjs
+
+  # Install some other GJS-runnable package from npm:
+  gjs -m install.mjs --target @ts-for-gir/cli
+
+  # Pin a specific version:
+  gjs -m install.mjs --tag 0.4.9
+`);
+}
+
+function checkGjsVersion() {
+    // imports.system.version is packed: major*10000 + minor*100 + micro
+    const v = system?.version;
+    if (typeof v !== 'number') return;
+    const major = Math.floor(v / 10000);
+    const minor = Math.floor((v - major * 10000) / 100);
+    if (major < 1 || (major === 1 && minor < 86)) {
+        error(`gjs ${major}.${minor} is too old — gjsify requires gjs 1.86 or newer.`);
+        error('Install hints:');
+        error('  Fedora 43+:  sudo dnf install gjs');
+        error('  Debian 13+:  sudo apt install gjs');
+        error('  Arch:        sudo pacman -S gjs');
+        exit(1);
+    }
+}
+
+async function fetchBytes(session, url) {
+    if (url.startsWith('file://')) {
+        const path = url.slice('file://'.length);
+        const file = Gio.File.new_for_path(path);
+        const [, bytes] = file.load_contents(null);
+        return bytes;
+    }
+    const message = Soup.Message.new('GET', url);
+    message.request_headers.append('User-Agent', USER_AGENT);
+    const bytes = await session.send_and_read_async(message, GLib.PRIORITY_DEFAULT, null);
+    const status = message.get_status();
+    if (status !== Soup.Status.OK) {
+        throw new Error(`HTTP ${status} from ${url}`);
+    }
+    return bytes.get_data();
+}
+
+function sha256Hex(bytes) {
+    const checksum = GLib.Checksum.new(GLib.ChecksumType.SHA256);
+    checksum.update(bytes);
+    return checksum.get_string();
+}
+
+function cacheDir() {
+    const override = GLib.getenv('GJSIFY_INSTALL_BOOTSTRAP_CACHE');
+    if (override) return override;
+    const xdg = GLib.getenv('XDG_CACHE_HOME') ||
+        GLib.build_filenamev([GLib.get_home_dir(), '.cache']);
+    return GLib.build_filenamev([xdg, 'gjsify', 'bootstrap']);
+}
+
+function ensureDir(dir) {
+    Gio.File.new_for_path(dir).make_directory_with_parents(null);
+}
+
+function writeBytes(path, bytes) {
+    Gio.File.new_for_path(path).replace_contents(
+        bytes, null, false, Gio.FileCreateFlags.REPLACE_DESTINATION, null,
+    );
+}
+
+async function downloadBootstrap(session, bootstrapUrl, sha256Url) {
+    info(`Downloading bootstrap from ${bootstrapUrl} ...`);
+    const bundleBytes = await fetchBytes(session, bootstrapUrl);
+    if (sha256Url && sha256Url !== '') {
+        info('Verifying SHA-256 ...');
+        let sumExpected;
+        try {
+            const sumBytes = await fetchBytes(session, sha256Url);
+            sumExpected = new TextDecoder().decode(sumBytes).trim().split(/\s+/)[0];
+        } catch (err) {
+            error(`Could not fetch ${sha256Url} — skipping verification: ${err.message}`);
+        }
+        if (sumExpected) {
+            const sumActual = sha256Hex(bundleBytes);
+            if (sumExpected.toLowerCase() !== sumActual.toLowerCase()) {
+                error(`SHA-256 mismatch: expected ${sumExpected}, got ${sumActual}`);
+                exit(1);
+            }
+        }
+    }
+    const dir = cacheDir();
+    try { ensureDir(dir); } catch { /* exists */ }
+    const bundlePath = GLib.build_filenamev([dir, 'cli.gjs.mjs']);
+    writeBytes(bundlePath, bundleBytes);
+    info(`Bootstrap cached at ${bundlePath} (${bundleBytes.length} bytes)`);
+    return bundlePath;
+}
+
+function buildSpec(target, tag) {
+    if (!tag || tag === 'latest') return target;
+    return `${target}@${tag}`;
+}
+
+async function runInstall(bundlePath, spec) {
+    // `gjsify install -g <spec>` is always idempotent — it rewrites the tree
+    // unconditionally. There is no separate "force" flag to forward; the
+    // installer's own `--force` is satisfied by the fact that we always
+    // re-download the bootstrap and re-invoke the CLI.
+    info(`Running: gjs -m <bootstrap> install -g ${spec}`);
+    const argv = ['gjs', '-m', bundlePath, 'install', '-g', spec];
+    // Forward env vars verbatim so override paths set by tests / power-users
+    // reach the spawned CLI.
+    const launcher = new Gio.SubprocessLauncher({
+        flags: Gio.SubprocessFlags.NONE,
+    });
+    const proc = launcher.spawnv(argv);
+    await proc.wait_check_async(null);
+}
+
+async function main() {
+    const opts = parseArgs();
+    if (opts.help) { printUsage(); exit(0); }
+    checkGjsVersion();
+
+    const session = new Soup.Session();
+    let bundlePath;
+    try {
+        bundlePath = await downloadBootstrap(session, opts.bootstrapUrl, opts.bootstrapSha256Url);
+    } catch (err) {
+        error(`Bootstrap download failed: ${err.message}`);
+        exit(1);
+    }
+
+    const spec = buildSpec(opts.target, opts.tag);
+    try {
+        await runInstall(bundlePath, spec);
+    } catch (err) {
+        error(`Install failed: ${err.message}`);
+        exit(1);
+    }
+
+    info('');
+    info(`Installed ${spec}`);
+    info(`Run: ${DEFAULT_BIN_NAME} --help`);
+}
+
+await main();

package/lib/utils/install-global.js

@@ -91,7 +91,19 @@ export function linkGlobalBins(packageNames, layout) {
             // Inline `${target}` directly — this file is rewritten on every
             // install, paths are user-owned, and POSIX `sh` quoting via
             // single-quotes plus `'\''` for embedded quotes is well-defined.
-            const launcher = `#!/bin/sh\nexec ${shQuote(targetAbs)} "$@"\n`;
+            //
+            // `.gjs.mjs` and `.mjs` bins are GJS-runnable bundles; we wrap them
+            // with `gjs -m` rather than direct-exec because not every published
+            // bundle ships a `#!/usr/bin/env -S gjs -m` shebang (the CLI's
+            // build:gjs-bundle script gained the `--shebang` flag late in
+            // Phase F, but published <=0.4.x tarballs predate it). Direct-
+            // exec'ing a shebang-less .mjs file falls back to /bin/sh which
+            // then tries to parse JavaScript as shell. Plain Node scripts
+            // with shebangs (lib/index.js) keep the direct-exec path.
+            const isGjsBundle = targetAbs.endsWith('.gjs.mjs') || targetAbs.endsWith('.mjs');
+            const launcher = isGjsBundle
+                ? `#!/bin/sh\nexec gjs -m ${shQuote(targetAbs)} "$@"\n`
+                : `#!/bin/sh\nexec ${shQuote(targetAbs)} "$@"\n`;
             fs.writeFileSync(linkPath, launcher);
             fs.chmodSync(linkPath, 0o755);
             created.push({ name: binName, target: targetAbs, link: linkPath });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.4.9",
+    "version": "0.4.10",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -23,8 +23,8 @@
         "clear": "rm -rf lib dist tsconfig.tsbuildinfo || exit 0",
         "check": "tsc --noEmit",
         "start": "node lib/index.js",
-        "build": "tsc && gjsify run chmod",
-        "build:gjs-bundle": "node lib/index.js build src/index.ts --app gjs --outfile dist/cli.gjs.mjs",
+        "build": "tsc && mkdir -p lib/templates && cp -L src/templates/install.mjs.tmpl lib/templates/install.mjs.tmpl && gjsify run chmod",
+        "build:gjs-bundle": "node lib/index.js build src/index.ts --app gjs --outfile dist/cli.gjs.mjs --shebang",
         "chmod": "chmod +x ./lib/index.js",
         "build:test:node": "node lib/index.js build src/test.mts --app node --outfile dist/test.node.mjs",
         "test:node": "node dist/test.node.mjs",
@@ -37,18 +37,18 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.4.9",
-        "@gjsify/create-app": "^0.4.9",
-        "@gjsify/node-globals": "^0.4.9",
-        "@gjsify/node-polyfills": "^0.4.9",
-        "@gjsify/npm-registry": "^0.4.9",
-        "@gjsify/resolve-npm": "^0.4.9",
-        "@gjsify/rolldown-plugin-gjsify": "^0.4.9",
-        "@gjsify/rolldown-plugin-pnp": "^0.4.9",
-        "@gjsify/semver": "^0.4.9",
-        "@gjsify/tar": "^0.4.9",
-        "@gjsify/web-polyfills": "^0.4.9",
-        "@gjsify/workspace": "^0.4.9",
+        "@gjsify/buffer": "^0.4.10",
+        "@gjsify/create-app": "^0.4.10",
+        "@gjsify/node-globals": "^0.4.10",
+        "@gjsify/node-polyfills": "^0.4.10",
+        "@gjsify/npm-registry": "^0.4.10",
+        "@gjsify/resolve-npm": "^0.4.10",
+        "@gjsify/rolldown-plugin-gjsify": "^0.4.10",
+        "@gjsify/rolldown-plugin-pnp": "^0.4.10",
+        "@gjsify/semver": "^0.4.10",
+        "@gjsify/tar": "^0.4.10",
+        "@gjsify/web-polyfills": "^0.4.10",
+        "@gjsify/workspace": "^0.4.10",
         "cosmiconfig": "^9.0.1",
         "get-tsconfig": "^4.14.0",
         "pkg-types": "^2.3.1",
@@ -56,12 +56,12 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.4.9",
+        "@gjsify/unit": "^0.4.10",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/rolldown-native": "^0.4.9"
+        "@gjsify/rolldown-native": "^0.4.10"
     },
     "peerDependenciesMeta": {
         "@gjsify/rolldown-native": {