{"owner":"hackjutsu","repo":"Lepton","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md","AGENTS.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis repository uses `AGENTS.md` as the canonical guidance file for AI coding\nagents.\n\nClaude Code users should follow the instructions in `AGENTS.md`.\n","AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to AI coding agents when working with code in this repository.\n\n## Project Overview\n\nLepton is a lean code snippet manager powered by GitHub Gist, built with Electron, React, and Redux. It provides a desktop application for managing and organizing code snippets with features like unlimited public/secret snippets, tagging, markdown/Jupyter notebook support, and GitHub Enterprise integration.\n\n## Tech Stack\n\n- **Framework**: Electron (desktop app)\n- **Frontend**: React 19 + Redux (with Redux Thunk for async actions)\n- **Build System**: Webpack + Babel (ES6 transpilation)\n- **Styling**: Sass/SCSS\n- **Code Editor**: CodeMirror (via react-codemirror)\n- **Testing/Linting**: Vitest, Electron smoke tests, ESLint with Standard config\n- **Dependencies**: Uses npm package manager\n\n## Key Commands\n\n### Runtime\n\nUse Node.js 24 LTS for local development, preferably the version in `.nvmrc`:\n```bash\nnvm install\nnvm use\n```\n\nThe project uses npm 11.x. This is the host runtime for dependency installation\nand webpack builds; Electron's bundled app runtime is controlled separately by\nthe Electron version in `package.json`.\n\nOn Apple Silicon, use the native arm64 Node.js runtime:\n```bash\nnpm ci\nnpm run build\nnpm start\n```\n\n### Development\n```bash\n# Install dependencies\nnpm ci\n\n# Development build and run\nnpm run build && npm start\n\n# Watch mode for development\nnpm run webpack-watch\n\n# Production build\nnpm run webpack-prod\n```\n\n### Building & Distribution\n```bash\n# Create installer for current platform\nnpm run dist\n\n# Platform-specific builds\nnpm run dist -- -m    # macOS\nnpm run dist -- -w    # Windows\nnpm run dist -- -l    # Linux (requires Docker for snap)\nnpm run dist -- -wml  # All platforms\n```\n\n### Code Quality\n```bash\n# Lint code\nnpm run lint\n\n# Normal local check: Vitest unit tests plus webpack development build\nnpm test\n\n# Unit tests only\nnpm run test:unit\n\n# Unit tests in watch mode\nnpm run test:unit:watch\n\n# Webpack build verification only\nnpm run test:build\n\n# Check for outdated dependencies\nnpm run check-outdated\n\n# Pre-version checks (runs lint + test + outdated check)\nnpm run preversion\n```\n\n### Testing\nThe `npm test` command runs Vitest unit tests and webpack development build\nverification. Use it for normal local validation before committing code changes.\n\nElectron smoke checks are available for UI/runtime-sensitive changes:\n\n```bash\n# Renderer smoke: login screens plus fixture-backed authenticated surfaces\nnpm run test:smoke\n\n# Packaged app smoke: builds an unpacked app and verifies packaged login render\nnpm run test:packaged-smoke\n```\n\n`npm run test:smoke` uses isolated config/user-data directories. It verifies the\nlogin UI and render fixtures such as active layout, edit/new modals,\nabout/settings, dashboard, search, delete confirmation, raw modal, pinned tags,\nand immersive view. Fixture smoke verifies initial rendering, preload bridge\navailability, renderer isolation, visible dimensions, screenshots, and absence\nof renderer warnings/errors/crashes.\n\nFixture smoke does not validate GitHub OAuth, Gist CRUD, sync behavior, real API\nresponses, OS shortcut delivery, or full interaction flows. Use manual\nverification for those.\n\n### Rendering Verification\nFor any Electron, React, layout, CSS, webpack, or dependency change that could affect the UI, always verify actual rendering before considering the work complete:\n\n```bash\nnpm run build\nnpm start\n```\n\nConfirm more than process startup. The app must visibly render the Lepton UI, not just log `updateUserSession ACTIVE`. Always capture a screenshot of the running app and show that screenshot in the chat when reporting rendering verification. If the window is blank or suspicious, inspect the renderer with Electron DevTools or a remote debugging port and verify DOM layout, visible text, and the renderer screenshot. Before relaunching, check for and stop duplicate Lepton/Electron instances so stale blank windows do not mask the current result.\n\nFor render-only confidence on authenticated surfaces, use the fixture smoke\npath when appropriate:\n\n```bash\nnpm run build\nLEPTON_RENDER_FIXTURE=active npm start\n```\n\nSupported fixture names are `active`, `edit`, `new`, `about`, `dashboard`,\n`search`, `delete`, `raw`, `pinned-tags`, and `immersive`. Fixture rendering is\nacceptable for checking React/Electron render regressions without login. It is\nnot enough for changes touching GitHub authentication, backend sync, request\nconstruction, shortcut delivery, or save/delete flows; those require manual\nlogged-in verification against GitHub/Gist behavior.\n\nDocument rendering verification in PR descriptions, including whether the app was launched locally and what was observed.\n\n## Architecture\n\n### Application Structure\n- `/app` - Main React application source\n  - `/containers` - React container components (connected to Redux)\n  - `/reducers` - Redux reducers for state management\n  - `/actions` - Redux action creators\n  - `/utilities` - Shared utilities (GitHub API, parser, search, etc.)\n- `/configs` - Configuration files including GitHub OAuth credentials\n- `/main.js` - Electron main process entry point\n- `/bundle` - Webpack build output directory\n\n### Key Components\n- **GitHub API Integration**: `/app/utilities/githubApi/` - handles Gist CRUD operations\n- **Theme Management**: `/app/utilities/themeManager/` - light/dark theme switching\n- **Code Rendering**: Uses CodeMirror for syntax highlighting and editing\n- **Search**: `/app/utilities/search/` - snippet metadata and downloaded-content search functionality\n- **Configuration**: Uses nconf for config management, stored in `~/.leptonrc`\n- **Preload Bridge**: `/preload.js` exposes the limited renderer API as `window.lepton`\n\n### Search Development Notes\n\nSearch records are built through `/app/utilities/search/records.js`. Use the\nshared builder when sync, create, edit, fixture rendering, or lazy single-gist\nfetches need to refresh indexed gist data. Search currently performs exact,\ncase-insensitive token matching across metadata and any downloaded file content;\ndo not reintroduce fuzzy matching without updating tests and UI expectations.\n\nComplete global content search depends on `snippet.downloadAll` being enabled\nbefore sync so every snippet's details and file contents are downloaded. When\n`downloadAll` is disabled, content search can only cover snippets whose details\nhave already been loaded locally.\n\n### GitHub OAuth Setup\nThe app requires GitHub OAuth credentials in `/configs/account.js`:\n```js\nmodule.exports = {\n  client_id: '<your_client_id>',\n  client_secret: '<your_client_secret>'\n}\n```\nRegister your application at https://github.com/settings/applications/new\n\n## Development Notes\n\n- **Electron Version**: Uses Electron 42.x. Renderer windows are sandboxed and context-isolated.\n- **Renderer Bridge**: Renderer code must use the `window.lepton` preload API. Do not access Node globals directly from renderer code.\n- **React Version**: Uses React 19 with `createRoot`; do not use legacy React root APIs.\n- **Node Version**: Use Node.js 24 LTS for local development.\n- **ES6 Support**: Babel transpiles application source for the Electron renderer.\n- **Hot Reloading**: Use `npm run webpack-watch` for auto-rebuilding during development\n- **Styling**: Uses Sass with component-level SCSS files\n- **State Management**: Redux store handles application state, actions use Redux Thunk for async operations\n- **Shortcuts**: Customizable keyboard shortcuts defined in config, registered via electron-localshortcut\n- **Packaged Runtime Files**: `electron-builder.js` allowlists the main-process runtime files shipped in packaged apps. When `main.js`, `preload.js`, or another packaged runtime file starts requiring a new local helper, add that helper path to `mainRuntimeAppFiles` in `electron-builder.js` and update `tests/configs/electronBuilder.test.js`.\n- **Locales/i18n**: Adding a UI locale is not just a renderer code change. Update the locale catalog and package configuration together so packaged Electron builds keep the right Chromium locale resources.\n\n### Adding A Locale\n\nWhen adding a new interface locale:\n1. Add `app/utilities/i18n/locales/<locale>.js`, using `en.js` as the source-of-truth key shape.\n2. Update `app/utilities/i18n/index.js` to import the catalog, add it to `catalogs`, and add the display label to `supportedLocales`.\n3. Update `tests/utilities/i18n.test.js` so the new catalog is included in shape/translation coverage and, when useful, has a focused behavior assertion.\n4. Update user-facing supported-locale lists in `README.md` and `wiki/configuration.md`.\n5. Update `configs/electronLanguages.js` if the new Lepton locale needs a different Electron/Chromium resource name in packaged apps. `electron-builder.js` derives the packaged locale list from `getSupportedLocales()`, so do not add a separate hard-coded list to `package.json`.\n6. Validate with `npm run test:unit` and `npm run test:packaged-smoke`. For packaged-smoke, confirm the packaged app contains every supported Electron locale and no intentionally unsupported locales. On macOS, inspect both:\n   - `dist/mac-arm64/Lepton.app/Contents/Frameworks/Electron Framework.framework/Versions/A/Resources/*.lproj`\n   - `dist/mac-arm64/Lepton.app/Contents/Resources/*.lproj`\n\n## Configuration\n\nThe app uses a hierarchical configuration system:\n1. Default config in `/configs/defaultConfig.js`\n2. User config in `~/.leptonrc` (JSON format)\n3. Environment variables and command line args\n\nKey configuration areas include theme, shortcuts, proxy settings, editor preferences, and GitHub Enterprise support.\n\n## Important Guidelines\n\nWhen working with this codebase:\n- **NEVER modify `node_modules/`** - this directory contains installed dependencies and should not be edited\n- **DO NOT commit `package-lock.json` churn** unless specifically updating dependencies - this file locks dependency versions\n- **DO NOT change LICENSE files** unless told\n- **DO NOT commit `license.json` path-only churn** - `npm run build` regenerates local absolute paths\n- Focus code changes on the `/app` directory, `/configs`, `main.js`, and configuration files\n- Avoid searching or reading files in `node_modules/`, `/bundle`, `/build`, `/dist` directories unless absolutely necessary\n- Avoid bypassing the global logger for auth-related values; logger methods automatically redact known token and secret patterns\n- When adding new files used by the Electron main process at packaged-app startup, update `electron-builder.js` so packaged builds include them; otherwise `npm run test:packaged-smoke` can fail even when dev builds work.\n- Do not reintroduce `@electron/remote`, `nodeIntegration`, renderer `require`, or renderer `process` access. Add preload bridge methods instead.\n- Do not reintroduce Redux Form or other React 19-incompatible form patterns.\n- Do not use `ReactDOM.render`; use the existing React 19 root setup.\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis repository uses `AGENTS.md` as the canonical guidance file for AI coding\nagents.\n\nClaude Code users should follow the instructions in `AGENTS.md`.\n","AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to AI coding agents when working with code in this repository.\n\n## Project Overview\n\nLepton is a lean code snippet manager powered by GitHub Gist, built with Electron, React, and Redux. It provides a desktop application for managing and organizing code snippets with features like unlimited public/secret snippets, tagging, markdown/Jupyter notebook support, and GitHub Enterprise integration.\n\n## Tech Stack\n\n- **Framework**: Electron (desktop app)\n- **Frontend**: React 19 + Redux (with Redux Thunk for async actions)\n- **Build System**: Webpack + Babel (ES6 transpilation)\n- **Styling**: Sass/SCSS\n- **Code Editor**: CodeMirror (via react-codemirror)\n- **Testing/Linting**: Vitest, Electron smoke tests, ESLint with Standard config\n- **Dependencies**: Uses npm package manager\n\n## Key Commands\n\n### Runtime\n\nUse Node.js 24 LTS for local development, preferably the version in `.nvmrc`:\n```bash\nnvm install\nnvm use\n```\n\nThe project uses npm 11.x. This is the host runtime for dependency installation\nand webpack builds; Electron's bundled app runtime is controlled separately by\nthe Electron version in `package.json`.\n\nOn Apple Silicon, use the native arm64 Node.js runtime:\n```bash\nnpm ci\nnpm run build\nnpm start\n```\n\n### Development\n```bash\n# Install dependencies\nnpm ci\n\n# Development build and run\nnpm run build && npm start\n\n# Watch mode for development\nnpm run webpack-watch\n\n# Production build\nnpm run webpack-prod\n```\n\n### Building & Distribution\n```bash\n# Create installer for current platform\nnpm run dist\n\n# Platform-specific builds\nnpm run dist -- -m    # macOS\nnpm run dist -- -w    # Windows\nnpm run dist -- -l    # Linux (requires Docker for snap)\nnpm run dist -- -wml  # All platforms\n```\n\n### Code Quality\n```bash\n# Lint code\nnpm run lint\n\n# Normal local check: Vitest unit tests plus webpack development build\nnpm test\n\n# Unit tests only\nnpm run test:unit\n\n# Unit tests in watch mode\nnpm run test:unit:watch\n\n# Webpack build verification only\nnpm run test:build\n\n# Check for outdated dependencies\nnpm run check-outdated\n\n# Pre-version checks (runs lint + test + outdated check)\nnpm run preversion\n```\n\n### Testing\nThe `npm test` command runs Vitest unit tests and webpack development build\nverification. Use it for normal local validation before committing code changes.\n\nElectron smoke checks are available for UI/runtime-sensitive changes:\n\n```bash\n# Renderer smoke: login screens plus fixture-backed authenticated surfaces\nnpm run test:smoke\n\n# Packaged app smoke: builds an unpacked app and verifies packaged login render\nnpm run test:packaged-smoke\n```\n\n`npm run test:smoke` uses isolated config/user-data directories. It verifies the\nlogin UI and render fixtures such as active layout, edit/new modals,\nabout/settings, dashboard, search, delete confirmation, raw modal, pinned tags,\nand immersive view. Fixture smoke verifies initial rendering, preload bridge\navailability, renderer isolation, visible dimensions, screenshots, and absence\nof renderer warnings/errors/crashes.\n\nFixture smoke does not validate GitHub OAuth, Gist CRUD, sync behavior, real API\nresponses, OS shortcut delivery, or full interaction flows. Use manual\nverification for those.\n\n### Rendering Verification\nFor any Electron, React, layout, CSS, webpack, or dependency change that could affect the UI, always verify actual rendering before considering the work complete:\n\n```bash\nnpm run build\nnpm start\n```\n\nConfirm more than process startup. The app must visibly render the Lepton UI, not just log `updateUserSession ACTIVE`. Always capture a screenshot of the running app and show that screenshot in the chat when reporting rendering verification. If the window is blank or suspicious, inspect the renderer with Electron DevTools or a remote debugging port and verify DOM layout, visible text, and the renderer screenshot. Before relaunching, check for and stop duplicate Lepton/Electron instances so stale blank windows do not mask the current result.\n\nFor render-only confidence on authenticated surfaces, use the fixture smoke\npath when appropriate:\n\n```bash\nnpm run build\nLEPTON_RENDER_FIXTURE=active npm start\n```\n\nSupported fixture names are `active`, `edit`, `new`, `about`, `dashboard`,\n`search`, `delete`, `raw`, `pinned-tags`, and `immersive`. Fixture rendering is\nacceptable for checking React/Electron render regressions without login. It is\nnot enough for changes touching GitHub authentication, backend sync, request\nconstruction, shortcut delivery, or save/delete flows; those require manual\nlogged-in verification against GitHub/Gist behavior.\n\nDocument rendering verification in PR descriptions, including whether the app was launched locally and what was observed.\n\n## Architecture\n\n### Application Structure\n- `/app` - Main React application source\n  - `/containers` - React container components (connected to Redux)\n  - `/reducers` - Redux reducers for state management\n  - `/actions` - Redux action creators\n  - `/utilities` - Shared utilities (GitHub API, parser, search, etc.)\n- `/configs` - Configuration files including GitHub OAuth credentials\n- `/main.js` - Electron main process entry point\n- `/bundle` - Webpack build output directory\n\n### Key Components\n- **GitHub API Integration**: `/app/utilities/githubApi/` - handles Gist CRUD operations\n- **Theme Management**: `/app/utilities/themeManager/` - light/dark theme switching\n- **Code Rendering**: Uses CodeMirror for syntax highlighting and editing\n- **Search**: `/app/utilities/search/` - snippet metadata and downloaded-content search functionality\n- **Configuration**: Uses nconf for config management, stored in `~/.leptonrc`\n- **Preload Bridge**: `/preload.js` exposes the limited renderer API as `window.lepton`\n\n### Search Development Notes\n\nSearch records are built through `/app/utilities/search/records.js`. Use the\nshared builder when sync, create, edit, fixture rendering, or lazy single-gist\nfetches need to refresh indexed gist data. Search currently performs exact,\ncase-insensitive token matching across metadata and any downloaded file content;\ndo not reintroduce fuzzy matching without updating tests and UI expectations.\n\nComplete global content search depends on `snippet.downloadAll` being enabled\nbefore sync so every snippet's details and file contents are downloaded. When\n`downloadAll` is disabled, content search can only cover snippets whose details\nhave already been loaded locally.\n\n### GitHub OAuth Setup\nThe app requires GitHub OAuth credentials in `/configs/account.js`:\n```js\nmodule.exports = {\n  client_id: '<your_client_id>',\n  client_secret: '<your_client_secret>'\n}\n```\nRegister your application at https://github.com/settings/applications/new\n\n## Development Notes\n\n- **Electron Version**: Uses Electron 42.x. Renderer windows are sandboxed and context-isolated.\n- **Renderer Bridge**: Renderer code must use the `window.lepton` preload API. Do not access Node globals directly from renderer code.\n- **React Version**: Uses React 19 with `createRoot`; do not use legacy React root APIs.\n- **Node Version**: Use Node.js 24 LTS for local development.\n- **ES6 Support**: Babel transpiles application source for the Electron renderer.\n- **Hot Reloading**: Use `npm run webpack-watch` for auto-rebuilding during development\n- **Styling**: Uses Sass with component-level SCSS files\n- **State Management**: Redux store handles application state, actions use Redux Thunk for async operations\n- **Shortcuts**: Customizable keyboard shortcuts defined in config, registered via electron-localshortcut\n- **Packaged Runtime Files**: `electron-builder.js` allowlists the main-process runtime files shipped in packaged apps. When `main.js`, `preload.js`, or another packaged runtime file starts requiring a new local helper, add that helper path to `mainRuntimeAppFiles` in `electron-builder.js` and update `tests/configs/electronBuilder.test.js`.\n- **Locales/i18n**: Adding a UI locale is not just a renderer code change. Update the locale catalog and package configuration together so packaged Electron builds keep the right Chromium locale resources.\n\n### Adding A Locale\n\nWhen adding a new interface locale:\n1. Add `app/utilities/i18n/locales/<locale>.js`, using `en.js` as the source-of-truth key shape.\n2. Update `app/utilities/i18n/index.js` to import the catalog, add it to `catalogs`, and add the display label to `supportedLocales`.\n3. Update `tests/utilities/i18n.test.js` so the new catalog is included in shape/translation coverage and, when useful, has a focused behavior assertion.\n4. Update user-facing supported-locale lists in `README.md` and `wiki/configuration.md`.\n5. Update `configs/electronLanguages.js` if the new Lepton locale needs a different Electron/Chromium resource name in packaged apps. `electron-builder.js` derives the packaged locale list from `getSupportedLocales()`, so do not add a separate hard-coded list to `package.json`.\n6. Validate with `npm run test:unit` and `npm run test:packaged-smoke`. For packaged-smoke, confirm the packaged app contains every supported Electron locale and no intentionally unsupported locales. On macOS, inspect both:\n   - `dist/mac-arm64/Lepton.app/Contents/Frameworks/Electron Framework.framework/Versions/A/Resources/*.lproj`\n   - `dist/mac-arm64/Lepton.app/Contents/Resources/*.lproj`\n\n## Configuration\n\nThe app uses a hierarchical configuration system:\n1. Default config in `/configs/defaultConfig.js`\n2. User config in `~/.leptonrc` (JSON format)\n3. Environment variables and command line args\n\nKey configuration areas include theme, shortcuts, proxy settings, editor preferences, and GitHub Enterprise support.\n\n## Important Guidelines\n\nWhen working with this codebase:\n- **NEVER modify `node_modules/`** - this directory contains installed dependencies and should not be edited\n- **DO NOT commit `package-lock.json` churn** unless specifically updating dependencies - this file locks dependency versions\n- **DO NOT change LICENSE files** unless told\n- **DO NOT commit `license.json` path-only churn** - `npm run build` regenerates local absolute paths\n- Focus code changes on the `/app` directory, `/configs`, `main.js`, and configuration files\n- Avoid searching or reading files in `node_modules/`, `/bundle`, `/build`, `/dist` directories unless absolutely necessary\n- Avoid bypassing the global logger for auth-related values; logger methods automatically redact known token and secret patterns\n- When adding new files used by the Electron main process at packaged-app startup, update `electron-builder.js` so packaged builds include them; otherwise `npm run test:packaged-smoke` can fail even when dev builds work.\n- Do not reintroduce `@electron/remote`, `nodeIntegration`, renderer `require`, or renderer `process` access. Add preload bridge methods instead.\n- Do not reintroduce Redux Form or other React 19-incompatible form patterns.\n- Do not use `ReactDOM.render`; use the existing React 19 root setup.\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nThis repository uses `AGENTS.md` as the canonical guidance file for AI coding\nagents.\n\nClaude Code users should follow the instructions in `AGENTS.md`.\n","category":"root","tokens":42},{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nThis file provides guidance to AI coding agents when working with code in this repository.\n\n## Project Overview\n\nLepton is a lean code snippet manager powered by GitHub Gist, built with Electron, React, and Redux. It provides a desktop application for managing and organizing code snippets with features like unlimited public/secret snippets, tagging, markdown/Jupyter notebook support, and GitHub Enterprise integration.\n\n## Tech Stack\n\n- **Framework**: Electron (desktop app)\n- **Frontend**: React 19 + Redux (with Redux Thunk for async actions)\n- **Build System**: Webpack + Babel (ES6 transpilation)\n- **Styling**: Sass/SCSS\n- **Code Editor**: CodeMirror (via react-codemirror)\n- **Testing/Linting**: Vitest, Electron smoke tests, ESLint with Standard config\n- **Dependencies**: Uses npm package manager\n\n## Key Commands\n\n### Runtime\n\nUse Node.js 24 LTS for local development, preferably the version in `.nvmrc`:\n```bash\nnvm install\nnvm use\n```\n\nThe project uses npm 11.x. This is the host runtime for dependency installation\nand webpack builds; Electron's bundled app runtime is controlled separately by\nthe Electron version in `package.json`.\n\nOn Apple Silicon, use the native arm64 Node.js runtime:\n```bash\nnpm ci\nnpm run build\nnpm start\n```\n\n### Development\n```bash\n# Install dependencies\nnpm ci\n\n# Development build and run\nnpm run build && npm start\n\n# Watch mode for development\nnpm run webpack-watch\n\n# Production build\nnpm run webpack-prod\n```\n\n### Building & Distribution\n```bash\n# Create installer for current platform\nnpm run dist\n\n# Platform-specific builds\nnpm run dist -- -m    # macOS\nnpm run dist -- -w    # Windows\nnpm run dist -- -l    # Linux (requires Docker for snap)\nnpm run dist -- -wml  # All platforms\n```\n\n### Code Quality\n```bash\n# Lint code\nnpm run lint\n\n# Normal local check: Vitest unit tests plus webpack development build\nnpm test\n\n# Unit tests only\nnpm run test:unit\n\n# Unit tests in watch mode\nnpm run test:unit:watch\n\n# Webpack build verification only\nnpm run test:build\n\n# Check for outdated dependencies\nnpm run check-outdated\n\n# Pre-version checks (runs lint + test + outdated check)\nnpm run preversion\n```\n\n### Testing\nThe `npm test` command runs Vitest unit tests and webpack development build\nverification. Use it for normal local validation before committing code changes.\n\nElectron smoke checks are available for UI/runtime-sensitive changes:\n\n```bash\n# Renderer smoke: login screens plus fixture-backed authenticated surfaces\nnpm run test:smoke\n\n# Packaged app smoke: builds an unpacked app and verifies packaged login render\nnpm run test:packaged-smoke\n```\n\n`npm run test:smoke` uses isolated config/user-data directories. It verifies the\nlogin UI and render fixtures such as active layout, edit/new modals,\nabout/settings, dashboard, search, delete confirmation, raw modal, pinned tags,\nand immersive view. Fixture smoke verifies initial rendering, preload bridge\navailability, renderer isolation, visible dimensions, screenshots, and absence\nof renderer warnings/errors/crashes.\n\nFixture smoke does not validate GitHub OAuth, Gist CRUD, sync behavior, real API\nresponses, OS shortcut delivery, or full interaction flows. Use manual\nverification for those.\n\n### Rendering Verification\nFor any Electron, React, layout, CSS, webpack, or dependency change that could affect the UI, always verify actual rendering before considering the work complete:\n\n```bash\nnpm run build\nnpm start\n```\n\nConfirm more than process startup. The app must visibly render the Lepton UI, not just log `updateUserSession ACTIVE`. Always capture a screenshot of the running app and show that screenshot in the chat when reporting rendering verification. If the window is blank or suspicious, inspect the renderer with Electron DevTools or a remote debugging port and verify DOM layout, visible text, and the renderer screenshot. Before relaunching, check for and stop duplicate Lepton/Electron instances so stale blank windows do not mask the current result.\n\nFor render-only confidence on authenticated surfaces, use the fixture smoke\npath when appropriate:\n\n```bash\nnpm run build\nLEPTON_RENDER_FIXTURE=active npm start\n```\n\nSupported fixture names are `active`, `edit`, `new`, `about`, `dashboard`,\n`search`, `delete`, `raw`, `pinned-tags`, and `immersive`. Fixture rendering is\nacceptable for checking React/Electron render regressions without login. It is\nnot enough for changes touching GitHub authentication, backend sync, request\nconstruction, shortcut delivery, or save/delete flows; those require manual\nlogged-in verification against GitHub/Gist behavior.\n\nDocument rendering verification in PR descriptions, including whether the app was launched locally and what was observed.\n\n## Architecture\n\n### Application Structure\n- `/app` - Main React application source\n  - `/containers` - React container components (connected to Redux)\n  - `/reducers` - Redux reducers for state management\n  - `/actions` - Redux action creators\n  - `/utilities` - Shared utilities (GitHub API, parser, search, etc.)\n- `/configs` - Configuration files including GitHub OAuth credentials\n- `/main.js` - Electron main process entry point\n- `/bundle` - Webpack build output directory\n\n### Key Components\n- **GitHub API Integration**: `/app/utilities/githubApi/` - handles Gist CRUD operations\n- **Theme Management**: `/app/utilities/themeManager/` - light/dark theme switching\n- **Code Rendering**: Uses CodeMirror for syntax highlighting and editing\n- **Search**: `/app/utilities/search/` - snippet metadata and downloaded-content search functionality\n- **Configuration**: Uses nconf for config management, stored in `~/.leptonrc`\n- **Preload Bridge**: `/preload.js` exposes the limited renderer API as `window.lepton`\n\n### Search Development Notes\n\nSearch records are built through `/app/utilities/search/records.js`. Use the\nshared builder when sync, create, edit, fixture rendering, or lazy single-gist\nfetches need to refresh indexed gist data. Search currently performs exact,\ncase-insensitive token matching across metadata and any downloaded file content;\ndo not reintroduce fuzzy matching without updating tests and UI expectations.\n\nComplete global content search depends on `snippet.downloadAll` being enabled\nbefore sync so every snippet's details and file contents are downloaded. When\n`downloadAll` is disabled, content search can only cover snippets whose details\nhave already been loaded locally.\n\n### GitHub OAuth Setup\nThe app requires GitHub OAuth credentials in `/configs/account.js`:\n```js\nmodule.exports = {\n  client_id: '<your_client_id>',\n  client_secret: '<your_client_secret>'\n}\n```\nRegister your application at https://github.com/settings/applications/new\n\n## Development Notes\n\n- **Electron Version**: Uses Electron 42.x. Renderer windows are sandboxed and context-isolated.\n- **Renderer Bridge**: Renderer code must use the `window.lepton` preload API. Do not access Node globals directly from renderer code.\n- **React Version**: Uses React 19 with `createRoot`; do not use legacy React root APIs.\n- **Node Version**: Use Node.js 24 LTS for local development.\n- **ES6 Support**: Babel transpiles application source for the Electron renderer.\n- **Hot Reloading**: Use `npm run webpack-watch` for auto-rebuilding during development\n- **Styling**: Uses Sass with component-level SCSS files\n- **State Management**: Redux store handles application state, actions use Redux Thunk for async operations\n- **Shortcuts**: Customizable keyboard shortcuts defined in config, registered via electron-localshortcut\n- **Packaged Runtime Files**: `electron-builder.js` allowlists the main-process runtime files shipped in packaged apps. When `main.js`, `preload.js`, or another packaged runtime file starts requiring a new local helper, add that helper path to `mainRuntimeAppFiles` in `electron-builder.js` and update `tests/configs/electronBuilder.test.js`.\n- **Locales/i18n**: Adding a UI locale is not just a renderer code change. Update the locale catalog and package configuration together so packaged Electron builds keep the right Chromium locale resources.\n\n### Adding A Locale\n\nWhen adding a new interface locale:\n1. Add `app/utilities/i18n/locales/<locale>.js`, using `en.js` as the source-of-truth key shape.\n2. Update `app/utilities/i18n/index.js` to import the catalog, add it to `catalogs`, and add the display label to `supportedLocales`.\n3. Update `tests/utilities/i18n.test.js` so the new catalog is included in shape/translation coverage and, when useful, has a focused behavior assertion.\n4. Update user-facing supported-locale lists in `README.md` and `wiki/configuration.md`.\n5. Update `configs/electronLanguages.js` if the new Lepton locale needs a different Electron/Chromium resource name in packaged apps. `electron-builder.js` derives the packaged locale list from `getSupportedLocales()`, so do not add a separate hard-coded list to `package.json`.\n6. Validate with `npm run test:unit` and `npm run test:packaged-smoke`. For packaged-smoke, confirm the packaged app contains every supported Electron locale and no intentionally unsupported locales. On macOS, inspect both:\n   - `dist/mac-arm64/Lepton.app/Contents/Frameworks/Electron Framework.framework/Versions/A/Resources/*.lproj`\n   - `dist/mac-arm64/Lepton.app/Contents/Resources/*.lproj`\n\n## Configuration\n\nThe app uses a hierarchical configuration system:\n1. Default config in `/configs/defaultConfig.js`\n2. User config in `~/.leptonrc` (JSON format)\n3. Environment variables and command line args\n\nKey configuration areas include theme, shortcuts, proxy settings, editor preferences, and GitHub Enterprise support.\n\n## Important Guidelines\n\nWhen working with this codebase:\n- **NEVER modify `node_modules/`** - this directory contains installed dependencies and should not be edited\n- **DO NOT commit `package-lock.json` churn** unless specifically updating dependencies - this file locks dependency versions\n- **DO NOT change LICENSE files** unless told\n- **DO NOT commit `license.json` path-only churn** - `npm run build` regenerates local absolute paths\n- Focus code changes on the `/app` directory, `/configs`, `main.js`, and configuration files\n- Avoid searching or reading files in `node_modules/`, `/bundle`, `/build`, `/dist` directories unless absolutely necessary\n- Avoid bypassing the global logger for auth-related values; logger methods automatically redact known token and secret patterns\n- When adding new files used by the Electron main process at packaged-app startup, update `electron-builder.js` so packaged builds include them; otherwise `npm run test:packaged-smoke` can fail even when dev builds work.\n- Do not reintroduce `@electron/remote`, `nodeIntegration`, renderer `require`, or renderer `process` access. Add preload bridge methods instead.\n- Do not reintroduce Redux Form or other React 19-incompatible form patterns.\n- Do not use `ReactDOM.render`; use the existing React 19 root setup.\n","category":"root","tokens":2736}]}