@gjsify/cli 0.26.0 → 0.27.0

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

@@ -7,15 +7,30 @@
 // up running the touched workspace + its downstream consumers instead of
 // the whole monorepo.
 //
+// EVERY VERDICT THIS FILE EMITS IS SCOPED TO ONE WORKFLOW: `main.yml`. That
+// scoping is the single most misread thing here, so it is stated before the
+// tables rather than after. The classifier is booted only by `main.yml`'s
+// `changes` job, and `main.yml` is the only workflow whose jobs consume its
+// outputs. So "ignored" NEVER means "irrelevant to the repository" — it means
+// "cannot change what `main.yml` builds or tests". Sibling workflows
+// (`prebuilds.yml`, `audit-runtimes.yml`, `node-gi.yml`, `napi.yml`,
+// `deploy-docs.yml`, …) gate themselves with their OWN `paths:` filters and are
+// unaffected by anything decided here. `IGNORE` has always worked this way —
+// `packages/node-gi/**` and `packages/napi/**` are load-bearing build inputs to
+// their own workflows and ignored here — but the table read as a global claim,
+// which is how a directory that is genuinely irrelevant to `main.yml` still
+// looks like something that must not be ignored.
+//
 // Classifier table (first-match wins) handles the cases that aren't a
 // straightforward "file lives in workspace X":
 //
-//   1. IGNORE  — pure-docs / *.md / website / refs/ submodule / unrelated
-//      workflow files / LICENSE / .gitignore. Discarded FIRST, before every
-//      other rule: an ignored file is never build-relevant, not even inside
-//      a GLOBAL_TRIGGERS directory (e.g. `packages/infra/cli/README.md` must
-//      not force a full run just because `packages/infra/cli/` is a global
-//      trigger). Ignore wins over global.
+//   1. IGNORE  — cannot change what `main.yml` builds or tests: pure-docs /
+//      *.md / website / refs/ submodule / other workflows' files and their
+//      inputs / LICENSE / .gitignore. Discarded FIRST, before every other
+//      rule: an ignored file is never build-relevant to this workflow, not
+//      even inside a GLOBAL_TRIGGERS directory (e.g.
+//      `packages/infra/cli/README.md` must not force a full run just because
+//      `packages/infra/cli/` is a global trigger). Ignore wins over global.
 //
 //   2. GLOBAL_TRIGGERS  — a non-ignored change touching infra the classifier
 //      itself depends on (`@gjsify/workspace`, `@gjsify/cli`, the bundler
@@ -24,12 +39,17 @@
 //      can't trust the closure when the algorithm that computes it just
 //      changed.
 //
-//   3. TEST_ONLY  — every changed file under ONE workspace is a spec
+//   3. SCRIPT_COUPLINGS  — a build input that reaches its consumer through a
+//      BUILD SCRIPT instead of a dependency, so the closure walk has no edge
+//      to follow. Contributes EXTRA seeds (and may force a test tier). See
+//      the table for why this cannot be inferred and must be declared.
+//
+//   4. TEST_ONLY  — every changed file under ONE workspace is a spec
 //      file, e2e fixture, or integration test. Seed = that workspace
 //      but SKIP the closure expansion (downstream consumers don't care
 //      about test code changes).
 //
-//   4. CODE (default)  — `workspacesForChangedFiles` maps file → ws,
+//   5. CODE (default)  — `workspacesForChangedFiles` maps file → ws,
 //      then `affectedClosure` walks reverse-dep edges.
 //
 // Integration tests are gated separately: they run when any workspace
@@ -162,13 +182,55 @@ const GLOBAL_TRIGGERS = [
     /^\.github\/workflows\/main\.yml$/,
     /^scripts\/audit-runtimes\.mjs$/,
 ];
+/**
+ * Inputs OWNED BY ANOTHER WORKFLOW — build-relevant, just not to `main.yml`.
+ *
+ * This is the sub-table where the workflow scoping stated at the top of the
+ * file is load-bearing, so each entry NAMES the workflow that does gate it.
+ * The test for membership is not "is this file unimportant" (none of these
+ * are) but "can `main.yml` build or test differently because of it" — and for
+ * every entry the answer is no, while the owning workflow has the path in its
+ * own `paths:` filter and would go red on a break.
+ *
+ * Adding a regex here is therefore a claim with two halves, and BOTH must
+ * hold: `main.yml` must not read the path, and some other workflow must.
+ */
+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|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/**`
+    // in BOTH its `push` and `pull_request` `paths:` filters, so a break here
+    // reds that workflow on the same PR. `main.yml` never executes any of it —
+    // it builds no prebuild and runs no emulated leg.
+    /^\.github\/prebuild-toolchain\//,
+    // The REPO-SCOPED manifest-conformance rules (#847) — `tier`, `refs-pin`,
+    // `platforms-ci` plus the `unchecked-fields` ledger. Their gate is
+    // `audit-runtimes.yml`, which runs `node scripts/audit-runtimes.mjs
+    // --check --strict` on EVERY pull_request with no `paths:` filter at all,
+    // so this content is verified on every PR regardless of what is ignored
+    // here; `prebuilds.yml` additionally declares it a shared input (#843) and
+    // rebuilds every native package when it changes.
+    //
+    // The distinction that makes this safe is a real one, not a technicality:
+    // `main.yml` DOES run manifest-conformance code, but it reaches it through
+    // `scripts/verify-package-outputs.mjs` importing
+    // `packages/infra/manifest-conformance/lib/**` — the PACKAGE, a normal
+    // workspace under the `packages/infra/*` glob that maps and seeds like any
+    // other. Only the `scripts/`-side repo-scoped half is ignored, and that
+    // half is precisely the half `main.yml` does not load.
+    /^scripts\/manifest-conformance\//,
+];
 /** Patterns that contribute no seed and don't force a full run. */
 const IGNORE = [
     /\.md$/i,
     /^refs\//,
     /^website\//,
     /^docs\//,
-    /^\.github\/workflows\/(deploy-docs|commitlint|release|audit-runtimes|prebuilds|node-gi|napi|cli-cross-platform|build-ci-image)\.yml$/,
+    ...OTHER_WORKFLOW_INPUTS,
     /^\.githooks\//,
     // @gjsify/node-gi (the Node-native GObject-Introspection engine, Axis 5) is
     // NOT a gjsify workspace member — the GJS-first install/foreach tooling can't
@@ -200,6 +262,31 @@ const IGNORE = [
 ];
 /** Patterns that suggest a test-only change. */
 const TEST_PATHS = [/\.spec\.[mc]?[tj]sx?$/, /^tests\/(e2e|integration)\//];
+const SCRIPT_COUPLINGS = [
+    {
+        // `templates/*` ARE workspaces (root `package.json#workspaces` carries
+        // a `templates/*` glob), so a template change already seeds its own
+        // `@gjsify/template-<name>`. That is not the consumer that matters.
+        //
+        // The consumer is `@gjsify/create-app`, and it is unreachable twice
+        // over: it lives at `packages/infra/create-gjsify/`, so no
+        // directory-name search finds it, and it takes the templates in
+        // through `node scripts/process-template.mjs` in its `build` script
+        // (which resolves each template's `workspace:^` specifiers and copies
+        // the result into `dist-templates/`), so there is no dependency edge
+        // either. `dist-templates/` is a build-output cache candidate, so once
+        // it is stale it stays stale.
+        match: /^templates\//,
+        seeds: ['@gjsify/create-app'],
+        // …and `tests/e2e/create-app` is the ONLY thing that would notice: it
+        // scaffolds a project out of `dist-templates/` and builds it. Without
+        // this a templates-only PR got neither the regenerated templates nor
+        // the suite that exercises them. PR #853 passed only by accident of
+        // also touching root `package.json` and tripping a global trigger.
+        runE2E: true,
+        why: '@gjsify/create-app build → node scripts/process-template.mjs reads templates/',
+    },
+];
 function classifyAndExpand(workspaces, changedFiles) {
     const files = changedFiles.map((f) => f.replace(/\\/g, '/')).filter((f) => f.length > 0);
     if (files.length === 0) {
@@ -250,23 +337,64 @@ function classifyAndExpand(workspaces, changedFiles) {
     }
     // Map files → workspaces. Files outside any workspace stay in `unmatched`.
     const { matched, unmatched } = workspacesForChangedFiles(workspaces, remaining);
+    // SCRIPT_COUPLINGS: add the seeds no graph edge can reach. Applied BEFORE
+    // the `unmatched` bail-out so the table works for a coupled directory that
+    // is NOT itself a workspace — such a file would otherwise force a full run
+    // and the declared seeds would never be consulted.
+    const knownNames = new Set(workspaces.map((w) => w.name));
+    const couplingSeeds = new Set();
+    const couplingAccounted = new Set();
+    let couplingRunE2E = false;
+    for (const c of SCRIPT_COUPLINGS) {
+        const hits = remaining.filter((f) => c.match.test(f));
+        if (hits.length === 0)
+            continue;
+        for (const h of hits)
+            couplingAccounted.add(h);
+        for (const s of c.seeds) {
+            // A declared seed that is not a workspace means the table has
+            // drifted from the tree (package renamed, moved, removed). Fail
+            // towards the full run and SAY SO — the whole point of this table
+            // is that a missing rebuild here is otherwise invisible, so it must
+            // never degrade quietly back into the bug it exists to prevent.
+            if (!knownNames.has(s)) {
+                return {
+                    global: true,
+                    reason: `script-coupling seed ${s} is not a workspace (${c.match.source} → ${c.why}); ` +
+                        `SCRIPT_COUPLINGS in commands/affected.ts is stale`,
+                    workspaces: workspaces.map((w) => w.name),
+                    runE2E: true,
+                    runIntegration: true,
+                    skipAll: false,
+                };
+            }
+            couplingSeeds.add(s);
+        }
+        if (c.runE2E)
+            couplingRunE2E = true;
+    }
     // Unmatched-but-not-ignored files are suspicious enough to fall back to
     // the conservative "full run" path. Examples: a new top-level dotfile,
     // a script in `scripts/` we haven't carved out, a refs/-adjacent file.
-    if (unmatched.length > 0) {
+    // A file a coupling claimed is accounted for and does not count here.
+    const stillUnmatched = unmatched.filter((f) => !couplingAccounted.has(f));
+    if (stillUnmatched.length > 0) {
         return {
             global: true,
-            reason: `unmatched files (${unmatched.length}): ${unmatched.slice(0, 3).join(', ')}${unmatched.length > 3 ? '…' : ''}`,
+            reason: `unmatched files (${stillUnmatched.length}): ${stillUnmatched.slice(0, 3).join(', ')}${stillUnmatched.length > 3 ? '…' : ''}`,
             workspaces: workspaces.map((w) => w.name),
             runE2E: true,
             runIntegration: true,
             skipAll: false,
         };
     }
+    for (const s of couplingSeeds)
+        matched.add(s);
     // TEST_ONLY shortcut: every remaining file is a spec / e2e / integration
     // path, all under ONE workspace. Skip the closure expansion — test code
-    // has no downstream consumers.
-    const testOnly = remaining.every((f) => TEST_PATHS.some((re) => re.test(f)));
+    // has no downstream consumers. A coupling deliberately disables it: the
+    // extra seeds exist precisely because a downstream consumer DOES care.
+    const testOnly = couplingSeeds.size === 0 && remaining.every((f) => TEST_PATHS.some((re) => re.test(f)));
     if (testOnly && matched.size === 1) {
         const only = [...matched][0];
         // E2E or integration test-only changes still need their own job.
@@ -317,10 +445,13 @@ function classifyAndExpand(workspaces, changedFiles) {
             }
         }
     }
-    const runE2E = remaining.some((f) => f.startsWith('tests/e2e/'));
+    // A `tests/e2e/**` touch turns the tier on, and so does any coupling that
+    // declares e2e as its only real coverage (see SCRIPT_COUPLINGS).
+    const runE2E = remaining.some((f) => f.startsWith('tests/e2e/')) || couplingRunE2E;
     return {
         global: false,
-        reason: `closure (${closure.size} ws from ${matched.size} seed(s))`,
+        reason: `closure (${closure.size} ws from ${matched.size} seed(s))` +
+            (couplingSeeds.size > 0 ? `, ${couplingSeeds.size} via script-coupling` : ''),
         workspaces: [...closure].sort(),
         runE2E,
         runIntegration,

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 {};