carto-md 2.0.4 → 2.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carto-md",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "Structural intelligence layer for AI coding tools. Indexes your codebase into SQLite — routes, models, import graph, blast radius, domains — and exposes 16 MCP tools for Kiro, Cursor, and Claude.",
   "bin": {
     "carto": "src/cli/index.js"

package/src/cli/check.js

@@ -4,8 +4,10 @@ const { execSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 const { SQLiteStore } = require('../store/sqlite-store');
+const { checkForUpdate } = require('./update-check');
 
 async function run(projectRoot) {
+  checkForUpdate(); // fire and forget
   const dbPath = path.join(projectRoot, '.carto', 'carto.db');
 
   if (!fs.existsSync(dbPath)) {

package/src/cli/impact.js

@@ -2,8 +2,10 @@
 
 const path = require('path');
 const { Carto } = require('../../index.js');
+const { checkForUpdate } = require('./update-check');
 
 async function run(projectRoot, fileArg) {
+  checkForUpdate(); // fire and forget
   if (!fileArg) {
     console.error('[CARTO] Usage: carto impact <file>');
     process.exit(1);

package/src/cli/init.js

@@ -3,8 +3,10 @@ const path = require('path');
 const { detectFramework } = require('../detector/framework');
 const { parseCartoIgnore } = require('../security/ignore');
 const { runSyncV2, discoverFiles: discoverFilesV2 } = require('../store/sync-v2');
+const { checkForUpdate } = require('./update-check');
 
 async function run(projectRoot) {
+  checkForUpdate(); // fire and forget
   console.log('[CARTO] Detecting project...');
 
   const detection = detectFramework(projectRoot);

package/src/cli/serve.js

@@ -1,7 +1,9 @@
 const path = require('path');
 const fs = require('fs');
+const { checkForUpdate } = require('./update-check');
 
 function run(projectRoot) {
+  checkForUpdate(); // fire and forget
   // Prefer V2 SQLite-backed server
   const dbPath = path.join(projectRoot, '.carto', 'carto.db');
   if (fs.existsSync(dbPath)) {

package/src/cli/update-check.js

@@ -1,12 +1,21 @@
+'use strict';
+
 const https = require('https');
 const pkg = require('../../package.json');
 
 /**
  * Fire-and-forget version check against the npm registry.
- * Prints a one-liner to stderr if a newer version exists.
- * Never throws, never blocks — safe to call without await.
+ *
+ * Prints a visually distinct notice to stderr if a newer version is on npm.
+ * Never throws, never blocks (3s socket timeout, ignores all errors) —
+ * safe to call without await from any CLI command's entry point.
+ *
+ * Set `CARTO_NO_UPDATE_CHECK=1` to disable entirely (used in test runs and
+ * by users who don't want the egress).
  */
 function checkForUpdate() {
+  if (process.env.CARTO_NO_UPDATE_CHECK) return;
+
   const req = https.get('https://registry.npmjs.org/carto-md/latest', {
     timeout: 3000,
   }, (res) => {
@@ -16,10 +25,8 @@ function checkForUpdate() {
       try {
         const data = JSON.parse(body);
         const latest = data.version;
-        if (latest && latest !== pkg.version && isNewer(latest, pkg.version)) {
-          process.stderr.write(
-            `[CARTO] Update available: ${pkg.version} → ${latest}  |  npm install -g carto-md\n`
-          );
+        if (latest && isNewer(latest, pkg.version)) {
+          process.stderr.write(formatNotice(pkg.version, latest));
         }
       } catch (_) {
         // malformed JSON — ignore
@@ -27,6 +34,10 @@ function checkForUpdate() {
     });
   });
 
+  // unref so the pending request never delays process exit on its own —
+  // if the main command finishes first, the check is silently dropped.
+  if (typeof req.unref === 'function') req.unref();
+
   req.on('timeout', () => { req.destroy(); });
   req.on('error', () => { /* offline / DNS failure — ignore */ });
 }
@@ -45,4 +56,36 @@ function isNewer(a, b) {
   return false;
 }
 
-module.exports = { checkForUpdate };
+/**
+ * formatNotice(current, latest) → multi-line stderr string.
+ *
+ * TTY-aware: emits ANSI yellow + bold when stderr is a TTY, plain text
+ * otherwise (so piped output and CI logs stay clean).
+ *
+ * Format (TTY example, ★ in yellow, version + command in bold):
+ *
+ *     <blank line>
+ *     [CARTO] ★ Update available: 2.0.1 → 2.0.5
+ *     [CARTO]   Run: npm install -g carto-md
+ *     <blank line>
+ *
+ * Two blank lines (one before, one after) separate the notice from
+ * regular [CARTO] log output so the upgrade prompt stands out even when
+ * it lands mid-progress (the check is fire-and-forget, so the response
+ * arrives whenever the network resolves).
+ */
+function formatNotice(current, latest) {
+  const useColor = !!process.stderr.isTTY && !process.env.NO_COLOR;
+  const yellow = (s) => useColor ? `\x1b[33m${s}\x1b[0m` : s;
+  const bold   = (s) => useColor ? `\x1b[1m${s}\x1b[0m`  : s;
+
+  return [
+    '',
+    `${yellow('[CARTO] ★ Update available:')} ${bold(`${current} → ${latest}`)}`,
+    `${yellow('[CARTO]   Run:')} ${bold('npm install -g carto-md')}`,
+    '',
+    ''
+  ].join('\n');
+}
+
+module.exports = { checkForUpdate, isNewer, formatNotice };