@gjsify/cli 0.36.0 → 0.37.0

package/lib/templates/install.mjs.tmpl

@@ -1,40 +1,21 @@
 #!/usr/bin/env -S gjs -m
 /**
- * gjsify universal installer — bootstraps `@gjsify/cli` (or any GJS app
- * published to npm) on a system that has only `gjs` (and `curl`/`wget`)
- * available, without requiring Node.js or `npm`.
+ * gjsify universal installer — bootstraps `@gjsify/cli` (or any GJS app on npm)
+ * on a system that has only `gjs` and libsoup: no Node, no npm. Decision and
+ * history: docs/adr/0002-bootstrap-bundle-minimization.md.
  *
- * Usage:
- *   gjs -m install.mjs                    # install / update @gjsify/cli
- *   gjs -m install.mjs --target @scope/x  # install any other GJS-runnable npm package
- *   gjs -m install.mjs --tag next         # pick an npm dist-tag or pinned version
- *   gjs -m install.mjs --force            # reinstall even if already present
- *   gjs -m install.mjs --help
+ * Two stages: download a self-contained GJS bundle of `@gjsify/cli`
+ * (`cli.gjs.mjs`) from this repo's GitHub releases and verify its SHA-256, then
+ * spawn it as `gjs -m <bundle> install -g <target>@<tag>`. Dependency
+ * resolution, native prebuilds, lockfiles and the `~/.local/bin` launchers all
+ * live in that bundle — this bootstrapper re-implements none of it on purpose.
  *
- * How it works (two-stage bootstrap):
- *   1. Download a small self-contained GJS bundle of the @gjsify/cli
- *      (`cli.gjs.mjs`) from this repo's GitHub releases. Verify SHA-256.
- *   2. Spawn that bundle: `gjs -m <bundle> install -g <target>@<tag>`. The
- *      bundle handles transitive dependency resolution, native prebuilds,
- *      lockfiles, and the `~/.local/bin` launchers — all the things this
- *      thin bootstrapper deliberately does NOT re-implement.
+ * `gjsify generate-installer` re-emits this file for end-user GJS apps with the
+ * marked constants substituted.
  *
- * Generated by `gjsify generate-installer` for end-user GJS apps: in that
- * mode the constants below (BOOTSTRAP_URL, DEFAULT_TARGET, DEFAULT_BIN_NAME)
- * are pre-substituted to the consumer's package + custom bootstrap URL.
- *
- * Test hooks (set by tests/e2e/install-script/run.mjs):
- *   GJSIFY_INSTALL_BOOTSTRAP_URL  override the cli.gjs.mjs download origin
- *                                 (accepts file:// for offline tests)
- *   GJSIFY_INSTALL_BOOTSTRAP_SHA256_URL  override the .sha256 companion URL.
- *                                 An EMPTY string is the only way to install
- *                                 without verification, and it warns loudly; a
- *                                 digest URL that is set but unreachable is a
- *                                 hard failure, never a silent downgrade.
- *   GJSIFY_GLOBAL_PREFIX          override install prefix (forwarded to cli)
- *   GJSIFY_GLOBAL_BIN_DIR         override bin dir (forwarded to cli)
- *   GJSIFY_INSTALL_REGISTRY       override npm registry (forwarded as npm_config_registry)
- *   GJSIFY_INSTALL_BOOTSTRAP_CACHE  override the bootstrap cache dir
+ * `--help` documents the user-facing flags and env vars. Two more exist only for
+ * tests/e2e/install-script/run.mjs: GJSIFY_INSTALL_BOOTSTRAP_SHA256_URL and
+ * GJSIFY_INSTALL_BOOTSTRAP_CACHE.
  */
 
 import GLib from 'gi://GLib';
@@ -53,17 +34,16 @@ const DEFAULT_BOOTSTRAP_SHA256_URL = `${DEFAULT_BOOTSTRAP_URL}.sha256`;
 
 const USER_AGENT = 'gjsify-installer/1.0';
 
-// The bootstrap cache is CONTENT-ADDRESSED: `cli-<sha256>.gjs.mjs`. See
-// `resolveBootstrap()` for why the digest, not a fixed name, keys it.
+// Content-addressed cache: `cli-<sha256>.gjs.mjs`. Why the digest and not a
+// fixed name keys it: `resolveBootstrap()`.
 const CACHE_PREFIX = 'cli-';
 const CACHE_SUFFIX = '.gjs.mjs';
 
 /**
- * Under `--fetch-only` the ONLY thing on stdout must be the bundle path, so
- * progress goes to stderr instead. A caller does
- * `BOOTSTRAP=$(gjs -m install.mjs --fetch-only)`, and one stray `info()` line
- * would make that a path with a log message glued to the front — a failure that
- * surfaces as a confusing "file not found" rather than as bad output.
+ * Under `--fetch-only` stdout carries nothing but the bundle path, so progress
+ * goes to stderr. A caller does `BOOTSTRAP=$(gjs -m install.mjs --fetch-only)`,
+ * where one stray `info()` line glues a log message to the front of the path and
+ * surfaces later as a confusing "file not found".
  */
 let logToStderr = false;
 
@@ -139,7 +119,7 @@ Examples:
 }
 
 function checkGjsVersion() {
-    // imports.system.version is packed: major*10000 + minor*100 + micro
+    // `system.version` is packed: major*10000 + minor*100 + micro
     const v = system?.version;
     if (typeof v !== 'number') return;
     const major = Math.floor(v / 10000);
@@ -197,18 +177,17 @@ function readBytesOrNull(path) {
         const [, bytes] = Gio.File.new_for_path(path).load_contents(null);
         return bytes;
     } catch {
-        // An absent — or unreadable, e.g. truncated by a killed earlier run —
-        // cache entry is a MISS, not an error. `load_contents` is a real
-        // `throws="1"` GIR call, so this catch has a genuine throw path.
+        // An absent or unreadable entry (truncated by a killed earlier run) is a
+        // MISS, not an error. `load_contents` is `throws="1"`, so this catch has
+        // a genuine throw path.
         return null;
     }
 }
 
 /**
- * Drop every other cached bootstrap so the content-addressed cache stays
- * bounded. Each entry is a ~6.6 MB bundle and the digest changes with every
- * release — without this, keying the cache by content would trade "the cache
- * can never be warm" for "the cache grows forever".
+ * Drop every other cached bootstrap. Each entry is a ~6.6 MB bundle and the
+ * digest changes every release, so without pruning, content-addressing would
+ * trade "the cache can never be warm" for "the cache grows forever".
  */
 function pruneCache(dir, keepBasename) {
     const children = Gio.File.new_for_path(dir).enumerate_children('standard::name', Gio.FileQueryInfoFlags.NONE, null);
@@ -224,21 +203,15 @@ function pruneCache(dir, keepBasename) {
 /**
  * Resolve a VERIFIED bootstrap bundle and return its path.
  *
- * The digest is fetched BEFORE the bundle, and the cache is keyed by it. That
- * ordering is the mechanism, not an optimisation — it fixes two independent
- * defects that both came from doing it the other way round:
- *
- *   1. Verification was skippable by anyone who could break ONE request. The
- *      bundle was downloaded first and verified after, and a failed `.sha256`
- *      fetch merely logged "skipping verification" and carried on — so a proxy,
- *      a 404, or a captive portal silently downgraded the install to no
- *      verification at all. Fetching the digest first makes that impossible:
- *      no digest, no install.
- *   2. The cache could never be warm. It wrote a fixed `cli.gjs.mjs` and never
- *      read it back, so every run re-downloaded ~6.6 MB. A content-addressed
- *      name lets a matching entry short-circuit the download entirely.
+ * Fetching the digest BEFORE the bundle, and keying the cache by it, is the
+ * mechanism rather than an optimisation; the reverse order cost two defects.
+ * Verifying after downloading made verification skippable by anyone who could
+ * break ONE request — a failed `.sha256` fetch logged "skipping verification"
+ * and carried on, so a proxy, a 404 or a captive portal silently downgraded the
+ * install. And a fixed `cli.gjs.mjs` name that was never read back meant every
+ * run re-downloaded ~6.6 MB; a content-addressed name short-circuits that.
  *
- * Skipping verification is still possible, but only as an EXPLICIT act
+ * Skipping verification remains possible only as an EXPLICIT act
  * (`GJSIFY_INSTALL_BOOTSTRAP_SHA256_URL=''`), and it says so on stderr.
  */
 async function resolveBootstrap(session, bootstrapUrl, sha256Url) {
@@ -313,14 +286,12 @@ function buildSpec(target, tag) {
 }
 
 async function runInstall(bundlePath, spec) {
-    // `gjsify install -g <spec>` is always idempotent — it rewrites the tree
-    // unconditionally. There is no separate "force" flag to forward; the
-    // installer's own `--force` is satisfied by the fact that we always
-    // re-download the bootstrap and re-invoke the CLI.
+    // `gjsify install -g <spec>` rewrites the tree unconditionally, so there is
+    // no force flag to forward and `--force` needs nothing here.
     info(`Running: gjs -m <bootstrap> install -g ${spec}`);
     const argv = ['gjs', '-m', bundlePath, 'install', '-g', spec];
-    // Forward env vars verbatim so override paths set by tests / power-users
-    // reach the spawned CLI.
+    // No `envp`: the launcher inherits ours, so override env vars set by tests
+    // and power-users reach the spawned CLI.
     const launcher = new Gio.SubprocessLauncher({
         flags: Gio.SubprocessFlags.NONE,
     });
@@ -349,7 +320,6 @@ async function main() {
     }
 
     if (opts.fetchOnly) {
-        // The one thing on stdout. Everything above went to stderr.
         print(bundlePath);
         exit(0);
     }

package/lib/types/cli-build-options.d.ts

@@ -1,106 +1,72 @@
 import type { App } from '@gjsify/rolldown-plugin-gjsify';
 export interface CliBuildOptions {
-    /**
-     * This is an array of files that each serve as an input to the bundling algorithm.
-     * @see https://esbuild.github.io/api/#entry-points
-     */
+    /** Input files to the bundling algorithm. */
     entryPoints?: string[];
-    /** Switch on the verbose mode */
     verbose?: boolean;
-    /**
-     * When enabled, the generated code will be minified instead of pretty-printed.
-     * @see https://esbuild.github.io/api/#minify
-     */
+    /** Minify the generated code instead of pretty-printing it. */
     minify?: boolean;
-    /**
-     * Override the default output format.
-     * @see https://esbuild.github.io/api/#format
-     */
+    /** Override the default output format. */
     format?: 'iife' | 'esm' | 'cjs';
-    /** Use this if you want to build an application or test, the platform node is usually only used internally to build the tests for Gjsify */
+    /** Build an application or test. `node` is mostly internal, for gjsify's tests. */
     app?: App;
-    /** Use this if you want to build a library for Gjsify */
+    /** Build a library rather than an application. */
     library?: boolean;
-    /**
-     * This option sets the output file name for the build operation.
-     * This is only applicable if there is a single entry point.
-     * If there are multiple entry points, you must use the outdir option instead to specify an output directory.
-     * @see https://esbuild.github.io/api/#outfile
-     */
+    /** Output file name. Single entry point only — otherwise use `outdir`. */
     outfile?: string;
-    /**
-     * This option sets the output directory for the build operation.
-     * @see https://esbuild.github.io/api/#outdir
-     */
     outdir?: string;
-    /** Enables TypeScript types on runtime using Deepkit's type compiler */
+    /** Enables TypeScript types at runtime using Deepkit's type compiler. */
     reflection?: boolean;
-    /**
-     * The log level can be changed to prevent esbuild from printing warning and/or error messages to the terminal
-     * @see https://esbuild.github.io/api/#log-level
-     */
+    /** How much the bundler prints to the terminal. */
     logLevel: 'silent' | 'error' | 'warning' | 'info' | 'debug' | 'verbose';
-    /** An array of glob patterns to exclude matches and aliases */
+    /** Glob patterns excluding matches and aliases. */
     exclude?: string[];
     /**
-     * Inject a console shim into GJS builds for clean output (no GLib prefix, ANSI colors work).
-     * Use --no-console-shim to disable. Only applies to GJS app builds. Default: true.
+     * Inject a console shim into GJS app builds for clean output (no GLib prefix,
+     * working ANSI colors). Disable with `--no-console-shim`. Default: true.
      */
     consoleShim?: boolean;
     /**
-     * Comma-separated list of global identifiers your code needs (e.g.
-     * `"fetch,Buffer,process,URL,crypto"`). Each identifier is mapped to the
-     * corresponding `@gjsify/<pkg>/register` module and injected into the
-     * bundle. Only applies to GJS app builds.
+     * Comma-separated global identifiers the code needs, e.g.
+     * `"fetch,Buffer,process,URL,crypto"`. Each maps to the corresponding
+     * `@gjsify/<pkg>/register` module, injected into the bundle. GJS app builds only.
      */
     globals?: string;
     /**
-     * Prepend a `#!/usr/bin/env -S gjs -m` shebang to the output file and mark
-     * it executable (chmod 755). Only applies to GJS app builds with a single
-     * `--outfile`. Default: false.
+     * Prepend a `#!/usr/bin/env -S gjs -m` shebang and chmod 755. GJS app builds with
+     * a single `--outfile` only. Default: false.
      */
     shebang?: boolean;
     /**
-     * Module names that should NOT be bundled. Each name remains as a literal
-     * `import`/`require` in the output and is resolved by the runtime against
-     * its own `node_modules` (or equivalent) at execution time.
-     *
-     * Repeat the flag or pass a comma-separated value:
-     * `--external typedoc,prettier --external typescript`. Glob-style wildcards
-     * (`@inquirer/*`, `lodash-*`) are forwarded as-is to esbuild.
-     *
-     * @see https://esbuild.github.io/api/#external
+     * Module names that must NOT be bundled: each stays a literal `import`/`require`
+     * in the output, resolved by the runtime at execution time. Repeat the flag or
+     * pass a comma-separated value (`--external typedoc,prettier --external
+     * typescript`); glob-style wildcards (`@inquirer/*`, `lodash-*`) pass through to
+     * the bundler unchanged.
      */
     external?: string[];
     /**
-     * Substitute compile-time constants in the bundle. Each entry is a
-     * `KEY=VALUE` pair where `VALUE` is an arbitrary JS expression — string
-     * literals must be quoted (`--define VERSION='"1.2.3"'`). Useful for
-     * upstream packages that read a build-time constant via
+     * Compile-time constants as `KEY=VALUE`, where `VALUE` is an arbitrary JS
+     * expression — string literals must be quoted (`--define VERSION='"1.2.3"'`).
+     * For upstream packages reading a build-time constant via
      * `typeof __FOO__ !== 'undefined'`.
-     *
-     * @see https://esbuild.github.io/api/#define
      */
     define?: string[];
     /**
-     * Map module specifiers to alternative targets at bundle time. Each entry
-     * is `FROM=TO` where `FROM` is the imported package name and `TO` is the
-     * substitute (typically `@gjsify/empty` to drop a heavy dep that the test
-     * scenario never executes). Layered on top of the built-in alias map.
+     * Remap module specifiers at bundle time as `FROM=TO`, typically to
+     * `@gjsify/empty` to drop a heavy dep the scenario never executes. Layered on top
+     * of the built-in alias map.
      */
     alias?: string[];
     /**
-     * Comma-separated global identifiers to remove from the auto-detected set.
-     * Useful for false positives from dead browser-compat code in npm deps
-     * whose polyfills require unavailable native libraries.
-     * Example: `--exclude-globals fetch,XMLHttpRequest`
+     * Comma-separated global identifiers to drop from the auto-detected set — for
+     * false positives from dead browser-compat code in npm deps whose polyfills need
+     * unavailable native libraries. Example: `--exclude-globals fetch,XMLHttpRequest`.
      */
     excludeGlobals?: string[];
     /**
-     * Watch source files and rebuild on change. Logs each rebuild with
-     * duration; SIGINT/SIGTERM cleanly closes the watcher. Only valid with
-     * `--app gjs|node|browser` (rejected with `--library`). Requires the
-     * npm `rolldown` engine — run under Node.
+     * Watch and rebuild on change; SIGINT/SIGTERM closes the watcher cleanly. Valid
+     * only with `--app gjs|node|browser`, rejected with `--library`, and requires the
+     * npm `rolldown` engine — so run it under Node.
      */
     watch?: boolean;
 }

package/lib/types/command.d.ts

@@ -8,19 +8,16 @@ export interface Command<T = unknown, U = T> {
     deprecated?: boolean | string;
 }
 /**
- * A command that definitely runs something — the shape of every command except
- * the builder-only parents.
+ * A command that definitely runs something — every command except the
+ * builder-only parents. Annotate any command a standalone entry invokes directly.
  *
- * WHY IT EXISTS: `Command.handler` has to stay optional for parent commands,
- * but that optionality then lands on every CALL site, including the ones
- * outside `cli-app.ts`'s yargs registration where a missing handler would be a
- * silent no-op rather than a type error. `src/affected-entry.ts` — the entry
- * the committed `dist/affected.gjs.mjs` is built from — invoked
- * `affectedCommand.handler(...)` through a cast that suppressed exactly that,
- * and nothing noticed for as long as the package's tsconfig scoped the compile
- * to the import closure of `src/index.ts`. Annotate a command that a standalone
- * entry invokes directly with this type, and the guarantee is in the type
- * instead of in a cast.
+ * `Command.handler` must stay optional for parent commands, but that optionality
+ * then lands on every CALL site, including those outside `cli-app.ts`'s yargs
+ * registration, where a missing handler is a silent no-op rather than a type
+ * error. `src/affected-entry.ts` — the entry `dist/affected.gjs.mjs` is built
+ * from — invoked `affectedCommand.handler(...)` through a cast that suppressed
+ * exactly that, unnoticed for as long as the tsconfig scoped the compile to the
+ * import closure of `src/index.ts`. This puts the guarantee in the type instead.
  */
 export type LeafCommand<T = unknown, U = T> = Command<T, U> & {
     handler: NonNullable<Command<T, U>['handler']>;