Initial commit without large files

Author: SFARPak

.cursor/rules/ipc.mdc

@@ -0,0 +1,87 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+You're building an Electron app following good security practices
+
+# IPC
+Structure:
+- [ipc_client.ts](mdc:src/ipc/ipc_client.ts) - lives in the renderer process and is used to send IPCs to the main process.
+    - to use it just do `IpcClient.getInstance()`
+- [preload.ts](mdc:src/preload.ts) - allowlist
+- [ipc_host.ts](mdc:src/ipc/ipc_host.ts) - contains the various IPC handlers attached which are: [app_handlers.ts](mdc:src/ipc/handlers/app_handlers.ts), [chat_stream_handlers.ts](mdc:src/ipc/handlers/chat_stream_handlers.ts), [settings_handlers.ts](mdc:src/ipc/handlers/settings_handlers.ts) etc.
+
+# React
+- This is a React app
+- Using TanStack router, NOT next.js, NOT react Router.
+
+
+# IPC & React query patterns
+
+
+Okay, I can help you summarize this pattern for creating a new Cursor rule, focusing on the TanStack Query integration and the preferred error handling strategy.
+
+Here's a summary of the pattern:
+
+The pattern involves a client-side React hook interacting with main process IPC handlers via an `IpcClient` layer, leveraging TanStack Query for managing asynchronous operations, state, and caching.
+
+**1. React Hook (e.g., `useSomething.ts`):**
+
+*   **Data Fetching (`useQuery`):**
+    *   Define a `queryKey` (e.g., `["entity", entityId]`) for caching and invalidation.
+    *   The `queryFn` is an asynchronous function that:
+        *   Retrieves an `IpcClient` instance.
+        *   Calls the appropriate method on `IpcClient` (e.g., `ipcClient.listEntities({ parentId })`). This method corresponds to an IPC channel.
+    *   Use the `enabled` option if the query depends on certain conditions (e.g., `entityId !== null`).
+    *   Optionally provide `initialData` and `meta` (e.g., for global error display like `showErrorToast: true`).
+    *   The hook returns `data`, `isLoading`, `error`, and a `refetch` function from `useQuery`.
+
+*   **Data Mutations (`useMutation`):**
+    *   The `mutationFn` is an asynchronous function that:
+        *   Performs any necessary input validation, potentially throwing an error directly if client-side checks fail (e.g., `if (!entityId) throw new Error("Entity ID is required");`).
+        *   Retrieves an `IpcClient` instance.
+        *   Calls the appropriate method on `IpcClient` (e.g., `ipcClient.createEntity({ data })`).
+    *   `onSuccess`:
+        *   Invalidate relevant queries using `queryClient.invalidateQueries({ queryKey: ["entity"] })` to ensure data consistency and trigger refetches.
+        *   Optionally, update local state directly or refetch specific related data.
+    *   `onError`:
+        *   Handle errors, often by displaying a notification to the user (e.g., using a `showError(error)` utility).
+    *   The hook exposes an asynchronous function (e.g., `createEntity`) that internally calls `mutation.mutateAsync(params)`.
+
+*   **Local State Management (Optional, e.g., Jotai):**
+    *   `useEffect` can synchronize data fetched by TanStack Query with global state atoms if needed.
+    *   Atoms can also store UI-related state or parameters for hooks.
+
+**2. IPC Client (`ipc_client.ts`):**
+
+*   Acts as an intermediary between the renderer process (React hooks) and the main process (IPC handlers).
+*   For each IPC channel, it has a corresponding asynchronous method (e.g., `async listEntities(params) { return this.ipcRenderer.invoke("list-entities", params); }`).
+*   It uses `ipcRenderer.invoke` to send messages and receive `Promise`s. If the main process handler throws an error, the `Promise` will be rejected, and this rejection will be handled by TanStack Query in the hook.
+
+**3. IPC Handlers (e.g., `entity_handlers.ts` in the main process):**
+
+*   **Registration:**
+    *   Handlers are registered using `ipcMain.handle("channel-name", async (event, args) => { /* ... */ })`. The `channel-name` must match what `IpcClient` calls.
+*   **Logic:**
+    *   Contains the core business logic, interacting with databases (e.g., `db`), file system (`fs`), or other main-process services (e.g., `git`).
+*   **Error Handling (Crucial):**
+    *   **Handlers MUST `throw new Error("Descriptive error message")` when an operation fails or an invalid state is encountered.** This is the preferred pattern over returning objects like `{ success: false, errorMessage: "..." }`.
+    
+*   **Concurrency (If Applicable):**
+    *   For operations that modify shared resources related to a specific entity (like an `appId`), use a locking mechanism (e.g., `withLock(appId, async () => { ... })`) to prevent race conditions.
+
+**Flow Summary:**
+
+1.  React component calls a function from the custom hook.
+2.  The hook's `queryFn` (for reads) or `mutationFn` (for writes) calls a method on `IpcClient`.
+3.  `IpcClient` uses `ipcRenderer.invoke` to send a message to the main process.
+4.  The corresponding `ipcMain.handle` in the main process executes.
+    *   If successful, it returns data.
+    *   **If an error occurs, it `throw`s an `Error`.**
+5.  The `Promise` from `ipcRenderer.invoke` resolves or rejects.
+6.  TanStack Query handles the resolved data or the rejection:
+    *   `useQuery`: Populates `data` or `error`.
+    *   `useMutation`: Calls `onSuccess` or `onError`.
+
+This pattern ensures that errors are propagated correctly from the main process back to the React application, where TanStack Query can manage the error state and allow for robust error handling and UI feedback.

.cursorignore

@@ -0,0 +1,2 @@
+# Add directories or file patterns to ignore during indexing (e.g. foo/ or *.csv)
+scaffold/

.devcontainer/devcontainer.json

@@ -0,0 +1,4 @@
+{
+  "image": "mcr.microsoft.com/devcontainers/universal:2",
+  "features": {}
+}

.env.example

@@ -0,0 +1,37 @@
+# Environment variables needed for dyad local development.
+# To use, copy this file to a new file named ".env" and fill in your private keys and settings.
+# Your actual .env file should NOT be committed.
+
+# AI Provider API Keys(Optional)
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+GOOGLE_API_KEY=
+
+
+# Local AI Model Configuration (Optional)
+# Set these if you are running local AI models like Ollama or LM Studio.
+# Default for Ollama is http://127.0.0.1:11434
+OLLAMA_HOST=
+
+# GitHub Integration (Optional)
+# Needed for features that interact with GitHub repositories.
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+GITHUB_TOKEN=
+
+
+# Apple Notarization (macOS Build Only)
+# Only required if you are building and signing a release version for macOS.
+APPLE_ID=
+APPLE_PASSWORD=
+APPLE_TEAM_ID=
+SM_CODE_SIGNING_CERT_SHA1=
+
+
+# Development & Testing Variables (Advanced)
+# These are typically not needed for standard contribution.
+# NODE_ENV=development
+# E2E_TEST_BUILD=
+# CI=
+# DYAD_ENGINE_URL=
+# DYAD_GATEWAY_URL=

.eslintrc.json

@@ -0,0 +1,16 @@
+{
+  "env": {
+    "browser": true,
+    "es6": true,
+    "node": true
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/eslint-recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:import/recommended",
+    "plugin:import/electron",
+    "plugin:import/typescript"
+  ],
+  "parser": "@typescript-eslint/parser"
+}

.gitattributes

@@ -0,0 +1,6 @@
+# Set the default behavior, in case people don't have core.autocrlf set.
+* text=auto
+
+# Make everything in the e2e-tests/snapshots directory use LF line endings.
+# Otherwise we'll get diffs in the snapshots when running on Windows.
+e2e-tests/snapshots/** text eol=lf

.github/ISSUE_TEMPLATE/add_template.md

@@ -0,0 +1,23 @@
+---
+name: Add Template
+about: Request to add a template to Dyad Hub
+title: "Add Template: [Template Name]"
+labels: "add-template"
+assignees: ""
+---
+
+If you'd like to add a template to Dyad Hub, follow the [Add Template guide](https://alifullstack.com/docs/templates/add-template).
+
+**Template name:**
+
+**Template description (1-2 sentences):**
+
+**GitHub repo:**
+
+**Screenshot**
+
+<!-- Please attach a screenshot of your template in action -->
+
+**Open Source License**
+
+- [ ] This template is open-source (e.g. MIT, Apache 2.0)

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ""
+labels: "bug"
+assignees: ""
+---
+
+<!--
+⚠️ IMPORTANT: All sections marked as required must be completed in English.
+Issues that do not meet these requirements will be closed and may need to be resubmitted.
+-->
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+
+- OS: [e.g. iOS]
+- Browser [e.g. chrome, safari]
+- Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ""
+labels: "feature request"
+assignees: ""
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/workflows/ci.yml

@@ -0,0 +1,149 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  test:
+    # Why Mac and Windows?
+    # I can't run electron playwright on ubuntu-latest and
+    # Linux support for Dyad is experimental so not as important
+    # as Mac + Windows
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [
+            # npm install is very slow
+            # { name: "windows-arm", image: "windows-11-arm" },
+            { name: "windows", image: "windows-latest" },
+            { name: "macos", image: "macos-latest" },
+          ]
+        shard: [1, 2, 3, 4]
+        shardTotal: [4]
+    runs-on: ${{ matrix.os.image }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Initialize environment
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: package.json
+          cache: npm
+          cache-dependency-path: package-lock.json
+      - name: Install node modules
+        run: npm ci --no-audit --no-fund --progress=false
+      - name: Presubmit check (e.g. lint, format)
+        # do not run this on Windows (it fails and not necessary)
+        # Only run on shard 1 to avoid redundant execution
+        if: contains(matrix.os.name, 'macos') && matrix.shard == 1
+        run: npm run presubmit
+      - name: Type-checking
+        # do not run this on windows (it's redunant)
+        # Only run on shard 1 to avoid redundant execution
+        if: contains(matrix.os.name, 'macos') && matrix.shard == 1
+        run: npm run ts
+      - name: Unit tests
+        # do not run this on windows (it's redunant)
+        # Only run on shard 1 to avoid redundant execution
+        if: contains(matrix.os.name, 'macos') && matrix.shard == 1
+        run: npm run test
+      - name: Setup pnpm
+        uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4.1.0
+        with:
+          version: latest
+      - name: Clone nextjs-template
+        run: git clone --depth 1 https://github.com/SFARPak/nextjs-template.git nextjs-template
+      - name: Get pnpm store directory
+        id: pnpm-cache
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
+      - name: Setup pnpm cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
+          key: ${{ matrix.os.name }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ matrix.os.name }}-pnpm-store-
+      # Not strictly needed but makes the e2e tests faster (and less flaky)
+      - name: Install scaffold dependencies
+        run: cd scaffold && pnpm install
+      - name: Install nextjs-template dependencies
+        run: cd nextjs-template && pnpm install
+      - name: Install Chromium browser for Playwright
+        run: npx playwright install chromium --with-deps
+      - name: Build
+        env:
+          NODE_OPTIONS: "--max-old-space-size=4096"
+        run: npm run pre:e2e
+      - name: Prep test server
+        run: cd testing/fake-llm-server && npm install && npm run build && cd -
+      - name: E2E tests (Shard ${{ matrix.shard }}/4)
+        # You can add debug logging to make it easier to see what's failing
+        # by adding "DEBUG=pw:browser" in front.
+        # Use blob reporter for sharding and merge capabilities
+        run: DEBUG=pw:browser npx playwright test --shard=${{ matrix.shard }}/${{ matrix.shardTotal }}
+      - name: Upload shard results
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: ${{ !cancelled() }}
+        with:
+          name: blob-report-${{ matrix.os.name }}-shard-${{ matrix.shard }}
+          path: blob-report
+          retention-days: 1
+
+  merge-reports:
+    # Merge reports after playwright-tests, even if some shards have failed
+    if: ${{ !cancelled() }}
+    needs: [test]
+
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+      - name: Install dependencies
+        run: npm ci --no-audit --no-fund --progress=false
+
+      - name: Download blob reports from GitHub Actions Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: all-blob-reports
+          pattern: blob-report-*
+          merge-multiple: true
+
+      - name: Debug - List downloaded blob reports
+        run: |
+          echo "Contents of all-blob-reports directory:"
+          ls -la all-blob-reports/
+          echo "File sizes and details:"
+          find all-blob-reports/ -type f -exec ls -lh {} \; || echo "No files found"
+
+      - name: Merge into HTML Report
+        run: PLAYWRIGHT_HTML_OUTPUT_DIR=playwright-report npx playwright merge-reports --config=merge.config.ts ./all-blob-reports
+
+      - name: Debug - List playwright-report contents
+        run: |
+          echo "Contents of playwright-report directory:"
+          ls -la playwright-report/ || echo "playwright-report directory does not exist"
+          echo "Current directory contents:"
+          ls -la
+
+      - name: Upload HTML report
+        uses: actions/upload-artifact@v4
+        with:
+          name: html-report--attempt-${{ github.run_attempt }}
+          path: playwright-report
+          retention-days: 3