@gjsify/cli 0.3.3 → 0.3.5

package/lib/actions/build.js

@@ -2,8 +2,10 @@ import { build } from "esbuild";
 import { gjsifyPlugin } from "@gjsify/esbuild-plugin-gjsify";
 import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals, } from "@gjsify/esbuild-plugin-gjsify/globals";
 import { dirname, extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { chmod, readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
 const GJS_SHEBANG = "#!/usr/bin/env -S gjs -m\n";
 /** Walk up from dir until .pnp.cjs is found; return its directory or null. */
 function findPnpRoot(dir) {
@@ -22,26 +24,80 @@ function findPnpRoot(dir) {
  * @yarnpkg/esbuild-plugin-pnp plugin so esbuild can resolve
  * modules from zip archives without manual extraction.
  *
- * Custom onResolve: fall through on UNDECLARED_DEPENDENCY errors so the
- * gjsify alias plugin can handle bare specifiers (e.g. `abort-controller`)
- * that PnP can't resolve from the inject file's issuer context but that
- * gjsify maps to `@gjsify/*` packages the project DOES have available.
+ * Custom onResolve: when the project's PnP context throws
+ * UNDECLARED_DEPENDENCY, retry via a two-hop relay:
+ *   1. @gjsify/cli context (direct dep of the project using gjsify build)
+ *   2. @gjsify/node-polyfills context (direct dep of @gjsify/cli, has all
+ *      node polyfills as direct deps including @gjsify/node-globals)
+ *   3. @gjsify/web-polyfills context (direct dep of @gjsify/cli, has all
+ *      web polyfills as direct deps including @gjsify/fetch, @gjsify/abort-controller)
+ * For bare specifiers that the gjsify alias plugin maps (e.g. `abort-controller`),
+ * fall through so that plugin can handle the transformation first.
  */
 async function getPnpPlugin() {
     if (!findPnpRoot(process.cwd()))
         return null;
     try {
         const { pnpPlugin } = await import("@yarnpkg/esbuild-plugin-pnp");
+        // gjsify's own file path — @gjsify/cli has node-polyfills + web-polyfills
+        // 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 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}/package.json`));
+            }
+            catch {
+                // polyfills package not in dep tree — relay won't cover it
+            }
+        }
+        let pnpApi = null;
+        try {
+            // pnpapi has no npm package — it is a virtual module injected by Yarn PnP
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-expect-error
+            pnpApi = (await import("pnpapi"));
+        }
+        catch {
+            // Not in a PnP runtime (shouldn't happen since findPnpRoot passed)
+        }
         return pnpPlugin({
-            onResolve: async (_args, { resolvedPath, error, watchFiles }) => {
+            onResolve: async (args, { resolvedPath, error, watchFiles }) => {
                 if (resolvedPath !== null) {
                     return { namespace: "pnp", path: resolvedPath, watchFiles };
                 }
-                // UNDECLARED_DEPENDENCY: package exists transitively but isn't
-                // in the issuer's direct deps. Fall through so the gjsify alias
-                // plugin can resolve it (e.g. bare → @gjsify/* mappings).
                 if (error?.pnpCode ===
                     "UNDECLARED_DEPENDENCY") {
+                    if (pnpApi !== null) {
+                        // Try @gjsify/cli context first (covers @gjsify/* that are
+                        // direct deps of cli's own deps — unlikely but fast check).
+                        try {
+                            const rp = pnpApi.resolveRequest(args.path, gjsifyIssuer);
+                            if (rp !== null)
+                                return { namespace: "pnp", path: rp, watchFiles };
+                        }
+                        catch { }
+                        // Two-hop relay: resolve from node-polyfills / web-polyfills context
+                        // which have the individual @gjsify/* packages as direct deps.
+                        for (const relayIssuer of relayIssuers) {
+                            try {
+                                const rp = pnpApi.resolveRequest(args.path, relayIssuer);
+                                if (rp !== null)
+                                    return { namespace: "pnp", path: rp, watchFiles };
+                            }
+                            catch { }
+                        }
+                    }
+                    // Fall through — bare aliases (abort-controller, fetch/register/*)
+                    // are handled by the gjsify alias plugin after this returns null,
+                    // then the re-resolved @gjsify/* path goes through this hook again.
                     return null;
                 }
                 return {

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 };
+}