@gjsify/cli 0.3.3 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/cli",
-  "version": "0.3.3",
+  "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.3",
-    "@gjsify/esbuild-plugin-gjsify": "^0.3.3",
-    "@gjsify/example-dom-canvas2d-fireworks": "^0.3.3",
-    "@gjsify/example-dom-excalibur-jelly-jumper": "^0.3.3",
-    "@gjsify/example-dom-three-geometry-teapot": "^0.3.3",
-    "@gjsify/example-dom-three-postprocessing-pixel": "^0.3.3",
-    "@gjsify/example-node-express-webserver": "^0.3.3",
-    "@gjsify/node-polyfills": "^0.3.3",
-    "@gjsify/web-polyfills": "^0.3.3",
+    "@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

@@ -8,8 +8,10 @@ import {
 	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";
 
@@ -29,27 +31,85 @@ function findPnpRoot(dir: string): string | null {
  * @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(): Promise<Plugin | null> {
 	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: string[] = [];
+		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
+			}
+		}
+
+		// pnpapi is a virtual module injected by Yarn PnP at runtime.
+		type PnpApi = {
+			resolveRequest: (req: string, issuer: string) => string | null;
+		};
+		let pnpApi: PnpApi | null = 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")) as 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 as { pnpCode?: string } | null)?.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/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 };
+}