@bitmagic/cli 0.1.54 → 0.1.55-dev.1

package/dist/commands/ios.js

@@ -0,0 +1,333 @@
+/**
+ * `bitmagic ios` — package the game as a native iOS app and ship it toward the App Store.
+ * Design: docs/ios-export-design.md.
+ *
+ *   build   bundle → vendor every asset → prove the game boots offline → generate the Xcode
+ *           shell → xcodebuild. Simulator .app by default (no signing); `--ipa` for a signed
+ *           store build; `--run` installs and launches on a simulator.
+ *   submit  upload the archive `build --ipa` produced to App Store Connect (TestFlight).
+ *
+ * Every iOS build is a MOBILE build: the shell boots `?platform=mobile`, the engine's own
+ * override, so a desktop-primary game still gets touch controls and mobile budgets. The
+ * project's `primaryPlatform` gates nothing here.
+ *
+ * Exit codes: 1 toolchain/build failure, 3 missing prerequisite (named remedy), 5 the packaged
+ * game failed offline validation, 6 signing/upload refusal.
+ */
+import { defineCommand } from 'citty';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { CliError } from '../errors.js';
+import { createOutput } from '../output.js';
+import { loadProjectContext } from '../project/context.js';
+import { buildBundlePaths, readBuildManifest, runBuild } from '../publish/bundle.js';
+import { computeFingerprint } from '../publish/fingerprint.js';
+import { coverImagePath } from './cover.js';
+import { resolveAppConfig } from '../ios/app-config.js';
+import { collectUrls } from '../ios/collect-urls.js';
+import { iosPaths } from '../ios/paths.js';
+import { runPackagedCheck } from '../ios/record-validate.js';
+import { transformBundleHtml } from '../ios/transform.js';
+import { vendorBasePathFor, vendorUrls } from '../ios/vendor.js';
+import { writeAppIcon } from '../ios/icon.js';
+import { stampXcodeProject, TARGET_NAME } from '../ios/xcode-template.js';
+import { archiveAndExportIpa, buildSimulatorApp, preflightXcodebuild, runOnSimulator, uploadArchive, } from '../ios/xcodebuild.js';
+/** The bundle to package: reused when the source is unchanged, rebuilt otherwise — publish's rule. */
+function ensureBundle(context, output) {
+    const fingerprint = computeFingerprint(context.root);
+    if (readBuildManifest(context.root)?.fingerprint !== fingerprint) {
+        output.info('Building the game bundle…');
+        runBuild(context.root, context.metadata.engineVersion);
+    }
+    else {
+        output.info('Reusing the existing bundle (source unchanged).');
+    }
+    const { htmlPath } = buildBundlePaths(context.root);
+    try {
+        return fs.readFileSync(htmlPath, 'utf-8');
+    }
+    catch {
+        throw new CliError(`The built bundle at ${htmlPath} is missing. Run \`bitmagic build\`, then package again.`);
+    }
+}
+/**
+ * Stage the payload afresh: vendored files land here, then the transformed page. The
+ * sw-cache-buster stub rides along so the engine's localhost-only service-worker registration
+ * finds its file during the validation passes; on device the hostname gate skips it entirely.
+ */
+function stagePayload(paths, root) {
+    fs.rmSync(paths.payloadDir, { recursive: true, force: true });
+    fs.mkdirSync(paths.payloadDir, { recursive: true });
+    const stub = path.join(root, 'sw-cache-buster.js');
+    if (fs.existsSync(stub)) {
+        fs.copyFileSync(stub, path.join(paths.payloadDir, 'sw-cache-buster.js'));
+    }
+}
+async function runIosBuild(args) {
+    const output = createOutput(args.json === true);
+    const context = loadProjectContext();
+    preflightXcodebuild();
+    const paths = iosPaths(context.root);
+    const builtHtml = ensureBundle(context, output);
+    const config = resolveAppConfig({
+        root: context.root,
+        gameId: context.metadata.gameId,
+        configPath: paths.configPath,
+        nameOverride: args.name,
+        teamOverride: args.team,
+    });
+    if (args.ipa === true && config.teamId === undefined) {
+        throw new CliError('Building a signed .ipa needs your Apple Developer team id — pass `--team <TEAMID>` once '
+            + '(it is remembered). The id is on https://developer.apple.com/account under Membership.', 3);
+    }
+    const collected = await collectUrls(context.root);
+    for (const note of collected.notes)
+        output.info(note);
+    stagePayload(paths, context.root);
+    output.info(`Vendoring ${collected.urls.size} assets into the app…`);
+    const vendored = await vendorUrls({
+        urls: collected.urls,
+        cacheDir: paths.cacheDir,
+        payloadDir: paths.payloadDir,
+    });
+    if (vendored.cacheHits > 0)
+        output.info(`  ${vendored.cacheHits} from the local cache.`);
+    for (const failure of vendored.failures) {
+        // A warning, not a refusal: a stale URL the game never loads must not block packaging, and
+        // the offline validation below is the gate that catches one the game DOES load.
+        output.info(`  warning: could not vendor ${failure.url} (${failure.error})`);
+    }
+    const assetMap = new Map(vendored.entries);
+    const baseRewrites = new Map();
+    for (const base of collected.bases) {
+        const rel = vendorBasePathFor(base);
+        if (rel !== null)
+            baseRewrites.set(base, rel);
+    }
+    const indexPath = path.join(paths.payloadDir, 'index.html');
+    const writeTransformed = () => {
+        const transformed = transformBundleHtml({ html: builtHtml, assetMap, baseRewrites });
+        fs.writeFileSync(indexPath, transformed.html);
+        return transformed.rewrites;
+    };
+    const rewrites = writeTransformed();
+    output.info(`Asset map: ${assetMap.size} entries, ${rewrites} URL literals rewritten.`);
+    let validation;
+    if (args['skip-validation'] === true) {
+        output.info('Offline validation skipped — this app is NOT confirmed to work without a network.');
+    }
+    else {
+        // Record pass: play the game the way the app will and vendor whatever it still fetched —
+        // the empirical net under the static collection (§4e of the design).
+        output.info('Recording runtime asset requests (headless Chrome, iPhone viewport)…');
+        const recorded = await runPackagedCheck({
+            payloadDir: paths.payloadDir,
+            artifactDir: path.join(paths.checkDir, 'record'),
+            mode: 'record',
+            orientation: config.orientation,
+        });
+        if (recorded.misses.length > 0) {
+            output.info(`  ${recorded.misses.length} runtime-discovered asset(s) — vendoring those too.`);
+            const extra = await vendorUrls({
+                urls: recorded.misses,
+                cacheDir: paths.cacheDir,
+                payloadDir: paths.payloadDir,
+            });
+            for (const [url, rel] of extra.entries)
+                assetMap.set(url, rel);
+            for (const failure of extra.failures) {
+                output.info(`  warning: could not vendor ${failure.url} (${failure.error})`);
+            }
+            writeTransformed();
+        }
+        output.info('Validating the app works offline…');
+        const offline = await runPackagedCheck({
+            payloadDir: paths.payloadDir,
+            artifactDir: path.join(paths.checkDir, 'offline'),
+            mode: 'offline',
+            orientation: config.orientation,
+        });
+        for (const warning of offline.result.warnings)
+            output.info(`  warning: ${warning}`);
+        validation = { ok: offline.result.ok && offline.misses.length === 0, misses: offline.misses.length };
+        if (!validation.ok) {
+            const misses = offline.misses.map((url) => `  ✗ still requests ${url}`).join('\n');
+            const failures = offline.result.failures.map((failure) => `  ✗ ${failure}`).join('\n');
+            throw new CliError('The packaged game does not work without a network:\n'
+                + [failures, misses].filter((section) => section.length > 0).join('\n')
+                + `\nArtifacts: ${path.join(paths.checkDir, 'offline')}`, 5);
+        }
+        output.info('Offline validation passed — the game renders with no network.');
+    }
+    stampXcodeProject(paths.projectDir, config);
+    const icon = writeAppIcon(path.join(paths.projectDir, 'Assets.xcassets'), coverImagePath(context.root));
+    if (icon.source === 'placeholder') {
+        output.info('App icon: flat placeholder. Run `bitmagic cover` for generated artwork.');
+    }
+    let appPath;
+    let ipaPath;
+    if (args.ipa === true) {
+        // teamId was gated non-undefined above, before any slow work.
+        const exported = archiveAndExportIpa({
+            xcodeprojDir: paths.xcodeprojDir,
+            derivedDataDir: paths.derivedDataDir,
+            distDir: paths.distDir,
+            productName: config.productName,
+            teamId: config.teamId ?? '',
+            log: output.info,
+        });
+        ipaPath = exported.ipaPath;
+        output.info(`Signed .ipa: ${ipaPath}`);
+        output.info('Upload it with `bitmagic ios submit`.');
+    }
+    else {
+        const built = buildSimulatorApp({
+            xcodeprojDir: paths.xcodeprojDir,
+            derivedDataDir: paths.derivedDataDir,
+            productName: config.productName,
+            log: output.info,
+        });
+        appPath = built.appPath;
+        if (built.iconSkipped) {
+            output.info('Built without the app icon: this Xcode has no simulator runtime matching its SDK. '
+                + 'Run `xcodebuild -downloadPlatform iOS` (or Xcode → Settings → Components) to fix that.');
+        }
+        output.info(`Simulator app: ${appPath}`);
+        if (args.run === true) {
+            runOnSimulator(appPath, config.bundleId, output.info);
+        }
+        else {
+            output.info('Run it with `bitmagic ios build --run`, or open .bitmagic/ios/App/App.xcodeproj.');
+        }
+    }
+    output.result({
+        ok: true,
+        bundleId: config.bundleId,
+        productName: config.productName,
+        displayName: config.displayName,
+        vendoredAssets: assetMap.size,
+        ...(validation !== undefined ? { offlineValidated: validation.ok } : { offlineValidated: false }),
+        ...(appPath !== undefined ? { appPath } : {}),
+        ...(ipaPath !== undefined ? { ipaPath } : {}),
+    });
+}
+export function submitCredentialsPath(baseDir = path.join(os.homedir(), '.bitmagic')) {
+    return path.join(baseDir, 'ios-submit.json');
+}
+function readSubmitCredentials(filePath) {
+    const remedy = `App Store Connect credentials are not set up. Create an API key under `
+        + 'https://appstoreconnect.apple.com/access/integrations/api (role: App Manager), then write '
+        + `${filePath} as {"keyId": "…", "issuerId": "…", "keyPath": "/path/to/AuthKey_….p8"}.`;
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        throw new CliError(remedy, 3);
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        throw new CliError(remedy, 3);
+    const record = parsed;
+    const { keyId, issuerId, keyPath } = record;
+    if (typeof keyId !== 'string' || typeof issuerId !== 'string' || typeof keyPath !== 'string') {
+        throw new CliError(remedy, 3);
+    }
+    if (!fs.existsSync(keyPath)) {
+        throw new CliError(`The App Store Connect key at ${keyPath} does not exist.`, 3);
+    }
+    return { keyId, issuerId, keyPath };
+}
+async function runIosSubmit(args) {
+    const output = createOutput(args.json === true);
+    const context = loadProjectContext();
+    preflightXcodebuild();
+    const paths = iosPaths(context.root);
+    const archivePath = path.join(paths.distDir, `${TARGET_NAME}.xcarchive`);
+    if (!fs.existsSync(archivePath)) {
+        throw new CliError('No archive to upload. Run `bitmagic ios build --ipa` first.', 3);
+    }
+    const config = resolveAppConfig({
+        root: context.root,
+        gameId: context.metadata.gameId,
+        configPath: paths.configPath,
+    });
+    if (config.teamId === undefined) {
+        throw new CliError('No team id on file. Run `bitmagic ios build --ipa --team <TEAMID>` first.', 3);
+    }
+    const credentials = readSubmitCredentials(submitCredentialsPath());
+    uploadArchive({
+        archivePath,
+        distDir: paths.distDir,
+        teamId: config.teamId,
+        keyPath: credentials.keyPath,
+        keyId: credentials.keyId,
+        issuerId: credentials.issuerId,
+        log: output.info,
+    });
+    output.info('Uploaded. The build appears in App Store Connect → TestFlight after processing —');
+    output.info('internal testers can install it from the TestFlight app within minutes.');
+    output.result({ ok: true, bundleId: config.bundleId, archivePath });
+}
+const buildCommand = defineCommand({
+    meta: {
+        name: 'build',
+        description: 'Package the game as an iOS app — all assets vendored, mobile controls forced. '
+            + 'Simulator app by default; --ipa for a signed store build.',
+    },
+    args: {
+        run: {
+            type: 'boolean',
+            description: 'After building, boot a simulator, install the app and launch the game.',
+        },
+        ipa: {
+            type: 'boolean',
+            description: 'Archive for devices and export a signed .ipa (needs a team id).',
+        },
+        team: {
+            type: 'string',
+            description: 'Apple Developer team id for signing — remembered in .bitmagic/ios.json.',
+        },
+        name: {
+            type: 'string',
+            description: 'Override the app display name for this build only.',
+        },
+        'skip-validation': {
+            type: 'boolean',
+            description: 'Skip the record/offline passes. The app still builds; working without a network is NOT confirmed.',
+        },
+        json: {
+            type: 'boolean',
+            description: 'Print the result as JSON on stdout; all progress goes to stderr.',
+        },
+    },
+    async run({ args }) {
+        await runIosBuild(args);
+    },
+});
+const submitCommand = defineCommand({
+    meta: {
+        name: 'submit',
+        description: 'Upload the archive from `ios build --ipa` to App Store Connect (TestFlight).',
+    },
+    args: {
+        json: {
+            type: 'boolean',
+            description: 'Print the result as JSON on stdout; all progress goes to stderr.',
+        },
+    },
+    async run({ args }) {
+        await runIosSubmit(args);
+    },
+});
+export const iosCommand = defineCommand({
+    meta: {
+        name: 'ios',
+        description: 'Package and submit the game as a native iOS app.',
+    },
+    subCommands: {
+        build: buildCommand,
+        submit: submitCommand,
+    },
+});
+//# sourceMappingURL=ios.js.map

package/dist/commands/ios.js.map

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

package/dist/commands/reference.d.ts

@@ -0,0 +1,41 @@
+import { Buffer } from 'buffer';
+import { type GenerateRunDeps } from './generate.js';
+import type { GenerationOutcome } from '../generate/stream.js';
+export interface ReferenceRunDeps extends GenerateRunDeps {
+    /** Seam over the generation lane, so a test drives this without a network or a token. */
+    generate: (type: string, label: string, body: Record<string, unknown>, deps: GenerateRunDeps) => Promise<GenerationOutcome>;
+    /** Returns whether the terminal actually drew the image. */
+    renderImage: (bytes: Buffer) => boolean;
+    /** The machine-readable result, emitted only under `--json`. */
+    result: (value: unknown) => void;
+}
+/**
+ * The prose the picture is drawn from: `--prompt` when given, otherwise GAME-DESIGN.md. The same
+ * source `bitmagic cover` reads, because the two pictures describe the same game — but the error
+ * paths name THIS command, since "write the design or pass --prompt" must say which command to
+ * re-run.
+ */
+export declare function resolveReferenceDesignText(options: {
+    promptFlag?: string | undefined;
+    root: string;
+}): string;
+export interface ReferenceMakeArgs {
+    prompt?: string;
+    from?: string;
+    'reference-image-url'?: string;
+    /** A local image to steer this candidate by — uploaded first ("make the world like this photo"). */
+    'reference-image'?: string;
+    json?: boolean;
+}
+export declare function runReferenceMake(args: ReferenceMakeArgs, deps?: ReferenceRunDeps): Promise<void>;
+export interface ReferenceAcceptArgs {
+    candidate: string;
+    json?: boolean;
+}
+export declare function runReferenceAccept(args: ReferenceAcceptArgs, deps?: ReferenceRunDeps): Promise<void>;
+export interface ReferenceShowArgs {
+    json?: boolean;
+}
+export declare function runReferenceShow(args: ReferenceShowArgs, deps?: ReferenceRunDeps): Promise<void>;
+export declare function runReferenceClear(args: ReferenceShowArgs, deps?: ReferenceRunDeps): Promise<void>;
+export declare const referenceCommand: import("citty").CommandDef<import("citty").ArgsDef>;