@gjsify/cli 0.53.0 → 0.55.0

package/lib/bundler-pick.d.ts

@@ -1,5 +1,6 @@
 import type { RolldownOutput, InputOptions, RolldownWatcher } from 'rolldown';
 import type { BundlerOptions } from './types/index.js';
+import { type ResolveNpmPackageOptions } from './utils/resolve-npm-package.js';
 export interface NativePluginContext {
     resolve(specifier: string, importer?: string, opts?: {
         skipSelf?: boolean;
@@ -113,6 +114,40 @@ export interface RunBundleOptions {
  * `rolldown(opts).write(opts.output)` flow used directly in build.ts.
  */
 export declare function runBundle(finalOpts: BundlerOptions, options?: RunBundleOptions): Promise<RolldownOutput>;
+/**
+ * The file `@gjsify/utils/native-library` resolves to, or THROWS when no anchor
+ * reaches it.
+ *
+ * `resolveNpmPackage` first, the same resolver — and the same `?? createRequire`
+ * tail — the ENGINE loader below uses, for the same reason: ONE
+ * `createRequire(import.meta.url)` anchor walks exactly one node_modules chain,
+ * the one rooted at the BUNDLE. v0.53.0's release `publish-napi` job runs the
+ * published bundle from `~/.cache/gjsify/bootstrap/`, which is in no workspace's
+ * chain, so the bundle-only anchor found nothing — and since #1901 moved
+ * `probeNativeLibrary()` onto `tryLoadNative()`'s SUCCESS path, that is not a
+ * degraded diagnostic but NO ENGINE: every `gjsify build` under GJS died with
+ * "no usable bundler engine", reported by a diagnostic that resolves the same
+ * specifier and so could not name the cause. MEASURED on the release job's own
+ * shape: with `@gjsify/utils` FULLY BUILT, anchoring only at the bundle still
+ * fails with `Cannot find module "@gjsify/utils/native-library" - not found in
+ * any node_modules directory`; anchoring at cwd resolves it. `main.yml` never
+ * saw this because it exports `XDG_CACHE_HOME=$PWD/.gjsify-cache` and therefore
+ * caches the bundle INSIDE the workspace, where the bundle-only anchor happens
+ * to work.
+ *
+ * Two independent defects, so both are fixed where they live: this anchor, and
+ * the `lib/esm` emit it then needs on a cold tree (`@gjsify/utils build:esm`
+ * before the first bundler clause, rule 5 of
+ * `scripts/check-build-infra-order.mjs`).
+ *
+ * SCOPE, since it decides what this unblocks: the release job runs `build:infra`
+ * with the PUBLISHED bundle, which is fixed code this change cannot reach — so on
+ * its own it does NOT unblock v0.53.0. What does is the `XDG_CACHE_HOME` line in
+ * release.yml's `publish-napi` job, which puts that bundle inside the workspace
+ * where ANY anchor finds this tree. This fix is what stops the next release from
+ * depending on that line.
+ */
+export declare function resolveNativeLibraryModule(opts?: ResolveNpmPackageOptions): string;
 export declare function shouldUseNative(): Promise<boolean>;
 /**
  * Walk parent directories from `startDir` (and optionally a second anchor

package/lib/bundler-pick.js

@@ -318,6 +318,43 @@ let _utilsCore = null;
  * measurement is reported as one.
  */
 let _utilsCoreError = null;
+/**
+ * The file `@gjsify/utils/native-library` resolves to, or THROWS when no anchor
+ * reaches it.
+ *
+ * `resolveNpmPackage` first, the same resolver — and the same `?? createRequire`
+ * tail — the ENGINE loader below uses, for the same reason: ONE
+ * `createRequire(import.meta.url)` anchor walks exactly one node_modules chain,
+ * the one rooted at the BUNDLE. v0.53.0's release `publish-napi` job runs the
+ * published bundle from `~/.cache/gjsify/bootstrap/`, which is in no workspace's
+ * chain, so the bundle-only anchor found nothing — and since #1901 moved
+ * `probeNativeLibrary()` onto `tryLoadNative()`'s SUCCESS path, that is not a
+ * degraded diagnostic but NO ENGINE: every `gjsify build` under GJS died with
+ * "no usable bundler engine", reported by a diagnostic that resolves the same
+ * specifier and so could not name the cause. MEASURED on the release job's own
+ * shape: with `@gjsify/utils` FULLY BUILT, anchoring only at the bundle still
+ * fails with `Cannot find module "@gjsify/utils/native-library" - not found in
+ * any node_modules directory`; anchoring at cwd resolves it. `main.yml` never
+ * saw this because it exports `XDG_CACHE_HOME=$PWD/.gjsify-cache` and therefore
+ * caches the bundle INSIDE the workspace, where the bundle-only anchor happens
+ * to work.
+ *
+ * Two independent defects, so both are fixed where they live: this anchor, and
+ * the `lib/esm` emit it then needs on a cold tree (`@gjsify/utils build:esm`
+ * before the first bundler clause, rule 5 of
+ * `scripts/check-build-infra-order.mjs`).
+ *
+ * SCOPE, since it decides what this unblocks: the release job runs `build:infra`
+ * with the PUBLISHED bundle, which is fixed code this change cannot reach — so on
+ * its own it does NOT unblock v0.53.0. What does is the `XDG_CACHE_HOME` line in
+ * release.yml's `publish-napi` job, which puts that bundle inside the workspace
+ * where ANY anchor finds this tree. This fix is what stops the next release from
+ * depending on that line.
+ */
+export function resolveNativeLibraryModule(opts = {}) {
+    const specifier = '@gjsify/utils/native-library';
+    return resolveNpmPackage(specifier, opts) ?? createRequire(opts.bundleUrl ?? import.meta.url).resolve(specifier);
+}
 async function utilsCore() {
     if (_utilsCore === null) {
         // `./native-library`, not `./core`: `core` re-exports `main-loop`, which
@@ -325,7 +362,18 @@ async function utilsCore() {
         // so loading `core` off disk would give the process a SECOND copy of that
         // singleton — inert today because only pure probe functions are read
         // through this edge, and a trap the first time that stops being true.
-        const href = pathToFileURL(createRequire(import.meta.url).resolve('@gjsify/utils/native-library')).href;
+        //
+        // Off disk, so the resolution's ANCHORS matter — see
+        // `resolveNativeLibraryModule()` — and on a cold tree the WORKSPACE copy
+        // it finds is itself a build output, which is what
+        // `@gjsify/utils build:esm` orders (rule 5 of
+        // `scripts/check-build-infra-order.mjs`). Two independent preconditions,
+        // and v0.53.0's release `publish-napi` job needed both: a bundle-only
+        // anchor resolved nothing when the bundle was the published
+        // `cli.gjs.mjs` — one loose file in `<cache>/gjsify/bootstrap/`, no
+        // `node_modules` above it. So a throw here is "not measured" (see
+        // `tryLoadNative`), never "no engine".
+        const href = pathToFileURL(resolveNativeLibraryModule({ bundleUrl: import.meta.url })).href;
         _utilsCore = (await import(/* @vite-ignore */ href));
     }
     return _utilsCore;
@@ -464,18 +512,37 @@ async function tryLoadNative() {
             // past `diagnoseNativeEngine()`, which then never runs.
             // Separated from the engine's own failure so that "the engine is
             // absent" and "the measurement could not run" stay distinguishable
-            // at the one place that reports them.
-            let surface;
+            // at the one place that reports them — and only a library the probe
+            // MEASURED as broken vetoes the engine. A probe that could not be
+            // LOADED does not: the engine's own load already answered twice
+            // over (the module imported, `hasNativeRolldown()` resolved its
+            // typelib), and under GJS there is no second engine to fall back to
+            // — the npm `rolldown` crate is a napi binary — so `null` here
+            // turned "nothing was measured" into "there is no bundler".
+            //
+            // What reaches that verdict is not exotic. `utilsCore()` resolves
+            // `@gjsify/utils/native-library` from THIS bundle's own directory,
+            // while every other resolution in this function goes through
+            // `resolveNpmPackage()` with its cwd/workspace anchors; the bundle
+            // that runs a cold `build:infra` is the PUBLISHED `cli.gjs.mjs`,
+            // which `install.mjs --fetch-only` caches as one loose file in
+            // `<cache>/gjsify/bootstrap/` with no `node_modules` beside it. On
+            // the release runner the probe therefore resolved nothing and
+            // `@gjsify/napi` did not publish (v0.53.0), and building utils'
+            // `lib/esm` first changed nothing — measured, which is why the
+            // asymmetry is fixed here and no clause was reordered.
+            let surface = null;
             try {
                 surface = await utilsCore();
             }
             catch (err) {
                 _utilsCoreError = err;
-                return null;
             }
-            _nativeLibraryFailure = surface.probeNativeLibrary('GjsifyRolldown');
-            if (_nativeLibraryFailure)
-                return null;
+            if (surface !== null) {
+                _nativeLibraryFailure = surface.probeNativeLibrary('GjsifyRolldown');
+                if (_nativeLibraryFailure)
+                    return null;
+            }
             return mod;
         }
         catch {

package/lib/cli-app.js

@@ -18,7 +18,7 @@
 import yargs from 'yargs';
 import { classifyCliFailure } from './cli-fail.js';
 import { cliVersion } from './utils/publish-headers.js';
-import { buildCommand as build, clearCommand as clear, copyCommand as copy, envCommand as env, execCommand as exec, 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, shipCommand as ship, dlxCommand as dlx, installCommand as install, linkCommand as link, unlinkCommand as unlink, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, onboardCommand as onboard, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, pruneCommand as prune, 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, devCommand as dev, debugCommand as debug, browseCommand as browse, webextCommand as webext, } from './commands/index.js';
+import { buildCommand as build, clearCommand as clear, copyCommand as copy, envCommand as env, execCommand as exec, 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, shipCommand as ship, dlxCommand as dlx, installCommand as install, linkCommand as link, unlinkCommand as unlink, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, onboardCommand as onboard, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, pruneCommand as prune, 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, devCommand as dev, debugCommand as debug, devtoolsCommand as devtools, browseCommand as browse, webextCommand as webext, blueprintCommand as blueprint, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 import { isBun, isDeno, isNode, gjsSystemVersion } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { ensureGjsifyShimOnPath } from './utils/gjsify-shim.js';
@@ -135,8 +135,10 @@ export async function runCli(argv) {
         .command(storybook.command, storybook.description, storybook.builder, storybook.handler)
         .command(dev.command, dev.description, dev.builder, dev.handler)
         .command(debug.command, debug.description, debug.builder, debug.handler)
+        .command(devtools.command, devtools.description, devtools.builder, devtools.handler)
         .command(browse.command, browse.description, browse.builder, browse.handler)
         .command(webext.command, webext.description, webext.builder, webext.handler)
+        .command(blueprint.command, blueprint.description, blueprint.builder, blueprint.handler)
         .demandCommand(1)
         .epilogue(`Running on ${runtimeLabel()}`)
         .help()

package/lib/commands/blueprint/index.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from '../../types/index.js';
+import { blueprintTypesCommand } from './types.js';
+export { blueprintTypesCommand };
+export declare const blueprintCommand: Command;

package/lib/commands/blueprint/index.js

@@ -0,0 +1,15 @@
+// `gjsify blueprint` — yargs subcommand-group dispatcher, the same shape as `flatpak/`.
+//
+// A directory rather than one file because `check-website-cli-reference.mjs` reads every
+// `command:` in a top-level file as a top-level command; a group's subcommands live beside
+// its `index.ts` and are documented as `#### gjsify blueprint <sub>`.
+import { blueprintTypesCommand } from './types.js';
+export { blueprintTypesCommand };
+export const blueprintCommand = {
+    command: 'blueprint <subcommand>',
+    description: 'Blueprint (.blp) tooling: generate the TypeScript type sidecars a .blp exports (ADR 0088).',
+    builder: (yargs) => yargs
+        .command(blueprintTypesCommand.command, blueprintTypesCommand.description, blueprintTypesCommand.builder, blueprintTypesCommand.handler)
+        .demandCommand(1)
+        .strict(),
+};

package/lib/commands/blueprint/types.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from '../../types/index.js';
+interface BlueprintTypesOptions {
+    paths?: string[];
+    check?: boolean;
+    verbose?: boolean;
+}
+export declare const blueprintTypesCommand: Command<unknown, BlueprintTypesOptions>;
+export {};

package/lib/commands/blueprint/types.js

@@ -0,0 +1,148 @@
+// `gjsify blueprint types [paths..]` — write the `.d.blp.ts` sidecars ADR 0088 § 4 defines.
+//
+// WHY THE CLI HAS THIS AT ALL, when `@gjsify/vite-plugin-blueprint` already writes a sidecar
+// during `load`: a type-check is not a build. `gjsify check` runs `tsc` and nothing else, so a
+// fresh clone — or a `.blp` whose consumer is being WRITTEN, before any bundle exists — has no
+// sidecar unless something outside the bundler can produce one. This is that something, and it
+// is why the command is usable before `gjsify check` rather than only after a build.
+//
+// `--check` IS FOR CONSUMERS OF THE PUBLISHED CLI. In this repository the sidecar gate is
+// `scripts/check-blueprint-sidecars.mjs`, which CI runs with plain `node` beside the other three
+// Blueprint gates — it has to be, because the CI bootstrap is the PREVIOUS RELEASE's bundle
+// (ADR 0002) and cannot run a command this tree just added. A third-party project has no
+// `scripts/` of ours, so without this flag it could generate sidecars and never hold them.
+// The two share the derivation; what is duplicated is the byte comparison.
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { emitTypedSidecar, parseBlueprint, sidecarPathFor } from '@gjsify/blueprint';
+import { emitFormatForTree } from '@gjsify/blueprint/oxfmt';
+/** What a walk never descends into: build output, and other projects' sources. */
+const SKIP = new Set(['node_modules', 'dist', 'lib', '.git']);
+/**
+ * Every `.blp` under one path, or the path itself when it names one.
+ *
+ * `statSync` rather than `withFileTypes`, the same choice `utils/build-cache.ts` makes and for
+ * the same reason: this command also runs from the GJS bundle, where `@gjsify/fs` is the readdir
+ * implementation.
+ */
+function blueprintsUnder(path, found) {
+    let entry;
+    try {
+        entry = statSync(path);
+    }
+    catch {
+        return found;
+    }
+    if (!entry.isDirectory()) {
+        if (path.endsWith('.blp'))
+            found.push(path);
+        return found;
+    }
+    for (const name of readdirSync(path).sort()) {
+        if (SKIP.has(name) || name.startsWith('.'))
+            continue;
+        blueprintsUnder(join(path, name), found);
+    }
+    return found;
+}
+/**
+ * The emitter options for the tree a `.blp` lives in, memoized per directory.
+ *
+ * ONE directory of the walk is a sidecar's, not the CWD's, and that is the difference between
+ * right and right-by-luck in a monorepo: a package with its own `.oxfmtrc` gets that package's
+ * width, and running the command from the repo root still writes that package's indent. The walk
+ * itself is `emitFormatForTree`'s — the same one the drift gate and the bundler plugin use, so
+ * three callers cannot answer "which config does the formatter read" three ways (ADR 0088 §
+ * Consequences: the emitter once read `printWidth` and hardcoded a 4-space indent beside it, which
+ * is a `tabWidth: 2` consumer's red `oxfmt --check`).
+ *
+ * Memoized because the walk touches the filesystem once per `.blp` and a tree of a thousand
+ * `.blp` files would do that a thousand times; one read per distinct directory, not per file.
+ */
+const formatCache = new Map();
+const formatFor = (dir) => {
+    const cached = formatCache.get(dir);
+    if (cached !== undefined)
+        return cached;
+    const format = emitFormatForTree(dir);
+    formatCache.set(dir, format);
+    return format;
+};
+export const blueprintTypesCommand = {
+    command: 'types [paths..]',
+    description: 'Generate the `<name>.d.blp.ts` type sidecar for each .blp (ADR 0088), so `import { build }` / ' +
+        '`import { GTypeName }` type-check before anything is built. Defaults to the current directory.',
+    builder: (yargs) => yargs
+        .positional('paths', {
+        description: 'Files or directories to scan for .blp (default: the current directory)',
+        type: 'string',
+        array: true,
+        normalize: true,
+        default: [],
+    })
+        .option('check', {
+        description: 'Write nothing; exit non-zero when a sidecar is missing or stale',
+        type: 'boolean',
+        default: false,
+    })
+        .option('verbose', {
+        description: 'Print every file considered, not only the ones that changed',
+        type: 'boolean',
+        default: false,
+    }),
+    handler: async (args) => {
+        const given = args.paths ?? [];
+        const roots = (given.length > 0 ? given : ['.']).map((path) => isAbsolute(path) ? path : resolve(process.cwd(), path));
+        const blueprints = [];
+        for (const root of roots)
+            blueprintsUnder(root, blueprints);
+        const outdated = [];
+        let written = 0;
+        for (const file of blueprints) {
+            const sidecar = sidecarPathFor(file);
+            // A parse or derive refusal is NOT caught. It names its file and its line (ADR 0053
+            // clause 3), which is the whole contract, and swallowing it here would report "0
+            // sidecars written" for a `.blp` that cannot compile.
+            // `basename` from `node:path`, which is the host's own answer under the GJS bundle as
+            // well as under node: `@gjsify/node-path` picks its win32 or posix flavour at module
+            // init, and the path here is the user's, on their machine. `@gjsify/blueprint` cannot
+            // take the name itself — see `typed-exports.mjs` § `emitTypedSidecar`.
+            const ast = parseBlueprint(readFileSync(file, 'utf8'), file);
+            const expected = emitTypedSidecar(ast, basename(file), formatFor(dirname(file)));
+            let current;
+            try {
+                current = readFileSync(sidecar, 'utf8');
+            }
+            catch {
+                current = undefined;
+            }
+            if (current === expected) {
+                if (args.verbose)
+                    console.log(`[gjsify blueprint types] current: ${sidecar}`);
+                continue;
+            }
+            if (args.check) {
+                outdated.push(sidecar);
+                continue;
+            }
+            // Only on a difference: an identical rewrite still moves the mtime, which a watcher
+            // reads as a change — the same rule `vite-plugin-blueprint`'s own writer follows.
+            writeFileSync(sidecar, expected, 'utf8');
+            written += 1;
+            console.log(`[gjsify blueprint types] wrote ${sidecar}`);
+        }
+        if (args.check) {
+            if (outdated.length === 0) {
+                console.log(`[gjsify blueprint types] ${blueprints.length} .blp checked, every sidecar current.`);
+                return;
+            }
+            for (const sidecar of outdated)
+                console.error(`[gjsify blueprint types] missing or stale: ${sidecar}`);
+            console.error('[gjsify blueprint types] run without --check to regenerate.');
+            process.exitCode = 1;
+            return;
+        }
+        console.log(`[gjsify blueprint types] ${blueprints.length} .blp scanned, ${written} sidecar(s) written, ` +
+            `${blueprints.length - written} already current.`);
+    },
+};

package/lib/commands/devtools.d.ts

@@ -0,0 +1,21 @@
+import type { Command } from '../types/index.js';
+interface DevtoolsCliOptions {
+    /** Positional 1: the control-plane operation, e.g. `shot`. */
+    operation: string;
+    /** Positional 2+: its arguments — the output path for `shot`, the selector for `find`. */
+    operands?: string[];
+    busName?: string;
+    address?: string;
+    instance?: string;
+    globals?: string;
+    out?: string;
+    timeout: number;
+}
+/**
+ * `gjsify devtools` builds and runs a tiny client over the `org.gjsify.Devtools` control
+ * plane. Subcommands mirror the control-plane methods — `shot`, `find`, `activate`, `key`,
+ * `tree`, `property`, `resize`, `status`, `actions`, `toplevels`, `css`, `gsettings`,
+ * `instances` — so anything a rig does by hand over `gdbus` has a scriptable spelling.
+ */
+export declare const devtoolsCommand: Command<unknown, DevtoolsCliOptions>;
+export {};

package/lib/commands/devtools.js

@@ -0,0 +1,146 @@
+// `gjsify devtools` — drive a running, devtools-enabled gjsify app from a SCRIPT.
+//
+// The peer of `gjsify debug`, not a replacement for it. `debug` speaks MCP over stdio, which
+// is the right shape for an AI agent and the wrong one for a shell script, a Makefile, or a CI
+// step: there is no way to pipe `Screenshot` into a file, because MCP's answer is base64 inside
+// a JSON-RPC frame. So every consumer that wanted a screenshot on disk wrote its own GJS
+// caller to unpack the `ay` variant — and every one of them had to re-decide the same two
+// things this command decides once:
+//
+//   · EMPTY BYTES ARE A FAILURE. `Screenshot` answers `ay[0]` when there is no active window
+//     or the window was never realised (the deliberate `CaptureBlocker` contract). Writing
+//     that produces a 0-byte file named `.png` and a success message.
+//   · THE SIZE COMES FROM THE PNG. `ResizeWindow` answers with the size it was ASKED for, so a
+//     window that ignored the resize still reports success — measured in a consumer: 1280
+//     requested, 1100 in the file, four checks green.
+//
+// Both live in `@gjsify/devtools` (`captureShot`), so a consumer driving the control plane from
+// its own code gets them by importing one function rather than by copying a script.
+//
+// Dispatch is IN-PROCESS like `debug`/`storybook`: the generated entry imports
+// `@gjsify/devtools` + `@gjsify/devtools-mcp` from the CONSUMER's node_modules (so the CLI keeps
+// no dependency on either), is built `--app gjs`, and the RESULT is printed on stdout.
+//
+// WHY A GENERATED BUNDLE AND NOT `gdbus`: the peer transport (macOS/Windows, which have no
+// session bus) is `Gio.DBusServer` + an address file, and `gdbus` cannot speak it. A command
+// that reached the app only over the session bus would be the Linux-only half of a capability
+// the package deliberately made OS-agnostic.
+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 {};
+    }
+}
+/**
+ * The generated entry. It takes its options as ARGV rather than baking them in, so one cached
+ * bundle serves every invocation — the command-line flags of a rig change far more often than
+ * the code does, and a rebuild per flag would make `--timeout` cost a full bundle build.
+ *
+ * `system.exit(await …)` is load-bearing rather than decorative: 0 done / 1 the app said no /
+ * 2 the request itself was wrong is the whole contract a shell rig reads out of `$?`, and an
+ * awaited value cannot become a process exit status under GJS. `system.programArgs` are the
+ * user arguments — under `gjs -m bundle.js …` the `-m` and the path are `programInvocationName`,
+ * not args, so nothing has to be sliced off.
+ */
+function generateEntry() {
+    return `// Auto-generated by \`gjsify devtools\` — do not edit by hand.
+import system from 'system';
+
+import { runDevtoolsCli } from '@gjsify/devtools-mcp';
+
+system.exit(await runDevtoolsCli(system.programArgs));
+`;
+}
+/**
+ * `gjsify devtools` builds and runs a tiny client over the `org.gjsify.Devtools` control
+ * plane. Subcommands mirror the control-plane methods — `shot`, `find`, `activate`, `key`,
+ * `tree`, `property`, `resize`, `status`, `actions`, `toplevels`, `css`, `gsettings`,
+ * `instances` — so anything a rig does by hand over `gdbus` has a scriptable spelling.
+ */
+export const devtoolsCommand = {
+    command: 'devtools',
+    description: 'Drive a running devtools-enabled app from a script: capture a screenshot to a file, find a widget, ' +
+        'activate it, send a key. Peer of `gjsify debug`, which speaks MCP for an AI agent.',
+    builder: (yargs) => yargs
+        .positional('operation', {
+        description: 'Control-plane operation: shot | find | activate | key | tree | property | …',
+        type: 'string',
+        demandOption: true,
+    })
+        .positional('operands', {
+        description: 'Subcommand arguments — e.g. the output path for `shot`, the selector for `find`.',
+        type: 'string',
+        array: true,
+    })
+        .option('bus-name', {
+        description: "App DBus base name — the app's Gtk application id (default: gjsify.devtools.busNameBase, " +
+            'then the storybook app-id). Unlike `gjsify debug` there is no derived fallback: the bus name ' +
+            'IS the application id, and guessing it produces a name nothing answers to',
+        type: 'string',
+    })
+        .option('address', {
+        description: 'Peer D-Bus address of the app (unix:path=… / nonce-tcp:…) instead of the session bus — for ' +
+            'macOS/Windows, which have no session bus. Default: GJSIFY_DEVTOOLS_ADDRESS, then the address ' +
+            'file the app publishes, then the session bus',
+        type: 'string',
+    })
+        .option('instance', {
+        description: 'App instance label for a multi-instance app (default: GJSIFY_DEVTOOLS_INSTANCE)',
+        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-devtools)',
+        type: 'string',
+    })
+        .option('timeout', {
+        description: 'Seconds to keep polling GetStatus for the control plane to answer (default: 30). 0 = do not wait',
+        type: 'number',
+        default: 30,
+    }),
+    handler: async (args) => {
+        const cwd = process.cwd();
+        const pkg = readPackage(cwd);
+        const config = pkg.gjsify?.devtools ?? {};
+        const busNameBase = args.busName ??
+            config.busNameBase ??
+            pkg.gjsify?.storybook?.applicationId ??
+            pkg.gjsify?.browse?.applicationId;
+        // Asked for BEFORE a bundle is built: without a bus name the build succeeds and the
+        // client then exits 2 having done nothing, which reads like a broken app.
+        if (!busNameBase) {
+            console.error("gjsify devtools: no bus name — the bus name IS the app's Gtk application id, so it cannot be " +
+                'derived from the package name. Pass --bus-name <org.example.App> (the app prints it when it ' +
+                'exports the control plane) or set package.json#gjsify.devtools.busNameBase.');
+            return process.exit(1);
+        }
+        const cacheDir = join(cwd, 'node_modules', '.cache', 'gjsify-devtools');
+        mkdirSync(cacheDir, { recursive: true });
+        const entryPath = join(cacheDir, 'entry.ts');
+        const outPath = args.out ? resolve(cwd, args.out) : join(cacheDir, 'cli.gjs.mjs');
+        const globals = args.globals ?? 'auto';
+        writeFileSync(entryPath, generateEntry());
+        // stderr for progress — stdout is the RESULT the caller captures.
+        console.error(`[gjsify devtools] bus=${busNameBase}${args.address ? ` address=${args.address}` : ''}${args.instance ? ` instance=${args.instance}` : ''}`);
+        const { runCli } = await import('../cli-app.js');
+        await runCli(['build', entryPath, '--app', 'gjs', '--globals', globals, '--outfile', outPath]);
+        // The RESOLVED values are forwarded, never the raw argv: the child parses its own flags
+        // and knows nothing about package.json, so forwarding only what was typed would drop the
+        // configured bus name on the floor.
+        const forwarded = [args.operation, ...(args.operands ?? []), '--bus-name', busNameBase];
+        if (args.address)
+            forwarded.push('--address', args.address);
+        if (args.instance)
+            forwarded.push('--instance', args.instance);
+        forwarded.push('--timeout', String(args.timeout));
+        const { runGjsBundle } = await import('../utils/run-gjs.js');
+        await runGjsBundle(outPath, forwarded, { completion: 'exit', exitOnSuccess: true });
+    },
+};

package/lib/commands/index.d.ts

@@ -41,5 +41,7 @@ export * from './affected.js';
 export * from './storybook.js';
 export * from './dev.js';
 export * from './debug.js';
+export * from './devtools.js';
 export * from './browse.js';
 export { webextCommand } from './webext/index.js';
+export { blueprintCommand, blueprintTypesCommand } from './blueprint/index.js';

package/lib/commands/index.js

@@ -41,5 +41,7 @@ export * from './affected.js';
 export * from './storybook.js';
 export * from './dev.js';
 export * from './debug.js';
+export * from './devtools.js';
 export * from './browse.js';
 export { webextCommand } from './webext/index.js';
+export { blueprintCommand, blueprintTypesCommand } from './blueprint/index.js';