@gjsify/cli 0.4.28 → 0.4.30

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

@@ -13,18 +13,18 @@
 //
 // Out of scope (still deferred): peerDependencies validation,
 // lifecycle scripts, git/file specs.
-import * as fs from "node:fs";
-import * as path from "node:path";
-import * as os from "node:os";
-import { Range, SemVer, maxSatisfying, satisfies, } from "@gjsify/semver";
-import { DEFAULT_REGISTRY, fetchPackument, fetchTarball, parseNpmrc, } from "@gjsify/npm-registry";
-import { extractTarball } from "@gjsify/tar";
-const DEFAULT_CONCURRENCY = Number(process.env.GJSIFY_INSTALL_CONCURRENCY ?? "8") || 8;
-const LOCKFILE_NAME = "gjsify-lock.json";
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { Range, SemVer, maxSatisfying, satisfies } from '@gjsify/semver';
+import { DEFAULT_REGISTRY, fetchPackument, fetchTarball, parseNpmrc, } from '@gjsify/npm-registry';
+import { extractTarball } from '@gjsify/tar';
+const DEFAULT_CONCURRENCY = Number(process.env.GJSIFY_INSTALL_CONCURRENCY ?? '8') || 8;
+const LOCKFILE_NAME = 'gjsify-lock.json';
 const LOCKFILE_VERSION = 2;
 export async function installPackagesNative(opts) {
     if (opts.specs.length === 0) {
-        throw new Error("installPackagesNative: empty specs list");
+        throw new Error('installPackagesNative: empty specs list');
     }
     fs.mkdirSync(opts.prefix, { recursive: true });
     const npmrc = await loadNpmrc(opts);
@@ -47,25 +47,25 @@ export async function installPackagesNative(opts) {
             throw new Error(`install: --immutable but ${lockfilePath} is stale.\n${drift}\n` +
                 `Re-run \`gjsify install\` (without --immutable) to refresh the lockfile.`);
         }
-        log("install: --immutable, using lockfile (%d package(s))", Object.keys(existingLock.packages).length);
+        log('install: --immutable, using lockfile (%d package(s))', Object.keys(existingLock.packages).length);
         nodes = lockfileToNodes(existingLock);
     }
     else if (existingLock && lockfileMatchesRequest(existingLock, opts.specs)) {
-        log("install: using lockfile (%d package(s))", Object.keys(existingLock.packages).length);
+        log('install: using lockfile (%d package(s))', Object.keys(existingLock.packages).length);
         nodes = lockfileToNodes(existingLock);
     }
     else {
-        log("install: resolving %d top-level spec(s) → %s", opts.specs.length, opts.prefix);
+        log('install: resolving %d top-level spec(s) → %s', opts.specs.length, opts.prefix);
         nodes = await resolveDeps(opts.specs, npmrc, log, opts.overrides, opts.skipDeps);
         if (opts.lockfile) {
             writeLockfile(lockfilePath, opts.specs, nodes);
-            log("install: wrote %s (%d entries)", LOCKFILE_NAME, nodes.length);
+            log('install: wrote %s (%d entries)', LOCKFILE_NAME, nodes.length);
         }
     }
-    log("install: downloading %d tarball(s)", nodes.length);
+    log('install: downloading %d tarball(s)', nodes.length);
     await downloadAndExtractAll(nodes, opts.prefix, npmrc, log);
     await linkBins(nodes, opts.prefix, log);
-    log("install: done");
+    log('install: done');
     // Surface the top-level requested packages so callers can update
     // package.json with the resolved version (mirrors `npm install --save`
     // behavior). Sub-deps are not included.
@@ -94,14 +94,14 @@ function topLevelResolutions(specs, nodes) {
     return out;
 }
 function parseSpecName(spec) {
-    if (spec.startsWith("@")) {
-        const slash = spec.indexOf("/");
+    if (spec.startsWith('@')) {
+        const slash = spec.indexOf('/');
         if (slash === -1)
             return spec;
-        const at = spec.indexOf("@", slash + 1);
+        const at = spec.indexOf('@', slash + 1);
         return at === -1 ? spec : spec.slice(0, at);
     }
-    const at = spec.indexOf("@");
+    const at = spec.indexOf('@');
     return at === -1 ? spec : spec.slice(0, at);
 }
 /**
@@ -128,7 +128,7 @@ async function resolveDeps(specs, npmrc, log, overrides, skipDeps) {
             return range;
         if (override === range)
             return range;
-        log("install: override %s %s → %s", name, range, override);
+        log('install: override %s %s → %s', name, range, override);
         return override;
     };
     const packumentCache = new Map();
@@ -139,7 +139,7 @@ async function resolveDeps(specs, npmrc, log, overrides, skipDeps) {
         const fresh = fetchPackument(name, {
             npmrc,
             onRetry: ({ attempt, error, delayMs }) => {
-                log("packument %s: retry %d after %dms (%s)", name, attempt, delayMs, errMsg(error));
+                log('packument %s: retry %d after %dms (%s)', name, attempt, delayMs, errMsg(error));
             },
         });
         packumentCache.set(name, fresh);
@@ -200,13 +200,23 @@ async function resolveDeps(specs, npmrc, log, overrides, skipDeps) {
             if (installPath === `node_modules/${edge.name}`) {
                 root.set(edge.name, node);
             }
-            log("resolve: %s@%s ← %s (at %s)", edge.name, version, edge.range, installPath);
+            log('resolve: %s@%s ← %s (at %s)', edge.name, version, edge.range, installPath);
             if (!skipDeps) {
                 for (const [depName, depRange] of Object.entries(node.dependencies)) {
-                    queue.push({ from: installPath, name: depName, range: applyOverride(depName, depRange), required: true });
+                    queue.push({
+                        from: installPath,
+                        name: depName,
+                        range: applyOverride(depName, depRange),
+                        required: true,
+                    });
                 }
                 for (const [depName, depRange] of Object.entries(node.optionalDependencies)) {
-                    queue.push({ from: installPath, name: depName, range: applyOverride(depName, depRange), required: false });
+                    queue.push({
+                        from: installPath,
+                        name: depName,
+                        range: applyOverride(depName, depRange),
+                        required: false,
+                    });
                 }
             }
         }
@@ -214,7 +224,7 @@ async function resolveDeps(specs, npmrc, log, overrides, skipDeps) {
             // Optional deps that fail to resolve are skipped — yarn/npm
             // behavior. Required deps re-throw.
             if (!edge.required) {
-                log("resolve: optional dep %s@%s skipped (%s)", edge.name, edge.range, e.message);
+                log('resolve: optional dep %s@%s skipped (%s)', edge.name, edge.range, e.message);
                 continue;
             }
             throw e;
@@ -245,12 +255,12 @@ function findVisible(requesterPath, name, byPath) {
         // eslint-disable-next-line no-constant-condition
         while (true) {
             // Find the deepest `/node_modules/<pkg>` in `p`, strip it.
-            const idx = p.lastIndexOf("/node_modules/");
+            const idx = p.lastIndexOf('/node_modules/');
             if (idx < 0)
                 break;
             p = p.slice(0, idx);
             candidates.push(`${p}/node_modules/${name}`);
-            if (p === "")
+            if (p === '')
                 break;
         }
     }
@@ -301,10 +311,10 @@ function readLockfile(lockfilePath) {
     if (!fs.existsSync(lockfilePath))
         return null;
     try {
-        const parsed = JSON.parse(fs.readFileSync(lockfilePath, "utf-8"));
+        const parsed = JSON.parse(fs.readFileSync(lockfilePath, 'utf-8'));
         if (parsed.lockfileVersion !== LOCKFILE_VERSION)
             return null;
-        if (!parsed.packages || typeof parsed.packages !== "object")
+        if (!parsed.packages || typeof parsed.packages !== 'object')
             return null;
         return parsed;
     }
@@ -330,7 +340,7 @@ function writeLockfile(lockfilePath, specs, nodes) {
         requested: [...specs],
         packages,
     };
-    fs.writeFileSync(lockfilePath, JSON.stringify(lockfile, null, 2) + "\n");
+    fs.writeFileSync(lockfilePath, JSON.stringify(lockfile, null, 2) + '\n');
 }
 function lockfileToNodes(lockfile) {
     return Object.entries(lockfile.packages).map(([installPath, entry]) => ({
@@ -349,8 +359,8 @@ function lockfileToNodes(lockfile) {
 function nameFromInstallPath(installPath) {
     // Last `node_modules/` boundary, then the rest is the package name
     // (single segment unscoped, or `@scope/pkg` scoped).
-    const idx = installPath.lastIndexOf("/node_modules/");
-    const after = idx < 0 ? installPath.replace(/^node_modules\//, "") : installPath.slice(idx + "/node_modules/".length);
+    const idx = installPath.lastIndexOf('/node_modules/');
+    const after = idx < 0 ? installPath.replace(/^node_modules\//, '') : installPath.slice(idx + '/node_modules/'.length);
     return after;
 }
 function lockfileMatchesRequest(lockfile, specs) {
@@ -381,10 +391,10 @@ function describeLockfileDrift(lockfile, specs) {
         return null;
     const lines = [];
     if (added.length > 0)
-        lines.push(`  + ${added.sort().join("\n  + ")}`);
+        lines.push(`  + ${added.sort().join('\n  + ')}`);
     if (removed.length > 0)
-        lines.push(`  - ${removed.sort().join("\n  - ")}`);
-    return lines.join("\n");
+        lines.push(`  - ${removed.sort().join('\n  - ')}`);
+    return lines.join('\n');
 }
 // Exported for unit-testing — keep the function name + signature
 // stable, the install-backend itself still calls it via the local
@@ -400,25 +410,25 @@ export function parseSpec(raw) {
     // shipped only prereleases (4.0.0-rc.17 is the `latest` tag, no
     // stable 4.x yet) and `*` was selecting the abandoned 3.3.0
     // instead.
-    if (raw.startsWith("@")) {
-        const slash = raw.indexOf("/");
+    if (raw.startsWith('@')) {
+        const slash = raw.indexOf('/');
         if (slash < 0)
             throw new Error(`Invalid spec (scoped name without slash): ${raw}`);
-        const at = raw.indexOf("@", slash);
+        const at = raw.indexOf('@', slash);
         if (at < 0)
-            return { name: raw, range: "latest" };
-        return { name: raw.slice(0, at), range: raw.slice(at + 1) || "latest" };
+            return { name: raw, range: 'latest' };
+        return { name: raw.slice(0, at), range: raw.slice(at + 1) || 'latest' };
     }
-    const at = raw.indexOf("@");
+    const at = raw.indexOf('@');
     if (at < 0)
-        return { name: raw, range: "latest" };
-    return { name: raw.slice(0, at), range: raw.slice(at + 1) || "latest" };
+        return { name: raw, range: 'latest' };
+    return { name: raw.slice(0, at), range: raw.slice(at + 1) || 'latest' };
 }
 // Exported for unit-testing. Internal API.
 export function pickVersion(packument, range) {
     // dist-tag fast path: `latest`, `next`, ...
-    if (packument["dist-tags"][range])
-        return packument["dist-tags"][range];
+    if (packument['dist-tags'][range])
+        return packument['dist-tags'][range];
     // Validate range early so a typo fails loudly.
     let parsedRange;
     try {
@@ -442,8 +452,7 @@ async function downloadAndExtractAll(nodes, prefix, npmrc, log) {
     // Sort by install-path depth ascending so parents extract before
     // children. Extracting a parent on top of an existing child would
     // wipe out the child.
-    const queue = [...nodes].sort((a, b) => depth(a.installPath) - depth(b.installPath) ||
-        (a.installPath < b.installPath ? -1 : 1));
+    const queue = [...nodes].sort((a, b) => depth(a.installPath) - depth(b.installPath) || (a.installPath < b.installPath ? -1 : 1));
     const workers = [];
     const concurrency = Math.max(1, Math.min(DEFAULT_CONCURRENCY, queue.length));
     // Parents (depth 1) are extracted serially first to avoid concurrent
@@ -477,22 +486,69 @@ async function downloadAndExtractAll(nodes, prefix, npmrc, log) {
 }
 async function extractOne(node, prefix, npmrc, log) {
     const dest = path.join(prefix, node.installPath);
-    log("fetch: %s@%s ← %s (→ %s)", node.name, node.version, node.tarballUrl, node.installPath);
+    // Defense-in-depth against the workspace-source-wipe data-loss bug:
+    // every extractable node MUST land inside a `node_modules/` directory.
+    // The resolver only ever produces `installPath`s of that shape, so this
+    // can only fail if a workspace package leaked into the fetch/extract
+    // queue (the root cause fixed in `workspaceInstall`). Refusing here means
+    // a regression in the resolver can never again `rmSync` a working-tree
+    // source dir — the realpath check additionally rejects a `dest` that
+    // resolves THROUGH a symlink into a directory outside node_modules.
+    assertNodeModulesDest(dest, node);
+    log('fetch: %s@%s ← %s (→ %s)', node.name, node.version, node.tarballUrl, node.installPath);
     const bytes = await fetchTarball(node.tarballUrl, {
         npmrc,
         integrity: node.integrity,
         onRetry: ({ attempt, error, delayMs }) => {
-            log("tarball %s@%s: retry %d after %dms (%s)", node.name, node.version, attempt, delayMs, errMsg(error));
+            log('tarball %s@%s: retry %d after %dms (%s)', node.name, node.version, attempt, delayMs, errMsg(error));
         },
     });
     fs.rmSync(dest, { recursive: true, force: true });
     fs.mkdirSync(dest, { recursive: true });
     await extractTarball(bytes, dest);
 }
+/**
+ * Guard: a tarball may only be extracted into a `node_modules/` directory.
+ *
+ * Two checks, both belt-and-suspenders against ever wiping a working-tree
+ * source dir (the install-deletes-workspace-sources data-loss bug):
+ *
+ *   1. The logical `installPath` must contain a `node_modules` path segment.
+ *      The resolver always produces such paths; a workspace package that
+ *      slipped into the queue would not.
+ *   2. If `dest` already exists and resolves (via symlink) to a directory
+ *      whose REAL path is not under a `node_modules/` segment, refuse. This
+ *      catches the case where `node_modules/<name>` is a symlink to a
+ *      workspace's source tree — `rmSync(dest, { recursive: true })` would
+ *      then delete the link's target contents.
+ */
+function assertNodeModulesDest(dest, node) {
+    const segments = dest.split(path.sep);
+    if (!segments.includes('node_modules')) {
+        throw new Error(`gjsify install: refusing to extract ${node.name}@${node.version} into ${dest} — ` +
+            `target is not inside a node_modules/ directory. This would overwrite working-tree files. ` +
+            `A workspace package likely leaked into the fetch queue (it must be symlinked, not fetched).`);
+    }
+    let real;
+    try {
+        real = fs.realpathSync(dest);
+    }
+    catch {
+        // `dest` doesn't exist yet (fresh install) — nothing to resolve, the
+        // logical-path check above is sufficient.
+        return;
+    }
+    const realSegments = real.split(path.sep);
+    if (!realSegments.includes('node_modules')) {
+        throw new Error(`gjsify install: refusing to extract ${node.name}@${node.version} — ${dest} resolves to ${real}, ` +
+            `which is outside any node_modules/ directory (likely a symlink to a workspace source tree). ` +
+            `Extracting here would delete working-tree source files.`);
+    }
+}
 function depth(installPath) {
     // Count `node_modules/` segments to know nesting depth.
     // `node_modules/foo` = 1, `node_modules/foo/node_modules/bar` = 2, etc.
-    return installPath.split("/node_modules/").length;
+    return installPath.split('/node_modules/').length;
 }
 async function linkBins(nodes, prefix, log) {
     // Only root-level packages publish bins into the top-level
@@ -500,7 +556,7 @@ async function linkBins(nodes, prefix, log) {
     // direct dependents through the nested .bin (npm matches this) — we
     // omit nested-bin linking for now since no consumer of the install
     // backend depends on it (gjsify's own use cases all hit root bins).
-    const binDir = path.join(prefix, "node_modules", ".bin");
+    const binDir = path.join(prefix, 'node_modules', '.bin');
     let created = 0;
     for (const node of nodes) {
         if (!node.bin)
@@ -536,15 +592,13 @@ async function linkBins(nodes, prefix, log) {
         }
     }
     if (created > 0)
-        log("bin: linked %d entry(ies) under .bin/", created);
+        log('bin: linked %d entry(ies) under .bin/', created);
 }
 function normalizeBin(pkgName, bin) {
     const out = new Map();
-    if (typeof bin === "string") {
+    if (typeof bin === 'string') {
         // String form is shorthand for `{ <last-segment-of-pkgName>: <bin> }`.
-        const baseName = pkgName.startsWith("@")
-            ? pkgName.slice(pkgName.indexOf("/") + 1)
-            : pkgName;
+        const baseName = pkgName.startsWith('@') ? pkgName.slice(pkgName.indexOf('/') + 1) : pkgName;
         out.set(baseName, bin);
         return out;
     }
@@ -565,11 +619,11 @@ async function loadNpmrc(opts) {
     // workspace-root one too; the gjsify project-local case is what users
     // hit most often (mock-registry tests, scoped-registry overrides), so
     // we cover that explicitly.
-    for (const candidate of [path.join(home, ".npmrc"), path.join(opts.prefix, ".npmrc")]) {
+    for (const candidate of [path.join(home, '.npmrc'), path.join(opts.prefix, '.npmrc')]) {
         if (!fs.existsSync(candidate))
             continue;
         try {
-            const projectParsed = parseNpmrc(fs.readFileSync(candidate, "utf-8"));
+            const projectParsed = parseNpmrc(fs.readFileSync(candidate, 'utf-8'));
             parsed = { ...parsed, ...projectParsed, scopes: { ...parsed.scopes, ...projectParsed.scopes } };
         }
         catch (e) {

package/lib/utils/install-backend.js

@@ -40,7 +40,8 @@ async function installViaNpm({ prefix, specs, verbose, registry }) {
         '--no-package-lock',
         '--no-audit',
         '--no-fund',
-        '--prefix', prefix,
+        '--prefix',
+        prefix,
         ...(verbose ? ['--loglevel', 'verbose'] : ['--loglevel', 'warn']),
         ...specs,
     ];

package/lib/utils/install-global.js

@@ -161,9 +161,7 @@ function pickBinMap(pkgName, pkgJson) {
 function normalizeBin(pkgName, bin) {
     const out = new Map();
     if (typeof bin === 'string') {
-        const baseName = pkgName.startsWith('@')
-            ? pkgName.slice(pkgName.indexOf('/') + 1)
-            : pkgName;
+        const baseName = pkgName.startsWith('@') ? pkgName.slice(pkgName.indexOf('/') + 1) : pkgName;
         out.set(baseName, bin);
         return out;
     }

package/lib/utils/normalize-bundler-options.js

@@ -2,10 +2,46 @@
 // field on `.gjsifyrc.js` / `package.json#gjsify` into the equivalent
 // `bundler?: RolldownOptions` shape. Logs a single warning per build.
 //
-// Drop in 0.5.0.
+// Also handles the top-level `bundler.define` alias: Rolldown reads
+// `transform.define`, not a top-level `define`. A user who flat-renames
+// `esbuild: { define: {...} }` → `bundler: { define: {...} }` puts `define`
+// at the top level where Rolldown silently ignores it, causing
+// `ReferenceError: <TOKEN> is not defined` at GJS load time. We auto-map
+// top-level `bundler.define` into `bundler.transform.define` and emit a
+// one-time warning so the user can correct their config.
+//
+// Drop `esbuild` shim in 0.5.0; the `bundler.define` alias is permanent.
 let warnedOnce = false;
+let warnedDefineOnce = false;
 export function normalizeBundlerOptions(configData) {
-    const fromBundler = (configData.bundler ?? {});
+    const raw = (configData.bundler ?? {});
+    // --- Top-level bundler.define alias ------------------------------------------
+    // Rolldown only reads `transform.define`; a top-level `define` key is silently
+    // ignored. Detect it, warn once, and move it into `transform.define` so the
+    // user's flat esbuild→bundler rename of `define` Just Works.
+    let fromBundler = raw;
+    if (typeof raw['define'] === 'object' &&
+        raw['define'] !== null) {
+        if (!warnedDefineOnce) {
+            warnedDefineOnce = true;
+            // eslint-disable-next-line no-console
+            console.warn("[gjsify] WARNING: 'bundler.define' is not a valid Rolldown option and would be " +
+                "silently ignored — it has been auto-mapped to 'bundler.transform.define'. " +
+                "Move 'define' under 'bundler.transform.define' in your config to suppress " +
+                'this warning and avoid a ReferenceError at GJS load time.');
+        }
+        const { define: topLevelDefine, ...rest } = raw;
+        fromBundler = {
+            ...rest,
+            transform: {
+                ...rest.transform,
+                define: {
+                    ...topLevelDefine,
+                    ...rest.transform?.define,
+                },
+            },
+        };
+    }
     if (!configData.esbuild)
         return fromBundler;
     if (!warnedOnce) {
@@ -22,19 +58,19 @@ export function normalizeBundlerOptions(configData) {
     // user-provided config and `input` must survive the merge.
     const out = { ...fromEsbuild, ...fromBundler };
     if (fromEsbuild.output || fromBundler.output) {
-        out.output = { ...(fromEsbuild.output ?? {}), ...(fromBundler.output ?? {}) };
+        out.output = { ...fromEsbuild.output, ...fromBundler.output };
     }
     if (fromEsbuild.transform || fromBundler.transform) {
-        out.transform = { ...(fromEsbuild.transform ?? {}), ...(fromBundler.transform ?? {}) };
+        out.transform = { ...fromEsbuild.transform, ...fromBundler.transform };
         if (fromEsbuild.transform?.define || fromBundler.transform?.define) {
             out.transform.define = {
-                ...(fromEsbuild.transform?.define ?? {}),
-                ...(fromBundler.transform?.define ?? {}),
+                ...fromEsbuild.transform?.define,
+                ...fromBundler.transform?.define,
             };
         }
     }
     if (fromEsbuild.resolve || fromBundler.resolve) {
-        out.resolve = { ...(fromEsbuild.resolve ?? {}), ...(fromBundler.resolve ?? {}) };
+        out.resolve = { ...fromEsbuild.resolve, ...fromBundler.resolve };
     }
     return out;
 }
@@ -54,10 +90,7 @@ function legacyEsbuildToRolldown(esb) {
         output.minify = esb.minify;
     if (esb.sourcemap !== undefined) {
         // esbuild has 'external' / 'both' which Rolldown doesn't — coerce to boolean.
-        output.sourcemap =
-            esb.sourcemap === 'inline'
-                ? 'inline'
-                : Boolean(esb.sourcemap);
+        output.sourcemap = esb.sourcemap === 'inline' ? 'inline' : Boolean(esb.sourcemap);
     }
     if (esb.banner?.js !== undefined)
         output.banner = esb.banner.js;
@@ -80,10 +113,12 @@ function legacyEsbuildToRolldown(esb) {
         out.transform = transform;
     if (Object.keys(resolve).length > 0)
         out.resolve = resolve;
-    // Discarded silently:
+    // Discarded (handled elsewhere):
     //   esb.inject  — esbuild's array-of-side-effect-files; surfaced at the
     //                 CLI layer instead, via input expansion.
-    //   esb.loader  — Rolldown infers module types from extensions natively.
+    //   esb.loader  — replaced by top-level `gjsify.loaders` (see ConfigData);
+    //                 migration: `esbuild.loader: { '.png': 'dataurl', '.glsl': 'text' }`
+    //                 → `loaders: { '.png': 'dataurl', '.glsl': 'text' }`.
     return out;
 }
 /**
@@ -108,16 +143,16 @@ export function mergeBundlerOptions(base, overrides) {
     const { input: _ignoredInput, external: _ignoredExternal, ...overridesRest } = overrides;
     const out = { ...base, ...overridesRest };
     if (base.output || overrides.output) {
-        out.output = { ...(base.output ?? {}), ...(overrides.output ?? {}) };
+        out.output = { ...base.output, ...overrides.output };
     }
     if (base.transform || overrides.transform) {
-        out.transform = { ...(base.transform ?? {}), ...(overrides.transform ?? {}) };
+        out.transform = { ...base.transform, ...overrides.transform };
         if (base.transform?.define || overrides.transform?.define) {
-            out.transform.define = { ...(base.transform?.define ?? {}), ...(overrides.transform?.define ?? {}) };
+            out.transform.define = { ...base.transform?.define, ...overrides.transform?.define };
         }
     }
     if (base.resolve || overrides.resolve) {
-        out.resolve = { ...(base.resolve ?? {}), ...(overrides.resolve ?? {}) };
+        out.resolve = { ...base.resolve, ...overrides.resolve };
     }
     return out;
 }

package/lib/utils/oxc-resolve.d.ts

@@ -0,0 +1,63 @@
+export type OxcTool = 'oxlint' | 'oxfmt';
+/**
+ * Resolve the absolute path to a tool's Node ESM launcher
+ * (`node_modules/<tool>/bin/<tool>`). Walks cwd → workspace-root → parents.
+ *
+ * Throws {@link OxcNotFoundError} with a clear install hint when not found.
+ */
+export declare function findOxcLauncher(tool: OxcTool, cwd?: string): string;
+export declare class OxcNotFoundError extends Error {
+    tool: OxcTool;
+    cwd: string;
+    constructor(tool: OxcTool, cwd: string);
+}
+/**
+ * Walk up from a starting directory to find the nearest oxlint config
+ * (`.oxlintrc.json`). Returns absolute path or null.
+ */
+export declare function findOxlintConfig(cwd?: string): string | null;
+/**
+ * Walk up from a starting directory to find the nearest oxfmt config
+ * (`.oxfmtrc` / `.oxfmtrc.json`). Returns absolute path or null.
+ */
+export declare function findOxfmtConfig(cwd?: string): string | null;
+export interface RunOxcOptions {
+    cwd?: string;
+    verbose?: boolean;
+}
+/**
+ * Spawn an oxc tool (oxlint / oxfmt) via its Node ESM launcher. Inherits
+ * stdio so the tool's own output (diagnostics, reformatted files, summary
+ * lines) reaches the user.
+ *
+ * The launcher is run with the current Node executable (`process.execPath`)
+ * so the JS plugin host is available — required for oxlint's `jsPlugins`.
+ *
+ * Returns the exit code; never throws on non-zero exit (callers check it).
+ */
+export declare function runOxc(tool: OxcTool, args: string[], opts?: RunOxcOptions): Promise<number>;
+/** Convenience wrappers. */
+export declare function runOxlint(args: string[], opts?: RunOxcOptions): Promise<number>;
+export declare function runOxfmt(args: string[], opts?: RunOxcOptions): Promise<number>;
+/**
+ * Lazy-load the embedded `.oxlintrc.json` scaffold template. The
+ * static-read-inliner matches this `readFileSync(new URL(<lit>,
+ * import.meta.url), 'utf-8')` shape at build time and inlines the file into
+ * the GJS bundle, so the template is available without runtime file I/O
+ * against the install dir. (Same mechanism the old `loadBiomeTemplate()`
+ * relied on — the shape must stay exactly this for the inliner to fire.)
+ */
+export declare function loadOxlintTemplate(): string;
+/** Lazy-load the embedded `.oxfmtrc` scaffold template (same inliner shape). */
+export declare function loadOxfmtTemplate(): string;
+/** Helper for callers to surface the install hint to the user cleanly. */
+export declare function printOxcNotFound(err: OxcNotFoundError): void;
+/**
+ * Has the given oxc tool's npm package (or its companion) been declared in the
+ * project's dependencies? Useful as a cheap pre-flight check — `gjsify flatpak
+ * init`'s post-format hook uses this to decide whether to auto-format outputs.
+ *
+ * Checks for `oxfmt` by default (the formatter), since that is what the
+ * post-format hook would invoke.
+ */
+export declare function hasOxcDevDep(cwd?: string, tool?: OxcTool): boolean;