@gjsify/cli 0.10.0 → 0.11.0

package/lib/cli-app.js

@@ -19,7 +19,7 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import yargs from 'yargs';
-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, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, storybookCommand as storybook, } 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, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, storybookCommand as storybook, debugCommand as debug, browseCommand as browse, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 import { isNode } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { ensureGjsifyShimOnPath } from './utils/gjsify-shim.js';
@@ -114,6 +114,8 @@ export async function runCli(argv) {
         .command(tsc.command, tsc.description, tsc.builder, tsc.handler)
         .command(affected.command, affected.description, affected.builder, affected.handler)
         .command(storybook.command, storybook.description, storybook.builder, storybook.handler)
+        .command(debug.command, debug.description, debug.builder, debug.handler)
+        .command(browse.command, browse.description, browse.builder, browse.handler)
         .demandCommand(1)
         .epilogue(`Running on ${runtimeLabel()}`)
         .help()

package/lib/commands/browse.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from '../types/index.js';
+interface BrowseCliOptions {
+    url?: string;
+    appId?: string;
+    title?: string;
+    globals?: string;
+    out?: string;
+    devtools: boolean;
+    buildOnly: boolean;
+}
+/** Derive a DBus app id from the package name (mirrored by `gjsify debug`). */
+export declare function deriveBrowserAppId(name?: string): string;
+export declare const browseCommand: Command<unknown, BrowseCliOptions>;
+export {};

package/lib/commands/browse.js

@@ -0,0 +1,93 @@
+// `gjsify browse [url]` — launch the Adwaita web browser from
+// @gjsify/devtools-browser, optionally at a URL. Generates a tiny entry that
+// calls runBrowserDevtools(), builds it (`--app gjs --globals auto,dom`), and
+// launches it. Dispatch is IN-PROCESS (runCli + runGjsBundle), like
+// `gjsify storybook`. `--devtools` sets GJSIFY_DEVTOOLS=1 so @gjsify/devtools
+// wires the org.gjsify.Devtools control plane (driveable via `gjsify debug`).
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+function readPackage(cwd) {
+    try {
+        return JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** Derive a DBus app id from the package name (mirrored by `gjsify debug`). */
+export function deriveBrowserAppId(name) {
+    if (!name)
+        return 'org.gjsify.Browser';
+    const slug = name
+        .replace(/^@/, '')
+        .replace(/[^a-zA-Z0-9]+/g, '.')
+        .replace(/^\.+|\.+$/g, '');
+    return `org.gjsify.browser.${slug}`;
+}
+function generateEntry(applicationId, url, title) {
+    const titleLine = title ? `\n    title: ${JSON.stringify(title)},` : '';
+    const urlLine = url ? `\n    homeUrl: ${JSON.stringify(url)},` : '';
+    return `// Auto-generated by \`gjsify browse\` — do not edit by hand.
+import { runBrowserDevtools } from '@gjsify/devtools-browser';
+
+await runBrowserDevtools({
+    applicationId: ${JSON.stringify(applicationId)},${titleLine}${urlLine}
+});
+`;
+}
+export const browseCommand = {
+    command: 'browse [url]',
+    description: 'Launch the Adwaita web browser, optionally pointed at a URL.',
+    builder: (yargs) => yargs
+        .positional('url', { description: 'Initial URL to load (default: page:welcome)', type: 'string' })
+        .option('app-id', {
+        description: 'GApplication id (default: gjsify.browse.applicationId or derived from the package name)',
+        type: 'string',
+    })
+        .option('title', { description: 'Window title', type: 'string' })
+        .option('globals', {
+        description: 'Value for `gjsify build --globals` (default: auto,dom — WebKit/iframe need DOM globals)',
+        type: 'string',
+    })
+        .option('out', {
+        description: 'Output bundle path (default: node_modules/.cache/gjsify-browse)',
+        type: 'string',
+    })
+        .option('devtools', {
+        description: 'Enable the MCP devtools control plane (sets GJSIFY_DEVTOOLS=1)',
+        type: 'boolean',
+        default: false,
+    })
+        .option('build-only', {
+        description: 'Build the bundle but do not launch it',
+        type: 'boolean',
+        default: false,
+    }),
+    handler: async (args) => {
+        const cwd = process.cwd();
+        const pkg = readPackage(cwd);
+        const config = pkg.gjsify?.browse ?? {};
+        const applicationId = args.appId ?? config.applicationId ?? deriveBrowserAppId(pkg.name);
+        const title = args.title ?? config.title;
+        const globals = args.globals ?? config.globals ?? 'auto,dom';
+        const url = args.url;
+        const cacheDir = join(cwd, 'node_modules', '.cache', 'gjsify-browse');
+        mkdirSync(cacheDir, { recursive: true });
+        const entryPath = join(cacheDir, 'entry.ts');
+        const outPath = args.out ? resolve(cwd, args.out) : join(cacheDir, 'browse.gjs.mjs');
+        writeFileSync(entryPath, generateEntry(applicationId, url, title));
+        console.log(`[gjsify browse] app=${applicationId}${url ? ` url=${url}` : ''}${args.devtools ? ' devtools=1' : ''}`);
+        const { runCli } = await import('../cli-app.js');
+        await runCli(['build', entryPath, '--app', 'gjs', '--globals', globals, '--outfile', outPath]);
+        if (args.buildOnly) {
+            console.log(`[gjsify browse] built ${outPath}`);
+            return;
+        }
+        // runGjsBundle spreads process.env into the child, so set the devtools
+        // gate here (RunGjsBundleOptions has no env field).
+        if (args.devtools)
+            process.env.GJSIFY_DEVTOOLS = '1';
+        const { runGjsBundle } = await import('../utils/run-gjs.js');
+        await runGjsBundle(outPath, [], { exitOnSuccess: true });
+    },
+};

package/lib/commands/build.js

@@ -99,7 +99,12 @@ export const buildCommand = {
             description: "Comma-separated list of global identifiers, 'auto' (default) to detect automatically from the bundled output, or 'none' to disable. The 'auto' token may be combined with explicit identifiers/groups (e.g. 'auto,dom') for cases where the detector cannot statically see a global because it's accessed via indirection. Each identifier is mapped to the corresponding `@gjsify/<pkg>/register` module and injected into the bundle. See the CLI Reference docs for the full list of known identifiers. Only applies to GJS app builds.",
             type: 'string',
             normalize: true,
-            default: 'auto',
+            // No yargs `default: 'auto'` — a yargs default is
+            // indistinguishable from a user-set value and would always
+            // clobber `package.json#gjsify.globals` / `.gjsifyrc.*` in
+            // config.ts (same footgun as `entryPoints`/`bundler.input`).
+            // The 'auto' fallback is applied post-merge in `Config.forBuild`
+            // so precedence is: CLI flag > config file > 'auto'.
         })
             .option('shebang', {
             description: 'Prepend a target-appropriate shebang to the output and mark it executable (chmod 755): `#!/usr/bin/env -S gjs -m` for --app gjs, `#!/usr/bin/env node` for --app node. Applies to GJS and Node app builds with a single --outfile. Default: false (use --shebang to enable, or set `shebang: true` in `.gjsifyrc.js`).',

package/lib/commands/debug.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from '../types/index.js';
+interface DebugCliOptions {
+    busName?: string;
+    profile?: string;
+    globals?: string;
+    out?: string;
+    buildOnly: boolean;
+}
+export declare const debugCommand: Command<unknown, DebugCliOptions>;
+export {};

package/lib/commands/debug.js

@@ -0,0 +1,139 @@
+// `gjsify debug` — launch an MCP↔devtools bridge for a running, devtools-enabled
+// gjsify app (its `org.gjsify.Devtools` DBus control plane). An MCP client (e.g.
+// Claude Code) uses this as its server command; the bridge speaks JSON-RPC on
+// stdio and translates tool calls to the app's DBus interface.
+//
+// Dispatch is IN-PROCESS (runCli + runGjsBundle), like `gjsify storybook`. The
+// generated entry resolves `@gjsify/devtools-mcp` from the CONSUMER's
+// node_modules (so it stays out of the CLI's own deps). The bridge is built
+// `--app gjs --shebang` and launched with stdio inherited, so its JSON-RPC
+// stdout reaches the client untouched.
+//
+// CRITICAL: this command logs ONLY to stderr — stdout is the MCP channel.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+function readPackage(cwd) {
+    try {
+        return JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** Mirror of `commands/storybook.ts` deriveAppId — the storybook app's DBus id. */
+function deriveStorybookAppId(name) {
+    if (!name)
+        return 'org.gjsify.Storybook';
+    const slug = name
+        .replace(/^@/, '')
+        .replace(/[^a-zA-Z0-9]+/g, '.')
+        .replace(/^\.+|\.+$/g, '');
+    return `org.gjsify.storybook.${slug}`;
+}
+/** Mirror of `commands/browse.ts` deriveBrowserAppId — the browser app's DBus id. */
+function deriveBrowserAppId(name) {
+    if (!name)
+        return 'org.gjsify.Browser';
+    const slug = name
+        .replace(/^@/, '')
+        .replace(/[^a-zA-Z0-9]+/g, '.')
+        .replace(/^\.+|\.+$/g, '');
+    return `org.gjsify.browser.${slug}`;
+}
+function hasDep(pkg, name) {
+    return Boolean(pkg.dependencies?.[name] || pkg.devDependencies?.[name]);
+}
+function generateEntry(profile, busNameBase, name, version) {
+    if (profile === 'storybook') {
+        return `// Auto-generated by \`gjsify debug\` — do not edit by hand.
+import { runDevtoolsMcp, storybookProfile } from '@gjsify/devtools-mcp';
+
+await runDevtoolsMcp(storybookProfile(${JSON.stringify(busNameBase)}));
+`;
+    }
+    if (profile === 'browser') {
+        return `// Auto-generated by \`gjsify debug\` — do not edit by hand.
+import { runDevtoolsMcp, browserProfile } from '@gjsify/devtools-mcp';
+
+await runDevtoolsMcp(browserProfile(${JSON.stringify(busNameBase)}));
+`;
+    }
+    return `// Auto-generated by \`gjsify debug\` — do not edit by hand.
+import { runDevtoolsMcp } from '@gjsify/devtools-mcp';
+
+await runDevtoolsMcp({
+    name: ${JSON.stringify(name)},
+    version: ${JSON.stringify(version)},
+    busNameBase: ${JSON.stringify(busNameBase)},
+});
+`;
+}
+export const debugCommand = {
+    command: 'debug',
+    description: 'Launch an MCP bridge for a devtools-enabled gjsify app (org.gjsify.Devtools).',
+    builder: (yargs) => yargs
+        .option('bus-name', {
+        description: 'App DBus base name (default: gjsify.devtools.busNameBase, or the storybook app-id)',
+        type: 'string',
+    })
+        .option('profile', {
+        description: 'Tool profile: generic | storybook | browser (default: auto — storybook if @gjsify/storybook is a dep, browser if @gjsify/devtools-browser is, else generic)',
+        type: 'string',
+    })
+        .option('globals', {
+        description: 'Value for `gjsify build --globals` (default: auto)',
+        type: 'string',
+    })
+        .option('out', {
+        description: 'Output bundle path (default: node_modules/.cache/gjsify-debug)',
+        type: 'string',
+    })
+        .option('build-only', {
+        description: 'Build the bridge bundle but do not launch it (for a .mcp.json command pointing at the bundle)',
+        type: 'boolean',
+        default: false,
+    }),
+    handler: async (args) => {
+        const cwd = process.cwd();
+        const pkg = readPackage(cwd);
+        const config = pkg.gjsify?.devtools ?? {};
+        const profile = args.profile ??
+            config.profile ??
+            (hasDep(pkg, '@gjsify/storybook')
+                ? 'storybook'
+                : hasDep(pkg, '@gjsify/devtools-browser')
+                    ? 'browser'
+                    : 'generic');
+        const busNameBase = args.busName ??
+            config.busNameBase ??
+            (profile === 'storybook'
+                ? (pkg.gjsify?.storybook?.applicationId ?? deriveStorybookAppId(pkg.name))
+                : profile === 'browser'
+                    ? (pkg.gjsify?.browse?.applicationId ?? deriveBrowserAppId(pkg.name))
+                    : undefined);
+        if (!busNameBase) {
+            console.error('gjsify debug: no bus name — set package.json#gjsify.devtools.busNameBase or pass --bus-name <org.example.App>');
+            process.exit(1);
+        }
+        const globals = args.globals ?? config.globals ?? 'auto';
+        const name = pkg.name ? `${pkg.name}-devtools` : 'gjsify-devtools';
+        const version = '0.8.0';
+        const cacheDir = join(cwd, 'node_modules', '.cache', 'gjsify-debug');
+        mkdirSync(cacheDir, { recursive: true });
+        const entryPath = join(cacheDir, 'entry.ts');
+        const outPath = args.out ? resolve(cwd, args.out) : join(cacheDir, 'bridge.gjs.mjs');
+        writeFileSync(entryPath, generateEntry(profile, busNameBase, name, version));
+        // stderr only — stdout is the MCP JSON-RPC channel.
+        console.error(`[gjsify debug] profile=${profile} bus=${busNameBase}`);
+        // In-process build (runtime-agnostic), then launch with stdio inherited
+        // so the bridge's JSON-RPC stdin/stdout are the client's pipes.
+        const { runCli } = await import('../cli-app.js');
+        await runCli(['build', entryPath, '--app', 'gjs', '--shebang', '--globals', globals, '--outfile', outPath]);
+        if (args.buildOnly) {
+            console.error(`[gjsify debug] built ${outPath}`);
+            return;
+        }
+        const { runGjsBundle } = await import('../utils/run-gjs.js');
+        await runGjsBundle(outPath, [], { exitOnSuccess: true });
+    },
+};

package/lib/commands/index.d.ts

@@ -31,3 +31,5 @@ export * from './barrels.js';
 export * from './tsc.js';
 export * from './affected.js';
 export * from './storybook.js';
+export * from './debug.js';
+export * from './browse.js';

package/lib/commands/index.js

@@ -31,3 +31,5 @@ export * from './barrels.js';
 export * from './tsc.js';
 export * from './affected.js';
 export * from './storybook.js';
+export * from './debug.js';
+export * from './browse.js';

package/lib/config.js

@@ -137,6 +137,12 @@ export class Config {
             configData.consoleShim = cliArgs.consoleShim;
         if (cliArgs.globals !== undefined)
             configData.globals = cliArgs.globals;
+        // Fallback applied post-merge (not as a yargs `default:`) so a
+        // `globals` declared in package.json#gjsify / `.gjsifyrc.*` survives —
+        // a yargs default is indistinguishable from a user value and would
+        // overwrite the config one. Precedence: CLI flag > config file > 'auto'
+        // (mirrors the `bundler.input` fallback below).
+        configData.globals ??= 'auto';
         if (cliArgs.shebang !== undefined)
             configData.shebang = cliArgs.shebang;
         if (cliArgs.excludeGlobals) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.10.0",
+    "version": "0.11.0",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -120,19 +120,19 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.10.0",
-        "@gjsify/create-app": "^0.10.0",
-        "@gjsify/node-globals": "^0.10.0",
-        "@gjsify/node-polyfills": "^0.10.0",
-        "@gjsify/npm-registry": "^0.10.0",
-        "@gjsify/resolve-npm": "^0.10.0",
-        "@gjsify/rolldown-plugin-gjsify": "^0.10.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.10.0",
-        "@gjsify/semver": "^0.10.0",
-        "@gjsify/tar": "^0.10.0",
-        "@gjsify/tsc": "^0.10.0",
-        "@gjsify/web-polyfills": "^0.10.0",
-        "@gjsify/workspace": "^0.10.0",
+        "@gjsify/buffer": "^0.11.0",
+        "@gjsify/create-app": "^0.11.0",
+        "@gjsify/node-globals": "^0.11.0",
+        "@gjsify/node-polyfills": "^0.11.0",
+        "@gjsify/npm-registry": "^0.11.0",
+        "@gjsify/resolve-npm": "^0.11.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.11.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.11.0",
+        "@gjsify/semver": "^0.11.0",
+        "@gjsify/tar": "^0.11.0",
+        "@gjsify/tsc": "^0.11.0",
+        "@gjsify/web-polyfills": "^0.11.0",
+        "@gjsify/workspace": "^0.11.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
         "pkg-types": "^2.3.1",
@@ -140,13 +140,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.10.0",
+        "@gjsify/unit": "^0.11.0",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.10.0",
-        "@gjsify/rolldown-native": "^0.10.0"
+        "@gjsify/oxfmt-native": "^0.11.0",
+        "@gjsify/rolldown-native": "^0.11.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {