@gjsify/cli 0.56.0 → 0.57.0

package/lib/commands/flatpak/sources.d.ts

@@ -6,6 +6,19 @@ interface FlatpakSourcesOptions {
     out?: string;
     cacheRoot?: string;
     printModule?: boolean;
+    focus?: string[];
 }
+/** One vendored tarball: its download URL + its SRI integrity (`sha512-…`). */
+interface Tarball {
+    url: string;
+    integrity: string;
+}
+/**
+ * `--focus` (ADR 0102): the tarballs the focused workspace closure installs. The same
+ * `planFocus` + `reachableInstallPaths` pair `gjsify install --focus` uses, so the
+ * Flatpak cache holds exactly what the offline install reads. Workspace-named
+ * packages are dropped as the installer drops them (they are symlinks, not fetches).
+ */
+export declare function focusedTarballs(lockfile: string, focus: string[]): Tarball[];
 export declare const flatpakSourcesCommand: Command<unknown, FlatpakSourcesOptions>;
 export {};

package/lib/commands/flatpak/sources.js

@@ -19,6 +19,9 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { Buffer } from 'node:buffer';
+import { discoverWorkspaces } from '@gjsify/workspace';
+import { planFocus } from '../../utils/install-focus.js';
+import { parseSpecName, readLockfileNodes, reachableInstallPaths } from '../../utils/install-backend-native.js';
 import { FLATPAK_SOURCES_FILE } from './utils.js';
 /** Checksum algorithms flatpak-builder accepts on a `file` source. */
 const FLATPAK_ALGOS = new Set(['sha256', 'sha512']);
@@ -187,6 +190,25 @@ function defaultLockfile(cwd) {
     }
     return 'gjsify-lock.json'; // surfaces a clear "not found" later
 }
+/**
+ * `--focus` (ADR 0102): the tarballs the focused workspace closure installs. The same
+ * `planFocus` + `reachableInstallPaths` pair `gjsify install --focus` uses, so the
+ * Flatpak cache holds exactly what the offline install reads. Workspace-named
+ * packages are dropped as the installer drops them (they are symlinks, not fetches).
+ */
+export function focusedTarballs(lockfile, focus) {
+    const root = dirname(lockfile);
+    const workspaces = discoverWorkspaces(root, { includeRoot: true });
+    const plan = planFocus(workspaces, focus, 'gjsify flatpak sources');
+    const nodes = readLockfileNodes(lockfile);
+    if (!nodes)
+        throw new Error(`gjsify flatpak sources: ${lockfile} is not a readable gjsify-lock.json.`);
+    const reachable = reachableInstallPaths(nodes, plan.specs.map(parseSpecName));
+    const workspaceNames = new Set(workspaces.map((w) => w.name));
+    return nodes
+        .filter((n) => reachable.has(n.installPath) && !workspaceNames.has(n.name))
+        .flatMap((n) => (n.tarballUrl && n.integrity ? [{ url: n.tarballUrl, integrity: n.integrity }] : []));
+}
 function parseLockfile(path, type) {
     const text = readFileSync(path, 'utf-8');
     if (type === 'yarn')
@@ -228,6 +250,11 @@ export const flatpakSourcesCommand = {
                 'Tarballs land at <cache-root>/gjsify/tarballs/v1/<algo>/<shard>/<hex>.tgz.',
             type: 'string',
             default: 'flatpak-gjsify-cache',
+        })
+            .option('focus', {
+            description: 'Only the tarballs the named workspaces (package names), the workspaces they depend on, and their external dependencies need, as `gjsify install --focus` installs them. gjsify-lock.json only.',
+            type: 'string',
+            array: true,
         })
             .option('print-module', {
             description: 'Also print a ready-to-paste flatpak manifest module snippet to stderr',
@@ -243,7 +270,12 @@ export const flatpakSourcesCommand = {
                 'Run `gjsify install` (or npm/yarn/pnpm) first, or pass --lockfile.');
         }
         const type = args.type ?? detectType(lockfile);
-        const tarballs = parseLockfile(lockfile, type);
+        const focus = args.focus;
+        if (focus && focus.length > 0 && type !== 'gjsify') {
+            throw new Error(`gjsify flatpak sources: --focus reads the per-package edges of gjsify-lock.json; ` +
+                `${type} lockfiles are not supported with it.`);
+        }
+        const tarballs = focus && focus.length > 0 ? focusedTarballs(lockfile, focus) : parseLockfile(lockfile, type);
         const cacheRoot = args.cacheRoot ?? 'flatpak-gjsify-cache';
         // Dedupe by content hash — the same tarball is locked at many install
         // paths; flatpak rejects duplicate dest/filename pairs.

package/lib/commands/install.d.ts

@@ -9,6 +9,7 @@ interface InstallOptions {
     immutable?: boolean;
     prune?: boolean;
     'refresh-lockfile'?: boolean;
+    focus?: string[];
     verbose: boolean;
     quiet?: boolean;
     progress?: boolean;

package/lib/commands/install.js

@@ -31,6 +31,7 @@ import { acquireInstallLock } from '../utils/install-lock.js';
 import { nodeBinary } from '../utils/run-node.js';
 import { spawnToCompletion } from '../utils/spawn.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
+import { planFocus } from '../utils/install-focus.js';
 import { binDirOnPath, BUNDLER_ENGINE_PACKAGE, defaultGlobalLayout, hasBundlerEngineInstalled, installGjsEnginePackages, linkGlobalBins, specToPackageName, } from '../utils/install-global.js';
 import { resolveHostPlatform } from '../utils/platform-check.js';
 import { pruneAfterInstall } from '../utils/prune-prefix.js';
@@ -86,6 +87,11 @@ export const installCommand = {
         description: 'Re-resolve every dependency to the newest version satisfying its range and rewrite the lockfile (bumps in-range transitive deps). Without it, a resolve preserves versions already pinned in the lockfile and only resolves new/changed deps — the npm/yarn/pnpm default. Mirrors yarn install --mode=update-lockfile.',
         type: 'boolean',
         default: false,
+    })
+        .option('focus', {
+        description: 'Install only the named workspaces (package names), the workspaces they depend on, and their external dependencies, as if they were the only members of the monorepo (yarn workspaces focus). Reads gjsify-lock.json and never rewrites it; fails if it is missing or stale. Workspace projects only.',
+        type: 'string',
+        array: true,
     })
         .option('verbose', {
         description: 'Verbose install logging.',
@@ -665,6 +671,10 @@ async function workspaceInstallLocked(cwd, args, signal) {
         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]));
+    // `--focus`: the members that are installed. The lockfile and its drift check
+    // still cover EVERY member (ADR 0102 § 2), so `externalSpecs` below stays the full set.
+    const focusPlan = args.focus && args.focus.length > 0 ? planFocus(workspaces, args.focus, 'gjsify install') : undefined;
+    const active = focusPlan ? new Set(focusPlan.workspaces) : undefined;
     const externalSpecs = new Set();
     // `"<name>@<range>"` → the members that declared it. Feeds the resolver's
     // version-conflict warning so it can attribute both sides of a conflict.
@@ -691,6 +701,8 @@ async function workspaceInstallLocked(cwd, args, signal) {
                     // Only an EXPLICIT out-of-workspace protocol opts out.
                     const explicitOverride = /^(link|file|portal|git\+|https?):/.test(spec);
                     if (!explicitOverride) {
+                        if (active && !active.has(ws))
+                            continue;
                         symlinks.push({
                             fromWorkspaceName: ws.name,
                             depName,
@@ -729,7 +741,7 @@ async function workspaceInstallLocked(cwd, args, signal) {
     // the workspace without its runner shim (`node_modules/.bin/gjsify`), and a
     // stale shim is refreshed even when a later phase aborts. Rewritten at the end
     // of this function so the GJS preamble reflects the installed tree.
-    writeWorkspaceBinShims(cwd, workspaces);
+    writeWorkspaceBinShims(cwd, focusPlan?.workspaces ?? workspaces);
     // Per-requester links (`<requester>/node_modules/<dep>`) plus a root hoist of
     // every workspace into `node_modules/<name>`, so transitive workspace deps
     // resolve by Node's parent-walk from any descendant. Idempotent, hence callable
@@ -793,7 +805,7 @@ async function workspaceInstallLocked(cwd, args, signal) {
         // runtime with `Module not found`.
         const rootBinDir = join(cwd, 'node_modules');
         let rootHoisted = 0;
-        for (const ws of workspaces) {
+        for (const ws of focusPlan?.workspaces ?? workspaces) {
             // The root workspace cannot symlink itself into its own node_modules.
             if (ws.location === cwd)
                 continue;
@@ -843,7 +855,7 @@ async function workspaceInstallLocked(cwd, args, signal) {
     const wsLocalSpecs = new Map(); // wsLocation → name@range set
     const droppedFromExternal = new Set();
     if (extracted && extracted.scoped.size > 0) {
-        for (const ws of workspaces) {
+        for (const ws of focusPlan?.workspaces ?? workspaces) {
             const wsManifest = ws.manifest;
             for (const kind of ['dependencies', 'devDependencies', 'optionalDependencies']) {
                 const deps = wsManifest[kind];
@@ -914,6 +926,7 @@ async function workspaceInstallLocked(cwd, args, signal) {
             // Aggregated over EVERY member, because the specs are: a name any member
             // declares as a plain dependency stays required.
             optionalSpecs: optionalDependencyNames(workspaces.map((w) => w.manifest)),
+            focusSpecs: focusPlan?.specs,
         };
         await installPackages(rootOpts);
     }
@@ -955,7 +968,7 @@ async function workspaceInstallLocked(cwd, args, signal) {
     // fresh checkout `detectNativePackages` finds nothing before extraction).
     // Running last also keeps workspace shims authoritative over any same-named
     // external bin the backend linked — yarn semantics: workspace bins win.
-    const wsBinsCreated = writeWorkspaceBinShims(cwd, workspaces);
+    const wsBinsCreated = writeWorkspaceBinShims(cwd, focusPlan?.workspaces ?? workspaces);
     if (wsBinsCreated > 0) {
         console.log(`gjsify install: linked ${wsBinsCreated} workspace bin(s) into node_modules/.bin/`);
     }

package/lib/utils/install-backend-native.d.ts

@@ -108,6 +108,17 @@ export interface NativeInstallOptions extends InstallOptions {
      * been written from the full resolved tree.
      */
     linkedNames?: Set<string>;
+    /**
+     * `--focus` (ADR 0102): the external `"<name>@<range>"` specs of the focused
+     * workspace closure. Only the packages reachable from these are fetched and
+     * extracted. `specs` stays the FULL set, because the drift check compares it
+     * against the lockfile's `requested` and the lockfile stays complete.
+     *
+     * Implies a lockfile-authoritative install: a missing or stale lockfile throws
+     * instead of resolving (a resolve would reach the toolchains the focus excludes),
+     * and nothing is ever written back, so the file cannot become a subset.
+     */
+    focusSpecs?: string[];
 }
 export declare function installPackagesNative(opts: NativeInstallOptions): Promise<InstalledTopLevel[]>;
 /**
@@ -144,6 +155,7 @@ export declare function applyPlatformFilter(nodes: ResolvedNode[], target: Platf
  * Pure detection — no script is run, so node-free-ness is preserved.
  */
 export declare function warnMissingNativeBuilds(nodes: ResolvedNode[], prefix: string, log: Logger): void;
+export declare function parseSpecName(spec: string): string;
 /**
  * A node's REQUIRED dependency edges: its `dependencies` minus every name its
  * `optionalDependencies` also lists. The ONE place that decides an edge's kind —
@@ -209,6 +221,21 @@ export declare function requiredPeerEntries(node: Pick<ResolvedNode, 'dependenci
  * composition, worth pinning without a registry.
  */
 export declare function computeOptionalFlags(nodes: ResolvedNode[], requiredNames: Set<string>, log: Logger): void;
+/**
+ * The `installPath`s reachable from the top-level packages named in `seedNames`, through
+ * `dependencies`, `optionalDependencies` and REQUIRED peers — what `--focus` (ADR 0102)
+ * keeps. Optional edges are followed on purpose: whether one installs is a per-host
+ * verdict (`applyPlatformFilter`), and a closure that left them out would depend on the
+ * host that computed it. An optional peer is not an edge, as the resolver never places it.
+ *
+ * Same walk as {@link computeOptionalFlags} — seeds are exact because a top-level spec
+ * always takes the root slot, and an edge resolves through {@link findVisible} the way
+ * the requester will at runtime. A seed with no placement is a workspace member (its
+ * symlink is wired elsewhere) or a name absent from the lockfile; both are skipped.
+ */
+export declare function reachableInstallPaths(nodes: readonly ResolvedNode[], seedNames: Iterable<string>): Set<string>;
+/** The nodes the lockfile at `lockfilePath` describes, or null when it is missing or unreadable. */
+export declare function readLockfileNodes(lockfilePath: string): ResolvedNode[] | null;
 export declare function parseSpec(raw: string): ParsedSpec;
 export declare function pickVersion(packument: Packument, range: string, preferred?: string): string | null;
 /**

package/lib/utils/install-backend-native.js

@@ -157,20 +157,23 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
      * resolve nothing.
      */
     let skippedEdges = new Set();
-    if (opts.frozen) {
+    if (opts.frozen || opts.focusSpecs) {
         // --immutable / --frozen: the lockfile is authoritative. Reject a missing,
         // version-mismatched or drifted file — silently honouring a stale lockfile
-        // masks the real dep churn `--immutable` exists to catch.
+        // masks the real dep churn `--immutable` exists to catch. `--focus` is the
+        // same promise without the tree check: it reads the lockfile, never resolves.
+        const flag = opts.frozen ? '--immutable' : '--focus';
+        const retry = opts.frozen ? '(without --immutable)' : '(without --focus)';
         if (!existingLock) {
-            throw new Error(`install: --immutable requires ${LOCKFILE_NAME} at ${opts.prefix} — none found. ` +
-                `Run \`gjsify install\` (without --immutable) to generate one and commit it.`);
+            throw new Error(`install: ${flag} requires ${LOCKFILE_NAME} at ${opts.prefix} — none found. ` +
+                `Run \`gjsify install\` ${retry} to generate one and commit it.`);
         }
         const drift = describeLockfileDrift(existingLock, opts.specs);
         if (drift) {
-            throw new Error(`install: --immutable but ${lockfilePath} is stale.\n${drift}\n` +
-                `Re-run \`gjsify install\` (without --immutable) to refresh the lockfile.`);
+            throw new Error(`install: ${flag} but ${lockfilePath} is stale.\n${drift}\n` +
+                `Re-run \`gjsify install\` ${retry} to refresh the lockfile.`);
         }
-        log('install: --immutable, using lockfile (%d package(s))', Object.keys(existingLock.packages).length);
+        log('install: %s, using lockfile (%d package(s))', flag, Object.keys(existingLock.packages).length);
         nodes = lockfileToNodes(existingLock);
         // ...and the tree must hold NOTHING ELSE. The installer only adds, so without
         // this an undescribed package survives the install and exits 0 — the CI cache
@@ -178,8 +181,17 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
         // Before the download so a wrong tree costs seconds, not the extract phase,
         // and with the FULL lockfile set: the workspace filter below removes nodes
         // that ARE described, and judging against the smaller set would call them
-        // strangers.
-        assertNoExtraneous(opts.prefix, nodes);
+        // strangers. `--focus` alone skips it: a tree an earlier full install left is
+        // not extraneous, and nothing here promises the tree matches the lockfile.
+        if (opts.frozen)
+            assertNoExtraneous(opts.prefix, nodes);
+        // The focus narrows AFTER the extraneous check, which judges the full set, and
+        // before the optional-flag fixpoint, which must see only what will be installed.
+        if (opts.focusSpecs) {
+            const reachable = reachableInstallPaths(nodes, opts.focusSpecs.map(parseSpecName));
+            log('install: --focus keeps %d of %d lockfile package(s)', reachable.size, nodes.length);
+            nodes = nodes.filter((n) => reachable.has(n.installPath));
+        }
     }
     else if (!opts.refreshLockfile &&
         existingLock &&
@@ -228,7 +240,7 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
     // before `writeLockfile` (so the persisted flag is final), before the platform
     // verdict (which reads it for fatal vs. inert), and before the workspace filter
     // below (which removes nodes and would truncate the walk).
-    computeOptionalFlags(nodes, requiredTopLevelNames(opts.specs, opts.optionalSpecs), log);
+    computeOptionalFlags(nodes, requiredTopLevelNames(opts.focusSpecs ?? opts.specs, opts.optionalSpecs), log);
     assertRequiredEdgesResolved(nodes, skippedEdges);
     if (resolved && opts.lockfile) {
         // The FULL resolved set, inert nodes included — see the header note:
@@ -440,7 +452,7 @@ function topLevelResolutions(specs, nodes) {
     }
     return out;
 }
-function parseSpecName(spec) {
+export function parseSpecName(spec) {
     if (spec.startsWith('@')) {
         const slash = spec.indexOf('/');
         if (slash === -1)
@@ -957,6 +969,48 @@ export function computeOptionalFlags(nodes, requiredNames, log) {
     }
     log('install: optionality fixpoint — %d of %d node(s) reachable only via optional edges%s', nodes.length - required.size, nodes.length, corrected > 0 ? `; corrected ${corrected} incoming flag(s)` : '');
 }
+/**
+ * The `installPath`s reachable from the top-level packages named in `seedNames`, through
+ * `dependencies`, `optionalDependencies` and REQUIRED peers — what `--focus` (ADR 0102)
+ * keeps. Optional edges are followed on purpose: whether one installs is a per-host
+ * verdict (`applyPlatformFilter`), and a closure that left them out would depend on the
+ * host that computed it. An optional peer is not an edge, as the resolver never places it.
+ *
+ * Same walk as {@link computeOptionalFlags} — seeds are exact because a top-level spec
+ * always takes the root slot, and an edge resolves through {@link findVisible} the way
+ * the requester will at runtime. A seed with no placement is a workspace member (its
+ * symlink is wired elsewhere) or a name absent from the lockfile; both are skipped.
+ */
+export function reachableInstallPaths(nodes, seedNames) {
+    const byPath = new Map();
+    for (const node of nodes)
+        byPath.set(node.installPath, node);
+    const reached = new Set();
+    const worklist = [];
+    const enter = (node) => {
+        if (!node || reached.has(node.installPath))
+            return;
+        reached.add(node.installPath);
+        worklist.push(node);
+    };
+    for (const name of seedNames)
+        enter(byPath.get(`node_modules/${name}`));
+    for (let node = worklist.pop(); node; node = worklist.pop()) {
+        const edges = [
+            ...Object.keys(node.dependencies),
+            ...Object.keys(node.optionalDependencies),
+            ...requiredPeerEntries(node).map(([name]) => name),
+        ];
+        for (const name of edges)
+            enter(findVisible(node.installPath, name, byPath));
+    }
+    return reached;
+}
+/** The nodes the lockfile at `lockfilePath` describes, or null when it is missing or unreadable. */
+export function readLockfileNodes(lockfilePath) {
+    const lock = readLockfile(lockfilePath);
+    return lock ? lockfileToNodes(lock) : null;
+}
 /**
  * Re-judge every failure the resolve swallowed against the FIXPOINT flags, and throw
  * if one turned out to be required after all.

package/lib/utils/install-focus.d.ts

@@ -0,0 +1,41 @@
+import type { Workspace } from '@gjsify/workspace';
+/** The three blocks `gjsify install` reads from a member; same list as install.ts. */
+export declare const DEPENDENCY_BLOCKS: readonly ["dependencies", "devDependencies", "optionalDependencies"];
+export type DependencyClass = {
+    kind: 'workspace';
+    target: Workspace;
+}
+/** `workspace:` against a name that is not a member: a typo or a missing package. */
+ | {
+    kind: 'missing-workspace';
+}
+/** `link:`/`file:`/`portal:`/`git+`/`http(s):` — neither linked nor fetched. */
+ | {
+    kind: 'ignored';
+} | {
+    kind: 'external';
+};
+/**
+ * What a `name: spec` entry of a member's manifest is. A name that matches a member is
+ * the member whatever the spec form (`workspace:`, `^1.2.3`, a dist-tag) — only an
+ * explicit out-of-workspace protocol opts out — because routing it to the registry would
+ * unpack a published tarball over the member's own source tree.
+ */
+export declare function classifyDependency(depName: string, spec: string, byName: ReadonlyMap<string, Workspace>): DependencyClass;
+export interface FocusPlan {
+    /** The closure, in discovery order: the named workspaces and everything they depend on. */
+    workspaces: Workspace[];
+    /** `"<name>@<range>"` of every external dependency the closure's manifests declare. */
+    specs: string[];
+}
+/**
+ * Resolve `--focus` names to the workspace closure and its external specs.
+ *
+ * Throws naming every unknown workspace — a typo must not become an install of
+ * nothing. Names are exact package names, the spelling the rest of the CLI uses; the
+ * root is a member like any other (Yarn's `workspaces focus` rule) and is in the
+ * closure only when named or depended on. A root without a `name` cannot be named.
+ *
+ * @param command label for error messages, e.g. `gjsify install`.
+ */
+export declare function planFocus(workspaces: readonly Workspace[], focus: readonly string[], command: string): FocusPlan;

package/lib/utils/install-focus.js

@@ -0,0 +1,80 @@
+// `--focus <workspace…>` for `gjsify install` and `gjsify flatpak sources`
+// (ADR 0102): act on the named workspaces, the workspaces they depend on, and the
+// external packages those need — as if they were the only members of the monorepo.
+//
+// THE MANIFEST HALF lives here; the LOCKFILE HALF (`reachableInstallPaths`) lives in
+// `install-backend-native.ts` beside `computeOptionalFlags`, because it reads the same
+// graph through the same private helpers. `gjsify-lock.json` records package → package
+// edges but no workspace → package edges, so the seeds of the walk come from the
+// manifests (on disk wherever either command runs) and the lockfile only continues it.
+//
+// ONE classifier decides what a dependency IS, and `workspaceInstallLocked` uses the
+// same one for the full install. The closure and the install cannot disagree about
+// whether `@scope/foo: ^1.0.0` is a workspace edge or a registry package, and that
+// agreement is what lets `flatpak sources --focus` fill exactly the cache the focused
+// install later reads. `@gjsify/workspace`'s `buildDependencyGraph` is deliberately not
+// used: it decides by "does the member's version satisfy the range", this installer by
+// NAME (a name-matched member is always symlinked — install.ts, `localWorkspace`).
+/** The three blocks `gjsify install` reads from a member; same list as install.ts. */
+export const DEPENDENCY_BLOCKS = ['dependencies', 'devDependencies', 'optionalDependencies'];
+/** Protocols that opt a dependency out of both the workspace link and the registry. */
+const EXPLICIT_PROTOCOL = /^(link|file|portal|git\+|https?):/;
+/**
+ * What a `name: spec` entry of a member's manifest is. A name that matches a member is
+ * the member whatever the spec form (`workspace:`, `^1.2.3`, a dist-tag) — only an
+ * explicit out-of-workspace protocol opts out — because routing it to the registry would
+ * unpack a published tarball over the member's own source tree.
+ */
+export function classifyDependency(depName, spec, byName) {
+    const target = byName.get(depName);
+    if (target && !EXPLICIT_PROTOCOL.test(spec))
+        return { kind: 'workspace', target };
+    if (spec.startsWith('workspace:'))
+        return { kind: 'missing-workspace' };
+    if (EXPLICIT_PROTOCOL.test(spec))
+        return { kind: 'ignored' };
+    return { kind: 'external' };
+}
+/** At most this many known names are listed in the unknown-name error. */
+const KNOWN_NAMES_SHOWN = 20;
+/**
+ * Resolve `--focus` names to the workspace closure and its external specs.
+ *
+ * Throws naming every unknown workspace — a typo must not become an install of
+ * nothing. Names are exact package names, the spelling the rest of the CLI uses; the
+ * root is a member like any other (Yarn's `workspaces focus` rule) and is in the
+ * closure only when named or depended on. A root without a `name` cannot be named.
+ *
+ * @param command label for error messages, e.g. `gjsify install`.
+ */
+export function planFocus(workspaces, focus, command) {
+    const byName = new Map(workspaces.map((w) => [w.name, w]));
+    const unknown = [...new Set(focus)].filter((name) => !byName.has(name));
+    if (unknown.length > 0) {
+        const known = [...byName.keys()].sort();
+        const shown = known.slice(0, KNOWN_NAMES_SHOWN).join(', ');
+        const more = known.length > KNOWN_NAMES_SHOWN ? `, … (${known.length - KNOWN_NAMES_SHOWN} more)` : '';
+        throw new Error(`${command}: --focus names unknown workspace(s): ${unknown.join(', ')}. ` +
+            `Pass a package name from a workspace's package.json. Known workspaces: ${shown}${more}.`);
+    }
+    // A Set grows while iterated, so each pass visits what the previous one added.
+    const closure = new Set(focus.map((name) => byName.get(name)));
+    const specs = new Set();
+    for (const ws of closure) {
+        for (const block of DEPENDENCY_BLOCKS) {
+            for (const [depName, spec] of Object.entries(ws.manifest[block] ?? {})) {
+                if (typeof spec !== 'string')
+                    continue;
+                const cls = classifyDependency(depName, spec, byName);
+                if (cls.kind === 'workspace')
+                    closure.add(cls.target);
+                else if (cls.kind === 'external')
+                    specs.add(`${depName}@${spec}`);
+            }
+        }
+    }
+    return {
+        workspaces: workspaces.filter((w) => closure.has(w)),
+        specs: [...specs],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.56.0",
+    "version": "0.57.0",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -142,22 +142,22 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/blueprint": "^0.56.0",
-        "@gjsify/buffer": "^0.56.0",
-        "@gjsify/create-app": "^0.56.0",
-        "@gjsify/node-globals": "^0.56.0",
-        "@gjsify/node-polyfills": "^0.56.0",
-        "@gjsify/npm-registry": "^0.56.0",
-        "@gjsify/resolve-npm": "^0.56.0",
-        "@gjsify/rolldown-plugin-gjsify": "^0.56.0",
-        "@gjsify/vite-plugin-blueprint": "^0.56.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.56.0",
-        "@gjsify/semver": "^0.56.0",
-        "@gjsify/tar": "^0.56.0",
-        "@gjsify/tsc": "^0.56.0",
-        "@gjsify/utils": "^0.56.0",
-        "@gjsify/web-polyfills": "^0.56.0",
-        "@gjsify/workspace": "^0.56.0",
+        "@gjsify/blueprint": "^0.57.0",
+        "@gjsify/buffer": "^0.57.0",
+        "@gjsify/create-app": "^0.57.0",
+        "@gjsify/node-globals": "^0.57.0",
+        "@gjsify/node-polyfills": "^0.57.0",
+        "@gjsify/npm-registry": "^0.57.0",
+        "@gjsify/resolve-npm": "^0.57.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.57.0",
+        "@gjsify/vite-plugin-blueprint": "^0.57.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.57.0",
+        "@gjsify/semver": "^0.57.0",
+        "@gjsify/tar": "^0.57.0",
+        "@gjsify/tsc": "^0.57.0",
+        "@gjsify/utils": "^0.57.0",
+        "@gjsify/web-polyfills": "^0.57.0",
+        "@gjsify/workspace": "^0.57.0",
         "acorn": "^8.17.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
@@ -166,13 +166,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.56.0",
+        "@gjsify/unit": "^0.57.0",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.56.0",
-        "@gjsify/rolldown-native": "^0.56.0"
+        "@gjsify/oxfmt-native": "^0.57.0",
+        "@gjsify/rolldown-native": "^0.57.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {