@gjsify/cli 0.25.1 → 0.26.1

package/lib/commands/onboard.js

@@ -116,8 +116,7 @@ export const onboardCommand = {
                 process.stdout.write(`${JSON.stringify({ ok: false, error: 'auth', message: msg })}\n`);
             else
                 console.error(msg);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         // Login may have written a fresh token — reload so the probes/ops use it.
         npmrc = await loadNpmrc(cwd);
@@ -136,8 +135,7 @@ export const onboardCommand = {
                 process.stdout.write(`${JSON.stringify({ ok: false, error: 'repository', message: msg })}\n`);
             else
                 console.error(msg);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         const workflow = normalizeWorkflowFile(args.workflow);
         const environment = args.environment;
@@ -155,8 +153,7 @@ export const onboardCommand = {
                 process.stdout.write(`${JSON.stringify({ ok: false, error: 'no-packages', message: msg })}\n`);
             else
                 console.error(msg);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         log(`gjsify onboard: ${selected.length} package(s) | repo=${repository} workflow=${workflow}`);
         if (dryRun)

package/lib/commands/publish.js

@@ -125,7 +125,9 @@ export const publishCommand = {
             const rawPkg = JSON.parse(readFileSync(rawPkgPath, 'utf-8'));
             if (typeof rawPkg.name !== 'string') {
                 process.stderr.write(`gjsify publish --check-trusted: ${rawPkgPath} has no \`name\` field\n`);
-                process.exit(2);
+                // `return` — a bare `process.exit()` is deferred under GJS and
+                // the check would continue on a nameless manifest.
+                return process.exit(2);
             }
             if (rawPkg.private === true) {
                 const out = { ok: true, action: 'check-trusted', name: rawPkg.name, skipped: 'private' };
@@ -432,13 +434,11 @@ function reportPublishOutcome(outcome, asJson) {
         }
         case 'otp-required': {
             console.error(`gjsify publish: npm requires a 2FA one-time code — re-run with \`--otp <code>\``);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         case 'oidc-failed': {
             handleOidcFailure(outcome.error, outcome.name, asJson);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         case 'oidc-no-token': {
             const msg = outcome.error instanceof Error ? outcome.error.message : String(outcome.error);
@@ -446,8 +446,7 @@ function reportPublishOutcome(outcome, asJson) {
             if (asJson) {
                 process.stdout.write(`${JSON.stringify({ ok: false, name: outcome.name, version: outcome.version, error: 'oidc-failed-no-token' }, null, 2)}\n`);
             }
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         case 'diagnostic': {
             if (asJson) {
@@ -463,14 +462,12 @@ function reportPublishOutcome(outcome, asJson) {
             else {
                 process.stderr.write(`${outcome.diag.message}\n`);
             }
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         case 'error': {
             console.error(`gjsify publish: ${outcome.name}@${outcome.version} — ${outcome.status} ${outcome.statusText}`);
             console.error(outcome.text);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
     }
 }

package/lib/commands/self-update.js

@@ -65,15 +65,13 @@ export const selfUpdateCommand = {
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             console.error(`Failed to fetch packument: ${msg}`);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         const target = resolveTag(packument, args.tag);
         if (!target) {
             console.error(`Unknown dist-tag '${args.tag}' on ${PACKAGE_NAME}. ` +
                 `Known tags: ${Object.keys(packument['dist-tags'] ?? {}).join(', ') || '(none)'}`);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         console.log(`Latest matching --tag ${args.tag}: v${target}`);
         // A version match is NOT sufficient to declare "up to date": a global
@@ -103,8 +101,7 @@ export const selfUpdateCommand = {
         }
         if (args.check) {
             console.log(currentVersion ? `Update available: v${currentVersion} → v${target}` : `Install required: → v${target}`);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         // `@gjsify/cli` ships two runtimes from one package: the Node `bin`
         // (`lib/index.js`, which imports its deps from `node_modules`) and the
@@ -141,8 +138,7 @@ export const selfUpdateCommand = {
             const msg = err instanceof Error ? err.message : String(err);
             console.error(`self-update: install failed — ${msg}`);
             console.error(`Re-run \`gjsify self-update\` to retry.`);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         // Lay down (or repair) the GJS-native engine bridges in lockstep with
         // the bundle — same set + best-effort handling as the global installer.

package/lib/commands/showcase.d.ts

@@ -1,4 +1,20 @@
 import type { Command } from '../types/index.js';
+/**
+ * Pinned invocations for the three runners that cache an unpinned bin.
+ *
+ * The deno line carries TWO flags because deno stacks two independent refusals,
+ * and dropping either one leaves the hint broken in exactly the window where it
+ * is reached most: `--reload` busts the `DENO_DIR` copy, and `--min-dep-age 0`
+ * waives deno's supply-chain policy of refusing any version published within
+ * the last 24 h (`minimumDependencyAge`, default `24h`). Without the second
+ * flag `@latest` silently resolves to the newest release OLDER THAN A DAY — so
+ * a user who hits a bug, is told to run `@latest`, and does, gets the SAME
+ * pre-fix binary back and a stale error message with it. Measured twice on one
+ * day against 0.25.1 (minutes old) falling back to 0.24.1. `@latest` is kept
+ * rather than a baked version so the hint cannot go stale itself; the age
+ * waiver is what makes `@latest` mean latest.
+ */
+export declare const PIN_HINT: string;
 interface ShowcaseOptions {
     name?: string;
     json: boolean;

package/lib/commands/showcase.js

@@ -7,7 +7,7 @@ import { ensurePkgDir } from './dlx.js';
 import { parseSpec } from '../utils/parse-spec.js';
 import { resolveNodeEntry } from '../utils/resolve-gjs-entry.js';
 import { runRuntimeBundle } from '../utils/run-node.js';
-import { EXAMPLE_RUNTIMES, isExampleRuntime, readDeclaredRuntimes, checkRuntimeSupported, defaultExampleRuntime, } from '../utils/runtimes.js';
+import { EXAMPLE_RUNTIMES, isExampleRuntime, readDeclaredRuntimes, checkRuntimeSupported, defaultExampleRuntime, requiresGjsSystemDeps, } from '../utils/runtimes.js';
 function readCliVersion() {
     try {
         const pkgUrl = new URL('../../package.json', import.meta.url);
@@ -34,11 +34,25 @@ function readCliVersion() {
 function runningAs(cliVersion) {
     return cliVersion ? `[gjsify ${cliVersion}] ` : '';
 }
-/** Pinned invocations for the three runners that cache an unpinned bin. */
-const PIN_HINT = 'A package runner reuses a CACHED copy of an unpinned bin. Force the current one:\n' +
+/**
+ * Pinned invocations for the three runners that cache an unpinned bin.
+ *
+ * The deno line carries TWO flags because deno stacks two independent refusals,
+ * and dropping either one leaves the hint broken in exactly the window where it
+ * is reached most: `--reload` busts the `DENO_DIR` copy, and `--min-dep-age 0`
+ * waives deno's supply-chain policy of refusing any version published within
+ * the last 24 h (`minimumDependencyAge`, default `24h`). Without the second
+ * flag `@latest` silently resolves to the newest release OLDER THAN A DAY — so
+ * a user who hits a bug, is told to run `@latest`, and does, gets the SAME
+ * pre-fix binary back and a stale error message with it. Measured twice on one
+ * day against 0.25.1 (minutes old) falling back to 0.24.1. `@latest` is kept
+ * rather than a baked version so the hint cannot go stale itself; the age
+ * waiver is what makes `@latest` mean latest.
+ */
+export const PIN_HINT = 'A package runner reuses a CACHED copy of an unpinned bin. Force the current one:\n' +
     '    npx @gjsify/cli@latest showcase <name>\n' +
     '    bunx @gjsify/cli@latest showcase <name>\n' +
-    '    deno run -A --reload npm:@gjsify/cli@latest showcase <name>';
+    '    deno run -A --reload --min-dep-age 0 npm:@gjsify/cli@latest showcase <name>';
 export const showcaseCommand = {
     command: 'showcase [name]',
     description: 'List or run curated gjsify showcase applications.',
@@ -119,33 +133,39 @@ export const showcaseCommand = {
             // `m_should_exit` core dump. Returning halts the handler here.
             return process.exit(1);
         }
+        // Resolve the runtime BEFORE the system-dependency gate: that gate is a
+        // question ABOUT the runtime, and asking it first gated every showcase
+        // on a gjs binary (see `requiresGjsSystemDeps`).
+        const runtime = (args.runtime ?? defaultExampleRuntime());
+        if (!isExampleRuntime(runtime)) {
+            console.error(`Unknown --runtime "${runtime}" (expected: ${EXAMPLE_RUNTIMES.join(', ')}).`);
+            // `return` — bare `process.exit` falls through under GJS (see above).
+            return process.exit(1);
+        }
         // System dependency check before delegating — only system libs (gjs,
-        // gtk4, …). The showcase's npm deps (incl. `@gjsify/webgl` with the
+        // gtk4, …), and only for a runtime that consumes the `--app gjs`
+        // bundle. The showcase's npm deps (incl. `@gjsify/webgl` with the
         // gwebgl Vala prebuild) are fetched by `gjsify dlx` into the npm
         // cache, and `runGjsBundle()` picks the prebuild up from the bundle
         // dir via `detectNativePackages()`. Pre-flight-checking npm deps
         // here would fail for `npx @gjsify/cli showcase` (no project
         // node_modules, CLI doesn't dep on the showcase libs).
-        const results = runMinimalChecks();
-        const missingHard = results.filter((r) => !r.found && r.severity === 'required');
-        if (missingHard.length > 0) {
-            console.error('Missing system dependencies:\n');
-            for (const dep of missingHard) {
-                console.error(`  ✗  ${dep.name}`);
-            }
-            const pm = detectPackageManager();
-            const cmd = buildInstallCommand(pm, missingHard);
-            if (cmd) {
-                console.error(`\nInstall with:\n  ${cmd}`);
+        if (requiresGjsSystemDeps(runtime)) {
+            const results = runMinimalChecks();
+            const missingHard = results.filter((r) => !r.found && r.severity === 'required');
+            if (missingHard.length > 0) {
+                console.error('Missing system dependencies:\n');
+                for (const dep of missingHard) {
+                    console.error(`  ✗  ${dep.name}`);
+                }
+                const pm = detectPackageManager();
+                const cmd = buildInstallCommand(pm, missingHard);
+                if (cmd) {
+                    console.error(`\nInstall with:\n  ${cmd}`);
+                }
+                // `return` — bare `process.exit` falls through under GJS (see above).
+                return process.exit(1);
             }
-            // `return` — bare `process.exit` falls through under GJS (see above).
-            return process.exit(1);
-        }
-        const runtime = (args.runtime ?? defaultExampleRuntime());
-        if (!isExampleRuntime(runtime)) {
-            console.error(`Unknown --runtime "${runtime}" (expected: ${EXAMPLE_RUNTIMES.join(', ')}).`);
-            // `return` — bare `process.exit` falls through under GJS (see above).
-            return process.exit(1);
         }
         const cliVersion = readCliVersion();
         // Non-gjs runtime: resolve the showcase's `--app node` bundle and run it

package/lib/commands/storybook.js

@@ -136,8 +136,22 @@ export const storybookCommand = {
         };
         const initialCount = writeEntry();
         if (initialCount === 0) {
-            console.error(`No *.story.ts files found under ${relative(cwd, storiesDir) || storiesDir}`);
-            process.exit(1);
+            // `return process.exit()`: a bare `process.exit()` does NOT halt
+            // synchronously under GJS (no atexit, the GLib loop is still
+            // armed), so execution fell through to the "Found 0 story file(s)"
+            // log and on into the build — and the deferred exit never carried
+            // its code, so `gjsify storybook` in a directory with no stories
+            // printed BOTH messages and exited 0. Measured: exit 1 under bun,
+            // exit 0 under gjs, same command. Same trap as `showcase.ts`.
+            console.error(`No *.story.ts files found under ${relative(cwd, storiesDir) || storiesDir}\n\n` +
+                `  \`gjsify storybook\` renders the stories of the CURRENT project: it discovers\n` +
+                `  \`*.story.ts\` files and launches a component browser over them. Point it at a\n` +
+                `  different directory with --stories <dir> (or \`gjsify.storybook.stories\` in\n` +
+                `  package.json) if yours live elsewhere.\n\n` +
+                `  To SEE a storybook without authoring one first, run the curated Libadwaita\n` +
+                `  component browser — it is a showcase, so it needs no project at all:\n\n` +
+                `      gjsify showcase adwaita-storybook`);
+            return process.exit(1);
         }
         console.log(`Found ${initialCount} story file(s) under ${relative(cwd, storiesDir) || '.'} (runtime: ${runtime})`);
         // In-process build — runtime-agnostic (Node uses npm rolldown, GJS uses

package/lib/commands/system-check.js

@@ -18,8 +18,7 @@ export const systemCheckCommand = {
         if (args.json) {
             console.log(JSON.stringify({ packageManager: pm, deps: results }, null, 2));
             // Only required deps influence the exit code.
-            process.exit(missingRequired.length > 0 ? 1 : 0);
-            return;
+            return process.exit(missingRequired.length > 0 ? 1 : 0);
         }
         console.log('System dependency check\n');
         const required = results.filter((r) => r.severity === 'required');

package/lib/commands/test.js

@@ -60,7 +60,9 @@ export const testCommand = {
             console.error(`[gjsify test] no test entry at ${relative(cwd, entry)} — ` +
                 `add an \`src/test.mts\` that aggregates your \`@gjsify/unit\` suites, ` +
                 `or set \`gjsify.test.entry\` in package.json.`);
-            process.exit(1);
+            // `return` — a bare `process.exit()` is deferred under GJS and the
+            // handler would try to build the missing entry anyway.
+            return process.exit(1);
         }
         const requested = args.runtime === 'gjs'
             ? ['gjs']
@@ -124,7 +126,9 @@ export const testCommand = {
         console.log(`[gjsify test] ${summary}`);
         const anyFailed = results.some((r) => !r.ok);
         if (anyFailed) {
-            process.exit(1);
+            // `return` — the deferred GJS exit otherwise fell through to the
+            // success `process.exit(0)` below, clobbering the failure code.
+            return process.exit(1);
         }
         // Explicit success exit: under GJS the spawn-armed main loop would
         // otherwise park this process after the summary. (runGjsBundle

package/lib/commands/trust.js

@@ -79,7 +79,9 @@ export const trustCommand = {
         const npmrc = await loadNpmrc(cwd);
         if (!hasAnyCredential(npmrc)) {
             console.error('gjsify trust: no npm token configured. Run `gjsify login` first.');
-            process.exit(1);
+            // `return` — a bare `process.exit()` is deferred under GJS and the
+            // handler would keep going without credentials.
+            return process.exit(1);
         }
         // Pre-flight: a present-but-DEAD token would otherwise surface as a
         // confusing per-package `401 "You must be logged in to publish
@@ -97,13 +99,13 @@ export const trustCommand = {
                 console.error(`gjsify trust: npm auth check failed (${msg}).\n` +
                     'Your ~/.npmrc token is dead or revoked — refresh it with `npm login`, then re-run.\n' +
                     '(`gjsify trust` uses the ~/.npmrc bearer token directly — unlike `npm trust`, which logs in via the browser.)');
-                process.exit(1);
-                return;
+                return process.exit(1);
             }
             if (!who.username) {
                 console.error('gjsify trust: your npm token appears dead or revoked (registry returned an empty whoami).\n' +
                     'Refresh it with `npm login`, then re-run.');
-                process.exit(1);
+                // `return` — see the deferred-exit note on the guard above.
+                return process.exit(1);
             }
             console.log(`gjsify trust: authenticated as ${who.username}`);
         }
@@ -117,11 +119,13 @@ export const trustCommand = {
         if (!repository) {
             console.error('gjsify trust: could not determine the GitHub repository.\n' +
                 'Pass --repository owner/repo (no `origin` remote to infer from).');
-            process.exit(1);
+            // `return` — see the deferred-exit note on the guard above.
+            return process.exit(1);
         }
         if (!validateRepository(repository)) {
             console.error(`gjsify trust: --repository must be "owner/repo", got "${repository}".`);
-            process.exit(1);
+            // `return` — see the deferred-exit note on the guard above.
+            return process.exit(1);
         }
         const workflow = normalizeWorkflowFile(args.workflow);
         const environment = args.environment;
@@ -148,7 +152,8 @@ export const trustCommand = {
         }).filter((ws) => ws.name);
         if (selected.length === 0) {
             console.error('gjsify trust: no publishable packages matched.');
-            process.exit(1);
+            // `return` — see the deferred-exit note on the guard above.
+            return process.exit(1);
         }
         console.log(`gjsify trust: ${selected.length} package(s) | repo=${repository} workflow=${workflow}`);
         if (dryRun)

package/lib/commands/tsc.js

@@ -104,7 +104,9 @@ export const tscCommand = {
         if (!bundlePath && !nodeTscPath) {
             console.error('gjsify tsc: neither @gjsify/tsc (GJS bundle) nor npm `typescript` (Node) is installed.');
             console.error('  Install with: gjsify install --save-dev @gjsify/tsc   (or add `typescript`).');
-            process.exit(1);
+            // `return` — a bare `process.exit()` is deferred under GJS and the
+            // handler would try to spawn a compiler that is not there.
+            return process.exit(1);
         }
         // Mirror `gjsify run`'s native-env composition so any future
         // typescript-the-bundle code path that reaches a native bridge

package/lib/commands/uninstall.js

@@ -46,8 +46,7 @@ export const uninstallCommand = {
         if (!args.global) {
             console.error('gjsify uninstall currently only supports --global. ' +
                 'For project-local removal, edit package.json + re-run `gjsify install`.');
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         const layout = defaultGlobalLayout();
         const dryRun = args['dry-run'] ?? false;

package/lib/commands/whoami.js

@@ -69,7 +69,9 @@ export const whoamiCommand = {
                     'Then verify:  gjsify whoami',
                 ].join('\n') + '\n');
             }
-            process.exit(1);
+            // `return` — a bare `process.exit()` is deferred under GJS and the
+            // handler would probe the registry without a token.
+            return process.exit(1);
         }
         let result;
         try {
@@ -85,8 +87,9 @@ export const whoamiCommand = {
                 process.stderr.write(`gjsify whoami: ${message}\n`);
                 process.stderr.write(`Registry: ${registryClean}\n`);
             }
-            process.exit(1);
-            return; // unreachable but pleases the type narrower
+            // `return process.exit` also keeps the type narrower happy: the
+            // never-typed call marks this branch as terminated.
+            return process.exit(1);
         }
         if (result.username && result.username.length > 0) {
             // Branch 1 — live token.

package/lib/utils/build-cache.js

@@ -49,10 +49,11 @@
 // or a permission error degrade to "run the script uncached" — a cache
 // hiccup must never break a build.
 import { createHash } from 'node:crypto';
-import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, readSync, renameSync, rmSync, symlinkSync, copyFileSync, writeFileSync, } from 'node:fs';
+import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, readSync, renameSync, rmSync, copyFileSync, writeFileSync, } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { buildDependencyGraph } from '@gjsify/workspace';
+import { replicateLinkSync } from './dir-link.js';
 /**
  * Bump to invalidate every existing cache entry (schema/semantic changes).
  *
@@ -417,7 +418,11 @@ function copyDirRecursive(from, to) {
         const dst = join(to, entry);
         const st = lstatSync(src);
         if (st.isSymbolicLink()) {
-            symlinkSync(readlinkSync(src), dst);
+            // Not `symlinkSync(readlinkSync(src), dst)`: replicating a link to a
+            // DIRECTORY verbatim needs a junction on Windows, and the target has
+            // to be resolved for it. See `dir-link.ts` — the one definition of
+            // that rule, added after the same mistake shipped in `dlx-cache.ts`.
+            replicateLinkSync(src, dst);
         }
         else if (st.isDirectory()) {
             copyDirRecursive(src, dst);

package/lib/utils/dir-link.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The link type a directory link must use on this platform.
+ *
+ * `undefined` on POSIX is deliberate: Node's default is correct there, and
+ * passing a type would be noise.
+ */
+export declare const DIR_LINK_TYPE: 'junction' | undefined;
+/** True when directory links on this platform are NTFS junctions. */
+export declare const dirLinksAreJunctions: () => boolean;
+/**
+ * Spell the `target` argument for a link at `linkPath` pointing at `absTarget`.
+ *
+ * Absolute on Windows because a junction demands it (gotcha 1 above); relative
+ * on POSIX so the tree stays movable (gotcha 2).
+ *
+ * `linkType` is a PARAMETER, defaulting to the host's, for the same reason
+ * `detect-native-packages.ts` takes `platform`/`arch`: the Windows branch is
+ * then unit-testable from a Linux host, which is the only place anyone runs the
+ * tests. A branch nobody can exercise is how the `'dir'` bug survived to a
+ * release.
+ *
+ * @param linkPath  where the link itself will live
+ * @param absTarget the directory it should point at, as an ABSOLUTE path
+ * @param linkType  override the host's link type (tests only)
+ */
+export declare function dirLinkTarget(linkPath: string, absTarget: string, linkType?: 'junction' | undefined): string;
+/**
+ * Link `linkPath` → `absTarget`, choosing symlink-vs-junction and the target
+ * spelling for the host.
+ *
+ * `absTarget` must be absolute; passing a relative path is the mistake gotcha 1
+ * describes, and it would only misbehave on Windows, so it is rejected here on
+ * every platform rather than left to surface on the one host nobody tests on.
+ */
+export declare function linkDirSync(linkPath: string, absTarget: string): void;
+/** Promise-returning twin of {@link linkDirSync}. */
+export declare function linkDir(linkPath: string, absTarget: string): Promise<void>;
+/**
+ * Recreate an EXISTING link at a new path, preserving what it points at.
+ *
+ * A different job from {@link linkDirSync}, and it cannot reuse it: the source
+ * link's target is whatever it already is — frequently relative, deliberately so
+ * — while a junction demands an absolute one. Copying the target verbatim is
+ * therefore right on POSIX and wrong on Windows the moment the target is a
+ * directory.
+ *
+ * So the target's KIND decides: a link to a directory becomes a junction with
+ * the target resolved against the source link's own directory (the resolution
+ * Node will not do for you — see gotcha 1 above); anything else stays a plain
+ * file symlink, which Windows allows unprivileged.
+ *
+ * A dangling source link keeps the verbatim target: it points nowhere either
+ * way, and guessing a kind for it would turn a faithful copy into a fabrication.
+ *
+ * Primitive fs ops only — this runs under the GJS facade as well as Node, which
+ * is why there is no `fs.cp`/`opendir` here.
+ */
+export declare function replicateLinkSync(srcLink: string, dstLink: string): void;

package/lib/utils/dir-link.js

@@ -0,0 +1,126 @@
+// Creating a link to a DIRECTORY, portably.
+//
+// WHY THIS FILE EXISTS. Windows cannot create a directory *symlink* without
+// elevation or Developer Mode — the call fails with `EPERM` — but any user can
+// create an NTFS **junction**, which is why npm, yarn and pnpm all use junctions
+// for directory links. `commands/install.ts` learned that and encoded it, twice,
+// as a local constant for its workspace links. Nothing shared it, so the next
+// site to link a directory got it wrong: `dlx-cache.ts` linked with `'dir'` and
+// every non-elevated Windows user hit
+//
+//     Could not resolve showcase "canvas2d-fireworks": EPERM: operation not
+//     permitted, symlink '…\<prepare-dir>' -> '…\pkg.tmp-…'
+//
+// on a plain `npx @gjsify/cli@latest showcase …`. The knowledge existed in the
+// repo and the bug shipped anyway, which is the argument for a single callable
+// definition rather than a convention.
+//
+// THE TWO GOTCHAS, both load-bearing:
+//
+//  1. **A junction target must be ABSOLUTE.** Node normalises a `'junction'`
+//     target with `path.resolve()` — against the process CWD, NOT against the
+//     link's own directory. A relative target that looks right produces a
+//     junction pointing somewhere else entirely, and only on Windows.
+//  2. **POSIX targets should stay RELATIVE** where the caller wants a movable
+//     tree: a relative symlink survives the whole tree being moved or mounted
+//     elsewhere. So the target spelling is per-platform, not one string.
+//
+// Autodetection is NOT a substitute. Node picks `'file'` or `'dir'` when the
+// type argument is omitted — never `'junction'` — so an omitted type is the
+// failing case, not the safe default.
+import { readlinkSync, statSync, symlinkSync } from 'node:fs';
+import { symlink } from 'node:fs/promises';
+import { dirname, relative, resolve } from 'node:path';
+/**
+ * The link type a directory link must use on this platform.
+ *
+ * `undefined` on POSIX is deliberate: Node's default is correct there, and
+ * passing a type would be noise.
+ */
+export const DIR_LINK_TYPE = process.platform === 'win32' ? 'junction' : undefined;
+/** True when directory links on this platform are NTFS junctions. */
+export const dirLinksAreJunctions = () => DIR_LINK_TYPE === 'junction';
+/**
+ * Spell the `target` argument for a link at `linkPath` pointing at `absTarget`.
+ *
+ * Absolute on Windows because a junction demands it (gotcha 1 above); relative
+ * on POSIX so the tree stays movable (gotcha 2).
+ *
+ * `linkType` is a PARAMETER, defaulting to the host's, for the same reason
+ * `detect-native-packages.ts` takes `platform`/`arch`: the Windows branch is
+ * then unit-testable from a Linux host, which is the only place anyone runs the
+ * tests. A branch nobody can exercise is how the `'dir'` bug survived to a
+ * release.
+ *
+ * @param linkPath  where the link itself will live
+ * @param absTarget the directory it should point at, as an ABSOLUTE path
+ * @param linkType  override the host's link type (tests only)
+ */
+export function dirLinkTarget(linkPath, absTarget, linkType = DIR_LINK_TYPE) {
+    return linkType === 'junction' ? resolve(absTarget) : relative(dirname(linkPath), absTarget);
+}
+/**
+ * Link `linkPath` → `absTarget`, choosing symlink-vs-junction and the target
+ * spelling for the host.
+ *
+ * `absTarget` must be absolute; passing a relative path is the mistake gotcha 1
+ * describes, and it would only misbehave on Windows, so it is rejected here on
+ * every platform rather than left to surface on the one host nobody tests on.
+ */
+export function linkDirSync(linkPath, absTarget) {
+    assertAbsolute(absTarget);
+    symlinkSync(dirLinkTarget(linkPath, absTarget), linkPath, DIR_LINK_TYPE);
+}
+/** Promise-returning twin of {@link linkDirSync}. */
+export async function linkDir(linkPath, absTarget) {
+    assertAbsolute(absTarget);
+    await symlink(dirLinkTarget(linkPath, absTarget), linkPath, DIR_LINK_TYPE);
+}
+/**
+ * Recreate an EXISTING link at a new path, preserving what it points at.
+ *
+ * A different job from {@link linkDirSync}, and it cannot reuse it: the source
+ * link's target is whatever it already is — frequently relative, deliberately so
+ * — while a junction demands an absolute one. Copying the target verbatim is
+ * therefore right on POSIX and wrong on Windows the moment the target is a
+ * directory.
+ *
+ * So the target's KIND decides: a link to a directory becomes a junction with
+ * the target resolved against the source link's own directory (the resolution
+ * Node will not do for you — see gotcha 1 above); anything else stays a plain
+ * file symlink, which Windows allows unprivileged.
+ *
+ * A dangling source link keeps the verbatim target: it points nowhere either
+ * way, and guessing a kind for it would turn a faithful copy into a fabrication.
+ *
+ * Primitive fs ops only — this runs under the GJS facade as well as Node, which
+ * is why there is no `fs.cp`/`opendir` here.
+ */
+export function replicateLinkSync(srcLink, dstLink) {
+    const rawTarget = readlinkSync(srcLink);
+    if (!dirLinksAreJunctions()) {
+        symlinkSync(rawTarget, dstLink);
+        return;
+    }
+    const resolvedTarget = resolve(dirname(srcLink), rawTarget);
+    let targetIsDir;
+    try {
+        targetIsDir = statSync(resolvedTarget).isDirectory();
+    }
+    catch {
+        // Dangling — copy it as-is rather than inventing a kind for it.
+        symlinkSync(rawTarget, dstLink);
+        return;
+    }
+    if (targetIsDir)
+        symlinkSync(resolvedTarget, dstLink, 'junction');
+    else
+        symlinkSync(rawTarget, dstLink, 'file');
+}
+function assertAbsolute(absTarget) {
+    if (resolve(absTarget) !== absTarget) {
+        throw new TypeError(`linkDir: target must be an absolute path, got ${JSON.stringify(absTarget)}. ` +
+            'Node resolves a Windows junction target against the process CWD rather than the ' +
+            "link's own directory, so a relative target silently points somewhere else there.");
+    }
+}