@bitmagic/cli 0.1.0 → 0.1.2

package/dist/forge/run-pipeline.d.ts

@@ -0,0 +1,105 @@
+import { type ForgeArtifact, type ForgeDeps, type ForgeJobInput, type ForgeLevelSummary, type ForgeLogger, type ForgeStorageEnv, type ForgeTransport, type ForgeWorldJsonSource, type ForgedWorkStore } from '@bitmagic/world-forger/pipeline/index.js';
+/** The project's one world.json — the file the engine loads and the forge writes back to. */
+export declare function projectWorldJsonPath(projectRoot: string): string;
+/**
+ * `ForgeDeps.worldJson` for a CLI project. **Both reads resolve to the SAME file**, and that is
+ * correct here rather than a shortcut.
+ *
+ * The seam has two reads because game-play-agent's web lane genuinely has two world.json files
+ * mid-session — a per-session copy the agent writes and a monorepo work copy the creator/browser
+ * writes — and which one a differential plan is computed against decides what survives a forge.
+ * `world-json-source.ts` carries the full argument; the short version is that what each read
+ * WANTS is the same thing, "the file the returned modifications will be applied to", and the web
+ * lane cannot collapse them without changing behaviour it has no test for.
+ *
+ * A CLI project has exactly ONE world.json. `applyModificationsToWorld` writes it, the engine
+ * loads it, and nothing else exists to diverge from it — so returning it from both reads is not
+ * "picking one", it is what "plan against the write target" reduces to when there is a single
+ * target. The seam's own header names this lane and says so.
+ *
+ * Both reads happen LAZILY, when step 5 calls them — never snapshotted when these deps are built.
+ * That matters even here: the reads run after a bake that can take 20 minutes, and the scaffolded
+ * project's own tooling (or the creator) may have written world.json during it.
+ *
+ * Both keep the seam's documented degradations. They are contract, not swallowed errors: a
+ * game with an unreadable world.json must still be able to forge, and neither `{}` nor `null`
+ * hides anything the creator could act on — a missing or corrupt world.json fails far more
+ * loudly, and much earlier, in `readProjectGameData` when the game is loaded into the browser.
+ */
+export declare function createProjectWorldJsonSource(projectRoot: string): ForgeWorldJsonSource;
+/**
+ * A `ForgeLogger` over a plain line printer. The pipeline logs with pino's object-first shape
+ * (`info({ jobId, ... }, 'message')`), which is what makes step progress visible at all — so the
+ * context object is rendered rather than dropped, but compactly: these lines go to a creator's
+ * terminal, not to a log aggregator.
+ */
+export declare function createConsoleForgeLogger(log: (message: string) => void): ForgeLogger;
+/**
+ * The `ForgeDeps` steps 3-5 read. Four seams, and the two the type also declares are omitted
+ * deliberately:
+ *
+ *  - `model` — steps 3-5 never call an LLM (that is step 1, on api-server). The type requires it,
+ *    so it is a client that THROWS rather than one that returns something plausible: a future
+ *    change that starts calling a model from the browser-driven half must fail loudly, not
+ *    silently produce a level designed by a stub. Same discipline api-server applies to the
+ *    `transport` and `worldJson` seams it does not implement.
+ *  - `assetCatalog` — omitted; absence degrades to "no reuse", never a failure. It feeds the
+ *    DESIGNER (step 1), which does not run here, so it would have no reader in this lane even if
+ *    the CLI built one.
+ *  - `hqAssetIds` — omitted. A CLI project has no HQ regeneration queue, and the absent seam
+ *    already means exactly "no jobs in flight" (see the field's own doc), so supplying an empty
+ *    set would restate the default in a second place.
+ */
+export declare function buildCliForgeDeps(options: {
+    projectRoot: string;
+    storage: ForgeStorageEnv;
+    transport: ForgeTransport;
+    logger: ForgeLogger;
+}): ForgeDeps;
+/**
+ * Put the upstream artifacts into the local store so steps 3-5 can read them.
+ *
+ * `forge` is written unconditionally: it is what the server just handed back, and on a resume the
+ * server returns the SAME cached artifact (`forgeWorld` ends every run with `store.get('forge')`
+ * whether or not either step re-ran), so the write is idempotent rather than a clobber.
+ *
+ * `platformer-movement` is written whenever the terminal frame carried one, on the same reasoning:
+ * it is step 1's output, it lives in api-server's store, and step 5 reads it from THIS store to set
+ * `worldForgerMovement` on the level record. Only a `--platformer` design produces one, so absence
+ * is normal — and on an older server that does not send the field it is also possible, which is
+ * what `warnIfPlatformerMovementMissing` still exists to catch.
+ *
+ * `input` is written ONLY when absent, mirroring api-server's own freeze. It is the job's frozen
+ * request, and steps 4 and 5 read the level name, prompt and start-level intent off it — so a
+ * resume must persist what was originally asked for, not what this invocation's flags happen to
+ * say.
+ */
+export declare function seedForgeStore(store: ForgedWorkStore, artifact: ForgeArtifact, input: ForgeJobInput, platformerMovement?: Record<string, unknown>): Promise<void>;
+/** Read a job's frozen `input`, or null if this machine has never run it. */
+export declare function readFrozenInput(storage: ForgeStorageEnv, jobId: string): Promise<ForgeJobInput | null>;
+export interface RunPipelineOptions {
+    projectRoot: string;
+    store: ForgedWorkStore;
+    deps: ForgeDeps;
+    /** Progress printer for the command's own step banners. */
+    log: (message: string) => void;
+}
+export interface RunPipelineResult {
+    summary: ForgeLevelSummary;
+    /** False when a resume found the job already applied and nothing was written this run. */
+    applied: boolean;
+    /** The world.json lines to print, empty on the already-applied path. */
+    changes: string[];
+}
+/**
+ * Drive steps 3-5 in order, skipping any whose output artifact already exists — the same
+ * resume mechanism `run-world-forger.ts` uses, and the same one api-server applies to steps 1-2.
+ *
+ * The write half deliberately does NOT live in step 5: `placeAndPersistLevel` returns the
+ * modifications and the heightfield, and the host applies both. The ordering below is a contract,
+ * not a detail — `persisted` is the job-complete marker a resume returns directly, so recording it
+ * before the world.json write would let a failed write resume into "done" over an unchanged world.
+ * Unlike the web lane's applier (which catches everything and returns `{success:false}`), the
+ * CLI's `applyModificationsToWorld` THROWS, so here that ordering does real work.
+ */
+export declare function runForgePipeline(options: RunPipelineOptions): Promise<RunPipelineResult>;

package/dist/forge/run-pipeline.js

@@ -0,0 +1,269 @@
+/**
+ * Steps 3-5 of the world forger, hosted by the CLI: create the archetype library assets, bake the
+ * level, then place its instances and write the result into the project's world.json.
+ *
+ * This is the CLI's counterpart to `game-play-agent/src/mastra/tools/run-world-forger.ts` (the
+ * step driver) and `world-forger/pipeline.ts` (the host-side writes). The three steps themselves
+ * are imported unchanged from `@bitmagic/world-forger` — the PUBLISHABLE half. The private half,
+ * `@bitmagic/world-forger-internal`, holds the designer, its system prompts and the geometry
+ * engine; it runs on api-server and must never be imported here, nor reach a creator's machine.
+ *
+ * Kept separate from `commands/forge.ts` so the whole pipeline half is testable without citty, a
+ * browser, a dev server or a network: every seam it needs arrives as a parameter.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { createForgedWorkStore, createLevelArchetypes, placeAndPersistLevel, voxelizeLevel, } from '@bitmagic/world-forger/pipeline/index.js';
+import { FORGED_HEIGHTFIELD_FILE } from '@bitmagic/world-forger/terrain-height-grid.js';
+import { CliError } from '../errors.js';
+import { aliasSourceDir } from '../scaffold/aliases.js';
+import { applyModificationsToWorld } from './apply-modifications.js';
+/** The project's one world.json — the file the engine loads and the forge writes back to. */
+export function projectWorldJsonPath(projectRoot) {
+    return path.join(projectRoot, aliasSourceDir('work'), 'world.json');
+}
+/**
+ * `ForgeDeps.worldJson` for a CLI project. **Both reads resolve to the SAME file**, and that is
+ * correct here rather than a shortcut.
+ *
+ * The seam has two reads because game-play-agent's web lane genuinely has two world.json files
+ * mid-session — a per-session copy the agent writes and a monorepo work copy the creator/browser
+ * writes — and which one a differential plan is computed against decides what survives a forge.
+ * `world-json-source.ts` carries the full argument; the short version is that what each read
+ * WANTS is the same thing, "the file the returned modifications will be applied to", and the web
+ * lane cannot collapse them without changing behaviour it has no test for.
+ *
+ * A CLI project has exactly ONE world.json. `applyModificationsToWorld` writes it, the engine
+ * loads it, and nothing else exists to diverge from it — so returning it from both reads is not
+ * "picking one", it is what "plan against the write target" reduces to when there is a single
+ * target. The seam's own header names this lane and says so.
+ *
+ * Both reads happen LAZILY, when step 5 calls them — never snapshotted when these deps are built.
+ * That matters even here: the reads run after a bake that can take 20 minutes, and the scaffolded
+ * project's own tooling (or the creator) may have written world.json during it.
+ *
+ * Both keep the seam's documented degradations. They are contract, not swallowed errors: a
+ * game with an unreadable world.json must still be able to forge, and neither `{}` nor `null`
+ * hides anything the creator could act on — a missing or corrupt world.json fails far more
+ * loudly, and much earlier, in `readProjectGameData` when the game is loaded into the browser.
+ */
+export function createProjectWorldJsonSource(projectRoot) {
+    const file = projectWorldJsonPath(projectRoot);
+    const read = () => {
+        if (!fs.existsSync(file))
+            return null;
+        try {
+            const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+            return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+                ? parsed
+                : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    return {
+        readForPersistPlan: async () => (read() ?? {}),
+        readForStarterScatterPlan: async () => read(),
+    };
+}
+/**
+ * A `ForgeLogger` over a plain line printer. The pipeline logs with pino's object-first shape
+ * (`info({ jobId, ... }, 'message')`), which is what makes step progress visible at all — so the
+ * context object is rendered rather than dropped, but compactly: these lines go to a creator's
+ * terminal, not to a log aggregator.
+ */
+export function createConsoleForgeLogger(log) {
+    const emit = (level, first, rest) => {
+        if (typeof first === 'string') {
+            log(`${level}${first}`);
+            return;
+        }
+        const message = typeof rest[0] === 'string' ? rest[0] : '';
+        const context = first;
+        const fields = Object.entries(context)
+            // `jobId` is printed by the command itself and repeats on every line; `err` is rendered
+            // separately below so a stack does not get JSON-quoted into one unreadable line.
+            .filter(([key]) => key !== 'jobId' && key !== 'err')
+            .map(([key, value]) => `${key}=${typeof value === 'object' ? JSON.stringify(value) : String(value)}`)
+            .join(' ');
+        const error = context.err;
+        const detail = error instanceof Error ? ` (${error.message})` : '';
+        log(`${level}${message}${fields ? ` — ${fields}` : ''}${detail}`);
+    };
+    return {
+        info: (first, ...rest) => emit('', first, rest),
+        warn: (first, ...rest) => emit('warning: ', first, rest),
+        error: (first, ...rest) => emit('error: ', first, rest),
+    };
+}
+/**
+ * The `ForgeDeps` steps 3-5 read. Four seams, and the two the type also declares are omitted
+ * deliberately:
+ *
+ *  - `model` — steps 3-5 never call an LLM (that is step 1, on api-server). The type requires it,
+ *    so it is a client that THROWS rather than one that returns something plausible: a future
+ *    change that starts calling a model from the browser-driven half must fail loudly, not
+ *    silently produce a level designed by a stub. Same discipline api-server applies to the
+ *    `transport` and `worldJson` seams it does not implement.
+ *  - `assetCatalog` — omitted; absence degrades to "no reuse", never a failure. It feeds the
+ *    DESIGNER (step 1), which does not run here, so it would have no reader in this lane even if
+ *    the CLI built one.
+ *  - `hqAssetIds` — omitted. A CLI project has no HQ regeneration queue, and the absent seam
+ *    already means exactly "no jobs in flight" (see the field's own doc), so supplying an empty
+ *    set would restate the default in a second place.
+ */
+export function buildCliForgeDeps(options) {
+    return {
+        storage: options.storage,
+        transport: options.transport,
+        worldJson: createProjectWorldJsonSource(options.projectRoot),
+        logger: options.logger,
+        model: {
+            async generateText() {
+                throw new CliError('The CLI hosts steps 3-5 of the forge, which never call a language model — '
+                    + 'the scene design runs on api-server. This is a bug in the CLI, not in your project.');
+            },
+        },
+    };
+}
+// ============================================================================
+// Seeding the local store from what the server returned
+// ============================================================================
+/**
+ * Put the upstream artifacts into the local store so steps 3-5 can read them.
+ *
+ * `forge` is written unconditionally: it is what the server just handed back, and on a resume the
+ * server returns the SAME cached artifact (`forgeWorld` ends every run with `store.get('forge')`
+ * whether or not either step re-ran), so the write is idempotent rather than a clobber.
+ *
+ * `platformer-movement` is written whenever the terminal frame carried one, on the same reasoning:
+ * it is step 1's output, it lives in api-server's store, and step 5 reads it from THIS store to set
+ * `worldForgerMovement` on the level record. Only a `--platformer` design produces one, so absence
+ * is normal — and on an older server that does not send the field it is also possible, which is
+ * what `warnIfPlatformerMovementMissing` still exists to catch.
+ *
+ * `input` is written ONLY when absent, mirroring api-server's own freeze. It is the job's frozen
+ * request, and steps 4 and 5 read the level name, prompt and start-level intent off it — so a
+ * resume must persist what was originally asked for, not what this invocation's flags happen to
+ * say.
+ */
+export async function seedForgeStore(store, artifact, input, platformerMovement) {
+    await store.put('forge', artifact);
+    if (platformerMovement) {
+        await store.put('platformer-movement', platformerMovement);
+    }
+    if (!(await store.has('input'))) {
+        await store.put('input', input);
+    }
+}
+/** Read a job's frozen `input`, or null if this machine has never run it. */
+export async function readFrozenInput(storage, jobId) {
+    return createForgedWorkStore(jobId, storage).get('input');
+}
+/**
+ * Warn when a platformer forge is about to persist WITHOUT its movement contract.
+ *
+ * `platformer-movement` is written by step 1, into api-server's store. It reaches this lane on the
+ * terminal SSE frame and is written into the local store by `seedForgeStore`, so the normal path
+ * HAS it — this is the belt-and-braces for the one window that remains: a CLI talking to an
+ * api-server deployed before that field existed. The two ship independently, and that window is
+ * exactly where a creator pays for the flag and silently does not get it.
+ *
+ * Step 5 reads the artifact with `store.get` and omits `worldForgerMovement` when it is absent,
+ * which makes the gap look like a graceful degradation. It is not one worth being quiet about: the
+ * forge's completability guarantee is CONDITIONAL on that contract, and without it the engine falls
+ * back to its default walking/jumping kit — a jump too short to climb a level designed around the
+ * contract's numbers. The result is a paid-for platformer level that is not traversable.
+ *
+ * Purely local and purely advisory: it changes nothing, it cannot fail the forge, and the level is
+ * still worth having.
+ */
+async function warnIfPlatformerMovementMissing(store, log) {
+    const input = await store.get('input');
+    if (input?.platformerMode !== true)
+        return;
+    if ((await store.get('platformer-movement')) !== null)
+        return;
+    log('warning: this platformer level is being saved WITHOUT its movement contract. The contract is '
+        + 'produced by the design step, which runs on the server, and the CLI lane cannot yet read it '
+        + 'back — so the character keeps the engine\'s default jump, which may be too short to climb '
+        + 'the level. If the level turns out not to be traversable, tune the character\'s jump height '
+        + 'and speed by hand rather than re-forging.');
+}
+/**
+ * Drive steps 3-5 in order, skipping any whose output artifact already exists — the same
+ * resume mechanism `run-world-forger.ts` uses, and the same one api-server applies to steps 1-2.
+ *
+ * The write half deliberately does NOT live in step 5: `placeAndPersistLevel` returns the
+ * modifications and the heightfield, and the host applies both. The ordering below is a contract,
+ * not a detail — `persisted` is the job-complete marker a resume returns directly, so recording it
+ * before the world.json write would let a failed write resume into "done" over an unchanged world.
+ * Unlike the web lane's applier (which catches everything and returns `{success:false}`), the
+ * CLI's `applyModificationsToWorld` THROWS, so here that ordering does real work.
+ */
+export async function runForgePipeline(options) {
+    const { projectRoot, store, deps, log } = options;
+    if (await store.has('persisted')) {
+        const cached = await store.get('persisted');
+        if (cached) {
+            log(`This job was already applied to world.json — nothing to redo. Level "${cached.asset_name}".`);
+            return { summary: cached, applied: false, changes: [] };
+        }
+    }
+    if (await store.has('archetype-assets')) {
+        log('[3/5] Objects already created — skipping (resumed).');
+    }
+    else {
+        log('[3/5] Creating the level\'s objects in the browser…');
+        await createLevelArchetypes(store, deps);
+        log('[3/5] Objects created.');
+    }
+    if (await store.has('level-bake')) {
+        log('[4/5] Level already baked — skipping (resumed).');
+    }
+    else {
+        log('[4/5] Baking the level (this is the long one — progress follows)…');
+        await voxelizeLevel(store, deps);
+        log('[4/5] Level baked.');
+    }
+    await warnIfPlatformerMovementMissing(store, log);
+    log('[5/5] Placing instances and writing world.json…');
+    const { summary, modifications, terrainHeightGrid } = await placeAndPersistLevel(store, deps);
+    const worldPath = projectWorldJsonPath(projectRoot);
+    let outcome;
+    try {
+        outcome = applyModificationsToWorld(worldPath, modifications);
+    }
+    catch (error) {
+        // The single most expensive failure in the command, and the one a creator is most likely to
+        // misread: everything has been designed, forged, baked and placed — and paid for — and only
+        // the last write did not land. Saying WHICH is the difference between "resume this" and
+        // "start over". `applyModificationsToWorld` writes through a temp file and a rename and
+        // validates the document before touching it, so "unchanged" here is a fact, not a hope.
+        const detail = error instanceof CliError ? error.message : String(error);
+        throw new CliError(`The level was designed, forged and baked successfully, but could not be written into `
+            + `world.json: ${detail} world.json is UNCHANGED — the level is not lost, it has been paid `
+            + 'for and is saved server-side, but it is not yet in your project. Fix the problem above '
+            + 'and resume this job; nothing will be re-forged or re-billed.', error instanceof CliError ? error.exitCode : 1);
+    }
+    // The world-space heightfield, next to world.json, so objects placed AFTER this forge can
+    // resolve `placeOnTerrain` Y on the forged surface — a placement raycast cannot, because the
+    // new terrain only loads on the next run. Best-effort by design: a missing sidecar just falls
+    // back to runtime snapping, and losing it must never fail a forge that has already landed.
+    if (terrainHeightGrid) {
+        const sidecarPath = path.join(path.dirname(worldPath), FORGED_HEIGHTFIELD_FILE);
+        try {
+            fs.writeFileSync(sidecarPath, JSON.stringify(terrainHeightGrid));
+            log(`Wrote the terrain heightfield sidecar (${terrainHeightGrid.nx}x${terrainHeightGrid.nz} cells).`);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            log(`warning: could not write ${FORGED_HEIGHTFIELD_FILE} (${detail}). `
+                + 'Objects placed later will fall back to runtime terrain snapping.');
+        }
+    }
+    await store.put('persisted', summary);
+    return { summary, applied: true, changes: outcome.summary };
+}
+//# sourceMappingURL=run-pipeline.js.map

package/dist/forge/run-pipeline.js.map

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

package/dist/forge/stream.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The client for `POST /api/cli/v1/forge/stream` — steps 1-2 of the world forger (LLM scene
+ * design, then geometry forge + GLB upload), which run on api-server because they are the paid,
+ * private half. The terminal frame carries the `ForgeArtifact` steps 3-5 need; the `jobId` that
+ * makes the work resumable is on EVERY frame, terminal or not, and is tracked as such — see
+ * `lastJobId` in {@link requestForge}.
+ *
+ * Mirrors `generate/stream.ts` in shape (same SSE plumbing, same pre-stream status mapping), but
+ * the terminal payload is different — `{ success, jobId, artifact }` rather than
+ * `{ success, message, patches }` — and so is what a failure means to the creator, which is what
+ * {@link classifyForgeFailure} is for.
+ */
+import type { ForgeArtifact } from '@bitmagic/world-forger/pipeline/index.js';
+import type { Environment } from '../config/environments.js';
+export interface ForgeSuccess {
+    success: true;
+    jobId: string;
+    artifact: ForgeArtifact;
+    /**
+     * Step 1's `platformer-movement` artifact, when the design produced one (only a
+     * `--platformer` forge does). It lives in api-server's store, and steps 3-5 run against the
+     * CLI's own local store — so it has to travel on this frame or step 5 cannot read it. See
+     * `seedForgeStore`, which writes it into the local store, and
+     * `warnIfPlatformerMovementMissing`, which stays as the older-server fallback.
+     */
+    platformerMovement?: Record<string, unknown>;
+}
+export interface ForgeFailure {
+    success: false;
+    jobId: string | null;
+    message: string;
+    /** Present when the failure carried a forged GLB the creator can still voxelize by hand. */
+    glbUrl?: string;
+    /**
+     * The server's own request deadline fired — the run was cut off mid-flight rather than failing.
+     * See {@link isDeadlineFailure} for why this cannot be inferred from {@link progress}.
+     */
+    timedOut: boolean;
+    /** Every progress line the server sent, in order — the input to {@link classifyForgeFailure}. */
+    progress: string[];
+}
+export type ForgeOutcome = ForgeSuccess | ForgeFailure;
+/**
+ * Which of steps 1-2 failed, which decides the ONLY thing a creator actually wants to know:
+ * whether resuming this job can possibly help.
+ *
+ *  - `design` — step 1 writes its `spec` artifact only on success, so nothing was saved. A
+ *    resume re-runs the design and is billed for it again. It CAN succeed (the designer is
+ *    non-deterministic and retries internally), but it is not free.
+ *  - `forge`  — step 2 is pure geometry over an already-cached `spec`. It is deterministic: a
+ *    resume feeds the identical spec to the identical code and fails identically. The web lane
+ *    says the same thing structurally, with `DETERMINISTIC_STEPS = new Set(['forge'])` in
+ *    `game-play-agent/src/mastra/tools/run-world-forger.ts`. The fix is a different prompt, not
+ *    a retry.
+ *  - `unknown` — we could not tell; the message states both cases rather than guessing.
+ */
+export type ForgeFailureStage = 'design' | 'forge' | 'unknown';
+export declare function isDeadlineFailure(failure: Pick<ForgeFailure, 'timedOut' | 'message'>): boolean;
+/**
+ * What to tell a creator whose run hit the server deadline: resume, unconditionally. No stage
+ * advice, because no stage failed.
+ */
+export declare function forgeDeadlineAdvice(jobId: string | null): string;
+/**
+ * What to tell a creator whose stream ended with NO terminal frame at all.
+ *
+ * This is the deadline's twin and needs the same answer — the run was cut off mid-flight, api-server
+ * deliberately does not cancel it (`cli-forge.ts`'s run promise is left to finish), and whatever it
+ * completes is written to the job's store — except that here nothing said so, because no frame
+ * arrived to say it. Without a job id the creator's only move is a fresh `--prompt` run, which mints
+ * a NEW job id and re-runs (and re-bills) a design the abandoned job may already have finished and
+ * saved. That is why {@link requestForge} tracks the job id off EVERY frame rather than only the
+ * terminal one: api-server puts it on every progress frame precisely so this case has an answer.
+ */
+export declare function forgeTruncationMessage(jobId: string | null): string;
+export declare function classifyForgeFailure(progress: readonly string[]): ForgeFailureStage;
+/**
+ * The resume advice for a failure, as a paragraph appended to the server's own message. Every
+ * branch says explicitly that world.json is unchanged, because a creator who does not know has to
+ * go and look — and a forge costs enough that "did I just pay for nothing, and is my project
+ * still intact?" is the first question.
+ */
+export declare function forgeFailureAdvice(stage: ForgeFailureStage, jobId: string | null): string;
+/**
+ * The complete message for a failed forge: the server's own text, then the ONE piece of advice
+ * that fits. The deadline check comes first and short-circuits the stage classification — see
+ * {@link isDeadlineFailure} for why the two must never both speak.
+ *
+ * The single entry point the command uses, so "which advice wins" is decided in one place and is
+ * testable without a network.
+ */
+export declare function describeForgeFailure(failure: ForgeFailure): string;
+export interface ForgeStreamDeps {
+    fetch: typeof globalThis.fetch;
+    onProgress: (message: string) => void;
+}
+/**
+ * POSTs to `/api/cli/v1/forge/stream` and consumes the SSE response.
+ *
+ * A non-2xx response fails before any stream opens (see `toCliError`). On 200, each `progress`
+ * event is forwarded AND recorded, and the terminal `result`/`error` event resolves this call. A
+ * stream that closes with no terminal event is a truncated connection, not a success — and it fails
+ * with {@link forgeTruncationMessage}, naming the job id the frames already reported so the
+ * expensive half can be resumed rather than paid for twice.
+ */
+export declare function requestForge(environment: Environment, accessToken: string, body: Record<string, unknown>, deps: ForgeStreamDeps): Promise<ForgeOutcome>;