@gjsify/cli 0.39.0 → 0.40.0

package/lib/utils/app-metadata.js

@@ -0,0 +1,338 @@
+// AppStream MetaInfo XML + freedesktop `.desktop` rendering, shared by every
+// install format.
+//
+// These files describe the APPLICATION, not the container it ships in: a
+// `.deb`, an `.rpm`, a Flatpak and (later) a macOS bundle all want the same
+// `<name>`, `<summary>`, categories, keywords and icon name. They lived under
+// `commands/flatpak/` while Flatpak was the only packer; ADR 0024 § 8 moves
+// them out so `gjsify ship` reads them without importing another command.
+//
+// The MetaInfo XML is built line by line in TypeScript rather than substituted
+// into a template: the AppStream surface (description blocks, per-release rich
+// notes, translator hints, kudos, supports/requires/recommends, content_rating
+// attributes, provides) has too many optional nested sections for a
+// template+placeholder approach to stay legible. The `.desktop` entry stays
+// template-based — it is flat `key=value`.
+import { readFileSync } from 'node:fs';
+/**
+ * Lazy template loader. `static-read-inliner` matches this exact shape
+ * (`readFileSync(new URL(<literal>, import.meta.url), 'utf-8')`) and inlines
+ * the template into the GJS bundle at build time — a `join(__dirname, …)`
+ * spelling silently loses that and ENOENTs under GJS.
+ */
+function loadDesktopTemplate() {
+    return readFileSync(new URL('../templates/app/desktop.tmpl', import.meta.url), 'utf-8');
+}
+/**
+ * Validate that the metadata has the minimum set of fields AppStream needs.
+ * Returns the missing fields with actionable hints; an empty list means OK.
+ */
+export function validateAppMetadata(inputs) {
+    const m = inputs.metadata;
+    const key = inputs.configKey;
+    const missing = [];
+    if (!m.developer?.id || !m.developer?.name) {
+        missing.push({
+            field: `${key}.developer`,
+            hint: `Set \`${key}.developer = { "id": "io.github.you", "name": "Your Name" }\` in package.json. The id is reverse-DNS.`,
+        });
+    }
+    if (!m.summary) {
+        missing.push({
+            field: `${key}.summary`,
+            hint: 'One-line app summary, ≤80 chars, no trailing period. Example: "Learn 6502 assembly language".',
+        });
+    }
+    if (!m.description) {
+        missing.push({
+            field: `${key}.description`,
+            hint: 'Plain text (split on blank lines) or DescriptionBlock[] for rich content with bullet lists + translator hints.',
+        });
+    }
+    if (!m.license?.project) {
+        missing.push({
+            field: `${key}.license.project`,
+            hint: 'SPDX identifier of the project license, e.g. "MIT", "GPL-3.0-or-later".',
+        });
+    }
+    if (!m.homepageUrl) {
+        missing.push({
+            field: `${key}.homepageUrl`,
+            hint: 'Required by Flathub. Example: "https://github.com/you/your-repo".',
+        });
+    }
+    return missing;
+}
+/** Render the MetaInfo XML for a desktop application. */
+export function renderMetainfoApp(inputs) {
+    return renderMetainfo(inputs, 'desktop-application');
+}
+/** Render the MetaInfo XML for a console application. */
+export function renderMetainfoCli(inputs) {
+    return renderMetainfo(inputs, 'console-application');
+}
+/**
+ * Render the `.desktop` entry (app kind only).
+ *
+ * `Exec=` carries a field code when the app declares MIME types, because a
+ * desktop entry with `MimeType=` and no `%f`/`%u` is registered as a handler
+ * that is then launched with no argument — the file the user double-clicked is
+ * dropped on the floor, and `desktop-file-validate` says so. `x-scheme-handler/*`
+ * wins over file types: a URL handler must take `%u`.
+ */
+export function renderDesktopEntry(inputs) {
+    const m = inputs.metadata;
+    const categoriesLine = (m.categories ?? ['Utility']).join(';') + ';';
+    const keywordsLine = m.keywords?.length ? `Keywords=${m.keywords.join(';')};\n` : '';
+    // `MimeType=` is sourced from `<config>.provides.mimetypes` — the same field
+    // already populates `<mediatype>` entries in the MetaInfo XML, so callers
+    // configure both with one knob. Typical entries: `x-scheme-handler/<scheme>`
+    // for URL-scheme handlers, or `application/<mime>` for file-type handlers.
+    const mimetypes = m.provides?.mimetypes ?? [];
+    const mimetypesLine = mimetypes.length ? `MimeType=${mimetypes.join(';')};\n` : '';
+    return substitute(loadDesktopTemplate(), {
+        NAME: inputs.name,
+        SUMMARY: m.summary ?? inputs.name,
+        COMMAND: `${inputs.command}${execFieldCode(mimetypes)}`,
+        APP_ID: inputs.appId,
+        CATEGORIES_LINE: categoriesLine,
+        KEYWORDS_LINE: keywordsLine,
+        MIMETYPES_LINE: mimetypesLine,
+    });
+}
+/** The `Exec=` field code implied by the declared MIME types. */
+function execFieldCode(mimetypes) {
+    if (mimetypes.some((t) => t.startsWith('x-scheme-handler/')))
+        return ' %u';
+    if (mimetypes.length > 0)
+        return ' %f';
+    return '';
+}
+// ─── MetaInfo XML builder ────────────────────────────────────────────────
+function renderMetainfo(inputs, kind) {
+    const m = inputs.metadata;
+    const year = inputs.copyrightYear ?? new Date().getFullYear();
+    const developerName = m.developer?.name ?? '';
+    const lines = [];
+    lines.push('<?xml version="1.0" encoding="UTF-8"?>');
+    lines.push(`<!-- Copyright ${year} ${escapeXml(developerName)} -->`);
+    lines.push(`<component type="${kind}">`);
+    lines.push(`  <id>${escapeXml(inputs.appId)}</id>`);
+    lines.push(`  <metadata_license>${escapeXml(m.license?.metadata ?? 'CC0-1.0')}</metadata_license>`);
+    lines.push(`  <project_license>${escapeXml(m.license?.project ?? '')}</project_license>`);
+    lines.push(`  <name>${escapeXml(inputs.name)}</name>`);
+    pushTranslatorHint(lines, m.summaryTranslatorHint, '  ');
+    lines.push(`  <summary>${escapeXml(m.summary ?? inputs.name)}</summary>`);
+    if (m.iconRemote) {
+        lines.push(`  <icon type="remote">${escapeXml(m.iconRemote)}</icon>`);
+    }
+    // <description>
+    lines.push('  <description>');
+    for (const blockLine of renderDescriptionBlocks(m.description ?? '', '    ')) {
+        lines.push(blockLine);
+    }
+    lines.push('  </description>');
+    // <developer>
+    if (m.developer?.id && m.developer?.name) {
+        lines.push(`  <developer id="${escapeXml(m.developer.id)}">`);
+        const translateAttr = m.developer.nameTranslatable === true ? '' : ' translate="no"';
+        lines.push(`    <name${translateAttr}>${escapeXml(m.developer.name)}</name>`);
+        if (m.developer.email) {
+            lines.push(`    <email>${escapeXml(m.developer.email)}</email>`);
+        }
+        lines.push('  </developer>');
+    }
+    if (kind === 'desktop-application') {
+        lines.push(`  <launchable type="desktop-id">${escapeXml(inputs.appId)}.desktop</launchable>`);
+    }
+    // <screenshots>
+    if (m.screenshots?.length) {
+        lines.push('  <screenshots>');
+        m.screenshots.forEach((s, i) => {
+            const type = s.type ?? (i === 0 ? 'default' : undefined);
+            const typeAttr = type ? ` type="${escapeXml(type)}"` : '';
+            const envAttr = s.environment ? ` environment="${escapeXml(s.environment)}"` : '';
+            lines.push(`    <screenshot${typeAttr}${envAttr}>`);
+            lines.push(`      <image>${escapeXml(s.url)}</image>`);
+            if (s.caption) {
+                pushTranslatorHint(lines, s.captionTranslatorHint, '      ');
+                lines.push(`      <caption>${escapeXml(s.caption)}</caption>`);
+            }
+            lines.push('    </screenshot>');
+        });
+        lines.push('  </screenshots>');
+    }
+    // <url> entries
+    if (m.homepageUrl)
+        lines.push(`  <url type="homepage">${escapeXml(m.homepageUrl)}</url>`);
+    if (m.bugtrackerUrl)
+        lines.push(`  <url type="bugtracker">${escapeXml(m.bugtrackerUrl)}</url>`);
+    if (m.vcsBrowserUrl)
+        lines.push(`  <url type="vcs-browser">${escapeXml(m.vcsBrowserUrl)}</url>`);
+    if (m.donationUrl)
+        lines.push(`  <url type="donation">${escapeXml(m.donationUrl)}</url>`);
+    if (m.translateUrl)
+        lines.push(`  <url type="translate">${escapeXml(m.translateUrl)}</url>`);
+    // <content_rating>
+    const cr = normaliseContentRating(m.contentRating);
+    if (cr.attributes && Object.keys(cr.attributes).length > 0) {
+        lines.push(`  <content_rating type="${escapeXml(cr.type)}">`);
+        for (const [key, value] of Object.entries(cr.attributes)) {
+            lines.push(`    <content_attribute id="${escapeXml(key)}">${escapeXml(value)}</content_attribute>`);
+        }
+        lines.push('  </content_rating>');
+    }
+    else {
+        lines.push(`  <content_rating type="${escapeXml(cr.type)}" />`);
+    }
+    // <releases>
+    if (m.releases?.length) {
+        lines.push('  <releases>');
+        for (const r of m.releases) {
+            if (r.description === undefined) {
+                lines.push(`    <release version="${escapeXml(r.version)}" date="${escapeXml(r.date)}" />`);
+            }
+            else {
+                lines.push(`    <release version="${escapeXml(r.version)}" date="${escapeXml(r.date)}">`);
+                lines.push('      <description>');
+                for (const blockLine of renderDescriptionBlocks(r.description, '        ')) {
+                    lines.push(blockLine);
+                }
+                lines.push('      </description>');
+                lines.push('    </release>');
+            }
+        }
+        lines.push('  </releases>');
+    }
+    // <categories>
+    if (m.categories?.length) {
+        lines.push('  <categories>');
+        for (const c of m.categories)
+            lines.push(`    <category>${escapeXml(c)}</category>`);
+        lines.push('  </categories>');
+    }
+    // <keywords>
+    if (m.keywords?.length) {
+        lines.push('  <keywords>');
+        for (const k of m.keywords)
+            lines.push(`    <keyword>${escapeXml(k)}</keyword>`);
+        lines.push('  </keywords>');
+    }
+    // <branding> (apps only — Flathub ignores it on CLI)
+    if (kind === 'desktop-application' && m.branding) {
+        lines.push('  <branding>');
+        lines.push(`    <color type="primary" scheme_preference="light">${escapeXml(m.branding.accentLight)}</color>`);
+        lines.push(`    <color type="primary" scheme_preference="dark">${escapeXml(m.branding.accentDark)}</color>`);
+        lines.push('  </branding>');
+    }
+    // <kudos>
+    if (m.kudos?.length) {
+        lines.push('  <kudos>');
+        for (const k of m.kudos)
+            lines.push(`    <kudo>${escapeXml(k)}</kudo>`);
+        lines.push('  </kudos>');
+    }
+    // <provides> — always emit <binary> for both kinds; <mediatype>/<dbus> only when configured
+    const binaries = m.provides?.binaries ?? [inputs.command];
+    const mimetypes = m.provides?.mimetypes ?? [];
+    const dbus = m.provides?.dbus ?? [];
+    if (binaries.length || mimetypes.length || dbus.length) {
+        lines.push('  <provides>');
+        for (const b of binaries)
+            lines.push(`    <binary>${escapeXml(b)}</binary>`);
+        for (const t of mimetypes)
+            lines.push(`    <mediatype>${escapeXml(t)}</mediatype>`);
+        for (const d of dbus)
+            lines.push(`    <dbus type="${escapeXml(d.type)}">${escapeXml(d.id)}</dbus>`);
+        lines.push('  </provides>');
+    }
+    // <supports>
+    if (m.supports?.controls?.length || m.supports?.internet) {
+        lines.push('  <supports>');
+        for (const c of m.supports.controls ?? [])
+            lines.push(`    <control>${escapeXml(c)}</control>`);
+        if (m.supports.internet)
+            lines.push(`    <internet>${escapeXml(m.supports.internet)}</internet>`);
+        lines.push('  </supports>');
+    }
+    // <requires>
+    if (m.requires?.displayLengthMin || m.requires?.controls?.length || m.requires?.internet) {
+        lines.push('  <requires>');
+        if (m.requires.displayLengthMin) {
+            lines.push(`    <display_length compare="ge">${m.requires.displayLengthMin}</display_length>`);
+        }
+        for (const c of m.requires.controls ?? [])
+            lines.push(`    <control>${escapeXml(c)}</control>`);
+        if (m.requires.internet)
+            lines.push(`    <internet>${escapeXml(m.requires.internet)}</internet>`);
+        lines.push('  </requires>');
+    }
+    // <recommends>
+    if (m.recommends?.displayLengthMin || m.recommends?.controls?.length) {
+        lines.push('  <recommends>');
+        if (m.recommends.displayLengthMin) {
+            lines.push(`    <display_length compare="ge">${m.recommends.displayLengthMin}</display_length>`);
+        }
+        for (const c of m.recommends.controls ?? [])
+            lines.push(`    <control>${escapeXml(c)}</control>`);
+        lines.push('  </recommends>');
+    }
+    lines.push('</component>');
+    return lines.join('\n') + '\n';
+}
+// ─── Description block renderer ──────────────────────────────────────────
+function renderDescriptionBlocks(description, indent) {
+    const blocks = typeof description === 'string' ? stringToBlocks(description) : description;
+    const out = [];
+    for (const block of blocks) {
+        if ('p' in block) {
+            pushTranslatorHint(out, block.translatorHint, indent);
+            out.push(`${indent}<p>${escapeXml(block.p.trim().replace(/\s+/g, ' '))}</p>`);
+        }
+        else {
+            pushTranslatorHint(out, block.translatorHint, indent);
+            out.push(`${indent}<ul>`);
+            for (const item of block.ul) {
+                if (typeof item === 'string') {
+                    out.push(`${indent}  <li>${escapeXml(item)}</li>`);
+                }
+                else {
+                    pushTranslatorHint(out, item.translatorHint, `${indent}  `);
+                    out.push(`${indent}  <li>${escapeXml(item.item)}</li>`);
+                }
+            }
+            out.push(`${indent}</ul>`);
+        }
+    }
+    return out;
+}
+/** Auto-convert blank-line-split string into paragraph blocks. */
+function stringToBlocks(s) {
+    return s
+        .trim()
+        .split(/\n\n+/)
+        .map((para) => ({ p: para.trim().replace(/\s+/g, ' ') }));
+}
+function pushTranslatorHint(out, hint, indent) {
+    if (!hint)
+        return;
+    out.push(`${indent}<!-- TRANSLATORS: ${hint} -->`);
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────
+function normaliseContentRating(cr) {
+    if (cr === undefined)
+        return { type: 'oars-1.1' };
+    if (typeof cr === 'string')
+        return { type: cr };
+    return { type: cr.type ?? 'oars-1.1', attributes: cr.attributes };
+}
+function substitute(template, tokens) {
+    let out = template;
+    for (const [key, value] of Object.entries(tokens)) {
+        out = out.split(`{{${key}}}`).join(value);
+    }
+    return out;
+}
+export function escapeXml(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}

package/lib/utils/cli-runtime-closure.d.ts

@@ -0,0 +1,23 @@
+import type { Workspace } from '@gjsify/workspace';
+export declare function moduleSpecifiers(code: string): string[];
+export interface CliRuntimeClosureOptions {
+    /**
+     * File to start the walk from. Defaults to the running CLI's Node entry
+     * (`bin.gjsify`), which is what a spawned child loads.
+     */
+    entry?: string | null;
+    /** The CLI's own manifest, for its optional peers. Read from disk by default. */
+    cliManifest?: {
+        peerDependencies?: Record<string, string>;
+    } | null;
+}
+/**
+ * Workspace packages the running CLI imports, so a parallel sweep can build them
+ * first instead of underneath itself.
+ *
+ * Empty is the correct answer in three real situations and none of them is an
+ * error: a consumer project (its `@gjsify/*` deps are not workspaces, so nothing
+ * the sweep builds can tear), a relocated bundle with no reachable manifest, and
+ * a CLI whose entry has not been built.
+ */
+export declare function cliRuntimeClosure(workspaces: readonly Workspace[], options?: CliRuntimeClosureOptions): Set<string>;

package/lib/utils/cli-runtime-closure.js

@@ -0,0 +1,274 @@
+// Which workspace packages does the RUNNING CLI import at runtime?
+//
+// WHY THE SCHEDULER NEEDS THIS
+//
+// `gjsify foreach <script> -p` spawns children, and every child is another
+// `gjsify` process: it BOOTS the CLI before it runs anything. So while a parallel
+// sweep rebuilds the workspace, each child is reading the very `lib/` trees its
+// siblings are writing. Measured on the macOS leg (run 31130155911,
+// darwin-arm64), on the first full build that leg ever reached:
+//
+//     [gjsify foreach] start @gjsify/native-platform (49/160 done, 3 in flight)
+//     [gjsify foreach] start @gjsify/npm-registry    (50/160 done, 3 in flight)
+//     [@gjsify/native-platform] ERR_MODULE_NOT_FOUND
+//       .../npm-registry/lib/esm/_virtual/_rolldown/runtime.js
+//       imported from .../npm-registry/lib/esm/auth.js
+//
+// `auth.js` was on disk and its rolldown chunk was not — a torn write, not a
+// corrupt build. `foreach` uses this set to build those packages BEFORE the
+// parallel sweep starts, so nothing rewrites them while a child boots.
+//
+// WHY IT IS DERIVED AND NOT LISTED
+//
+// The four names a root script once carried by hand (`semver`, `npm-registry`,
+// `tar`, `workspace`) were never the whole answer, and a hand-written list is the
+// same defect one level up: it is right until an import changes. Two measured
+// alternatives were rejected before this one:
+//
+//   * the MANIFEST closure of `@gjsify/cli` (transitive workspace `dependencies`)
+//     selects 110 of the ~160 packages a full sweep builds — it counts the
+//     umbrella polyfill metas the CLI declares for the alias layer and never
+//     imports under Node. Serialising 110 packages is not a fix, it is the end of
+//     parallelism;
+//   * a regex over the sources reports 27, because `commands/storybook.ts` emits
+//     GENERATED CODE containing `import { … } from '@gjsify/storybook';` inside a
+//     template literal. A text scan cannot tell a program from a string, and that
+//     one string drags the whole GTK storybook subtree into the prefix.
+//
+// So the graph is PARSED, from the entry the children actually boot, and the
+// answer was checked against ground truth: a Node loader hook recording every
+// `file:` URL `gjsify --version` loads reports exactly the ten packages this walk
+// returns (see `cli-runtime-closure.spec.ts` for the shape the walk must keep).
+//
+// THE ONE THING A PARSE CANNOT SEE
+//
+// A COMPUTED dynamic import. `bundler-pick.ts` loads the bundler engine as
+// `await import(target)` where `target` is a resolved file URL, and
+// `rolldown-plugin-gjsify`'s `css-as-string.ts` does the same for lightningcss —
+// deliberately, so tsc and rolldown do not resolve an optional peer at build
+// time. Those are invisible to any static walk, and they are invisible to npm for
+// the same reason, which is exactly why the convention is to declare them as
+// optional PEER dependencies. So the peers of every package in the graph are
+// added: one declaration closes both blind spots, and it stays a declaration the
+// package owns rather than a list this file keeps.
+import * as acorn from 'acorn';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import { cliPackageDir } from './publish-headers.js';
+/**
+ * Split a bare specifier into a WORKSPACE package name + its `exports` key, or
+ * `null` when it names no workspace.
+ *
+ * Matched against the workspace index rather than against the `@gjsify/` scope: a
+ * scope literal would be a second place that has to be edited when the project is
+ * vendored, forked or renamed, and the question here is only ever "is this one of
+ * OUR packages". Scoped names take two segments, unscoped one.
+ */
+function splitWorkspaceSpecifier(specifier, byName) {
+    if (specifier.startsWith('.') || specifier.startsWith('/') || specifier.includes(':'))
+        return null;
+    const parts = specifier.split('/');
+    const candidates = specifier.startsWith('@') ? [2] : [1];
+    for (const depth of candidates) {
+        const name = parts.slice(0, depth).join('/');
+        if (!byName.has(name))
+            continue;
+        const rest = parts.slice(depth).join('/');
+        return { name, subpath: rest ? `./${rest}` : '.' };
+    }
+    return null;
+}
+/**
+ * The string a module specifier node names, or `null` when it is computed.
+ *
+ * A substitution-free TEMPLATE LITERAL is as static as a quoted string, and
+ * skipping it is not hypothetical: the minifier rewrites `await
+ * import('gi://GLib?version=2.0')` to a backtick form, so a Literal-only reader
+ * silently loses every dynamic import in a built bundle.
+ */
+function literalSpecifier(node) {
+    if (node?.type === 'Literal')
+        return typeof node.value === 'string' ? node.value : null;
+    if (node?.type === 'TemplateLiteral' && node.expressions?.length === 0) {
+        const cooked = node.quasis?.[0]?.value?.cooked;
+        return typeof cooked === 'string' ? cooked : null;
+    }
+    return null;
+}
+export function moduleSpecifiers(code) {
+    let ast;
+    try {
+        ast = acorn.parse(code, { ecmaVersion: 'latest', sourceType: 'module', allowHashBang: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        if (Array.isArray(node)) {
+            for (const child of node)
+                visit(child);
+            return;
+        }
+        const n = node;
+        if (n.type === 'ImportDeclaration' ||
+            n.type === 'ExportNamedDeclaration' ||
+            n.type === 'ExportAllDeclaration' ||
+            n.type === 'ImportExpression') {
+            const specifier = literalSpecifier(n.source);
+            if (specifier !== null)
+                out.push(specifier);
+        }
+        for (const [key, value] of Object.entries(n)) {
+            if (key === 'type' || key === 'start' || key === 'end' || key === 'loc')
+                continue;
+            visit(value);
+        }
+    };
+    visit(ast);
+    return out;
+}
+/** The file a relative specifier names, probing the extensionless spellings Node accepts. */
+function resolveRelative(fromFile, specifier) {
+    const base = resolvePath(dirname(fromFile), specifier);
+    for (const candidate of [base, `${base}.js`, `${base}.mjs`, join(base, 'index.js')]) {
+        try {
+            if (statSync(candidate).isFile())
+                return candidate;
+        }
+        catch {
+            /* not this spelling */
+        }
+    }
+    return null;
+}
+/**
+ * The file a workspace package's `<subpath>` resolves to, read from its own
+ * manifest. `subpath` is `'.'` for a bare package specifier.
+ *
+ * The `exports` conditions are walked in the order the CHILD's runtime resolves
+ * them; `main`/`module` is the pre-`exports` fallback. Deliberately NOT
+ * `import.meta.resolve`: that answers only for the runtime doing the asking, and
+ * this walk must give the same answer from Node and from GJS, from a spec with a
+ * fixture tree as from a real install. Resolving the SUBPATH rather than the
+ * package root matters — `@gjsify/rolldown-plugin-gjsify/runtime` is a leaf, and
+ * substituting the root barrel for it would drag in everything the barrel
+ * re-exports and nothing imports.
+ */
+function workspaceEntry(ws, subpath) {
+    const manifest = ws.manifest;
+    const pick = (node) => {
+        if (typeof node === 'string')
+            return node;
+        if (!node || typeof node !== 'object' || Array.isArray(node))
+            return null;
+        const record = node;
+        for (const condition of ['node', 'import', 'default', 'gjs']) {
+            if (condition in record) {
+                const picked = pick(record[condition]);
+                if (picked)
+                    return picked;
+            }
+        }
+        return null;
+    };
+    let target = null;
+    if (typeof manifest.exports === 'string')
+        target = subpath === '.' ? manifest.exports : null;
+    else if (manifest.exports && typeof manifest.exports === 'object') {
+        target = pick(manifest.exports[subpath]);
+    }
+    if (!target && subpath === '.') {
+        target = typeof manifest.module === 'string' ? manifest.module : null;
+        target ??= typeof manifest.main === 'string' ? manifest.main : null;
+    }
+    if (!target)
+        return null;
+    const file = resolvePath(ws.location, target);
+    return existsSync(file) ? file : null;
+}
+/** `peerDependencies` of `manifest` that name a workspace package. */
+function workspacePeers(manifest, byName) {
+    return Object.keys(manifest.peerDependencies ?? {}).filter((name) => byName.has(name));
+}
+/**
+ * Workspace packages the running CLI imports, so a parallel sweep can build them
+ * first instead of underneath itself.
+ *
+ * Empty is the correct answer in three real situations and none of them is an
+ * error: a consumer project (its `@gjsify/*` deps are not workspaces, so nothing
+ * the sweep builds can tear), a relocated bundle with no reachable manifest, and
+ * a CLI whose entry has not been built.
+ */
+export function cliRuntimeClosure(workspaces, options = {}) {
+    const byName = new Map(workspaces.map((ws) => [ws.name, ws]));
+    const found = new Set();
+    let entry = options.entry;
+    let cliManifest = options.cliManifest;
+    if (entry === undefined || cliManifest === undefined) {
+        const packageDir = cliPackageDir();
+        let manifest = null;
+        if (packageDir) {
+            try {
+                manifest = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8'));
+            }
+            catch {
+                /* unreadable — the closure degrades to empty, which is a no-op prefix */
+            }
+        }
+        cliManifest ??= manifest;
+        if (entry === undefined) {
+            // The npm `bin` entry, NOT `gjsify.bin`: the GJS bundle is self-contained,
+            // so walking it would report nothing, while a GJS child still loads the
+            // engine facades through the peers below. The `lib/` graph is a superset
+            // of what either entry reaches, and one code path beats two.
+            const bin = manifest?.bin;
+            const relative = typeof bin === 'string' ? bin : (bin?.['gjsify'] ?? manifest?.main);
+            entry = packageDir && relative ? resolvePath(packageDir, relative) : null;
+        }
+    }
+    for (const peer of workspacePeers(cliManifest ?? {}, byName))
+        found.add(peer);
+    if (!entry || !existsSync(entry))
+        return found;
+    const seen = new Set();
+    const queue = [entry];
+    while (queue.length > 0) {
+        const file = queue.shift();
+        if (seen.has(file))
+            continue;
+        seen.add(file);
+        let code;
+        try {
+            code = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const specifier of moduleSpecifiers(code)) {
+            if (specifier.startsWith('.')) {
+                const next = resolveRelative(file, specifier);
+                if (next)
+                    queue.push(next);
+                continue;
+            }
+            const split = splitWorkspaceSpecifier(specifier, byName);
+            const ws = split ? byName.get(split.name) : undefined;
+            if (!split || !ws)
+                continue;
+            found.add(split.name);
+            for (const peer of workspacePeers(ws.manifest, byName))
+                found.add(peer);
+            // Queued per SUBPATH, not per package: `seen` dedupes files, so a
+            // package imported through two subpaths is walked through both. A
+            // package-level visited set would stop at whichever subpath came
+            // first and miss what the other one reaches.
+            const next = workspaceEntry(ws, split.subpath);
+            if (next)
+                queue.push(next);
+        }
+    }
+    return found;
+}

package/lib/utils/publish-headers.d.ts

@@ -39,3 +39,16 @@ export interface PublishHeaderOptions {
  */
 export declare function buildPublishHeaders(url: string, opts: PublishHeaderOptions): Record<string, string>;
 export declare function cliVersion(): string;
+/**
+ * Directory of the RUNNING `@gjsify/cli` package — the nearest ancestor of this
+ * module holding a `package.json` named `@gjsify/cli`; `null` when none.
+ *
+ * The climb, not a fixed `'..'` hop, for the reason {@link cliVersion} states: the
+ * package is dual-entry and the two entries sit at different depths.
+ * `GJSIFY_CLI_PACKAGE_JSON` overrides the starting point, same as for the version.
+ *
+ * Exported because the answer to "where am I installed" is the same question as
+ * "which version am I", and this file is where that climb lives — a second copy
+ * elsewhere is the drift `check-cli-own-version-read.mjs` exists to prevent.
+ */
+export declare function cliPackageDir(): string | null;