@cubis/foundry 0.3.82 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/electron-qa/references/native-modules.md

@@ -1,310 +0,0 @@
-# Native Modules
-
-Load this reference when validating native Node.js modules, rebuilding for Electron's Node.js ABI, or debugging native module crashes.
-
-## The ABI Problem
-
-Native Node.js modules (`.node` files) are compiled C/C++ addons linked against a specific Node.js ABI version. Electron bundles its own version of Node.js, which may have a different ABI than the system Node.js. If the ABIs do not match, the module crashes on load with an error like:
-
-```
-Error: The module 'better-sqlite3.node' was compiled against a different Node.js version
-using NODE_MODULE_VERSION 108. This version of Node.js requires NODE_MODULE_VERSION 116.
-```
-
-## Rebuilding Native Modules
-
-### Using electron-rebuild (recommended)
-
-```bash
-# Install
-npm install -D @electron/rebuild
-
-# Rebuild all native modules for the current Electron version
-npx electron-rebuild
-
-# Rebuild a specific module
-npx electron-rebuild -m node_modules/better-sqlite3
-
-# Specify Electron version explicitly
-npx electron-rebuild -v 28.1.0
-```
-
-### Using node-gyp manually
-
-```bash
-# Set the target to Electron's Node.js version
-export npm_config_target=28.1.0
-export npm_config_arch=x64
-export npm_config_disturl=https://electronjs.org/headers
-export npm_config_runtime=electron
-export npm_config_build_from_source=true
-
-npm install better-sqlite3
-```
-
-### In package.json scripts
-
-```json
-{
-  "scripts": {
-    "postinstall": "electron-rebuild",
-    "rebuild": "electron-rebuild -f"
-  }
-}
-```
-
-## Common Native Modules in Electron
-
-| Module | Purpose | Special handling |
-| --- | --- | --- |
-| `better-sqlite3` | SQLite database | Must unpack from ASAR |
-| `node-pty` | Terminal emulation | Platform-specific build |
-| `sharp` | Image processing | Large binary, consider prebuilt |
-| `keytar` | OS keychain access | Requires system keychain headers |
-| `node-hid` | USB HID devices | Requires libusb on Linux |
-| `serialport` | Serial port access | Platform-specific drivers |
-| `fsevents` | macOS file watching | macOS only, skip on other platforms |
-
-## ASAR Unpacking
-
-Native modules contain platform-specific binary files that cannot be loaded from inside an ASAR archive. They must be unpacked.
-
-### electron-builder configuration
-
-```json
-{
-  "asarUnpack": [
-    "node_modules/better-sqlite3/**/*",
-    "node_modules/node-pty/**/*",
-    "node_modules/sharp/**/*"
-  ]
-}
-```
-
-### electron-forge configuration
-
-```javascript
-// forge.config.js
-module.exports = {
-  packagerConfig: {
-    asar: {
-      unpack: '{node_modules/better-sqlite3/**/*,node_modules/sharp/**/*}',
-    },
-  },
-};
-```
-
-### Verifying unpacked modules
-
-```typescript
-import * as fs from 'fs';
-import * as path from 'path';
-
-function verifyUnpacked(appDir: string, moduleName: string): boolean {
-  const unpackedPath = path.join(appDir, 'resources', 'app.asar.unpacked', 'node_modules', moduleName);
-  return fs.existsSync(unpackedPath);
-}
-```
-
-## Testing Native Modules
-
-### Unit tests with mocking
-
-For CI environments without native build tools, mock native modules:
-
-```typescript
-// tests/unit/database.test.ts
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-
-// Mock better-sqlite3
-vi.mock('better-sqlite3', () => {
-  return {
-    default: vi.fn().mockImplementation((dbPath: string) => ({
-      prepare: vi.fn().mockReturnValue({
-        all: vi.fn().mockReturnValue([{ id: 1, title: 'Test' }]),
-        run: vi.fn().mockReturnValue({ changes: 1 }),
-        get: vi.fn().mockReturnValue({ id: 1, title: 'Test' }),
-      }),
-      exec: vi.fn(),
-      close: vi.fn(),
-      pragma: vi.fn(),
-    })),
-  };
-});
-
-import { DatabaseService } from '../../main/database';
-
-describe('DatabaseService', () => {
-  let db: DatabaseService;
-
-  beforeEach(() => {
-    db = new DatabaseService(':memory:');
-  });
-
-  it('queries notes', () => {
-    const notes = db.getAllNotes();
-    expect(notes).toHaveLength(1);
-    expect(notes[0].title).toBe('Test');
-  });
-});
-```
-
-### Integration tests with real native modules
-
-For environments with native build tools, test the actual module:
-
-```typescript
-// tests/integration/native-sqlite.test.ts
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import Database from 'better-sqlite3';
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-
-describe('better-sqlite3 native module', () => {
-  const dbPath = path.join(os.tmpdir(), 'test-native.db');
-  let db: Database.Database;
-
-  beforeAll(() => {
-    db = new Database(dbPath);
-  });
-
-  afterAll(() => {
-    db.close();
-    fs.unlinkSync(dbPath);
-  });
-
-  it('loads without ABI error', () => {
-    expect(db).toBeDefined();
-  });
-
-  it('creates tables and inserts data', () => {
-    db.exec('CREATE TABLE IF NOT EXISTS test (id INTEGER PRIMARY KEY, value TEXT)');
-    const insert = db.prepare('INSERT INTO test (value) VALUES (?)');
-    const result = insert.run('hello');
-    expect(result.changes).toBe(1);
-  });
-
-  it('queries data correctly', () => {
-    const row = db.prepare('SELECT value FROM test WHERE id = 1').get() as any;
-    expect(row.value).toBe('hello');
-  });
-
-  it('handles concurrent access', () => {
-    db.pragma('journal_mode = WAL');
-    const insert = db.prepare('INSERT INTO test (value) VALUES (?)');
-    const transaction = db.transaction((values: string[]) => {
-      for (const v of values) insert.run(v);
-    });
-    transaction(['a', 'b', 'c']);
-    const count = (db.prepare('SELECT COUNT(*) as n FROM test').get() as any).n;
-    expect(count).toBe(4); // 1 from earlier + 3 from transaction
-  });
-});
-```
-
-### E2E native module verification
-
-In the packaged app, verify the native module loads correctly:
-
-```typescript
-// tests/e2e/native-module.spec.ts
-import { test, expect, _electron as electron } from '@playwright/test';
-import * as path from 'path';
-
-test('better-sqlite3 loads in packaged app', async () => {
-  const app = await electron.launch({
-    args: [path.join(__dirname, '../../main/index.js')],
-  });
-
-  // Verify from the main process
-  const canLoadSqlite = await app.evaluate(() => {
-    try {
-      const Database = require('better-sqlite3');
-      const db = new Database(':memory:');
-      db.exec('SELECT 1');
-      db.close();
-      return true;
-    } catch (e) {
-      return false;
-    }
-  });
-
-  expect(canLoadSqlite).toBe(true);
-  await app.close();
-});
-```
-
-## Cross-Platform Compilation
-
-### Platform-specific builds in CI
-
-```yaml
-# .github/workflows/native-modules.yml
-jobs:
-  build:
-    strategy:
-      matrix:
-        os: [macos-latest, windows-latest, ubuntu-latest]
-        arch: [x64, arm64]
-        exclude:
-          - os: windows-latest
-            arch: arm64
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: 20 }
-      - run: npm ci
-      - run: npx electron-rebuild
-      - run: npm test
-```
-
-### Prebuild binaries
-
-Use `prebuild` or `prebuild-install` to distribute precompiled binaries:
-
-```json
-{
-  "scripts": {
-    "install": "prebuild-install -r electron || node-gyp rebuild"
-  }
-}
-```
-
-This downloads prebuilt binaries when available and falls back to compilation when they are not.
-
-## Debugging Native Module Failures
-
-| Error | Cause | Fix |
-| --- | --- | --- |
-| `NODE_MODULE_VERSION mismatch` | Compiled for wrong Node ABI | Run `electron-rebuild` |
-| `Cannot find module *.node` | Module inside ASAR archive | Add to `asarUnpack` |
-| `GLIBC not found` | Linux binary built on newer glibc | Build on older distro (Ubuntu 20.04) |
-| `dyld: Library not loaded` | Missing macOS framework dependency | Install Xcode Command Line Tools |
-| `The specified module could not be found` | Missing Windows DLL dependency | Install Visual C++ Redistributable |
-| `Error: dlopen failed` | Architecture mismatch (x64 vs arm64) | Rebuild for correct architecture |
-
-## Version Compatibility Matrix
-
-Keep these versions synchronized:
-
-```
-Electron version ─── determines ──→ Chromium version
-       │                                     │
-       └── determines ──→ Node.js ABI  ──→ Native module binary
-```
-
-Check your Electron's Node version:
-
-```bash
-npx electron -e "console.log(process.versions)"
-```
-
-Check the ABI version:
-
-```bash
-npx electron -e "console.log(process.versions.modules)"
-```
-
-Rebuild native modules every time you upgrade Electron.

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/electron-qa/references/packaging.md

@@ -1,315 +0,0 @@
-# Packaging
-
-Load this reference when building installers, verifying packaged applications, validating code signing, or testing auto-update flows.
-
-## Packaging Tools
-
-### electron-builder (recommended)
-
-The most widely used Electron packaging tool. Supports all platforms, auto-update, and code signing.
-
-```bash
-npm install -D electron-builder
-```
-
-### electron-forge
-
-Electron's official tooling. Better integration with Electron's ecosystem but fewer packaging options.
-
-```bash
-npm install -D @electron-forge/cli
-```
-
-### Comparison
-
-| Feature | electron-builder | electron-forge |
-| --- | --- | --- |
-| macOS DMG | Yes | Yes |
-| macOS PKG | Yes | Yes |
-| Windows NSIS | Yes | No (uses Squirrel) |
-| Windows MSI | Yes (via WiX) | No |
-| Linux AppImage | Yes | No |
-| Linux Snap | Yes | Yes |
-| Linux deb/rpm | Yes | Yes |
-| Auto-update | electron-updater | Built-in |
-| Code signing | Built-in | Built-in |
-| ASAR packing | Yes | Yes |
-
-## electron-builder Configuration
-
-```json
-{
-  "build": {
-    "appId": "com.example.myapp",
-    "productName": "MyApp",
-    "directories": {
-      "buildResources": "build",
-      "output": "dist"
-    },
-    "files": [
-      "build/**/*",
-      "node_modules/**/*",
-      "package.json"
-    ],
-    "asarUnpack": [
-      "node_modules/better-sqlite3/**/*"
-    ],
-    "mac": {
-      "category": "public.app-category.productivity",
-      "target": ["dmg", "zip"],
-      "icon": "build/icon.icns",
-      "hardenedRuntime": true,
-      "gatekeeperAssess": false,
-      "entitlements": "build/entitlements.mac.plist",
-      "entitlementsInherit": "build/entitlements.mac.plist"
-    },
-    "win": {
-      "target": ["nsis"],
-      "icon": "build/icon.ico"
-    },
-    "nsis": {
-      "oneClick": false,
-      "allowToChangeInstallationDirectory": true,
-      "createDesktopShortcut": true,
-      "createStartMenuShortcut": true
-    },
-    "linux": {
-      "target": ["AppImage", "deb"],
-      "icon": "build/icons",
-      "category": "Office"
-    },
-    "publish": {
-      "provider": "github",
-      "owner": "your-org",
-      "repo": "your-app"
-    }
-  }
-}
-```
-
-## Building
-
-```bash
-# Build for current platform
-npx electron-builder
-
-# Build for specific platform
-npx electron-builder --mac
-npx electron-builder --win
-npx electron-builder --linux
-
-# Build all platforms (macOS only — cross-compilation)
-npx electron-builder -mwl
-```
-
-Cross-compilation:
-- macOS can build for macOS, Windows, and Linux
-- Windows can build for Windows only
-- Linux can build for Linux and Windows (with Wine)
-
-## Code Signing
-
-### macOS
-
-macOS requires code signing and notarization for distribution outside the App Store.
-
-#### Prerequisites
-- Apple Developer account ($99/year)
-- Developer ID Application certificate
-- Developer ID Installer certificate (for PKG)
-
-#### Configuration
-
-```json
-{
-  "mac": {
-    "hardenedRuntime": true,
-    "gatekeeperAssess": false,
-    "entitlements": "build/entitlements.mac.plist",
-    "entitlementsInherit": "build/entitlements.mac.plist"
-  },
-  "afterSign": "scripts/notarize.js"
-}
-```
-
-#### Entitlements
-
-```xml
-<!-- build/entitlements.mac.plist -->
-<?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>com.apple.security.cs.allow-jit</key>
-  <true/>
-  <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
-  <true/>
-  <key>com.apple.security.cs.allow-dyld-environment-variables</key>
-  <true/>
-</dict>
-</plist>
-```
-
-#### Verification
-
-```bash
-# Verify code signature
-codesign --verify --deep --strict /path/to/MyApp.app
-
-# Check notarization
-spctl --assess --verbose /path/to/MyApp.app
-
-# Verify DMG signature
-codesign --verify /path/to/MyApp.dmg
-```
-
-### Windows
-
-Windows uses Authenticode code signing.
-
-#### Prerequisites
-- Code signing certificate (EV or standard)
-- SignTool.exe (part of Windows SDK)
-
-#### Configuration (CI environment variables)
-
-```bash
-CSC_LINK=path/to/certificate.pfx
-CSC_KEY_PASSWORD=certificate-password
-```
-
-#### Verification
-
-```powershell
-# Verify Authenticode signature
-Get-AuthenticodeSignature -FilePath "dist\MyApp Setup.exe"
-```
-
-## ASAR Verification
-
-The ASAR archive contains your application source code. Verify its contents after packaging.
-
-```typescript
-import * as asar from '@electron/asar';
-
-function verifyAsar(asarPath: string, requiredFiles: string[]): string[] {
-  const listing = asar.listPackage(asarPath);
-  const missing: string[] = [];
-
-  for (const file of requiredFiles) {
-    if (!listing.includes(file)) {
-      missing.push(file);
-    }
-  }
-
-  return missing;
-}
-
-// Usage
-const missing = verifyAsar('dist/mac/MyApp.app/Contents/Resources/app.asar', [
-  '/package.json',
-  '/build/main/index.js',
-  '/build/preload/preload.js',
-  '/build/renderer/index.html',
-]);
-
-if (missing.length > 0) {
-  console.error('Missing files in ASAR:', missing);
-  process.exit(1);
-}
-```
-
-## Auto-Update
-
-### electron-updater setup
-
-```typescript
-// main/updater.ts
-import { autoUpdater } from 'electron-updater';
-import { BrowserWindow } from 'electron';
-
-export function setupAutoUpdate(mainWindow: BrowserWindow) {
-  autoUpdater.autoDownload = false;
-  autoUpdater.autoInstallOnAppQuit = true;
-
-  autoUpdater.on('update-available', (info) => {
-    mainWindow.webContents.send('update:available', info.version);
-  });
-
-  autoUpdater.on('download-progress', (progress) => {
-    mainWindow.webContents.send('update:progress', progress.percent);
-  });
-
-  autoUpdater.on('update-downloaded', (info) => {
-    mainWindow.webContents.send('update:ready', info.version);
-  });
-
-  autoUpdater.on('error', (error) => {
-    mainWindow.webContents.send('update:error', error.message);
-  });
-
-  // Check for updates after app is ready
-  autoUpdater.checkForUpdates();
-}
-```
-
-### Testing auto-update with mock server
-
-```typescript
-import * as http from 'http';
-
-function createMockUpdateServer(port: number, updateInfo: any): http.Server {
-  return http.createServer((req, res) => {
-    if (req.url?.endsWith('/latest.yml') || req.url?.endsWith('/latest-mac.yml')) {
-      res.writeHead(200, { 'Content-Type': 'text/yaml' });
-      res.end(`
-version: ${updateInfo.version}
-releaseDate: ${updateInfo.date}
-files:
-  - url: update-${updateInfo.version}.zip
-    sha512: ${updateInfo.sha512}
-    size: ${updateInfo.size}
-path: update-${updateInfo.version}.zip
-      `);
-    } else {
-      res.writeHead(404);
-      res.end();
-    }
-  }).listen(port);
-}
-```
-
-## Icon Requirements
-
-| Platform | Format | Sizes | File |
-| --- | --- | --- | --- |
-| macOS | .icns | 16, 32, 64, 128, 256, 512, 1024 | `build/icon.icns` |
-| Windows | .ico | 16, 32, 48, 64, 128, 256 | `build/icon.ico` |
-| Linux | .png | 16, 32, 48, 64, 128, 256, 512 | `build/icons/` directory |
-
-Generate all formats from a single 1024x1024 PNG:
-
-```bash
-# macOS
-iconutil -c icns build/icon.iconset
-
-# Windows (requires imagemagick)
-convert icon-1024.png -define icon:auto-resize=256,128,64,48,32,16 icon.ico
-
-# Linux — place PNGs in build/icons/{size}x{size}/
-```
-
-## Packaging Checklist
-
-Before releasing:
-
-- [ ] ASAR contains all required source files
-- [ ] Native modules are unpacked and match the Electron ABI
-- [ ] Application icons are included for all target platforms
-- [ ] Code signing is valid (macOS: codesign + notarization, Windows: Authenticode)
-- [ ] Auto-updater points to the correct update server
-- [ ] Version number in package.json matches the release tag
-- [ ] License file is included in the package
-- [ ] No development dependencies are bundled (check package size)
-- [ ] The packaged app launches without errors on each platform
-- [ ] File associations and protocol handlers are registered correctly

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/expo-app/evals/assertions.md

@@ -1,48 +0,0 @@
-# Expo App Eval Assertions
-
-## Eval 1: EAS Build Configuration
-
-This eval tests EAS Build configuration: defining build profiles for development, preview, and production with proper signing, environment variables, and runtime versioning.
-
-### Assertions
-
-| # | Type     | What it checks                                  | Why it matters                                                                                       |
-|---|----------|-------------------------------------------------|------------------------------------------------------------------------------------------------------|
-| 1 | contains | `eas.json` — Configuration file reference        | All EAS Build configuration lives in eas.json. Without it, `eas build` has no profiles to execute against. |
-| 2 | contains | `developmentClient` — Dev client flag            | Setting developmentClient: true in the development profile builds with expo-dev-client, enabling custom native module support that Expo Go cannot provide. |
-| 3 | contains | `distribution` — Distribution channel            | Each profile needs explicit distribution (internal for dev/preview, store for production) to control who can install the build and how. |
-| 4 | contains | `runtimeVersion` — OTA compatibility versioning  | Runtime versioning ties OTA updates to compatible native binaries. Without it, a JS update targeting a different native version crashes on launch. |
-| 5 | contains | `env` — Per-profile environment variables        | Different environments need different API keys and endpoints. Build-time env injection prevents secrets from being committed to source control. |
-
-### What a passing response looks like
-
-- An `eas.json` file with three profiles: development, preview, production.
-- Development profile with `developmentClient: true`, `distribution: "internal"`, and debug env vars.
-- Preview profile with `distribution: "internal"` or `"store"` for TestFlight/internal track.
-- Production profile with `distribution: "store"` and production API keys.
-- `runtimeVersion` configured with `{ "policy": "fingerprint" }` or `{ "policy": "appVersion" }` in `app.config.js`.
-- Environment variables defined per profile for API_URL, API_KEY, and similar configuration.
-
----
-
-## Eval 2: Push Notification Setup
-
-This eval tests push notification implementation: token registration, permission handling, foreground display, tap handling, and server-side delivery.
-
-### Assertions
-
-| # | Type     | What it checks                                  | Why it matters                                                                                       |
-|---|----------|-------------------------------------------------|------------------------------------------------------------------------------------------------------|
-| 1 | contains | `getExpoPushTokenAsync` — Token acquisition      | The Expo push token is the device identifier required for server-side push delivery. Without it, the server cannot target this device. |
-| 2 | contains | `requestPermissionsAsync` — Permission request   | iOS requires explicit permission and Android 13+ requires POST_NOTIFICATIONS. Skipping permission request causes silent token acquisition failure. |
-| 3 | contains | `setNotificationHandler` — Foreground behavior   | Without a notification handler, notifications received while the app is foregrounded are silently discarded instead of displayed. |
-| 4 | contains | `addNotificationResponseReceivedListener` — Tap handling | Users expect tapping a notification to open the relevant screen. Without a response listener, taps open the app but do not navigate to context. |
-| 5 | contains | `expo.dev/--/api/v2/push/send` — Server delivery | Push notifications must be sent through Expo's push API, which handles APNs/FCM routing. Calling APNs/FCM directly bypasses Expo's token format. |
-
-### What a passing response looks like
-
-- App initialization code that requests permissions, then calls `getExpoPushTokenAsync`.
-- Token sent to the backend API for storage, with handling for token refresh on subsequent launches.
-- `setNotificationHandler` configured with `shouldShowAlert: true` for foreground display.
-- `addNotificationResponseReceivedListener` that extracts navigation data from the notification and uses expo-router to navigate.
-- Server endpoint that POSTs to Expo's push API with the push token, title, body, and optional data payload.