@gjsify/cli 0.7.5 → 0.9.0

package/lib/actions/build.d.ts

@@ -37,9 +37,40 @@ export declare class BuildAction {
      * there is no in-bundle plugin, so this hook is the sole injection point.
      */
     private applyShebang;
+    /**
+     * GJS plugin loader — bundle the resolved plugin module to a single
+     * self-contained ESM file, then import that. Works around GJS's native
+     * ESM loader not following `package.json#exports` subpath maps for bare
+     * specifiers: Rolldown resolves those subpaths at bundle time, so the
+     * emitted file has no unresolvable bare-specifier imports left. Injected
+     * as the `loadModule` strategy in `buildApp` only when running under GJS.
+     */
+    private loadPluginViaGjsBundle;
+    /**
+     * Bundle a single plugin entry for `--app gjs` to a cached temp file and
+     * return its path. Reuses the full `--app gjs` pipeline (exports-map-aware
+     * resolution, `node:`→`@gjsify` aliases, `--globals auto`, single-file
+     * output) via a nested `BuildAction`. The nested config carries no
+     * `bundler.plugins`, so it never recurses back into plugin resolution.
+     *
+     * Cached under `node_modules/.cache/gjsify/plugins/`, keyed by the resolved
+     * source path. Invalidated when the plugin entry OR the project lockfile is
+     * newer than the cached bundle — a dep bump rewrites the lockfile but not
+     * the plugin's own entry mtime. The one window neither mtime catches (a
+     * transitive dep edited in place) is covered by the `GJSIFY_NO_PLUGIN_CACHE=1`
+     * escape hatch. Failures are rethrown with context naming the plugin.
+     */
+    private bundlePluginForGjs;
+    /**
+     * Fresh when the cached bundle is newer than BOTH the plugin entry AND the
+     * project's lockfile (the dep-change signal). Missing bundle/source → not
+     * fresh (rebuild).
+     */
+    private isPluginBundleFresh;
     /** Application mode */
     buildApp(app?: App, opts?: {
         watch?: boolean;
+        preserveDefaultExport?: boolean;
     }): Promise<RolldownOutput[]>;
     /**
      * Drive `rolldown.watch(...)`: rebuild on source change, apply the

package/lib/actions/build.js

@@ -1,10 +1,12 @@
 import { runBundle, runWatch, bundleToChunks } from '../bundler-pick.js';
 import { gjsifyPlugin, textLoaderPlugin, resolveShebangLine, NODE_SHEBANG } from '@gjsify/rolldown-plugin-gjsify';
+import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { resolveUserPlugins } from '../utils/resolve-plugin-by-name.js';
 import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals } from '@gjsify/rolldown-plugin-gjsify/globals';
 import { pnpPlugin } from '@gjsify/rolldown-plugin-pnp';
-import { dirname, extname } from 'node:path';
-import { chmod, readFile, writeFile } from 'node:fs/promises';
+import { dirname, extname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { chmod, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { normalizeBundlerOptions, mergeBundlerOptions } from '../utils/normalize-bundler-options.js';
 const DEFAULT_GJS_SHEBANG = '#!/usr/bin/env -S gjs -m';
 /**
@@ -34,6 +36,43 @@ function isUnsafeDefaultOutput(path) {
 async function buildPnpPlugin() {
     return pnpPlugin({ issuerUrl: import.meta.url });
 }
+/**
+ * Stable, filesystem-safe short hash of a string (djb2 → 8 hex chars).
+ * Used to key a plugin's cached GJS bundle by its resolved source path.
+ * Dependency-free on purpose — avoids pulling crypto into this hot path.
+ */
+function shortHash(value) {
+    let h = 5381;
+    for (let i = 0; i < value.length; i++) {
+        h = ((h << 5) + h + value.charCodeAt(i)) >>> 0;
+    }
+    return h.toString(16).padStart(8, '0');
+}
+function isTruthyEnv(v) {
+    return v === '1' || v === 'true' || v === 'yes';
+}
+/**
+ * Lockfiles whose change implies a plugin's *transitive* deps may have moved.
+ * A dep bump (`npm/yarn/pnpm/gjsify install`) rewrites one of these but leaves
+ * the plugin's own entry-file mtime untouched — so the plugin GJS-bundle cache
+ * must invalidate on these too, not only on the entry.
+ */
+const PLUGIN_CACHE_DEP_SIGNALS = ['gjsify-lock.json', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml'];
+/** Newest mtime (ms) among known lockfiles in `cwd`, or 0 when none exist. */
+async function newestLockfileMtime(cwd) {
+    let newest = 0;
+    for (const name of PLUGIN_CACHE_DEP_SIGNALS) {
+        try {
+            const s = await stat(join(cwd, name));
+            if (s.mtimeMs > newest)
+                newest = s.mtimeMs;
+        }
+        catch {
+            // not present — ignore
+        }
+    }
+    return newest;
+}
 export class BuildAction {
     configData;
     constructor(configData = {}) {
@@ -179,6 +218,90 @@ export class BuildAction {
         if (verbose)
             console.debug(`[gjsify] --shebang: wrote ${line} + chmod 0o755 to ${outfile}`);
     }
+    /**
+     * GJS plugin loader — bundle the resolved plugin module to a single
+     * self-contained ESM file, then import that. Works around GJS's native
+     * ESM loader not following `package.json#exports` subpath maps for bare
+     * specifiers: Rolldown resolves those subpaths at bundle time, so the
+     * emitted file has no unresolvable bare-specifier imports left. Injected
+     * as the `loadModule` strategy in `buildApp` only when running under GJS.
+     */
+    async loadPluginViaGjsBundle(resolvedPath, pluginName, verbose) {
+        const outfile = await this.bundlePluginForGjs(resolvedPath, pluginName, verbose);
+        try {
+            return (await import(pathToFileURL(outfile).href));
+        }
+        catch (err) {
+            throw new Error(`gjsify config: failed to import the GJS bundle for plugin "${pluginName}" ` +
+                `(bundled to ${outfile}). (${err.message})`);
+        }
+    }
+    /**
+     * Bundle a single plugin entry for `--app gjs` to a cached temp file and
+     * return its path. Reuses the full `--app gjs` pipeline (exports-map-aware
+     * resolution, `node:`→`@gjsify` aliases, `--globals auto`, single-file
+     * output) via a nested `BuildAction`. The nested config carries no
+     * `bundler.plugins`, so it never recurses back into plugin resolution.
+     *
+     * Cached under `node_modules/.cache/gjsify/plugins/`, keyed by the resolved
+     * source path. Invalidated when the plugin entry OR the project lockfile is
+     * newer than the cached bundle — a dep bump rewrites the lockfile but not
+     * the plugin's own entry mtime. The one window neither mtime catches (a
+     * transitive dep edited in place) is covered by the `GJSIFY_NO_PLUGIN_CACHE=1`
+     * escape hatch. Failures are rethrown with context naming the plugin.
+     */
+    async bundlePluginForGjs(resolvedPath, pluginName, verbose) {
+        const cwd = process.cwd();
+        const cacheDir = join(cwd, 'node_modules', '.cache', 'gjsify', 'plugins');
+        const safeName = pluginName.replace(/[^a-zA-Z0-9._-]/g, '_');
+        const outfile = join(cacheDir, `${safeName}-${shortHash(resolvedPath)}.mjs`);
+        const cacheDisabled = isTruthyEnv(process.env.GJSIFY_NO_PLUGIN_CACHE);
+        if (!cacheDisabled && (await this.isPluginBundleFresh(outfile, resolvedPath, cwd))) {
+            if (verbose)
+                console.debug(`[gjsify] plugin "${pluginName}": reusing cached GJS bundle ${outfile}`);
+            return outfile;
+        }
+        if (verbose)
+            console.debug(`[gjsify] plugin "${pluginName}": bundling for GJS → ${outfile}`);
+        try {
+            await mkdir(cacheDir, { recursive: true });
+            // `--globals auto` stays on so the plugin's own runtime globals
+            // (the MDX/unified toolchain touches `document`, etc.) are injected
+            // — but that injection wraps the entry with `export * from <entry>`,
+            // which drops the `default` export the plugin factory lives on.
+            // `preserveDefaultExport` makes the wrapper re-export `default` too,
+            // so the bundled plugin imports correctly as a library.
+            // shebang is intentionally left unset — the artifact is imported,
+            // not executed, so it must NOT carry a `#!` line.
+            const pluginBuild = new BuildAction({
+                verbose,
+                bundler: { input: resolvedPath, output: { file: outfile } },
+            });
+            await pluginBuild.buildApp('gjs', { preserveDefaultExport: true });
+        }
+        catch (err) {
+            throw new Error(`gjsify config: failed to bundle plugin "${pluginName}" for GJS ` +
+                `(needed because GJS can't import packages that use exports-map subpaths directly; ` +
+                `cache dir ${cacheDir}). (${err.message})`);
+        }
+        return outfile;
+    }
+    /**
+     * Fresh when the cached bundle is newer than BOTH the plugin entry AND the
+     * project's lockfile (the dep-change signal). Missing bundle/source → not
+     * fresh (rebuild).
+     */
+    async isPluginBundleFresh(outfile, resolvedPath, cwd) {
+        try {
+            const outStat = await stat(outfile);
+            const srcStat = await stat(resolvedPath);
+            const depMtime = await newestLockfileMtime(cwd);
+            return outStat.mtimeMs >= Math.max(srcStat.mtimeMs, depMtime);
+        }
+        catch {
+            return false;
+        }
+    }
     /** Application mode */
     async buildApp(app = 'gjs', opts = {}) {
         const { verbose, typescript, exclude, library: pkg, aliases, excludeGlobals } = this.configData;
@@ -211,6 +334,7 @@ export class BuildAction {
             reflection: typescript?.reflection,
             consoleShim,
             ...(aliases ? { aliases } : {}),
+            ...(opts.preserveDefaultExport ? { preserveDefaultExport: true } : {}),
         };
         const { autoMode, extras } = this.parseGlobalsValue(globals);
         const pnp = await buildPnpPlugin();
@@ -230,7 +354,15 @@ export class BuildAction {
         // auto-globals pre-build to avoid claiming the same files via
         // Rolldown's default classifier.
         if (userBundler.plugins?.length) {
-            const resolved = await resolveUserPlugins(userBundler.plugins, process.cwd());
+            // Under GJS, plugin modules can't always be imported directly:
+            // GJS's native ESM loader doesn't follow `package.json#exports`
+            // subpath maps, so a plugin whose source imports an internal
+            // subpath (e.g. `@mdx-js/mdx/internal-…`) throws `Module not
+            // found` even when the file is on disk. The injected loader
+            // first bundles such a plugin to a single self-contained ESM
+            // (Rolldown resolves the exports map at bundle time) and imports
+            // that instead. On Node the default direct-import path is used.
+            const resolved = await resolveUserPlugins(userBundler.plugins, process.cwd(), isGjs() ? { loadModule: (p, name) => this.loadPluginViaGjsBundle(p, name, verbose) } : {});
             userPlugins.push(...resolved);
         }
         // --- Auto mode (with optional extras): iterative multi-pass build ---

package/lib/bundler-pick.js

@@ -32,6 +32,7 @@ import * as path from 'node:path';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { resolveNpmPackage } from './utils/resolve-npm-package.js';
+import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 // npm `rolldown` is a Rust crate with platform-specific prebuilds; loading
 // it eagerly at module init pulls musl-detection code that does
 // `require('node:fs')` synchronously — fine on Node, but fatal under GJS
@@ -46,8 +47,7 @@ async function loadNpmRolldown() {
     // inside the crate's wrapper (e.g. on a truly-cold workspace where
     // `@gjsify/rolldown-native`'s lib/ is not built yet, issue #497).
     // Fail with the actionable diagnosis instead.
-    const isGjs = typeof globalThis.imports?.gi !== 'undefined';
-    if (isGjs) {
+    if (isGjs()) {
         throw new Error('gjsify build: no usable bundler engine under GJS — `@gjsify/rolldown-native` is not loadable ' +
             '(its JS facade lib/ is not built, or its prebuild typelib is missing from GI_TYPELIB_PATH), ' +
             'and the npm `rolldown` engine is a Rust napi crate that cannot run under GJS. ' +
@@ -83,8 +83,7 @@ async function loadNpmRolldown() {
  * rolldown` even though the package is present under the install dir.
  */
 function resolveImportTargetForGjs(specifier) {
-    const isGjs = typeof globalThis.imports?.gi !== 'undefined';
-    if (!isGjs)
+    if (!isGjs())
         return specifier;
     const resolved = resolveNpmPackage(specifier, { bundleUrl: import.meta.url });
     if (resolved)
@@ -193,8 +192,7 @@ export async function shouldUseNative() {
     //   GJS:     try @gjsify/rolldown-native — it's the only engine
     //            that can actually run here (npm rolldown is a Rust
     //            crate). Fall back to npm only on Node.
-    const isGjs = typeof globalThis.imports?.gi !== 'undefined';
-    if (!isGjs)
+    if (!isGjs())
         return false;
     const native = await tryLoadNative();
     return native !== null;
@@ -236,8 +234,7 @@ async function tryLoadNative() {
     if (_nativeProbe)
         return _nativeProbe;
     _nativeProbe = (async () => {
-        const isGjs = typeof globalThis.imports?.gi !== 'undefined';
-        if (!isGjs)
+        if (!isGjs())
             return null;
         try {
             // Under GJS the ESM loader has no node_modules resolver — a bare
@@ -256,7 +253,7 @@ async function tryLoadNative() {
             // to npm rolldown (which then throws ImportError for `rolldown`).
             const specifier = '@gjsify/rolldown-native';
             let target = specifier;
-            if (isGjs) {
+            if (isGjs()) {
                 // Same multi-anchor resolution as `loadNpmRolldown` —
                 // when the bundle is invoked from a cwd outside the
                 // install dir, anchoring solely at `import.meta.url`

package/lib/cli-app.js

@@ -19,8 +19,9 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import yargs from 'yargs';
-import { buildCommand as build, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, } from './commands/index.js';
+import { buildCommand as build, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, storybookCommand as storybook, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
+import { isNode } from '@gjsify/rolldown-plugin-gjsify/runtime';
 // Detect which runtime is executing the CLI (GJS or Node.js).
 // GJS MUST be checked first because @gjsify/process sets
 // `process.versions.node = '20.0.0'` for compatibility — a plain
@@ -36,7 +37,7 @@ function runtimeLabel() {
     catch {
         /* not GJS */
     }
-    if (typeof process !== 'undefined' && typeof process.versions?.node === 'string') {
+    if (isNode()) {
         return `Node.js ${process.version}`;
     }
     return 'unknown runtime';
@@ -106,6 +107,7 @@ export async function runCli(argv) {
         .command(barrels.command, barrels.description, barrels.builder, barrels.handler)
         .command(tsc.command, tsc.description, tsc.builder, tsc.handler)
         .command(affected.command, affected.description, affected.builder, affected.handler)
+        .command(storybook.command, storybook.description, storybook.builder, storybook.handler)
         .demandCommand(1)
         .epilogue(`Running on ${runtimeLabel()}`)
         .help()

package/lib/commands/index.d.ts

@@ -30,3 +30,4 @@ export * from './upgrade.js';
 export * from './barrels.js';
 export * from './tsc.js';
 export * from './affected.js';
+export * from './storybook.js';

package/lib/commands/index.js

@@ -30,3 +30,4 @@ export * from './upgrade.js';
 export * from './barrels.js';
 export * from './tsc.js';
 export * from './affected.js';
+export * from './storybook.js';

package/lib/commands/login.js

@@ -21,7 +21,7 @@
 import { DEFAULT_REGISTRY, registryFor, whoami } from '@gjsify/npm-registry';
 import { loadNpmrc } from '../utils/load-npmrc.js';
 import { writeAuthToken } from '../utils/auth-npmrc.js';
-import { promptLine, promptHidden } from '../utils/prompt.js';
+import { promptCredentials, promptLine } from '../utils/prompt.js';
 export const loginCommand = {
     command: 'login',
     description: "Log in to an npm registry (Node-free `npm login`). Prompts for username + password (hidden) and writes the token to ~/.npmrc. Use --otp for 2FA. Web-OAuth flow is not supported — this is npm's legacy credentials flow.",
@@ -44,12 +44,15 @@ export const loginCommand = {
             (args.scope ? registryFor(args.scope.startsWith('@') ? `${args.scope}/_` : `@${args.scope}/_`, npmrc) : undefined) ??
             DEFAULT_REGISTRY;
         const registryClean = registry.endsWith('/') ? registry : `${registry}/`;
-        const username = args.username ?? (await promptLine(`Username: `));
+        // Read username (visible) + password (masked) in a single raw-mode TTY
+        // session — robust against cooked line-discipline state + the shared
+        // stdin resume/pause race that intermittently broke the old two-prompt
+        // sequence (Enter showing `^M`, or an empty username).
+        const { username, password } = await promptCredentials(args.username);
         if (!username) {
             console.error('gjsify login: a username is required.');
             process.exit(1);
         }
-        const password = await promptHidden(`Password: `);
         if (!password) {
             console.error('gjsify login: a password is required.');
             process.exit(1);

package/lib/commands/run.js

@@ -19,6 +19,7 @@ import { spawn } from 'node:child_process';
 import { runGjsBundle } from '../utils/run-gjs.js';
 import { readPackageJson } from '../utils/pkg-json-edit.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
+import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 export const runCommand = {
     command: 'run <target> [args..]',
     description: 'Run a script from package.json (yarn-run-style) or a GJS bundle file. If <target> resolves to a file on disk (or has a path-like prefix), it is launched via gjs with LD_LIBRARY_PATH + GI_TYPELIB_PATH set for native packages. Otherwise it is looked up in the current package.json `scripts`.',
@@ -151,7 +152,7 @@ async function runScript(script, extraArgs) {
     // Anything fancier (compound `&&`, pipes, a non-gjsify command) falls
     // through to the shell spawn below. Node keeps spawning (cheap there); this
     // only triggers under GJS, where the nesting actually hurts. See cli-app.ts.
-    const inProcArgv = runningUnderGjs() ? gjsifyInProcessArgv(literal, extraArgs) : null;
+    const inProcArgv = isGjs() ? gjsifyInProcessArgv(literal, extraArgs) : null;
     if (inProcArgv) {
         // The subcommand runs in our process, so surface the script env on
         // `process.env` (PATH with the workspace .bin dirs, npm_* lifecycle
@@ -203,11 +204,6 @@ function shellEscape(arg) {
         return arg;
     return `'${arg.replace(/'/g, "'\\''")}'`;
 }
-// Detected at CALL time (a module-load const reads `undefined` in the bundled
-// `--app gjs` form). `bundler-pick.ts` uses the same expression.
-function runningUnderGjs() {
-    return typeof globalThis.imports?.gi !== 'undefined';
-}
 /**
  * If `literal` is a SINGLE `gjsify <subcommand> …` command with no shell
  * operators / substitutions / unquoted globs, return the argv to feed `runCli`

package/lib/commands/storybook.d.ts

@@ -0,0 +1,12 @@
+import type { Command } from '../types/index.js';
+interface StorybookCliOptions {
+    stories?: string;
+    appId?: string;
+    title?: string;
+    globals?: string;
+    out?: string;
+    watch: boolean;
+    buildOnly: boolean;
+}
+export declare const storybookCommand: Command<unknown, StorybookCliOptions>;
+export {};

package/lib/commands/storybook.js

@@ -0,0 +1,172 @@
+// `gjsify storybook` — discover every *.story.ts in a project, generate a tiny
+// entry that registers them, then build (`--app gjs`) and launch the generic
+// @gjsify/storybook component browser. No per-project storybook app needed.
+//
+// Dispatch is IN-PROCESS (runCli + runGjsBundle), not a re-spawn of the CLI:
+// the showcase-style `spawn(process.execPath, [cliBin, …])` pattern assumes
+// Node, but under the committed GJS bundle `process.execPath` is `gjs` and the
+// `../index.js` path is not a runnable entry. In-process dispatch works
+// identically under Node and GJS. @gjsify/storybook is resolved from the
+// CONSUMER's node_modules by the generated entry, so it stays out of the CLI's
+// own dependencies.
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+function readPackage(cwd) {
+    try {
+        return JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** Derive a stable GApplication id from the package name when none is configured. */
+function deriveAppId(name) {
+    if (!name)
+        return 'org.gjsify.Storybook';
+    const slug = name
+        .replace(/^@/, '')
+        .replace(/[^a-zA-Z0-9]+/g, '.')
+        .replace(/^\.+|\.+$/g, '');
+    return `org.gjsify.storybook.${slug}`;
+}
+/** Recursively collect `*.story.{ts,js,mts,mjs}` files under a directory. */
+function findStoryFiles(dir) {
+    const out = [];
+    if (!existsSync(dir))
+        return out;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === 'node_modules' || entry.name.startsWith('.'))
+            continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...findStoryFiles(full));
+        }
+        else if (/\.story\.(ts|js|mts|mjs)$/.test(entry.name)) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+function generateEntry(files, applicationId, title) {
+    const imports = files.map((file, i) => `import * as m${i} from ${JSON.stringify(file)};`).join('\n');
+    const namespaces = files.map((_, i) => `m${i}`).join(', ');
+    const titleLine = title ? `\n    title: ${JSON.stringify(title)},` : '';
+    return `// Auto-generated by \`gjsify storybook\` — do not edit by hand.
+import { collectStoryModules, runStorybook } from '@gjsify/storybook';
+${imports}
+
+await runStorybook({
+    applicationId: ${JSON.stringify(applicationId)},${titleLine}
+    stories: collectStoryModules([${namespaces}]),
+});
+`;
+}
+export const storybookCommand = {
+    command: 'storybook',
+    description: 'Discover *.story.ts in this project and launch the GTK storybook browser.',
+    builder: (yargs) => yargs
+        .option('stories', {
+        description: 'Directory scanned recursively for *.story.ts (default: src, or gjsify.storybook.stories)',
+        type: 'string',
+    })
+        .option('app-id', {
+        description: 'GApplication id (default: gjsify.storybook.applicationId or derived from the package name)',
+        type: 'string',
+    })
+        .option('title', { description: 'Window title', type: 'string' })
+        .option('globals', {
+        description: 'Value for `gjsify build --globals` (default: auto; use auto,dom for canvas/DOM stories)',
+        type: 'string',
+    })
+        .option('out', {
+        description: 'Output bundle path (default: node_modules/.cache/gjsify-storybook)',
+        type: 'string',
+    })
+        .option('watch', {
+        description: 'Rebuild and relaunch when a story file changes',
+        type: 'boolean',
+        default: false,
+    })
+        .option('build-only', { description: 'Build the bundle but do not launch it', type: 'boolean', default: false }),
+    handler: async (args) => {
+        const cwd = process.cwd();
+        const pkg = readPackage(cwd);
+        const config = pkg.gjsify?.storybook ?? {};
+        const storiesDir = resolve(cwd, args.stories ?? config.stories ?? 'src');
+        const applicationId = args.appId ?? config.applicationId ?? deriveAppId(pkg.name);
+        const title = args.title ?? config.title;
+        const globals = args.globals ?? config.globals ?? 'auto';
+        const cacheDir = join(cwd, 'node_modules', '.cache', 'gjsify-storybook');
+        mkdirSync(cacheDir, { recursive: true });
+        const entryPath = join(cacheDir, 'entry.ts');
+        const outPath = args.out ? resolve(cwd, args.out) : join(cacheDir, 'storybook.gjs.mjs');
+        const writeEntry = () => {
+            const files = findStoryFiles(storiesDir).sort();
+            writeFileSync(entryPath, generateEntry(files, applicationId, title));
+            return files.length;
+        };
+        const initialCount = writeEntry();
+        if (initialCount === 0) {
+            console.error(`No *.story.ts files found under ${relative(cwd, storiesDir) || storiesDir}`);
+            process.exit(1);
+        }
+        console.log(`Found ${initialCount} story file(s) under ${relative(cwd, storiesDir) || '.'}`);
+        // In-process build — runtime-agnostic (Node uses npm rolldown, GJS uses
+        // the @gjsify/rolldown-native facade), no re-spawn of the CLI binary.
+        const { runCli } = await import('../cli-app.js');
+        const buildBundle = () => runCli(['build', entryPath, '--app', 'gjs', '--globals', globals, '--outfile', outPath]);
+        if (!args.watch) {
+            await buildBundle();
+            if (args.buildOnly)
+                return;
+            const { runGjsBundle } = await import('../utils/run-gjs.js');
+            await runGjsBundle(outPath, [], { exitOnSuccess: true });
+            return;
+        }
+        // Watch mode: rebuild + relaunch on any change under the stories dir.
+        // The storybook bundle only needs system Gtk/Adw typelibs at runtime
+        // (no @gjsify native bridges), so a plain `gjs -m` child is enough and
+        // stays killable for relaunch.
+        const { watch } = await import('node:fs');
+        let child = null;
+        let rebuilding = false;
+        let pending = false;
+        const rebuild = async () => {
+            if (rebuilding) {
+                pending = true;
+                return;
+            }
+            rebuilding = true;
+            try {
+                writeEntry();
+                if (child) {
+                    child.kill();
+                    child = null;
+                }
+                await buildBundle();
+                if (!args.buildOnly) {
+                    child = spawn('gjs', ['-m', outPath], { stdio: 'inherit' });
+                }
+            }
+            catch (err) {
+                console.error(`[storybook] rebuild failed: ${err.message}`);
+            }
+            finally {
+                rebuilding = false;
+                if (pending) {
+                    pending = false;
+                    void rebuild();
+                }
+            }
+        };
+        await rebuild();
+        let debounce = null;
+        watch(storiesDir, { recursive: true }, () => {
+            if (debounce)
+                clearTimeout(debounce);
+            debounce = setTimeout(() => void rebuild(), 200);
+        });
+        console.log(`[storybook] watching ${relative(cwd, storiesDir) || '.'} — press Ctrl+C to stop`);
+    },
+};

package/lib/utils/oxc-resolve.js

@@ -53,6 +53,7 @@ import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { findWorkspaceRoot } from './workspace-root.js';
 import { resolveNpmPackage } from './resolve-npm-package.js';
+import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 /**
  * Map Node.js `process.platform` + `arch` (+ musl on Linux) to the
  * napi-rs binding-package suffix oxc uses, e.g. `linux-x64-gnu`,
@@ -210,8 +211,7 @@ async function tryLoadNativeOxfmt() {
     if (_nativeOxfmtProbe)
         return _nativeOxfmtProbe;
     _nativeOxfmtProbe = (async () => {
-        const isGjs = typeof globalThis.imports?.gi !== 'undefined';
-        if (!isGjs)
+        if (!isGjs())
             return null;
         try {
             const specifier = '@gjsify/oxfmt-native';
@@ -249,8 +249,7 @@ export async function shouldUseNativeOxfmt() {
         }
         return true;
     }
-    const isGjs = typeof globalThis.imports?.gi !== 'undefined';
-    if (!isGjs)
+    if (!isGjs())
         return false;
     return (await tryLoadNativeOxfmt()) !== null;
 }

package/lib/utils/prompt.d.ts

@@ -1,8 +1,34 @@
-/** Print a question and read one line from stdin (visible). */
-export declare function promptLine(question: string): Promise<string>;
+/** Credentials read from the terminal. */
+export interface PromptedCredentials {
+    username: string;
+    password: string;
+}
+/** Result of feeding one keystroke to the raw-mode line editor. */
+export interface KeyOutcome {
+    /** The line buffer after this key. */
+    buf: string;
+    /** Text to echo to the terminal for this key (`''` = nothing). */
+    echo: string;
+    /** The line is complete (Enter). */
+    done: boolean;
+    /** Ctrl-C was pressed (caller should restore + exit). */
+    interrupt: boolean;
+}
 /**
- * Print a question and read one line WITHOUT echoing it (passwords). Uses raw
- * mode + manual key handling on a TTY; falls back to a plain line read when
- * stdin is not a TTY (piped). Ctrl-C aborts the process.
+ * Pure key handler for the raw-mode line editor — the single source of truth
+ * for how a keystroke updates the buffer + echo. Kept pure (no I/O) so it is
+ * unit-testable: this is what makes Enter (`\r` OR `\n`) reliably submit, masks
+ * passwords, and treats Ctrl-C as an interrupt rather than text.
  */
+export declare function applyKey(buf: string, ch: string, mask: boolean): KeyOutcome;
+/** Print a question and read one visible line. */
+export declare function promptLine(question: string): Promise<string>;
+/** Print a question and read one line WITHOUT echoing it (passwords). */
 export declare function promptHidden(question: string): Promise<string>;
+/**
+ * Read npm credentials. On a TTY both the visible username and the masked
+ * password are read in ONE raw session (no cooked-line dependency, no
+ * inter-prompt resume/pause race). `providedUsername` (from `--username`) skips
+ * the username prompt.
+ */
+export declare function promptCredentials(providedUsername?: string): Promise<PromptedCredentials>;