AlexandrAI AGENTS.md
agents-md

HTML Editor Electron File Store Agent Guide

Module-specific agent guide for Electron file open, atomic save, preload IPC, and security defaults.

AGENTS.md

Guidance for coding agents working on HTML Editor Electron File Store in the html-editor project.

Project overview

This guide covers the Electron file boundary. The renderer does not access the filesystem directly. It calls a small preload API, which invokes main-process IPC handlers. The main process opens HTML files, computes content hashes, and saves through an atomic write path with conflict detection.

Primary source files

  • src/main/fileStore.ts owns hashContent, loadFile, saveAtomic, and ConflictError.
  • src/main/index.ts registers file:open and file:save handlers and injects the app CSP.
  • src/preload/index.ts exposes editorAPI.openFile and editorAPI.saveFile.
  • src/main/security.ts defines secure BrowserWindow preferences and external navigation detection.
  • src/renderer/src/render/exportHtml.ts creates the HTML content that is saved.

Setup commands

npm install npm test npm run typecheck npm run build

For focused validation, run npm test -- src/main/fileStore.test.ts src/main/security.test.ts when those tests exist.

Change rules

  • Keep renderer filesystem access behind preload IPC.
  • Preserve nodeIntegration: false, contextIsolation: true, sandbox: true, and webSecurity: true.
  • Keep save conflict checks based on the hash captured at open time.
  • Write to a temporary file and rename into place so partially written output is not left as the target file.
  • Preserve backup behavior for existing files when expected hash comparison is active.

IPC contract

openFile returns path, content, and hash or null when canceled. saveFile accepts an optional path, required content, and optional expected hash. It returns the target path and new hash or null when the save dialog is canceled.

Security

External navigation and popups should be denied in the app window and opened outside the app only when isExternalUrl classifies them as external. Do not expose generic IPC invoke, shell, or filesystem helpers to the renderer.

PR checklist

  • File APIs remain narrow and typed.
  • Conflict behavior is tested for changed files and new files.
  • CSP changes are justified by the renderer build mode.
  • Full npm test and npm run typecheck pass.