@bitmagic/cli 0.1.55-dev.0 → 0.1.55-dev.2

package/dist/ios/xcodebuild.d.ts

@@ -0,0 +1,71 @@
+/** Refuses early, with the remedy, on machines that cannot build iOS at all. */
+export declare function preflightXcodebuild(platform?: typeof process.platform): void;
+export interface SimulatorBuildOptions {
+    xcodeprojDir: string;
+    derivedDataDir: string;
+    productName: string;
+    log: (message: string) => void;
+}
+export interface SimulatorBuildResult {
+    appPath: string;
+    /** True when the asset-catalog fallback fired and the app shipped without its icon. */
+    iconSkipped: boolean;
+}
+/**
+ * Build the unsigned Simulator .app and return its path.
+ *
+ * Deliberately the destination-free `-target -sdk iphonesimulator` form, not `-scheme` with a
+ * destination: destination resolution refuses outright on a Mac whose Xcode has no iOS DEVICE
+ * platform installed (a fresh install commonly has only simulators), while the target build
+ * needs nothing but the simulator SDK.
+ *
+ * The retry handles the other fresh-Xcode gap: actool refuses to compile an asset catalog when
+ * no installed simulator runtime matches the SDK (an SDK-bumped Xcode before the matching
+ * runtime download). The app then builds without its icon — cosmetic on a simulator — and the
+ * caller says so, with the real remedy.
+ */
+export declare function buildSimulatorApp(options: SimulatorBuildOptions): SimulatorBuildResult;
+export interface ArchiveOptions {
+    xcodeprojDir: string;
+    derivedDataDir: string;
+    distDir: string;
+    productName: string;
+    teamId: string;
+    log: (message: string) => void;
+}
+export interface ArchiveResult {
+    archivePath: string;
+    ipaPath: string;
+}
+/** Archive for device and export a signed .ipa. Signing errors surface with xcodebuild's tail. */
+export declare function archiveAndExportIpa(options: ArchiveOptions): ArchiveResult;
+export interface SubmitOptions {
+    archivePath: string;
+    distDir: string;
+    teamId: string;
+    keyPath: string;
+    keyId: string;
+    issuerId: string;
+    log: (message: string) => void;
+}
+/** Upload the archive to App Store Connect — the headless path now that altool is gone. */
+export declare function uploadArchive(options: SubmitOptions): void;
+interface SimctlDevice {
+    udid: string;
+    name: string;
+    state: string;
+    isAvailable: boolean;
+}
+/**
+ * The simulator to run on: whatever is already booted, else the newest available iPhone.
+ * Exported for tests; the runtime keys sort lexicographically into version order within the
+ * same major-number width, which is as much precision as "pick a recent phone" needs.
+ */
+export declare function chooseSimulator(devicesByRuntime: Record<string, SimctlDevice[]>): {
+    udid: string;
+    name: string;
+    booted: boolean;
+} | null;
+/** Boot (if needed) a simulator, install the app, launch the bundle — the `--run` tail. */
+export declare function runOnSimulator(appPath: string, bundleId: string, log: (m: string) => void): void;
+export {};

package/dist/ios/xcodebuild.js

@@ -0,0 +1,216 @@
+/**
+ * Everything that shells out: xcodebuild (simulator build, archive, export, upload) and simctl
+ * (boot/install/launch for `--run`). Preflights name their remedy — an agent told "build
+ * failed" with no cause would start editing game code over a missing Xcode.
+ */
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { CliError, errnoCode } from '../errors.js';
+import { TARGET_NAME } from './xcode-template.js';
+const MAX_TOOL_OUTPUT = 64 * 1024 * 1024;
+/** How much of a failed tool's output to replay — enough to carry the actual error. */
+const FAILURE_TAIL_LINES = 60;
+function run(command, args, options = {}) {
+    const result = spawnSync(command, args, {
+        cwd: options.cwd,
+        encoding: 'utf-8',
+        maxBuffer: MAX_TOOL_OUTPUT,
+    });
+    if (result.error) {
+        if (errnoCode(result.error) === 'ENOENT') {
+            throw new CliError(`\`${command}\` is not available. Building for iOS needs Xcode — install it from the `
+                + 'App Store, then run `sudo xcode-select -s /Applications/Xcode.app` and try again.', 3);
+        }
+        throw new CliError(`Could not run ${command}: ${result.error.message}`);
+    }
+    return { status: result.status ?? 1, output: `${result.stdout ?? ''}${result.stderr ?? ''}` };
+}
+function failWithTail(what, output, exitCode) {
+    const tail = output.split('\n').slice(-FAILURE_TAIL_LINES).join('\n');
+    throw new CliError(`${what} failed:\n${tail}`, exitCode);
+}
+/** Refuses early, with the remedy, on machines that cannot build iOS at all. */
+export function preflightXcodebuild(platform = process.platform) {
+    if (platform !== 'darwin') {
+        throw new CliError('Building for iOS needs macOS with Xcode — this machine is not a Mac. '
+            + 'Run `bitmagic ios build` on a Mac with Xcode installed.', 3);
+    }
+    const probe = run('xcodebuild', ['-version']);
+    if (probe.status !== 0) {
+        throw new CliError('Xcode is present but `xcodebuild -version` failed. If you only have the Command Line '
+            + 'Tools, install full Xcode and run `sudo xcode-select -s /Applications/Xcode.app`.\n'
+            + probe.output.trim(), 3);
+    }
+}
+/**
+ * Build the unsigned Simulator .app and return its path.
+ *
+ * Deliberately the destination-free `-target -sdk iphonesimulator` form, not `-scheme` with a
+ * destination: destination resolution refuses outright on a Mac whose Xcode has no iOS DEVICE
+ * platform installed (a fresh install commonly has only simulators), while the target build
+ * needs nothing but the simulator SDK.
+ *
+ * The retry handles the other fresh-Xcode gap: actool refuses to compile an asset catalog when
+ * no installed simulator runtime matches the SDK (an SDK-bumped Xcode before the matching
+ * runtime download). The app then builds without its icon — cosmetic on a simulator — and the
+ * caller says so, with the real remedy.
+ */
+export function buildSimulatorApp(options) {
+    options.log('Building the Simulator app (first build can take a couple of minutes)…');
+    const baseArgs = [
+        '-project', options.xcodeprojDir,
+        '-target', TARGET_NAME,
+        '-configuration', 'Release',
+        '-sdk', 'iphonesimulator',
+        'build',
+        'CODE_SIGNING_ALLOWED=NO',
+        `SYMROOT=${path.join(options.derivedDataDir, 'Build', 'Products')}`,
+    ];
+    let iconSkipped = false;
+    let result = run('xcodebuild', baseArgs);
+    if (result.status !== 0 && result.output.includes('No simulator runtime version')) {
+        iconSkipped = true;
+        result = run('xcodebuild', [
+            ...baseArgs,
+            'EXCLUDED_SOURCE_FILE_NAMES=Assets.xcassets',
+            'ASSETCATALOG_COMPILER_APPICON_NAME=',
+        ]);
+    }
+    if (result.status !== 0)
+        failWithTail('xcodebuild (simulator)', result.output, 1);
+    const appPath = path.join(options.derivedDataDir, 'Build', 'Products', 'Release-iphonesimulator', `${options.productName}.app`);
+    if (!fs.existsSync(appPath)) {
+        throw new CliError(`xcodebuild reported success but ${appPath} does not exist.`);
+    }
+    return { appPath, iconSkipped };
+}
+function exportOptionsPlist(teamId, destination) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+\t<key>method</key>
+\t<string>app-store-connect</string>
+\t<key>destination</key>
+\t<string>${destination}</string>
+\t<key>signingStyle</key>
+\t<string>automatic</string>
+\t<key>teamID</key>
+\t<string>${teamId}</string>
+</dict>
+</plist>
+`;
+}
+/** Archive for device and export a signed .ipa. Signing errors surface with xcodebuild's tail. */
+export function archiveAndExportIpa(options) {
+    fs.mkdirSync(options.distDir, { recursive: true });
+    const archivePath = path.join(options.distDir, `${TARGET_NAME}.xcarchive`);
+    options.log('Archiving for devices (signing happens here)…');
+    const archived = run('xcodebuild', [
+        '-project', options.xcodeprojDir,
+        '-scheme', TARGET_NAME,
+        '-configuration', 'Release',
+        '-destination', 'generic/platform=iOS',
+        '-derivedDataPath', options.derivedDataDir,
+        '-archivePath', archivePath,
+        'archive',
+        `DEVELOPMENT_TEAM=${options.teamId}`,
+        '-allowProvisioningUpdates',
+    ]);
+    if (archived.status !== 0)
+        failWithTail('xcodebuild archive', archived.output, 6);
+    const plistPath = path.join(options.distDir, 'export-options.plist');
+    fs.writeFileSync(plistPath, exportOptionsPlist(options.teamId, 'export'));
+    options.log('Exporting the signed .ipa…');
+    const exported = run('xcodebuild', [
+        '-exportArchive',
+        '-archivePath', archivePath,
+        '-exportOptionsPlist', plistPath,
+        '-exportPath', options.distDir,
+        '-allowProvisioningUpdates',
+    ]);
+    if (exported.status !== 0)
+        failWithTail('xcodebuild -exportArchive', exported.output, 6);
+    const ipaPath = path.join(options.distDir, `${options.productName}.ipa`);
+    if (!fs.existsSync(ipaPath)) {
+        throw new CliError(`Export reported success but ${ipaPath} does not exist.`, 6);
+    }
+    return { archivePath, ipaPath };
+}
+/** Upload the archive to App Store Connect — the headless path now that altool is gone. */
+export function uploadArchive(options) {
+    const plistPath = path.join(options.distDir, 'upload-options.plist');
+    fs.mkdirSync(options.distDir, { recursive: true });
+    fs.writeFileSync(plistPath, exportOptionsPlist(options.teamId, 'upload'));
+    options.log('Uploading to App Store Connect (this can take several minutes)…');
+    const uploaded = run('xcodebuild', [
+        '-exportArchive',
+        '-archivePath', options.archivePath,
+        '-exportOptionsPlist', plistPath,
+        '-authenticationKeyPath', options.keyPath,
+        '-authenticationKeyID', options.keyId,
+        '-authenticationKeyIssuerID', options.issuerId,
+        '-allowProvisioningUpdates',
+    ]);
+    if (uploaded.status !== 0)
+        failWithTail('xcodebuild upload', uploaded.output, 6);
+}
+/**
+ * The simulator to run on: whatever is already booted, else the newest available iPhone.
+ * Exported for tests; the runtime keys sort lexicographically into version order within the
+ * same major-number width, which is as much precision as "pick a recent phone" needs.
+ */
+export function chooseSimulator(devicesByRuntime) {
+    const runtimes = Object.keys(devicesByRuntime).sort().reverse();
+    for (const runtime of runtimes) {
+        const booted = devicesByRuntime[runtime].find((device) => device.state === 'Booted');
+        if (booted)
+            return { udid: booted.udid, name: booted.name, booted: true };
+    }
+    for (const runtime of runtimes) {
+        if (!runtime.includes('iOS'))
+            continue;
+        const phone = devicesByRuntime[runtime].find((device) => device.isAvailable && device.name.includes('iPhone'));
+        if (phone)
+            return { udid: phone.udid, name: phone.name, booted: false };
+    }
+    return null;
+}
+/** Boot (if needed) a simulator, install the app, launch the bundle — the `--run` tail. */
+export function runOnSimulator(appPath, bundleId, log) {
+    const listed = run('xcrun', ['simctl', 'list', 'devices', '--json']);
+    if (listed.status !== 0)
+        failWithTail('simctl list', listed.output, 1);
+    let devices;
+    try {
+        devices = JSON.parse(listed.output).devices;
+    }
+    catch {
+        throw new CliError('Could not parse `simctl list devices --json` output.');
+    }
+    const chosen = chooseSimulator(devices);
+    if (chosen === null) {
+        throw new CliError('No iPhone simulator is available. Open Xcode → Settings → Platforms and install an iOS '
+            + 'simulator runtime, then run again.', 3);
+    }
+    if (!chosen.booted) {
+        log(`Booting ${chosen.name}…`);
+        const booted = run('xcrun', ['simctl', 'boot', chosen.udid]);
+        // "Unable to boot device in current state: Booted" is a benign race with the UI.
+        if (booted.status !== 0 && !booted.output.includes('current state: Booted')) {
+            failWithTail('simctl boot', booted.output, 1);
+        }
+    }
+    // Fronts the Simulator window so the creator actually sees the game; harmless when headless.
+    run('open', ['-a', 'Simulator']);
+    log(`Installing on ${chosen.name}…`);
+    const installed = run('xcrun', ['simctl', 'install', chosen.udid, appPath]);
+    if (installed.status !== 0)
+        failWithTail('simctl install', installed.output, 1);
+    const launched = run('xcrun', ['simctl', 'launch', chosen.udid, bundleId]);
+    if (launched.status !== 0)
+        failWithTail('simctl launch', launched.output, 1);
+    log(`Launched ${bundleId} on ${chosen.name}.`);
+}
+//# sourceMappingURL=xcodebuild.js.map

package/dist/ios/xcodebuild.js.map

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

package/dist/project/jobs.d.ts

@@ -1,7 +1,7 @@
 import type { ForgeProgressSnapshot } from '../forge/progress.js';
 import type { ForgeLayoutMap } from '@bitmagic/world-forger/pipeline/index.js';
 /** Which command is running. Shown as-is in the dev view, so these are creator-facing words. */
-export type JobKind = 'skybox' | 'background' | 'block-type' | 'sound' | 'image' | 'character' | 'animation' | 'prop' | 'vehicle' | 'forge' | 'cover' | 'hq' | 'judge' | 'upload' | 'model';
+export type JobKind = 'skybox' | 'background' | 'block-type' | 'sound' | 'image' | 'character' | 'animation' | 'prop' | 'vehicle' | 'forge' | 'cover' | 'reference' | 'hq' | 'judge' | 'upload' | 'model';
 export interface JobRecord {
     jobId: string;
     kind: JobKind;

package/dist/project/reference-file.d.ts

@@ -0,0 +1,44 @@
+import type { CommandRunDeps } from '../commands/run-deps.js';
+import { type ReferenceFlagArgs, type ResolvedReference } from './reference.js';
+/** Far above any sane reference image; the cap exists so a mispassed video fails with a size, not a timeout. */
+export declare const MAX_REFERENCE_FILE_BYTES: number;
+/** The three formats the whole reference lane round-trips (api-server's forge fetch enforces the same set). */
+export declare function sniffImageContentType(bytes: Buffer): {
+    contentType: string;
+    extension: string;
+} | null;
+/**
+ * Read a local image and re-host it under the game's bucket, returning the public URL.
+ *
+ * Every refusal happens BEFORE the network: an unreadable path, a non-image, an oversized file
+ * each cost nothing and name the fix. Content-addressed filename, so re-sending the same picture
+ * twice at least reads as the same picture in the bucket listing (the upload key still gets a
+ * server-side timestamp prefix, so this is legibility, not dedup).
+ */
+export declare function uploadReferenceImageFile(options: {
+    root: string;
+    gameId: string;
+    filePath: string;
+    deps: CommandRunDeps;
+}): Promise<{
+    url: string;
+    contentType: string;
+}>;
+/** The file-flag sibling of ReferenceFlagArgs — commands that take `--reference-image <file>`. */
+export interface ReferenceFileFlagArgs extends ReferenceFlagArgs {
+    'reference-image'?: string;
+}
+/**
+ * The full per-call resolution, file flag included: `--reference-image <file>` is uploaded and
+ * wins (it IS the caller choosing, like the URL flag), then the URL-flag/`--no-reference`/project
+ * precedence of {@link resolveReferenceImageUrl}. Both flags together is two answers to the same
+ * question and is refused.
+ */
+export declare function resolveReferenceForCall(options: {
+    args: ReferenceFileFlagArgs;
+    root: string;
+    gameId: string;
+    deps: CommandRunDeps;
+    /** One line when a file was uploaded, so the agent sees the URL its picture became. */
+    log: (message: string) => void;
+}): Promise<ResolvedReference>;

package/dist/project/reference-file.js

@@ -0,0 +1,94 @@
+/**
+ * Per-call reference images from LOCAL FILES — the "make a world like this [image]" case.
+ *
+ * The accepted project reference (reference.ts) answers "what does this game look like"; this
+ * module answers "what should THIS generation look like", when the creator hands their agent an
+ * actual picture. The generators upstream take only URLs, so a local file has to become one
+ * first: it is uploaded to the game's own bucket (the same signed-upload lane `bitmagic assets
+ * add` and `reference accept` use) and the resulting public URL rides the call as
+ * `referenceImageUrl` — outranking the accepted project reference exactly as an explicit
+ * `--reference-image-url` does, because both are the caller choosing.
+ *
+ * Nothing is recorded: a per-call reference is a one-off by definition. The command that wants
+ * the picture to BECOME the project's look is `bitmagic reference accept <file>`.
+ */
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import { CliError } from '../errors.js';
+import { resolveEnvironmentForCommand, resolveAuth0ClientId } from '../config/environments.js';
+import { getAccessToken } from '../auth/session.js';
+import { uploadProjectFile } from '../http/signed-upload.js';
+import { resolveReferenceImageUrl } from './reference.js';
+/** Far above any sane reference image; the cap exists so a mispassed video fails with a size, not a timeout. */
+export const MAX_REFERENCE_FILE_BYTES = 20 * 1024 * 1024;
+/** The three formats the whole reference lane round-trips (api-server's forge fetch enforces the same set). */
+export function sniffImageContentType(bytes) {
+    if (bytes.length >= 4 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) {
+        return { contentType: 'image/png', extension: 'png' };
+    }
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+        return { contentType: 'image/jpeg', extension: 'jpg' };
+    }
+    if (bytes.length >= 12 && bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP') {
+        return { contentType: 'image/webp', extension: 'webp' };
+    }
+    return null;
+}
+/**
+ * Read a local image and re-host it under the game's bucket, returning the public URL.
+ *
+ * Every refusal happens BEFORE the network: an unreadable path, a non-image, an oversized file
+ * each cost nothing and name the fix. Content-addressed filename, so re-sending the same picture
+ * twice at least reads as the same picture in the bucket listing (the upload key still gets a
+ * server-side timestamp prefix, so this is legibility, not dedup).
+ */
+export async function uploadReferenceImageFile(options) {
+    const { root, gameId, filePath, deps } = options;
+    let bytes;
+    try {
+        bytes = fs.readFileSync(filePath);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CliError(`Could not read the reference image ${filePath}: ${message}`);
+    }
+    const sniffed = sniffImageContentType(bytes);
+    if (!sniffed) {
+        throw new CliError(`${filePath} is not a PNG, JPEG or WebP image — those are the formats the generators accept as a reference.`);
+    }
+    if (bytes.byteLength > MAX_REFERENCE_FILE_BYTES) {
+        throw new CliError(`${filePath} is ${Math.round(bytes.byteLength / (1024 * 1024))}MB — a reference image must be at most ` +
+            `${Math.floor(MAX_REFERENCE_FILE_BYTES / (1024 * 1024))}MB.`);
+    }
+    const environment = resolveEnvironmentForCommand({ cwd: root, baseDir: deps.baseDir });
+    const clientId = resolveAuth0ClientId(environment);
+    const token = await getAccessToken(environment, clientId, { fetch: deps.fetch, sleep: deps.sleep, now: deps.now }, deps.baseDir);
+    const hash = createHash('sha256').update(bytes).digest('hex').slice(0, 8);
+    const upload = await uploadProjectFile(environment, token, {
+        gameId,
+        filename: `reference-${hash}.${sniffed.extension}`,
+        contentType: sniffed.contentType,
+        bytes,
+    }, { fetch: deps.fetch });
+    return { url: upload.url, contentType: sniffed.contentType };
+}
+/**
+ * The full per-call resolution, file flag included: `--reference-image <file>` is uploaded and
+ * wins (it IS the caller choosing, like the URL flag), then the URL-flag/`--no-reference`/project
+ * precedence of {@link resolveReferenceImageUrl}. Both flags together is two answers to the same
+ * question and is refused.
+ */
+export async function resolveReferenceForCall(options) {
+    const { args, root, gameId, deps, log } = options;
+    const filePath = args['reference-image'];
+    if (filePath !== undefined && filePath !== '') {
+        if (args['reference-image-url'] !== undefined && args['reference-image-url'] !== '') {
+            throw new CliError('--reference-image and --reference-image-url both name the reference for this call — pass one or the other.');
+        }
+        const uploaded = await uploadReferenceImageFile({ root, gameId, filePath, deps });
+        log(`Using ${filePath} as the reference for this call: ${uploaded.url}`);
+        return { url: uploaded.url, source: 'flag' };
+    }
+    return resolveReferenceImageUrl(args, root);
+}
+//# sourceMappingURL=reference-file.js.map

package/dist/project/reference-file.js.map

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

package/dist/project/reference.d.ts

@@ -0,0 +1,78 @@
+export declare const REFERENCE_DIR: string;
+export declare function referenceDirPath(root: string): string;
+export declare function acceptedReferencePath(root: string): string;
+export declare function candidateImagePath(root: string, id: string): string;
+/** One generated candidate — a picture the creator may accept, iterate from, or ignore. */
+export interface CandidateRecord {
+    id: string;
+    /** The Asset Forger URL the generation returned. Short-lived; the accept re-hosts it. */
+    url: string;
+    /** The prompt actually sent, truncated — enough to recognise a candidate in a list. */
+    prompt: string;
+    /** The candidate this one was iterated from (`--from`), if any. */
+    from?: string;
+    /** An explicit `--reference-image-url` this candidate was steered by, if any. */
+    referenceImageUrl?: string;
+    createdAt: string;
+}
+/** The accepted reference — what every generator and forge inherits. */
+export interface AcceptedReference {
+    /** The URL generators are given: the re-hosted public URL, or the source URL when re-hosting failed. */
+    url: string;
+    /** False when re-hosting failed and `url` is the (expiring) source URL — worth re-accepting. */
+    hosted: boolean;
+    /** What was accepted, before any re-hosting. */
+    sourceUrl: string;
+    /** Absent when a bare URL was accepted rather than a generated candidate. */
+    candidateId?: string;
+    /** The local copy, when bytes were available to keep. */
+    imagePath?: string;
+    acceptedAt: string;
+}
+export declare function readAcceptedReference(root: string): AcceptedReference | null;
+export declare function writeAcceptedReference(root: string, accepted: AcceptedReference): void;
+/** Remove the accepted reference. Candidates stay — clearing a decision is not deleting the work. */
+export declare function clearAcceptedReference(root: string): boolean;
+export declare function readCandidate(root: string, id: string): CandidateRecord | null;
+export declare function writeCandidate(root: string, record: CandidateRecord): void;
+/** Every readable candidate, newest first (ids sort chronologically by construction). */
+export declare function listCandidates(root: string): CandidateRecord[];
+/** `ref-<yyyymmdd-hhmmss>-<4 rand>` — short enough to type, sortable by creation time. */
+export declare function newCandidateId(now?: Date): string;
+/** Candidate ids become file names, so anything path-shaped is refused, never sanitised. */
+export declare function isSafeCandidateId(id: string): boolean;
+/** The two flags every reference-aware command declares (see REFERENCE_IMAGE_FLAG / NO_REFERENCE_FLAG). */
+export interface ReferenceFlagArgs {
+    'reference-image-url'?: string;
+    /** citty's negative boolean: `--no-reference` arrives as `false`; the flag has no positive form. */
+    reference?: boolean;
+}
+export interface ResolvedReference {
+    url?: string;
+    source: 'flag' | 'disabled' | 'project' | 'none';
+}
+/**
+ * The reference a generating command should send, in precedence order: an explicit
+ * `--reference-image-url` wins outright (it IS a reference choice), `--no-reference` disables,
+ * and otherwise the project's accepted reference applies — that inheritance being the whole
+ * point of accepting one.
+ */
+export declare function resolveReferenceImageUrl(args: ReferenceFlagArgs, root: string): ResolvedReference;
+/**
+ * The one line a command logs when the PROJECT's reference was applied — so the agent driving
+ * the CLI can see the default took effect (and knows the switch that turns it off). Explicit
+ * flags echo nothing: the caller chose, and repeating their own flag back is noise.
+ */
+export declare function describeAppliedReference(resolved: ResolvedReference): string | null;
+export declare const REFERENCE_IMAGE_FLAG: {
+    readonly type: "string";
+    readonly description: "Style/composition reference image URL forwarded to the image model. Overrides the accepted project reference for this call.";
+};
+export declare const NO_REFERENCE_FLAG: {
+    readonly type: "boolean";
+    readonly negativeDescription: "Do not apply the accepted project reference image (`bitmagic reference`) to this call.";
+};
+export declare const REFERENCE_FILE_FLAG: {
+    readonly type: "string";
+    readonly description: "A local image file (PNG/JPEG/WebP) to use as the reference for this call — uploaded to the game's storage first. Overrides the accepted project reference.";
+};