@gjsify/cli 0.4.21 → 0.4.22

package/lib/commands/check.d.ts

@@ -1,6 +1,10 @@
 import type { Command } from '../types/index.js';
 interface CheckOptions {
-    json: boolean;
+    include?: string[];
+    exclude?: string[];
+    parallel?: boolean;
+    jobs?: number;
+    verbose?: boolean;
 }
-export declare const checkCommand: Command<any, CheckOptions>;
+export declare const checkCommand: Command<unknown, CheckOptions>;
 export {};

package/lib/commands/check.js

@@ -1,72 +1,182 @@
-import { runAllChecks, detectPackageManager, buildInstallCommand } from '../utils/check-system-deps.js';
+// `gjsify check` — workspace TypeScript-check orchestrator.
+//
+// In a workspace root: runs `npm run check` across every workspace that
+// declares a `check` script (filtered the same way `gjsify foreach` filters:
+// excludes `@girs/*`, honours --include/--exclude). Parallel by default.
+//
+// In a single package (or anywhere a `package.json` with a `check` script
+// is reachable from cwd): runs the local `check` script directly. This is
+// the natural "tsc --noEmit on the current scope" invocation, analogous to
+// `gjsify format` / `lint` / `fix` (which all wrap Biome workspace-wide).
+//
+// The legacy system-dep-check shape lives under `gjsify system-check` after
+// PR #254. The `check` alias on `system-check` stays valid for one release
+// — 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 { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { cpus } from 'node:os';
+import { discoverWorkspaces, filterWorkspaces, } from '@gjsify/workspace';
+import { findWorkspaceRoot } from '../utils/workspace-root.js';
+function readPackageJson(dir) {
+    const path = join(dir, 'package.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run a single workspace's `check` script. Returns the exit code; non-zero
+ * indicates failure. Output is forwarded to the parent's stdout/stderr,
+ * line-prefixed with the workspace name when `prefix` is set.
+ */
+function runCheck(ws, prefix) {
+    return new Promise((resolve) => {
+        const child = spawn('npm', ['run', 'check', '--if-present'], {
+            cwd: ws.location,
+            stdio: prefix === null ? 'inherit' : ['ignore', 'pipe', 'pipe'],
+        });
+        if (prefix !== null && child.stdout && child.stderr) {
+            const tag = `[${prefix}] `;
+            const forward = (stream, dest) => {
+                stream.on('data', (chunk) => {
+                    const text = chunk.toString('utf-8');
+                    for (const line of text.split('\n')) {
+                        if (line.length > 0)
+                            dest.write(`${tag}${line}\n`);
+                    }
+                });
+            };
+            forward(child.stdout, process.stdout);
+            forward(child.stderr, process.stderr);
+        }
+        child.on('close', (code) => resolve(code ?? 1));
+        child.on('error', () => resolve(1));
+    });
+}
 export const checkCommand = {
     command: 'check',
-    description: 'Check that required system dependencies (GJS, GTK4, libsoup3, …) are installed. Optional dependencies are detected only when their @gjsify/* package is in your project.',
-    builder: (yargs) => {
-        return yargs
-            .option('json', {
-            description: 'Output results as JSON',
-            type: 'boolean',
-            default: false,
-        });
-    },
+    description: 'Run `npm run check` (TypeScript type-check) across the current workspace. In a workspace root: walks every package with a `check` script (excludes @girs/*; honours --include/--exclude). In a single package: runs the local `check` script directly. Symmetric peer of `gjsify format` / `lint` / `fix`. (Legacy system-dep `gjsify check` is now `gjsify system-check` — see #254.)',
+    builder: (yargs) => yargs
+        .option('include', {
+        description: 'Only run in workspaces matching these glob patterns (repeatable).',
+        type: 'string',
+        array: true,
+    })
+        .option('exclude', {
+        description: 'Skip workspaces matching these glob patterns (repeatable). Always excludes @girs/*.',
+        type: 'string',
+        array: true,
+    })
+        .option('parallel', {
+        description: 'Run workspace checks in parallel (default). Use --no-parallel to run them sequentially with full per-workspace output.',
+        type: 'boolean',
+        alias: 'p',
+        default: true,
+    })
+        .option('jobs', {
+        description: 'Max parallel workers (when --parallel). Default: os.cpus().length.',
+        type: 'number',
+        alias: 'j',
+    })
+        .option('verbose', {
+        description: 'Log the per-workspace command before spawning.',
+        type: 'boolean',
+        default: false,
+    }),
     handler: async (args) => {
-        const results = runAllChecks(process.cwd());
-        const pm = detectPackageManager();
-        const missingRequired = results.filter(r => !r.found && r.severity === 'required');
-        const missingOptional = results.filter(r => !r.found && r.severity === 'optional');
-        const allMissing = [...missingRequired, ...missingOptional];
-        if (args.json) {
-            console.log(JSON.stringify({ packageManager: pm, deps: results }, null, 2));
-            // Only required deps influence the exit code.
-            process.exit(missingRequired.length > 0 ? 1 : 0);
-            return;
-        }
-        console.log('System dependency check\n');
-        const required = results.filter(r => r.severity === 'required');
-        const optional = results.filter(r => r.severity === 'optional');
-        if (required.length > 0) {
-            console.log('Required:');
-            for (const dep of required) {
-                const icon = dep.found ? '✓' : '✗';
-                const ver = dep.version ? `  (${dep.version})` : '';
-                console.log(`  ${icon}  ${dep.name}${ver}`);
+        const cwd = process.cwd();
+        const workspaceRoot = findWorkspaceRoot(cwd);
+        // ---- Single-package mode ----
+        // Run when we're inside a package that has a `check` script but is
+        // NOT itself the workspace root. This is the "I want to tsc just
+        // this package" path — equivalent to `npm run check` but spawned
+        // through gjsify so the command surface stays uniform with format/
+        // lint/fix.
+        if (workspaceRoot && cwd !== workspaceRoot) {
+            const pkg = readPackageJson(cwd);
+            if (pkg?.scripts?.check) {
+                if (args.verbose) {
+                    console.log(`[check] cwd=${cwd}  → npm run check`);
+                }
+                const r = spawnSync('npm', ['run', 'check'], { cwd, stdio: 'inherit' });
+                process.exit(r.status ?? 1);
             }
+            // Fall through to workspace mode when the local package has no
+            // check script (cd'd into a non-package dir under the root).
         }
-        if (optional.length > 0) {
-            console.log('\nOptional:');
-            for (const dep of optional) {
-                // ⚠ for missing-but-needed-by-installed-packages, ○ for missing-but-not-needed (shouldn't appear in conditional mode)
-                const icon = dep.found ? '✓' : '⚠';
-                const ver = dep.version ? `  (${dep.version})` : '';
-                const requiredBy = dep.requiredBy && dep.requiredBy.length > 0
-                    ? `  — needed by ${dep.requiredBy.join(', ')}`
-                    : '';
-                console.log(`  ${icon}  ${dep.name}${ver}${requiredBy}`);
-            }
+        // ---- Workspace mode ----
+        if (!workspaceRoot) {
+            console.error('gjsify check: no workspace root found from cwd. Run inside a workspace (or a package within one) with `npm run check` defined.');
+            process.exit(1);
         }
-        console.log(`\nPackage manager: ${pm}`);
-        if (allMissing.length === 0) {
-            console.log('\nAll dependencies found.');
-            return;
+        const allWorkspaces = discoverWorkspaces(workspaceRoot);
+        // Always exclude @girs/* (type-only packages, no own tsc check).
+        const exclude = ['@girs/*', ...(args.exclude ?? [])];
+        const filtered = filterWorkspaces(allWorkspaces, {
+            include: args.include,
+            exclude,
+            // noPrivate omitted → include private workspaces (test pkgs often have check).
+        });
+        // Skip workspaces without a `check` script (manifest.scripts.check).
+        const targets = filtered.filter((ws) => {
+            const scripts = ws.manifest.scripts;
+            return scripts?.check !== undefined;
+        });
+        if (targets.length === 0) {
+            console.error('gjsify check: no workspaces with a `check` script found.');
+            process.exit(1);
         }
-        if (missingRequired.length > 0) {
-            console.log(`\nMissing required: ${missingRequired.map(d => d.name).join(', ')}`);
+        if (args.verbose) {
+            console.log(`[check] root=${workspaceRoot}  workspaces=${targets.length}  parallel=${args.parallel ? 'yes' : 'no'}`);
         }
-        if (missingOptional.length > 0) {
-            console.log(`Missing optional: ${missingOptional.map(d => d.name).join(', ')}`);
+        // ---- Sequential mode ----
+        if (!args.parallel) {
+            let firstFail = 0;
+            for (const ws of targets) {
+                if (args.verbose)
+                    console.log(`[check] → ${ws.name}`);
+                const code = await runCheck(ws, null);
+                if (code !== 0 && firstFail === 0)
+                    firstFail = code;
+            }
+            if (firstFail !== 0)
+                console.error(`gjsify check: failures in ${targets.filter(async (ws) => await runCheck(ws, null) !== 0).length}+ workspaces`);
+            process.exit(firstFail);
         }
-        const cmd = buildInstallCommand(pm, allMissing);
-        if (cmd) {
-            console.log(`\nTo install:\n  ${cmd}`);
+        // ---- Parallel mode (default) ----
+        const concurrency = args.jobs ?? Math.max(1, cpus().length);
+        const failures = [];
+        let cursor = 0;
+        const workers = [];
+        for (let i = 0; i < concurrency; i++) {
+            workers.push((async () => {
+                while (true) {
+                    const idx = cursor++;
+                    if (idx >= targets.length)
+                        return;
+                    const ws = targets[idx];
+                    const code = await runCheck(ws, ws.name);
+                    if (code !== 0)
+                        failures.push({ name: ws.name, code });
+                }
+            })());
         }
-        else {
-            console.log('\nNo install command available for your package manager. Install manually.');
+        await Promise.all(workers);
+        if (failures.length > 0) {
+            console.error(`\ngjsify check: ${failures.length} of ${targets.length} workspace(s) failed:`);
+            for (const f of failures)
+                console.error(`  ✗ ${f.name} (exit ${f.code})`);
+            process.exit(1);
         }
-        // Exit non-zero ONLY if a required dependency is missing.
-        // Optional deps that are missing but needed by an installed @gjsify/*
-        // package generate a warning but keep exit code 0 — the user can still
-        // build/run code paths that don't touch the optional library.
-        process.exit(missingRequired.length > 0 ? 1 : 0);
+        if (args.verbose)
+            console.log(`\ngjsify check: ${targets.length} workspace(s) green.`);
+        process.exit(0);
     },
 };

package/lib/commands/dlx.js

@@ -19,17 +19,24 @@ export const dlxCommand = {
     command: 'dlx <spec> [binOrArg] [extraArgs..]',
     description: 'Run the GJS bundle of an npm-published package without installing it locally.',
     builder: (yargs) => yargs
+        // Collect everything after `--` into argv['--'] so callers can
+        // forward flags that would otherwise be intercepted by gjsify's
+        // own parser. Canonical example: `gjsify dlx @ts-for-gir/cli --
+        // --help` shows ts-for-gir's --help instead of gjsify dlx's.
+        // Without `populate--`, the trailing `--help` is consumed at
+        // the gjsify level and the bundle never sees it.
+        .parserConfiguration({ 'populate--': true })
         .positional('spec', {
         description: 'Package spec (`name`, `name@version`, `@scope/name@spec`, or local path).',
         type: 'string',
         demandOption: true,
     })
         .positional('binOrArg', {
-        description: 'Optional bin name when the package defines `gjsify.bin` with multiple entries; otherwise treated as the first argument forwarded to the bundle.',
+        description: 'Optional bin name when the package defines `gjsify.bin` with multiple entries; otherwise treated as the first argument forwarded to the bundle. To pass a flag here (e.g. `--help`) use the `--` separator: `gjsify dlx <pkg> -- --help`.',
         type: 'string',
     })
         .positional('extraArgs', {
-        description: 'Extra args forwarded to `gjs -m <bundle>`.',
+        description: 'Extra args forwarded to `gjs -m <bundle>`. Use `--` before flags to bypass gjsify-level parsing (`gjsify dlx <pkg> -- --help --verbose`).',
         type: 'string',
         array: true,
     })
@@ -71,7 +78,15 @@ export const dlxCommand = {
         //   gjsify dlx <pkg> mybin                   → bin if package has gjsify.bin[mybin], else arg
         //   gjsify dlx <pkg> mybin -- arg1 arg2      → bin + extra args
         //   gjsify dlx <pkg> -- arg1 arg2            → no bin, extra args
-        const { binName, extraArgs } = splitBinAndArgs(pkgDir, args.binOrArg, args.extraArgs ?? []);
+        //
+        // The `parserConfiguration({ 'populate--': true })` on the builder
+        // routes anything after `--` into `args['--']` (as `(string |
+        // number)[]`), so flags like `--help` reach the bundle untouched.
+        // Merge those into the positional extraArgs the splitter sees so
+        // both call shapes share one downstream path.
+        const passthroughDoubleDash = (args['--'] ?? []).map((v) => String(v));
+        const extraArgsCombined = [...(args.extraArgs ?? []), ...passthroughDoubleDash];
+        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.`);

package/lib/commands/fix.js

@@ -2,8 +2,8 @@
 //
 // Equivalent to biome's `check` (format + safe-lint-fix + organize-imports).
 // Default writes fixes in-place; pass `--no-write` to report-only.
-// Naming: deliberately distinct from `gjsify check` (which verifies
-// system dependencies).
+// Naming: deliberately distinct from `gjsify check` (workspace TS check)
+// and `gjsify system-check` (system-dependency verifier).
 import { resolve } from 'node:path';
 import { BiomeNotFoundError, findBiomeConfig, printBiomeNotFound, runBiome, } from '../utils/biome-resolve.js';
 export const fixCommand = {

package/lib/commands/flatpak/init.js

@@ -138,14 +138,28 @@ export const flatpakInitCommand = {
         const cleanup = flatpak.cleanup;
         if (cleanup?.length)
             manifest.cleanup = cleanup;
+        // Module assembly. Two precedence rules:
+        //   `flatpak.modules`      — full replacement; if set, neither the
+        //                            extras nor the meson default get added.
+        //                            Right shape for npm-tarball CLI tools
+        //                            where the meson default would be wrong.
+        //   `flatpak.extraModules` — prepended to the meson default.
+        //                            Right shape for meson-built GTK apps
+        //                            that want a few extra sibling modules
+        //                            (e.g. blueprint-compiler).
         const modules = [];
-        if (flatpak.extraModules?.length)
-            modules.push(...flatpak.extraModules);
-        modules.push({
-            name: deriveModuleName(appId),
-            buildsystem: 'meson',
-            sources: [{ type: 'dir', path: '.' }],
-        });
+        if (flatpak.modules?.length) {
+            modules.push(...flatpak.modules);
+        }
+        else {
+            if (flatpak.extraModules?.length)
+                modules.push(...flatpak.extraModules);
+            modules.push({
+                name: deriveModuleName(appId),
+                buildsystem: 'meson',
+                sources: [{ type: 'dir', path: '.' }],
+            });
+        }
         manifest.modules = modules;
         const writtenFiles = [];
         const trackWrite = (p) => {

package/lib/commands/index.d.ts

@@ -2,6 +2,7 @@ export * from './build.js';
 export * from './test.js';
 export * from './run.js';
 export * from './info.js';
+export * from './system-check.js';
 export * from './check.js';
 export * from './showcase.js';
 export * from './create.js';

package/lib/commands/index.js

@@ -2,6 +2,7 @@ export * from './build.js';
 export * from './test.js';
 export * from './run.js';
 export * from './info.js';
+export * from './system-check.js';
 export * from './check.js';
 export * from './showcase.js';
 export * from './create.js';

package/lib/commands/install.d.ts

@@ -7,6 +7,7 @@ interface InstallOptions {
     'save-optional'?: boolean;
     immutable?: boolean;
     verbose: boolean;
+    backend?: 'native' | 'npm';
 }
 export declare const installCommand: Command<any, InstallOptions>;
 export {};

package/lib/commands/install.js

@@ -6,10 +6,11 @@
 //   gjsify install -g <pkg> [...]     → user-global install (XDG, GJS-runnable bin)
 //
 // All three modes route through `@gjsify/{semver,npm-registry,tar}` via
-// `installPackagesNative` — no Node/npm required at runtime. Set
-// `GJSIFY_INSTALL_BACKEND=npm` to opt back into the legacy `npm install`
-// subprocess flow (useful as escape-hatch for projects that hit a
-// missing native-backend feature).
+// `installPackagesNative` — no Node/npm required at runtime. Pass
+// `--backend=npm` (or set the legacy `GJSIFY_INSTALL_BACKEND=npm` env var)
+// to opt back into the `npm install` subprocess flow — useful as an
+// escape hatch for projects that hit a missing native-backend feature
+// (Yarn PnP repos, lifecycle scripts, npm's `overrides` quirks).
 //
 // Workspace install (`gjsify install` in a monorepo root with a
 // `"workspaces"` field) hoists every workspace's externals into the root
@@ -53,6 +54,11 @@ export const installCommand = {
         description: 'Verbose install logging.',
         type: 'boolean',
         default: false,
+    })
+        .option('backend', {
+        description: 'Install backend. `native` (default) routes through `@gjsify/{semver,npm-registry,tar}` — no Node/npm at runtime. `npm` shells out to `npm install` as an escape hatch for cases the native backend does not yet model (Yarn PnP repos, lifecycle scripts). Overrides `GJSIFY_INSTALL_BACKEND` if both are set.',
+        type: 'string',
+        choices: ['native', 'npm'],
     }),
     handler: async (args) => {
         // --immutable is incompatible with explicit `<pkg>` adds and with
@@ -82,8 +88,12 @@ export const installCommand = {
             await installGlobalAndLink(args.packages, { verbose: args.verbose });
             return;
         }
-        // Escape-hatch: legacy npm subprocess flow.
-        if (process.env.GJSIFY_INSTALL_BACKEND === 'npm') {
+        // Backend selection (in precedence order):
+        //   1. --backend flag (explicit user choice)
+        //   2. GJSIFY_INSTALL_BACKEND env (back-compat shape from pre-flag era)
+        //   3. native (default)
+        const backend = args.backend ?? process.env.GJSIFY_INSTALL_BACKEND ?? 'native';
+        if (backend === 'npm') {
             await projectInstallViaNpm(args);
             await runPostInstallChecks();
             return;

package/lib/commands/pack.d.ts

@@ -4,6 +4,7 @@ interface PackOptions {
     'pack-destination'?: string;
     json?: boolean;
     'dry-run'?: boolean;
+    'ignore-scripts'?: boolean;
 }
 interface PackResult {
     filename: string;
@@ -30,6 +31,21 @@ export interface PackWorkspaceOptions {
     dryRun?: boolean;
     /** Skip the workspace:^ rewrite step (rare — useful for testing the raw layout). */
     skipWorkspaceRewrite?: boolean;
+    /**
+     * Lifecycle scripts to run from `pkg.scripts` BEFORE the file collection
+     * pass. Order matters — entries are executed sequentially, stopping on
+     * the first failure.
+     *
+     * Defaults:
+     *   - `['prepack']` from the `gjsify pack` CLI handler
+     *   - `['prepublishOnly', 'prepack']` from `gjsify publish`
+     *   - `[]` from programmatic callers that have already run scripts
+     *
+     * Mirrors `npm pack` / `npm publish` semantics. Pass `[]` (or set
+     * `--ignore-scripts` on the CLI) to skip — useful when an outer
+     * workflow has already produced the build artifacts.
+     */
+    lifecycleScripts?: readonly string[];
 }
 /**
  * Programmatic equivalent of the `pack` command — used by `gjsify publish`

package/lib/commands/pack.js

@@ -29,6 +29,7 @@ import { join, resolve } from 'node:path';
 import { createTarball, gzip } from '@gjsify/tar';
 import { discoverWorkspaces } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
+import { runLifecycleScript } from '../utils/run-lifecycle-script.js';
 export const packCommand = {
     command: 'pack [path]',
     description: 'Produce an npm-compatible .tgz tarball for the workspace at <path> (default: cwd). Rewrites workspace:^/~/* deps to resolved versions.',
@@ -50,12 +51,20 @@ export const packCommand = {
         description: 'Compute everything but do not write the .tgz.',
         type: 'boolean',
         default: false,
+    })
+        .option('ignore-scripts', {
+        description: 'Skip the `prepack` lifecycle script before packing. ' +
+            'Mirrors `npm pack --ignore-scripts`. Use when scripts ' +
+            'are already run by the outer workflow.',
+        type: 'boolean',
+        default: false,
     }),
     handler: async (args) => {
         const wsDir = resolve(args.path ?? process.cwd());
         const result = await packWorkspace(wsDir, {
             destination: args['pack-destination'],
             dryRun: args['dry-run'] === true,
+            lifecycleScripts: args['ignore-scripts'] ? [] : ['prepack'],
         });
         if (args.json) {
             process.stdout.write(`${JSON.stringify([result], null, 2)}\n`);
@@ -82,17 +91,35 @@ export async function packWorkspace(wsDir, opts = {}) {
     if (!name) {
         throw new Error(`gjsify pack: package.json at ${wsDir} has no "name"`);
     }
+    // Run npm-style lifecycle scripts BEFORE walking the file tree. The
+    // canonical case is `prepack` — many packages use it to generate
+    // build artifacts that aren't otherwise produced by their `build`
+    // script (template processing, codegen, etc.). Skipping these means
+    // the resulting tarball is missing files the package needs to work
+    // post-install. Matches `npm pack` / `npm publish` semantics.
+    const lifecycleScripts = opts.lifecycleScripts ?? ['prepack'];
+    for (const scriptName of lifecycleScripts) {
+        await runLifecycleScript(wsDir, pkg, scriptName, { optional: true });
+    }
+    // Re-read package.json AFTER lifecycle scripts in case one of them
+    // mutated it (e.g. a `prepack` that injects build metadata into
+    // package.json fields). Rare but legal — npm pack does the same.
+    const sourceAfterScripts = readFileSync(pkgPath, 'utf-8');
+    const pkgAfterScripts = sourceAfterScripts === originalSource
+        ? pkg
+        : JSON.parse(sourceAfterScripts);
     // Rewrite workspace:^/~/* deps to resolved npm version ranges, mirroring
     // yarn's auto-rewrite at publish time. Done in-memory only — the source
     // package.json on disk is never mutated by `gjsify pack`.
     const rewrittenPkg = opts.skipWorkspaceRewrite
-        ? pkg
-        : rewriteWorkspaceDeps(pkg, wsDir);
-    const rewrittenSource = JSON.stringify(rewrittenPkg, null, indentOf(originalSource)) + '\n';
+        ? pkgAfterScripts
+        : rewriteWorkspaceDeps(pkgAfterScripts, wsDir);
+    const rewrittenSource = JSON.stringify(rewrittenPkg, null, indentOf(sourceAfterScripts)) + '\n';
     // Collect files according to the package.json `files` field (or npm's
     // default set). The package.json itself is always included with the
-    // rewritten contents.
-    const filesToPack = collectFiles(wsDir, pkg);
+    // rewritten contents. We use the post-script `pkgAfterScripts` here so
+    // that any `files` array modified by a prepack script is honored.
+    const filesToPack = collectFiles(wsDir, pkgAfterScripts);
     const entries = [{ name: 'package/', directory: true, mode: 0o755 }];
     const fileMetas = [];
     let unpackedSize = 0;

package/lib/commands/publish.js

@@ -149,8 +149,17 @@ export const publishCommand = {
                 return;
             }
         }
-        // 1. Pack the workspace (rewrites workspace:^, computes integrity)
-        const packOpts = { dryRun: true };
+        // 1. Pack the workspace (rewrites workspace:^, computes integrity).
+        // Lifecycle scripts: `prepublishOnly` (publish-specific) runs before
+        // `prepack`. Matches `npm publish` semantics — packages that gate
+        // release-time validation on `prepublishOnly` (typecheck, smoke
+        // tests, version-tagging) get exactly that, and packages whose
+        // `prepack` generates build artifacts (process-templates,
+        // codegen, …) get those artifacts into the tarball.
+        const packOpts = {
+            dryRun: true,
+            lifecycleScripts: ['prepublishOnly', 'prepack'],
+        };
         const packed = await packWorkspace(wsDir, packOpts);
         // We need the raw bytes — re-run with destination=null and capture.
         // packWorkspace returns metadata only; for the bytes we re-pack into
@@ -351,9 +360,16 @@ export const publishCommand = {
 };
 async function packWorkspaceToBytes(wsDir) {
     // Cheap re-run that writes to a tempdir, then read back. Avoids
-    // duplicating the file-walking + tar-building logic here.
+    // duplicating the file-walking + tar-building logic here. Lifecycle
+    // scripts are already run by the outer publish flow's first pack
+    // call — passing `[]` here skips re-running them (idempotent for
+    // most projects but a needless cost otherwise).
     const tmp = `/tmp/gjsify-publish-${process.pid}-${Date.now()}`;
-    const res = await packWorkspace(wsDir, { destination: tmp, dryRun: false });
+    const res = await packWorkspace(wsDir, {
+        destination: tmp,
+        dryRun: false,
+        lifecycleScripts: [],
+    });
     if (!res.absolutePath)
         throw new Error('gjsify publish: pack did not produce a file');
     const bytes = new Uint8Array(readFileSync(res.absolutePath));

package/lib/commands/system-check.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from '../types/index.js';
+interface CheckOptions {
+    json: boolean;
+}
+export declare const systemCheckCommand: Command<any, CheckOptions>;
+export {};

package/lib/commands/system-check.js

@@ -0,0 +1,72 @@
+import { runAllChecks, detectPackageManager, buildInstallCommand } from '../utils/check-system-deps.js';
+export const systemCheckCommand = {
+    command: 'system-check',
+    description: 'Check that required system dependencies (GJS, GTK4, libsoup3, …) are installed. Optional dependencies are detected only when their @gjsify/* package is in your project. (Previously called `gjsify check`; the bare name now runs TypeScript checks across the workspace — see `gjsify check --help`.)',
+    builder: (yargs) => {
+        return yargs
+            .option('json', {
+            description: 'Output results as JSON',
+            type: 'boolean',
+            default: false,
+        });
+    },
+    handler: async (args) => {
+        const results = runAllChecks(process.cwd());
+        const pm = detectPackageManager();
+        const missingRequired = results.filter(r => !r.found && r.severity === 'required');
+        const missingOptional = results.filter(r => !r.found && r.severity === 'optional');
+        const allMissing = [...missingRequired, ...missingOptional];
+        if (args.json) {
+            console.log(JSON.stringify({ packageManager: pm, deps: results }, null, 2));
+            // Only required deps influence the exit code.
+            process.exit(missingRequired.length > 0 ? 1 : 0);
+            return;
+        }
+        console.log('System dependency check\n');
+        const required = results.filter(r => r.severity === 'required');
+        const optional = results.filter(r => r.severity === 'optional');
+        if (required.length > 0) {
+            console.log('Required:');
+            for (const dep of required) {
+                const icon = dep.found ? '✓' : '✗';
+                const ver = dep.version ? `  (${dep.version})` : '';
+                console.log(`  ${icon}  ${dep.name}${ver}`);
+            }
+        }
+        if (optional.length > 0) {
+            console.log('\nOptional:');
+            for (const dep of optional) {
+                // ⚠ for missing-but-needed-by-installed-packages, ○ for missing-but-not-needed (shouldn't appear in conditional mode)
+                const icon = dep.found ? '✓' : '⚠';
+                const ver = dep.version ? `  (${dep.version})` : '';
+                const requiredBy = dep.requiredBy && dep.requiredBy.length > 0
+                    ? `  — needed by ${dep.requiredBy.join(', ')}`
+                    : '';
+                console.log(`  ${icon}  ${dep.name}${ver}${requiredBy}`);
+            }
+        }
+        console.log(`\nPackage manager: ${pm}`);
+        if (allMissing.length === 0) {
+            console.log('\nAll dependencies found.');
+            return;
+        }
+        if (missingRequired.length > 0) {
+            console.log(`\nMissing required: ${missingRequired.map(d => d.name).join(', ')}`);
+        }
+        if (missingOptional.length > 0) {
+            console.log(`Missing optional: ${missingOptional.map(d => d.name).join(', ')}`);
+        }
+        const cmd = buildInstallCommand(pm, allMissing);
+        if (cmd) {
+            console.log(`\nTo install:\n  ${cmd}`);
+        }
+        else {
+            console.log('\nNo install command available for your package manager. Install manually.');
+        }
+        // Exit non-zero ONLY if a required dependency is missing.
+        // Optional deps that are missing but needed by an installed @gjsify/*
+        // package generate a warning but keep exit code 0 — the user can still
+        // build/run code paths that don't touch the optional library.
+        process.exit(missingRequired.length > 0 ? 1 : 0);
+    },
+};