feat(desktop): add cross-platform Electron shell

.github/workflows/desktop-packaging.yml

@@ -0,0 +1,178 @@
+name: Desktop Packaging
+
+on:
+  pull_request:
+    paths:
+      - .github/workflows/desktop-packaging.yml
+      - gitnexus-desktop/**
+      - gitnexus/**
+      - gitnexus-web/**
+      - gitnexus-shared/**
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  validate:
+    name: Validate desktop package
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: gitnexus-desktop/package-lock.json
+
+      - name: Install desktop dependencies
+        run: npm ci
+        working-directory: gitnexus-desktop
+
+      - name: Typecheck desktop package
+        run: npm run typecheck
+        working-directory: gitnexus-desktop
+
+      - name: Run desktop unit tests
+        run: npm test
+        working-directory: gitnexus-desktop
+
+  package:
+    name: Build ${{ matrix.label }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 90
+    needs: validate
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: windows-latest
+            label: Windows NSIS
+            command: npm run build:win
+            artifact_name: gitnexus-desktop-windows
+            installer_glob: gitnexus-desktop/release/*/GitNexus Desktop Setup *.exe
+            artifact_paths: |
+              gitnexus-desktop/release/*/GitNexus Desktop Setup *.exe
+              gitnexus-desktop/release/*/win-unpacked/**
+          - os: macos-latest
+            label: macOS DMG
+            command: npm run build:mac
+            artifact_name: gitnexus-desktop-macos
+            installer_glob: gitnexus-desktop/release/*/*.dmg
+            artifact_paths: |
+              gitnexus-desktop/release/*/*.dmg
+              gitnexus-desktop/release/*/mac*/**
+          - os: ubuntu-latest
+            label: Linux AppImage
+            command: npm run build:linux
+            artifact_name: gitnexus-desktop-linux
+            installer_glob: gitnexus-desktop/release/*/*.AppImage
+            artifact_paths: |
+              gitnexus-desktop/release/*/*.AppImage
+              gitnexus-desktop/release/*/linux-unpacked/**
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: |
+            gitnexus-shared/package-lock.json
+            gitnexus/package-lock.json
+            gitnexus-web/package-lock.json
+            gitnexus-desktop/package-lock.json
+
+      - name: Install shared dependencies
+        run: npm ci
+        working-directory: gitnexus-shared
+
+      - name: Build shared package
+        run: npm run build
+        working-directory: gitnexus-shared
+
+      - name: Install GitNexus dependencies
+        run: npm ci
+        working-directory: gitnexus
+
+      - name: Install web dependencies
+        run: npm ci
+        working-directory: gitnexus-web
+
+      - name: Install desktop dependencies
+        run: npm ci
+        working-directory: gitnexus-desktop
+
+      - name: Build unpacked desktop bundle
+        run: npm run build:dir
+        working-directory: gitnexus-desktop
+        env:
+          CSC_IDENTITY_AUTO_DISCOVERY: 'false'
+
+      - name: Inspect rebuilt native modules (Windows)
+        if: matrix.os == 'windows-latest'
+        shell: pwsh
+        run: |
+          $releaseDir = Get-ChildItem gitnexus-desktop/release -Directory | Sort-Object LastWriteTime -Descending | Select-Object -First 1
+
+          if (-not $releaseDir) {
+            Write-Host "No release directory found."
+            exit 0
+          }
+
+          $runtimeNodeModules = Join-Path $releaseDir.FullName 'win-unpacked\resources\gitnexus\node_modules'
+          Write-Host "Inspecting native modules under $runtimeNodeModules"
+
+          if (-not (Test-Path $runtimeNodeModules)) {
+            Write-Host "Runtime node_modules directory not found."
+            exit 0
+          }
+
+          Get-ChildItem $runtimeNodeModules -Recurse -Filter '*.node' |
+            Select-Object FullName, LastWriteTime |
+            Format-Table -AutoSize
+
+      - name: Start Xvfb
+        if: matrix.os == 'ubuntu-latest'
+        run: |
+          Xvfb :99 -screen 0 1024x768x24 &
+          echo "DISPLAY=:99" >> "$GITHUB_ENV"
+
+      - name: Smoke test unpacked desktop bundle
+        run: node scripts/smoke-unpacked.mjs
+        working-directory: gitnexus-desktop
+
+      - name: Build desktop package
+        run: ${{ matrix.command }}
+        working-directory: gitnexus-desktop
+        env:
+          CSC_IDENTITY_AUTO_DISCOVERY: 'false'
+
+      - name: Upload desktop artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: ${{ matrix.artifact_name }}
+          path: ${{ matrix.artifact_paths }}
+          if-no-files-found: error
+          retention-days: 14
+
+      - name: Attest desktop artifacts
+        if: github.event_name != 'pull_request'
+        uses: actions/attest-build-provenance@db473fddc028af60658334401dc6fa3ffd8669fd # v2.3.0
+        with:
+          subject-path: ${{ matrix.installer_glob }}

.gitignore

@@ -105,8 +105,11 @@ gitnexus/vendor/**/node_modules/
 
 local_docs/
 
+undefined/
+_bmad/
 # Local agent scratch / review prompts (never commit)
 .tmp/
 .agents/
 .context/
 gitnexus/web/
+.pi/

.husky/pre-commit

@@ -20,7 +20,7 @@ fi
 
 if [ -n "$CLI_CHANGED" ]; then
   echo "pre-commit: typechecking gitnexus..."
-  cd "$ROOT/gitnexus" && ./node_modules/.bin/tsc --noEmit || exit 1
+  cd "$ROOT" && ./node_modules/.bin/tsc -p gitnexus/tsconfig.json --noEmit || exit 1
 fi
 
 echo "pre-commit: all checks passed"

eslint.config.mjs

@@ -50,6 +50,7 @@ export default [
   {
     ignores: [
       '**/dist/**',
+      'gitnexus-desktop/release/**',
       '**/node_modules/**',
       '**/coverage/**',
       'gitnexus/vendor/**',

gitnexus-desktop/.gitignore

@@ -0,0 +1,2 @@
+dist/
+release/

gitnexus-desktop/README.md

@@ -0,0 +1,32 @@
+# GitNexus Desktop
+
+Electron desktop shell for GitNexus. The app starts the local backend and loads the real `gitnexus-web` UI inside the desktop window.
+
+## Commands
+
+```bash
+npm run dev
+npm run build:dir
+npm run build:win
+npm run build:mac
+npm run build:linux
+```
+
+- `npm run dev` starts the Electron shell plus the local GitNexus backend.
+- `npm run build:dir` creates an unpacked desktop app directory.
+- `npm run build:win` creates a Windows NSIS installer `.exe`.
+- `npm run build:mac` creates a macOS `.dmg`.
+- `npm run build:linux` creates a Linux `.AppImage`.
+- `npm run smoke:unpacked` launches the latest unpacked desktop build, verifies startup, and exits.
+
+Build output is written under `gitnexus-desktop/release/<timestamp>/`.
+
+## PR Artifacts
+
+The `Desktop Packaging` GitHub Actions workflow builds an unpacked desktop app, smoke-tests startup, then uploads preview desktop artifacts for pull requests that touch `.github/workflows/desktop-packaging.yml`, `gitnexus-desktop/**`, `gitnexus/**`, `gitnexus-web/**`, or `gitnexus-shared/**`.
+
+- `gitnexus-desktop-windows` contains the Windows NSIS installer `.exe` and `win-unpacked/`.
+- `gitnexus-desktop-macos` contains the macOS `.dmg` and `mac*/` output.
+- `gitnexus-desktop-linux` contains the Linux `.AppImage` and `linux-unpacked/`.
+
+GitHub artifact URLs are run-specific and expire, so use the artifact names above from the latest successful PR workflow run.

gitnexus-desktop/electron-builder.yml

@@ -0,0 +1,59 @@
+appId: io.github.abhigyanpatwari.gitnexus.desktop
+productName: GitNexus Desktop
+directories:
+  buildResources: build
+files:
+  - dist/**/*
+  - package.json
+extraResources:
+  - from: '${env.GITNEXUS_DESKTOP_WEB_DIST}'
+    to: gitnexus-web
+    filter:
+      - '**/*'
+  - from: '${env.GITNEXUS_DESKTOP_GITNEXUS_DIST}'
+    to: gitnexus/dist
+    filter:
+      - '**/*'
+  - from: '${env.GITNEXUS_DESKTOP_GITNEXUS_NODE_MODULES}'
+    to: gitnexus/node_modules
+    filter:
+      - '**/*'
+  - from: '${env.GITNEXUS_DESKTOP_GITNEXUS_HOOKS}'
+    to: gitnexus/hooks
+    filter:
+      - '**/*'
+  - from: '${env.GITNEXUS_DESKTOP_GITNEXUS_SKILLS}'
+    to: gitnexus/skills
+    filter:
+      - '**/*'
+  - from: '${env.GITNEXUS_DESKTOP_GITNEXUS_VENDOR}'
+    to: gitnexus/vendor
+    filter:
+      - '**/*'
+  - from: '${env.GITNEXUS_DESKTOP_GITNEXUS_PACKAGE_JSON}'
+    to: gitnexus/package.json
+  - from: 'build/icon.png'
+    to: icon.png
+  - from: 'build/icon.ico'
+    to: icon.ico
+asar: false
+npmRebuild: false
+afterPack: scripts/after-pack.mjs
+win:
+  signAndEditExecutable: false
+  icon: build/icon.ico
+  target:
+    - nsis
+mac:
+  category: public.app-category.developer-tools
+  icon: build/icon.png
+  target:
+    - dmg
+linux:
+  category: Development
+  icon: build/icon.png
+  target:
+    - AppImage
+nsis:
+  oneClick: false
+  allowToChangeInstallationDirectory: true

gitnexus-desktop/electron.vite.config.ts

@@ -0,0 +1,46 @@
+import { resolve } from 'node:path';
+
+export default {
+  main: {
+    build: {
+      outDir: 'dist/main',
+      rollupOptions: {
+        input: {
+          main: resolve(__dirname, 'src/main/main.ts'),
+        },
+      },
+    },
+  },
+  preload: {
+    build: {
+      outDir: 'dist/preload',
+      rollupOptions: {
+        input: {
+          preload: resolve(__dirname, 'src/main/preload.ts'),
+        },
+        output: {
+          format: 'cjs',
+          entryFileNames: 'preload.js',
+        },
+      },
+    },
+  },
+  renderer: {
+    server: {
+      host: 'localhost',
+      port: 5174,
+      strictPort: true,
+      watch: {
+        ignored: ['**/release/**'],
+      },
+    },
+    build: {
+      outDir: 'dist/renderer',
+      rollupOptions: {
+        input: {
+          index: resolve(__dirname, 'src/renderer/index.html'),
+        },
+      },
+    },
+  },
+};