nexora-code 1.0.2 → 1.0.3

package/package.json

@@ -1,84 +1,97 @@
-{
-  "name": "nexora-code",
-  "version": "1.0.2",
-  "description": "Nexora Code — World-Class AI Coding Agent CLI. BYOK · 51 tools · Multi-action · Streaming · Session Memory",
-  "author": "Enoch Boadu",
-  "license": "MIT",
-  "type": "module",
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/enochboadu/nexora-code"
-  },
-  "keywords": [
-    "ai",
-    "cli",
-    "agent",
-    "coding-agent",
-    "gemini",
-    "claude",
-    "openai",
-    "openrouter",
-    "chat",
-    "terminal",
-    "nexora"
-  ],
-  "bin": {
-    "nexora": "./dist/bundle.cjs"
-  },
-  "files": [
-    "dist/bundle.cjs",
-    "README.md"
-  ],
-  "scripts": {
-    "start": "tsx src/index.ts",
-    "dev": "tsx watch src/index.ts",
-    "build": "tsc --noEmit && esbuild src/index.ts --bundle --platform=node --target=node20 --format=cjs --define:import.meta.url=\"\\\"file://C:/\\\"\" --external:*.node --external:better-sqlite3 --external:sqlite-vss --external:onnxruntime-node --external:@xenova/transformers --external:keytar --outfile=dist/bundle.cjs",
-    "package": "node scripts/package.js",
-    "release": "node scripts/release.js",
-    "bundle": "esbuild src/index.ts --bundle --platform=node --format=cjs --define:import.meta.url=\"\\\"file://C:/\\\"\" --external:*.node --external:better-sqlite3 --external:sqlite-vss --external:onnxruntime-node --external:@xenova/transformers --external:keytar --outfile=dist/bundle.cjs",
-    "build-binaries": "node scripts/build-binaries.js",
-    "test": "node dist/bundle.cjs --version"
-  },
-  "dependencies": {
-    "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
-    "@opentelemetry/resources": "^2.7.1",
-    "@opentelemetry/sdk-trace-node": "^2.7.1",
-    "@opentelemetry/semantic-conventions": "^1.41.1",
-    "@xenova/transformers": "^2.17.2",
-    "better-sqlite3": "^12.8.0",
-    "boxen": "^8.0.1",
-    "chalk": "^5.3.0",
-    "cli-boxes": "^3.0.0",
-    "clipboardy": "^5.3.1",
-    "compute-cosine-similarity": "^1.1.0",
-    "conf": "^13.0.0",
-    "diff": "^8.0.4",
-    "eventsource": "^2.0.2",
-    "gradient-string": "^2.0.2",
-    "keytar": "^7.9.0",
-    "node-fetch": "^3.3.2",
-    "ora": "^8.0.1",
-    "pdf-parse": "^2.4.5",
-    "semver": "^7.8.1",
-    "sqlite-vss": "^0.1.2",
-    "string-width": "^7.1.0",
-    "update-notifier": "^7.3.1",
-    "wrap-ansi": "^9.0.0"
-  },
-  "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/keytar": "^4.4.0",
-    "@types/node": "^25.9.1",
-    "@types/semver": "^7.7.1",
-    "@types/update-notifier": "^6.0.8",
-    "esbuild": "^0.21.5",
-    "eslint": "^10.4.1",
-    "postject": "^1.0.0-alpha.6",
-    "tsx": "^4.22.4",
-    "typescript": "^6.0.3"
-  }
-}
+{
+    "name": "nexora-code",
+    "version": "1.0.3",
+    "description": "Nexora Code — World-Class AI Coding Agent CLI. BYOK · 51 tools · Multi-action · Streaming · Session Memory",
+    "author": "Enoch Boadu",
+    "license": "MIT",
+    "type": "module",
+    "engines": {
+        "node": ">=20.0.0"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/enochboadu/nexora-code"
+    },
+    "keywords": [
+        "ai",
+        "cli",
+        "agent",
+        "coding-agent",
+        "gemini",
+        "claude",
+        "openai",
+        "openrouter",
+        "chat",
+        "terminal",
+        "nexora"
+    ],
+    "bin": {
+        "nexora": "./dist/bundle.cjs"
+    },
+    "files": [
+        "dist/bundle.cjs",
+        "assets/",
+        "scripts/desktop/",
+        "README.md"
+    ],
+    "scripts": {
+        "start": "tsx src/index.ts",
+        "dev": "tsx watch src/index.ts",
+        "build": "tsc --noEmit && esbuild src/index.ts --bundle --platform=node --target=node20 --format=cjs --define:import.meta.url=\"\\\"file://C:/\\\"\" --external:*.node --external:better-sqlite3 --external:sqlite-vss --external:onnxruntime-node --external:@xenova/transformers --external:keytar --outfile=dist/bundle.cjs",
+        "package": "node scripts/package.js",
+        "release": "node scripts/release.js",
+        "bundle": "esbuild src/index.ts --bundle --platform=node --format=cjs --define:import.meta.url=\"\\\"file://C:/\\\"\" --external:*.node --external:better-sqlite3 --external:sqlite-vss --external:onnxruntime-node --external:@xenova/transformers --external:keytar --outfile=dist/bundle.cjs",
+        "build-binaries": "node scripts/build-binaries.js",
+        "test": "node dist/bundle.cjs --version",
+        "postinstall": "node ./scripts/desktop/postinstall.cjs",
+        "preuninstall": "node ./scripts/desktop/preuninstall.cjs"
+    },
+    "dependencies": {
+        "@anthropic-ai/sdk": "^0.101.0",
+        "@inquirer/prompts": "^8.5.2",
+        "@opentelemetry/api": "^1.9.1",
+        "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
+        "@opentelemetry/resources": "^2.7.1",
+        "@opentelemetry/sdk-trace-node": "^2.7.1",
+        "@opentelemetry/semantic-conventions": "^1.41.1",
+        "@xenova/transformers": "^2.17.2",
+        "better-sqlite3": "^12.8.0",
+        "boxen": "^8.0.1",
+        "chalk": "^5.3.0",
+        "cli-boxes": "^3.0.0",
+        "clipboardy": "^5.3.1",
+        "compute-cosine-similarity": "^1.1.0",
+        "conf": "^13.0.0",
+        "diff": "^8.0.4",
+        "eventsource": "^2.0.2",
+        "gradient-string": "^2.0.2",
+        "keytar": "^7.9.0",
+        "node-fetch": "^3.3.2",
+        "open": "^11.0.0",
+        "ora": "^8.0.1",
+        "pdf-parse": "^2.4.5",
+        "semver": "^7.8.1",
+        "sqlite-vss": "^0.1.2",
+        "string-width": "^7.1.0",
+        "update-notifier": "^7.3.1",
+        "wrap-ansi": "^9.0.0",
+        "xlsx": "^0.18.5"
+    },
+    "devDependencies": {
+        "@types/archiver": "^7.0.0",
+        "@types/better-sqlite3": "^7.6.13",
+        "@types/keytar": "^4.4.0",
+        "@types/node": "^25.9.1",
+        "@types/semver": "^7.7.1",
+        "@types/update-notifier": "^6.0.8",
+        "archiver": "^8.0.0",
+        "esbuild": "^0.21.5",
+        "eslint": "^10.4.1",
+        "postject": "^1.0.0-alpha.6",
+        "tsx": "^4.22.4",
+        "typescript": "^6.0.3"
+    },
+    "workspaces": [
+        "packages/*"
+    ]
+}

package/scripts/desktop/linux.cjs

@@ -0,0 +1,126 @@
+'use strict';
+// ╔══════════════════════════════════════════════════════════════════════════════╗
+// ║  Nexora Code — Linux Desktop Entry Creator                                   ║
+// ║  Generates XDG-compliant .desktop files — works on GNOME, KDE, XFCE etc.  ║
+// ╚══════════════════════════════════════════════════════════════════════════════╝
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs   = require('fs');
+
+// Ordered by quality of terminal experience (best first)
+const TERMINAL_CANDIDATES = [
+  { bin: 'gnome-terminal',       args: '-- bash -c "nexora-code; exec bash"' },
+  { bin: 'konsole',              args: '-e bash -c "nexora-code; exec bash"' },
+  { bin: 'xfce4-terminal',      args: '--command="bash -c \'nexora-code; exec bash\'"' },
+  { bin: 'tilix',               args: '-e "bash -c \'nexora-code; exec bash\'"' },
+  { bin: 'alacritty',           args: '-e bash -c "nexora-code; exec bash"' },
+  { bin: 'kitty',               args: 'bash -c "nexora-code; exec bash"' },
+  { bin: 'xterm',               args: '-e "nexora-code; bash"' },
+  { bin: 'x-terminal-emulator', args: '-e bash -c "nexora-code; exec bash"' }, // Debian/Ubuntu alias
+];
+
+/**
+ * Detects the best available terminal emulator on Linux.
+ * Returns null if none found (headless/Wayland-only without emulator).
+ */
+function detectLinuxTerminal() {
+  for (const candidate of TERMINAL_CANDIDATES) {
+    try {
+      execSync(`which ${candidate.bin}`, { stdio: 'pipe' });
+      return candidate;
+    } catch { continue; }
+  }
+  return null;
+}
+
+/**
+ * Creates a .desktop launcher on the desktop and in the app menu.
+ */
+function createLinuxShortcut(ctx) {
+  const terminal   = detectLinuxTerminal();
+  const iconPath   = path.join(ctx.iconDir, 'icon.png');
+  const iconExists = fs.existsSync(iconPath);
+
+  // XDG .desktop file spec
+  const execLine = terminal
+    ? `${terminal.bin} ${terminal.args}`
+    : 'nexora-code';  // Last resort: hope $TERM is set and system opens a terminal
+
+  const iconLine = iconExists ? iconPath : 'utilities-terminal';
+
+  const desktopContent = [
+    '[Desktop Entry]',
+    'Version=1.0',
+    'Type=Application',
+    'Name=Nexora Code',
+    'GenericName=AI Developer Workspace',
+    'Comment=Launch Nexora Code — World-class AI coding assistant',
+    `Exec=${execLine}`,
+    `Icon=${iconLine}`,
+    'Terminal=false',     // false: the terminal emulator handles this
+    'StartupNotify=true',
+    'Categories=Development;IDE;',
+    'Keywords=nexora;code;ai;developer;assistant;cli;',
+    'StartupWMClass=nexora-code',
+  ].join('\n') + '\n';
+
+  // 1. Desktop icon
+  const desktopFilePath = path.join(ctx.desktopPath, 'nexora-code.desktop');
+  fs.writeFileSync(desktopFilePath, desktopContent, 'utf-8');
+  fs.chmodSync(desktopFilePath, 0o755);  // Mark as trusted on GNOME 3.28+
+  console.log(`  ✓  Desktop launcher:   ${desktopFilePath}`);
+
+  // 2. App menu entry (~/.local/share/applications/)
+  const appMenuDir  = path.join(ctx.realHomeDir, '.local', 'share', 'applications');
+  const appMenuPath = path.join(appMenuDir, 'nexora-code.desktop');
+  try {
+    fs.mkdirSync(appMenuDir, { recursive: true });
+    fs.writeFileSync(appMenuPath, desktopContent, 'utf-8');
+    fs.chmodSync(appMenuPath, 0o755);
+    console.log(`  ✓  App menu entry:     ${appMenuPath}`);
+
+    // Refresh the app database so it appears immediately in launchers
+    try {
+      execSync('update-desktop-database ~/.local/share/applications', { stdio: 'pipe' });
+    } catch { /* non-critical — many distros don't have this */ }
+  } catch (err) {
+    console.log(`  ⚠  App menu entry skipped: ${err.message}`);
+  }
+
+  if (terminal) {
+    console.log(`  ✓  Terminal detected:  ${terminal.bin}`);
+  } else {
+    console.log('  ⚠  No terminal emulator detected — using system default.');
+  }
+
+  console.log('');
+  console.log('  → Double-click the icon on your Desktop to launch Nexora Code!');
+  if (!terminal) {
+    console.log('  → Or run "nexora-code" directly in your terminal.');
+  }
+  console.log('');
+}
+
+/**
+ * Removes all Nexora Code shortcut files on Linux.
+ */
+function removeLinuxShortcut(ctx) {
+  const targets = [
+    path.join(ctx.desktopPath, 'nexora-code.desktop'),
+    path.join(ctx.realHomeDir, '.local', 'share', 'applications', 'nexora-code.desktop'),
+  ];
+
+  for (const t of targets) {
+    try {
+      fs.unlinkSync(t);
+      console.log(`  ✓  Removed: ${t}`);
+    } catch { /* already gone */ }
+  }
+
+  try {
+    execSync('update-desktop-database ~/.local/share/applications', { stdio: 'pipe' });
+  } catch { /* non-critical */ }
+}
+
+module.exports = { createLinuxShortcut, removeLinuxShortcut };

package/scripts/desktop/macos.cjs

@@ -0,0 +1,169 @@
+'use strict';
+// ╔══════════════════════════════════════════════════════════════════════════════╗
+// ║  Nexora Code — macOS App Bundle Creator                                      ║
+// ║  Creates a proper .app bundle (not just a .command file) with icon support  ║
+// ╚══════════════════════════════════════════════════════════════════════════════╝
+
+const { execSync }  = require('child_process');
+const path          = require('path');
+const fs            = require('fs');
+
+const APP_NAME = 'Nexora Code';
+
+/**
+ * Detect best terminal on macOS.
+ * Priority: iTerm2 > Warp > Hyper > Terminal.app (always available)
+ */
+function detectMacTerminalScript() {
+  if (fs.existsSync('/Applications/iTerm.app')) {
+    return `#!/bin/bash
+open -a iTerm -- bash -c "nexora-code; exec bash"
+`;
+  }
+
+  if (fs.existsSync('/Applications/Warp.app')) {
+    // Warp doesn't support direct command injection via `open` args.
+    // Best we can do is open it and let the user type nexora-code.
+    return `#!/bin/bash
+open -a Warp
+osascript -e 'tell application "Warp" to activate'
+`;
+  }
+
+  if (fs.existsSync('/Applications/Hyper.app')) {
+    return `#!/bin/bash
+open -a Hyper
+`;
+  }
+
+  // Terminal.app — always present on macOS
+  return `#!/bin/bash
+osascript <<'APPLESCRIPT'
+tell application "Terminal"
+  activate
+  do script "nexora-code"
+end tell
+APPLESCRIPT
+`;
+}
+
+/**
+ * Builds the Info.plist content for the .app bundle.
+ */
+function buildPlist(hasIcon) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleExecutable</key>
+  <string>nexora-launcher</string>
+  <key>CFBundleIdentifier</key>
+  <string>cloud.getnexora.code</string>
+  <key>CFBundleName</key>
+  <string>${APP_NAME}</string>
+  <key>CFBundleDisplayName</key>
+  <string>${APP_NAME}</string>
+  <key>CFBundleVersion</key>
+  <string>1.0.0</string>
+  <key>CFBundleShortVersionString</key>
+  <string>1.0.0</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  ${hasIcon ? '<key>CFBundleIconFile</key>\n  <string>AppIcon</string>' : ''}
+  <key>LSMinimumSystemVersion</key>
+  <string>11.0</string>
+  <key>NSHighResolutionCapable</key>
+  <true/>
+  <key>LSUIElement</key>
+  <false/>
+</dict>
+</plist>
+`;
+}
+
+/**
+ * Creates a proper macOS .app bundle on the Desktop.
+ * Structure:
+ *   Nexora Code.app/
+ *     Contents/
+ *       Info.plist
+ *       MacOS/
+ *         nexora-launcher   (executable shell script)
+ *       Resources/
+ *         AppIcon.icns      (optional)
+ */
+function createMacosShortcut(ctx) {
+  const appBundlePath = path.join(ctx.desktopPath, `${APP_NAME}.app`);
+  const macOSDir      = path.join(appBundlePath, 'Contents', 'MacOS');
+  const resourceDir   = path.join(appBundlePath, 'Contents', 'Resources');
+  const icnsPath      = path.join(ctx.iconDir, 'icon.icns');
+  const hasIcon       = fs.existsSync(icnsPath);
+
+  // Create bundle directory structure
+  fs.mkdirSync(macOSDir,    { recursive: true });
+  fs.mkdirSync(resourceDir, { recursive: true });
+
+  // Write launcher script
+  const launcherContent = detectMacTerminalScript();
+  const launcherPath    = path.join(macOSDir, 'nexora-launcher');
+  fs.writeFileSync(launcherPath, launcherContent, 'utf-8');
+  fs.chmodSync(launcherPath, 0o755);
+
+  // Write Info.plist
+  fs.writeFileSync(
+    path.join(appBundlePath, 'Contents', 'Info.plist'),
+    buildPlist(hasIcon),
+    'utf-8'
+  );
+
+  // Copy icon if available
+  if (hasIcon) {
+    fs.copyFileSync(icnsPath, path.join(resourceDir, 'AppIcon.icns'));
+  }
+
+  // Remove quarantine flag (prevents "app is damaged" Gatekeeper warning)
+  try { execSync(`xattr -dr com.apple.quarantine "${appBundlePath}"`, { stdio: 'pipe' }); } catch {}
+
+  // Touch the bundle to refresh Finder icon cache
+  try { execSync(`touch "${appBundlePath}"`, { stdio: 'pipe' }); } catch {}
+
+  console.log(`  ✓  App bundle created: ${appBundlePath}`);
+
+  // Also create a simpler .command file as a backup for users who prefer it
+  createCommandFallback(ctx.desktopPath);
+
+  console.log('');
+  console.log(`  → Double-click "${APP_NAME}" on your Desktop to launch Nexora!`);
+  console.log('');
+}
+
+/**
+ * Creates a fallback .command script (simpler than .app, but always works).
+ */
+function createCommandFallback(desktopPath) {
+  const commandPath    = path.join(desktopPath, `${APP_NAME} (Terminal).command`);
+  const commandContent = `#!/bin/bash\nclear\nnexora-code\nexec $SHELL\n`;
+  fs.writeFileSync(commandPath, commandContent, 'utf-8');
+  fs.chmodSync(commandPath, 0o755);
+  console.log(`  ✓  .command fallback:  ${commandPath}`);
+}
+
+/**
+ * Removes all Nexora Code shortcut files on macOS.
+ */
+function removeMacosShortcut(ctx) {
+  const targets = [
+    path.join(ctx.desktopPath, `${APP_NAME}.app`),
+    path.join(ctx.desktopPath, `${APP_NAME} (Terminal).command`),
+  ];
+
+  for (const t of targets) {
+    try {
+      fs.rmSync(t, { recursive: true, force: true });
+      console.log(`  ✓  Removed: ${t}`);
+    } catch { /* already gone */ }
+  }
+}
+
+module.exports = { createMacosShortcut, removeMacosShortcut };

package/scripts/desktop/make-ico.ps1

@@ -0,0 +1,85 @@
+# make-ico.ps1 — Nexora Code icon generator
+# Composites the logo onto a dark navy rounded-corner background.
+
+Add-Type -AssemblyName System.Drawing
+
+$src      = 'C:\dev\nexora-lab\Nexora_code_logo.png'
+$assetsDir = 'C:\dev\nexora-lab\assets'
+$pngDst   = $assetsDir + '\icon.png'
+$dst      = $assetsDir + '\icon.ico'
+[int]$SIZE    = 256
+[int]$RADIUS  = 40
+[int]$PADDING = 26   # pixels of breathing room around the logo
+
+New-Item -ItemType Directory -Force -Path $assetsDir | Out-Null
+
+# ── 1. Load original PNG ──────────────────────────────────────────────────────
+$original = [System.Drawing.Bitmap]::FromFile($src)
+
+# ── 2. Create canvas ──────────────────────────────────────────────────────────
+$canvas = New-Object System.Drawing.Bitmap($SIZE, $SIZE, [System.Drawing.Imaging.PixelFormat]::Format32bppArgb)
+$g = [System.Drawing.Graphics]::FromImage($canvas)
+$g.SmoothingMode      = [System.Drawing.Drawing2D.SmoothingMode]::AntiAlias
+$g.InterpolationMode  = [System.Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic
+$g.CompositingQuality = [System.Drawing.Drawing2D.CompositingQuality]::HighQuality
+
+# Fill transparent first (clear)
+$g.Clear([System.Drawing.Color]::Transparent)
+
+# ── 3. Draw dark rounded-rectangle background ─────────────────────────────────
+# Dark navy: #0D111C — matches Nexora's terminal dark theme
+$bgColor = [System.Drawing.Color]::FromArgb(255, 13, 17, 28)
+$brush   = New-Object System.Drawing.SolidBrush($bgColor)
+
+# Build rounded-rect GraphicsPath manually
+$path = New-Object System.Drawing.Drawing2D.GraphicsPath
+
+# Top-left arc
+$path.AddArc(0, 0, ($RADIUS * 2), ($RADIUS * 2), 180, 90)
+# Top-right arc
+$path.AddArc(($SIZE - $RADIUS * 2), 0, ($RADIUS * 2), ($RADIUS * 2), 270, 90)
+# Bottom-right arc
+$path.AddArc(($SIZE - $RADIUS * 2), ($SIZE - $RADIUS * 2), ($RADIUS * 2), ($RADIUS * 2), 0, 90)
+# Bottom-left arc
+$path.AddArc(0, ($SIZE - $RADIUS * 2), ($RADIUS * 2), ($RADIUS * 2), 90, 90)
+$path.CloseFigure()
+
+$g.FillPath($brush, $path)
+$brush.Dispose()
+$path.Dispose()
+
+# ── 4. Draw logo centred with padding ─────────────────────────────────────────
+[int]$logoSize = $SIZE - ($PADDING * 2)
+$logoRect = New-Object System.Drawing.Rectangle($PADDING, $PADDING, $logoSize, $logoSize)
+$g.DrawImage($original, [System.Drawing.Rectangle]$logoRect)
+
+$g.Dispose()
+$original.Dispose()
+
+# ── 5. Save icon.png ─────────────────────────────────────────────────────────
+$canvas.Save($pngDst, [System.Drawing.Imaging.ImageFormat]::Png)
+Write-Host "  [+] icon.png saved: $pngDst"
+
+# ── 6. Build ICO binary (PNG-in-ICO, Vista+) ──────────────────────────────────
+$ms = New-Object System.IO.MemoryStream
+$canvas.Save($ms, [System.Drawing.Imaging.ImageFormat]::Png)
+$pngBytes = $ms.ToArray()
+$ms.Dispose()
+$canvas.Dispose()
+
+$fs = [System.IO.File]::Create($dst)
+$w  = New-Object System.IO.BinaryWriter($fs)
+# ICO Header (6 bytes)
+$w.Write([uint16]0); $w.Write([uint16]1); $w.Write([uint16]1)
+# Directory Entry (16 bytes)
+$w.Write([byte]0);   $w.Write([byte]0);   $w.Write([byte]0); $w.Write([byte]0)
+$w.Write([uint16]1); $w.Write([uint16]32)
+$w.Write([uint32]$pngBytes.Length)
+$w.Write([uint32]22)   # data starts at byte 22 (6+16)
+# PNG data
+$w.Write($pngBytes)
+$w.Flush(); $w.Close(); $fs.Close()
+
+$icoSize = (Get-Item $dst).Length
+Write-Host "  [+] icon.ico saved: $dst ($icoSize bytes)"
+Write-Host "  Done."

package/scripts/desktop/postinstall.cjs

@@ -0,0 +1,40 @@
+'use strict';
+// ╔══════════════════════════════════════════════════════════════════════════════╗
+// ║  Nexora Code — npm postinstall entry point                                   ║
+// ║  Runs after: npm install -g nexora-code                                      ║
+// ║                                                                              ║
+// ║  Guards:                                                                     ║
+// ║    • Exits silently (0) on local/dev installs (not -g)                      ║
+// ║    • Exits silently (0) in CI environments                                   ║
+// ║    • Never propagates errors — shortcut failure ≠ install failure           ║
+// ╚══════════════════════════════════════════════════════════════════════════════╝
+
+const { createShortcut } = require('./shortcut.cjs');
+
+function main() {
+  // ── Guard 1: Only run on global installs (-g flag) ──────────────────────────
+  // npm sets npm_config_global=true for `npm install -g` commands.
+  // Local `npm install` inside the project does NOT set this.
+  const isGlobalInstall = process.env.npm_config_global === 'true';
+  if (!isGlobalInstall) {
+    // Silent exit — developer installs don't need a shortcut
+    process.exit(0);
+  }
+
+  // ── Guard 2: Skip in CI/CD environments ──────────────────────────────────────
+  const isCI =
+    process.env.CI                    ||
+    process.env.CONTINUOUS_INTEGRATION ||
+    process.env.GITHUB_ACTIONS         ||
+    process.env.TRAVIS                 ||
+    process.env.CIRCLECI               ||
+    process.env.GITLAB_CI;
+
+  if (isCI) {
+    process.exit(0);
+  }
+
+  createShortcut();
+}
+
+main();

package/scripts/desktop/preuninstall.cjs

@@ -0,0 +1,29 @@
+'use strict';
+// ╔══════════════════════════════════════════════════════════════════════════════╗
+// ║  Nexora Code — npm preuninstall entry point                                  ║
+// ║  Runs before: npm uninstall -g nexora-code                                   ║
+// ║                                                                              ║
+// ║  Cleans up the desktop shortcut so users get a completely clean system      ║
+// ╚══════════════════════════════════════════════════════════════════════════════╝
+
+const { removeShortcut } = require('./shortcut.cjs');
+
+function main() {
+  // Only clean up after global uninstalls — not local dev uninstalls
+  const isGlobalUninstall = process.env.npm_config_global === 'true';
+  if (!isGlobalUninstall) {
+    process.exit(0);
+  }
+
+  console.log('');
+  console.log('  Nexora Code — Cleaning up desktop shortcut...');
+  removeShortcut();
+}
+
+// Never let cleanup errors break the uninstall
+try {
+  main();
+} catch (err) {
+  console.log(`  ⚠  Cleanup warning: ${err.message}`);
+  process.exit(0);
+}