@cubis/foundry 0.3.83 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/electron-qa/examples/02-packaging-validation.md

@@ -1,359 +0,0 @@
-# Example: Packaging Validation for Cross-Platform Electron App
-
-This example demonstrates validating packaged Electron binaries across macOS, Windows, and Linux, including code signing verification, ASAR contents checking, native module inclusion, and installer smoke tests.
-
-## Scenario
-
-A note-taking Electron app built with electron-builder that:
-- Uses better-sqlite3 for local storage
-- Includes custom application icons for all platforms
-- Supports auto-update via electron-updater
-- Targets macOS (DMG), Windows (NSIS installer), and Linux (AppImage)
-
-## electron-builder Configuration
-
-```json
-{
-  "appId": "com.example.notes",
-  "productName": "QuickNotes",
-  "directories": {
-    "output": "dist"
-  },
-  "files": [
-    "build/**/*",
-    "node_modules/**/*",
-    "package.json"
-  ],
-  "asarUnpack": [
-    "node_modules/better-sqlite3/**/*"
-  ],
-  "mac": {
-    "category": "public.app-category.productivity",
-    "target": ["dmg"],
-    "icon": "assets/icon.icns",
-    "hardenedRuntime": true,
-    "entitlements": "build/entitlements.mac.plist",
-    "entitlementsInherit": "build/entitlements.mac.plist"
-  },
-  "win": {
-    "target": ["nsis"],
-    "icon": "assets/icon.ico",
-    "signingHashAlgorithms": ["sha256"]
-  },
-  "linux": {
-    "target": ["AppImage"],
-    "icon": "assets/icon.png",
-    "category": "Office"
-  },
-  "publish": {
-    "provider": "github",
-    "owner": "example",
-    "repo": "quick-notes"
-  }
-}
-```
-
-## Packaging Validation Script
-
-```typescript
-// scripts/validate-package.ts
-import * as fs from 'fs';
-import * as path from 'path';
-import { execSync } from 'child_process';
-import * as asar from '@electron/asar';
-
-const DIST_DIR = path.resolve(__dirname, '../dist');
-const platform = process.platform;
-
-interface ValidationResult {
-  check: string;
-  passed: boolean;
-  details: string;
-}
-
-const results: ValidationResult[] = [];
-
-function check(name: string, fn: () => string) {
-  try {
-    const details = fn();
-    results.push({ check: name, passed: true, details });
-  } catch (error: any) {
-    results.push({ check: name, passed: false, details: error.message });
-  }
-}
-
-// --- Cross-platform checks ---
-
-check('ASAR archive exists', () => {
-  const asarPaths = {
-    darwin: 'mac/QuickNotes.app/Contents/Resources/app.asar',
-    win32: 'win-unpacked/resources/app.asar',
-    linux: 'linux-unpacked/resources/app.asar',
-  };
-  const asarPath = path.join(DIST_DIR, asarPaths[platform as keyof typeof asarPaths]);
-  if (!fs.existsSync(asarPath)) throw new Error(`ASAR not found at ${asarPath}`);
-  return `Found at ${asarPath}`;
-});
-
-check('ASAR contains main process entry', () => {
-  const asarPaths = {
-    darwin: 'mac/QuickNotes.app/Contents/Resources/app.asar',
-    win32: 'win-unpacked/resources/app.asar',
-    linux: 'linux-unpacked/resources/app.asar',
-  };
-  const asarPath = path.join(DIST_DIR, asarPaths[platform as keyof typeof asarPaths]);
-  const listing = asar.listPackage(asarPath);
-  if (!listing.includes('/build/main/index.js')) {
-    throw new Error('Main process entry point missing from ASAR');
-  }
-  return `ASAR contains ${listing.length} files including main entry`;
-});
-
-check('ASAR contains preload script', () => {
-  const asarPaths = {
-    darwin: 'mac/QuickNotes.app/Contents/Resources/app.asar',
-    win32: 'win-unpacked/resources/app.asar',
-    linux: 'linux-unpacked/resources/app.asar',
-  };
-  const asarPath = path.join(DIST_DIR, asarPaths[platform as keyof typeof asarPaths]);
-  const listing = asar.listPackage(asarPath);
-  if (!listing.includes('/build/preload/preload.js')) {
-    throw new Error('Preload script missing from ASAR');
-  }
-  return 'Preload script present in ASAR';
-});
-
-check('Native module unpacked (better-sqlite3)', () => {
-  const unpackedPaths = {
-    darwin: 'mac/QuickNotes.app/Contents/Resources/app.asar.unpacked/node_modules/better-sqlite3',
-    win32: 'win-unpacked/resources/app.asar.unpacked/node_modules/better-sqlite3',
-    linux: 'linux-unpacked/resources/app.asar.unpacked/node_modules/better-sqlite3',
-  };
-  const nativePath = path.join(DIST_DIR, unpackedPaths[platform as keyof typeof unpackedPaths]);
-  if (!fs.existsSync(nativePath)) {
-    throw new Error('better-sqlite3 not found in unpacked directory');
-  }
-  // Check for the .node binary
-  const bindingDir = path.join(nativePath, 'build', 'Release');
-  if (!fs.existsSync(bindingDir)) {
-    throw new Error('Native binding directory missing');
-  }
-  return `Native module found at ${nativePath}`;
-});
-
-// --- macOS-specific checks ---
-
-if (platform === 'darwin') {
-  check('macOS code signing', () => {
-    const appPath = path.join(DIST_DIR, 'mac/QuickNotes.app');
-    const output = execSync(`codesign --verify --deep --strict "${appPath}" 2>&1`, {
-      encoding: 'utf-8',
-    });
-    return output || 'Code signature valid';
-  });
-
-  check('macOS icon (.icns)', () => {
-    const iconPath = path.join(DIST_DIR, 'mac/QuickNotes.app/Contents/Resources/icon.icns');
-    if (!fs.existsSync(iconPath)) throw new Error('App icon not found');
-    const stat = fs.statSync(iconPath);
-    if (stat.size < 1000) throw new Error('Icon file suspiciously small');
-    return `Icon present (${stat.size} bytes)`;
-  });
-
-  check('macOS app bundle structure', () => {
-    const requiredPaths = [
-      'Contents/MacOS/QuickNotes',
-      'Contents/Resources/app.asar',
-      'Contents/Info.plist',
-      'Contents/Frameworks/Electron Framework.framework',
-    ];
-    const appBase = path.join(DIST_DIR, 'mac/QuickNotes.app');
-    for (const p of requiredPaths) {
-      if (!fs.existsSync(path.join(appBase, p))) {
-        throw new Error(`Missing: ${p}`);
-      }
-    }
-    return 'All required bundle paths present';
-  });
-
-  check('DMG artifact exists', () => {
-    const files = fs.readdirSync(DIST_DIR).filter((f) => f.endsWith('.dmg'));
-    if (files.length === 0) throw new Error('No DMG file found in dist/');
-    return `Found: ${files.join(', ')}`;
-  });
-}
-
-// --- Windows-specific checks ---
-
-if (platform === 'win32') {
-  check('Windows installer exists', () => {
-    const files = fs.readdirSync(DIST_DIR).filter((f) => f.endsWith('.exe'));
-    if (files.length === 0) throw new Error('No installer EXE found in dist/');
-    return `Found: ${files.join(', ')}`;
-  });
-
-  check('Windows icon (.ico)', () => {
-    const iconPath = path.join(DIST_DIR, 'win-unpacked/resources/icon.ico');
-    if (!fs.existsSync(iconPath)) {
-      // electron-builder may embed the icon differently
-      const exePath = path.join(DIST_DIR, 'win-unpacked/QuickNotes.exe');
-      if (!fs.existsSync(exePath)) throw new Error('Neither icon nor exe found');
-      return 'Icon embedded in executable';
-    }
-    return 'Icon file present';
-  });
-}
-
-// --- Linux-specific checks ---
-
-if (platform === 'linux') {
-  check('AppImage artifact exists', () => {
-    const files = fs.readdirSync(DIST_DIR).filter((f) => f.endsWith('.AppImage'));
-    if (files.length === 0) throw new Error('No AppImage found in dist/');
-    return `Found: ${files.join(', ')}`;
-  });
-
-  check('AppImage is executable', () => {
-    const files = fs.readdirSync(DIST_DIR).filter((f) => f.endsWith('.AppImage'));
-    const appImage = path.join(DIST_DIR, files[0]);
-    const stat = fs.statSync(appImage);
-    const isExecutable = (stat.mode & 0o111) !== 0;
-    if (!isExecutable) throw new Error('AppImage is not executable');
-    return `${files[0]} has execute permission`;
-  });
-
-  check('Linux icon present', () => {
-    const iconPath = path.join(DIST_DIR, 'linux-unpacked/resources/icon.png');
-    if (!fs.existsSync(iconPath)) throw new Error('Icon not found');
-    return 'Linux icon present';
-  });
-}
-
-// --- Report ---
-
-console.log('\n=== Packaging Validation Report ===\n');
-let passed = 0;
-let failed = 0;
-
-for (const r of results) {
-  const status = r.passed ? 'PASS' : 'FAIL';
-  console.log(`[${status}] ${r.check}`);
-  console.log(`       ${r.details}\n`);
-  if (r.passed) passed++;
-  else failed++;
-}
-
-console.log(`\nTotal: ${passed} passed, ${failed} failed out of ${results.length} checks`);
-process.exit(failed > 0 ? 1 : 0);
-```
-
-## Auto-Update Mock Test
-
-```typescript
-// tests/e2e/auto-update.spec.ts
-import { test, expect, _electron as electron } from '@playwright/test';
-import * as http from 'http';
-import * as path from 'path';
-
-let mockUpdateServer: http.Server;
-
-test.beforeAll(async () => {
-  // Start a mock update server
-  mockUpdateServer = http.createServer((req, res) => {
-    if (req.url?.includes('/update/')) {
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({
-        version: '99.0.0',
-        releaseDate: '2025-01-01',
-        url: 'http://localhost:9999/download/update.zip',
-        sha512: 'abc123',
-      }));
-    } else {
-      res.writeHead(404);
-      res.end();
-    }
-  });
-  mockUpdateServer.listen(9999);
-});
-
-test.afterAll(async () => {
-  mockUpdateServer.close();
-});
-
-test('detects available update from mock server', async () => {
-  const app = await electron.launch({
-    args: [path.join(__dirname, '../../main/index.js')],
-    env: {
-      ...process.env,
-      ELECTRON_UPDATE_URL: 'http://localhost:9999/update',
-      NODE_ENV: 'test',
-    },
-  });
-
-  const page = await app.firstWindow();
-
-  // Trigger update check via the UI
-  await page.getByRole('menuitem', { name: 'Check for Updates' }).click();
-
-  // Verify the update notification appears
-  await expect(page.getByText('Update available: v99.0.0')).toBeVisible({
-    timeout: 10000,
-  });
-
-  await app.close();
-});
-```
-
-## CI Integration
-
-```yaml
-# .github/workflows/package-validation.yml
-name: Package Validation
-on: [push, pull_request]
-
-jobs:
-  validate-macos:
-    runs-on: macos-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: 20 }
-      - run: npm ci
-      - run: npm run build
-      - run: npx electron-builder --mac
-      - run: npx ts-node scripts/validate-package.ts
-      - uses: actions/upload-artifact@v4
-        with:
-          name: macos-dmg
-          path: dist/*.dmg
-
-  validate-windows:
-    runs-on: windows-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: 20 }
-      - run: npm ci
-      - run: npm run build
-      - run: npx electron-builder --win
-      - run: npx ts-node scripts/validate-package.ts
-
-  validate-linux:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: 20 }
-      - run: npm ci
-      - run: npm run build
-      - run: npx electron-builder --linux
-      - run: npx ts-node scripts/validate-package.ts
-```
-
-## Key Takeaways
-
-- ASAR verification catches files excluded by packaging configuration before users encounter missing-file errors
-- Native modules must be unpacked from the ASAR (via `asarUnpack`) because they contain platform-specific binaries
-- Code signing verification is platform-specific: `codesign` on macOS, Authenticode on Windows
-- Auto-update testing with a mock server verifies the full lifecycle without network dependencies
-- Run packaging validation on all three platforms in CI to catch platform-specific failures

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/electron-qa/references/ci-setup.md

@@ -1,327 +0,0 @@
-# CI Setup
-
-Load this reference when configuring CI pipelines for Electron builds, cross-platform testing, or artifact publishing.
-
-## CI Requirements for Electron
-
-Electron CI pipelines are more demanding than typical web app pipelines:
-
-| Requirement | Why | Impact |
-| --- | --- | --- |
-| Display server (Linux) | Chromium needs a display to render | Xvfb or virtual framebuffer |
-| Large disk space | Electron + Chromium binary is 150-200 MB | 2-4 GB free disk minimum |
-| Sufficient RAM | Chromium renderer + Node.js main process | 4 GB minimum, 8 GB recommended |
-| Native build tools | Native modules need compilation | Xcode, Visual Studio Build Tools, build-essential |
-| Code signing certs | macOS notarization, Windows Authenticode | Stored as CI secrets |
-| Platform runners | Must build on target OS | macOS, Windows, Linux runners |
-
-## GitHub Actions — Complete Pipeline
-
-```yaml
-name: Electron CI
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-env:
-  NODE_VERSION: 20
-
-jobs:
-  # Job 1: Lint and unit tests (fast, no Electron)
-  lint-and-unit:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-          cache: 'npm'
-      - run: npm ci
-      - run: npm run lint
-      - run: npm run test:unit
-
-  # Job 2: E2E tests on each platform
-  e2e-tests:
-    needs: lint-and-unit
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [macos-latest, windows-latest, ubuntu-latest]
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Rebuild native modules
-        run: npx electron-rebuild
-
-      - name: Run E2E tests (Linux)
-        if: runner.os == 'Linux'
-        run: xvfb-run --auto-servernum npx playwright test
-        env:
-          DISPLAY: ':99'
-
-      - name: Run E2E tests (macOS/Windows)
-        if: runner.os != 'Linux'
-        run: npx playwright test
-
-      - name: Upload test results
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: test-results-${{ matrix.os }}
-          path: |
-            playwright-report/
-            test-results/
-
-  # Job 3: Build and package
-  package:
-    needs: e2e-tests
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - os: macos-latest
-            build-args: --mac
-            artifact-name: macos-build
-            artifact-path: dist/*.dmg
-          - os: windows-latest
-            build-args: --win
-            artifact-name: windows-build
-            artifact-path: dist/*.exe
-          - os: ubuntu-latest
-            build-args: --linux
-            artifact-name: linux-build
-            artifact-path: dist/*.AppImage
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Build application
-        run: npm run build
-
-      - name: Package application
-        run: npx electron-builder ${{ matrix.build-args }}
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          CSC_LINK: ${{ secrets.MAC_CERTIFICATE }}
-          CSC_KEY_PASSWORD: ${{ secrets.MAC_CERTIFICATE_PASSWORD }}
-          APPLE_ID: ${{ secrets.APPLE_ID }}
-          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
-
-      - name: Validate package
-        run: npx ts-node scripts/validate-package.ts
-
-      - name: Upload artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: ${{ matrix.artifact-name }}
-          path: ${{ matrix.artifact-path }}
-          retention-days: 30
-```
-
-## Linux Display Server (Xvfb)
-
-Chromium requires a display server to render. On headless Linux CI, use Xvfb:
-
-```bash
-# Install
-sudo apt-get install -y xvfb
-
-# Run tests with Xvfb
-xvfb-run --auto-servernum --server-args="-screen 0 1280x720x24" npx playwright test
-```
-
-### Alternative: Use a Docker image with Xvfb
-
-```dockerfile
-FROM node:20-bullseye
-
-RUN apt-get update && apt-get install -y \
-  xvfb \
-  libgtk-3-0 \
-  libnotify-dev \
-  libgconf-2-4 \
-  libnss3 \
-  libxss1 \
-  libasound2 \
-  libxtst6 \
-  libatk-bridge2.0-0 \
-  libdrm2 \
-  libgbm1
-
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci
-COPY . .
-
-CMD ["xvfb-run", "--auto-servernum", "npm", "test"]
-```
-
-## Native Module Compilation in CI
-
-### macOS
-
-macOS runners include Xcode by default. No additional setup needed.
-
-### Windows
-
-Windows runners need Visual Studio Build Tools:
-
-```yaml
-- name: Install Windows Build Tools
-  if: runner.os == 'Windows'
-  run: npm install -g windows-build-tools
-```
-
-Or use the pre-installed tools on GitHub Actions `windows-latest` runners.
-
-### Linux
-
-```yaml
-- name: Install Linux build dependencies
-  if: runner.os == 'Linux'
-  run: |
-    sudo apt-get update
-    sudo apt-get install -y \
-      build-essential \
-      libx11-dev \
-      libxkbfile-dev \
-      libsecret-1-dev \
-      python3
-```
-
-## Code Signing in CI
-
-### macOS signing secrets
-
-Store these as GitHub Actions secrets:
-
-| Secret | Contents |
-| --- | --- |
-| `MAC_CERTIFICATE` | Base64-encoded .p12 certificate file |
-| `MAC_CERTIFICATE_PASSWORD` | Password for the .p12 file |
-| `APPLE_ID` | Apple Developer account email |
-| `APPLE_APP_SPECIFIC_PASSWORD` | App-specific password for notarization |
-| `APPLE_TEAM_ID` | Apple Developer team ID |
-
-#### Encoding the certificate
-
-```bash
-base64 -i Certificates.p12 | pbcopy
-# Paste into GitHub secret MAC_CERTIFICATE
-```
-
-### Windows signing secrets
-
-| Secret | Contents |
-| --- | --- |
-| `WIN_CERTIFICATE` | Base64-encoded .pfx certificate |
-| `WIN_CERTIFICATE_PASSWORD` | Password for the .pfx file |
-
-## Caching Strategies
-
-### npm cache
-
-```yaml
-- uses: actions/setup-node@v4
-  with:
-    node-version: 20
-    cache: 'npm'
-```
-
-### Electron binary cache
-
-Electron downloads a large binary on first install. Cache it:
-
-```yaml
-- name: Cache Electron
-  uses: actions/cache@v4
-  with:
-    path: ~/.cache/electron
-    key: electron-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
-```
-
-### electron-builder cache
-
-```yaml
-- name: Cache electron-builder
-  uses: actions/cache@v4
-  with:
-    path: ~/.cache/electron-builder
-    key: electron-builder-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
-```
-
-## Release Pipeline
-
-Publish builds when a git tag is pushed:
-
-```yaml
-on:
-  push:
-    tags:
-      - 'v*'
-
-jobs:
-  release:
-    strategy:
-      matrix:
-        os: [macos-latest, windows-latest, ubuntu-latest]
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: 20 }
-      - run: npm ci
-      - run: npm run build
-
-      - name: Publish
-        run: npx electron-builder --publish always
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          CSC_LINK: ${{ secrets.MAC_CERTIFICATE }}
-          CSC_KEY_PASSWORD: ${{ secrets.MAC_CERTIFICATE_PASSWORD }}
-```
-
-This creates a GitHub Release with the packaged artifacts attached.
-
-## Troubleshooting CI
-
-| Issue | Platform | Fix |
-| --- | --- | --- |
-| `cannot open display` | Linux | Add `xvfb-run` wrapper |
-| `Error: ENOMEM` | All | Increase runner memory or reduce workers |
-| `Timeout waiting for Electron` | All | Increase `timeout` in playwright.config.ts |
-| Native module build fails | Windows | Install windows-build-tools |
-| Code signing fails | macOS | Verify certificate is not expired, check team ID |
-| AppImage not executable | Linux | Add `chmod +x` step after build |
-| ASAR missing files | All | Check `files` glob in electron-builder config |
-| Disk space exhausted | All | Clean caches before build, use larger runner |
-
-## Pipeline Duration Targets
-
-| Stage | Target | Notes |
-| --- | --- | --- |
-| Install + rebuild | < 3 min | With caching |
-| Unit tests | < 2 min | No Electron needed |
-| E2E tests | < 5 min | Per platform |
-| Package build | < 5 min | Per platform |
-| Code signing + notarization | < 5 min | macOS is slowest |
-| Total pipeline | < 20 min | All platforms parallel |
-
-If total pipeline exceeds 20 minutes, investigate caching, test parallelism, and build optimization.