@nockdev/awf 6.2.5 → 6.2.7

package/.agent/skills/cross-cutting/electron/references/ipc-testing.md

@@ -0,0 +1,114 @@
+## 📦 IPC Communication
+
+### Main Process Handlers
+
+```typescript
+// main.ts
+import { ipcMain, dialog, BrowserWindow } from "electron";
+import { z } from "zod";
+
+// ✅ Schema validation
+const SaveFileSchema = z.object({
+  path: z.string(),
+  content: z.string(),
+});
+
+ipcMain.handle("dialog:openFile", async (event) => {
+  const window = BrowserWindow.fromWebContents(event.sender);
+  if (!window) return null;
+
+  const result = await dialog.showOpenDialog(window, {
+    properties: ["openFile"],
+    filters: [{ name: "Text", extensions: ["txt", "md"] }],
+  });
+
+  if (result.canceled) return null;
+  return result.filePaths[0];
+});
+
+ipcMain.handle("file:save", async (event, data: unknown) => {
+  const parsed = SaveFileSchema.safeParse(data);
+  if (!parsed.success) {
+    throw new Error("Invalid data format");
+  }
+  // Save logic with validated data
+  return true;
+});
+```
+
+---
+
+## 🧪 Testing Patterns
+
+### Unit Testing with Vitest
+
+```typescript
+// src/main/__tests__/validators.test.ts
+import { describe, it, expect } from "vitest";
+import { validateFilePath, sanitizeInput } from "../validators";
+
+describe("Input Validation", () => {
+  it("rejects path traversal", () => {
+    expect(validateFilePath("../etc/passwd")).toBe(false);
+    expect(validateFilePath("..\\windows\\system32")).toBe(false);
+  });
+
+  it("accepts valid paths", () => {
+    expect(validateFilePath("/home/user/documents/file.txt")).toBe(true);
+  });
+
+  it("sanitizes HTML input", () => {
+    expect(sanitizeInput("<script>alert(1)</script>")).toBe("");
+  });
+});
+```
+
+### E2E Testing with Playwright
+
+```typescript
+// e2e/app.spec.ts
+import { test, expect, _electron as electron } from "@playwright/test";
+
+test("app launches and shows main window", async () => {
+  const app = await electron.launch({ args: ["./dist/main.js"] });
+  const window = await app.firstWindow();
+
+  await expect(window).toHaveTitle(/MyApp/);
+
+  // Test IPC communication
+  const result = await window.evaluate(() => {
+    return window.electronAPI.getVersion();
+  });
+  expect(result).toMatch(/\d+\.\d+\.\d+/);
+
+  await app.close();
+});
+
+test("file dialog works", async () => {
+  const app = await electron.launch({ args: ["./dist/main.js"] });
+  const window = await app.firstWindow();
+
+  await window.click('button[data-testid="open-file"]');
+  // Dialog opens - mock or handle appropriately
+
+  await app.close();
+});
+```
+
+### Playwright Config
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./e2e",
+  timeout: 30000,
+  use: {
+    trace: "on-first-retry",
+  },
+  projects: [{ name: "electron" }],
+});
+```
+
+---

package/.agent/skills/cross-cutting/electron/references/native-integrations.md

@@ -0,0 +1,216 @@
+## 📦 Native Integrations
+
+### System Tray
+
+```typescript
+// main/tray.ts
+import { Tray, Menu, nativeImage, app, BrowserWindow } from "electron";
+import path from "path";
+
+let tray: Tray | null = null;
+
+export function createTray(mainWindow: BrowserWindow) {
+  const icon = nativeImage.createFromPath(
+    path.join(__dirname, "assets/tray-icon.png"),
+  );
+
+  tray = new Tray(icon);
+  tray.setToolTip("MyApp");
+
+  const contextMenu = Menu.buildFromTemplate([
+    { label: "Show", click: () => mainWindow.show() },
+    { type: "separator" },
+    { label: "Quit", click: () => app.quit() },
+  ]);
+
+  tray.setContextMenu(contextMenu);
+
+  // Click to show window
+  tray.on("click", () => {
+    mainWindow.isVisible() ? mainWindow.hide() : mainWindow.show();
+  });
+}
+```
+
+### Global Shortcuts
+
+```typescript
+// main/shortcuts.ts
+import { globalShortcut, app, BrowserWindow } from "electron";
+
+export function registerGlobalShortcuts(mainWindow: BrowserWindow) {
+  // Register when app is ready
+  app.whenReady().then(() => {
+    globalShortcut.register("CommandOrControl+Shift+X", () => {
+      if (mainWindow.isVisible()) {
+        mainWindow.hide();
+      } else {
+        mainWindow.show();
+        mainWindow.focus();
+      }
+    });
+  });
+
+  // Unregister on quit
+  app.on("will-quit", () => {
+    globalShortcut.unregisterAll();
+  });
+}
+```
+
+### Power Monitor
+
+```typescript
+// main/power.ts
+import { powerMonitor } from "electron";
+
+export function initPowerMonitor() {
+  powerMonitor.on("suspend", () => {
+    console.log("System suspended - saving state");
+    // Save draft, pause sync, etc.
+  });
+
+  powerMonitor.on("resume", () => {
+    console.log("System resumed - checking for updates");
+    // Resume sync, check for updates
+  });
+
+  powerMonitor.on("on-battery", () => {
+    console.log("On battery - reducing background tasks");
+  });
+
+  powerMonitor.on("on-ac", () => {
+    console.log("On AC power - resuming normal operations");
+  });
+}
+```
+
+### Notifications
+
+```typescript
+// main/notifications.ts
+import { Notification } from "electron";
+
+export function showNotification(title: string, body: string) {
+  if (!Notification.isSupported()) return;
+
+  new Notification({
+    title,
+    body,
+    icon: path.join(__dirname, "assets/icon.png"),
+  }).show();
+}
+
+// With actions (macOS)
+export function showActionNotification(title: string, body: string) {
+  const notification = new Notification({
+    title,
+    body,
+    actions: [
+      { text: "View", type: "button" },
+      { text: "Dismiss", type: "button" },
+    ],
+  });
+
+  notification.on("action", (_, index) => {
+    if (index === 0) {
+      // Handle View action
+    }
+  });
+
+  notification.show();
+}
+```
+
+---
+
+## 🔗 Deep Linking
+
+```typescript
+// main.ts
+import { app, BrowserWindow } from "electron";
+
+const PROTOCOL = "my-app";
+
+// Register protocol
+if (process.defaultApp) {
+  app.setAsDefaultProtocolClient(PROTOCOL, process.execPath, [__dirname]);
+} else {
+  app.setAsDefaultProtocolClient(PROTOCOL);
+}
+
+// Single instance lock
+const gotTheLock = app.requestSingleInstanceLock();
+
+if (!gotTheLock) {
+  app.quit();
+} else {
+  app.on("second-instance", (event, argv) => {
+    // Windows/Linux: URL in argv
+    const url = argv.find((arg) => arg.startsWith(`${PROTOCOL}://`));
+    if (url) handleDeepLink(url);
+
+    // Focus window
+    if (mainWindow) {
+      if (mainWindow.isMinimized()) mainWindow.restore();
+      mainWindow.focus();
+    }
+  });
+
+  // macOS: URL via open-url event
+  app.on("open-url", (event, url) => {
+    event.preventDefault();
+    handleDeepLink(url);
+  });
+}
+
+function handleDeepLink(url: string) {
+  const parsed = new URL(url);
+  console.log("Deep link:", parsed.pathname, parsed.searchParams);
+  // Route to appropriate view
+}
+```
+
+---
+
+## 💥 Crash Reporting
+
+### Built-in crashReporter
+
+```typescript
+// main.ts
+import { crashReporter } from "electron";
+
+crashReporter.start({
+  productName: "MyApp",
+  submitURL: "https://your-crash-server.com/submit",
+  uploadToServer: true,
+  extra: {
+    app_version: app.getVersion(),
+    build_type: process.env.NODE_ENV,
+  },
+});
+```
+
+### Sentry Integration
+
+```typescript
+// main.ts
+import * as Sentry from "@sentry/electron/main";
+
+Sentry.init({
+  dsn: "https://your-dsn@sentry.io/project",
+  release: app.getVersion(),
+});
+
+// preload.ts
+import * as Sentry from "@sentry/electron/renderer";
+
+Sentry.init({
+  dsn: "https://your-dsn@sentry.io/project",
+});
+```
+
+---
+
+## ⚡ Performance Optimization

package/.agent/skills/cross-cutting/electron/references/performance-accessibility.md

@@ -0,0 +1,118 @@
+## ⚡ Performance Optimization
+
+### Lazy Window Loading
+
+```typescript
+// main/windows.ts
+let settingsWindow: BrowserWindow | null = null;
+
+export function getSettingsWindow(): BrowserWindow {
+  if (!settingsWindow || settingsWindow.isDestroyed()) {
+    settingsWindow = new BrowserWindow({
+      show: false,
+      webPreferences: { preload: settingsPreload },
+    });
+    settingsWindow.loadFile("settings.html");
+  }
+  return settingsWindow;
+}
+
+// Show when ready
+ipcMain.handle("open-settings", () => {
+  const win = getSettingsWindow();
+  win.once("ready-to-show", () => win.show());
+});
+```
+
+### Worker Threads for Heavy Tasks
+
+```typescript
+// main/workers/heavy-task.ts
+import { Worker, isMainThread, parentPort } from "worker_threads";
+
+if (!isMainThread && parentPort) {
+  parentPort.on("message", (data) => {
+    const result = processHeavyTask(data);
+    parentPort!.postMessage(result);
+  });
+}
+
+// main.ts
+const worker = new Worker("./workers/heavy-task.js");
+worker.postMessage(largeDataset);
+worker.on("message", (result) => {
+  mainWindow.webContents.send("task:complete", result);
+});
+```
+
+---
+
+## ♿ Accessibility
+
+```typescript
+// main.ts
+import { app } from "electron";
+
+// Check if accessibility is enabled
+if (app.accessibilitySupportEnabled) {
+  console.log("Accessibility support enabled");
+}
+
+// Enable programmatically if needed
+app.setAccessibilitySupportEnabled(true);
+
+// Inform renderer about accessibility state
+ipcMain.handle("get-accessibility-state", () => {
+  return app.accessibilitySupportEnabled;
+});
+```
+
+### Renderer Best Practices
+
+```typescript
+// Use semantic HTML and ARIA
+<button
+  aria-label="Open file"
+  aria-keyshortcuts="Ctrl+O"
+  onClick={handleOpen}
+>
+  Open
+</button>
+
+// Focus management
+useEffect(() => {
+  if (isModalOpen) {
+    modalRef.current?.focus();
+  }
+}, [isModalOpen]);
+```
+
+---
+
+## 📦 Project Structure
+
+```
+my-electron-app/
+ src/
+   main/              # Main process
+   index.ts       # Entry point
+   ipc.ts         # IPC handlers
+   tray.ts        # System tray
+   shortcuts.ts   # Global shortcuts
+   updates.ts     # Auto-updater
+   database.ts    # SQLite
+   preload/           # Preload scripts
+   index.ts       # Main preload
+   index.d.ts     # Type declarations
+   renderer/          # Renderer (React/Vue)
+   App.tsx
+   main.tsx
+   e2e/                   # E2E tests
+   app.spec.ts
+   electron.vite.config.ts
+   electron-builder.json5
+ playwright.config.ts
+ package.json
+```
+
+---

package/.agent/skills/cross-cutting/electron/references/updates-persistence.md

@@ -0,0 +1,165 @@
+## 📦 Auto Updates
+
+### electron-updater Setup
+
+```typescript
+// main.ts
+import { autoUpdater } from "electron-updater";
+import { app, dialog, BrowserWindow } from "electron";
+import log from "electron-log";
+
+// Configure logging
+autoUpdater.logger = log;
+autoUpdater.autoDownload = false;
+
+export function initAutoUpdater(mainWindow: BrowserWindow) {
+  // Check for updates on launch
+  autoUpdater.checkForUpdatesAndNotify();
+
+  autoUpdater.on("checking-for-update", () => {
+    log.info("Checking for update...");
+  });
+
+  autoUpdater.on("update-available", (info) => {
+    dialog
+      .showMessageBox(mainWindow, {
+        type: "info",
+        title: "Update Available",
+        message: `Version ${info.version} is available. Download now?`,
+        buttons: ["Download", "Later"],
+      })
+      .then(({ response }) => {
+        if (response === 0) autoUpdater.downloadUpdate();
+      });
+  });
+
+  autoUpdater.on("download-progress", (progress) => {
+    mainWindow.webContents.send("update:progress", progress.percent);
+  });
+
+  autoUpdater.on("update-downloaded", (info) => {
+    dialog
+      .showMessageBox(mainWindow, {
+        type: "info",
+        title: "Update Ready",
+        message: `Version ${info.version} is ready. Restart to apply?`,
+        buttons: ["Restart", "Later"],
+      })
+      .then(({ response }) => {
+        if (response === 0) autoUpdater.quitAndInstall();
+      });
+  });
+
+  autoUpdater.on("error", (err) => {
+    log.error("Auto-update error:", err);
+  });
+}
+```
+
+### Code Signing (macOS)
+
+```bash
+# macOS notarization
+npx electron-builder --mac --publish always
+
+# Required environment variables
+export APPLE_ID="your@email.com"
+export APPLE_APP_SPECIFIC_PASSWORD="xxxx-xxxx-xxxx-xxxx"
+export APPLE_TEAM_ID="XXXXXXXXXX"
+```
+
+---
+
+## 💾 Data Persistence
+
+### better-sqlite3 (Best for Desktop)
+
+```typescript
+// main/database.ts
+import Database from "better-sqlite3";
+import path from "path";
+import { app } from "electron";
+
+const dbPath = path.join(app.getPath("userData"), "app.db");
+const db = new Database(dbPath);
+
+// Enable WAL mode for better concurrent performance
+db.pragma("journal_mode = WAL");
+
+// Initialize schema
+db.exec(`
+  CREATE TABLE IF NOT EXISTS settings (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+  )
+`);
+
+// Type-safe operations
+export const settings = {
+  get: db.prepare("SELECT value FROM settings WHERE key = ?"),
+  set: db.prepare("INSERT OR REPLACE INTO settings (key, value) VALUES (?, ?)"),
+};
+```
+
+### electron-store (Simple Key-Value)
+
+```typescript
+// main/store.ts
+import Store from "electron-store";
+
+interface AppSettings {
+  theme: "light" | "dark" | "system";
+  windowBounds?: { width: number; height: number; x: number; y: number };
+  recentFiles: string[];
+}
+
+const store = new Store<AppSettings>({
+  defaults: {
+    theme: "system",
+    recentFiles: [],
+  },
+  encryptionKey: process.env.STORE_ENCRYPTION_KEY, // Optional
+});
+
+export function getSetting<K extends keyof AppSettings>(
+  key: K,
+): AppSettings[K] {
+  return store.get(key);
+}
+
+export function setSetting<K extends keyof AppSettings>(
+  key: K,
+  value: AppSettings[K],
+) {
+  store.set(key, value);
+}
+```
+
+### safeStorage (Sensitive Data)
+
+```typescript
+// main/secrets.ts
+import { safeStorage } from "electron";
+import fs from "fs";
+import path from "path";
+import { app } from "electron";
+
+const secretsPath = path.join(app.getPath("userData"), "secrets.enc");
+
+export function storeSecret(key: string, value: string) {
+  if (!safeStorage.isEncryptionAvailable()) {
+    throw new Error("Encryption not available");
+  }
+
+  const encrypted = safeStorage.encryptString(`${key}:${value}`);
+  // Append to secrets file or use a database
+  fs.appendFileSync(secretsPath, encrypted);
+}
+
+export function getSecret(key: string): string | null {
+  // Implementation to retrieve and decrypt
+  // ...
+}
+```
+
+---

package/.agent/skills/cross-cutting/seo/META.yaml

@@ -1,5 +1,5 @@
 name: seo
-version: "6.2.5"
+version: "6.2.7"
 display: SEO & Core Web Vitals
 category: cross-cutting
 tier: 1

package/.agent/skills/cross-cutting/skill-creator/META.yaml

@@ -0,0 +1,37 @@
+name: skill-creator
+version: "6.2.7"
+display: Skill Creator
+category: cross-cutting
+tier: 2
+priority: 4
+
+desc: "Meta-skill for creating new domyh-awf skills with proper schema, structure, and progressive disclosure."
+
+trigger_desc: |
+  Activate when user wants to create a new skill, scaffold a skill template,
+  or understand the skill system schema. Guides through META.yaml creation,
+  SKILL.md authoring, and data file organization.
+
+triggers:
+  keywords:
+    - create skill
+    - new skill
+    - skill template
+    - scaffold skill
+    - META.yaml schema
+    - skill structure
+  intents:
+    - "create a new skill"
+    - "make a skill for"
+    - "skill template"
+    - "skill schema reference"
+
+caps:
+  - Skill scaffolding
+  - META.yaml v2 schema
+  - Progressive disclosure patterns
+  - SKILL.md authoring guide
+
+related_skills:
+  - coding-rules
+  - audit-pro