@bitmagic/cli 0.1.52-dev.1 → 0.1.52-dev.10

package/dist/levels/registry.d.ts

@@ -0,0 +1,88 @@
+/**
+ * `bitmagic levels` — the level registry in `worldProfileData.levels`, without the web Creator.
+ *
+ * `forge` can CREATE levels but never could manage them: only a game's first forge becomes the
+ * start level (or `forge --make-start` at creation), so fixing a wrong start, renaming, or deleting
+ * a level meant opening the Creator.
+ *
+ * ── The invariant this file exists to respect ────────────────────────────────────────────────
+ *
+ * `worldProfileData` keeps three LEGACY MIRRORS — `voxelUrl`, `spawnPoints` and
+ * `playerSpawnPosition` — describing the START level, because frozen genre and work-template code
+ * boots from those rather than from the registry (see `WorldLevel` in game/src/types/game.ts).
+ *
+ * Nothing self-heals on the normal boot path. `applyBootLevelOverride` does recompute them, but
+ * only when the main screen's level chooser passes a `bootLevelId`. So a `startLevelId` moved
+ * without its mirrors boots the NEW level's objects, lighting and navmesh over the OLD level's
+ * terrain, and nothing throws. That is the failure this module exists to prevent.
+ *
+ * The mirrors come from `buildStartLevelMirrors` in `@bitmagic/world-forger`, deliberately rather
+ * than reimplemented — the same function the forge uses, carrying a subtlety worth not
+ * rediscovering: spawn mirrors are written ONLY when the level owns spawn points, because a level
+ * without its own inherits the globals, which are then already correct.
+ *
+ * Pure: it computes modifications and never applies them.
+ */
+import { type LevelEntry, type WorldJsonModification } from '@bitmagic/world-forger/pipeline/index.js';
+import { type JsonObject } from '../project/world-json.js';
+export interface LevelRow {
+    id: string;
+    name: string;
+    vwldAssetId: string;
+    /** The `.vwld` asset is absent from `assets[]`, so this level has nothing to load. */
+    missingAsset: boolean;
+    start: boolean;
+    spawnPoints: number;
+    /** Placed objects tagged to this level. Untagged ones are global and belong to none. */
+    placed: number;
+}
+export declare function listLevels(world: JsonObject): LevelRow[];
+export interface LevelPlan {
+    modifications: WorldJsonModification[];
+    /** Said after the write. Never a reason to refuse. */
+    notes: string[];
+}
+/**
+ * Make `levelId` the level the game boots into — registry AND mirrors, together.
+ *
+ * Refused when the level's `.vwld` asset is missing or has no url: the mirrors are what actually
+ * boot the game, so writing `startLevelId` alone would leave `voxelUrl` describing the previous
+ * level, and the registry and the thing that loads would disagree with no error anywhere.
+ */
+export declare function planSetStart(world: JsonObject, levelId: string): LevelPlan;
+export declare function planRename(world: JsonObject, levelId: string, name: string): LevelPlan;
+export interface AddPlan extends LevelPlan {
+    level: LevelEntry;
+    /** True when this made the game multi-level for the first time. */
+    converted: boolean;
+}
+/**
+ * Register an existing `.vwld` asset as a level.
+ *
+ * Start-level policy matches `forge`'s: a game's FIRST level becomes the start, later ones do not,
+ * and `--make-start` overrides. Stealing the start from a working game because someone registered
+ * a second level would be the surprising outcome.
+ */
+export declare function planAdd(world: JsonObject, vwldAssetId: string, options: {
+    name?: string;
+    makeStart: boolean;
+}): AddPlan;
+export interface RemovePlan extends LevelPlan {
+    level: LevelEntry;
+    /** Placed instances tagged to this level, which go with it. */
+    placedRemoved: number;
+    /** Doors and key items scoped to it, which also go. */
+    scopedRemoved: string[];
+}
+/**
+ * Remove a level from the registry.
+ *
+ * Two refusals, matching the agent's `manage-levels delete` so the two lanes cannot disagree:
+ * the last level, and the START level. The second matters most — `startLevelId` naming nothing
+ * falls back to `levels[0]` at boot while the mirrors still describe the deleted level, which is
+ * the silent stale-mirror failure. Move the start first, deliberately.
+ *
+ * The `.vwld` asset is left alone: it may be large, nothing here deletes uploaded bytes, and a
+ * re-add is then free.
+ */
+export declare function planRemove(world: JsonObject, levelId: string): RemovePlan;

package/dist/levels/registry.js

@@ -0,0 +1,309 @@
+/**
+ * `bitmagic levels` — the level registry in `worldProfileData.levels`, without the web Creator.
+ *
+ * `forge` can CREATE levels but never could manage them: only a game's first forge becomes the
+ * start level (or `forge --make-start` at creation), so fixing a wrong start, renaming, or deleting
+ * a level meant opening the Creator.
+ *
+ * ── The invariant this file exists to respect ────────────────────────────────────────────────
+ *
+ * `worldProfileData` keeps three LEGACY MIRRORS — `voxelUrl`, `spawnPoints` and
+ * `playerSpawnPosition` — describing the START level, because frozen genre and work-template code
+ * boots from those rather than from the registry (see `WorldLevel` in game/src/types/game.ts).
+ *
+ * Nothing self-heals on the normal boot path. `applyBootLevelOverride` does recompute them, but
+ * only when the main screen's level chooser passes a `bootLevelId`. So a `startLevelId` moved
+ * without its mirrors boots the NEW level's objects, lighting and navmesh over the OLD level's
+ * terrain, and nothing throws. That is the failure this module exists to prevent.
+ *
+ * The mirrors come from `buildStartLevelMirrors` in `@bitmagic/world-forger`, deliberately rather
+ * than reimplemented — the same function the forge uses, carrying a subtlety worth not
+ * rediscovering: spawn mirrors are written ONLY when the level owns spawn points, because a level
+ * without its own inherits the globals, which are then already correct.
+ *
+ * Pure: it computes modifications and never applies them.
+ */
+import { buildConversionModifications, buildStartLevelMirrors, getLevels, getStartLevel, mintLevelId, } from '@bitmagic/world-forger/pipeline/index.js';
+import { CliError } from '../errors.js';
+import { isJsonObject } from '../project/world-json.js';
+/** The same document, seen through the shared helpers' narrower view. */
+function asWorldJson(world) {
+    return world;
+}
+function assetsOf(world) {
+    return (Array.isArray(world.assets) ? world.assets : []).filter(isJsonObject);
+}
+export function listLevels(world) {
+    const start = getStartLevel(asWorldJson(world));
+    const assets = assetsOf(world);
+    const objects = (Array.isArray(world.environmentObjects) ? world.environmentObjects : [])
+        .filter(isJsonObject);
+    return getLevels(asWorldJson(world)).map((level) => ({
+        id: level.id,
+        name: level.name,
+        vwldAssetId: level.vwldAssetId,
+        missingAsset: !assets.some((asset) => asset.id === level.vwldAssetId),
+        start: start !== null && start.id === level.id,
+        spawnPoints: level.spawnPoints?.length ?? 0,
+        placed: objects.filter((object) => object.levelId === level.id).length,
+    }));
+}
+function requireLevel(world, levelId) {
+    const levels = getLevels(asWorldJson(world));
+    const level = levels.find((entry) => entry.id === levelId);
+    if (level === undefined) {
+        throw new CliError(`No level with id "${levelId}" in this project. `
+            + (levels.length > 0
+                ? `This game has: ${levels.map((entry) => `${entry.id} ("${entry.name}")`).join(', ')}. `
+                : 'This game has no levels — `bitmagic forge` creates one. ')
+            + 'world.json is unchanged.');
+    }
+    return level;
+}
+/** The url a level's `.vwld` asset serves, or null when it is missing or not a level bake. */
+function vwldUrlFor(world, level) {
+    const asset = assetsOf(world).find((item) => item.id === level.vwldAssetId);
+    if (asset === undefined || asset.type !== 'vwld')
+        return null;
+    return typeof asset.url === 'string' && asset.url !== '' ? asset.url : null;
+}
+/**
+ * Make `levelId` the level the game boots into — registry AND mirrors, together.
+ *
+ * Refused when the level's `.vwld` asset is missing or has no url: the mirrors are what actually
+ * boot the game, so writing `startLevelId` alone would leave `voxelUrl` describing the previous
+ * level, and the registry and the thing that loads would disagree with no error anywhere.
+ */
+export function planSetStart(world, levelId) {
+    const level = requireLevel(world, levelId);
+    const current = getStartLevel(asWorldJson(world));
+    if (current !== null && current.id === levelId) {
+        throw new CliError(`"${level.name}" is already the start level. world.json is unchanged.`);
+    }
+    const vwldUrl = vwldUrlFor(world, level);
+    if (vwldUrl === null) {
+        throw new CliError(`Level "${level.name}" points at asset "${level.vwldAssetId}", which this project has no `
+            + 'loadable .vwld for — so it has nothing to boot. Fix the level first (`bitmagic assets '
+            + 'list` shows what is there). world.json is unchanged.');
+    }
+    return {
+        modifications: [
+            { type: 'set', path: ['startLevelId'], value: levelId },
+            // Without these the game boots the OLD level's terrain. See the file header.
+            ...buildStartLevelMirrors(level, vwldUrl),
+        ],
+        notes: (level.spawnPoints?.length ?? 0) === 0
+            ? [`"${level.name}" has no spawn points of its own, so it keeps the game's global ones.`]
+            : [],
+    };
+}
+export function planRename(world, levelId, name) {
+    const level = requireLevel(world, levelId);
+    const trimmed = name.trim();
+    if (trimmed === '')
+        throw new CliError('A level name cannot be empty. world.json is unchanged.');
+    if (trimmed === level.name) {
+        throw new CliError(`"${level.name}" already has that name. world.json is unchanged.`);
+    }
+    const clash = getLevels(asWorldJson(world)).some((e) => e.id !== levelId && e.name === trimmed);
+    return {
+        modifications: [{
+                type: 'update',
+                path: ['levels'],
+                predicate: (item) => isJsonObject(item) && item.id === levelId,
+                // An updater, not a `{ ...level, name }` snapshot (which is what the agent's tool builds):
+                // the snapshot was read before the write and reverts anything another writer changed on this
+                // level in between. Same reason editor/save.ts gives for its own level write.
+                value: (item) => ({ ...(isJsonObject(item) ? item : {}), name: trimmed }),
+            }],
+        notes: clash
+            ? [`Another level is also called "${trimmed}" — names are for humans, ids are what code uses.`]
+            : [],
+    };
+}
+/**
+ * Register an existing `.vwld` asset as a level.
+ *
+ * Start-level policy matches `forge`'s: a game's FIRST level becomes the start, later ones do not,
+ * and `--make-start` overrides. Stealing the start from a working game because someone registered
+ * a second level would be the surprising outcome.
+ */
+export function planAdd(world, vwldAssetId, options) {
+    const asset = assetsOf(world).find((item) => item.id === vwldAssetId);
+    if (asset === undefined) {
+        const available = assetsOf(world).filter((item) => item.type === 'vwld');
+        throw new CliError(`No asset with id "${vwldAssetId}" in this project. `
+            + (available.length > 0
+                ? `Baked levels here: ${available.map((a) => `${String(a.id)} ("${String(a.name)}")`).join(', ')}. `
+                : 'This project has no baked levels — `bitmagic forge` makes one. ')
+            + 'world.json is unchanged.');
+    }
+    if (asset.type !== 'vwld') {
+        throw new CliError(`Asset "${vwldAssetId}" is ${typeof asset.type === 'string' ? `a ${asset.type}` : 'an unknown'} `
+            + 'asset, not a baked level (.vwld). Only a level bake can become a level. '
+            + 'world.json is unchanged.');
+    }
+    const url = typeof asset.url === 'string' ? asset.url : '';
+    if (url === '') {
+        throw new CliError(`Asset "${vwldAssetId}" has no url, so a level made from it would have nothing to load. `
+            + 'world.json is unchanged.');
+    }
+    // Two levels on one bake is the same place twice, and the forge's re-bake path resolves a level
+    // by `vwldAssetId` — with duplicates it picks the first arbitrarily.
+    const sharing = getLevels(asWorldJson(world)).find((entry) => entry.vwldAssetId === vwldAssetId);
+    if (sharing !== undefined) {
+        throw new CliError(`Level "${sharing.name}" (${sharing.id}) already uses that bake. world.json is unchanged.`);
+    }
+    const assetName = typeof asset.name === 'string' && asset.name !== '' ? asset.name : vwldAssetId;
+    const level = {
+        id: mintLevelId(),
+        name: (options.name ?? assetName).trim() || assetName,
+        vwldAssetId,
+    };
+    const existing = getLevels(asWorldJson(world));
+    if (existing.length > 0) {
+        const makeStart = options.makeStart;
+        return {
+            level,
+            converted: false,
+            modifications: [
+                { type: 'push', path: ['levels'], value: level },
+                ...(makeStart
+                    ? [
+                        { type: 'set', path: ['startLevelId'], value: level.id },
+                        ...buildStartLevelMirrors(level, url),
+                    ]
+                    : []),
+            ],
+            notes: makeStart
+                ? [`"${level.name}" is now the start level.`]
+                : ['The start level is unchanged — pass --make-start, or use `bitmagic levels set-start`.'],
+        };
+    }
+    // No registry yet. If the game already HAS a world (a `voxelUrl` naming a registered bake), that
+    // world must become a level too — otherwise turning on multi-level would strand the place the
+    // game currently loads, with no entry naming it.
+    const conversion = safeConversion(world);
+    if (conversion !== null) {
+        return {
+            level,
+            converted: true,
+            modifications: [
+                // Everything the conversion does EXCEPT its own `levels` write, which named only level 1.
+                ...conversion.modifications.filter((mod) => !('path' in mod) || mod.path[0] !== 'levels'),
+                { type: 'set', path: ['levels'], value: [conversion.level1, level] },
+            ],
+            notes: [
+                `This game's existing world became level "${conversion.level1.name}" and remains the start `
+                    + 'level; every object that was not already tagged now belongs to it.',
+            ],
+        };
+    }
+    // A procedural game with no world of its own: the new level is the only one, so it must boot.
+    return {
+        level,
+        converted: false,
+        modifications: [
+            { type: 'set', path: ['levels'], value: [level] },
+            { type: 'set', path: ['startLevelId'], value: level.id },
+            ...buildStartLevelMirrors(level, url),
+        ],
+        notes: [`This is the game's first level, so it is the start level.`],
+    };
+}
+/**
+ * The legacy→levels conversion, or null when there is nothing to convert.
+ *
+ * Throws inside the shared helper when the current world is not a registered bake (a legacy map or
+ * an unregistered one); that is a refusal for the caller, not a crash.
+ */
+function safeConversion(world) {
+    try {
+        return buildConversionModifications(asWorldJson(world));
+    }
+    catch (error) {
+        throw new CliError('This game\'s current world is not a registered level bake, so it cannot be turned into a '
+            + `level alongside the new one: ${error instanceof Error ? error.message : String(error)} `
+            + 'Re-bake it with `bitmagic forge` first. world.json is unchanged.');
+    }
+}
+/**
+ * Remove a level from the registry.
+ *
+ * Two refusals, matching the agent's `manage-levels delete` so the two lanes cannot disagree:
+ * the last level, and the START level. The second matters most — `startLevelId` naming nothing
+ * falls back to `levels[0]` at boot while the mirrors still describe the deleted level, which is
+ * the silent stale-mirror failure. Move the start first, deliberately.
+ *
+ * The `.vwld` asset is left alone: it may be large, nothing here deletes uploaded bytes, and a
+ * re-add is then free.
+ */
+export function planRemove(world, levelId) {
+    const level = requireLevel(world, levelId);
+    const levels = getLevels(asWorldJson(world));
+    if (levels.length <= 1) {
+        throw new CliError('This is the game\'s only level, and a levels-mode game needs one. world.json is unchanged.');
+    }
+    const start = getStartLevel(asWorldJson(world));
+    if (start !== null && start.id === levelId) {
+        const other = levels.find((entry) => entry.id !== levelId);
+        throw new CliError(`"${level.name}" is the start level. Removing it would leave the game booting one level's `
+            + 'terrain under another\'s objects. Move the start first:\n'
+            + `  bitmagic levels set-start ${other?.id ?? '<levelId>'}\n`
+            + 'world.json is unchanged.');
+    }
+    const profile = isJsonObject(world.worldProfileData) ? world.worldProfileData : {};
+    const objects = (Array.isArray(world.environmentObjects) ? world.environmentObjects : [])
+        .filter(isJsonObject);
+    const placedRemoved = objects.filter((object) => object.levelId === levelId).length;
+    const modifications = [
+        {
+            type: 'remove',
+            path: ['levels'],
+            predicate: (item) => isJsonObject(item) && item.id === levelId,
+        },
+        // Instances belonging to this level go with it. Left behind they would load in no level at
+        // all — invisible, and still counted as references that pin their assets against a purge.
+        {
+            type: 'removeRoot',
+            path: ['environmentObjects'],
+            predicate: (item) => isJsonObject(item) && item.levelId === levelId,
+        },
+    ];
+    // Doors and key items are level-scoped the same way, and the agent's tool leaves them — which
+    // makes them permanent dead weight: they never spawn, yet `persist-level` still counts their
+    // assetIds as referenced, so the placeholder assets can never be purged either.
+    const scopedRemoved = [];
+    for (const key of ['doors', 'keyItems']) {
+        const entries = Array.isArray(profile[key]) ? profile[key].filter(isJsonObject) : [];
+        const doomed = entries.filter((entry) => entry.levelId === levelId).length;
+        if (doomed === 0)
+            continue;
+        scopedRemoved.push(`${doomed} ${key}`);
+        modifications.push({
+            type: 'remove',
+            path: [key],
+            predicate: (item) => isJsonObject(item) && item.levelId === levelId,
+        });
+    }
+    const notes = [];
+    if (placedRemoved > 0) {
+        notes.push(`${placedRemoved} placed object(s) belonged to it and were removed with it.`);
+    }
+    if (scopedRemoved.length > 0)
+        notes.push(`Also removed: ${scopedRemoved.join(', ')}.`);
+    // The start-screen chooser filters by id and is hand-authored; it warns and skips unknown ids on
+    // its own, so this is reported rather than rewritten.
+    if (choosersNaming(profile, levelId) > 0) {
+        notes.push('The main screen\'s level chooser still lists this level; it will skip it, but tidy '
+            + '`hud.startScreen.selections[].levelIds` when you get a chance.');
+    }
+    return { level, modifications, notes, placedRemoved, scopedRemoved };
+}
+function choosersNaming(profile, levelId) {
+    const hud = isJsonObject(profile.hud) ? profile.hud : {};
+    const startScreen = isJsonObject(hud.startScreen) ? hud.startScreen : {};
+    const selections = Array.isArray(startScreen.selections) ? startScreen.selections : [];
+    return selections.filter((step) => isJsonObject(step) && Array.isArray(step.levelIds) && step.levelIds.includes(levelId)).length;
+}
+//# sourceMappingURL=registry.js.map

package/dist/levels/registry.js.map

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

package/dist/messages/check.d.ts

@@ -0,0 +1,30 @@
+import type { EnvironmentName } from '../config/environments.js';
+import { type UnreadMessagesCache } from './notice.js';
+export declare function messagesCachePath(baseDir?: string): string;
+/**
+ * The last recorded answer, or null if there is none to trust.
+ *
+ * Missing, unreadable and malformed all collapse to null on purpose: the caller's next move is
+ * identical in every case — say nothing now, refresh in the background.
+ */
+export declare function readUnreadMessagesCache(baseDir?: string): UnreadMessagesCache | null;
+export declare function writeUnreadMessagesCache(cache: UnreadMessagesCache, baseDir?: string): void;
+/**
+ * The line bin.ts prints before a command runs — read from the cache, never the network.
+ *
+ * A cache belonging to a DIFFERENT environment answers a different question and is ignored:
+ * a dev broadcast must not nudge a prod session, or the other way round. The same rule
+ * `pendingUpdateNotice` applies to dist-tags.
+ */
+export declare function pendingMessagesNotice(environment: EnvironmentName | undefined, baseDir?: string, now?: number): string | null;
+/**
+ * Refresh the cache if it is stale. Fire-and-forget: callers must not await this for its value.
+ *
+ * A cache about a different environment is refreshed immediately however recent it is —
+ * switching environments must not leave the nudge mute for the rest of its interval.
+ *
+ * On failure the result is still written, with `unread: null`, so an offline machine backs off
+ * for the interval instead of asking on every command. That is why the failure marker is null
+ * rather than 0: zero would be a claim ("you have nothing unread"), null is an admission.
+ */
+export declare function refreshUnreadMessagesInBackground(environment: EnvironmentName, apiUrl: string, accessToken: string, now?: number, baseDir?: string, fetchImpl?: typeof globalThis.fetch): Promise<void>;

package/dist/messages/check.js

@@ -0,0 +1,119 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { defaultBaseDir } from '../config/credentials.js';
+import { apiServerHeaders } from '../telemetry/request-headers.js';
+import { isMessagesCacheStale, unreadMessagesNotice, } from './notice.js';
+/**
+ * Reading and refreshing the unread-messages count.
+ *
+ * Deliberately the same shape as update/check.ts, which already solved every hard part: the
+ * notice is decided from the CACHE ONLY (never the network, so printing costs nothing), the
+ * refresh is fire-and-forget and bounded, and every filesystem error is swallowed because this
+ * is a hint, not a thing worth failing a command over.
+ */
+/**
+ * Cap on the background refresh.
+ *
+ * A pending fetch keeps Node alive, so an unbounded request would hold a finished command open
+ * for as long as the network sulks. Matches the update check's allowance.
+ */
+const REFRESH_TIMEOUT_MS = 2000;
+export function messagesCachePath(baseDir = defaultBaseDir()) {
+    return path.join(baseDir, 'messages-check.json');
+}
+function isCache(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const c = value;
+    return ((c.environment === 'dev' || c.environment === 'prod' || c.environment === 'local') &&
+        (c.unread === null || typeof c.unread === 'number') &&
+        (c.inboxUrl === null || typeof c.inboxUrl === 'string') &&
+        typeof c.checkedAt === 'number');
+}
+/**
+ * The last recorded answer, or null if there is none to trust.
+ *
+ * Missing, unreadable and malformed all collapse to null on purpose: the caller's next move is
+ * identical in every case — say nothing now, refresh in the background.
+ */
+export function readUnreadMessagesCache(baseDir = defaultBaseDir()) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(messagesCachePath(baseDir), 'utf-8'));
+        return isCache(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeUnreadMessagesCache(cache, baseDir = defaultBaseDir()) {
+    try {
+        fs.mkdirSync(baseDir, { recursive: true });
+        fs.writeFileSync(messagesCachePath(baseDir), `${JSON.stringify(cache)}\n`);
+    }
+    catch {
+        // A cache we cannot write is a nudge one run late, not an error anyone should see.
+    }
+}
+/**
+ * The line bin.ts prints before a command runs — read from the cache, never the network.
+ *
+ * A cache belonging to a DIFFERENT environment answers a different question and is ignored:
+ * a dev broadcast must not nudge a prod session, or the other way round. The same rule
+ * `pendingUpdateNotice` applies to dist-tags.
+ */
+export function pendingMessagesNotice(environment, baseDir, now = Date.now()) {
+    if (environment === undefined)
+        return null;
+    const cache = readUnreadMessagesCache(baseDir);
+    if (cache === null || cache.environment !== environment)
+        return null;
+    return unreadMessagesNotice(cache, now);
+}
+/** Ask api-server for the caller's count. Null on any failure — this never throws. */
+async function fetchUnread(apiUrl, accessToken, fetchImpl) {
+    try {
+        const response = await fetchImpl(`${apiUrl}/api/cli/v1/messages/unread`, {
+            headers: {
+                ...apiServerHeaders(),
+                Authorization: `Bearer ${accessToken}`,
+                Accept: 'application/json',
+            },
+            signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            return null;
+        const data = await response.json();
+        if (typeof data !== 'object' || data === null)
+            return null;
+        const d = data;
+        if (typeof d.unreadCount !== 'number' || typeof d.inboxUrl !== 'string')
+            return null;
+        return { unreadCount: d.unreadCount, inboxUrl: d.inboxUrl };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Refresh the cache if it is stale. Fire-and-forget: callers must not await this for its value.
+ *
+ * A cache about a different environment is refreshed immediately however recent it is —
+ * switching environments must not leave the nudge mute for the rest of its interval.
+ *
+ * On failure the result is still written, with `unread: null`, so an offline machine backs off
+ * for the interval instead of asking on every command. That is why the failure marker is null
+ * rather than 0: zero would be a claim ("you have nothing unread"), null is an admission.
+ */
+export async function refreshUnreadMessagesInBackground(environment, apiUrl, accessToken, now = Date.now(), baseDir, fetchImpl = globalThis.fetch) {
+    const cache = readUnreadMessagesCache(baseDir);
+    if (cache !== null && cache.environment === environment && !isMessagesCacheStale(cache, now))
+        return;
+    const result = await fetchUnread(apiUrl, accessToken, fetchImpl);
+    writeUnreadMessagesCache({
+        environment,
+        unread: result === null ? null : result.unreadCount,
+        inboxUrl: result === null ? null : result.inboxUrl,
+        checkedAt: now,
+    }, baseDir);
+}
+//# sourceMappingURL=check.js.map

package/dist/messages/check.js.map

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

package/dist/messages/notice.d.ts

@@ -0,0 +1,58 @@
+import type { EnvironmentName } from '../config/environments.js';
+/**
+ * The unread-messages nudge.
+ *
+ * Bitmagic broadcasts reach web creators through the portal's notification bell. A CLI-lane
+ * creator may never open the portal at all, so a command prints a one-line pointer instead —
+ * the same shape as the update nudge next door, and for the same reason: a hint worth giving,
+ * never worth failing or slowing a command over.
+ *
+ * The CLI never CONSUMES a message. Reading is an act, and the read receipt is what tells an
+ * admin whether a broadcast actually landed — a terminal glancing at a count is not that.
+ */
+/** What is remembered between runs, so no command pays for the network. */
+export interface UnreadMessagesCache {
+    /**
+     * Which environment the count is about.
+     *
+     * Credentials are per environment and a creator can hold a prod and a dev login at once, so
+     * an answer about one says nothing about the other. Mirrors `UpdateCheckCache.tag`, including
+     * the consequence: a cache for the other environment reads as absent and is refreshed.
+     */
+    environment: EnvironmentName;
+    /** The count, or null when the last check could not reach the server (a back-off marker). */
+    unread: number | null;
+    /** Where to read them — the server hands this over; see check.ts. */
+    inboxUrl: string | null;
+    /** Epoch ms of that check. */
+    checkedAt: number;
+}
+/**
+ * How stale a count may be before it is refreshed.
+ *
+ * An hour, matching the release line's update check. Broadcasts are rare and never urgent to
+ * the minute, and the cost of being wrong is one extra line of stderr.
+ */
+export declare const MESSAGES_CHECK_INTERVAL_MS: number;
+/**
+ * How old a cached count may be and still be PRINTED.
+ *
+ * Separate from the refresh interval, and the thing that stops a laptop that has been offline
+ * for a fortnight nagging every single command about a message read in a browser on day one.
+ * Past this, the nudge goes quiet until a check succeeds again.
+ */
+export declare const MESSAGES_NOTICE_MAX_AGE_MS: number;
+/** Whether the cached answer should be refreshed in the background. */
+export declare function isMessagesCacheStale(cache: UnreadMessagesCache | null, now: number): boolean;
+/**
+ * The line to print, or null to stay quiet.
+ *
+ * Quiet for: no cache at all (a first-ever run pays one silent command, exactly as the update
+ * notice does), a failed check (`unread: null` — an unreachable server is not evidence of
+ * anything), nothing unread, no inbox URL to point at, and an answer past its max age.
+ *
+ * The wording is deliberately soft. The count can be up to an interval stale and the CLI cannot
+ * know whether the message was read in a browser five minutes ago, so it reports rather than
+ * instructs.
+ */
+export declare function unreadMessagesNotice(cache: UnreadMessagesCache | null, now: number): string | null;