aegis-desktop 0.3.0 → 0.4.0

package/README.md

@@ -0,0 +1,61 @@
+# AEGIS Desktop
+
+Electron host — see the repo root [README.md](../README.md) for the full
+build/architecture reference. This file covers day-to-day usage details that
+don't belong in the top-level doc.
+
+## Keyboard shortcuts
+
+### In the main window
+
+| Shortcut | Action |
+|---|---|
+| `Cmd/Ctrl+N` | New chat |
+| `Cmd/Ctrl+K` | Open search (memory inspector) |
+| `Cmd/Ctrl+S` | Save as… (export the open session as Markdown) |
+| `Cmd/Ctrl+R` | Reload |
+| `Cmd/Ctrl+Shift+I` | Toggle DevTools |
+| `Enter` | Send the composer prompt |
+| `Shift+Enter` | Newline in the composer |
+| `Esc` | Close the memory inspector overlay |
+
+### Global quick launcher
+
+`Cmd/Ctrl+Shift+Space` (default, configurable in the sidebar's **Quick
+Launcher** card) toggles a small, frameless, always-on-top prompt window near
+your cursor — from anywhere on the desktop, even when AEGIS Desktop isn't the
+focused app. It streams a one-shot answer over the same transport the main
+window uses, with the agent's tool-calling loop turned off (no file/shell
+access, no approval prompts) — just a fast question and an answer.
+
+| Shortcut | Action |
+|---|---|
+| `Cmd/Ctrl+Shift+Space` (default, configurable) | Toggle the quick launcher |
+| `Enter` | Ask the typed prompt |
+| `Shift+Enter` | Newline in the prompt |
+| `Cmd/Ctrl+Enter` | Add the current answer to the main window as a new chat turn |
+| `Esc` | Close the quick launcher |
+| *(click away)* | Also closes it — closing never steals focus from whatever window had it before |
+
+**Packaged builds** (the installed app) always register the global shortcut.
+**Dev runs** (`npm start` / `electron .`) do not, unless you turn on "enable
+global shortcut" in the sidebar's Quick Launcher card — this keeps a local
+dev session from silently grabbing a systemwide hotkey. If the configured
+accelerator is already claimed by another application, registration fails
+gracefully: a warning is logged to the main process console and the
+Quick Launcher card shows the reason instead of the app crashing or hanging.
+
+## Run from source
+
+```bash
+cd desktop
+npm install
+npm start
+```
+
+## Checks
+
+```bash
+npm run check          # node --check every main-process + renderer file
+node ../test/desktop-shell.mjs   # headless IPC smoke test (no Electron binary needed)
+```

package/lib/deep-link.js

@@ -0,0 +1,83 @@
+'use strict';
+
+/**
+ * deep-link.js — aegis:// URL parsing (native desktop plumbing).
+ * Pure functions, no Electron import, so this unit-tests without the
+ * Electron binary. main.js wires the result into IPC; this module only
+ * turns a raw URL/argv list into `{ action, ... }` or null.
+ *
+ * Supported shapes:
+ *   aegis://open?session=<id>   -> { action: 'open', sessionId }
+ *   aegis://new?prompt=<text>   -> { action: 'new', prompt }
+ */
+
+const PROTOCOL = 'aegis';
+const SCHEME_PREFIX = `${PROTOCOL}://`;
+
+/** True for any string that looks like our protocol, cheap enough to filter
+ *  argv with before the full URL parse (which throws on most argv entries —
+ *  flags, file paths — so callers should not run it against every arg). */
+function isDeepLinkUrl(value) {
+  return typeof value === 'string' && value.toLowerCase().startsWith(SCHEME_PREFIX);
+}
+
+/**
+ * Parse a raw `aegis://...` URL into a routable action, or null for anything
+ * unparseable or from a scheme/action this app doesn't recognise. Never
+ * throws — a malformed or malicious URL (e.g. handed to the OS by another
+ * app) just yields null.
+ */
+function parseDeepLinkUrl(url) {
+  if (!isDeepLinkUrl(url)) return null;
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== `${PROTOCOL}:`) return null;
+
+  // For a non-special scheme like "aegis:", "//host" still parses into
+  // `.hostname` — aegis://open?session=x -> hostname "open".
+  const action = (parsed.hostname || '').toLowerCase();
+
+  if (action === 'open') {
+    const sessionId = parsed.searchParams.get('session');
+    if (!sessionId) return null;
+    return { action: 'open', sessionId };
+  }
+
+  if (action === 'new') {
+    return { action: 'new', prompt: parsed.searchParams.get('prompt') || '' };
+  }
+
+  return null;
+}
+
+/**
+ * Find the deep-link URL among a process's argv, handling the Linux quirk
+ * where the OS hands the URL to the app as a bare positional argument (no
+ * `--url=` flag, no special marker) — it can land anywhere after the
+ * executable/script path, so every entry is checked rather than assuming a
+ * fixed index.
+ */
+function extractDeepLinkUrl(argv) {
+  if (!Array.isArray(argv)) return null;
+  for (const arg of argv) {
+    if (isDeepLinkUrl(arg)) return arg;
+  }
+  return null;
+}
+
+/** Convenience: argv -> parsed action in one call, or null at either step. */
+function parseDeepLinkArgv(argv) {
+  return parseDeepLinkUrl(extractDeepLinkUrl(argv));
+}
+
+module.exports = {
+  PROTOCOL,
+  isDeepLinkUrl,
+  parseDeepLinkUrl,
+  extractDeepLinkUrl,
+  parseDeepLinkArgv,
+};