@gjsify/cli 0.26.1 → 0.27.1

package/lib/bundler-pick.js

@@ -93,13 +93,21 @@ function diagnoseNativeEngine() {
     const facade = path.join(pkgDir, 'lib', 'esm', 'index.js');
     if (!existsSync(facade)) {
         return (`The engine's JS facade is NOT BUILT: ${facade} does not exist.\n` +
-            'It is a BUILD OUTPUT, not something `gjsify install` produces — so a freshly cloned or freshly ' +
-            'installed tree never has it, and every `gjsify build` under GJS fails here until it is built once. ' +
+            'It is a BUILD OUTPUT, so this is almost certainly a clone of the gjsify REPOSITORY rather than a ' +
+            'consumer install: in a clone, node_modules/@gjsify/rolldown-native is a symlink to the workspace ' +
+            'package, whose `lib/` no `gjsify install` produces. An installed package from npm is NOT affected — ' +
+            'the published tarball does contain `lib/esm/index.js` (verified against 0.26.1), so a consumer that ' +
+            'hit this message should report it.\n' +
             'Building it needs a bundler, which is why it cannot bootstrap itself under GJS; the Node CLI entry ' +
-            'does it instead. From the gjsify repo root:\n' +
+            'does it instead. From the gjsify repo root — NOTE both of these REQUIRE Node:\n' +
             '  gjsify run build:infra                          # the full cold-tree chain (recommended)\n' +
             '  node scripts/bootstrap-native-facades.mjs       # just the facades, if the rest is already built\n' +
-            'Both are idempotent and skip already-built facades in seconds.');
+            'Both are idempotent and skip already-built facades in seconds.\n' +
+            'ON A NODE-LESS GJS HOST there is currently no in-repo way out, and saying so is the point — this ' +
+            'message used to recommend those two commands unconditionally, and on such a host BOTH fail (the ' +
+            "second directly, the first at `@gjsify/create-app`'s `node scripts/process-template.mjs`). Until " +
+            'that is closed, seed `lib/` from the published package — which ships it — or from a host that has ' +
+            'Node. Tracked in `status/open-todos.md` ("A Node-less host cannot bootstrap a fresh CLONE").');
     }
     return ('The JS facade is built, so this is the typelib/prebuild lookup failing. Most likely the CLI bundle was ' +
         'invoked DIRECTLY (`gjs -m …/cli.gjs.mjs`, or by executing dist/cli.gjs.mjs), which bypasses the `gjsify` ' +

package/lib/cli-app.js

@@ -19,7 +19,7 @@ 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, onboardCommand as onboard, 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, debugCommand as debug, browseCommand as browse, } from './commands/index.js';
+import { buildCommand as build, clearCommand as clear, copyCommand as copy, 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, onboardCommand as onboard, 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, debugCommand as debug, browseCommand as browse, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 import { isBun, isDeno, isNode, gjsSystemVersion } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { ensureGjsifyShimOnPath } from './utils/gjsify-shim.js';
@@ -89,6 +89,8 @@ export async function runCli(argv) {
         .command(create.command, create.description, create.builder, create.handler)
         .command(install.command, install.description, install.builder, install.handler)
         .command(build.command, build.description, build.builder, build.handler)
+        .command(clear.command, clear.description, clear.builder, clear.handler)
+        .command(copy.command, copy.description, copy.builder, copy.handler)
         .command(test.command, test.description, test.builder, test.handler)
         .command(run.command, run.description, run.builder, run.handler)
         .command(dlx.command, dlx.description, dlx.builder, dlx.handler)

package/lib/commands/affected.js

@@ -199,7 +199,7 @@ const OTHER_WORKFLOW_INPUTS = [
     // Each sibling workflow's own definition. `main.yml` is deliberately
     // absent — it is a GLOBAL_TRIGGER, since a job-shape change there is
     // invisible until the workflow re-runs.
-    /^\.github\/workflows\/(deploy-docs|commitlint|release|release-cut|audit-runtimes|prebuilds|node-gi|napi|cli-cross-platform|build-ci-image)\.yml$/,
+    /^\.github\/workflows\/(deploy-docs|commitlint|release|release-cut|audit-runtimes|prebuilds|node-gi|napi|cli-cross-platform|build-ci-image|cancel-pr-runs)\.yml$/,
     // `prebuilds.yml`'s toolchain (#838): the QEMU-emulated build script and
     // the `changed-packages` classifier that decides which native packages a
     // prebuild run rebuilds. `prebuilds.yml` lists `.github/prebuild-toolchain/**`

package/lib/commands/build.js

@@ -1,5 +1,26 @@
 import { Config } from '../config.js';
 import { BuildAction } from '../actions/build.js';
+// NO `normalize: true` ON THE GLOB-BEARING OPTIONS — `entry-points` and
+// `exclude` are PATTERNS, not paths.
+//
+// yargs' `normalize` runs `path.normalize()` over every value, which on win32
+// rewrites separators: `src/**/*.{ts,js}` becomes `src\**\*.{ts,js}`. Those
+// patterns go to fast-glob, whose own source says why that must not happen
+// ("we cannot use the standard `path.normalize` method, because on Windows
+// platform it will use of backslashes") — and the failure is not a clean
+// no-match. With no `/` left, fast-glob finds no static base, walks from `.`,
+// follows the workspace's relative `node_modules/@gjsify/*` symlinks with
+// unbounded depth and no cycle detection, and dies of heap exhaustion after
+// tens of minutes without writing one output file. That is issue #914's
+// "`--library` is pathologically slow" report, in full: every `build:gjsify`
+// script in the tree passes its entry points as globs. See
+// `rolldown-plugin-gjsify/src/utils/entry-points.ts` for the second layer.
+//
+// The flag had also been copied onto twelve options that are not paths at all
+// (booleans, `choices` enums, comma-separated identifier lists). Normalizing
+// those is meaningless, and it is what made the one place it is harmful look
+// like house style. `outfile`/`outdir` keep it: they ARE single paths, and
+// nothing globs them.
 export const buildCommand = {
     command: 'build [entryPoints..]',
     description: 'Build and bundle your Gjs project',
@@ -9,7 +30,6 @@ export const buildCommand = {
             description: 'The entry points you want to bundle. Defaults to bundler.input from package.json#gjsify or .gjsifyrc.js, falling back to src/index.ts when neither is set.',
             array: true,
             type: 'string',
-            normalize: true,
             // No yargs `default` here on purpose. A yargs default value
             // is indistinguishable from "user passed the flag" in the
             // parsed args (cliArgs.entryPoints?.length is truthy either
@@ -29,20 +49,17 @@ export const buildCommand = {
             description: 'An array of glob patterns to exclude entry-points and aliases',
             array: true,
             type: 'string',
-            normalize: true,
             default: [],
         })
             .option('verbose', {
             description: 'Switch on the verbose mode',
             type: 'boolean',
-            normalize: true,
             default: false,
         })
             .option('app', {
             description: 'Build target for an application. Defaults to the target of the HOST runtime running the CLI: gjs when run under gjs, node when run under node/bun/deno (both consume the --app node bundle). Set `gjsify.app` in package.json#gjsify to override the host default.',
             type: 'string',
             choices: ['gjs', 'node', 'browser', 'nativescript'],
-            normalize: true,
             // No yargs `default: 'gjs'` — a yargs default is
             // indistinguishable from a user-set value and would clobber
             // `package.json#gjsify.app` in config.ts (same footgun as
@@ -55,18 +72,15 @@ export const buildCommand = {
             description: 'Override the default output format',
             type: 'string',
             choices: ['iife', 'esm', 'cjs'],
-            normalize: true,
         })
             .option('minify', {
             description: 'Minify the bundled output. Defaults to true; use --no-minify to emit pretty-printed code (e.g. for debugging or readable bundle review).',
             type: 'boolean',
-            normalize: true,
             defaultDescription: 'true',
         })
             .option('library', {
             description: 'Use this if you want to build a library for Gjsify',
             type: 'boolean',
-            normalize: true,
             default: false,
         })
             .option('outfile', {
@@ -85,26 +99,22 @@ export const buildCommand = {
             alias: 'r',
             description: "Enables TypeScript types on runtime using Deepkit's type compiler",
             type: 'boolean',
-            normalize: true,
             default: false,
         })
             .option('log-level', {
             description: 'The log level can be changed to prevent esbuild from printing warning and/or error messages to the terminal',
             type: 'string',
             choices: ['silent', 'error', 'warning', 'info', 'debug', 'verbose'],
-            normalize: true,
             default: 'warning',
         })
             .option('console-shim', {
             description: 'Inject a console shim into GJS builds for clean output without the GLib prefix and with working ANSI colors. Use --no-console-shim to disable. Only applies to GJS app builds.',
             type: 'boolean',
-            normalize: true,
             default: true,
         })
             .option('globals', {
             description: "Comma-separated list of global identifiers, 'auto' (default) to detect automatically from the bundled output, or 'none' to disable. The 'auto' token may be combined with explicit identifiers/groups (e.g. 'auto,dom') for cases where the detector cannot statically see a global because it's accessed via indirection. Each identifier is mapped to the corresponding `@gjsify/<pkg>/register` module and injected into the bundle. See the CLI Reference docs for the full list of known identifiers. Only applies to GJS app builds.",
             type: 'string',
-            normalize: true,
             // No yargs `default: 'auto'` — a yargs default is
             // indistinguishable from a user-set value and would always
             // clobber `package.json#gjsify.globals` / `.gjsifyrc.*` in
@@ -115,7 +125,6 @@ export const buildCommand = {
             .option('shebang', {
             description: 'Prepend a target-appropriate shebang to the output and mark it executable (chmod 755): `#!/usr/bin/env -S gjs -m` for --app gjs, `#!/usr/bin/env node` for --app node. Applies to GJS and Node app builds with a single --outfile. Default: false (use --shebang to enable, or set `shebang: true` in `.gjsifyrc.js`).',
             type: 'boolean',
-            normalize: true,
         })
             .option('external', {
             description: 'Module names that should NOT be bundled — EXACT package names only, matched literally on both bundler engines (no globs). Repeat the flag or pass a comma-separated list (e.g. --external typedoc,prettier). Appended to the per-app built-in externals; register subpaths (`<pkg>/register[/…]`) are always force-inlined for --app gjs regardless of this flag.',
@@ -146,13 +155,11 @@ export const buildCommand = {
             .option('exclude-globals', {
             description: 'Comma-separated global identifiers to remove from auto-detection results. Use for false positives from dead browser-compat code whose polyfills require unavailable native libraries (e.g. --exclude-globals fetch,XMLHttpRequest).',
             type: 'string',
-            normalize: true,
         })
             .option('watch', {
             alias: 'w',
             description: 'Watch source files and rebuild on change. Logs each rebuild with duration; clean SIGINT shutdown. Only valid with --app gjs|node|browser (rejected with --library). Requires the npm `rolldown` engine — run under Node, not the GJS-bundled CLI.',
             type: 'boolean',
-            normalize: true,
             default: false,
         });
     },

package/lib/commands/check.js

@@ -14,7 +14,6 @@
 // — if both `system-check`-style flags (`--json`) and `check`-style scripts
 // are reachable here, the `--json` flag routes through this command first
 // (since the typescript-check binding is positional `[paths..]`).
-import { spawnSync } from 'node:child_process';
 import { prefixLines } from '../utils/prefixed-output.js';
 import { spawnToCompletion } from '../utils/spawn.js';
 import { readPackageJson } from '../utils/pkg-json.js';
@@ -22,6 +21,7 @@ import { join } from 'node:path';
 import { cpus } from 'node:os';
 import { discoverWorkspaces, filterWorkspaces } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
+import { detectPackageManager } from './workspace.js';
 /**
  * Run a single workspace's `check` script. Returns the exit code; non-zero
  * indicates failure. Output is forwarded to the parent's stdout/stderr,
@@ -33,8 +33,25 @@ async function runCheck(ws, prefix) {
     // GJS, so the STREAMING async path is safe here (and required: the
     // blocking one would serialize the parallel workers). See utils/spawn.ts.
     const flushers = [];
+    // The RUNNER is detected, never hardcoded — `foreach` and `workspace` have
+    // always done this and this site did not, which made `gjsify check` the one
+    // orchestrator that still required Node. Under GJS `detectPackageManager()`
+    // returns `gjsify` and the script goes through the shim on PATH.
+    //
+    // It failed in the worst possible shape: `spawnToCompletion` maps the
+    // `spawn npm ENOENT` into the rejection the `catch` below turns into a bare
+    // `exit 1`, so a Node-less host reported `✗ <pkg> (exit 1)` for a check
+    // script that never ran — measured on postmarketOS/aarch64 against a
+    // package whose `check` was literally `echo`.
+    const runner = detectPackageManager();
+    // `--if-present` is an npm/yarn flag with no `gjsify run` equivalent, so for
+    // the GJS runner the absence test moves here rather than being dropped.
+    if (runner === 'gjsify' && readPackageJson(join(ws.location, 'package.json'))?.scripts?.check === undefined) {
+        return 0;
+    }
+    const argv = runner === 'gjsify' ? ['run', 'check'] : ['run', 'check', '--if-present'];
     try {
-        const { code } = await spawnToCompletion('npm', ['run', 'check', '--if-present'], {
+        const { code } = await spawnToCompletion(runner, argv, {
             completion: 'exit',
             cwd: ws.location,
             stdio: prefix === null ? 'inherit' : 'pipe',
@@ -111,11 +128,30 @@ export const checkCommand = {
                 if (args.verbose) {
                     console.log(`[check] cwd=${cwd}  → npm run check`);
                 }
-                const r = spawnSync('npm', ['run', 'check'], { cwd, stdio: 'inherit' });
+                // Through `spawnToCompletion`, like workspace mode above and
+                // like every other spawn in the CLI. This site kept a raw
+                // `spawnSync('npm', …)` when the six wrappers were consolidated
+                // (see utils/spawn.ts), and that made it the last place where
+                // `npm` was handed to `spawn` as a bare name — ENOENT on
+                // Windows, where npm is a `.cmd` shim `CreateProcess` never
+                // finds. Reading only `r.status` then turned that into
+                // `process.exit(1)` with NO diagnostic at all: `gjsify check`
+                // inside any package failed silently on win32. Measured there
+                // before the change; `--verbose` printed the command line and
+                // nothing else.
+                // Runner detected, not hardcoded — same reason as workspace mode
+                // above. This branch already established that the package HAS a
+                // check script, so there is no `--if-present` to translate.
+                const { code } = await spawnToCompletion(detectPackageManager(), ['run', 'check'], {
+                    cwd,
+                    // The handler exits the process on every path below, so the
+                    // streaming path is safe under GJS too.
+                    completion: 'exit',
+                });
                 // `return` — a bare `process.exit()` is deferred under GJS (no
                 // atexit), so execution fell through into workspace mode and
                 // re-checked the whole monorepo after the single-package run.
-                return process.exit(r.status ?? 1);
+                return process.exit(code ?? 1);
             }
             // Fall through to workspace mode when the local package has no
             // check script (cd'd into a non-package dir under the root).

package/lib/commands/clear.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from '../types/index.js';
+interface ClearOptions {
+    paths?: string[];
+    dryRun?: boolean;
+    verbose?: boolean;
+}
+export declare const clearCommand: Command<unknown, ClearOptions>;
+export {};

package/lib/commands/clear.js

@@ -0,0 +1,90 @@
+// `gjsify clear <paths…>` — portable recursive delete for package `clear` scripts.
+//
+// WHY THIS EXISTS
+//
+// Every `clear` script in this workspace was `rm -rf <dirs…> || exit 0`. npm runs
+// package scripts through `cmd.exe` on Windows, which has neither `rm` nor that
+// syntax, so `gjsify foreach clear` — and with it the documented full gate
+// (`gjsify install --immutable && gjsify run clear && gjsify run build …`) —
+// could not run there at all. 224 package.json files carried that line, so the
+// fix is one portable implementation, not 224 hand-written platform branches
+// (issue #914, finding 3).
+//
+// `force: true` already ignores a missing path, which is all the `|| exit 0` tail
+// ever did — so the rewritten scripts drop it and stop swallowing REAL failures.
+// A permission error used to exit 0 and read as a successful clean.
+//
+// THE BOOTSTRAP QUESTION, ANSWERED DELIBERATELY
+//
+// A `clear` script that calls `gjsify` makes cleaning depend on a built CLI —
+// the same circularity `gjsify run chmod` had in the CLI's own build (removed in
+// ce47b6a). It is acceptable HERE, and for a stronger reason than "you cannot
+// clear a tree you never built": for the single-command case there is no second
+// process at all. `gjsify run clear` recognises a script that is one
+// `gjsify <subcommand>` and dispatches it IN-PROCESS (see `cli-app.ts`), so the
+// nested-gjs cost the chmod case paid does not arise. `gjsify foreach clear`
+// still spawns one child per package, exactly as it did for `rm -rf`, and the
+// root script already passes `-p`.
+//
+// What it does mean: `clear` is a NEW command, so it does not exist in the
+// committed `dist/cli.gjs.mjs` until that bundle is rebuilt. On a checkout
+// carrying a stale bundle, `gjsify run clear` fails with "Unknown command" rather
+// than silently clearing nothing — which is the honest failure of the two.
+import { rm, stat } from 'node:fs/promises';
+import { readdirSync } from 'node:fs';
+import { relative } from 'node:path';
+import { resolveClearTargets } from '../utils/clear-targets.js';
+export const clearCommand = {
+    command: 'clear [paths..]',
+    description: 'Delete build output recursively. Portable replacement for `rm -rf` in package `clear` scripts.',
+    // No `normalize: true` anywhere below — see the comment block in
+    // `commands/build.ts`. It is meaningless for a path `fs.rm` resolves itself,
+    // and on win32 it is what would backslash a wildcard segment.
+    builder: (yargs) => {
+        return yargs
+            .positional('paths', {
+            description: 'Files and directories to delete, relative to the current package. A missing path is not an error. `*` and `?` are honoured in the last segment.',
+            type: 'string',
+            array: true,
+        })
+            .option('dry-run', {
+            description: 'Print what would be deleted and exit without touching anything.',
+            type: 'boolean',
+            default: false,
+        })
+            .option('verbose', {
+            alias: 'v',
+            description: 'Print each path as it is deleted.',
+            type: 'boolean',
+            default: false,
+        });
+    },
+    handler: async (args) => {
+        const cwd = process.cwd();
+        const paths = args.paths ?? [];
+        if (paths.length === 0) {
+            throw new Error('gjsify clear: no paths given. Usage: gjsify clear <paths…>');
+        }
+        // Resolution validates every target and throws on anything outside the
+        // package — before a single delete runs.
+        const targets = resolveClearTargets(paths, { cwd, readdir: readdirSync });
+        for (const target of targets) {
+            const shown = relative(cwd, target);
+            if (args.dryRun) {
+                const present = await stat(target).then(() => true, () => false);
+                console.log(`gjsify clear: would remove ${shown}${present ? '' : ' (absent)'}`);
+                continue;
+            }
+            // `maxRetries` is for Windows: a file another process still holds
+            // open fails there with EBUSY/EPERM instead of being unlinked while
+            // open as on POSIX — and clearing `@gjsify/cli` itself deletes the
+            // `lib/`+`dist/` the running process was loaded from. Both runtimes
+            // read a module fully and close it, so this covers a transient lock
+            // (a scanner, an editor), not a genuinely held handle; if it does
+            // fail, the error names the path instead of exiting 0.
+            await rm(target, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+            if (args.verbose)
+                console.log(`gjsify clear: removed ${shown}`);
+        }
+    },
+};

package/lib/commands/copy.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from '../types/index.js';
+interface CopyOptions {
+    paths?: string[];
+    dryRun?: boolean;
+    verbose?: boolean;
+}
+export declare const copyCommand: Command<unknown, CopyOptions>;
+export {};

package/lib/commands/copy.js

@@ -0,0 +1,87 @@
+// `gjsify copy <sources…> <dest>` — portable file staging for package scripts.
+//
+// WHY THIS EXISTS
+//
+// The sibling of `gjsify clear`, and the second half of the same finding. npm
+// runs package scripts through `cmd.exe` on Windows, which has no `cp`, no
+// `mkdir -p` and expands no glob. `clear` closed the 224 `rm -rf` scripts
+// (issue #914); what remained were 34 scripts that stage static assets with
+// `mkdir -p X && cp -r …` — `build:assets` (24), `build:public` (5), and one
+// each of `build:views`, `sync:theme`, `prebuild:test`, `prebuild:test:fixtures`.
+//
+// They were not merely a hygiene item. `showcases/node/express-webserver` is the
+// one showcase that runs on Windows at all — its `--app node` bundle needs no
+// gjs — and `build:public` is what puts `index.html` and `style.css` next to it.
+// Without this command the showcase builds and then serves 404s for its own
+// frontend, which is a worse failure than not building: the server starts.
+//
+// WHAT IT IS NOT
+//
+// Not a `cp` clone. Two deliberate differences, both because a build step is
+// re-run:
+//
+//   - `mkdir -p` is implied. Every one of the replaced scripts paired the two,
+//     and a copy that fails because the output directory does not exist yet is
+//     not a distinction worth preserving.
+//   - directory-vs-path is decided by the ARGUMENTS, never by what is on disk —
+//     see `isDirectoryDestination`. `cp -r src/assets dist/res` means two
+//     different things on the first and second run; this does not.
+//
+// Overwriting is unconditional (`force: true`), which is what the `-f` in most
+// of the replaced scripts asked for and what the rest wanted without saying so.
+import { cp, mkdir } from 'node:fs/promises';
+import { readdirSync } from 'node:fs';
+import { dirname, relative } from 'node:path';
+import { planCopy } from '../utils/copy-targets.js';
+export const copyCommand = {
+    command: 'copy [paths..]',
+    description: 'Copy files and directories into the build output. Portable replacement for `mkdir -p` + `cp -r` in package scripts.',
+    // No `normalize: true` — see the comment block in `commands/build.ts`. It is
+    // meaningless for a path resolved here anyway, and on win32 it is what would
+    // backslash a wildcard segment before it can be matched.
+    builder: (yargs) => {
+        return yargs
+            .positional('paths', {
+            description: 'One or more sources followed by the destination. The destination is a DIRECTORY when it ends with "/", when several sources are given, or when a source carries a wildcard; otherwise it is the exact target path. Missing parent directories are created. `*` and `?` are honoured in the last segment of a source.',
+            type: 'string',
+            array: true,
+        })
+            .option('dry-run', {
+            description: 'Print what would be copied and exit without touching anything.',
+            type: 'boolean',
+            default: false,
+        })
+            .option('verbose', {
+            alias: 'v',
+            description: 'Print each path as it is copied.',
+            type: 'boolean',
+            default: false,
+        });
+    },
+    handler: async (args) => {
+        const cwd = process.cwd();
+        const paths = args.paths ?? [];
+        if (paths.length < 2) {
+            throw new Error('gjsify copy: needs at least one source and a destination. Usage: gjsify copy <sources…> <dest>');
+        }
+        // Planning validates every argument — and every destination against the
+        // package boundary — before a single byte is written.
+        const ops = planCopy(paths, { cwd, readdir: readdirSync });
+        const show = (p) => {
+            const rel = relative(cwd, p);
+            // A source may legitimately live in a sibling package; showing it as
+            // `../../../packages/…` is more useful than an absolute path there.
+            return rel === '' ? '.' : rel;
+        };
+        for (const { from, to } of ops) {
+            if (args.dryRun) {
+                console.log(`gjsify copy: would copy ${show(from)} -> ${show(to)}`);
+                continue;
+            }
+            await mkdir(dirname(to), { recursive: true });
+            await cp(from, to, { recursive: true, force: true });
+            if (args.verbose)
+                console.log(`gjsify copy: ${show(from)} -> ${show(to)}`);
+        }
+    },
+};

package/lib/commands/dlx.js

@@ -89,7 +89,14 @@ export const dlxCommand = {
         const { binName, extraArgs } = splitBinAndArgs(pkgDir, args.binOrArg, extraArgsCombined);
         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.`);
+            // Name the key that is actually missing. The condition is
+            // `resolveGjsEntry` finding no `gjsify.main` (or no matching
+            // `gjsify.bin`), but the text said "no `gjsify` field" — and two
+            // showcases DO carry a `gjsify` object (tier + example) without a
+            // `main`, so the warning sent the reader looking for a field that
+            // was right there. Measured running `gjsify showcase
+            // webrtc-loopback` on a Node-less device.
+            console.warn(`[gjsify dlx] package "${cachedPkgName ?? parsed.kind}" declares no \`gjsify.main\` — falling back to package.json#main. Add \`gjsify.main\` to silence.`);
         }
         // Terminal call — exit on success, or the GJS main loop parks this
         // process forever (see RunGjsBundleOptions.exitOnSuccess).

package/lib/commands/index.d.ts

@@ -1,4 +1,6 @@
 export * from './build.js';
+export * from './clear.js';
+export * from './copy.js';
 export * from './test.js';
 export * from './run.js';
 export * from './info.js';

package/lib/commands/index.js

@@ -1,4 +1,6 @@
 export * from './build.js';
+export * from './clear.js';
+export * from './copy.js';
 export * from './test.js';
 export * from './run.js';
 export * from './info.js';

package/lib/commands/install.d.ts

@@ -12,6 +12,10 @@ interface InstallOptions {
     progress?: boolean;
     backend?: 'native' | 'npm';
     timeout: number;
+    os?: string;
+    cpu?: string;
+    libc?: string;
+    force?: boolean;
 }
 export declare const installCommand: Command<unknown, InstallOptions>;
 export declare function buildBinShim(wsLocation: string, nodeTarget?: string, gjsTarget?: string, nativePrebuildDirs?: string[], platform?: string, scanRoot?: string): string;