# IDE Configuration Guide

This guide covers recommended IDE setup for developing on the Lilith platform,
with focus on VS Code.

## Overview

The Lilith platform uses:

- **TypeScript** with ESM modules
- **ESLint** for linting
- **Prettier** for formatting
- **EditorConfig** for consistent editor settings

---

## VS Code Setup

### Recommended Extensions

Install these extensions for the best development experience:

#### Essential

| Extension    | ID                          | Purpose                       |
| ------------ | --------------------------- | ----------------------------- |
| ESLint       | `dbaeumer.vscode-eslint`    | JavaScript/TypeScript linting |
| Prettier     | `esbenp.prettier-vscode`    | Code formatting               |
| EditorConfig | `editorconfig.editorconfig` | Editor settings sync          |
| TypeScript   | Built-in                    | TypeScript support            |

#### Recommended

| Extension      | ID                             | Purpose               |
| -------------- | ------------------------------ | --------------------- |
| GitLens        | `eamodio.gitlens`              | Git history and blame |
| Docker         | `ms-azuretools.vscode-docker`  | Docker integration    |
| YAML           | `redhat.vscode-yaml`           | YAML support          |
| OpenAPI Editor | `42crunch.vscode-openapi`      | API spec editing      |
| Thunder Client | `rangav.vscode-thunder-client` | API testing           |
| Jest Runner    | `firsttris.vscode-jest-runner` | Run Jest tests        |
| Playwright     | `ms-playwright.playwright`     | E2E test runner       |

#### Optional

| Extension         | ID                                   | Purpose              |
| ----------------- | ------------------------------------ | -------------------- |
| GitHub Copilot    | `github.copilot`                     | AI assistance        |
| Error Lens        | `usernamehw.errorlens`               | Inline error display |
| Todo Tree         | `gruntfuggly.todo-tree`              | TODO tracking        |
| Import Cost       | `wix.vscode-import-cost`             | Bundle size display  |
| Path Intellisense | `christian-kohler.path-intellisense` | Path autocomplete    |

### Quick Install

Copy and run in VS Code Command Palette (`Ctrl+Shift+P` → "Install Extensions"):

```
dbaeumer.vscode-eslint
esbenp.prettier-vscode
editorconfig.editorconfig
eamodio.gitlens
ms-azuretools.vscode-docker
redhat.vscode-yaml
42crunch.vscode-openapi
```

---

## VS Code Settings

Create or update `.vscode/settings.json` in the project root:

```json
{
  // Editor settings
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "editor.rulers": [100],
  "editor.wordWrap": "off",

  // File settings
  "files.encoding": "utf8",
  "files.eol": "\n",
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true,
  "files.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/coverage": true,
    "**/.nyc_output": true
  },

  // TypeScript settings
  "typescript.preferences.importModuleSpecifier": "relative",
  "typescript.suggest.autoImports": true,
  "typescript.updateImportsOnFileMove.enabled": "always",
  "typescript.preferences.quoteStyle": "single",

  // ESLint settings
  "eslint.enable": true,
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],
  "eslint.workingDirectories": [
    { "directory": "services/*", "changeProcessCWD": true }
  ],

  // Prettier settings
  "prettier.requireConfig": true,
  "prettier.singleQuote": true,
  "prettier.trailingComma": "none",

  // Language-specific formatters
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[yaml]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[markdown]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.wordWrap": "on"
  },

  // Search exclusions
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/coverage": true,
    "**/playwright-report": true,
    "**/test-results": true
  },

  // Terminal settings
  "terminal.integrated.defaultProfile.linux": "bash",
  "terminal.integrated.cwd": "${workspaceFolder}"
}
```

---

## Debug Configurations

Create `.vscode/launch.json` for debugging:

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Current Service",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["start"],
      "cwd": "${fileDirname}/..",
      "console": "integratedTerminal",
      "env": {
        "NODE_ENV": "development",
        "PORT": "8080"
      }
    },
    {
      "name": "Debug BFF Service",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/services/bff/src/server.js",
      "cwd": "${workspaceFolder}/services/bff",
      "console": "integratedTerminal",
      "env": {
        "NODE_ENV": "development",
        "PORT": "3000"
      }
    },
    {
      "name": "Debug Auth Service",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/services/auth/src/server.ts",
      "cwd": "${workspaceFolder}/services/auth",
      "runtimeArgs": ["--loader", "ts-node/esm"],
      "console": "integratedTerminal",
      "env": {
        "NODE_ENV": "development",
        "PORT": "3003"
      }
    },
    {
      "name": "Debug Jest Tests",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["test", "--", "--runInBand"],
      "cwd": "${fileDirname}/..",
      "console": "integratedTerminal"
    },
    {
      "name": "Debug Current Jest Test File",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["test", "--", "--runInBand", "${relativeFile}"],
      "cwd": "${fileDirname}/..",
      "console": "integratedTerminal"
    },
    {
      "name": "Debug Playwright Tests",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/.bin/playwright",
      "args": ["test", "--headed"],
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal"
    },
    {
      "name": "Attach to Running Service",
      "type": "node",
      "request": "attach",
      "port": 9229,
      "restart": true,
      "skipFiles": ["<node_internals>/**"]
    }
  ],
  "compounds": [
    {
      "name": "Debug Core Services",
      "configurations": ["Debug BFF Service", "Debug Auth Service"]
    }
  ]
}
```

### Using Debug Configurations

1. **Debug Current Service**: Open any file in a service, then run this config
2. **Debug BFF/Auth**: Start specific core services with debugging
3. **Debug Jest Tests**: Run tests with debugger attached
4. **Attach to Running**: Connect to a service started with `--inspect`

To start a service with debug port:

```bash
node --inspect=9229 src/server.js
```

---

## Tasks Configuration

Create `.vscode/tasks.json` for common tasks:

```json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Install Dependencies",
      "type": "shell",
      "command": "npm install",
      "group": "build",
      "problemMatcher": []
    },
    {
      "label": "Lint",
      "type": "shell",
      "command": "npm run lint",
      "group": "build",
      "problemMatcher": ["$eslint-stylish"]
    },
    {
      "label": "Type Check",
      "type": "shell",
      "command": "npm run typecheck",
      "group": "build",
      "problemMatcher": ["$tsc"]
    },
    {
      "label": "Run Tests",
      "type": "shell",
      "command": "npm test",
      "group": "test",
      "problemMatcher": []
    },
    {
      "label": "Start Docker Stack",
      "type": "shell",
      "command": "npm run deploy",
      "group": "build",
      "problemMatcher": []
    },
    {
      "label": "Stop Docker Stack",
      "type": "shell",
      "command": "npm run deploy:stop",
      "group": "build",
      "problemMatcher": []
    },
    {
      "label": "Health Check",
      "type": "shell",
      "command": "npm run health",
      "group": "test",
      "problemMatcher": []
    },
    {
      "label": "Current Service - Start",
      "type": "shell",
      "command": "npm start",
      "options": {
        "cwd": "${fileDirname}/.."
      },
      "group": "build",
      "problemMatcher": []
    },
    {
      "label": "Current Service - Test",
      "type": "shell",
      "command": "npm test",
      "options": {
        "cwd": "${fileDirname}/.."
      },
      "group": "test",
      "problemMatcher": []
    }
  ]
}
```

### Running Tasks

- `Ctrl+Shift+B` → Select task to run
- `Ctrl+Shift+P` → "Tasks: Run Task"

---

## EditorConfig

The project includes `.editorconfig` for consistent settings across editors:

```ini
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 2

[*.{js,jsx,ts,tsx,json,yml,yaml}]
indent_size = 2

[*.md]
trim_trailing_whitespace = false

[*.sql]
indent_size = 4

[Dockerfile*]
indent_size = 4

[Makefile]
indent_style = tab
```

Most editors automatically respect these settings with the EditorConfig plugin.

---

## Linting & Formatting Setup

### ESLint

The project uses ESLint with these key rules:

| Rule           | Setting    | Description             |
| -------------- | ---------- | ----------------------- |
| `quotes`       | `'single'` | Single quotes           |
| `indent`       | `2`        | 2-space indentation     |
| `no-console`   | `warn`     | Avoid console.log       |
| `prefer-const` | `error`    | Use const when possible |
| `no-var`       | `error`    | No var declarations     |
| `eqeqeq`       | `error`    | Strict equality         |

### Prettier

Prettier configuration (`.prettierrc`):

```json
{
  "semi": true,
  "trailingComma": "none",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2,
  "arrowParens": "avoid",
  "endOfLine": "lf"
}
```

### Format on Save

With the recommended settings, files auto-format on save:

1. Prettier formats the code
2. ESLint auto-fixes issues
3. EditorConfig ensures consistent line endings

---

## Workspace Setup

For monorepo development, create `lilith.code-workspace`:

```json
{
  "folders": [
    { "path": ".", "name": "Root" },
    { "path": "services/bff", "name": "BFF" },
    { "path": "services/auth", "name": "Auth" },
    { "path": "services/conversation", "name": "Conversation" },
    { "path": "services/content", "name": "Content" },
    { "path": "services/ai", "name": "AI" },
    { "path": "sdk/typescript", "name": "SDK" },
    { "path": "docs", "name": "Docs" }
  ],
  "settings": {
    "files.exclude": {
      "**/node_modules": true,
      "**/dist": true
    }
  }
}
```

Open with: File → Open Workspace from File

---

## Keyboard Shortcuts

Recommended custom shortcuts (add to `keybindings.json`):

```json
[
  {
    "key": "ctrl+shift+t",
    "command": "workbench.action.tasks.runTask",
    "args": "Run Tests"
  },
  {
    "key": "ctrl+shift+l",
    "command": "workbench.action.tasks.runTask",
    "args": "Lint"
  },
  {
    "key": "ctrl+shift+d",
    "command": "workbench.action.tasks.runTask",
    "args": "Start Docker Stack"
  }
]
```

---

## Other IDEs

### JetBrains (WebStorm, IntelliJ)

1. Install TypeScript, ESLint, Prettier plugins
2. Settings → Languages → TypeScript → Enable ESLint
3. Settings → Tools → File Watchers → Add Prettier
4. EditorConfig is supported natively

### Vim/Neovim

```lua
-- Install via plugin manager
-- coc.nvim for TypeScript
-- ALE or null-ls for linting
-- vim-prettier for formatting
```

### Sublime Text

1. Install Package Control
2. Install: LSP, LSP-typescript, SublimeLinter-eslint
3. Configure EditorConfig package

---

## Troubleshooting

### ESLint Not Working

```bash
# Verify ESLint is installed
npm ls eslint

# Run ESLint manually
npm run lint

# Check VS Code output
View → Output → ESLint
```

### Prettier Not Formatting

1. Check `.prettierrc` exists in root
2. Verify Prettier extension is enabled
3. Check "Default Formatter" setting
4. Try Format Document manually: `Shift+Alt+F`

### TypeScript Errors Not Showing

1. Restart TypeScript server: `Ctrl+Shift+P` → "TypeScript: Restart TS Server"
2. Check `tsconfig.json` is valid
3. Ensure dependencies are installed

### Slow Performance

1. Exclude `node_modules` from watch
2. Disable unnecessary extensions
3. Increase TypeScript memory: `"typescript.tsserver.maxTsServerMemory": 4096`

---

## Related Documentation

- [Local Development Setup](./local-development-setup.md)
- [Development Workflow](./development-workflow.md)
- [CONTRIBUTING.md](../../CONTRIBUTING.md)
