@gjsify/cli 0.3.4 → 0.3.5

package/lib/actions/build.js

@@ -43,13 +43,16 @@ async function getPnpPlugin() {
         // as direct deps, so we can resolve them as relay issuers from here.
         const gjsifyIssuer = fileURLToPath(import.meta.url);
         // Two-hop relay: node-polyfills and web-polyfills have all individual
-        // @gjsify/* packages as direct deps. Resolving from their paths allows
-        // PnP to reach e.g. @gjsify/node-globals (dep of node-polyfills).
+        // @gjsify/* packages as direct deps. Resolving from their package.json
+        // paths allows PnP to use them as issuers — sub-path imports
+        // (`@gjsify/foo/register/bar`) then resolve through the polyfill's
+        // dep graph. Resolve to package.json (always present, exports-agnostic)
+        // rather than main/module (the polyfills meta packages have no main).
         const requireFromGjsify = createRequire(gjsifyIssuer);
         const relayIssuers = [];
         for (const pkg of ["@gjsify/node-polyfills", "@gjsify/web-polyfills"]) {
             try {
-                relayIssuers.push(requireFromGjsify.resolve(pkg));
+                relayIssuers.push(requireFromGjsify.resolve(`${pkg}/package.json`));
             }
             catch {
                 // polyfills package not in dep tree — relay won't cover it

package/lib/commands/build.js

@@ -93,10 +93,9 @@ export const buildCommand = {
             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.",
+            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. Default: false (use --shebang to enable, or set `shebang: true` in `.gjsifyrc.js`).",
             type: 'boolean',
-            normalize: true,
-            default: false
+            normalize: true
         })
             .option('external', {
             description: "Module names that should NOT be bundled. Repeat the flag or pass a comma-separated list (e.g. --external typedoc,prettier). Globs are forwarded to esbuild as-is. See https://esbuild.github.io/api/#external",

package/lib/commands/dlx.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from '../types/index.js';
+interface DlxOptions {
+    spec: string;
+    binOrArg?: string;
+    extraArgs?: string[];
+    'cache-max-age': number;
+    verbose: boolean;
+    registry?: string;
+}
+export declare const dlxCommand: Command<any, DlxOptions>;
+export {};

package/lib/commands/dlx.js

@@ -0,0 +1,117 @@
+// `gjsify dlx <package> [bin] [-- args...]` — runs the GJS bundle of an
+// npm-published package without persisting it in the user's project.
+//
+// Cardinal rule: dlx is a **GJS-bundle runner**, not a generic bin runner.
+// It always invokes `gjs -m <bundle>` via the existing `runGjsBundle()` util.
+// Packages without a GJS entry (no `gjsify.main`/`gjsify.bin`, no fallback
+// `main`) fail loudly.
+//
+// Cache: $XDG_CACHE_HOME/gjsify/dlx/<sha256>/ with TTL (default 7d, override
+// via --cache-max-age=<minutes>). Cache hit on second run skips `npm install`
+// entirely. Layout + atomic-swap pattern adapted from pnpm's dlx implementation
+// (refs/pnpm/exec/commands/src/dlx.ts).
+import { runGjsBundle } from '../utils/run-gjs.js';
+import { parseSpec } from '../utils/parse-spec.js';
+import { resolveGjsEntry } from '../utils/resolve-gjs-entry.js';
+import { cacheDirFor, createCacheKey, getValidCachedPkg, makePrepareDir, resolveInstalledPkgDir, symlinkSwap, } from '../utils/dlx-cache.js';
+import { installPackages } from '../utils/install-backend.js';
+export const dlxCommand = {
+    command: 'dlx <spec> [binOrArg] [extraArgs..]',
+    description: 'Run the GJS bundle of an npm-published package without installing it locally.',
+    builder: (yargs) => yargs
+        .positional('spec', {
+        description: 'Package spec (`name`, `name@version`, `@scope/name@spec`, or local path).',
+        type: 'string',
+        demandOption: true,
+    })
+        .positional('binOrArg', {
+        description: 'Optional bin name when the package defines `gjsify.bin` with multiple entries; otherwise treated as the first argument forwarded to the bundle.',
+        type: 'string',
+    })
+        .positional('extraArgs', {
+        description: 'Extra args forwarded to `gjs -m <bundle>`.',
+        type: 'string',
+        array: true,
+    })
+        .option('cache-max-age', {
+        description: 'Cache TTL in minutes. Defaults to 7 days. Use 0 to bypass cache.',
+        type: 'number',
+        default: 60 * 24 * 7,
+    })
+        .option('verbose', {
+        description: 'Verbose logging (passes --loglevel verbose to npm).',
+        type: 'boolean',
+        default: false,
+    })
+        .option('registry', {
+        description: 'Registry URL override.',
+        type: 'string',
+    }),
+    handler: async (args) => {
+        const parsed = parseSpec(args.spec);
+        const { pkgDir, cachedPkgName } = await ensurePkgDir(parsed, {
+            verbose: args.verbose,
+            registry: args.registry,
+            cacheMaxAge: args['cache-max-age'],
+        });
+        // Bin / args disambiguation:
+        //   gjsify dlx <pkg>                         → no bin, no args
+        //   gjsify dlx <pkg> mybin                   → bin if package has gjsify.bin[mybin], else arg
+        //   gjsify dlx <pkg> mybin -- arg1 arg2      → bin + extra args
+        //   gjsify dlx <pkg> -- arg1 arg2            → no bin, extra args
+        const { binName, extraArgs } = splitBinAndArgs(pkgDir, args.binOrArg, args.extraArgs ?? []);
+        const entry = resolveGjsEntry(pkgDir, binName);
+        if (entry.fromFallback) {
+            console.warn(`[gjsify dlx] package "${cachedPkgName ?? parsed.kind}" has no \`gjsify\` field — falling back to package.json#main. Add \`gjsify.main\` to silence.`);
+        }
+        await runGjsBundle(entry.bundlePath, extraArgs);
+    },
+};
+async function ensurePkgDir(parsed, opts) {
+    if (parsed.kind === 'local') {
+        return { pkgDir: parsed.path, cachedPkgName: null };
+    }
+    const cacheKey = createCacheKey({ packages: [parsed.spec] });
+    const cacheDir = cacheDirFor(cacheKey);
+    const cached = opts.cacheMaxAge > 0 ? getValidCachedPkg(cacheDir, opts.cacheMaxAge) : undefined;
+    if (cached) {
+        return {
+            pkgDir: resolveInstalledPkgDir(cached, parsed.name),
+            cachedPkgName: parsed.name,
+        };
+    }
+    const prepareDir = makePrepareDir(cacheDir);
+    await installPackages({
+        prefix: prepareDir,
+        specs: [parsed.spec],
+        verbose: opts.verbose,
+        registry: opts.registry,
+    });
+    const liveTarget = symlinkSwap(cacheDir, prepareDir);
+    return {
+        pkgDir: resolveInstalledPkgDir(liveTarget, parsed.name),
+        cachedPkgName: parsed.name,
+    };
+}
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+function splitBinAndArgs(pkgDir, binOrArg, extraArgs) {
+    if (!binOrArg) {
+        return { binName: null, extraArgs };
+    }
+    const pkgJsonPath = join(pkgDir, 'package.json');
+    if (existsSync(pkgJsonPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+            const bins = pkg.gjsify?.bin;
+            if (bins && Object.prototype.hasOwnProperty.call(bins, binOrArg)) {
+                return { binName: binOrArg, extraArgs };
+            }
+        }
+        catch {
+            // Fall through to treating as an arg.
+        }
+    }
+    // Not a known bin — treat the positional as the first argv to the bundle.
+    return { binName: null, extraArgs: [binOrArg, ...extraArgs] };
+}

package/lib/commands/index.d.ts

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

package/lib/commands/index.js

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

package/lib/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
-import { buildCommand as build, runCommand as run, infoCommand as info, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, } 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, dlxCommand as dlx, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 void yargs(hideBin(process.argv))
     .scriptName(APP_NAME)
@@ -9,6 +9,7 @@ void yargs(hideBin(process.argv))
     .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(dlx.command, dlx.description, dlx.builder, dlx.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)

package/lib/utils/dlx-cache.d.ts

@@ -0,0 +1,34 @@
+interface CacheKeyOpts {
+    packages: string[];
+    registries?: Record<string, string>;
+}
+/** Stable, sorted JSON hash of inputs. */
+export declare function createCacheKey(opts: CacheKeyOpts): string;
+/** $XDG_CACHE_HOME/gjsify/dlx — created if missing. */
+export declare function dlxCacheRoot(): string;
+/** Per-key cache directory: <root>/<sha>. */
+export declare function cacheDirFor(cacheKey: string): string;
+/** A fresh prepare directory under the per-key cache, named timestamp-pid. */
+export declare function makePrepareDir(cacheDir: string): string;
+/**
+ * If <cacheDir>/pkg points to a target whose mtime + maxAge < now, return its
+ * realpath. Returns undefined when the link doesn't exist, isn't a symlink,
+ * has been removed, or has expired.
+ */
+export declare function getValidCachedPkg(cacheDir: string, maxAgeMinutes?: number): string | undefined;
+/**
+ * Atomically swap `<cacheDir>/pkg` to point at `prepareDir`.
+ *
+ * Strategy:
+ *   1. Create new symlink `<cacheDir>/pkg-<rand>` → prepareDir.
+ *   2. `rename(pkg-<rand>, pkg)` — POSIX guarantees rename-over-existing is atomic.
+ *
+ * Returns the realpath of the new live target. EBUSY/EEXIST indicates a race
+ * — a parallel process won, return its realpath.
+ */
+export declare function symlinkSwap(cacheDir: string, prepareDir: string): string;
+/** Clean up `<cacheDir>/<oldPrepareDir>` siblings older than `maxAgeMinutes`. */
+export declare function cleanupStalePrepareDirs(cacheDir: string, _maxAgeMinutes?: number): void;
+/** Resolve absolute path to the installed package's directory inside cache. */
+export declare function resolveInstalledPkgDir(cachedRoot: string, pkgName: string): string;
+export {};

package/lib/utils/dlx-cache.js

@@ -0,0 +1,120 @@
+// Cache for `gjsify dlx` — content-addressable, atomic, parallel-safe.
+//
+// Pattern adapted from refs/pnpm/exec/commands/src/dlx.ts:
+//   - cache key = sha256 over sorted [packages, registries]
+//   - cache layout: <root>/<sha>/{pkg,timestamp-pid}/
+//   - prepare into a fresh temp dir, then atomically swap a `pkg` symlink
+//   - TTL via lstat mtime + maxAgeMinutes (default 7 days)
+import { createHash } from 'node:crypto';
+import { lstatSync, mkdirSync, realpathSync, renameSync, rmSync, symlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+const ONE_MINUTE_MS = 60_000;
+const DEFAULT_TTL_MIN = 60 * 24 * 7; // 7 days
+function lexCompare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Stable, sorted JSON hash of inputs. */
+export function createCacheKey(opts) {
+    const sortedPkgs = [...opts.packages].sort(lexCompare);
+    const sortedRegs = Object.entries(opts.registries ?? {}).sort(([a], [b]) => lexCompare(a, b));
+    const payload = JSON.stringify([sortedPkgs, sortedRegs]);
+    return createHash('sha256').update(payload).digest('hex');
+}
+/** $XDG_CACHE_HOME/gjsify/dlx — created if missing. */
+export function dlxCacheRoot() {
+    const xdg = process.env.XDG_CACHE_HOME;
+    const base = xdg && xdg.length > 0 ? xdg : join(homedir(), '.cache');
+    const root = join(base, 'gjsify', 'dlx');
+    mkdirSync(root, { recursive: true });
+    return root;
+}
+/** Per-key cache directory: <root>/<sha>. */
+export function cacheDirFor(cacheKey) {
+    const dir = join(dlxCacheRoot(), cacheKey);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+/** A fresh prepare directory under the per-key cache, named timestamp-pid. */
+export function makePrepareDir(cacheDir) {
+    const name = `${Date.now().toString(16)}-${process.pid.toString(16)}`;
+    const dir = join(cacheDir, name);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+/**
+ * If <cacheDir>/pkg points to a target whose mtime + maxAge < now, return its
+ * realpath. Returns undefined when the link doesn't exist, isn't a symlink,
+ * has been removed, or has expired.
+ */
+export function getValidCachedPkg(cacheDir, maxAgeMinutes = DEFAULT_TTL_MIN) {
+    const linkPath = join(cacheDir, 'pkg');
+    let stats;
+    try {
+        stats = lstatSync(linkPath);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+    if (!stats.isSymbolicLink())
+        return undefined;
+    let target;
+    try {
+        target = realpathSync(linkPath);
+    }
+    catch {
+        return undefined;
+    }
+    const ageMs = Date.now() - stats.mtime.getTime();
+    return ageMs <= maxAgeMinutes * ONE_MINUTE_MS ? target : undefined;
+}
+/**
+ * Atomically swap `<cacheDir>/pkg` to point at `prepareDir`.
+ *
+ * Strategy:
+ *   1. Create new symlink `<cacheDir>/pkg-<rand>` → prepareDir.
+ *   2. `rename(pkg-<rand>, pkg)` — POSIX guarantees rename-over-existing is atomic.
+ *
+ * Returns the realpath of the new live target. EBUSY/EEXIST indicates a race
+ * — a parallel process won, return its realpath.
+ */
+export function symlinkSwap(cacheDir, prepareDir) {
+    const linkPath = join(cacheDir, 'pkg');
+    const tmpName = `pkg.tmp-${Date.now().toString(16)}-${process.pid.toString(16)}`;
+    const tmpLink = join(cacheDir, tmpName);
+    try {
+        symlinkSync(prepareDir, tmpLink, 'dir');
+    }
+    catch (err) {
+        // If we cannot even create the tmp link, give up.
+        throw err;
+    }
+    try {
+        renameSync(tmpLink, linkPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EBUSY' || code === 'EPERM' || code === 'EEXIST') {
+            // Race lost — clean up our tmp and use whoever won.
+            try {
+                rmSync(tmpLink);
+            }
+            catch { }
+            return realpathSync(linkPath);
+        }
+        throw err;
+    }
+    return realpathSync(linkPath);
+}
+/** Clean up `<cacheDir>/<oldPrepareDir>` siblings older than `maxAgeMinutes`. */
+export function cleanupStalePrepareDirs(cacheDir, _maxAgeMinutes = DEFAULT_TTL_MIN) {
+    // Out of scope for Phase 1 — pnpm has the same TODO. Leaving a stub so
+    // call sites already exist when we do implement it.
+    void cacheDir;
+}
+/** Resolve absolute path to the installed package's directory inside cache. */
+export function resolveInstalledPkgDir(cachedRoot, pkgName) {
+    return resolve(cachedRoot, 'node_modules', pkgName);
+}

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

@@ -0,0 +1,11 @@
+export interface InstallOptions {
+    /** Directory to install into (npm `--prefix`). Created by caller. */
+    prefix: string;
+    /** npm-resolvable specs: `name`, `name@version`, `git+https://...`, tarball URL, ... */
+    specs: string[];
+    /** Verbose logging passes through `--loglevel verbose`. */
+    verbose?: boolean;
+    /** Optional registry override (writes a temp `.npmrc` in prefix). */
+    registry?: string;
+}
+export declare function installPackages(opts: InstallOptions): Promise<void>;

package/lib/utils/install-backend.js

@@ -0,0 +1,57 @@
+// Install backend abstraction — Phase-4 seam.
+//
+// Today: spawns `npm install --no-package-lock --no-audit --no-fund --prefix <dir> <specs...>`.
+// Future (Phase 4): a GJS-native resolver replaces this without changing
+// the public signature, switched via `GJSIFY_INSTALL_BACKEND=native|npm`.
+//
+// Why npm and not pnpm/yarn? npm ships with Node so users already have it.
+// Adding a yarn/pnpm dep would defeat the purpose of `gjsify dlx` (which
+// itself is meant to ship binary-free GJS apps).
+//
+// `--no-package-lock` keeps the cache prepare dir hermetic; the cache key
+// already covers reproducibility. `--no-audit --no-fund` cuts ~5s off cold runs.
+import { spawn } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const DEFAULT_BACKEND = process.env.GJSIFY_INSTALL_BACKEND ?? 'npm';
+export async function installPackages(opts) {
+    if (DEFAULT_BACKEND === 'native') {
+        throw new Error('GJSIFY_INSTALL_BACKEND=native is reserved for the Phase 4 GJS-native resolver — not yet implemented.');
+    }
+    return installViaNpm(opts);
+}
+async function installViaNpm({ prefix, specs, verbose, registry }) {
+    if (specs.length === 0) {
+        throw new Error('installPackages: empty specs list');
+    }
+    // Seed an empty package.json so npm doesn't walk up from prefix and pick
+    // up the user's project metadata. Cosmetic name/version only.
+    writeFileSync(join(prefix, 'package.json'), JSON.stringify({ name: 'gjsify-dlx-cache', version: '0.0.0', private: true }, null, 2));
+    if (registry) {
+        writeFileSync(join(prefix, '.npmrc'), `registry=${registry}\n`);
+    }
+    const args = [
+        'install',
+        '--no-package-lock',
+        '--no-audit',
+        '--no-fund',
+        '--prefix', prefix,
+        ...(verbose ? ['--loglevel', 'verbose'] : ['--loglevel', 'warn']),
+        ...specs,
+    ];
+    await new Promise((resolve, reject) => {
+        const child = spawn('npm', args, { stdio: 'inherit' });
+        child.on('close', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`npm install exited with code ${code}`));
+        });
+        child.on('error', (err) => {
+            const msg = err.code === 'ENOENT'
+                ? 'npm not found on PATH — install Node.js or set GJSIFY_INSTALL_BACKEND=native (not yet supported)'
+                : `npm install failed: ${err.message}`;
+            reject(new Error(msg));
+        });
+    });
+}

package/lib/utils/parse-spec.d.ts

@@ -0,0 +1,20 @@
+export type ParsedSpec = {
+    kind: 'local';
+    path: string;
+} | {
+    kind: 'registry';
+    name: string;
+    version?: string;
+    spec: string;
+};
+/**
+ * Parse a CLI input into either a local-path or an npm-registry spec.
+ *
+ * Local: starts with `./`, `../`, `/`, or is an existing directory path.
+ * Registry: `<name>` | `<name>@<version>` | `@scope/<name>` | `@scope/<name>@<version>`
+ *
+ * The full spec string is preserved on the registry case so it can be passed
+ * verbatim to `npm install` (which already understands dist-tags, ranges,
+ * git URIs, tarball URLs, etc. — we don't re-parse those).
+ */
+export declare function parseSpec(input: string): ParsedSpec;

package/lib/utils/parse-spec.js

@@ -0,0 +1,37 @@
+// Parse a `gjsify dlx` package spec — distinguishes local paths from npm specs.
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+const NPM_NAME_RE = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+/**
+ * Parse a CLI input into either a local-path or an npm-registry spec.
+ *
+ * Local: starts with `./`, `../`, `/`, or is an existing directory path.
+ * Registry: `<name>` | `<name>@<version>` | `@scope/<name>` | `@scope/<name>@<version>`
+ *
+ * The full spec string is preserved on the registry case so it can be passed
+ * verbatim to `npm install` (which already understands dist-tags, ranges,
+ * git URIs, tarball URLs, etc. — we don't re-parse those).
+ */
+export function parseSpec(input) {
+    if (!input)
+        throw new Error('dlx: empty package spec');
+    if (input.startsWith('./') || input.startsWith('../') || isAbsolute(input)) {
+        return { kind: 'local', path: resolve(input) };
+    }
+    if (existsSync(input)) {
+        return { kind: 'local', path: resolve(input) };
+    }
+    // Registry spec: split off the version after the LAST `@` that isn't the
+    // leading scope separator.
+    let name = input;
+    let version;
+    const lastAt = input.lastIndexOf('@');
+    if (lastAt > 0) {
+        name = input.slice(0, lastAt);
+        version = input.slice(lastAt + 1);
+    }
+    if (!NPM_NAME_RE.test(name)) {
+        throw new Error(`dlx: invalid package name "${name}"`);
+    }
+    return { kind: 'registry', name, version, spec: input };
+}

package/lib/utils/resolve-gjs-entry.d.ts

@@ -0,0 +1,7 @@
+interface ResolvedEntry {
+    bundlePath: string;
+    binName: string | null;
+    fromFallback: boolean;
+}
+export declare function resolveGjsEntry(pkgDir: string, binName: string | null): ResolvedEntry;
+export {};

package/lib/utils/resolve-gjs-entry.js

@@ -0,0 +1,65 @@
+// Resolve the GJS entry point of an installed package.
+//
+// Per the `gjsify` field convention (see CLI reference):
+//
+//   {
+//     "gjsify": {
+//       "main": "dist/gjs.js",
+//       "bin":  { "name-a": "dist/a.js", "name-b": "dist/b.js" }
+//     }
+//   }
+//
+// Resolution order:
+//   1. user-supplied bin name + `gjsify.bin[name]`     → that path
+//   2. single-entry `gjsify.bin`                       → the only path
+//   3. `gjsify.main`                                   → that path
+//   4. fallback: `package.json#main`                   → that path (advisory warning)
+//   5. otherwise: hard-fail with a fix hint
+import { readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+export function resolveGjsEntry(pkgDir, binName) {
+    const pkgJsonPath = join(pkgDir, 'package.json');
+    if (!existsSync(pkgJsonPath)) {
+        throw new Error(`dlx: no package.json found at ${pkgDir}`);
+    }
+    const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+    const gjsifyBin = pkg.gjsify?.bin;
+    const gjsifyMain = pkg.gjsify?.main;
+    const fallbackMain = pkg.main;
+    let entry;
+    let resolvedBin = null;
+    let fromFallback = false;
+    if (binName !== null) {
+        if (!gjsifyBin || !gjsifyBin[binName]) {
+            const known = gjsifyBin ? Object.keys(gjsifyBin).join(', ') : '(none)';
+            throw new Error(`dlx: package "${pkg.name ?? pkgDir}" has no GJS bin named "${binName}" — known: ${known}`);
+        }
+        entry = gjsifyBin[binName];
+        resolvedBin = binName;
+    }
+    else if (gjsifyBin && Object.keys(gjsifyBin).length === 1) {
+        const onlyBin = Object.keys(gjsifyBin)[0];
+        entry = gjsifyBin[onlyBin];
+        resolvedBin = onlyBin;
+    }
+    else if (gjsifyMain) {
+        entry = gjsifyMain;
+    }
+    else if (fallbackMain) {
+        entry = fallbackMain;
+        fromFallback = true;
+    }
+    if (gjsifyBin && Object.keys(gjsifyBin).length > 1 && binName === null) {
+        const names = Object.keys(gjsifyBin).join(', ');
+        throw new Error(`dlx: package "${pkg.name ?? pkgDir}" defines multiple GJS bins — pass one of: ${names}`);
+    }
+    if (!entry) {
+        throw new Error(`dlx: package "${pkg.name ?? pkgDir}" has no GJS entry — set \`gjsify.main\` (or \`gjsify.bin\`) in its package.json`);
+    }
+    const bundlePath = resolve(pkgDir, entry);
+    if (!existsSync(bundlePath)) {
+        throw new Error(`dlx: GJS entry not found: ${bundlePath}`);
+    }
+    return { bundlePath, binName: resolvedBin, fromFallback };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/cli",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "CLI for Gjsify",
   "type": "module",
   "main": "lib/index.js",
@@ -23,15 +23,15 @@
     "cli"
   ],
   "dependencies": {
-    "@gjsify/create-app": "^0.3.4",
-    "@gjsify/esbuild-plugin-gjsify": "^0.3.4",
-    "@gjsify/example-dom-canvas2d-fireworks": "^0.3.4",
-    "@gjsify/example-dom-excalibur-jelly-jumper": "^0.3.4",
-    "@gjsify/example-dom-three-geometry-teapot": "^0.3.4",
-    "@gjsify/example-dom-three-postprocessing-pixel": "^0.3.4",
-    "@gjsify/example-node-express-webserver": "^0.3.4",
-    "@gjsify/node-polyfills": "^0.3.4",
-    "@gjsify/web-polyfills": "^0.3.4",
+    "@gjsify/create-app": "^0.3.5",
+    "@gjsify/esbuild-plugin-gjsify": "^0.3.5",
+    "@gjsify/example-dom-canvas2d-fireworks": "^0.3.5",
+    "@gjsify/example-dom-excalibur-jelly-jumper": "^0.3.5",
+    "@gjsify/example-dom-three-geometry-teapot": "^0.3.5",
+    "@gjsify/example-dom-three-postprocessing-pixel": "^0.3.5",
+    "@gjsify/example-node-express-webserver": "^0.3.5",
+    "@gjsify/node-polyfills": "^0.3.5",
+    "@gjsify/web-polyfills": "^0.3.5",
     "@yarnpkg/esbuild-plugin-pnp": "^3.0.0-rc.15",
     "cosmiconfig": "^9.0.1",
     "esbuild": "^0.28.0",

package/src/actions/build.ts

@@ -51,13 +51,16 @@ async function getPnpPlugin(): Promise<Plugin | null> {
 		const gjsifyIssuer = fileURLToPath(import.meta.url);
 
 		// Two-hop relay: node-polyfills and web-polyfills have all individual
-		// @gjsify/* packages as direct deps. Resolving from their paths allows
-		// PnP to reach e.g. @gjsify/node-globals (dep of node-polyfills).
+		// @gjsify/* packages as direct deps. Resolving from their package.json
+		// paths allows PnP to use them as issuers — sub-path imports
+		// (`@gjsify/foo/register/bar`) then resolve through the polyfill's
+		// dep graph. Resolve to package.json (always present, exports-agnostic)
+		// rather than main/module (the polyfills meta packages have no main).
 		const requireFromGjsify = createRequire(gjsifyIssuer);
 		const relayIssuers: string[] = [];
 		for (const pkg of ["@gjsify/node-polyfills", "@gjsify/web-polyfills"]) {
 			try {
-				relayIssuers.push(requireFromGjsify.resolve(pkg));
+				relayIssuers.push(requireFromGjsify.resolve(`${pkg}/package.json`));
 			} catch {
 				// polyfills package not in dep tree — relay won't cover it
 			}

package/src/commands/build.ts

@@ -95,10 +95,9 @@ export const buildCommand: Command<any, CliBuildOptions> = {
                 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.",
+                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. Default: false (use --shebang to enable, or set `shebang: true` in `.gjsifyrc.js`).",
                 type: 'boolean',
-                normalize: true,
-                default: false
+                normalize: true
             })
             .option('external', {
                 description: "Module names that should NOT be bundled. Repeat the flag or pass a comma-separated list (e.g. --external typedoc,prettier). Globs are forwarded to esbuild as-is. See https://esbuild.github.io/api/#external",

package/src/commands/dlx.ts

@@ -0,0 +1,173 @@
+// `gjsify dlx <package> [bin] [-- args...]` — runs the GJS bundle of an
+// npm-published package without persisting it in the user's project.
+//
+// Cardinal rule: dlx is a **GJS-bundle runner**, not a generic bin runner.
+// It always invokes `gjs -m <bundle>` via the existing `runGjsBundle()` util.
+// Packages without a GJS entry (no `gjsify.main`/`gjsify.bin`, no fallback
+// `main`) fail loudly.
+//
+// Cache: $XDG_CACHE_HOME/gjsify/dlx/<sha256>/ with TTL (default 7d, override
+// via --cache-max-age=<minutes>). Cache hit on second run skips `npm install`
+// entirely. Layout + atomic-swap pattern adapted from pnpm's dlx implementation
+// (refs/pnpm/exec/commands/src/dlx.ts).
+
+import type { Command } from '../types/index.js';
+import { runGjsBundle } from '../utils/run-gjs.js';
+import { parseSpec, type ParsedSpec } from '../utils/parse-spec.js';
+import { resolveGjsEntry } from '../utils/resolve-gjs-entry.js';
+import {
+    cacheDirFor,
+    createCacheKey,
+    getValidCachedPkg,
+    makePrepareDir,
+    resolveInstalledPkgDir,
+    symlinkSwap,
+} from '../utils/dlx-cache.js';
+import { installPackages } from '../utils/install-backend.js';
+
+interface DlxOptions {
+    spec: string;
+    binOrArg?: string;
+    extraArgs?: string[];
+    'cache-max-age': number;
+    verbose: boolean;
+    registry?: string;
+}
+
+export const dlxCommand: Command<any, DlxOptions> = {
+    command: 'dlx <spec> [binOrArg] [extraArgs..]',
+    description:
+        'Run the GJS bundle of an npm-published package without installing it locally.',
+    builder: (yargs) =>
+        yargs
+            .positional('spec', {
+                description:
+                    'Package spec (`name`, `name@version`, `@scope/name@spec`, or local path).',
+                type: 'string',
+                demandOption: true,
+            })
+            .positional('binOrArg', {
+                description:
+                    'Optional bin name when the package defines `gjsify.bin` with multiple entries; otherwise treated as the first argument forwarded to the bundle.',
+                type: 'string',
+            })
+            .positional('extraArgs', {
+                description: 'Extra args forwarded to `gjs -m <bundle>`.',
+                type: 'string',
+                array: true,
+            })
+            .option('cache-max-age', {
+                description:
+                    'Cache TTL in minutes. Defaults to 7 days. Use 0 to bypass cache.',
+                type: 'number',
+                default: 60 * 24 * 7,
+            })
+            .option('verbose', {
+                description: 'Verbose logging (passes --loglevel verbose to npm).',
+                type: 'boolean',
+                default: false,
+            })
+            .option('registry', {
+                description: 'Registry URL override.',
+                type: 'string',
+            }),
+    handler: async (args) => {
+        const parsed = parseSpec(args.spec);
+
+        const { pkgDir, cachedPkgName } = await ensurePkgDir(parsed, {
+            verbose: args.verbose,
+            registry: args.registry,
+            cacheMaxAge: args['cache-max-age'],
+        });
+
+        // Bin / args disambiguation:
+        //   gjsify dlx <pkg>                         → no bin, no args
+        //   gjsify dlx <pkg> mybin                   → bin if package has gjsify.bin[mybin], else arg
+        //   gjsify dlx <pkg> mybin -- arg1 arg2      → bin + extra args
+        //   gjsify dlx <pkg> -- arg1 arg2            → no bin, extra args
+        const { binName, extraArgs } = splitBinAndArgs(
+            pkgDir,
+            args.binOrArg,
+            args.extraArgs ?? [],
+        );
+
+        const entry = resolveGjsEntry(pkgDir, binName);
+        if (entry.fromFallback) {
+            console.warn(
+                `[gjsify dlx] package "${cachedPkgName ?? parsed.kind}" has no \`gjsify\` field — falling back to package.json#main. Add \`gjsify.main\` to silence.`,
+            );
+        }
+
+        await runGjsBundle(entry.bundlePath, extraArgs);
+    },
+};
+
+interface EnsureOpts {
+    verbose: boolean;
+    registry?: string;
+    cacheMaxAge: number;
+}
+
+async function ensurePkgDir(
+    parsed: ParsedSpec,
+    opts: EnsureOpts,
+): Promise<{ pkgDir: string; cachedPkgName: string | null }> {
+    if (parsed.kind === 'local') {
+        return { pkgDir: parsed.path, cachedPkgName: null };
+    }
+
+    const cacheKey = createCacheKey({ packages: [parsed.spec] });
+    const cacheDir = cacheDirFor(cacheKey);
+
+    const cached = opts.cacheMaxAge > 0 ? getValidCachedPkg(cacheDir, opts.cacheMaxAge) : undefined;
+    if (cached) {
+        return {
+            pkgDir: resolveInstalledPkgDir(cached, parsed.name),
+            cachedPkgName: parsed.name,
+        };
+    }
+
+    const prepareDir = makePrepareDir(cacheDir);
+    await installPackages({
+        prefix: prepareDir,
+        specs: [parsed.spec],
+        verbose: opts.verbose,
+        registry: opts.registry,
+    });
+
+    const liveTarget = symlinkSwap(cacheDir, prepareDir);
+    return {
+        pkgDir: resolveInstalledPkgDir(liveTarget, parsed.name),
+        cachedPkgName: parsed.name,
+    };
+}
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function splitBinAndArgs(
+    pkgDir: string,
+    binOrArg: string | undefined,
+    extraArgs: string[],
+): { binName: string | null; extraArgs: string[] } {
+    if (!binOrArg) {
+        return { binName: null, extraArgs };
+    }
+
+    const pkgJsonPath = join(pkgDir, 'package.json');
+    if (existsSync(pkgJsonPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8')) as {
+                gjsify?: { bin?: Record<string, string> };
+            };
+            const bins = pkg.gjsify?.bin;
+            if (bins && Object.prototype.hasOwnProperty.call(bins, binOrArg)) {
+                return { binName: binOrArg, extraArgs };
+            }
+        } catch {
+            // Fall through to treating as an arg.
+        }
+    }
+    // Not a known bin — treat the positional as the first argv to the bundle.
+    return { binName: null, extraArgs: [binOrArg, ...extraArgs] };
+}

package/src/commands/index.ts

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

package/src/index.ts

@@ -11,6 +11,7 @@ import {
     createCommand as create,
     gresourceCommand as gresource,
     gettextCommand as gettext,
+    dlxCommand as dlx,
 } from './commands/index.js'
 import { APP_NAME } from './constants.js'
 
@@ -20,6 +21,7 @@ void yargs(hideBin(process.argv))
     .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(dlx.command, dlx.description, dlx.builder, dlx.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)

package/src/utils/dlx-cache.ts

@@ -0,0 +1,135 @@
+// Cache for `gjsify dlx` — content-addressable, atomic, parallel-safe.
+//
+// Pattern adapted from refs/pnpm/exec/commands/src/dlx.ts:
+//   - cache key = sha256 over sorted [packages, registries]
+//   - cache layout: <root>/<sha>/{pkg,timestamp-pid}/
+//   - prepare into a fresh temp dir, then atomically swap a `pkg` symlink
+//   - TTL via lstat mtime + maxAgeMinutes (default 7 days)
+
+import { createHash } from 'node:crypto';
+import { lstatSync, mkdirSync, realpathSync, renameSync, rmSync, symlinkSync, type Stats } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const ONE_MINUTE_MS = 60_000;
+const DEFAULT_TTL_MIN = 60 * 24 * 7; // 7 days
+
+function lexCompare(a: string, b: string): number {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+
+interface CacheKeyOpts {
+    packages: string[];
+    registries?: Record<string, string>;
+}
+
+/** Stable, sorted JSON hash of inputs. */
+export function createCacheKey(opts: CacheKeyOpts): string {
+    const sortedPkgs = [...opts.packages].sort(lexCompare);
+    const sortedRegs = Object.entries(opts.registries ?? {}).sort(([a], [b]) => lexCompare(a, b));
+    const payload = JSON.stringify([sortedPkgs, sortedRegs]);
+    return createHash('sha256').update(payload).digest('hex');
+}
+
+/** $XDG_CACHE_HOME/gjsify/dlx — created if missing. */
+export function dlxCacheRoot(): string {
+    const xdg = process.env.XDG_CACHE_HOME;
+    const base = xdg && xdg.length > 0 ? xdg : join(homedir(), '.cache');
+    const root = join(base, 'gjsify', 'dlx');
+    mkdirSync(root, { recursive: true });
+    return root;
+}
+
+/** Per-key cache directory: <root>/<sha>. */
+export function cacheDirFor(cacheKey: string): string {
+    const dir = join(dlxCacheRoot(), cacheKey);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+
+/** A fresh prepare directory under the per-key cache, named timestamp-pid. */
+export function makePrepareDir(cacheDir: string): string {
+    const name = `${Date.now().toString(16)}-${process.pid.toString(16)}`;
+    const dir = join(cacheDir, name);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+
+/**
+ * If <cacheDir>/pkg points to a target whose mtime + maxAge < now, return its
+ * realpath. Returns undefined when the link doesn't exist, isn't a symlink,
+ * has been removed, or has expired.
+ */
+export function getValidCachedPkg(
+    cacheDir: string,
+    maxAgeMinutes: number = DEFAULT_TTL_MIN,
+): string | undefined {
+    const linkPath = join(cacheDir, 'pkg');
+    let stats: Stats;
+    try {
+        stats = lstatSync(linkPath);
+    } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+        throw err;
+    }
+    if (!stats.isSymbolicLink()) return undefined;
+
+    let target: string;
+    try {
+        target = realpathSync(linkPath);
+    } catch {
+        return undefined;
+    }
+
+    const ageMs = Date.now() - stats.mtime.getTime();
+    return ageMs <= maxAgeMinutes * ONE_MINUTE_MS ? target : undefined;
+}
+
+/**
+ * Atomically swap `<cacheDir>/pkg` to point at `prepareDir`.
+ *
+ * Strategy:
+ *   1. Create new symlink `<cacheDir>/pkg-<rand>` → prepareDir.
+ *   2. `rename(pkg-<rand>, pkg)` — POSIX guarantees rename-over-existing is atomic.
+ *
+ * Returns the realpath of the new live target. EBUSY/EEXIST indicates a race
+ * — a parallel process won, return its realpath.
+ */
+export function symlinkSwap(cacheDir: string, prepareDir: string): string {
+    const linkPath = join(cacheDir, 'pkg');
+    const tmpName = `pkg.tmp-${Date.now().toString(16)}-${process.pid.toString(16)}`;
+    const tmpLink = join(cacheDir, tmpName);
+
+    try {
+        symlinkSync(prepareDir, tmpLink, 'dir');
+    } catch (err) {
+        // If we cannot even create the tmp link, give up.
+        throw err;
+    }
+
+    try {
+        renameSync(tmpLink, linkPath);
+    } catch (err) {
+        const code = (err as NodeJS.ErrnoException).code;
+        if (code === 'EBUSY' || code === 'EPERM' || code === 'EEXIST') {
+            // Race lost — clean up our tmp and use whoever won.
+            try { rmSync(tmpLink); } catch {}
+            return realpathSync(linkPath);
+        }
+        throw err;
+    }
+
+    return realpathSync(linkPath);
+}
+
+/** Clean up `<cacheDir>/<oldPrepareDir>` siblings older than `maxAgeMinutes`. */
+export function cleanupStalePrepareDirs(cacheDir: string, _maxAgeMinutes: number = DEFAULT_TTL_MIN): void {
+    // Out of scope for Phase 1 — pnpm has the same TODO. Leaving a stub so
+    // call sites already exist when we do implement it.
+    void cacheDir;
+}
+
+/** Resolve absolute path to the installed package's directory inside cache. */
+export function resolveInstalledPkgDir(cachedRoot: string, pkgName: string): string {
+    return resolve(cachedRoot, 'node_modules', pkgName);
+}

package/src/utils/install-backend.ts

@@ -0,0 +1,79 @@
+// Install backend abstraction — Phase-4 seam.
+//
+// Today: spawns `npm install --no-package-lock --no-audit --no-fund --prefix <dir> <specs...>`.
+// Future (Phase 4): a GJS-native resolver replaces this without changing
+// the public signature, switched via `GJSIFY_INSTALL_BACKEND=native|npm`.
+//
+// Why npm and not pnpm/yarn? npm ships with Node so users already have it.
+// Adding a yarn/pnpm dep would defeat the purpose of `gjsify dlx` (which
+// itself is meant to ship binary-free GJS apps).
+//
+// `--no-package-lock` keeps the cache prepare dir hermetic; the cache key
+// already covers reproducibility. `--no-audit --no-fund` cuts ~5s off cold runs.
+
+import { spawn } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface InstallOptions {
+    /** Directory to install into (npm `--prefix`). Created by caller. */
+    prefix: string;
+    /** npm-resolvable specs: `name`, `name@version`, `git+https://...`, tarball URL, ... */
+    specs: string[];
+    /** Verbose logging passes through `--loglevel verbose`. */
+    verbose?: boolean;
+    /** Optional registry override (writes a temp `.npmrc` in prefix). */
+    registry?: string;
+}
+
+const DEFAULT_BACKEND = process.env.GJSIFY_INSTALL_BACKEND ?? 'npm';
+
+export async function installPackages(opts: InstallOptions): Promise<void> {
+    if (DEFAULT_BACKEND === 'native') {
+        throw new Error(
+            'GJSIFY_INSTALL_BACKEND=native is reserved for the Phase 4 GJS-native resolver — not yet implemented.',
+        );
+    }
+    return installViaNpm(opts);
+}
+
+async function installViaNpm({ prefix, specs, verbose, registry }: InstallOptions): Promise<void> {
+    if (specs.length === 0) {
+        throw new Error('installPackages: empty specs list');
+    }
+
+    // Seed an empty package.json so npm doesn't walk up from prefix and pick
+    // up the user's project metadata. Cosmetic name/version only.
+    writeFileSync(
+        join(prefix, 'package.json'),
+        JSON.stringify({ name: 'gjsify-dlx-cache', version: '0.0.0', private: true }, null, 2),
+    );
+
+    if (registry) {
+        writeFileSync(join(prefix, '.npmrc'), `registry=${registry}\n`);
+    }
+
+    const args = [
+        'install',
+        '--no-package-lock',
+        '--no-audit',
+        '--no-fund',
+        '--prefix', prefix,
+        ...(verbose ? ['--loglevel', 'verbose'] : ['--loglevel', 'warn']),
+        ...specs,
+    ];
+
+    await new Promise<void>((resolve, reject) => {
+        const child = spawn('npm', args, { stdio: 'inherit' });
+        child.on('close', (code) => {
+            if (code === 0) resolve();
+            else reject(new Error(`npm install exited with code ${code}`));
+        });
+        child.on('error', (err) => {
+            const msg = (err as NodeJS.ErrnoException).code === 'ENOENT'
+                ? 'npm not found on PATH — install Node.js or set GJSIFY_INSTALL_BACKEND=native (not yet supported)'
+                : `npm install failed: ${err.message}`;
+            reject(new Error(msg));
+        });
+    });
+}

package/src/utils/parse-spec.ts

@@ -0,0 +1,48 @@
+// Parse a `gjsify dlx` package spec — distinguishes local paths from npm specs.
+
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+
+export type ParsedSpec =
+    | { kind: 'local'; path: string }
+    | { kind: 'registry'; name: string; version?: string; spec: string };
+
+const NPM_NAME_RE = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+
+/**
+ * Parse a CLI input into either a local-path or an npm-registry spec.
+ *
+ * Local: starts with `./`, `../`, `/`, or is an existing directory path.
+ * Registry: `<name>` | `<name>@<version>` | `@scope/<name>` | `@scope/<name>@<version>`
+ *
+ * The full spec string is preserved on the registry case so it can be passed
+ * verbatim to `npm install` (which already understands dist-tags, ranges,
+ * git URIs, tarball URLs, etc. — we don't re-parse those).
+ */
+export function parseSpec(input: string): ParsedSpec {
+    if (!input) throw new Error('dlx: empty package spec');
+
+    if (input.startsWith('./') || input.startsWith('../') || isAbsolute(input)) {
+        return { kind: 'local', path: resolve(input) };
+    }
+
+    if (existsSync(input)) {
+        return { kind: 'local', path: resolve(input) };
+    }
+
+    // Registry spec: split off the version after the LAST `@` that isn't the
+    // leading scope separator.
+    let name = input;
+    let version: string | undefined;
+    const lastAt = input.lastIndexOf('@');
+    if (lastAt > 0) {
+        name = input.slice(0, lastAt);
+        version = input.slice(lastAt + 1);
+    }
+
+    if (!NPM_NAME_RE.test(name)) {
+        throw new Error(`dlx: invalid package name "${name}"`);
+    }
+
+    return { kind: 'registry', name, version, spec: input };
+}

package/src/utils/resolve-gjs-entry.ts

@@ -0,0 +1,96 @@
+// Resolve the GJS entry point of an installed package.
+//
+// Per the `gjsify` field convention (see CLI reference):
+//
+//   {
+//     "gjsify": {
+//       "main": "dist/gjs.js",
+//       "bin":  { "name-a": "dist/a.js", "name-b": "dist/b.js" }
+//     }
+//   }
+//
+// Resolution order:
+//   1. user-supplied bin name + `gjsify.bin[name]`     → that path
+//   2. single-entry `gjsify.bin`                       → the only path
+//   3. `gjsify.main`                                   → that path
+//   4. fallback: `package.json#main`                   → that path (advisory warning)
+//   5. otherwise: hard-fail with a fix hint
+
+import { readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+interface ResolvedEntry {
+    bundlePath: string;
+    binName: string | null;
+    fromFallback: boolean;
+}
+
+interface PackageJson {
+    name?: string;
+    main?: string;
+    gjsify?: {
+        main?: string;
+        bin?: Record<string, string>;
+        prebuilds?: string;
+    };
+}
+
+export function resolveGjsEntry(
+    pkgDir: string,
+    binName: string | null,
+): ResolvedEntry {
+    const pkgJsonPath = join(pkgDir, 'package.json');
+    if (!existsSync(pkgJsonPath)) {
+        throw new Error(`dlx: no package.json found at ${pkgDir}`);
+    }
+    const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8')) as PackageJson;
+
+    const gjsifyBin = pkg.gjsify?.bin;
+    const gjsifyMain = pkg.gjsify?.main;
+    const fallbackMain = pkg.main;
+
+    let entry: string | undefined;
+    let resolvedBin: string | null = null;
+    let fromFallback = false;
+
+    if (binName !== null) {
+        if (!gjsifyBin || !gjsifyBin[binName]) {
+            const known = gjsifyBin ? Object.keys(gjsifyBin).join(', ') : '(none)';
+            throw new Error(
+                `dlx: package "${pkg.name ?? pkgDir}" has no GJS bin named "${binName}" — known: ${known}`,
+            );
+        }
+        entry = gjsifyBin[binName];
+        resolvedBin = binName;
+    } else if (gjsifyBin && Object.keys(gjsifyBin).length === 1) {
+        const onlyBin = Object.keys(gjsifyBin)[0];
+        entry = gjsifyBin[onlyBin];
+        resolvedBin = onlyBin;
+    } else if (gjsifyMain) {
+        entry = gjsifyMain;
+    } else if (fallbackMain) {
+        entry = fallbackMain;
+        fromFallback = true;
+    }
+
+    if (gjsifyBin && Object.keys(gjsifyBin).length > 1 && binName === null) {
+        const names = Object.keys(gjsifyBin).join(', ');
+        throw new Error(
+            `dlx: package "${pkg.name ?? pkgDir}" defines multiple GJS bins — pass one of: ${names}`,
+        );
+    }
+
+    if (!entry) {
+        throw new Error(
+            `dlx: package "${pkg.name ?? pkgDir}" has no GJS entry — set \`gjsify.main\` (or \`gjsify.bin\`) in its package.json`,
+        );
+    }
+
+    const bundlePath = resolve(pkgDir, entry);
+    if (!existsSync(bundlePath)) {
+        throw new Error(`dlx: GJS entry not found: ${bundlePath}`);
+    }
+
+    return { bundlePath, binName: resolvedBin, fromFallback };
+}