cyclops-clientdevbridge-cli 0.1.1

package/dist/initscript.js

@@ -0,0 +1,202 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { coordinate, GROOVY_DEPENDENCY, GROUP, releasesMavenUrl } from './artifacts.js';
+function groovyString(value) {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+/**
+ * Generates the init script the CLI injects at launch, so that a consumer repository never has to
+ * be edited to be driveable (plan §4).
+ *
+ * The run task is configured through `JavaExec` rather than through Loom's or NeoGradle's own run
+ * DSL: both plugins' `runClient` tasks are `JavaExec` subclasses, so one code path covers both
+ * loaders and does not break when either plugin reshuffles its extensions.
+ */
+export function renderInitScript(options) {
+    const dependency = coordinate(options.minecraftVersion, options.loader, options.bridgeVersion);
+    const jvmArgs = [
+        '-Dclientdevbridge.enabled=true',
+        `-Dclientdevbridge.port=${options.port}`,
+        `-Dclientdevbridge.projectDir=${options.projectDir}`,
+        ...(options.evalEnabled ? ['-Dclientdevbridge.eval=true'] : []),
+        ...(options.jdwpPort === null
+            ? []
+            : [`-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=127.0.0.1:${options.jdwpPort}`]),
+        ...(options.extraJvmArgs ?? []),
+    ];
+    const programArgs = [
+        '--username',
+        options.username,
+        '--width',
+        String(options.width),
+        '--height',
+        String(options.height),
+        ...(options.world === null ? [] : ['--quickPlaySingleplayer', options.world]),
+    ];
+    return `// Generated by clientdevbridge-cli. Regenerated on every 'clientdevbridge start'; do not edit.
+// It injects the ClientDevBridge mod into an unmodified consumer checkout and pins the
+// determinism settings the screenshot comparisons depend on.
+
+def clientDevBridgeDependency = ${groovyString(dependency)}
+// The eval escape hatch reaches Groovy through javax.script. It is added here rather than left to
+// transitive resolution because the Cyclops publishing convention emits artifact-only POMs, so the
+// published module carries no dependency metadata for a consumer to resolve.
+def clientDevBridgeGroovy = ${groovyString(GROOVY_DEPENDENCY)}
+// Only the module being launched is touched. A multiloader repo configures every loader module in
+// the same build, and injecting into the ones that are not being run is at best pointless: on the
+// Minecraft 26 toolchain, adding a dependency to Loom's project makes it set Minecraft up before
+// its own mappings configuration is populated, which fails the whole build with an error that
+// names neither this script nor the module it came from.
+def clientDevBridgeTarget = ${groovyString(options.targetProjectPath)}
+def clientDevBridgeJvmArgs = [
+${jvmArgs.map((arg) => `        ${groovyString(arg)}`).join(',\n')}
+]
+def clientDevBridgeProgramArgs = [
+${programArgs.map((arg) => `        ${groovyString(arg)}`).join(',\n')}
+]
+
+allprojects { project ->
+    // Nothing at all is done to the modules that are not being launched. Adding even a repository
+    // to Loom's project is enough to change how it resolves its own mappings.
+    if (project.path != clientDevBridgeTarget) {
+        return
+    }
+
+    // Both repositories are restricted to ClientDevBridge's own group. Adding an unfiltered
+    // repository to somebody else's build is a real hazard -- mavenLocal in particular will shadow
+    // any dependency a stale local build happens to have -- and this script has no business
+    // affecting how the project resolves anything but the bridge.
+    project.repositories {
+        // mavenLocal first, so that a developer working on ClientDevBridge itself picks up
+        // their own './gradlew publishToMavenLocal' build ahead of any released one.
+        mavenLocal {
+            content { includeGroup ${groovyString(GROUP)} }
+        }
+        maven {
+            name = 'ClientDevBridge releases'
+            // A static Maven repository served by GitHub Pages. No credentials block, and that is
+            // the point: the CyclopsMC GitHub Packages Maven needs a token even for public
+            // packages, so a consumer would have to set one up before they could launch a client.
+            url = ${groovyString(releasesMavenUrl())}
+            content { includeGroup ${groovyString(GROUP)} }
+        }
+    }
+
+${options.loader === 'fabric'
+        ? `    // Which configuration a runtime mod belongs in differs between Loom generations -- 1.15
+    // dropped modLocalRuntime -- so the name is looked up rather than assumed. That keeps this
+    // working across Minecraft versions without the CLI tracking each toolchain's configuration
+    // names on top of everything else it already has to know.
+    def firstExisting = { String... names ->
+        for (String candidate : names) {
+            if (project.configurations.findByName(candidate) != null) {
+                return candidate
+            }
+        }
+        return 'runtimeOnly'
+    }
+`
+        : ''}
+    // Which loader this is comes from the CLI, which already had to decide before it could pick the
+    // artifact to inject. Asking Gradle instead is not free: registering a
+    // plugins.withId('net.fabricmc.fabric-loom') callback -- even an empty one -- is enough to make
+    // Loom 1.15 set Minecraft up before the build script's dependencies { } block has run, and the
+    // build dies with "Configuration 'mappings' has no dependencies", naming neither this script
+    // nor what it did.
+    //
+    // The additions are deferred to afterEvaluate for a related reason: adding to a Loom-managed
+    // configuration while the build script is still being evaluated has the same effect.
+    project.afterEvaluate {
+${options.loader === 'fabric'
+        ? `        project.dependencies.add(firstExisting('modLocalRuntime', 'localRuntime', 'runtimeOnly'),
+                clientDevBridgeDependency)
+        // Groovy is a plain library, not a mod, so it must never go through Loom's remapping.
+        project.dependencies.add('runtimeOnly', clientDevBridgeGroovy)`
+        : `        // NeoGradle and ModDevGradle both discover mods from the runtime classpath directly,
+        // and ModDevGradle 2 rejects additionalRuntimeClasspath outright, telling callers to
+        // use a standard configuration instead.
+        project.dependencies.add('runtimeOnly', clientDevBridgeDependency)
+        project.dependencies.add('runtimeOnly', clientDevBridgeGroovy)`}
+    }
+
+    project.tasks.matching { it.name == 'runClient' }.configureEach { task ->
+        if (task instanceof JavaExec) {
+            task.jvmArgs(clientDevBridgeJvmArgs)
+            // Program arguments go through an argument provider rather than args(). Gradle emits
+            // every static argument before every provider's, and ModDevGradle passes the real main
+            // class through a provider -- so appending statically puts our first argument ahead of
+            // it, and the launcher tries to load '--username' as the main class. Registering a
+            // provider last keeps ours genuinely last.
+            task.argumentProviders.add({ clientDevBridgeProgramArgs } as org.gradle.process.CommandLineArgumentProvider)
+        } else {
+            project.logger.warn("ClientDevBridge: task \${task.path} is not a JavaExec, so its JVM arguments were not set. " +
+                    'Report this with the loader and plugin versions at https://github.com/CyclopsMC/clientdevbridge-cli/issues')
+        }
+    }
+}
+`;
+}
+/**
+ * The client options that make screenshots reproducible from one run to the next.
+ *
+ * Anything that animates, adapts to the machine, or depends on focus is turned off; without this,
+ * `compare` against a golden image is noise.
+ */
+export const DETERMINISM_OPTIONS = {
+    guiScale: '2',
+    pauseOnLostFocus: 'false',
+    enableVsync: 'false',
+    maxFps: '60',
+    renderClouds: '"false"',
+    particles: '2',
+    ao: 'false',
+    entityShadows: 'false',
+    bobView: 'false',
+    fov: '0.0',
+    gamma: '0.0',
+    darkMojangStudiosBackground: 'true',
+    narrator: '0',
+    soundCategory_master: '0.0',
+    tutorialStep: 'none',
+    skipMultiplayerWarning: 'true',
+    onboardAccessibility: 'false',
+    fullscreen: 'false',
+};
+/**
+ * Writes the determinism options into the run directory's `options.txt`.
+ *
+ * Keys the caller did not ask about are preserved, so a hand-tuned dev options file survives.
+ */
+export function pinOptions(runDir) {
+    const optionsFile = path.join(runDir, 'options.txt');
+    fs.mkdirSync(runDir, { recursive: true });
+    const existing = new Map();
+    const order = [];
+    const created = !fs.existsSync(optionsFile);
+    if (!created) {
+        for (const line of fs.readFileSync(optionsFile, 'utf8').split('\n')) {
+            const separator = line.indexOf(':');
+            if (separator > 0) {
+                const key = line.slice(0, separator);
+                existing.set(key, line.slice(separator + 1));
+                order.push(key);
+            }
+        }
+    }
+    const changed = [];
+    for (const [key, value] of Object.entries(DETERMINISM_OPTIONS)) {
+        if (existing.get(key) !== value) {
+            if (existing.has(key)) {
+                changed.push(key);
+            }
+            else {
+                order.push(key);
+            }
+            existing.set(key, value);
+        }
+    }
+    const rendered = order.map((key) => `${key}:${existing.get(key)}`).join('\n');
+    fs.writeFileSync(optionsFile, `${rendered}\n`, 'utf8');
+    return { created, changed };
+}
+//# sourceMappingURL=initscript.js.map

package/dist/initscript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"initscript.js","sourceRoot":"","sources":["../src/initscript.ts"],"names":[],"mappings":"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"}

package/dist/java.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Finding the JDK Gradle will run on.
+ *
+ * This matters more than it looks like it should. The loader plugins check the JDK *Gradle itself*
+ * is running on, not the toolchain: Loom refuses to configure a Minecraft 26 project when Gradle
+ * runs on Java 21, with an error that arrives during configuration and never mentions JAVA_HOME.
+ * And Gradle takes that JDK from `JAVA_HOME`, not from `java` on the PATH, so a machine with a
+ * newer `java` first on the PATH and an older `JAVA_HOME` looks fine and is not.
+ */
+export interface JavaProbe {
+    /** The JDK's home directory, or null when it was found on the PATH with no home to name. */
+    readonly home: string | null;
+    readonly major: number | null;
+    /** Human-readable first line of `java -version`, for reporting. */
+    readonly versionLine: string | null;
+    /** Where this JDK came from, e.g. `JAVA_HOME` or `PATH`. */
+    readonly source: string;
+}
+export declare function javaBinary(home: string | null): string;
+/** Runs `java -version` and reads the major version out of it. */
+export declare function probeJava(home: string | null, source: string): JavaProbe;
+/** The JDK Gradle would use with no help: `JAVA_HOME` when set, the PATH otherwise. */
+export declare function gradleJava(): JavaProbe;
+/**
+ * Looks for an installed JDK of at least `requiredMajor`, preferring the lowest version that
+ * qualifies: a mod that asks for Java 21 is built and tested on 21, and running Gradle on a much
+ * newer JDK than the project expects trades one class of surprise for another.
+ *
+ * @return the JDK's home directory, or null when the machine has none
+ */
+export declare function findJavaHome(requiredMajor: number): JavaProbe | null;
+export interface JavaResolution {
+    /** What Gradle should be run with; null means "leave the environment alone". */
+    readonly javaHome: string | null;
+    readonly probe: JavaProbe;
+    /** Set when the environment's own JDK was too old and another one was found. */
+    readonly substituted: boolean;
+}
+/**
+ * Decides which JDK to run Gradle on.
+ *
+ * The environment's own choice wins whenever it is new enough — a developer who set `JAVA_HOME`
+ * meant it. Only when it would fail outright does this go looking, and the caller says so rather
+ * than silently running on a JDK nobody asked for.
+ */
+export declare function resolveJavaHome(requiredMajor: number): JavaResolution;
+//# sourceMappingURL=java.d.ts.map

package/dist/java.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"java.d.ts","sourceRoot":"","sources":["../src/java.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AAEH,MAAM,WAAW,SAAS;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAEtD;AAED,kEAAkE;AAClE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAexE;AAED,uFAAuF;AACvF,wBAAgB,UAAU,IAAI,SAAS,CAKtC;AA2CD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAkBpE;AAED,MAAM,WAAW,cAAc;IAC7B,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,cAAc,CAUrE"}

package/dist/java.js

@@ -0,0 +1,114 @@
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+export function javaBinary(home) {
+    return home === null ? 'java' : path.join(home, 'bin', process.platform === 'win32' ? 'java.exe' : 'java');
+}
+/** Runs `java -version` and reads the major version out of it. */
+export function probeJava(home, source) {
+    // `java -version` reports on stderr, and some environments prepend a JAVA_TOOL_OPTIONS notice,
+    // so both streams are read and searched rather than just stdout.
+    const probe = spawnSync(javaBinary(home), ['-version'], { encoding: 'utf8' });
+    const output = `${probe.stdout ?? ''}\n${probe.stderr ?? ''}`;
+    const versionLine = output
+        .split('\n')
+        .map((entry) => entry.trim())
+        .find((entry) => entry.includes('version "')) ?? null;
+    const match = /version "(\d+)(?:\.(\d+))?/.exec(output);
+    // Java 8 and older report `1.8.0`; the major version is the second component there.
+    const major = match === null ? null : Number(match[1]) === 1 ? Number(match[2] ?? '0') : Number(match[1]);
+    return { home, major: Number.isNaN(major) ? null : major, versionLine, source };
+}
+/** The JDK Gradle would use with no help: `JAVA_HOME` when set, the PATH otherwise. */
+export function gradleJava() {
+    const home = process.env['JAVA_HOME'];
+    return home === undefined || home.length === 0
+        ? probeJava(null, 'PATH')
+        : probeJava(home, 'JAVA_HOME');
+}
+/**
+ * Directories that conventionally hold one JDK each. Deliberately a short list of the layouts a
+ * mod developer's machine actually has, rather than a filesystem search.
+ */
+function candidateRoots() {
+    const home = os.homedir();
+    return [
+        '/usr/lib/jvm',
+        '/usr/java',
+        path.join(home, '.sdkman', 'candidates', 'java'),
+        path.join(home, '.gradle', 'jdks'),
+        '/Library/Java/JavaVirtualMachines',
+        'C:\\Program Files\\Java',
+        'C:\\Program Files\\Eclipse Adoptium',
+    ];
+}
+function javaHomesIn(root) {
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const homes = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() && !entry.isSymbolicLink()) {
+            continue;
+        }
+        const base = path.join(root, entry.name);
+        // macOS buries the home one level down; everywhere else the directory is the home.
+        for (const candidate of [base, path.join(base, 'Contents', 'Home')]) {
+            if (fs.existsSync(javaBinary(candidate))) {
+                homes.push(candidate);
+                break;
+            }
+        }
+    }
+    return homes;
+}
+/**
+ * Looks for an installed JDK of at least `requiredMajor`, preferring the lowest version that
+ * qualifies: a mod that asks for Java 21 is built and tested on 21, and running Gradle on a much
+ * newer JDK than the project expects trades one class of surprise for another.
+ *
+ * @return the JDK's home directory, or null when the machine has none
+ */
+export function findJavaHome(requiredMajor) {
+    const found = [];
+    const seen = new Set();
+    for (const root of candidateRoots()) {
+        for (const home of javaHomesIn(root)) {
+            const real = fs.existsSync(home) ? fs.realpathSync(home) : home;
+            if (seen.has(real)) {
+                continue;
+            }
+            seen.add(real);
+            const probe = probeJava(home, root);
+            if (probe.major !== null && probe.major >= requiredMajor) {
+                found.push(probe);
+            }
+        }
+    }
+    found.sort((left, right) => (left.major ?? 0) - (right.major ?? 0));
+    return found[0] ?? null;
+}
+/**
+ * Decides which JDK to run Gradle on.
+ *
+ * The environment's own choice wins whenever it is new enough — a developer who set `JAVA_HOME`
+ * meant it. Only when it would fail outright does this go looking, and the caller says so rather
+ * than silently running on a JDK nobody asked for.
+ */
+export function resolveJavaHome(requiredMajor) {
+    const current = gradleJava();
+    if (current.major !== null && current.major >= requiredMajor) {
+        return { javaHome: current.home, probe: current, substituted: false };
+    }
+    const found = findJavaHome(requiredMajor);
+    if (found === null || found.home === null) {
+        return { javaHome: current.home, probe: current, substituted: false };
+    }
+    return { javaHome: found.home, probe: found, substituted: true };
+}
+//# sourceMappingURL=java.js.map

package/dist/java.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"java.js","sourceRoot":"","sources":["../src/java.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAsBlC,MAAM,UAAU,UAAU,CAAC,IAAmB;IAC5C,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7G,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,SAAS,CAAC,IAAmB,EAAE,MAAc;IAC3D,+FAA+F;IAC/F,iEAAiE;IACjE,MAAM,KAAK,GAAG,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9E,MAAM,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,IAAI,EAAE,KAAK,KAAK,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;IAC9D,MAAM,WAAW,GACf,MAAM;SACH,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;SAC5B,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,IAAI,IAAI,CAAC;IAC1D,MAAM,KAAK,GAAG,4BAA4B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACxD,oFAAoF;IACpF,MAAM,KAAK,GACT,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9F,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;AAClF,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,UAAU;IACxB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACtC,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAC5C,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC;QACzB,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;AACnC,CAAC;AAED;;;GAGG;AACH,SAAS,cAAc;IACrB,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;IAC1B,OAAO;QACL,cAAc;QACd,WAAW;QACX,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,CAAC;QAChD,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC;QAClC,mCAAmC;QACnC,yBAAyB;QACzB,qCAAqC;KACtC,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,OAAoB,CAAC;IACzB,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,EAAE,EAAE,CAAC;YACpD,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACzC,mFAAmF;QACnF,KAAK,MAAM,SAAS,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;YACpE,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;gBACzC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBACtB,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,aAAqB;IAChD,MAAM,KAAK,GAAgB,EAAE,CAAC;IAC9B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,EAAE,CAAC;QACpC,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAChE,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnB,SAAS;YACX,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACf,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACpC,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,KAAK,IAAI,aAAa,EAAE,CAAC;gBACzD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpB,CAAC;QACH,CAAC;IACH,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC;IACpE,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAC1B,CAAC;AAUD;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,aAAqB;IACnD,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,KAAK,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,IAAI,aAAa,EAAE,CAAC;QAC7D,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;IACxE,CAAC;IACD,MAAM,KAAK,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;IAC1C,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QAC1C,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;IACxE,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;AACnE,CAAC"}

package/dist/launcher.d.ts

@@ -0,0 +1,104 @@
+import { type Loader } from './detect.js';
+import { type Session } from './session.js';
+export declare const DEFAULT_PORT = 25599;
+export declare const DEFAULT_WIDTH = 854;
+export declare const DEFAULT_HEIGHT = 480;
+export declare const DEFAULT_USERNAME = "ClientDevBridge";
+export interface StartOptions {
+    readonly projectDir: string;
+    readonly loader?: Loader | undefined;
+    readonly minecraftVersion?: string | undefined;
+    readonly bridgeVersion?: string | undefined;
+    readonly world?: string | undefined;
+    readonly headed: boolean;
+    readonly port: number;
+    readonly timeoutMs: number;
+    readonly gradleArgs: readonly string[];
+    readonly width: number;
+    readonly height: number;
+    readonly evalEnabled: boolean;
+    readonly pinOptions: boolean;
+    readonly jdwpPort: number | null;
+    readonly onProgress?: (line: string) => void;
+}
+/**
+ * Best-effort identification of whatever holds a port, for the orphaned-client message.
+ * Returns null when the platform has no tool for it; this is a nicety, never a requirement.
+ */
+/**
+ * Removes Loom's cached *remapped* copy of the bridge mod.
+ *
+ * Loom remaps every mod on the dev runtime classpath and caches the result keyed by group,
+ * artifact and version. A local build republished under the same version (`1.0.0-DEV`, say) is
+ * therefore never re-read: the client silently keeps running the previous build, which looks
+ * exactly like the new code having no effect. NeoGradle uses the jar directly and does not have
+ * this problem, so it only ever bites on Fabric — and only while developing ClientDevBridge
+ * itself, which is precisely when it is most confusing.
+ *
+ * Only local builds are affected: a released version is immutable, so its cache entry is correct.
+ */
+export declare function clearLoomRemapCache(projectDir: string, minecraftVersion: string, loader: Loader): string[];
+/**
+ * Asks whatever is listening on the bridge port who it is.
+ *
+ * A client on the port is not automatically an orphan: a mod developer with two checkouts open
+ * hits this constantly, and telling them to `kill` a perfectly healthy client of their own is bad
+ * advice given confidently. A ClientDevBridge client answers with the project it belongs to.
+ */
+export declare function describeBridgeOnPort(port: number): Promise<{
+    projectDir: string | null;
+    mcVersion: string;
+    loader: string;
+} | null>;
+/** What to tell someone whose bridge port is already taken. */
+export declare function hintForOccupiedPort(port: number, owner: string | null, bridge: {
+    projectDir: string | null;
+    mcVersion: string;
+    loader: string;
+} | null, thisProject: string): string;
+export declare function describePortOwner(port: number): string | null;
+/**
+ * Whether nothing is listening on this port, on any loopback address.
+ *
+ * Both families are probed because a client can be on either -- see LOOPBACK_HOSTS. Treating a
+ * client on ::1 as "the port is free" is the worst of the two errors: `start` would launch a
+ * second one and then wait out its whole timeout for the first.
+ */
+export declare function isPortFree(port: number): Promise<boolean>;
+/**
+ * Launches a client and waits until it answers the handshake.
+ *
+ * The process is detached into its own group so it survives this short-lived CLI invocation;
+ * `stop` later kills the whole group, which is what actually reaps Gradle's forked JVM.
+ */
+export declare function start(options: StartOptions): Promise<{
+    session: Session;
+    hello: unknown;
+}>;
+export declare function newestInMavenLocal(minecraftVersion: string, loader: Loader): string | null;
+/**
+ * Asks the client JVM to print every thread's stack into the game log.
+ *
+ * SIGQUIT makes a JVM dump its threads to its own stdout, which the launcher is already capturing
+ * into gradle.log -- so the evidence ends up in the file the error message points at, with no
+ * debugger and no second run.
+ *
+ * Only the client JVM is signalled, located by the system property that launched it. Signalling
+ * the process group instead would reach xvfb-run and Xvfb, for which SIGQUIT is fatal: that would
+ * take the display down and destroy the very evidence being collected.
+ *
+ * @return whether a dump was requested from at least one process
+ */
+export declare function requestThreadDump(): Promise<boolean>;
+export declare function tailFile(file: string, lines: number): string;
+/** Reads at most the last {@link GRADLE_LOG_MAX_BYTES} of a file, so a huge log cannot blow up memory. */
+export declare function readTruncated(file: string): string;
+/**
+ * Kills the whole process group, so Gradle, xvfb-run, and the forked client JVM all go together.
+ */
+export declare function stop(projectDir: string, port?: number): Promise<{
+    stopped: boolean;
+    wasStale: boolean;
+    orphan: string | null;
+}>;
+//# sourceMappingURL=launcher.d.ts.map

package/dist/launcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launcher.d.ts","sourceRoot":"","sources":["../src/launcher.ts"],"names":[],"mappings":"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"}