@codemieai/code 0.15.1 → 0.15.3

package/dist/utils/tips.js

@@ -0,0 +1,221 @@
+/**
+ * Feature Tips ("Did you know?") — selection, rotation and rendering logic.
+ *
+ * The curated catalog lives in src/utils/tips.json (pure data — edit tips
+ * there); this module loads it once at startup and exposes it as TIPS.
+ * Tips are shown at session start and end, browseable on demand via
+ * `codemie tips`, and sprinkled onto selected CLI surfaces (doctor, first-run
+ * screens) via renderTip().
+ *
+ * Catalog maintenance workflow (edit src/utils/tips.json):
+ * - Add a tip: append one `{ "id", "category", "message", "command"? }` object
+ *   to the array. Use a fresh kebab-case id — ids are never reused, because
+ *   the rotation state (~/.codemie/.tips-state.json) remembers them.
+ * - Retire a command: delete its tip in the same PR. If the tip is missed,
+ *   `codemie tips` validates `command` references against the live CLI command
+ *   tree and silently drops (plus debug-logs) tips pointing at retired
+ *   commands — session rendering never validates and never breaks.
+ * - Reword a tip: edit `message` in place and keep `id` stable so the rotation
+ *   history stays meaningful.
+ *
+ * This module must stay safe to import from the agent runtime, so it depends
+ * only on fs/path, chalk, the logger and the paths utility — never on
+ * commander or the CLI layer.
+ *
+ * Environment Variables:
+ * - CODEMIE_TIPS=true (default): show tips at session start/end
+ * - CODEMIE_TIPS=false|0|no: disable session tips (`codemie tips` still works)
+ */
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import { logger } from './logger.js';
+import { getCodemiePath } from './paths.js';
+import { parseBooleanEnv } from './env.js';
+const isStringArray = (value) => Array.isArray(value) && value.every(item => typeof item === 'string');
+/**
+ * Load the tip catalog from src/utils/tips.json at the package root (resolved
+ * relative to this module, so it works from src/utils in dev and dist/utils in
+ * the installed package, where the JSON ships via the package.json files list).
+ *
+ * Best-effort: any failure — missing file, malformed JSON, wrong shape — is
+ * debug-logged and yields an empty catalog. Tips must never break a session.
+ */
+function loadTipsCatalog() {
+    try {
+        // Resolve via import.meta.url, not paths.js: tests legitimately mock
+        // ./paths.js without declaring every export, and this module is loaded
+        // eagerly through BaseAgentAdapter — a mocked-out helper must never break
+        // module evaluation. Resolves identically from src/utils (dev) and
+        // dist/utils (built/installed package, where tips.json ships in src/utils).
+        const catalogPath = fileURLToPath(new URL('../../src/utils/tips.json', import.meta.url));
+        const parsed = JSON.parse(readFileSync(catalogPath, 'utf-8'));
+        if (!Array.isArray(parsed)) {
+            logger.debug('[tips] tips.json is not an array — using empty catalog', { catalogPath });
+            return [];
+        }
+        const tips = parsed
+            .filter((entry) => typeof entry === 'object' &&
+            entry !== null &&
+            typeof entry.id === 'string' &&
+            typeof entry.category === 'string' &&
+            typeof entry.message === 'string')
+            .map(entry => {
+            // Tolerate a malformed optional `commands` field by dropping just it
+            if (entry.commands !== undefined && !isStringArray(entry.commands)) {
+                logger.debug(`[tips] tips.json: ignoring malformed 'commands' on tip '${entry.id}'`);
+                return { ...entry, commands: undefined };
+            }
+            return entry;
+        });
+        if (tips.length !== parsed.length) {
+            logger.debug(`[tips] tips.json: dropped ${parsed.length - tips.length} malformed entrie(s)`, { catalogPath });
+        }
+        return tips;
+    }
+    catch (error) {
+        logger.debug('[tips] Failed to load tips.json — using empty catalog:', error);
+        return [];
+    }
+}
+/**
+ * Curated tip catalog, loaded eagerly from src/utils/tips.json. Every
+ * `command` value references a top-level command registered in
+ * src/cli/index.ts; `codemie tips` re-validates these at runtime.
+ */
+export const TIPS = loadTipsCatalog();
+const stateFilePath = () => getCodemiePath('.tips-state.json');
+/**
+ * Check if session tips are enabled (default: true).
+ * Reads the CODEMIE_TIPS environment variable.
+ *
+ * @returns true unless CODEMIE_TIPS is set to a falsy value ('false', '0', 'no')
+ */
+export function isTipsEnabled() {
+    return parseBooleanEnv(process.env.CODEMIE_TIPS, true);
+}
+/**
+ * Return the full tip catalog (used by `codemie tips`).
+ */
+export function listTips() {
+    return TIPS;
+}
+/**
+ * Pick the tip to show at a session lifecycle point.
+ *
+ * Randomly selects a tip that has not been shown yet (per the rotation state
+ * file), records the pick, and resets the shown list once every tip has been
+ * shown. Both contexts share one catalog and one rotation for now; the context
+ * is recorded in the debug log so future per-context catalogs can reuse it.
+ *
+ * Best-effort: unreadable/corrupt state is treated as empty, write failures
+ * are swallowed — a tip must never block or break a session.
+ *
+ * @param context - Where the tip is rendered ('start' or 'end' of session)
+ * @returns A tip, or null when tips are disabled or the catalog is empty
+ */
+export function getSessionTip(context) {
+    if (!isTipsEnabled() || TIPS.length === 0) {
+        return null;
+    }
+    const state = loadRotationState();
+    // Prune ids of retired tips so the rotation can still complete and reset.
+    const catalogIds = new Set(TIPS.map(tip => tip.id));
+    state.shownTipIds = state.shownTipIds.filter(id => catalogIds.has(id));
+    let candidates = TIPS.filter(tip => !state.shownTipIds.includes(tip.id));
+    if (candidates.length === 0) {
+        // Full rotation complete — start a fresh cycle.
+        state.shownTipIds = [];
+        candidates = [...TIPS];
+    }
+    const tip = candidates[Math.floor(Math.random() * candidates.length)];
+    state.shownTipIds.push(tip.id);
+    saveRotationState(state);
+    logger.debug('[tips] Selected session tip', { context, id: tip.id });
+    return tip;
+}
+/**
+ * Format a tip for terminal display: a gold ✨ prefix followed by the message
+ * in the same warm gold, bold. Yellow is the CLI's established accent color
+ * (matches the Kimi-style prompt echo) — deliberately no background bars or
+ * badge, just plain foreground styling.
+ * Shared by session lifecycle rendering (BaseAgentAdapter), renderTip(), and
+ * `codemie tips --random` so tips look identical everywhere.
+ */
+export function formatTipLine(tip) {
+    return chalk.bold.yellow(`✨ ${tip.message}`);
+}
+/**
+ * Print a single random tip to the console for CLI surfaces (doctor,
+ * first-run and post-setup screens, ...). Unlike getSessionTip(), this does
+ * not read or update the rotation state — rotation stays exclusive to session
+ * start/end.
+ *
+ * Best-effort: never throws, and is a no-op when tips are disabled.
+ *
+ * @param options.category - Restrict the pick to one category; falls back to
+ *   the full catalog when the category has no tips
+ */
+export function renderTip(options) {
+    try {
+        if (!isTipsEnabled() || TIPS.length === 0) {
+            return;
+        }
+        let pool = TIPS;
+        if (options?.category) {
+            const filtered = TIPS.filter(tip => tip.category === options.category);
+            if (filtered.length > 0) {
+                pool = filtered;
+            }
+        }
+        const tip = pool[Math.floor(Math.random() * pool.length)];
+        console.log();
+        console.log(formatTipLine(tip));
+    }
+    catch (error) {
+        logger.debug('[tips] renderTip failed (non-fatal):', error);
+    }
+}
+function loadRotationState() {
+    const file = stateFilePath();
+    try {
+        const content = readFileSync(file, 'utf-8');
+        const parsed = JSON.parse(content);
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            Array.isArray(parsed.shownTipIds)) {
+            const shownTipIds = parsed.shownTipIds
+                .filter((id) => typeof id === 'string');
+            return { shownTipIds };
+        }
+        return { shownTipIds: [] };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ENOENT') {
+            logger.debug('[tips] Rotation state unreadable — treating as empty', { file });
+        }
+        return { shownTipIds: [] };
+    }
+}
+/**
+ * Persist rotation state. The write goes through a same-directory temp file
+ * plus rename, so a concurrent reader never sees a truncated file (rename is
+ * atomic on POSIX and Windows for same-dir renames). Read-modify-write races
+ * between concurrent sessions remain theoretically possible — accepted as
+ * low-harm (worst case: a tip repeats); deliberately no locking.
+ */
+function saveRotationState(state) {
+    const file = stateFilePath();
+    try {
+        mkdirSync(path.dirname(file), { recursive: true });
+        const tmpFile = `${file}.tmp`;
+        writeFileSync(tmpFile, JSON.stringify(state, null, 2), 'utf-8');
+        renameSync(tmpFile, file);
+    }
+    catch (error) {
+        logger.debug('[tips] Failed to persist rotation state (non-fatal):', error);
+    }
+}
+//# sourceMappingURL=tips.js.map

package/dist/utils/tips.js.map

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

package/dist/utils/version-warnings.d.ts

@@ -0,0 +1,41 @@
+/**
+ * VersionWarningStore
+ *
+ * Records one-time "untested version" markers at user scope.
+ * Backing file: `~/.codemie/version-warnings.json`.
+ *
+ * A marker is keyed by (agent, installed agent version) and additionally stores
+ * the `supportedVersion` baseline it was acknowledged against. The marker is
+ * honoured only while that baseline still matches: a CodeMie release that moves
+ * the recommended version forward invalidates old markers and buys exactly one
+ * re-notice, while CodeMie releases that leave the baseline alone never re-nag.
+ *
+ * See EPMCDME-13734.
+ */
+export interface VersionWarningRecord {
+    agentName: string;
+    agentVersion: string;
+    /** Recommended version at the time the notice was acknowledged. */
+    supportedVersion: string;
+    /** CodeMie version that emitted the notice (context for `codemie doctor`). */
+    codemieVersion: string;
+    warnedAt: string;
+}
+export interface VersionWarningHistory {
+    version: 1;
+    warnings: VersionWarningRecord[];
+}
+export declare class VersionWarningStore {
+    static loadHistory(): Promise<VersionWarningHistory>;
+    static saveHistory(history: VersionWarningHistory): Promise<void>;
+    /**
+     * True when this agent version was already acknowledged against the same
+     * recommended baseline. A moved baseline makes the stored marker stale.
+     */
+    static hasWarned(agentName: string, agentVersion: string, supportedVersion: string): Promise<boolean>;
+    static recordWarning(agentName: string, agentVersion: string, supportedVersion: string, codemieVersion: string): Promise<void>;
+    static clear(): Promise<{
+        removed: number;
+    }>;
+}
+//# sourceMappingURL=version-warnings.d.ts.map

package/dist/utils/version-warnings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-warnings.d.ts","sourceRoot":"","sources":["../../src/utils/version-warnings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,CAAC,CAAC;IACX,QAAQ,EAAE,oBAAoB,EAAE,CAAC;CAClC;AAMD,qBAAa,mBAAmB;WACjB,WAAW,IAAI,OAAO,CAAC,qBAAqB,CAAC;WA0B7C,WAAW,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMvE;;;OAGG;WACU,SAAS,CACpB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,OAAO,CAAC;WAUN,aAAa,CACxB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,EACxB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC;WAeH,KAAK,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAkBnD"}

package/dist/utils/version-warnings.js

@@ -0,0 +1,93 @@
+/**
+ * VersionWarningStore
+ *
+ * Records one-time "untested version" markers at user scope.
+ * Backing file: `~/.codemie/version-warnings.json`.
+ *
+ * A marker is keyed by (agent, installed agent version) and additionally stores
+ * the `supportedVersion` baseline it was acknowledged against. The marker is
+ * honoured only while that baseline still matches: a CodeMie release that moves
+ * the recommended version forward invalidates old markers and buys exactly one
+ * re-notice, while CodeMie releases that leave the baseline alone never re-nag.
+ *
+ * See EPMCDME-13734.
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { logger } from './logger.js';
+import { getCodemiePath } from './paths.js';
+const filePath = () => getCodemiePath('version-warnings.json');
+const emptyHistory = () => ({ version: 1, warnings: [] });
+export class VersionWarningStore {
+    static async loadHistory() {
+        const file = filePath();
+        try {
+            const content = await fs.readFile(file, 'utf-8');
+            const parsed = JSON.parse(content);
+            if (typeof parsed === 'object' &&
+                parsed !== null &&
+                Array.isArray(parsed.warnings)) {
+                return {
+                    version: 1,
+                    warnings: parsed.warnings,
+                };
+            }
+            return emptyHistory();
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ENOENT') {
+                return emptyHistory();
+            }
+            logger.warn('[VersionWarningStore] Corrupt or unreadable file — treating as empty', { file });
+            return emptyHistory();
+        }
+    }
+    static async saveHistory(history) {
+        const file = filePath();
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        await fs.writeFile(file, JSON.stringify(history, null, 2), 'utf-8');
+    }
+    /**
+     * True when this agent version was already acknowledged against the same
+     * recommended baseline. A moved baseline makes the stored marker stale.
+     */
+    static async hasWarned(agentName, agentVersion, supportedVersion) {
+        const history = await this.loadHistory();
+        return history.warnings.some((warning) => warning.agentName === agentName &&
+            warning.agentVersion === agentVersion &&
+            warning.supportedVersion === supportedVersion);
+    }
+    static async recordWarning(agentName, agentVersion, supportedVersion, codemieVersion) {
+        const history = await this.loadHistory();
+        const others = history.warnings.filter((warning) => !(warning.agentName === agentName && warning.agentVersion === agentVersion));
+        others.push({
+            agentName,
+            agentVersion,
+            supportedVersion,
+            codemieVersion,
+            warnedAt: new Date().toISOString(),
+        });
+        await this.saveHistory({ version: 1, warnings: others });
+    }
+    static async clear() {
+        const file = filePath();
+        const history = await this.loadHistory();
+        const removed = history.warnings.length;
+        try {
+            await fs.unlink(file);
+            return { removed };
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ENOENT') {
+                return { removed: 0 };
+            }
+            // The user ran the reset intentionally — failing `codemie doctor` here
+            // would be worse than reporting "0 removed" and continuing the checks.
+            logger.warn('[VersionWarningStore] clear() failed; markers left in place', { file, code });
+            return { removed: 0 };
+        }
+    }
+}
+//# sourceMappingURL=version-warnings.js.map

package/dist/utils/version-warnings.js.map

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

package/dist/utils/whatsnew.d.ts

@@ -0,0 +1,83 @@
+/**
+ * What's New — release notes from CHANGELOG.md
+ *
+ * CHANGELOG.md (Keep a Changelog format) is the curated source of truth for
+ * release notes. It ships inside the npm package and is consumed by:
+ * - `codemie whatsnew` — browse notes for the current, one, or all versions
+ * - the once-per-upgrade startup notice in bin/codemie.js, which shows the
+ *   current version's notes once and records a `.last-seen-version` marker
+ *   under the CodeMie home directory
+ *
+ * This module must stay safe to import from the bin entry point, so its
+ * dependencies are limited to fs/path/chalk plus the logger, paths, and tips
+ * utilities — never commander or the CLI layer.
+ *
+ * Environment Variables:
+ * - CODEMIE_TIPS=false|0|no: also suppresses the upgrade notice. The "reduce
+ *   chatter" switch is shared with feature tips on purpose — see tips.ts.
+ */
+/**
+ * One `### Section` block inside a release entry.
+ */
+export interface ReleaseSection {
+    title: string;
+    items: string[];
+}
+/**
+ * One `## [version]` release entry from the changelog.
+ */
+export interface ReleaseEntry {
+    version: string;
+    date?: string;
+    sections: ReleaseSection[];
+}
+/**
+ * Tolerant Keep-a-Changelog parser. Recognizes `## [x.y.z] - date` headings,
+ * `### Section` subheadings, and `- item` bullets; everything else is skipped.
+ */
+export declare function parseChangelog(content: string): ReleaseEntry[];
+/**
+ * Locate CHANGELOG.md at the package root. Works both from src/utils (dev
+ * repo) and dist/utils (built/installed package) — the root is two levels up
+ * in both layouts.
+ *
+ * @returns Absolute path to CHANGELOG.md, or null when it is not shipped
+ */
+export declare function getChangelogPath(): string | null;
+/**
+ * Read release notes from the changelog.
+ *
+ * @param version - When given, the entry for this exact version; if there is
+ *   no matching heading, falls back to the newest versioned entry (or
+ *   Unreleased when that is all there is) so the once-per-upgrade notice
+ *   always has something to show
+ * @returns Parsed entries (newest first, as written), or an empty array when
+ *   the changelog is missing or unparseable
+ */
+export declare function getReleaseNotes(version?: string): ReleaseEntry[];
+/**
+ * Version for which the upgrade notice was last shown, or null if never.
+ * Best-effort: an unreadable marker is treated as "never seen".
+ */
+export declare function getLastSeenVersion(): string | null;
+/**
+ * Record that the upgrade notice was shown for a version. Best-effort: write
+ * failures are swallowed — worst case the notice shows once more.
+ */
+export declare function markVersionSeen(version: string): void;
+/**
+ * Render release notes to the console. Never throws.
+ *
+ * @param options.maxItems - Cap on the total number of bullets printed across
+ *   all entries; when truncated, a pointer to `codemie whatsnew` is appended
+ */
+export declare function renderReleaseNotes(entries: ReleaseEntry[], options?: {
+    maxItems?: number;
+}): void;
+/**
+ * Whether the once-per-upgrade notice may print. Deliberately shares the
+ * CODEMIE_TIPS switch with feature tips — one "reduce chatter" toggle for all
+ * informational CLI output.
+ */
+export declare function isWhatsNewEnabled(): boolean;
+//# sourceMappingURL=whatsnew.d.ts.map

package/dist/utils/whatsnew.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whatsnew.d.ts","sourceRoot":"","sources":["../../src/utils/whatsnew.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AASH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,CAoC9D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAGhD;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE,CAkChE;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAMlD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAQrD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAgDjG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C"}

package/dist/utils/whatsnew.js

@@ -0,0 +1,200 @@
+/**
+ * What's New — release notes from CHANGELOG.md
+ *
+ * CHANGELOG.md (Keep a Changelog format) is the curated source of truth for
+ * release notes. It ships inside the npm package and is consumed by:
+ * - `codemie whatsnew` — browse notes for the current, one, or all versions
+ * - the once-per-upgrade startup notice in bin/codemie.js, which shows the
+ *   current version's notes once and records a `.last-seen-version` marker
+ *   under the CodeMie home directory
+ *
+ * This module must stay safe to import from the bin entry point, so its
+ * dependencies are limited to fs/path/chalk plus the logger, paths, and tips
+ * utilities — never commander or the CLI layer.
+ *
+ * Environment Variables:
+ * - CODEMIE_TIPS=false|0|no: also suppresses the upgrade notice. The "reduce
+ *   chatter" switch is shared with feature tips on purpose — see tips.ts.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { logger } from './logger.js';
+import { getCodemiePath, getDirname } from './paths.js';
+import { isTipsEnabled } from './tips.js';
+/**
+ * Tolerant Keep-a-Changelog parser. Recognizes `## [x.y.z] - date` headings,
+ * `### Section` subheadings, and `- item` bullets; everything else is skipped.
+ */
+export function parseChangelog(content) {
+    const entries = [];
+    let currentEntry = null;
+    let currentSection = null;
+    for (const line of content.split(/\r?\n/)) {
+        const versionMatch = line.match(/^##\s+\[([^\]]+)\](?:\s*-\s*(.+?))?\s*$/);
+        if (versionMatch) {
+            currentEntry = {
+                version: versionMatch[1].trim(),
+                date: versionMatch[2]?.trim(),
+                sections: []
+            };
+            entries.push(currentEntry);
+            currentSection = null;
+            continue;
+        }
+        if (!currentEntry) {
+            continue;
+        }
+        const sectionMatch = line.match(/^###\s+(.+?)\s*$/);
+        if (sectionMatch) {
+            currentSection = { title: sectionMatch[1].trim(), items: [] };
+            currentEntry.sections.push(currentSection);
+            continue;
+        }
+        const itemMatch = line.match(/^\s*[-*]\s+(.+?)\s*$/);
+        if (itemMatch && currentSection) {
+            currentSection.items.push(itemMatch[1].trim());
+        }
+    }
+    return entries;
+}
+/**
+ * Locate CHANGELOG.md at the package root. Works both from src/utils (dev
+ * repo) and dist/utils (built/installed package) — the root is two levels up
+ * in both layouts.
+ *
+ * @returns Absolute path to CHANGELOG.md, or null when it is not shipped
+ */
+export function getChangelogPath() {
+    const changelogPath = path.resolve(getDirname(import.meta.url), '../../CHANGELOG.md');
+    return existsSync(changelogPath) ? changelogPath : null;
+}
+/**
+ * Read release notes from the changelog.
+ *
+ * @param version - When given, the entry for this exact version; if there is
+ *   no matching heading, falls back to the newest versioned entry (or
+ *   Unreleased when that is all there is) so the once-per-upgrade notice
+ *   always has something to show
+ * @returns Parsed entries (newest first, as written), or an empty array when
+ *   the changelog is missing or unparseable
+ */
+export function getReleaseNotes(version) {
+    const changelogPath = getChangelogPath();
+    if (!changelogPath) {
+        logger.debug('[whatsnew] CHANGELOG.md not found at package root');
+        return [];
+    }
+    try {
+        const entries = parseChangelog(readFileSync(changelogPath, 'utf-8'));
+        if (entries.length === 0) {
+            logger.debug('[whatsnew] CHANGELOG.md parsed to zero release entries', { changelogPath });
+        }
+        if (!version) {
+            return entries;
+        }
+        const exact = entries.filter(entry => entry.version === version);
+        if (exact.length > 0) {
+            return exact;
+        }
+        // No heading for this exact version (changelog not updated for the
+        // release) — fall back to the newest versioned entry so the once-per-
+        // upgrade notice still shows something before the version is marked seen.
+        const fallback = entries.find(entry => entry.version !== 'Unreleased') ?? entries[0];
+        if (fallback) {
+            logger.debug(`[whatsnew] No changelog entry for ${version} — falling back to ${fallback.version}`);
+            return [fallback];
+        }
+        return [];
+    }
+    catch (error) {
+        logger.debug('[whatsnew] Failed to read changelog:', error);
+        return [];
+    }
+}
+const lastSeenFilePath = () => getCodemiePath('.last-seen-version');
+/**
+ * Version for which the upgrade notice was last shown, or null if never.
+ * Best-effort: an unreadable marker is treated as "never seen".
+ */
+export function getLastSeenVersion() {
+    try {
+        return readFileSync(lastSeenFilePath(), 'utf-8').trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Record that the upgrade notice was shown for a version. Best-effort: write
+ * failures are swallowed — worst case the notice shows once more.
+ */
+export function markVersionSeen(version) {
+    try {
+        const file = lastSeenFilePath();
+        mkdirSync(path.dirname(file), { recursive: true });
+        writeFileSync(file, version, 'utf-8');
+    }
+    catch (error) {
+        logger.debug('[whatsnew] Failed to persist last-seen version (non-fatal):', error);
+    }
+}
+/**
+ * Render release notes to the console. Never throws.
+ *
+ * @param options.maxItems - Cap on the total number of bullets printed across
+ *   all entries; when truncated, a pointer to `codemie whatsnew` is appended
+ */
+export function renderReleaseNotes(entries, options) {
+    try {
+        if (entries.length === 0) {
+            return;
+        }
+        let remaining = options?.maxItems ?? Number.POSITIVE_INFINITY;
+        let truncated = false;
+        console.log();
+        for (const entry of entries) {
+            if (remaining <= 0) {
+                truncated = true;
+                break;
+            }
+            const dateSuffix = entry.date ? ` (${entry.date})` : '';
+            console.log(chalk.bold.cyan(`## What's new in ${entry.version}${dateSuffix}`));
+            for (const section of entry.sections) {
+                if (remaining <= 0) {
+                    truncated = true;
+                    break;
+                }
+                if (section.items.length === 0) {
+                    continue;
+                }
+                console.log(chalk.dim(`  ${section.title}`));
+                for (const item of section.items) {
+                    if (remaining <= 0) {
+                        truncated = true;
+                        break;
+                    }
+                    console.log(`  • ${item}`);
+                    remaining--;
+                }
+            }
+            console.log();
+        }
+        if (truncated) {
+            console.log(chalk.dim('  … run `codemie whatsnew` for the full notes'));
+            console.log();
+        }
+    }
+    catch (error) {
+        logger.debug('[whatsnew] renderReleaseNotes failed (non-fatal):', error);
+    }
+}
+/**
+ * Whether the once-per-upgrade notice may print. Deliberately shares the
+ * CODEMIE_TIPS switch with feature tips — one "reduce chatter" toggle for all
+ * informational CLI output.
+ */
+export function isWhatsNewEnabled() {
+    return isTipsEnabled();
+}
+//# sourceMappingURL=whatsnew.js.map