@gjsify/cli 0.1.10 → 0.1.12

package/lib/actions/build.d.ts

@@ -26,6 +26,11 @@ export declare class BuildAction {
      * The auto path is handled in `buildApp` via the two-pass build.
      */
     private resolveGlobalsInject;
+    /**
+     * Post-processing: prepend GJS shebang and mark the output file executable.
+     * Only runs for GJS app builds with a resolvable single outfile.
+     */
+    private applyShebang;
     /** Application mode */
     buildApp(app?: App): Promise<BuildResult<{
         format: "esm" | "cjs";

package/lib/actions/build.js

@@ -1,7 +1,9 @@
 import { build } from 'esbuild';
 import { gjsifyPlugin } from '@gjsify/esbuild-plugin-gjsify';
 import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals } from '@gjsify/esbuild-plugin-gjsify/globals';
-import { dirname, extname } from 'path';
+import { dirname, extname } from 'node:path';
+import { chmod, readFile, writeFile } from 'node:fs/promises';
+const GJS_SHEBANG = '#!/usr/bin/env -S gjs -m\n';
 export class BuildAction {
     configData;
     constructor(configData = {}) {
@@ -105,6 +107,28 @@ export class BuildAction {
         }
         return injectPath ?? undefined;
     }
+    /**
+     * Post-processing: prepend GJS shebang and mark the output file executable.
+     * Only runs for GJS app builds with a resolvable single outfile.
+     */
+    async applyShebang(outfile, verbose) {
+        if (!outfile) {
+            if (verbose)
+                console.warn('[gjsify] --shebang skipped: no single outfile (use --outfile for GJS executables)');
+            return;
+        }
+        const content = await readFile(outfile, 'utf-8');
+        if (content.startsWith('#!')) {
+            if (verbose)
+                console.debug(`[gjsify] --shebang skipped: ${outfile} already starts with a shebang`);
+        }
+        else {
+            await writeFile(outfile, GJS_SHEBANG + content);
+        }
+        await chmod(outfile, 0o755);
+        if (verbose)
+            console.debug(`[gjsify] --shebang: wrote shebang + chmod 0o755 to ${outfile}`);
+    }
     /** Application mode */
     async buildApp(app = 'gjs') {
         const { verbose, esbuild, typescript, exclude, library: pgk } = this.configData;
@@ -140,6 +164,9 @@ export class BuildAction {
                     }),
                 ],
             });
+            if (app === 'gjs' && this.configData.shebang) {
+                await this.applyShebang(esbuild?.outfile, verbose);
+            }
             return [result];
         }
         // --- Explicit list (no `auto` token) or none mode ---
@@ -157,6 +184,9 @@ export class BuildAction {
                 }),
             ]
         });
+        if (app === 'gjs' && this.configData.shebang) {
+            await this.applyShebang(esbuild?.outfile, verbose);
+        }
         return [result];
     }
     async start(buildType = { app: 'gjs' }) {

package/lib/commands/build.js

@@ -91,6 +91,12 @@ export const buildCommand = {
             type: 'string',
             normalize: true,
             default: 'auto'
+        })
+            .option('shebang', {
+            description: "Prepend a `#!/usr/bin/env -S gjs -m` shebang to the output and mark it executable (chmod 755). Only applies to GJS app builds with a single --outfile.",
+            type: 'boolean',
+            normalize: true,
+            default: false
         });
     },
     handler: async (args) => {

package/lib/commands/create.d.ts

@@ -1,6 +1,9 @@
 import type { Command } from '../types/index.js';
 interface CreateOptions {
     'project-name': string;
+    template?: string;
+    force: boolean;
+    install: boolean;
 }
 export declare const createCommand: Command<any, CreateOptions>;
 export {};

package/lib/commands/create.js

@@ -1,15 +1,52 @@
-import { createProject } from '@gjsify/create-app';
+import { createProject, discoverTemplates } from '@gjsify/create-app';
+import { promptTemplate } from '@gjsify/create-app/prompt';
 export const createCommand = {
     command: 'create [project-name]',
     description: 'Scaffold a new Gjsify project in a new directory.',
     builder: (yargs) => {
-        return yargs.positional('project-name', {
+        const templates = discoverTemplates();
+        const templateChoices = templates.map((t) => t.name);
+        return yargs
+            .positional('project-name', {
             describe: 'Name of the project directory to create',
             type: 'string',
             default: 'my-gjs-app',
+        })
+            .option('template', {
+            alias: 't',
+            describe: 'Template to scaffold from',
+            type: 'string',
+            choices: templateChoices.length > 0 ? templateChoices : undefined,
+        })
+            .option('force', {
+            alias: 'f',
+            describe: 'Scaffold into a non-empty directory',
+            type: 'boolean',
+            default: false,
+        })
+            .option('install', {
+            describe: 'Run npm install after scaffolding',
+            type: 'boolean',
+            default: false,
         });
     },
     handler: async (args) => {
-        await createProject(args['project-name']);
+        let template = args.template;
+        if (!template) {
+            const templates = discoverTemplates();
+            if (!process.stdin.isTTY) {
+                const list = templates.map((t) => t.name).join(', ');
+                console.error(`Error: --template is required in non-interactive mode. Available templates: ${list || '(none)'}`);
+                process.exit(1);
+            }
+            const picked = await promptTemplate(templates);
+            template = picked.name;
+        }
+        await createProject({
+            projectName: args['project-name'],
+            template,
+            force: args.force,
+            install: args.install,
+        });
     },
 };

package/lib/commands/gettext.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from '../types/index.js';
+type GettextFormat = 'mo' | 'xml' | 'desktop' | 'json';
+interface GettextOptions {
+    poDir: string;
+    outDir: string;
+    domain: string;
+    format?: GettextFormat;
+    metainfo?: string;
+    filename?: string;
+    removeXmlComments?: boolean;
+    verbose?: boolean;
+}
+export declare const gettextCommand: Command<any, GettextOptions>;
+export {};

package/lib/commands/gettext.js

@@ -0,0 +1,201 @@
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+async function listLanguages(poDir) {
+    const entries = await readdir(poDir);
+    return entries
+        .filter((name) => name.endsWith('.po') && !name.startsWith('.'))
+        .map((name) => name.slice(0, -3))
+        .sort();
+}
+function stripXmlComments(source) {
+    return source.replace(/<!--[\s\S]*?-->/g, '');
+}
+async function ensureDir(path) {
+    await mkdir(path, { recursive: true });
+}
+async function fileExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function compileBulkXml(opts) {
+    const outputFile = join(opts.outDir, opts.filename);
+    await ensureDir(opts.outDir);
+    const args = [
+        `--output-file=${outputFile}`,
+        '--xml',
+        `--template=${opts.template}`,
+        '-d',
+        opts.poDir,
+    ];
+    if (opts.verbose) {
+        console.log(`[gjsify gettext] msgfmt ${args.join(' ')}`);
+    }
+    await execFileAsync('msgfmt', args);
+    if (opts.removeXmlComments) {
+        const content = await readFile(outputFile, 'utf-8');
+        await writeFile(outputFile, stripXmlComments(content));
+    }
+    if (opts.verbose) {
+        console.log(`[gjsify gettext] wrote ${outputFile}`);
+    }
+}
+async function compilePerLanguage(opts) {
+    const languages = await listLanguages(opts.poDir);
+    if (languages.length === 0) {
+        console.warn(`[gjsify gettext] no .po files found in ${opts.poDir}`);
+        return;
+    }
+    for (const lang of languages) {
+        const poFile = join(opts.poDir, `${lang}.po`);
+        const langDir = opts.format === 'mo'
+            ? join(opts.outDir, lang, 'LC_MESSAGES')
+            : join(opts.outDir, lang);
+        await ensureDir(langDir);
+        const outputFile = join(langDir, opts.filename);
+        // msgfmt produces the binary .mo format by default — there is no
+        // `--mo` flag (only --xml, --desktop, --properties-output, ...).
+        const args = [`--output-file=${outputFile}`];
+        if (opts.format !== 'mo') {
+            args.push(`--${opts.format}`);
+        }
+        args.push(poFile);
+        if (opts.verbose) {
+            console.log(`[gjsify gettext] msgfmt ${args.join(' ')}`);
+        }
+        await execFileAsync('msgfmt', args);
+    }
+    if (opts.verbose) {
+        console.log(`[gjsify gettext] compiled ${languages.length} language(s) into ${opts.outDir}`);
+    }
+}
+function defaultFilename(domain, format, metainfoTemplate) {
+    switch (format) {
+        case 'mo':
+            return `${domain}.mo`;
+        case 'json':
+            return `${domain}.json`;
+        case 'desktop':
+            return `${domain}.desktop`;
+        case 'xml': {
+            // Mirror the template filename but without the trailing `.in` (convention for
+            // pre-processed metainfo templates: `org.foo.Bar.metainfo.xml.in`).
+            if (metainfoTemplate) {
+                const base = metainfoTemplate.replace(/\.in$/, '');
+                const slash = base.lastIndexOf('/');
+                return slash >= 0 ? base.slice(slash + 1) : base;
+            }
+            return `${domain}.xml`;
+        }
+    }
+}
+export const gettextCommand = {
+    command: 'gettext <poDir> <outDir>',
+    description: 'Compile gettext .po files to .mo (per-language locale tree) or substitute a metainfo template via msgfmt --xml.',
+    builder: (yargs) => {
+        return yargs
+            .positional('poDir', {
+            description: 'Directory containing <lang>.po files',
+            type: 'string',
+            normalize: true,
+            demandOption: true,
+        })
+            .positional('outDir', {
+            description: 'Output directory (locale tree for --format=mo, plain dir for xml/desktop/json)',
+            type: 'string',
+            normalize: true,
+            demandOption: true,
+        })
+            .option('domain', {
+            description: 'Text domain / application ID (e.g. `org.pixelrpg.maker`)',
+            type: 'string',
+            normalize: true,
+            demandOption: true,
+        })
+            .option('format', {
+            description: 'Output format',
+            type: 'string',
+            choices: ['mo', 'xml', 'desktop', 'json'],
+            default: 'mo',
+        })
+            .option('metainfo', {
+            description: 'For --format=xml: path to the template (`.metainfo.xml.in`) used as msgfmt --template',
+            type: 'string',
+            normalize: true,
+        })
+            .option('filename', {
+            description: 'Override the output filename (defaults to <domain>.<ext>)',
+            type: 'string',
+            normalize: true,
+        })
+            .option('remove-xml-comments', {
+            description: 'For --format=xml: strip XML comments from the compiled output',
+            type: 'boolean',
+            default: true,
+        })
+            .option('verbose', {
+            description: 'Print each msgfmt invocation',
+            type: 'boolean',
+            default: false,
+        });
+    },
+    handler: async (args) => {
+        const poDir = resolve(args.poDir);
+        const outDir = resolve(args.outDir);
+        const domain = args.domain;
+        const format = args.format ?? 'mo';
+        const metainfo = args.metainfo ? resolve(args.metainfo) : undefined;
+        const filename = args.filename ?? defaultFilename(domain, format, metainfo);
+        const verbose = !!args.verbose;
+        const removeXmlComments = !!args['remove-xml-comments'];
+        if (!(await fileExists(poDir))) {
+            console.error(`[gjsify gettext] PO directory does not exist: ${poDir}`);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            if (format === 'xml' && metainfo) {
+                await compileBulkXml({
+                    poDir,
+                    outDir,
+                    domain,
+                    template: metainfo,
+                    filename,
+                    removeXmlComments,
+                    verbose,
+                });
+            }
+            else {
+                if (format === 'xml') {
+                    console.warn('[gjsify gettext] --format=xml without --metainfo: falling back to per-language XML files');
+                }
+                await compilePerLanguage({
+                    poDir,
+                    outDir,
+                    domain,
+                    format,
+                    filename,
+                    verbose,
+                });
+            }
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT') {
+                console.error('[gjsify gettext] msgfmt not found. Install it via your distro (package: gettext).');
+            }
+            else {
+                if (err?.stderr)
+                    process.stderr.write(err.stderr);
+                console.error(`[gjsify gettext] msgfmt failed${err?.code !== undefined ? ` (exit ${err.code})` : ''}`);
+            }
+            process.exitCode = typeof err?.code === 'number' ? err.code : 1;
+        }
+    },
+};

package/lib/commands/gresource.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from '../types/index.js';
+interface GResourceOptions {
+    xml: string;
+    sourcedir?: string;
+    target?: string;
+    verbose?: boolean;
+}
+export declare const gresourceCommand: Command<any, GResourceOptions>;
+export {};

package/lib/commands/gresource.js

@@ -0,0 +1,82 @@
+import { execFile } from 'node:child_process';
+import { mkdir } from 'node:fs/promises';
+import { basename, dirname, extname, resolve } from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/**
+ * Derive a default `.gresource` target path from the XML descriptor.
+ * `foo.gresource.xml` → `foo.gresource` in the same directory.
+ */
+function defaultTargetFor(xmlPath) {
+    const ext = extname(xmlPath);
+    const stem = basename(xmlPath, ext);
+    return resolve(dirname(xmlPath), stem);
+}
+export const gresourceCommand = {
+    command: 'gresource <xml>',
+    description: 'Compile a GResource XML descriptor into a binary .gresource bundle (wraps `glib-compile-resources`).',
+    builder: (yargs) => {
+        return yargs
+            .positional('xml', {
+            description: 'Path to the .gresource.xml descriptor',
+            type: 'string',
+            normalize: true,
+            demandOption: true,
+        })
+            .option('sourcedir', {
+            description: 'Directory containing the resource files referenced by <xml>',
+            type: 'string',
+            normalize: true,
+        })
+            .option('target', {
+            alias: 't',
+            description: 'Output .gresource file (default: <xml-without-.xml> next to <xml>)',
+            type: 'string',
+            normalize: true,
+        })
+            .option('verbose', {
+            description: 'Print the underlying glib-compile-resources invocation',
+            type: 'boolean',
+            default: false,
+        });
+    },
+    handler: async (args) => {
+        const xmlPath = resolve(args.xml);
+        const target = args.target ? resolve(args.target) : defaultTargetFor(xmlPath);
+        const sourcedir = args.sourcedir
+            ? resolve(args.sourcedir)
+            : dirname(xmlPath);
+        const cmdArgs = [
+            `--sourcedir=${sourcedir}`,
+            `--target=${target}`,
+            xmlPath,
+        ];
+        if (args.verbose) {
+            console.log(`[gjsify gresource] glib-compile-resources ${cmdArgs.join(' ')}`);
+        }
+        // Ensure the target directory exists — glib-compile-resources writes
+        // a temporary file next to the target and fails with ENOENT otherwise.
+        await mkdir(dirname(target), { recursive: true });
+        try {
+            const { stdout, stderr } = await execFileAsync('glib-compile-resources', cmdArgs);
+            if (stdout)
+                process.stdout.write(stdout);
+            if (stderr)
+                process.stderr.write(stderr);
+            if (args.verbose) {
+                console.log(`[gjsify gresource] wrote ${target}`);
+            }
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT') {
+                console.error('[gjsify gresource] glib-compile-resources 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 gresource] glib-compile-resources failed${err?.code !== undefined ? ` (exit ${err.code})` : ''}`);
+            }
+            process.exitCode = typeof err?.code === 'number' ? err.code : 1;
+        }
+    },
+};

package/lib/commands/index.d.ts

@@ -4,3 +4,5 @@ export * from './info.js';
 export * from './check.js';
 export * from './showcase.js';
 export * from './create.js';
+export * from './gresource.js';
+export * from './gettext.js';

package/lib/commands/index.js

@@ -4,3 +4,5 @@ export * from './info.js';
 export * from './check.js';
 export * from './showcase.js';
 export * from './create.js';
+export * from './gresource.js';
+export * from './gettext.js';

package/lib/config.js

@@ -71,6 +71,8 @@ export class Config {
             configData.consoleShim = cliArgs.consoleShim;
         if (cliArgs.globals !== undefined)
             configData.globals = cliArgs.globals;
+        if (cliArgs.shebang !== undefined)
+            configData.shebang = cliArgs.shebang;
         merge(configData.library ??= {}, pkg, configData.library);
         merge(configData.typescript ??= {}, tsConfig, configData.typescript);
         merge(configData.esbuild ??= {}, {

package/lib/index.js

@@ -1,17 +1,18 @@
 #!/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 } 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, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 void yargs(hideBin(process.argv))
     .scriptName(APP_NAME)
     .strict()
-    // .usage(Config.usage)
     .command(create.command, create.description, create.builder, create.handler)
     .command(build.command, build.description, build.builder, build.handler)
     .command(run.command, run.description, run.builder, run.handler)
     .command(info.command, info.description, info.builder, info.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)
+    .command(gettext.command, gettext.description, gettext.builder, gettext.handler)
     .demandCommand(1)
     .help().argv;

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

@@ -54,4 +54,10 @@ export interface CliBuildOptions {
      * bundle. Only applies to GJS app builds.
      */
     globals?: string;
+    /**
+     * Prepend a `#!/usr/bin/env -S gjs -m` shebang to the output file and mark
+     * it executable (chmod 755). Only applies to GJS app builds with a single
+     * `--outfile`. Default: false.
+     */
+    shebang?: boolean;
 }

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

@@ -18,4 +18,8 @@ export interface ConfigData {
      * See CliBuildOptions for format.
      */
     globals?: string;
+    /**
+     * Prepend GJS shebang to output and mark executable. See CliBuildOptions.
+     */
+    shebang?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/cli",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "CLI for Gjsify",
   "type": "module",
   "main": "lib/index.js",
@@ -23,18 +23,19 @@
     "cli"
   ],
   "dependencies": {
-    "@gjsify/create-app": "^0.1.10",
-    "@gjsify/esbuild-plugin-gjsify": "^0.1.10",
-    "@gjsify/example-dom-canvas2d-fireworks": "^0.1.10",
-    "@gjsify/example-dom-excalibur-jelly-jumper": "^0.1.10",
-    "@gjsify/example-dom-three-geometry-teapot": "^0.1.10",
-    "@gjsify/example-dom-three-postprocessing-pixel": "^0.1.10",
-    "@gjsify/example-node-express-webserver": "^0.1.10",
-    "@gjsify/node-polyfills": "^0.1.10",
-    "@gjsify/web-polyfills": "^0.1.10",
+    "@gjsify/create-app": "^0.1.12",
+    "@gjsify/esbuild-plugin-gjsify": "^0.1.12",
+    "@gjsify/example-dom-adwaita-package-builder": "^0.1.12",
+    "@gjsify/example-dom-canvas2d-fireworks": "^0.1.12",
+    "@gjsify/example-dom-excalibur-jelly-jumper": "^0.1.12",
+    "@gjsify/example-dom-three-geometry-teapot": "^0.1.12",
+    "@gjsify/example-dom-three-postprocessing-pixel": "^0.1.12",
+    "@gjsify/example-node-express-webserver": "^0.1.12",
+    "@gjsify/node-polyfills": "^0.1.12",
+    "@gjsify/web-polyfills": "^0.1.12",
     "cosmiconfig": "^9.0.1",
     "esbuild": "^0.28.0",
-    "get-tsconfig": "^4.13.7",
+    "get-tsconfig": "^4.14.0",
     "pkg-types": "^2.3.0",
     "yargs": "^18.0.0"
   },

package/src/actions/build.ts

@@ -3,7 +3,10 @@ import type { App } from '@gjsify/esbuild-plugin-gjsify';
 import { build, BuildOptions, BuildResult } from 'esbuild';
 import { gjsifyPlugin } from '@gjsify/esbuild-plugin-gjsify';
 import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals } from '@gjsify/esbuild-plugin-gjsify/globals';
-import { dirname, extname } from 'path';
+import { dirname, extname } from 'node:path';
+import { chmod, readFile, writeFile } from 'node:fs/promises';
+
+const GJS_SHEBANG = '#!/usr/bin/env -S gjs -m\n';
 
 export class BuildAction {
     constructor(readonly configData: ConfigData = {}) {
@@ -123,6 +126,26 @@ export class BuildAction {
         return injectPath ?? undefined;
     }
 
+    /**
+     * Post-processing: prepend GJS shebang and mark the output file executable.
+     * Only runs for GJS app builds with a resolvable single outfile.
+     */
+    private async applyShebang(outfile: string | undefined, verbose: boolean | undefined): Promise<void> {
+        if (!outfile) {
+            if (verbose) console.warn('[gjsify] --shebang skipped: no single outfile (use --outfile for GJS executables)');
+            return;
+        }
+
+        const content = await readFile(outfile, 'utf-8');
+        if (content.startsWith('#!')) {
+            if (verbose) console.debug(`[gjsify] --shebang skipped: ${outfile} already starts with a shebang`);
+        } else {
+            await writeFile(outfile, GJS_SHEBANG + content);
+        }
+        await chmod(outfile, 0o755);
+        if (verbose) console.debug(`[gjsify] --shebang: wrote shebang + chmod 0o755 to ${outfile}`);
+    }
+
     /** Application mode */
     async buildApp(app: App = 'gjs') {
 
@@ -172,6 +195,10 @@ export class BuildAction {
                 ],
             });
 
+            if (app === 'gjs' && this.configData.shebang) {
+                await this.applyShebang(esbuild?.outfile, verbose);
+            }
+
             return [result];
         }
 
@@ -192,6 +219,10 @@ export class BuildAction {
             ]
         });
 
+        if (app === 'gjs' && this.configData.shebang) {
+            await this.applyShebang(esbuild?.outfile, verbose);
+        }
+
         return [result];
     }
 

package/src/commands/build.ts

@@ -94,6 +94,12 @@ export const buildCommand: Command<any, CliBuildOptions> = {
                 normalize: true,
                 default: 'auto'
             })
+            .option('shebang', {
+                description: "Prepend a `#!/usr/bin/env -S gjs -m` shebang to the output and mark it executable (chmod 755). Only applies to GJS app builds with a single --outfile.",
+                type: 'boolean',
+                normalize: true,
+                default: false
+            })
     },
     handler: async (args) => {
         const config = new Config();

package/src/commands/create.ts

@@ -1,21 +1,63 @@
-import { createProject } from '@gjsify/create-app';
+import { createProject, discoverTemplates } from '@gjsify/create-app';
+import { promptTemplate } from '@gjsify/create-app/prompt';
 import type { Command } from '../types/index.js';
 
 interface CreateOptions {
     'project-name': string;
+    template?: string;
+    force: boolean;
+    install: boolean;
 }
 
 export const createCommand: Command<any, CreateOptions> = {
     command: 'create [project-name]',
     description: 'Scaffold a new Gjsify project in a new directory.',
     builder: (yargs) => {
-        return yargs.positional('project-name', {
-            describe: 'Name of the project directory to create',
-            type: 'string',
-            default: 'my-gjs-app',
-        });
+        const templates = discoverTemplates();
+        const templateChoices = templates.map((t) => t.name);
+        return yargs
+            .positional('project-name', {
+                describe: 'Name of the project directory to create',
+                type: 'string',
+                default: 'my-gjs-app',
+            })
+            .option('template', {
+                alias: 't',
+                describe: 'Template to scaffold from',
+                type: 'string',
+                choices: templateChoices.length > 0 ? templateChoices : undefined,
+            })
+            .option('force', {
+                alias: 'f',
+                describe: 'Scaffold into a non-empty directory',
+                type: 'boolean',
+                default: false,
+            })
+            .option('install', {
+                describe: 'Run npm install after scaffolding',
+                type: 'boolean',
+                default: false,
+            });
     },
     handler: async (args) => {
-        await createProject(args['project-name']);
+        let template = args.template;
+        if (!template) {
+            const templates = discoverTemplates();
+            if (!process.stdin.isTTY) {
+                const list = templates.map((t) => t.name).join(', ');
+                console.error(
+                    `Error: --template is required in non-interactive mode. Available templates: ${list || '(none)'}`,
+                );
+                process.exit(1);
+            }
+            const picked = await promptTemplate(templates);
+            template = picked.name;
+        }
+        await createProject({
+            projectName: args['project-name'],
+            template,
+            force: args.force,
+            install: args.install,
+        });
     },
 };

package/src/commands/gettext.ts

@@ -0,0 +1,258 @@
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import type { Command } from '../types/index.js';
+
+const execFileAsync = promisify(execFile);
+
+type GettextFormat = 'mo' | 'xml' | 'desktop' | 'json';
+
+interface GettextOptions {
+    poDir: string;
+    outDir: string;
+    domain: string;
+    format?: GettextFormat;
+    metainfo?: string;
+    filename?: string;
+    removeXmlComments?: boolean;
+    verbose?: boolean;
+}
+
+async function listLanguages(poDir: string): Promise<string[]> {
+    const entries = await readdir(poDir);
+    return entries
+        .filter((name) => name.endsWith('.po') && !name.startsWith('.'))
+        .map((name) => name.slice(0, -3))
+        .sort();
+}
+
+function stripXmlComments(source: string): string {
+    return source.replace(/<!--[\s\S]*?-->/g, '');
+}
+
+async function ensureDir(path: string): Promise<void> {
+    await mkdir(path, { recursive: true });
+}
+
+async function fileExists(path: string): Promise<boolean> {
+    try {
+        await stat(path);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+async function compileBulkXml(opts: {
+    poDir: string;
+    outDir: string;
+    domain: string;
+    template: string;
+    filename: string;
+    removeXmlComments: boolean;
+    verbose: boolean;
+}): Promise<void> {
+    const outputFile = join(opts.outDir, opts.filename);
+    await ensureDir(opts.outDir);
+
+    const args = [
+        `--output-file=${outputFile}`,
+        '--xml',
+        `--template=${opts.template}`,
+        '-d',
+        opts.poDir,
+    ];
+
+    if (opts.verbose) {
+        console.log(`[gjsify gettext] msgfmt ${args.join(' ')}`);
+    }
+
+    await execFileAsync('msgfmt', args);
+
+    if (opts.removeXmlComments) {
+        const content = await readFile(outputFile, 'utf-8');
+        await writeFile(outputFile, stripXmlComments(content));
+    }
+
+    if (opts.verbose) {
+        console.log(`[gjsify gettext] wrote ${outputFile}`);
+    }
+}
+
+async function compilePerLanguage(opts: {
+    poDir: string;
+    outDir: string;
+    domain: string;
+    format: GettextFormat;
+    filename: string;
+    verbose: boolean;
+}): Promise<void> {
+    const languages = await listLanguages(opts.poDir);
+    if (languages.length === 0) {
+        console.warn(`[gjsify gettext] no .po files found in ${opts.poDir}`);
+        return;
+    }
+
+    for (const lang of languages) {
+        const poFile = join(opts.poDir, `${lang}.po`);
+        const langDir =
+            opts.format === 'mo'
+                ? join(opts.outDir, lang, 'LC_MESSAGES')
+                : join(opts.outDir, lang);
+        await ensureDir(langDir);
+        const outputFile = join(langDir, opts.filename);
+
+        // msgfmt produces the binary .mo format by default — there is no
+        // `--mo` flag (only --xml, --desktop, --properties-output, ...).
+        const args = [`--output-file=${outputFile}`];
+        if (opts.format !== 'mo') {
+            args.push(`--${opts.format}`);
+        }
+        args.push(poFile);
+
+        if (opts.verbose) {
+            console.log(`[gjsify gettext] msgfmt ${args.join(' ')}`);
+        }
+
+        await execFileAsync('msgfmt', args);
+    }
+
+    if (opts.verbose) {
+        console.log(
+            `[gjsify gettext] compiled ${languages.length} language(s) into ${opts.outDir}`,
+        );
+    }
+}
+
+function defaultFilename(domain: string, format: GettextFormat, metainfoTemplate?: string): string {
+    switch (format) {
+        case 'mo':
+            return `${domain}.mo`;
+        case 'json':
+            return `${domain}.json`;
+        case 'desktop':
+            return `${domain}.desktop`;
+        case 'xml': {
+            // Mirror the template filename but without the trailing `.in` (convention for
+            // pre-processed metainfo templates: `org.foo.Bar.metainfo.xml.in`).
+            if (metainfoTemplate) {
+                const base = metainfoTemplate.replace(/\.in$/, '');
+                const slash = base.lastIndexOf('/');
+                return slash >= 0 ? base.slice(slash + 1) : base;
+            }
+            return `${domain}.xml`;
+        }
+    }
+}
+
+export const gettextCommand: Command<any, GettextOptions> = {
+    command: 'gettext <poDir> <outDir>',
+    description:
+        'Compile gettext .po files to .mo (per-language locale tree) or substitute a metainfo template via msgfmt --xml.',
+    builder: (yargs) => {
+        return yargs
+            .positional('poDir', {
+                description: 'Directory containing <lang>.po files',
+                type: 'string',
+                normalize: true,
+                demandOption: true,
+            })
+            .positional('outDir', {
+                description:
+                    'Output directory (locale tree for --format=mo, plain dir for xml/desktop/json)',
+                type: 'string',
+                normalize: true,
+                demandOption: true,
+            })
+            .option('domain', {
+                description: 'Text domain / application ID (e.g. `org.pixelrpg.maker`)',
+                type: 'string',
+                normalize: true,
+                demandOption: true,
+            })
+            .option('format', {
+                description: 'Output format',
+                type: 'string',
+                choices: ['mo', 'xml', 'desktop', 'json'] as const,
+                default: 'mo' as const,
+            })
+            .option('metainfo', {
+                description:
+                    'For --format=xml: path to the template (`.metainfo.xml.in`) used as msgfmt --template',
+                type: 'string',
+                normalize: true,
+            })
+            .option('filename', {
+                description: 'Override the output filename (defaults to <domain>.<ext>)',
+                type: 'string',
+                normalize: true,
+            })
+            .option('remove-xml-comments', {
+                description: 'For --format=xml: strip XML comments from the compiled output',
+                type: 'boolean',
+                default: true,
+            })
+            .option('verbose', {
+                description: 'Print each msgfmt invocation',
+                type: 'boolean',
+                default: false,
+            });
+    },
+    handler: async (args) => {
+        const poDir = resolve(args.poDir as string);
+        const outDir = resolve(args.outDir as string);
+        const domain = args.domain as string;
+        const format = (args.format as GettextFormat | undefined) ?? 'mo';
+        const metainfo = args.metainfo ? resolve(args.metainfo as string) : undefined;
+        const filename = args.filename ?? defaultFilename(domain, format, metainfo);
+        const verbose = !!args.verbose;
+        const removeXmlComments = !!args['remove-xml-comments'];
+
+        if (!(await fileExists(poDir))) {
+            console.error(`[gjsify gettext] PO directory does not exist: ${poDir}`);
+            process.exitCode = 1;
+            return;
+        }
+
+        try {
+            if (format === 'xml' && metainfo) {
+                await compileBulkXml({
+                    poDir,
+                    outDir,
+                    domain,
+                    template: metainfo,
+                    filename,
+                    removeXmlComments,
+                    verbose,
+                });
+            } else {
+                if (format === 'xml') {
+                    console.warn(
+                        '[gjsify gettext] --format=xml without --metainfo: falling back to per-language XML files',
+                    );
+                }
+                await compilePerLanguage({
+                    poDir,
+                    outDir,
+                    domain,
+                    format,
+                    filename,
+                    verbose,
+                });
+            }
+        } catch (err: any) {
+            if (err?.code === 'ENOENT') {
+                console.error(
+                    '[gjsify gettext] msgfmt not found. Install it via your distro (package: gettext).',
+                );
+            } else {
+                if (err?.stderr) process.stderr.write(err.stderr);
+                console.error(
+                    `[gjsify gettext] msgfmt failed${err?.code !== undefined ? ` (exit ${err.code})` : ''}`,
+                );
+            }
+            process.exitCode = typeof err?.code === 'number' ? err.code : 1;
+        }
+    },
+};

package/src/commands/gresource.ts

@@ -0,0 +1,97 @@
+import { execFile } from 'node:child_process';
+import { mkdir } from 'node:fs/promises';
+import { basename, dirname, extname, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import type { Command } from '../types/index.js';
+
+const execFileAsync = promisify(execFile);
+
+interface GResourceOptions {
+    xml: string;
+    sourcedir?: string;
+    target?: string;
+    verbose?: boolean;
+}
+
+/**
+ * Derive a default `.gresource` target path from the XML descriptor.
+ * `foo.gresource.xml` → `foo.gresource` in the same directory.
+ */
+function defaultTargetFor(xmlPath: string): string {
+    const ext = extname(xmlPath);
+    const stem = basename(xmlPath, ext);
+    return resolve(dirname(xmlPath), stem);
+}
+
+export const gresourceCommand: Command<any, GResourceOptions> = {
+    command: 'gresource <xml>',
+    description:
+        'Compile a GResource XML descriptor into a binary .gresource bundle (wraps `glib-compile-resources`).',
+    builder: (yargs) => {
+        return yargs
+            .positional('xml', {
+                description: 'Path to the .gresource.xml descriptor',
+                type: 'string',
+                normalize: true,
+                demandOption: true,
+            })
+            .option('sourcedir', {
+                description: 'Directory containing the resource files referenced by <xml>',
+                type: 'string',
+                normalize: true,
+            })
+            .option('target', {
+                alias: 't',
+                description: 'Output .gresource file (default: <xml-without-.xml> next to <xml>)',
+                type: 'string',
+                normalize: true,
+            })
+            .option('verbose', {
+                description: 'Print the underlying glib-compile-resources invocation',
+                type: 'boolean',
+                default: false,
+            });
+    },
+    handler: async (args) => {
+        const xmlPath = resolve(args.xml as string);
+        const target = args.target ? resolve(args.target as string) : defaultTargetFor(xmlPath);
+        const sourcedir = args.sourcedir
+            ? resolve(args.sourcedir as string)
+            : dirname(xmlPath);
+
+        const cmdArgs = [
+            `--sourcedir=${sourcedir}`,
+            `--target=${target}`,
+            xmlPath,
+        ];
+
+        if (args.verbose) {
+            console.log(`[gjsify gresource] glib-compile-resources ${cmdArgs.join(' ')}`);
+        }
+
+        // Ensure the target directory exists — glib-compile-resources writes
+        // a temporary file next to the target and fails with ENOENT otherwise.
+        await mkdir(dirname(target), { recursive: true });
+
+        try {
+            const { stdout, stderr } = await execFileAsync('glib-compile-resources', cmdArgs);
+            if (stdout) process.stdout.write(stdout);
+            if (stderr) process.stderr.write(stderr);
+            if (args.verbose) {
+                console.log(`[gjsify gresource] wrote ${target}`);
+            }
+        } catch (err: any) {
+            if (err?.code === 'ENOENT') {
+                console.error(
+                    '[gjsify gresource] glib-compile-resources 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 gresource] glib-compile-resources failed${err?.code !== undefined ? ` (exit ${err.code})` : ''}`,
+                );
+            }
+            process.exitCode = typeof err?.code === 'number' ? err.code : 1;
+        }
+    },
+};

package/src/commands/index.ts

@@ -3,4 +3,6 @@ export * from './run.js';
 export * from './info.js';
 export * from './check.js';
 export * from './showcase.js';
-export * from './create.js';
+export * from './create.js';
+export * from './gresource.js';
+export * from './gettext.js';

package/src/config.ts

@@ -83,6 +83,7 @@ export class Config {
         configData.exclude = cliArgs.exclude || [];
         if (cliArgs.consoleShim !== undefined) configData.consoleShim = cliArgs.consoleShim;
         if (cliArgs.globals !== undefined) configData.globals = cliArgs.globals;
+        if (cliArgs.shebang !== undefined) configData.shebang = cliArgs.shebang;
 
         merge(configData.library ??= {}, pkg, configData.library);
         merge(configData.typescript ??= {}, tsConfig, configData.typescript);

package/src/index.ts

@@ -2,18 +2,28 @@
 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 } 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,
+} from './commands/index.js'
 import { APP_NAME } from './constants.js'
 
 void yargs(hideBin(process.argv))
     .scriptName(APP_NAME)
     .strict()
-    // .usage(Config.usage)
     .command(create.command, create.description, create.builder, create.handler)
     .command(build.command, build.description, build.builder, build.handler)
     .command(run.command, run.description, run.builder, run.handler)
     .command(info.command, info.description, info.builder, info.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)
+    .command(gettext.command, gettext.description, gettext.builder, gettext.handler)
     .demandCommand(1)
     .help().argv

package/src/types/cli-build-options.ts

@@ -55,4 +55,10 @@ export interface CliBuildOptions {
    * bundle. Only applies to GJS app builds.
    */
   globals?: string;
+  /**
+   * Prepend a `#!/usr/bin/env -S gjs -m` shebang to the output file and mark
+   * it executable (chmod 755). Only applies to GJS app builds with a single
+   * `--outfile`. Default: false.
+   */
+  shebang?: boolean;
 }

package/src/types/config-data.ts

@@ -19,4 +19,8 @@ export interface ConfigData {
      * See CliBuildOptions for format.
      */
     globals?: string;
+    /**
+     * Prepend GJS shebang to output and mark executable. See CliBuildOptions.
+     */
+    shebang?: boolean;
 }