Merge pull request #117 from asperpharma/copilot/update-cursor-rules-docs

Fix Azure CI failure; add Antigravity feature flag, diagnostic script, and Cursor rules guide

Author: asperpharma

.github/workflows/azure-webapps-node.yml

@@ -32,6 +32,10 @@ permissions:
 
 jobs:
   build:
+    # Skip this workflow when Azure credentials are not configured.
+    # To enable Azure deployment, set AZURE_WEBAPP_PUBLISH_PROFILE in
+    # Settings → Secrets and variables → Actions and update AZURE_WEBAPP_NAME above.
+    if: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE != '' }}
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4

docs/copilot-update-cursor-rules.md

@@ -0,0 +1,76 @@
+# Copilot & Cursor Rules — Update Guide
+
+This document explains where Cursor rules live, how to create or update them,
+and how to keep GitHub Copilot settings in sync.
+
+---
+
+## Where Cursor rules live
+
+All project-specific Cursor rules are stored under **`.cursor/rules/`**.  
+Each rule is a `.mdc` file (Markdown + metadata front-matter):
+
+```
+.cursor/
+└── rules/
+    ├── Compliance-Legal-Rules.mdc
+    ├── Monitoring-Quality-Rules.mdc
+    ├── Operational-Workflow-Rules.mdc
+    └── Strategic-Vision-Rules.mdc
+```
+
+Global (user-level) rules live in `~/.cursor/rules/` or are managed via
+**Cursor → Settings → Rules for AI**.
+
+---
+
+## Creating or updating rules
+
+Use the built-in **`create-rule`** skill (if available) for scaffolding:
+
+```bash
+# Example: scaffold a new rule called "Security-Rules"
+cursor skill create-rule Security-Rules
+```
+
+To edit an existing rule manually, open the `.mdc` file and update the
+front-matter (title, description, `alwaysApply`, `globs`) and the rule body.
+
+---
+
+## Keeping Copilot in sync
+
+When you update a Cursor rule that also affects GitHub Copilot behaviour,
+mirror the change in Copilot's instruction settings:
+
+| Setting | Location |
+|---|---|
+| Review selection instructions | `github.copilot.chat.reviewSelection.instructions` in VS Code / Cursor user settings |
+| Commit message instructions | `github.copilot.chat.commitMessageGeneration.instructions` |
+| Generate test instructions | `github.copilot.chat.generateTests.instructions` |
+
+The reference file for all custom Copilot/Cursor JSON overrides is
+**`cursor-user-settings-FIXED.json`** in the repository root (if present).  
+Apply it with the `install-cursor` skill or by copying the relevant keys into
+your editor's user `settings.json`.
+
+---
+
+## Workflow
+
+1. **Edit rule** — open the relevant `.cursor/rules/*.mdc` file and update.
+2. **Sync Copilot** — if the rule change affects code review or generation
+   instructions, update the corresponding Copilot setting (see table above).
+3. **Install settings** — run `install-cursor` skill or apply
+   `cursor-user-settings-FIXED.json` if prompted.
+4. **Commit & push** — rules are committed to the repo so the team shares
+   the same AI behaviour.
+
+---
+
+## References
+
+- [CURSOR-SETTINGS-FIX](../cursor-user-settings-FIXED.json) *(if present)*
+- [.cursorrules](../.cursorrules) — legacy root-level rules file
+- [Cursor documentation — Rules for AI](https://cursor.sh/docs/rules-for-ai)
+- [GitHub Copilot custom instructions](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)

env.main-site.example

@@ -42,3 +42,9 @@ LOVABLE_WEBHOOK_URL=
 SHOPIFY_ADMIN_ACCESS_TOKEN=
 SHOPIFY_STORE_DOMAIN=lovable-project-milns.myshopify.com
 CSV_PATH=./data/shopify-import-2.csv
+
+# ========== Feature Flags ==========
+# Set to "true" to enable Antigravity IDE integration panel and diagnostics.
+# Requires the Antigravity language server (language_server_windows_x64.exe) to be running.
+# See src/lib/antigravityFeatureFlag.ts and scripts/antigravity-diagnostic.ps1.
+VITE_FEATURE_ANTIGRAVITY=false

package-lock.json

@@ -0,0 +1,39 @@
+# Antigravity Language Server Diagnostic Script
+# Usage: powershell -NoProfile -ExecutionPolicy Bypass -File "scripts\antigravity-diagnostic.ps1"
+#
+# Checks whether the Antigravity language server process is running on this machine.
+# Mirrors the process check performed by the Antigravity Toolkit VS Code/Cursor extension
+# so you can diagnose "no_process" / quota failures without needing the extension UI.
+
+$ProcessName = "language_server_windows_x64"
+$FullExe     = "$ProcessName.exe"
+
+Write-Host "=== Antigravity Language Server Diagnostic ===" -ForegroundColor Cyan
+Write-Host "Searching for process: $FullExe"
+Write-Host ""
+
+$processes = Get-Process -Name $ProcessName -ErrorAction SilentlyContinue
+
+if ($processes) {
+    Write-Host "FOUND: $($processes.Count) instance(s) of $FullExe running." -ForegroundColor Green
+    $processes | Format-Table Id, Name, CPU, WorkingSet -AutoSize
+    Write-Host ""
+    Write-Host "Status: CONNECTED — the Antigravity Toolkit should be able to reach the language server." -ForegroundColor Green
+    exit 0
+} else {
+    Write-Host "NOT FOUND: no $FullExe process detected." -ForegroundColor Yellow
+    Write-Host ""
+    Write-Host "Status: no_process" -ForegroundColor Yellow
+    Write-Host ""
+    Write-Host "What this means:" -ForegroundColor Cyan
+    Write-Host "  The Antigravity Toolkit extension connects to an external Antigravity process"
+    Write-Host "  (e.g. Antigravity IDE or its language server).  Until that process is running,"
+    Write-Host "  the Toolkit will report 'no_process' and 'Cannot fetch quota: server info not available'."
+    Write-Host ""
+    Write-Host "Next steps:" -ForegroundColor Cyan
+    Write-Host "  1. Start Antigravity IDE (or the app that launches $FullExe)."
+    Write-Host "  2. Reload Cursor / run this script again to confirm the process is detected."
+    Write-Host "  3. If you do not use Antigravity, disable or uninstall the 'Toolkit for Antigravity'"
+    Write-Host "     extension in Cursor to stop the repeated connection attempts."
+    exit 0
+}

scripts/antigravity-diagnostic.ps1

@@ -0,0 +1,74 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+
+/**
+ * Unit tests for src/lib/antigravityFeatureFlag.ts
+ *
+ * Tests the FEATURE_ANTIGRAVITY flag value and the behaviour of
+ * runAntigravityDiagnostic() under various conditions.
+ */
+
+/** Helper type for patching globalThis.window in tests. */
+type GlobalWithWindow = typeof globalThis & { window?: unknown };
+
+describe("FEATURE_ANTIGRAVITY flag", () => {
+  it("defaults to false when VITE_FEATURE_ANTIGRAVITY env var is absent", async () => {
+    // In the test environment VITE_FEATURE_ANTIGRAVITY is not set,
+    // so the flag should evaluate to false.
+    const { FEATURE_ANTIGRAVITY } = await import("../antigravityFeatureFlag");
+    expect(FEATURE_ANTIGRAVITY).toBe(false);
+  });
+});
+
+describe("runAntigravityDiagnostic()", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it("returns status 'error' when the feature flag is false", async () => {
+    const { runAntigravityDiagnostic } = await import("../antigravityFeatureFlag");
+    const result = await runAntigravityDiagnostic();
+    expect(result.status).toBe("error");
+    expect(result.details).toMatch(/disabled by feature flag/i);
+  });
+
+  it("returns status 'error' when called in a browser-like environment (no process on window)", async () => {
+    // Simulate a browser context: window exists but window.process does not.
+    const hadWindow = "window" in globalThis;
+    const originalWindowProcess = (globalThis as GlobalWithWindow & { window?: { process?: unknown } }).window?.process;
+
+    // Set up a window object without a .process property
+    (globalThis as GlobalWithWindow).window = {};
+
+    vi.stubEnv("VITE_FEATURE_ANTIGRAVITY", "true");
+    vi.resetModules();
+
+    const { runAntigravityDiagnostic } = await import("../antigravityFeatureFlag");
+    const result = await runAntigravityDiagnostic();
+
+    expect(result.status).toBe("error");
+    expect(result.details).toMatch(/browser environment/i);
+
+    // Restore window
+    if (hadWindow) {
+      (globalThis as GlobalWithWindow).window = { process: originalWindowProcess };
+    } else {
+      delete (globalThis as GlobalWithWindow).window;
+    }
+  });
+
+  it("returns status 'error' when flag is true but PowerShell is not available (CI/Linux)", async () => {
+    // In the Linux CI environment, 'powershell' does not exist.
+    // The function should catch the exec error and return { status: "error" }.
+    vi.stubEnv("VITE_FEATURE_ANTIGRAVITY", "true");
+    vi.resetModules();
+
+    const { runAntigravityDiagnostic } = await import("../antigravityFeatureFlag");
+    const result = await runAntigravityDiagnostic();
+
+    // PowerShell is unavailable → exec throws → catch block returns "error"
+    expect(result.status).toBe("error");
+    expect(result.details.length).toBeGreaterThan(0);
+  });
+});
+

src/lib/__tests__/antigravityFeatureFlag.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Feature Flag: Antigravity Panel
+ *
+ * All Antigravity connection/diagnostic UI or workflow changes must be wrapped
+ * with this flag, per Operational-Workflow-Rules. This enables safe, incremental
+ * rollout and easy toggling without redeployment.
+ *
+ * Control via environment variable (recommended):
+ *   VITE_FEATURE_ANTIGRAVITY=true   — enable
+ *   VITE_FEATURE_ANTIGRAVITY=false  — disable (default)
+ *
+ * See env.main-site.example and APPLY_TO_MAIN_SITE.md for conventions.
+ */
+export const FEATURE_ANTIGRAVITY: boolean =
+  typeof import.meta !== "undefined" &&
+  import.meta.env &&
+  typeof import.meta.env.VITE_FEATURE_ANTIGRAVITY !== "undefined"
+    ? String(import.meta.env.VITE_FEATURE_ANTIGRAVITY).toLowerCase() === "true"
+    : false;
+
+/**
+ * Run the Antigravity diagnostic PowerShell script and return a structured result.
+ *
+ * - Only executes when FEATURE_ANTIGRAVITY is true.
+ * - Requires a Node.js / Deno-capable runtime (not available in the browser).
+ * - Runs `scripts/antigravity-diagnostic.ps1` via PowerShell.
+ * - Returns `{ status, details }` for downstream UI or workflow handling.
+ * - Follows Monitoring-Quality-Rules: errors produce an escalatable object.
+ *
+ * Possible status values:
+ *   "success"    — language server process was found.
+ *   "no_process" — script ran but found no language server process.
+ *   "error"      — flag disabled, wrong environment, or script failed.
+ *   "escalate"   — script output signals uncertainty; human review needed.
+ */
+export async function runAntigravityDiagnostic(): Promise<{
+  status: "success" | "no_process" | "error" | "escalate";
+  details: string;
+}> {
+  if (!FEATURE_ANTIGRAVITY) {
+    return {
+      status: "error",
+      details: "Antigravity diagnostics are disabled by feature flag.",
+    };
+  }
+
+  // Guard: cannot run PowerShell in a pure browser environment.
+  if (typeof window !== "undefined" && typeof (window as Window & { process?: unknown }).process === "undefined") {
+    return {
+      status: "error",
+      details: "Cannot run PowerShell diagnostics in browser environment.",
+    };
+  }
+
+  try {
+    // Dynamic imports so this module remains safe to bundle in browser contexts
+    // even though the runtime branch above will never reach here in a browser.
+    const { exec } = await import("child_process");
+    const util = await import("util");
+    const path = await import("path");
+    const execAsync = util.promisify(exec);
+
+    const scriptPath = path.join("scripts", "antigravity-diagnostic.ps1");
+    const { stdout } = await execAsync(
+      `powershell -NoProfile -ExecutionPolicy Bypass -File "${scriptPath}"`
+    );
+
+    if (
+      stdout?.includes("no language_server_windows_x64") ||
+      stdout?.toLowerCase().includes("no_process")
+    ) {
+      return { status: "no_process", details: stdout.trim() };
+    }
+
+    return { status: "success", details: stdout?.trim() || "Diagnostic succeeded." };
+  } catch (err: unknown) {
+    const e = err as { stderr?: string; message?: string };
+    const detail = e?.stderr || e?.message || "Unknown error in diagnosis script";
+    return {
+      status:
+        detail.includes("uncertain") || detail.includes("cannot detect")
+          ? "escalate"
+          : "error",
+      details: detail,
+    };
+  }
+}