@gjsify/cli 0.3.20 → 0.4.0

package/lib/commands/foreach.js

@@ -0,0 +1,268 @@
+// `gjsify foreach [flags] <script>` — yarn-workspaces-foreach replacement.
+//
+// Replaces every `yarn workspaces foreach -A -p --no-private --exclude
+// '@girs/*' --topological run build` style invocation in monorepo
+// scripts. Flags mirror yarn 4's shape so root package.json scripts can
+// move over with a 1:1 substitution.
+//
+// Output is line-prefixed `[<workspace-name>]` when --parallel is set,
+// matching yarn's interactive flow. Exit code is non-zero if any child
+// process failed; first failure's stderr is forwarded.
+import { spawn } from 'node:child_process';
+import { cpus } from 'node:os';
+import { buildDependencyGraph, discoverWorkspaces, filterWorkspaces, topologicalSort, } from '@gjsify/workspace';
+export const foreachCommand = {
+    command: 'foreach <script> [args..]',
+    description: 'Run a workspace script across all (or filtered) workspaces. Drop-in for `yarn workspaces foreach`: -A/--all, -p/--parallel, -t/--topological, --include, --exclude, --no-private.',
+    builder: (yargs) => yargs
+        .positional('script', {
+        description: 'Script name to run in each workspace (`run <name>`-equivalent).',
+        type: 'string',
+        demandOption: true,
+    })
+        .positional('args', {
+        description: 'Extra arguments forwarded to each child invocation.',
+        type: 'string',
+        array: true,
+    })
+        .option('all', {
+        description: 'Include workspaces declared as `private: true`.',
+        type: 'boolean',
+        alias: 'A',
+        default: false,
+    })
+        .option('parallel', {
+        description: 'Run workspaces in parallel (capped by --jobs).',
+        type: 'boolean',
+        alias: 'p',
+        default: false,
+    })
+        .option('topological', {
+        description: 'Wait for each workspace\'s deps to finish before starting it (production deps only).',
+        type: 'boolean',
+        alias: 't',
+        default: false,
+    })
+        .option('topological-dev', {
+        description: 'Like --topological but also respects devDependencies (often cyclic — use sparingly).',
+        type: 'boolean',
+        default: false,
+    })
+        .option('include', {
+        description: 'Glob pattern to include workspaces by name (repeatable).',
+        type: 'string',
+        array: true,
+    })
+        .option('exclude', {
+        description: 'Glob pattern to exclude workspaces by name (repeatable).',
+        type: 'string',
+        array: true,
+    })
+        .option('private', {
+        // Yargs auto-negates `--no-private` to `private=false`, so the
+        // user-facing flag stays `--no-private` (yarn-compatible).
+        description: 'Include private workspaces (default true). Pass --no-private to skip them.',
+        type: 'boolean',
+        default: true,
+    })
+        .option('verbose', {
+        description: 'Echo every spawned command before running it.',
+        type: 'boolean',
+        alias: 'v',
+        default: false,
+    })
+        .option('jobs', {
+        description: 'Maximum concurrent workspaces in --parallel mode (default: cpu count).',
+        type: 'number',
+        alias: 'j',
+    }),
+    handler: async (args) => {
+        const cwd = process.cwd();
+        const allWorkspaces = discoverWorkspaces(cwd);
+        let selected = filterWorkspaces(allWorkspaces, {
+            include: args.include,
+            exclude: args.exclude,
+            noPrivate: args.private === false,
+        });
+        // Only run on workspaces that actually have the requested script —
+        // yarn does this too, otherwise every project that doesn't declare
+        // `<script>` would fail and force the user to `--exclude` it.
+        selected = selected.filter((ws) => {
+            const scripts = ws.manifest.scripts ?? {};
+            return typeof scripts[args.script] === 'string';
+        });
+        if (selected.length === 0) {
+            console.log(`gjsify foreach: no workspaces match (script="${args.script}", include=${JSON.stringify(args.include ?? [])}, exclude=${JSON.stringify(args.exclude ?? [])})`);
+            return;
+        }
+        if (args.topological || args['topological-dev']) {
+            const graph = buildDependencyGraph(selected, {
+                includeDev: args['topological-dev'] === true,
+            });
+            selected = topologicalSort(graph);
+        }
+        const cmd = args.script;
+        const cmdArgs = args.args ?? [];
+        const verbose = args.verbose === true;
+        if (args.parallel && !args.topological && !args['topological-dev']) {
+            const jobs = args.jobs && args.jobs > 0 ? args.jobs : cpus().length;
+            await runParallel(selected, cmd, cmdArgs, jobs, verbose);
+            return;
+        }
+        if (args.parallel) {
+            // Topological + parallel: each workspace starts as soon as its
+            // deps (in the selected set) have finished. Yarn calls this
+            // "topological order with concurrency"; we cap at --jobs.
+            const jobs = args.jobs && args.jobs > 0 ? args.jobs : cpus().length;
+            await runTopologicalParallel(selected, cmd, cmdArgs, jobs, verbose, args['topological-dev'] === true);
+            return;
+        }
+        await runSequential(selected, cmd, cmdArgs, verbose);
+    },
+};
+async function runSequential(workspaces, script, args, verbose) {
+    for (const ws of workspaces) {
+        await runOne(ws, script, args, /* prefixOutput */ false, verbose);
+    }
+}
+async function runParallel(workspaces, script, args, concurrency, verbose) {
+    let cursor = 0;
+    const workers = [];
+    for (let w = 0; w < concurrency; w++) {
+        workers.push((async () => {
+            while (cursor < workspaces.length) {
+                const i = cursor++;
+                await runOne(workspaces[i], script, args, /* prefixOutput */ true, verbose);
+            }
+        })());
+    }
+    await Promise.all(workers);
+}
+async function runTopologicalParallel(workspaces, script, args, concurrency, verbose, includeDev) {
+    const selectedNames = new Set(workspaces.map((w) => w.name));
+    const remaining = new Map();
+    for (const ws of workspaces) {
+        const wsDeps = new Set();
+        const m = ws.manifest;
+        for (const block of [
+            m.dependencies,
+            includeDev ? m.devDependencies : undefined,
+            m.optionalDependencies,
+        ]) {
+            if (!block)
+                continue;
+            for (const [name, spec] of Object.entries(block)) {
+                if (typeof spec !== 'string')
+                    continue;
+                if (!spec.startsWith('workspace:'))
+                    continue;
+                if (selectedNames.has(name))
+                    wsDeps.add(name);
+            }
+        }
+        remaining.set(ws.name, wsDeps);
+    }
+    const byName = new Map(workspaces.map((w) => [w.name, w]));
+    const done = new Set();
+    let inflight = 0;
+    return new Promise((resolve, reject) => {
+        let error = null;
+        const pump = () => {
+            if (error)
+                return;
+            while (inflight < concurrency) {
+                const ready = [...remaining.entries()]
+                    .filter(([, deps]) => [...deps].every((d) => done.has(d)))
+                    .map(([n]) => n);
+                if (ready.length === 0)
+                    break;
+                const next = ready.sort()[0];
+                remaining.delete(next);
+                inflight++;
+                runOne(byName.get(next), script, args, /* prefixOutput */ true, verbose)
+                    .then(() => {
+                    inflight--;
+                    done.add(next);
+                    if (remaining.size === 0 && inflight === 0) {
+                        resolve();
+                        return;
+                    }
+                    pump();
+                })
+                    .catch((e) => {
+                    error = e instanceof Error ? e : new Error(String(e));
+                    // Wait for in-flight tasks to finish (yarn does the
+                    // same — surfaces all errors instead of abruptly
+                    // killing siblings).
+                    if (inflight === 0)
+                        reject(error);
+                });
+            }
+            if (remaining.size > 0 && inflight === 0 && !error) {
+                reject(new Error(`gjsify foreach --topological: stuck — workspaces ${[...remaining.keys()].join(', ')} have unsatisfied deps in the selected set`));
+            }
+        };
+        pump();
+    });
+}
+async function runOne(ws, script, args, prefixOutput, verbose) {
+    // Use the same package manager that invoked us — yarn under yarn,
+    // npm under npm, gjsify under gjsify. Default to `npm` for portability
+    // when nothing is detectable; the script-runner (D.5) will replace
+    // this once `gjsify run` ships.
+    const runner = detectPackageManager();
+    const argv = runner === 'gjsify'
+        ? ['run', script, ...args]
+        : ['run', script, ...(args.length > 0 ? ['--', ...args] : [])];
+    if (verbose) {
+        console.error(`[${ws.name}] $ ${runner} ${argv.join(' ')}`);
+    }
+    await spawnPrefixed(runner, argv, ws.location, prefixOutput ? `[${ws.name}] ` : null);
+}
+function detectPackageManager() {
+    // `npm_config_user_agent` is set by npm/yarn/pnpm — first token is
+    // `<name>/<version>`. Reuse it so `gjsify foreach build` invoked
+    // through `yarn run` keeps using yarn, etc.
+    const ua = process.env.npm_config_user_agent ?? '';
+    if (ua.startsWith('yarn/'))
+        return 'yarn';
+    if (ua.startsWith('gjsify/'))
+        return 'gjsify';
+    return 'npm';
+}
+function spawnPrefixed(cmd, args, cwd, prefix) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, {
+            cwd,
+            stdio: prefix ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+            env: process.env,
+        });
+        if (prefix && child.stdout && child.stderr) {
+            prefixLines(child.stdout, process.stdout, prefix);
+            prefixLines(child.stderr, process.stderr, prefix);
+        }
+        child.on('close', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`${cmd} ${args.join(' ')} exited with code ${code}`));
+        });
+        child.on('error', (err) => reject(err));
+    });
+}
+function prefixLines(src, sink, prefix) {
+    let buf = '';
+    src.setEncoding('utf-8');
+    src.on('data', (chunk) => {
+        buf += chunk;
+        let idx;
+        while ((idx = buf.indexOf('\n')) !== -1) {
+            sink.write(prefix + buf.slice(0, idx + 1));
+            buf = buf.slice(idx + 1);
+        }
+    });
+    src.on('end', () => {
+        if (buf.length > 0)
+            sink.write(prefix + buf + '\n');
+    });
+}

package/lib/commands/index.d.ts

@@ -10,3 +10,5 @@ export * from './gsettings.js';
 export { flatpakCommand } from './flatpak/index.js';
 export * from './dlx.js';
 export * from './install.js';
+export * from './foreach.js';
+export * from './workspace.js';

package/lib/commands/index.js

@@ -10,3 +10,5 @@ export * from './gsettings.js';
 export { flatpakCommand } from './flatpak/index.js';
 export * from './dlx.js';
 export * from './install.js';
+export * from './foreach.js';
+export * from './workspace.js';

package/lib/commands/install.d.ts

@@ -5,6 +5,7 @@ interface InstallOptions {
     'save-dev'?: boolean;
     'save-peer'?: boolean;
     'save-optional'?: boolean;
+    immutable?: boolean;
     verbose: boolean;
 }
 export declare const installCommand: Command<any, InstallOptions>;

package/lib/commands/install.js

@@ -1,28 +1,28 @@
 // `gjsify install [pkg...]` — install packages with gjsify-aware post-checks.
 //
 // Modes:
-//   gjsify install                    → project install (npm install)
-//   gjsify install <pkg> [<pkg>...]   → add package(s) to project (npm install <pkg>...)
+//   gjsify install                    → project install (native, reads pkg.json)
+//   gjsify install <pkg> [<pkg>...]   → add package(s) to project (native)
 //   gjsify install -g <pkg> [...]     → user-global install (XDG, GJS-runnable bin)
 //
-// Project mode delegates to `npm install` in cwd and runs `runMinimalChecks()`
-// + `detectNativePackages()` to surface missing system deps and `@gjsify/*`
-// packages with native prebuilds.
+// 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).
 //
-// Global mode is the GJS equivalent of `npm i -g`: extracts the package tree
-// into `${XDG_DATA_HOME}/gjsify/global/node_modules/<pkg>/` via the native
-// install backend (no Node/npm required at runtime), then symlinks the bins
-// declared by `gjsify.bin` (preferred) or `bin` (fallback) into
-// `~/.local/bin/`. Subsequent commands invoked by name resolve to the
-// extracted package, so package-relative assets like `@ts-for-gir/cli`'s
-// `dist-templates/` are found by ordinary `__dirname/..` resolution — no
-// embedded asset stores, no separate release tarballs.
+// Workspace-aware install (`gjsify install` in a monorepo root with a
+// `"workspaces"` field) is Phase D.3 — for now we detect and surface a
+// clear error pointing at the in-progress work.
+import { existsSync, lstatSync, mkdirSync, rmSync, symlinkSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
 import { spawn } from 'node:child_process';
-import { mkdirSync } from 'node:fs';
+import { discoverWorkspaces } from '@gjsify/workspace';
 import { buildInstallCommand, detectPackageManager, runMinimalChecks, } from '../utils/check-system-deps.js';
 import { detectNativePackages } from '../utils/detect-native-packages.js';
 import { installPackages } from '../utils/install-backend.js';
 import { binDirOnPath, defaultGlobalLayout, linkGlobalBins, specToPackageName, } from '../utils/install-global.js';
+import { addDependencyEntry, defaultRangeFromVersion, parseSpec, projectSpecsFromPackageJson, readPackageJson, writePackageJson, } from '../utils/pkg-json-edit.js';
 export const installCommand = {
     command: 'install [packages..]',
     description: 'Install npm dependencies in the current project (or globally with -g), then run gjsify-aware post-checks.',
@@ -41,12 +41,31 @@ export const installCommand = {
         .option('save-dev', { type: 'boolean', alias: 'D' })
         .option('save-peer', { type: 'boolean' })
         .option('save-optional', { type: 'boolean', alias: 'O' })
+        .option('immutable', {
+        description: 'CI mode: install strictly from gjsify-lock.json, fail if the lockfile is missing or stale. Equivalent to yarn --immutable / npm ci --frozen-lockfile.',
+        type: 'boolean',
+        default: false,
+    })
         .option('verbose', {
         description: 'Verbose install logging.',
         type: 'boolean',
         default: false,
     }),
     handler: async (args) => {
+        // --immutable is incompatible with explicit `<pkg>` adds and with
+        // `--global` (which has no lockfile concept). Matches yarn's
+        // behavior: `yarn add --immutable` is a hard error.
+        if (args.immutable) {
+            if (args.packages && args.packages.length > 0) {
+                console.error('gjsify install --immutable does not accept package arguments. ' +
+                    'Remove the package names or drop --immutable.');
+                process.exit(1);
+            }
+            if (args.global) {
+                console.error('gjsify install --immutable is incompatible with --global.');
+                process.exit(1);
+            }
+        }
         if (args.global) {
             if (!args.packages || args.packages.length === 0) {
                 console.error('gjsify install --global requires at least one <pkg> argument.');
@@ -60,22 +79,199 @@ export const installCommand = {
             await installGlobalAndLink(args.packages, { verbose: args.verbose });
             return;
         }
-        const npmArgs = ['install'];
-        if (args['save-dev'])
-            npmArgs.push('--save-dev');
-        if (args['save-peer'])
-            npmArgs.push('--save-peer');
-        if (args['save-optional'])
-            npmArgs.push('--save-optional');
-        if (args.verbose)
-            npmArgs.push('--loglevel', 'verbose');
-        if (args.packages && args.packages.length > 0) {
-            npmArgs.push(...args.packages);
+        // Escape-hatch: legacy npm subprocess flow.
+        if (process.env.GJSIFY_INSTALL_BACKEND === 'npm') {
+            await projectInstallViaNpm(args);
+            await runPostInstallChecks();
+            return;
         }
-        await spawnNpm(npmArgs);
+        await projectInstallNative(args);
         await runPostInstallChecks();
     },
 };
+function isWorkspaceRoot(cwd) {
+    const pkgPath = join(cwd, 'package.json');
+    const pkg = readPackageJson(pkgPath);
+    if (!pkg)
+        return false;
+    return pkg.workspaces !== undefined;
+}
+function depKindFromArgs(args) {
+    if (args['save-dev'])
+        return 'devDependencies';
+    if (args['save-peer'])
+        return 'peerDependencies';
+    if (args['save-optional'])
+        return 'optionalDependencies';
+    return 'dependencies';
+}
+async function projectInstallNative(args) {
+    const cwd = process.cwd();
+    const pkgPath = join(cwd, 'package.json');
+    // Yarn-Berry / PnP detection: fall back to yarn with a clear warning
+    // rather than producing a half-working node_modules tree.
+    if (existsSync(join(cwd, '.pnp.cjs')) || existsSync(join(cwd, '.pnp.loader.mjs'))) {
+        throw new Error('gjsify install: detected Yarn PnP (.pnp.cjs) — native install is ' +
+            'not PnP-aware yet. Use `yarn install` or set ' +
+            'GJSIFY_INSTALL_BACKEND=npm.');
+    }
+    // Workspace install (no args, root pkg.json has `workspaces`) — Phase D.3.
+    // Project-local `gjsify install <pkg>` inside a workspace child still
+    // goes through the single-package code path below (this branch only
+    // fires for the root no-args case, which is the `yarn install`
+    // equivalent).
+    if ((!args.packages || args.packages.length === 0) && isWorkspaceRoot(cwd)) {
+        await workspaceInstall(cwd, args);
+        return;
+    }
+    let specs;
+    const pkg = readPackageJson(pkgPath);
+    const existingSpecs = pkg ? projectSpecsFromPackageJson(pkg) : [];
+    if (args.packages && args.packages.length > 0) {
+        // Combine new specs with existing manifest deps so a single
+        // `gjsify install <new>` doesn't churn the lockfile (would drop
+        // every previously-pinned entry otherwise). New specs with the
+        // same name as an existing dep override.
+        const newNames = new Set(args.packages.map((s) => parseSpec(s).name));
+        const carryover = existingSpecs.filter((s) => !newNames.has(parseSpec(s).name));
+        specs = [...carryover, ...args.packages];
+    }
+    else {
+        if (!pkg) {
+            throw new Error(`gjsify install: no package.json in ${cwd}`);
+        }
+        specs = existingSpecs;
+        if (specs.length === 0) {
+            console.log('gjsify install: no dependencies declared in package.json — nothing to do.');
+            return;
+        }
+    }
+    mkdirSync(cwd, { recursive: true });
+    const result = await installPackages({
+        prefix: cwd,
+        specs,
+        verbose: args.verbose,
+        // --immutable consumes the lockfile verbatim and must NOT rewrite
+        // it (the whole point is byte-stability under CI).
+        lockfile: !args.immutable,
+        frozen: args.immutable,
+    });
+    // Update package.json only when the user passed explicit packages
+    // (the `gjsify install <pkg>...` add-a-dep flow). The no-args refresh
+    // flow doesn't mutate manifest entries.
+    if (args.packages && args.packages.length > 0 && pkg) {
+        const kind = depKindFromArgs(args);
+        for (const spec of args.packages) {
+            const { name, range } = parseSpec(spec);
+            const installed = result.installed.find((r) => r.name === name);
+            const finalRange = range ?? (installed ? defaultRangeFromVersion(installed.version) : 'latest');
+            addDependencyEntry(pkg, name, finalRange, kind);
+        }
+        writePackageJson(pkgPath, pkg);
+    }
+}
+/**
+ * Phase D.3 — workspace-aware install. Mirrors what `yarn install` does
+ * at a monorepo root:
+ *   1. Discover every workspace under the root.
+ *   2. Aggregate the union of their external (non-`workspace:`) deps.
+ *   3. Run the native install backend ONCE at the root prefix so all
+ *      externals land in a single `node_modules/` (poor-man's hoisting —
+ *      we don't deduplicate version-range conflicts yet, the BFS resolver
+ *      picks first-match).
+ *   4. For every `workspace:` reference, symlink the target workspace's
+ *      directory into the requesting workspace's `node_modules/<dep>`
+ *      so `import '@gjsify/utils'` resolves to the local source.
+ *
+ * Hoisting strategy is intentionally minimal — D.3 ships the working
+ * baseline; per-workspace dedup + nested `node_modules/` for version
+ * conflicts are tracked as a follow-up in STATUS.md "Open TODOs".
+ */
+async function workspaceInstall(cwd, args) {
+    const workspaces = discoverWorkspaces(cwd, { includeRoot: true });
+    if (workspaces.length === 0) {
+        throw new Error(`gjsify install: ${cwd} has a "workspaces" field but no workspaces were discovered`);
+    }
+    const byName = new Map(workspaces.map((w) => [w.name, w]));
+    const externalSpecs = new Set();
+    const symlinks = [];
+    for (const ws of workspaces) {
+        const m = ws.manifest;
+        for (const kind of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+            const block = m[kind];
+            if (!block)
+                continue;
+            for (const [depName, spec] of Object.entries(block)) {
+                if (typeof spec !== 'string')
+                    continue;
+                if (spec.startsWith('workspace:')) {
+                    const target = byName.get(depName);
+                    if (!target) {
+                        throw new Error(`gjsify install: ${ws.name} declares "${depName}: ${spec}" but ` +
+                            `no workspace with that name exists`);
+                    }
+                    symlinks.push({ fromWorkspaceName: ws.name, depName, targetLocation: target.location });
+                    continue;
+                }
+                if (/^(link|file|portal|git\+|https?):/.test(spec))
+                    continue;
+                externalSpecs.add(`${depName}@${spec}`);
+            }
+        }
+    }
+    console.log(`gjsify install: ${workspaces.length} workspace(s), ${externalSpecs.size} external dep spec(s), ${symlinks.length} workspace symlink(s)`);
+    if (externalSpecs.size > 0) {
+        await installPackages({
+            prefix: cwd,
+            specs: [...externalSpecs],
+            verbose: args.verbose,
+            lockfile: !args.immutable,
+            frozen: args.immutable,
+        });
+    }
+    else if (args.verbose) {
+        console.log('gjsify install: no external deps to fetch');
+    }
+    for (const link of symlinks) {
+        const target = byName.get(link.fromWorkspaceName);
+        if (!target)
+            continue;
+        const linkPath = join(target.location, 'node_modules', link.depName);
+        mkdirSync(dirname(linkPath), { recursive: true });
+        // Remove any prior entry (regular dir, broken symlink, file).
+        try {
+            const stat = lstatSync(linkPath);
+            if (stat.isSymbolicLink() || stat.isFile()) {
+                rmSync(linkPath, { force: true });
+            }
+            else if (stat.isDirectory()) {
+                rmSync(linkPath, { recursive: true, force: true });
+            }
+        }
+        catch { /* ENOENT — fine, nothing to remove */ }
+        // Relative symlink so the repo is portable across checkout paths.
+        const relTarget = relative(dirname(linkPath), link.targetLocation);
+        symlinkSync(relTarget, linkPath);
+    }
+    if (symlinks.length > 0) {
+        console.log(`gjsify install: wired ${symlinks.length} workspace symlink(s)`);
+    }
+}
+async function projectInstallViaNpm(args) {
+    const npmArgs = ['install'];
+    if (args['save-dev'])
+        npmArgs.push('--save-dev');
+    if (args['save-peer'])
+        npmArgs.push('--save-peer');
+    if (args['save-optional'])
+        npmArgs.push('--save-optional');
+    if (args.verbose)
+        npmArgs.push('--loglevel', 'verbose');
+    if (args.packages && args.packages.length > 0) {
+        npmArgs.push(...args.packages);
+    }
+    await spawnNpm(npmArgs);
+}
 async function spawnNpm(npmArgs) {
     return new Promise((resolve, reject) => {
         const child = spawn('npm', npmArgs, { stdio: 'inherit' });

package/lib/commands/run.d.ts

@@ -1,6 +1,6 @@
 import type { Command } from '../types/index.js';
 interface RunOptions {
-    file: string;
+    target: string;
     args: string[];
 }
 export declare const runCommand: Command<any, RunOptions>;