@moda-ai/cli 1.2.0 → 1.4.0

package/dist/cli.js

@@ -5,13 +5,16 @@ import { callDataAPI, ApiError, getApiRequestCount, resetApiRequestCount, } from
 import { OverviewSchema, ClustersSchema, ClusterConversationsSchema, ConversationsSchema, ContextSchema, FrustrationsSchema, ToolFailuresSchema, ToolFailureDetailSchema, WorkflowsSchema, RunsSchema, RunDetailSchema, LoopsSchema, LoopDetailSchema, } from './schemas.js';
 import { withFrustrationAnchors, withToolFailureAnchors, embeddedWindowSize, asRecord, asString, asNumber } from './transforms.js';
 import { runPromptsCommand } from './prompts.js';
-import { runHooksInstall, runSparkCommand, runWorkspaceCommand } from './workspace.js';
+// Coding-agent capture (shadow workspace / Shadow Spark / trace hooks) is temporarily
+// disabled while the feature is finished — see the commented-out command registrations below.
+// import { runHooksInstall, runSparkCommand, runWorkspaceCommand } from './workspace.js';
 import { runSkillsCommand } from './skills.js';
 import { runHarnessCommand } from './harness.js';
 import { runSyncCommand } from './sync.js';
 import { runDoctorCommand, runStatusCommand } from './doctor.js';
 import { CliInputError } from './errors.js';
 import { isTelemetryDisabled, sendCliUsageTelemetry, stripTelemetryFlag, } from './telemetry.js';
+import { isUpdateCheckDisabled, printUpdateNotice, startUpdateCheck, stripUpdateCheckFlag, } from './update-check.js';
 import { createCommandContext } from './command-context.js';
 import { createCommandRegistry } from './command-registry.js';
 import { createAgentErrorEnvelope, errorToAgentError, outputModeFromFlags, } from './output.js';
@@ -154,25 +157,6 @@ Commands:
   prompts sync --watch             Upload again when prompt files change
   prompts promote <key>            Move a dev/staging/prod label
 
-  Shadow workspace:
-  spark status                     Show Shadow Spark workspace state
-  spark explain                    Explain what Shadow Spark captures and posts
-  spark snapshot                   Manual / hook-invoked Shadow Spark snapshot
-  spark snapshot --dry-run         Show file inventory without copy/commit/post
-  spark log                        Show Shadow Spark history
-  spark bundle                     Bundle a shadow commit range for replay
-  spark remove --yes               Delete this repo's local shadow workspace
-  workspace init                   Create shadow workspace for current repo
-  workspace snapshot               Manual / hook-invoked sync + shadow commit
-  workspace status                 Show shadow workspace state
-  workspace explain                Explain shadow workspace behavior
-  workspace log                    Show Moda shadow history (not user git log)
-  workspace bundle                 Bundle a shadow commit range for replay
-  hooks install                    Install Claude Code shadow-workspace hooks
-  hooks install --agent=codex      Install Codex hooks
-  hooks install --agent=cursor     Install Cursor hooks
-  hooks install --agent=all        Install Claude Code, Codex, and Cursor hooks
-
   Skills:
   skills gen                       Kick off tenant-wide skill generation
   skills pull                      Pull tenant-generated skills into .claude/skills (and .cursor/rules)
@@ -195,6 +179,7 @@ Common flags:
   --yes                            Accept explicit automation defaults
   --tui                            Force the human analyst dashboard when supported
   --no-tui                         Show raw analyst stream instead of dashboard
+  --no-update-check                Skip the daily new-version check (or MODA_CLI_UPDATE_CHECK=0)
 
 Runs flags:
   --outcome=OUTCOME                Filter by outcome (running|succeeded|partial|failed|loop|abandoned|unknown)
@@ -207,8 +192,6 @@ Init flags:
                                    Choose harness analyst adapter
   --tui                            Show full-screen analyst dashboard in human TTYs
   --no-tui                         Show raw external analyst output
-  --coding-agent-traces            Install Claude/Codex/Cursor trace hooks
-  --no-coding-agent-traces         Skip Claude/Codex/Cursor trace hook installation
   --sdk-guide                      Write .moda/SDK_INTEGRATION.md
   --no-sdk-guide                   Skip SDK integration guide creation
   --ci-cd                          Create GitHub Actions Moda validation workflow
@@ -241,8 +224,6 @@ Examples:
   moda sync harness --profile=prod
   moda harness scan --json
   moda harness explain --agent=agent_support
-  moda init --coding-agent-traces
-  moda init --no-coding-agent-traces
   moda init --ci-cd
   moda overview --days-back=30
   moda clusters --time-range=7d
@@ -258,11 +239,6 @@ Examples:
   moda prompts status
   moda prompts sync
   moda prompts promote support.triage --label=prod --version=pver_abc123
-  moda spark explain
-  moda spark snapshot --dry-run --json
-  moda workspace snapshot --json
-  moda hooks install
-  moda hooks install --agent=all
   moda skills pull`);
 }
 // --- Command Handlers ---
@@ -870,57 +846,60 @@ export const commandRegistry = createCommandRegistry([
         resetApiRequestCountBeforeRun: true,
         telemetry: 'result-and-error',
     }),
-    {
-        name: 'workspace',
-        description: 'Manage Moda shadow workspace snapshots',
-        examples: ['moda workspace init', 'moda workspace snapshot --json', 'moda workspace explain'],
-        auth: 'none',
-        outputModes: ['human', 'json', 'agent'],
-        mutability: 'write',
-        validateConfigBeforeRun: false,
-        resetApiRequestCountBeforeRun: false,
-        telemetry: 'none',
-        handler: async (context) => ({
-            exitCode: await runWorkspaceCommand({
-                command: context.command,
-                positional: context.positional,
-                positionals: context.positionals,
-                flags: context.flags,
-            }),
-        }),
-    },
-    {
-        name: 'spark',
-        aliases: ['shadow'],
-        description: 'Manage Shadow Spark workspace snapshots',
-        examples: ['moda spark status', 'moda spark explain', 'moda spark snapshot --dry-run --json'],
-        auth: 'none',
-        outputModes: ['human', 'json', 'agent'],
-        mutability: 'write',
-        validateConfigBeforeRun: false,
-        resetApiRequestCountBeforeRun: false,
-        telemetry: 'none',
-        handler: runSparkCommand,
-    },
-    {
-        name: 'hooks',
-        description: 'Install coding-agent trace hooks',
-        examples: ['moda hooks install', 'moda hooks install --agent=all'],
-        auth: 'none',
-        outputModes: ['human', 'json', 'agent'],
-        mutability: 'write',
-        validateConfigBeforeRun: false,
-        resetApiRequestCountBeforeRun: false,
-        telemetry: 'none',
-        handler: async (context) => ({
-            exitCode: await runHooksInstall({
-                command: context.command,
-                positional: context.positional,
-                positionals: context.positionals,
-                flags: context.flags,
-            }),
-        }),
-    },
+    // Coding-agent capture commands disabled until the feature is production-ready.
+    // Re-enable by restoring these registrations, the workspace.js import above, the
+    // "Shadow workspace" help section, the init hooks phase, and the doctor spark/hook checks.
+    // {
+    //   name: 'workspace',
+    //   description: 'Manage Moda shadow workspace snapshots',
+    //   examples: ['moda workspace init', 'moda workspace snapshot --json', 'moda workspace explain'],
+    //   auth: 'none',
+    //   outputModes: ['human', 'json', 'agent'],
+    //   mutability: 'write',
+    //   validateConfigBeforeRun: false,
+    //   resetApiRequestCountBeforeRun: false,
+    //   telemetry: 'none',
+    //   handler: async (context) => ({
+    //     exitCode: await runWorkspaceCommand({
+    //       command: context.command,
+    //       positional: context.positional,
+    //       positionals: context.positionals,
+    //       flags: context.flags,
+    //     }),
+    //   }),
+    // },
+    // {
+    //   name: 'spark',
+    //   aliases: ['shadow'],
+    //   description: 'Manage Shadow Spark workspace snapshots',
+    //   examples: ['moda spark status', 'moda spark explain', 'moda spark snapshot --dry-run --json'],
+    //   auth: 'none',
+    //   outputModes: ['human', 'json', 'agent'],
+    //   mutability: 'write',
+    //   validateConfigBeforeRun: false,
+    //   resetApiRequestCountBeforeRun: false,
+    //   telemetry: 'none',
+    //   handler: runSparkCommand,
+    // },
+    // {
+    //   name: 'hooks',
+    //   description: 'Install coding-agent trace hooks',
+    //   examples: ['moda hooks install', 'moda hooks install --agent=all'],
+    //   auth: 'none',
+    //   outputModes: ['human', 'json', 'agent'],
+    //   mutability: 'write',
+    //   validateConfigBeforeRun: false,
+    //   resetApiRequestCountBeforeRun: false,
+    //   telemetry: 'none',
+    //   handler: async (context) => ({
+    //     exitCode: await runHooksInstall({
+    //       command: context.command,
+    //       positional: context.positional,
+    //       positionals: context.positionals,
+    //       flags: context.flags,
+    //     }),
+    //   }),
+    // },
     {
         name: 'skills',
         description: 'Generate and pull Moda skills',
@@ -984,8 +963,9 @@ function printAgentCliError(command, error) {
 }
 export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
     const { command, flags } = parsed;
-    const commandFlags = stripTelemetryFlag(flags);
+    const commandFlags = stripUpdateCheckFlag(stripTelemetryFlag(flags));
     const telemetryDisabled = isTelemetryDisabled(flags);
+    const updateCheckDisabled = isUpdateCheckDisabled(flags);
     if (command === '--version' || command === '-V' || flags.version === 'true') {
         console.log(`moda-cli ${VERSION}`);
         return 0;
@@ -1012,6 +992,11 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
     if (definition.name === 'agent' && commandFlags.json !== 'true') {
         commandFlags.agent = 'true';
     }
+    // Kick off the registry check before the handler so the (at most daily)
+    // request overlaps with command work instead of delaying exit.
+    if (!updateCheckDisabled) {
+        void startUpdateCheck();
+    }
     if (definition.validateConfigBeforeRun) {
         validateConfig();
     }
@@ -1037,6 +1022,9 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
                 apiRequestCount: getApiRequestCount(),
             });
         }
+        if (!updateCheckDisabled) {
+            printUpdateNotice();
+        }
         return result.exitCode;
     }
     catch (error) {
@@ -1058,6 +1046,9 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
         else {
             printCliError(error);
         }
+        if (!updateCheckDisabled) {
+            printUpdateNotice();
+        }
         return 1;
     }
 }

package/dist/doctor.js

@@ -162,9 +162,12 @@ export async function buildDoctorReport(context, options) {
         '__tests__',
     ]));
     checks.push(sdkInitializationCheck(context.cwd));
-    checks.push(shadowSparkWorkspaceCheck(context.cwd, context.env));
-    checks.push(hookCheck(context.env));
-    checks.push(...hookTelemetryChecks(context.env, ingestUrl));
+    // Coding-agent capture (Shadow Spark + trace hooks) is temporarily disabled, so doctor
+    // must not recommend its commands. `shadowSpark` in the status payload falls back to
+    // 'skipped' via checkStatus.
+    // checks.push(shadowSparkWorkspaceCheck(context.cwd, context.env));
+    // checks.push(hookCheck(context.env));
+    // checks.push(...hookTelemetryChecks(context.env, ingestUrl));
     checks.push(validationEventPathCheck(ingestUrl));
     if (options.offline || !apiKey) {
         checks.push(...offlineCloudChecks(options.offline));
@@ -519,6 +522,8 @@ function sdkInitializationCheck(cwd) {
         nextCommand: 'moda init',
     };
 }
+// Unused while coding-agent capture is disabled; kept for re-enablement.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
 function shadowSparkWorkspaceCheck(cwd, env) {
     const repo = detectGitRepo(cwd);
     if (!repo) {
@@ -552,6 +557,8 @@ function shadowSparkWorkspaceCheck(cwd, env) {
         nextCommand: healthy ? undefined : 'moda spark snapshot --json',
     };
 }
+// Unused while coding-agent capture is disabled; kept for re-enablement.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
 function hookCheck(env) {
     const paths = getModaPaths({ env });
     const hookCandidates = [
@@ -571,6 +578,8 @@ function hookCheck(env) {
         nextCommand: found.length > 0 ? undefined : 'moda hooks install --agent=all',
     };
 }
+// Unused while coding-agent capture is disabled; kept for re-enablement.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
 function hookTelemetryChecks(env, ingestUrl) {
     const configs = agentTelemetryConfigs(env);
     return [

package/dist/init/index.js

@@ -8,7 +8,8 @@ import { detectAgents } from './mcp.js';
 import { installRules } from './rules.js';
 import { initPrompts } from '../prompts.js';
 import { pullSkills } from '../skills.js';
-import { runHooksInstall } from '../workspace.js';
+// Coding-agent capture is temporarily disabled — see the hooks phase below.
+// import { runHooksInstall } from '../workspace.js';
 import { SDK_GUIDE_PATH, writeSdkIntegrationGuide } from './sdk-guide.js';
 import { createCommandContext } from '../command-context.js';
 import { CliInputError } from '../errors.js';
@@ -29,7 +30,9 @@ export async function runInit(flags, options = {}) {
         if (human)
             console.log(message);
     };
-    const warn = (message) => {
+    // `warn` is only used by the temporarily-disabled hooks phase below; keep the
+    // underscore-prefixed binding so re-enabling it is a rename away.
+    const _warn = (message) => {
         if (human)
             console.error(message);
     };
@@ -103,7 +106,9 @@ export async function runInit(flags, options = {}) {
     // Step 5: Setup plan
     log(renderInitStep(5, 7, 'Setup Plan', 'Every write/sync action is explicit before it is applied.'));
     const setupPlan = buildSetupPlan({
-        installHooks: await shouldIngestCodingAgentTraces(flags, yes),
+        // Coding-agent capture is temporarily disabled; never prompt for or install trace hooks.
+        // installHooks: await shouldIngestCodingAgentTraces(flags, yes),
+        installHooks: false,
         installSdkGuide: await shouldCreateSdkGuide(flags, yes),
         configureCiCd: await shouldConfigureCiCd(flags, yes),
     });
@@ -113,25 +118,25 @@ export async function runInit(flags, options = {}) {
     // Step 6: Apply approved setup changes.
     log(renderInitStep(6, 7, 'Apply Approved Changes'));
     emit('apply', 'Applying approved setup changes.');
-    const ingestCodingAgentTraces = setupPlan.find((action) => action.category === 'hooks')?.approved === true;
-    if (ingestCodingAgentTraces) {
-        try {
-            await runHooksInstall({
-                command: 'hooks',
-                positional: 'install',
-                positionals: ['install'],
-                flags: { agent: 'all', ...(human ? {} : { json: 'true' }) },
-            });
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            warn(renderInitNote(`hook/telemetry install failed: ${message}`, 'warning'));
-            warn('  Run `moda hooks install --agent=all` manually to enable traces.');
-        }
-    }
-    else {
-        log(renderInitNote('Skipped coding-agent trace ingestion', 'skipped'));
-    }
+    // Coding-agent capture is temporarily disabled; the hooks phase never runs.
+    // const ingestCodingAgentTraces = setupPlan.find((action) => action.category === 'hooks')?.approved === true;
+    const ingestCodingAgentTraces = false;
+    // if (ingestCodingAgentTraces) {
+    //   try {
+    //     await runHooksInstall({
+    //       command: 'hooks',
+    //       positional: 'install',
+    //       positionals: ['install'],
+    //       flags: { agent: 'all', ...(human ? {} : { json: 'true' }) },
+    //     });
+    //   } catch (err) {
+    //     const message = err instanceof Error ? err.message : String(err);
+    //     warn(renderInitNote(`hook/telemetry install failed: ${message}`, 'warning'));
+    //     warn('  Run `moda hooks install --agent=all` manually to enable traces.');
+    //   }
+    // } else {
+    //   log(renderInitNote('Skipped coding-agent trace ingestion', 'skipped'));
+    // }
     const agents = detectAgents();
     if (agents.length > 0) {
         log(renderInitNote(`Detected coding agents: ${agents.join(', ')}`));
@@ -172,7 +177,7 @@ export async function runInit(flags, options = {}) {
     }
     log(renderInitNote('Reusing approved Step 4 harness report; no second analyst run needed'));
     markApplied(setupPlan, 'harness');
-    markApplied(setupPlan, 'hooks', ingestCodingAgentTraces ? undefined : 'User skipped coding-agent trace hooks.');
+    markApplied(setupPlan, 'hooks', ingestCodingAgentTraces ? undefined : 'Coding-agent trace capture is temporarily unavailable.');
     markApplied(setupPlan, 'prompts');
     markApplied(setupPlan, 'skills');
     emit('apply', 'Approved changes applied.', 'completed');
@@ -226,7 +231,7 @@ function buildSetupPlan(options) {
             approved: options.installHooks,
             files: ['~/.claude/settings.json', '~/.codex/hooks.json', '~/.cursor/hooks.json'],
             command: 'moda hooks install --agent=all',
-            reason: options.installHooks ? undefined : 'Not approved during init.',
+            reason: options.installHooks ? undefined : 'Coding-agent trace capture is temporarily unavailable.',
         },
         {
             category: 'prompts',
@@ -351,19 +356,20 @@ function commandFlags(flags) {
 function stringFlag(value) {
     return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
 }
-async function shouldIngestCodingAgentTraces(flags, yes) {
-    const explicit = parseOptionalBoolean(flagValue(flags, 'coding-agent-traces', 'coding_agent_traces'));
-    if (explicit !== undefined)
-        return explicit;
-    if (isTruthyFlag(flagValue(flags, 'no-coding-agent-traces', 'no_coding_agent_traces')))
-        return false;
-    if (yes)
-        return true;
-    return confirm({
-        message: 'Ingest coding-agent traces for Claude Code, Codex, and Cursor?',
-        default: true,
-    });
-}
+// Coding-agent capture is temporarily disabled; restore this prompt with the hooks phase.
+// async function shouldIngestCodingAgentTraces(
+//   flags: Record<string, unknown>,
+//   yes: boolean,
+// ): Promise<boolean> {
+//   const explicit = parseOptionalBoolean(flagValue(flags, 'coding-agent-traces', 'coding_agent_traces'));
+//   if (explicit !== undefined) return explicit;
+//   if (isTruthyFlag(flagValue(flags, 'no-coding-agent-traces', 'no_coding_agent_traces'))) return false;
+//   if (yes) return true;
+//   return confirm({
+//     message: 'Ingest coding-agent traces for Claude Code, Codex, and Cursor?',
+//     default: true,
+//   });
+// }
 async function shouldConfigureCiCd(flags, yes) {
     const explicit = parseOptionalBoolean(flagValue(flags, 'ci-cd', 'ci_cd', 'ci'));
     if (explicit !== undefined)

package/dist/update-check.d.ts

@@ -0,0 +1,31 @@
+import { type ProfileIOOptions } from './profiles.js';
+export declare function stripUpdateCheckFlag(flags: Record<string, string>): Record<string, string>;
+export declare function isUpdateCheckDisabled(flags: Record<string, string>, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Numeric semver comparison ignoring prerelease/build suffixes; npm's
+ * `latest` dist-tag only carries stable releases, so this is sufficient
+ * without pulling in a semver dependency.
+ */
+export declare function isNewerVersion(candidate: string, current: string): boolean;
+/**
+ * Refresh the cached latest version from the npm registry at most once per
+ * 24 hours. Fire-and-forget from the CLI dispatcher. The abort timer is
+ * unref'd so it can't keep the process alive after the socket closes (it does
+ * not unref the in-flight fetch itself — a fast command may still wait up to
+ * REGISTRY_TIMEOUT_MS for the request to resolve, matching the telemetry
+ * module's trade-off). Every failure path is swallowed — an update check must
+ * never break a command.
+ */
+export declare function startUpdateCheck(options?: ProfileIOOptions, now?: number): Promise<void>;
+/**
+ * Returns the upgrade notice when the cached registry version is newer than
+ * the running build, or undefined. Reads only the local cache — never the
+ * network — so it is safe to call synchronously at the end of every command.
+ */
+export declare function getUpdateNotice(options?: ProfileIOOptions): string | undefined;
+/**
+ * Print the upgrade notice to stderr in interactive terminals only: stdout
+ * stays machine-readable, and piped/CI invocations stay noise-free.
+ */
+export declare function printUpdateNotice(options?: ProfileIOOptions): void;
+//# sourceMappingURL=update-check.d.ts.map

package/dist/update-check.js

@@ -0,0 +1,141 @@
+// src/update-check.ts — Daily npm-registry version check with an upgrade
+// notice. Mirrors the telemetry contract: fire-and-forget, short abort
+// timeout, never throws, and never touches stdout (notice goes to stderr so
+// JSON/agent output stays machine-readable).
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { VERSION } from './config.js';
+import { getModaDir } from './profiles.js';
+const UPDATE_CHECK_FLAG = 'no-update-check';
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const REGISTRY_TIMEOUT_MS = 1_500;
+const REGISTRY_LATEST_URL = 'https://registry.npmjs.org/@moda-ai/cli/latest';
+// npm's `latest` dist-tag is always a stable semver. Anchored, no control
+// chars: a registry response intercepted by a proxy can't smuggle ANSI escape
+// sequences into the cache (and thus the terminal notice) this way.
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+export function stripUpdateCheckFlag(flags) {
+    const { [UPDATE_CHECK_FLAG]: _drop, ...rest } = flags;
+    return rest;
+}
+export function isUpdateCheckDisabled(flags, env = process.env) {
+    return (flags[UPDATE_CHECK_FLAG] === 'true' ||
+        env.MODA_CLI_UPDATE_CHECK === '0' ||
+        env.DO_NOT_TRACK === '1' ||
+        // Treat CI as set only when it carries a real truthy value: `CI=false`
+        // and `CI=0` are common ways to simulate a non-CI shell locally.
+        (env.CI !== undefined &&
+            env.CI !== '' &&
+            env.CI !== 'false' &&
+            env.CI !== '0'));
+}
+function cachePath(options = {}) {
+    return join(getModaDir(options), 'update-check.json');
+}
+function readCache(options = {}) {
+    try {
+        const parsed = JSON.parse(readFileSync(cachePath(options), 'utf8'));
+        if (parsed &&
+            typeof parsed === 'object' &&
+            typeof parsed.checked_at === 'number' &&
+            typeof parsed.latest === 'string') {
+            return parsed;
+        }
+    }
+    catch {
+        // Missing or corrupt cache means "never checked".
+    }
+    return undefined;
+}
+function writeCache(cache, options = {}) {
+    try {
+        mkdirSync(getModaDir(options), { recursive: true });
+        writeFileSync(cachePath(options), `${JSON.stringify(cache, null, 2)}\n`, 'utf8');
+    }
+    catch {
+        // Best-effort: an unwritable cache only means we re-check next run.
+    }
+}
+/**
+ * Numeric semver comparison ignoring prerelease/build suffixes; npm's
+ * `latest` dist-tag only carries stable releases, so this is sufficient
+ * without pulling in a semver dependency.
+ */
+export function isNewerVersion(candidate, current) {
+    const parse = (v) => v.split(/[-+]/)[0].split('.').map((part) => Number.parseInt(part, 10) || 0);
+    const a = parse(candidate);
+    const b = parse(current);
+    for (let i = 0; i < 3; i++) {
+        if ((a[i] ?? 0) > (b[i] ?? 0))
+            return true;
+        if ((a[i] ?? 0) < (b[i] ?? 0))
+            return false;
+    }
+    return false;
+}
+/**
+ * Refresh the cached latest version from the npm registry at most once per
+ * 24 hours. Fire-and-forget from the CLI dispatcher. The abort timer is
+ * unref'd so it can't keep the process alive after the socket closes (it does
+ * not unref the in-flight fetch itself — a fast command may still wait up to
+ * REGISTRY_TIMEOUT_MS for the request to resolve, matching the telemetry
+ * module's trade-off). Every failure path is swallowed — an update check must
+ * never break a command.
+ */
+export async function startUpdateCheck(options = {}, now = Date.now()) {
+    const cache = readCache(options);
+    if (cache && now - cache.checked_at < CHECK_INTERVAL_MS) {
+        return;
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REGISTRY_TIMEOUT_MS);
+    if (typeof timeout.unref === 'function') {
+        timeout.unref();
+    }
+    try {
+        const res = await fetch(REGISTRY_LATEST_URL, {
+            headers: { Accept: 'application/json' },
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return;
+        const body = (await res.json());
+        if (typeof body.version !== 'string' || !SEMVER_RE.test(body.version))
+            return;
+        writeCache({ checked_at: now, latest: body.version }, options);
+    }
+    catch {
+        // Network/timeout errors are expected offline; try again next run.
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Returns the upgrade notice when the cached registry version is newer than
+ * the running build, or undefined. Reads only the local cache — never the
+ * network — so it is safe to call synchronously at the end of every command.
+ */
+export function getUpdateNotice(options = {}) {
+    const cache = readCache(options);
+    if (!cache || !isNewerVersion(cache.latest, VERSION)) {
+        return undefined;
+    }
+    return [
+        '',
+        `Update available: moda-cli ${VERSION} → ${cache.latest}`,
+        'Run `npm install -g @moda-ai/cli@latest` to update.',
+    ].join('\n');
+}
+/**
+ * Print the upgrade notice to stderr in interactive terminals only: stdout
+ * stays machine-readable, and piped/CI invocations stay noise-free.
+ */
+export function printUpdateNotice(options = {}) {
+    if (!process.stderr.isTTY)
+        return;
+    const notice = getUpdateNotice(options);
+    if (notice)
+        console.error(notice);
+}
+//# sourceMappingURL=update-check.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "CLI for Moda - AI agent analytics and observability",
   "type": "module",
   "bin": {