@bitmagic/cli 0.1.46-dev.3 → 0.1.46-dev.4

package/dist/telemetry/command-context.d.ts

@@ -0,0 +1,73 @@
+import { type Environment } from '../config/environments.js';
+/**
+ * What is driving the CLI.
+ *
+ * - `claude-code` — a Claude Code session (its `CLAUDECODE` env var, verified).
+ * - `json` — some agent, unidentified: `--json` is the flag agents pass.
+ * - `tty` — a person at a terminal.
+ * - `pipe` — a script or CI: no `--json`, no terminal.
+ *
+ * Add an agent here only once its marker is verified against the real thing; a
+ * guessed env var never fires and just misleads whoever reads the table.
+ */
+export type CliDriver = 'claude-code' | 'json' | 'tty' | 'pipe';
+export declare function detectDriver(input: {
+    json: boolean;
+    env: Record<string, string | undefined>;
+    isTTY: boolean;
+}): CliDriver;
+/**
+ * `DO_NOT_TRACK` set to anything but `0`/`false`/empty. The convention says
+ * `1`; being generous about the spelling is the polite reading of a signal
+ * that only ever means "please don't".
+ *
+ * Lives here rather than in report.ts because it is consulted BEFORE anything
+ * is collected — `beginCommand` skips the whole snapshot when it is set — and
+ * report.ts already imports this module, so the other direction would close a
+ * cycle. Re-exported from report.ts, which is where callers expect it.
+ */
+export declare function isTelemetryDisabled(env: Record<string, string | undefined>): boolean;
+export interface TokenSnapshot {
+    accessToken: string;
+    /** Epoch milliseconds, as stored. */
+    expiresAt: number;
+}
+export interface CommandContext {
+    /** As typed, so a report reads the way the creator invoked it: `publish`, `generate skybox`. */
+    name: string;
+    json: boolean;
+    driver: CliDriver;
+    /**
+     * Where this command is talking to, resolved ONCE here through the same
+     * precedence every command uses (`--env` > BITMAGIC_ENV > the project's
+     * bitmagic.json > the stored default). `report.ts` reads it rather than
+     * resolving again: a second resolution is a second chance to disagree, and
+     * one that skipped the project tier would send a project's beacons to a
+     * different environment than the work they describe.
+     *
+     * Null only when resolution threw — an unknown `--env`, or a project whose
+     * `environment` field is not a valid name. The command itself fails with
+     * that message moments later; there is simply nowhere to report it to.
+     */
+    environment: Environment | null;
+    /** Epoch milliseconds when the command began. */
+    startedAt: number;
+    /** See the module header: the stored access token at start, for the one command that removes it. */
+    tokenSnapshot: TokenSnapshot | null;
+}
+export interface BeginCommandInput {
+    name: string;
+    json: boolean;
+    explicitEnv?: string;
+    env?: Record<string, string | undefined>;
+    isTTY?: boolean;
+    now?: () => number;
+    baseDir?: string;
+    /** Where to look for the project's own environment pin; defaults to process.cwd(). */
+    cwd?: string;
+}
+export declare function beginCommand(input: BeginCommandInput): CommandContext;
+/** The running command, or null before `beginCommand` — e.g. under a test that calls a module directly. */
+export declare function currentCommand(): CommandContext | null;
+/** Test seam: forget the running command, so one test's context cannot leak into the next. */
+export declare function resetCommandContextForTests(): void;

package/dist/telemetry/command-context.js

@@ -0,0 +1,114 @@
+/**
+ * Which command this process is running — the one piece of state the CLI's usage
+ * reporting is built on.
+ *
+ * One process runs one command, so this is process-scoped: cli.ts's wrapper calls
+ * {@link beginCommand} once before the command's `run`, and two readers use it —
+ * `request-headers.ts`, which names the command on every api-server call, and
+ * `report.ts`, which sends the outcome when the command ends. It is the CLI's
+ * equivalent of a request context, and it lives here rather than being threaded
+ * through every command signature because there are five separate fetch sites and
+ * eighteen commands, and a parameter every one of them must remember to pass is
+ * how one of them ends up unlabelled.
+ *
+ * Nothing here reaches the network. The token snapshot is a file read, and it
+ * exists for exactly one command: `logout` removes the stored credentials, so by
+ * the time its outcome is reported there is nothing to authenticate the report
+ * with — except what was there when it started.
+ */
+import { readCredentials } from '../config/credentials.js';
+import { resolveEnvironmentForCommand } from '../config/environments.js';
+const AGENT_ENV_MARKERS = [['CLAUDECODE', 'claude-code']];
+export function detectDriver(input) {
+    for (const [marker, driver] of AGENT_ENV_MARKERS) {
+        if (input.env[marker])
+            return driver;
+    }
+    if (input.json)
+        return 'json';
+    return input.isTTY ? 'tty' : 'pipe';
+}
+/**
+ * `DO_NOT_TRACK` set to anything but `0`/`false`/empty. The convention says
+ * `1`; being generous about the spelling is the polite reading of a signal
+ * that only ever means "please don't".
+ *
+ * Lives here rather than in report.ts because it is consulted BEFORE anything
+ * is collected — `beginCommand` skips the whole snapshot when it is set — and
+ * report.ts already imports this module, so the other direction would close a
+ * cycle. Re-exported from report.ts, which is where callers expect it.
+ */
+export function isTelemetryDisabled(env) {
+    const value = env.DO_NOT_TRACK?.trim().toLowerCase();
+    return value !== undefined && value !== '' && value !== '0' && value !== 'false';
+}
+let current = null;
+/**
+ * The environment this command targets, or null if it cannot be resolved.
+ *
+ * `resolveEnvironmentForCommand` is the same entry point the commands use, so
+ * a project pinned to an environment reports there too. It throws for an
+ * unknown name typed right now (a bad `--env`, a bad `bitmagic.json`), which
+ * the command surfaces properly — here it only means "no environment to report
+ * to", never a failed command.
+ */
+function snapshotEnvironment(input, env) {
+    try {
+        return resolveEnvironmentForCommand({
+            explicit: input.explicitEnv,
+            cwd: input.cwd,
+            baseDir: input.baseDir,
+            env,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The stored access token for `environment`, or null.
+ *
+ * Every failure collapses to null on purpose: no environment, an unreadable
+ * credentials file, nothing stored — the command itself will report whichever
+ * of those matters, in its own words. This is a snapshot for a report, and a
+ * report is never worth failing a command over.
+ */
+function snapshotToken(environment, baseDir) {
+    if (environment === null)
+        return null;
+    try {
+        const stored = readCredentials(environment.name, baseDir);
+        return stored ? { accessToken: stored.accessToken, expiresAt: stored.expiresAt } : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function beginCommand(input) {
+    const env = input.env ?? process.env;
+    // Nothing is collected for a creator who opted out. Both snapshots below are
+    // filesystem work — a walk up the tree for the project's bitmagic.json, then
+    // credentials.json — done on every one of the eighteen commands, including
+    // the offline ones and the `reload` hook that runs after every agent turn.
+    // None of it has a purpose if no report will be sent.
+    const collect = !isTelemetryDisabled(env);
+    const environment = collect ? snapshotEnvironment(input, env) : null;
+    current = {
+        name: input.name,
+        json: input.json,
+        driver: detectDriver({ json: input.json, env, isTTY: input.isTTY ?? process.stdout.isTTY === true }),
+        environment,
+        startedAt: (input.now ?? Date.now)(),
+        tokenSnapshot: collect ? snapshotToken(environment, input.baseDir) : null,
+    };
+    return current;
+}
+/** The running command, or null before `beginCommand` — e.g. under a test that calls a module directly. */
+export function currentCommand() {
+    return current;
+}
+/** Test seam: forget the running command, so one test's context cannot leak into the next. */
+export function resetCommandContextForTests() {
+    current = null;
+}
+//# sourceMappingURL=command-context.js.map

package/dist/telemetry/command-context.js.map

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

package/dist/telemetry/report.d.ts

@@ -0,0 +1,43 @@
+import { isTelemetryDisabled } from './command-context.js';
+export { isTelemetryDisabled };
+/**
+ * Cap on each request the report makes (the token refresh, when one is due, and
+ * the POST itself). A pending fetch keeps Node alive, so an unbounded one would
+ * hold a finished command open for as long as the network sulks.
+ */
+export declare const REPORT_TIMEOUT_MS = 1500;
+export declare const CLI_EVENTS_PATH = "/api/cli/v1/events";
+export interface CommandReport {
+    /** `finished` for every command's end; `started` for a long-running command once it is up. */
+    stage: 'started' | 'finished';
+    ok?: boolean;
+    durationMs?: number;
+    exitCode?: number;
+    /** A category — `CliError.code`, `cli_error`, `crash:TypeError` — never a message. */
+    failure?: string;
+}
+export interface ReportDeps {
+    fetch: typeof globalThis.fetch;
+    env: Record<string, string | undefined>;
+    now?: () => number;
+    /** Where credentials live; tests point this at a temp dir. */
+    baseDir?: string;
+}
+/**
+ * The failure category for an error that is not a CliError — a genuine bug, not
+ * a refusal we wrote a message for. `crash:TypeError`, `crash:RangeError`: the
+ * error's class, which says what kind of bug without saying anything about the
+ * creator's machine. Anything odd in the name is folded to `_` so the value
+ * always fits the shape api-server accepts.
+ */
+export declare function crashCategory(error: unknown): string;
+/**
+ * Report the running command's `report` to api-server. Resolves when the report
+ * has been sent, refused, or given up on — always, and never by throwing.
+ *
+ * Callers `await` it (bounded, see above) rather than fire and forget: on the
+ * failure path cli.ts calls `process.exit` next, which would otherwise cut the
+ * request off mid-flight, and on the success path the pending fetch would keep
+ * the process alive for the same time either way.
+ */
+export declare function reportCommandEvent(report: CommandReport, deps?: ReportDeps): Promise<void>;

package/dist/telemetry/report.js

@@ -0,0 +1,123 @@
+/**
+ * The command beacon: one `POST /api/cli/v1/events` per command, saying how it went.
+ *
+ * Why it exists: api-server can see the commands that call it — but `dev`,
+ * `build`, `check`, `verify` and `reload` are offline by design, and even a
+ * `publish` that fails on a stale verify never reaches the server. This is how
+ * every command becomes visible, and how the ones the server does see get an
+ * end-to-end outcome and duration to go with the server's own event. The
+ * server turns it into `cli_command` / `cli_command_started` (see
+ * `api-server/src/cli/cli-analytics.ts`); nothing goes to Google from here.
+ *
+ * Contract, in order of importance:
+ *
+ *   1. It never fails or delays a command. Every failure path — not logged in,
+ *      no network, a slow server, a bad `--env` — returns silently. It is
+ *      bounded to {@link REPORT_TIMEOUT_MS} per request so a finished command is
+ *      never held open by a sulking network (the same reasoning as
+ *      update/check.ts). It never prints.
+ *   2. It sends categories, never messages: the command name, ok/failed, the
+ *      exit code, a `CliError.code`, and a duration. A message can name a path
+ *      or a game; none of that belongs in an analytics event.
+ *   3. It is authenticated with the creator's own token, so the server can key
+ *      the event to the account and look up their real Pro state. No token, no
+ *      report — an anonymous beacon would be a spammable endpoint for nothing.
+ *   4. `DO_NOT_TRACK=1` (the cross-tool convention, consoledonottrack.com)
+ *      turns it off. It does not touch the ordinary api-server calls a command
+ *      makes — those are the command's work, and the server logs them anyway.
+ */
+import { resolveAuth0ClientId } from '../config/environments.js';
+import { getAccessToken } from '../auth/session.js';
+import { apiServerHeaders } from './request-headers.js';
+import { currentCommand, isTelemetryDisabled } from './command-context.js';
+// Re-exported because this is where the opt-out is enforced for a report that is already
+// under way; `beginCommand` consults the same predicate to skip collecting anything at all.
+export { isTelemetryDisabled };
+/**
+ * Cap on each request the report makes (the token refresh, when one is due, and
+ * the POST itself). A pending fetch keeps Node alive, so an unbounded one would
+ * hold a finished command open for as long as the network sulks.
+ */
+export const REPORT_TIMEOUT_MS = 1500;
+export const CLI_EVENTS_PATH = '/api/cli/v1/events';
+/**
+ * The failure category for an error that is not a CliError — a genuine bug, not
+ * a refusal we wrote a message for. `crash:TypeError`, `crash:RangeError`: the
+ * error's class, which says what kind of bug without saying anything about the
+ * creator's machine. Anything odd in the name is folded to `_` so the value
+ * always fits the shape api-server accepts.
+ */
+export function crashCategory(error) {
+    const name = error instanceof Error && error.name ? error.name : 'unknown';
+    return `crash:${name.replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 40)}`;
+}
+/** The given fetch, with every call bounded by REPORT_TIMEOUT_MS. */
+function boundedFetch(fetchImpl) {
+    return (input, init) => fetchImpl(input, { ...init, signal: AbortSignal.timeout(REPORT_TIMEOUT_MS) });
+}
+/**
+ * The token to authenticate the report with, or null for "no report".
+ *
+ * The stored token first — refreshed if it has expired, exactly as any command
+ * would, so a report never wastes a request on a 401 — and failing that the
+ * snapshot taken when the command began, which is what `logout` leaves behind.
+ */
+async function resolveReportToken(environment, command, deps) {
+    try {
+        const clientId = resolveAuth0ClientId(environment, deps.env);
+        return await getAccessToken(environment, clientId, {
+            fetch: boundedFetch(deps.fetch),
+            sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+            now: deps.now,
+        }, deps.baseDir);
+    }
+    catch {
+        const snapshot = command.tokenSnapshot;
+        const now = (deps.now ?? Date.now)();
+        return snapshot !== null && snapshot.expiresAt > now ? snapshot.accessToken : null;
+    }
+}
+function defaultDeps() {
+    return { fetch: globalThis.fetch, env: process.env };
+}
+/**
+ * Report the running command's `report` to api-server. Resolves when the report
+ * has been sent, refused, or given up on — always, and never by throwing.
+ *
+ * Callers `await` it (bounded, see above) rather than fire and forget: on the
+ * failure path cli.ts calls `process.exit` next, which would otherwise cut the
+ * request off mid-flight, and on the success path the pending fetch would keep
+ * the process alive for the same time either way.
+ */
+export async function reportCommandEvent(report, deps = defaultDeps()) {
+    try {
+        if (isTelemetryDisabled(deps.env))
+            return;
+        const command = currentCommand();
+        if (command === null)
+            return;
+        // Resolved once, at command start — see CommandContext.environment for why
+        // this must not resolve again. Null means it could not be resolved at all,
+        // so there is nowhere to send this.
+        const environment = command.environment;
+        if (environment === null)
+            return;
+        const token = await resolveReportToken(environment, command, deps);
+        if (token === null)
+            return;
+        await boundedFetch(deps.fetch)(`${environment.apiUrl}${CLI_EVENTS_PATH}`, {
+            method: 'POST',
+            headers: {
+                ...apiServerHeaders(),
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ command: command.name, ...report }),
+        });
+    }
+    catch {
+        // Best-effort by design — see the module header. Whatever went wrong here,
+        // the command's own outcome has already been decided and printed.
+    }
+}
+//# sourceMappingURL=report.js.map

package/dist/telemetry/report.js.map

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

package/dist/telemetry/request-headers.d.ts

@@ -0,0 +1,14 @@
+export declare const CLI_COMMAND_HEADER = "X-Bitmagic-Cli-Command";
+export declare const CLI_DRIVER_HEADER = "X-Bitmagic-Cli-Driver";
+/** `bitmagic-cli/0.1.46 (darwin-arm64; node/v22.12.0)` — the shape api-server's context reader parses. */
+export declare function userAgent(): string;
+/**
+ * Spread these into the `headers` of every fetch aimed at api-server. Callers
+ * add their own `Authorization`, `Accept` and `Content-Type` after — nothing
+ * here collides with those.
+ *
+ * The command headers are present only once cli.ts has begun a command; a
+ * module exercised directly (a test, a future library caller) still identifies
+ * the CLI, just not the command.
+ */
+export declare function apiServerHeaders(): Record<string, string>;

package/dist/telemetry/request-headers.js

@@ -0,0 +1,48 @@
+/**
+ * The headers every api-server call carries, so the server's analytics know who
+ * asked and why.
+ *
+ * The CLI never sends analytics to Google itself — the GA4 Measurement Protocol
+ * needs an API secret, and a public npm package cannot keep one. api-server
+ * emits every event instead (`api-server/src/cli/cli-analytics.ts` reads these
+ * headers back as `cli_version`, `cli_platform`, `cli_node`, `cli_command` and
+ * `cli_driver`). That is what lets a `cli_asset_generated` event tell `generate
+ * image` from `cover`, which share a route, and a `publish` from a `forge`,
+ * which share the signed-URL route.
+ *
+ * Only for api-server. GCS signed URLs and the npm registry get nothing from
+ * here — a signed PUT can refuse headers it did not sign for, and neither has
+ * any use for them.
+ */
+import { currentCliVersion } from '../update/cli-version.js';
+import { currentCommand } from './command-context.js';
+export const CLI_COMMAND_HEADER = 'X-Bitmagic-Cli-Command';
+export const CLI_DRIVER_HEADER = 'X-Bitmagic-Cli-Driver';
+let cachedUserAgent = null;
+/** `bitmagic-cli/0.1.46 (darwin-arm64; node/v22.12.0)` — the shape api-server's context reader parses. */
+export function userAgent() {
+    if (cachedUserAgent === null) {
+        const version = currentCliVersion() || 'unknown';
+        cachedUserAgent = `bitmagic-cli/${version} (${process.platform}-${process.arch}; node/${process.version})`;
+    }
+    return cachedUserAgent;
+}
+/**
+ * Spread these into the `headers` of every fetch aimed at api-server. Callers
+ * add their own `Authorization`, `Accept` and `Content-Type` after — nothing
+ * here collides with those.
+ *
+ * The command headers are present only once cli.ts has begun a command; a
+ * module exercised directly (a test, a future library caller) still identifies
+ * the CLI, just not the command.
+ */
+export function apiServerHeaders() {
+    const headers = { 'User-Agent': userAgent() };
+    const command = currentCommand();
+    if (command) {
+        headers[CLI_COMMAND_HEADER] = command.name;
+        headers[CLI_DRIVER_HEADER] = command.driver;
+    }
+    return headers;
+}
+//# sourceMappingURL=request-headers.js.map

package/dist/telemetry/request-headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-headers.js","sourceRoot":"","sources":["../../src/telemetry/request-headers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,MAAM,CAAC,MAAM,kBAAkB,GAAG,wBAAwB,CAAC;AAC3D,MAAM,CAAC,MAAM,iBAAiB,GAAG,uBAAuB,CAAC;AAEzD,IAAI,eAAe,GAAkB,IAAI,CAAC;AAE1C,0GAA0G;AAC1G,MAAM,UAAU,SAAS;IACvB,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,iBAAiB,EAAE,IAAI,SAAS,CAAC;QACjD,eAAe,GAAG,gBAAgB,OAAO,KAAK,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,UAAU,OAAO,CAAC,OAAO,GAAG,CAAC;IAC7G,CAAC;IACD,OAAO,eAAe,CAAC;AACzB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,OAAO,GAA2B,EAAE,YAAY,EAAE,SAAS,EAAE,EAAE,CAAC;IACtE,MAAM,OAAO,GAAG,cAAc,EAAE,CAAC;IACjC,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,CAAC,kBAAkB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;QAC3C,OAAO,CAAC,iBAAiB,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9C,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/update/check.d.ts

@@ -1,3 +1,4 @@
+import type { EnvironmentName } from '../config/environments.js';
 import { type UpdateCheckCache, type UpdateTag } from './notice.js';
 export declare function updateCachePath(baseDir?: string): string;
 /**
@@ -24,6 +25,19 @@ export declare function fetchTagVersion(tag: UpdateTag, fetchImpl?: typeof globa
  * every command wait on npm to be told something it could just as well be told tomorrow.
  */
 export declare function pendingUpdateNotice(currentVersion: string, baseDir?: string): string | null;
+/**
+ * The single line bin.ts prints before a command runs — at most one install command, ever.
+ *
+ * The wrong-line notice wins over the newer-version one, and suppresses it. Both at once would
+ * print two different `npm i -g` commands in the same breath ("update to 0.1.45 on your line" next
+ * to "be on the other line"), which is the ambiguity this exists to end: a creator standing in a
+ * project should never have to choose which one they meant.
+ *
+ * `projectEnvironment` is the project's committed pin, or undefined outside a project and for one
+ * that has none. Undefined leaves the old behaviour exactly as it was: nothing here invents a line
+ * for a directory that never claimed one.
+ */
+export declare function startupNotice(currentVersion: string, projectEnvironment: EnvironmentName | undefined, baseDir?: string): string | null;
 /**
  * Refresh the cache if it is stale. Fire-and-forget: callers must not await this.
  *

package/dist/update/check.js

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { defaultBaseDir } from '../config/credentials.js';
-import { cliUpdateNotice, isCacheStale, updateTagFor, } from './notice.js';
+import { cliLineMismatchNotice, cliUpdateNotice, isCacheStale, updateTagFor, } from './notice.js';
 /** Public registry metadata, one document per dist-tag. No auth, no scope needed. */
 const NPM_PACKAGE_URL = 'https://registry.npmjs.org/@bitmagic/cli';
 /**
@@ -90,6 +90,22 @@ export function pendingUpdateNotice(currentVersion, baseDir) {
         return null;
     return cliUpdateNotice(currentVersion, cache.latest);
 }
+/**
+ * The single line bin.ts prints before a command runs — at most one install command, ever.
+ *
+ * The wrong-line notice wins over the newer-version one, and suppresses it. Both at once would
+ * print two different `npm i -g` commands in the same breath ("update to 0.1.45 on your line" next
+ * to "be on the other line"), which is the ambiguity this exists to end: a creator standing in a
+ * project should never have to choose which one they meant.
+ *
+ * `projectEnvironment` is the project's committed pin, or undefined outside a project and for one
+ * that has none. Undefined leaves the old behaviour exactly as it was: nothing here invents a line
+ * for a directory that never claimed one.
+ */
+export function startupNotice(currentVersion, projectEnvironment, baseDir) {
+    const mismatch = projectEnvironment === undefined ? null : cliLineMismatchNotice(currentVersion, projectEnvironment);
+    return mismatch ?? pendingUpdateNotice(currentVersion, baseDir);
+}
 /**
  * Refresh the cache if it is stale. Fire-and-forget: callers must not await this.
  *

package/dist/update/check.js.map

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

package/dist/update/notice.d.ts

@@ -1,3 +1,4 @@
+import type { EnvironmentName } from '../config/environments.js';
 /** Which published line a build came from: a prerelease was installed from `@bitmagic/cli@dev`. */
 export type UpdateTag = 'latest' | 'dev';
 /**
@@ -11,6 +12,32 @@ export type UpdateTag = 'latest' | 'dev';
 export declare function updateTagFor(version: string): UpdateTag;
 /** How to install the line a build is already on, so a nudge never moves someone between lines. */
 export declare function installCommandFor(tag: UpdateTag): string;
+/**
+ * What to call a line in a sentence.
+ *
+ * The dev line says "prerelease" out loud because the only place this is used asks someone to
+ * install it, and portal/src/cli-install.ts is right that putting an untested build on the machine
+ * of someone who never opted into testing is the worse failure. Being asked to cross lines is
+ * legitimate — the project's environment is what wants it — but nobody should cross without knowing
+ * which side they are landing on.
+ */
+export declare function describeUpdateTag(tag: UpdateTag): string;
+/**
+ * Which line a PROJECT's CLI should come from — the one answer to "dev or prod?" for anyone
+ * standing in a project directory, and the reason nobody should ever be asked.
+ *
+ * The project decides because the project is where the mismatch bites: new `/api/cli/v1` endpoints
+ * reach the dev api-server before production, so a prerelease run against `prod` calls endpoints
+ * that are not there yet, and a release run against `dev` is behind the engine that environment
+ * serves. `local` sits with `dev` — a localhost api-server is built from the same `main` a
+ * prerelease is cut from, so it is ahead of the release by construction.
+ *
+ * Note this is NOT `updateTagFor` applied to something else: that reads a version string and
+ * answers "which line is this build ON", which is a fact about the install. This answers "which
+ * line SHOULD it be on here", which is a fact about the project. The two disagreeing is exactly
+ * what `cliLineMismatchNotice` reports.
+ */
+export declare function updateTagForEnvironment(environment: EnvironmentName): UpdateTag;
 /**
  * How stale a cached npm answer may be before it is refreshed.
  *
@@ -46,3 +73,16 @@ export declare function isCacheStale(cache: UpdateCheckCache | null, now: number
  * 0.1.46-dev.3 to "update" to the older 0.1.45 release.
  */
 export declare function cliUpdateNotice(currentVersion: string, latestVersion: string | null | undefined): string | null;
+/**
+ * The line to say when the CLI running inside a project came from the other one.
+ *
+ * This is the one place the two lines are deliberately crossed, and it needs no version comparison
+ * to do it: whatever the numbers say, a project pinned to `dev` wants the dev line and a project
+ * pinned to `prod` wants the release. Version-driven nudges structurally cannot report this — a
+ * prerelease sitting in a `prod` project is *ahead* of the release tag, so `cliUpdateNotice` is
+ * correctly silent about a CLI that is on the wrong line entirely.
+ *
+ * `projectEnvironment` must be a project's committed pin, never a resolved environment: a one-off
+ * `--env` is a statement about this command, not about which CLI belongs in this directory.
+ */
+export declare function cliLineMismatchNotice(currentVersion: string, projectEnvironment: EnvironmentName): string | null;

package/dist/update/notice.js

@@ -14,6 +14,36 @@ export function updateTagFor(version) {
 export function installCommandFor(tag) {
     return tag === 'dev' ? 'npm i -g @bitmagic/cli@dev' : 'npm i -g @bitmagic/cli';
 }
+/**
+ * What to call a line in a sentence.
+ *
+ * The dev line says "prerelease" out loud because the only place this is used asks someone to
+ * install it, and portal/src/cli-install.ts is right that putting an untested build on the machine
+ * of someone who never opted into testing is the worse failure. Being asked to cross lines is
+ * legitimate — the project's environment is what wants it — but nobody should cross without knowing
+ * which side they are landing on.
+ */
+export function describeUpdateTag(tag) {
+    return tag === 'dev' ? 'dev (prerelease)' : 'release';
+}
+/**
+ * Which line a PROJECT's CLI should come from — the one answer to "dev or prod?" for anyone
+ * standing in a project directory, and the reason nobody should ever be asked.
+ *
+ * The project decides because the project is where the mismatch bites: new `/api/cli/v1` endpoints
+ * reach the dev api-server before production, so a prerelease run against `prod` calls endpoints
+ * that are not there yet, and a release run against `dev` is behind the engine that environment
+ * serves. `local` sits with `dev` — a localhost api-server is built from the same `main` a
+ * prerelease is cut from, so it is ahead of the release by construction.
+ *
+ * Note this is NOT `updateTagFor` applied to something else: that reads a version string and
+ * answers "which line is this build ON", which is a fact about the install. This answers "which
+ * line SHOULD it be on here", which is a fact about the project. The two disagreeing is exactly
+ * what `cliLineMismatchNotice` reports.
+ */
+export function updateTagForEnvironment(environment) {
+    return environment === 'prod' ? 'latest' : 'dev';
+}
 /**
  * How stale a cached npm answer may be before it is refreshed.
  *
@@ -52,4 +82,27 @@ export function cliUpdateNotice(currentVersion, latestVersion) {
     const install = installCommandFor(updateTagFor(currentVersion));
     return `A newer bitmagic CLI is available: ${latestVersion} (you have ${currentVersion}). Run \`${install}\` to update.`;
 }
+/**
+ * The line to say when the CLI running inside a project came from the other one.
+ *
+ * This is the one place the two lines are deliberately crossed, and it needs no version comparison
+ * to do it: whatever the numbers say, a project pinned to `dev` wants the dev line and a project
+ * pinned to `prod` wants the release. Version-driven nudges structurally cannot report this — a
+ * prerelease sitting in a `prod` project is *ahead* of the release tag, so `cliUpdateNotice` is
+ * correctly silent about a CLI that is on the wrong line entirely.
+ *
+ * `projectEnvironment` must be a project's committed pin, never a resolved environment: a one-off
+ * `--env` is a statement about this command, not about which CLI belongs in this directory.
+ */
+export function cliLineMismatchNotice(currentVersion, projectEnvironment) {
+    if (typeof currentVersion !== 'string' || currentVersion === '')
+        return null;
+    const wanted = updateTagForEnvironment(projectEnvironment);
+    const installed = updateTagFor(currentVersion);
+    if (installed === wanted)
+        return null;
+    return (`This project is on the ${projectEnvironment} environment, so its CLI comes from the ` +
+        `${describeUpdateTag(wanted)} line — but you are running a ${describeUpdateTag(installed)} ` +
+        `build (${currentVersion}). Run \`${installCommandFor(wanted)}\`.`);
+}
 //# sourceMappingURL=notice.js.map

package/dist/update/notice.js.map

@@ -1 +1 @@
-{"version":3,"file":"notice.js","sourceRoot":"","sources":["../../src/update/notice.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAKrE;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;AAClD,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,iBAAiB,CAAC,GAAc;IAC9C,OAAO,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,4BAA4B,CAAC,CAAC,CAAC,wBAAwB,CAAC;AACjF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAkB5D,MAAM,UAAU,YAAY,CAAC,KAA8B,EAAE,GAAW;IACtE,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,+FAA+F;IAC/F,oBAAoB;IACpB,IAAI,KAAK,CAAC,SAAS,GAAG,GAAG;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,GAAG,GAAG,KAAK,CAAC,SAAS,IAAI,wBAAwB,CAAC;AAC3D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,cAAsB,EAAE,aAAwC;IAC9F,IAAI,OAAO,aAAa,KAAK,QAAQ,IAAI,aAAa,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC3E,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,cAAc,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC7E,IAAI,oBAAoB,CAAC,cAAc,EAAE,aAAa,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9E,8FAA8F;IAC9F,MAAM,OAAO,GAAG,iBAAiB,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC,CAAC;IAChE,OAAO,sCAAsC,aAAa,cAAc,cAAc,YAAY,OAAO,eAAe,CAAC;AAC3H,CAAC"}
+{"version":3,"file":"notice.js","sourceRoot":"","sources":["../../src/update/notice.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAKrE;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;AAClD,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,iBAAiB,CAAC,GAAc;IAC9C,OAAO,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,4BAA4B,CAAC,CAAC,CAAC,wBAAwB,CAAC;AACjF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAc;IAC9C,OAAO,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,SAAS,CAAC;AACxD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,uBAAuB,CAAC,WAA4B;IAClE,OAAO,WAAW,KAAK,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAkB5D,MAAM,UAAU,YAAY,CAAC,KAA8B,EAAE,GAAW;IACtE,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,+FAA+F;IAC/F,oBAAoB;IACpB,IAAI,KAAK,CAAC,SAAS,GAAG,GAAG;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,GAAG,GAAG,KAAK,CAAC,SAAS,IAAI,wBAAwB,CAAC;AAC3D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,cAAsB,EAAE,aAAwC;IAC9F,IAAI,OAAO,aAAa,KAAK,QAAQ,IAAI,aAAa,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC3E,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,cAAc,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC7E,IAAI,oBAAoB,CAAC,cAAc,EAAE,aAAa,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9E,8FAA8F;IAC9F,MAAM,OAAO,GAAG,iBAAiB,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC,CAAC;IAChE,OAAO,sCAAsC,aAAa,cAAc,cAAc,YAAY,OAAO,eAAe,CAAC;AAC3H,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CACnC,cAAsB,EACtB,kBAAmC;IAEnC,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,cAAc,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC7E,MAAM,MAAM,GAAG,uBAAuB,CAAC,kBAAkB,CAAC,CAAC;IAC3D,MAAM,SAAS,GAAG,YAAY,CAAC,cAAc,CAAC,CAAC;IAC/C,IAAI,SAAS,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,CACL,0BAA0B,kBAAkB,0CAA0C;QACtF,GAAG,iBAAiB,CAAC,MAAM,CAAC,iCAAiC,iBAAiB,CAAC,SAAS,CAAC,GAAG;QAC5F,UAAU,cAAc,YAAY,iBAAiB,CAAC,MAAM,CAAC,KAAK,CACnE,CAAC;AACJ,CAAC"}