@hienlh/ppm 0.23.11 → 0.23.13

package/docs/architecture/workspace-and-ui.md

@@ -277,7 +277,7 @@ A **Design tab** puts a design chat beside a live, sandboxed canvas of what the
 
 **The design session** is an ordinary chat session whose `session_metadata.design_slug` is fixed at creation (`POST /chat/sessions` with `designSlug`, accepted only on a provider with `supportsDesignInstructions` — Claude and Codex). `chatService.prepareSendOptions` rebuilds the instruction block from the stored slug on every turn, whoever sends it (WebSocket, `ppm chat send`, scheduler, bots): Claude gets it appended to the `claude_code` preset, Codex as `developerInstructions` (`design-instructions.ts`). The permission mode defaults exactly as for a new chat (the provider's configured default, normally `bypassPermissions`), because a design agent reads and searches the project constantly and a stricter default asked on every file. A user who picks `acceptEdits` for a design session gets the tighter design policy: project file reads and writes are approved, shell and every other tool ask (`design-tool-policy.ts` for Claude, `workspace-write` + `untrusted` for Codex). Every `done`, and every terminal background task, schedules a `turn` snapshot 2 s later (`design-turn-snapshot.ts`). The tab keeps the session in design mode: a fork is swapped in place, `/clear` starts the next session in the same tab, the embedded history lists only this design's sessions, and opening a design session from anywhere focuses its design tab (`openSessionInItsTab`, `tabSessionId()` in `src/web/lib/tab-session-id.ts`).
 
-**The user's design instructions** (Settings → Design, `design-settings-section.tsx`; `GET/PUT /api/settings/design`, `src/server/routes/design-settings.ts`) are one global text (config row `design.instructions`, 8 KB UTF-8 cap, `design-settings.service.ts`). `design-user-section.ts` appends them after PPM's block, quoted in a `<user_design_instructions>` block under a statement that PPM's rules win. `/name` and `$name` mentions (`src/shared/design-skill-mentions.ts`) are resolved per session against the skills that provider can load (`design-skill-sources.ts`: Claude's slash discovery for the project narrowed to `.claude`, `CLAUDE_CONFIG_DIR` and plugins, since the Skill tool cannot run a `.codex`/`.ppm` skill the composer also lists; Codex's `skills/list` for the session's cwd and account): Claude is told to invoke the canonical name with the Skill tool, Codex to use `$name` (Codex's own mention syntax, the same rewrite `provider-skill-sigil.ts` does in chat). A name found nowhere is "not a skill, read it as text", any mention adds the ask-before-installing rule, and an unreadable list (an empty codex answer counts) marks the names unchecked; listing has a 5 s timeout and a 60 s back-off after a failure so a broken codex cannot spawn an app-server per turn. The editor reuses the composer's `SlashCommandPicker` and `slash-trigger.ts`. When nothing named resolves and no `ui-ux-pro-max` is installed, the pane (and a hint in New Design) shows the upstream install commands (`design-skill-suggestion.ts`); PPM never installs a skill. Claude snapshots its system prompt at a session's first request and Codex reads developer instructions on connect, so a change reaches new design chats; the section is cached per session and text. e2e `tests/e2e/design-settings-e2e.mjs`.
+**The user's design instructions** (Settings → Design, `design-settings-section.tsx`; `GET/PUT /api/settings/design`, `src/server/routes/design-settings.ts`) are one global text (config row `design.instructions`, 8 KB UTF-8 cap, `design-settings.service.ts`). `design-user-section.ts` appends them after PPM's block, quoted in a `<user_design_instructions>` block under a statement that PPM's rules win. `/name` and `$name` mentions (`src/shared/design-skill-mentions.ts`) are resolved per session against the skills that provider can load (`design-skill-sources.ts`: Claude's slash discovery for the project narrowed to `.claude`, `CLAUDE_CONFIG_DIR` and plugins, since the Skill tool cannot run a `.codex`/`.ppm` skill the composer also lists; Codex's `skills/list` for the session's cwd and account): Claude is told to invoke the canonical name with the Skill tool, Codex to use `$name` (Codex's own mention syntax, the same rewrite `provider-skill-sigil.ts` does in chat). A name found nowhere is "not a skill, read it as text", any mention adds the ask-before-installing rule, and an unreadable list (an empty codex answer counts) marks the names unchecked; listing has a 5 s timeout and a 60 s back-off after a failure so a broken codex cannot spawn an app-server per turn. The editor reuses the composer's `SlashCommandPicker` and `slash-trigger.ts`. When nothing named resolves and no `ui-ux-pro-max` is installed, the pane offers to install it (a hint in New Design points there): `POST /api/settings/design/skill` runs `design-skill-install.service.ts`, which downloads the `ui-ux-pro-max-cli` tarball pinned by version (`design-skill-suggestion.ts`) and SHA-256 (`DESIGN_SKILL_PACKAGE`) and writes exactly what upstream's `uipro init --ai <claude|codex> --global` writes, for each configured design provider — Claude's skills folder (`$CLAUDE_CONFIG_DIR/skills`, else `~/.claude/skills`), Codex's `~/.agents/skills` — never replacing a folder that is already there. The pane then names `/ui-ux-pro-max` in the instructions, saved at once unless the draft has unsaved edits. The upstream commands stay behind "Install it yourself instead"; the skill's scripts need Python 3, which PPM reports and does not install. `tests/e2e/design-skill-install-e2e.ts` compares the result with upstream's file for file. Claude snapshots its system prompt at a session's first request and Codex reads developer instructions on connect, so a change reaches new design chats; the section is cached per session and text. e2e `tests/e2e/design-settings-e2e.mjs`.
 
 **The canvas** (`src/server/routes/design-preview.ts`):
 - `POST /api/design-preview` (authenticated) mints a token for one design and one purpose. A canvas token lives 30 min idle and 8 h at most, and is extended only by authenticated refreshes; within the last hour a refresh rotates it. Print and standalone tokens last 10 min and cannot be refreshed. Unauthenticated content reads never extend a token (`design-preview-tokens.ts`).
@@ -358,6 +358,32 @@ Shell (bash/zsh) receives SIGWINCH signal
 Terminal state updated
 ```
 
+A terminal with no layout is never fitted. That covers the dock's active tab while the dock is hidden, which on a phone is every restore because the dock comes back collapsed, and any tab parked off-screen. FitAddon would propose its 2x1 floor for such a terminal, and zsh with a themed prompt aborts on the next keystroke after being redrawn that narrow. The server also drops any size below 20x2 (`src/shared/terminal-size.ts`). Until the terminal is shown, the shell keeps its last real size, or 80x24.
+
+### Terminal selection to chat
+
+A selection in the terminal offers the editor's two actions, Add to current chat and Add to new
+chat, in a small bar under the selection's last row (over its first row when there is no room
+under it), as Cursor shows its Add to Chat. `terminal-selection-chat.tsx` draws it; `useTerminal`
+hands it the xterm instance. Either action adds the selection as a context chip
+(`sendToChat({ asContext })`, label "Terminal selection") and clears it, which takes the bar away.
+On a phone the selection is made in select mode and the buttons are 44px tall.
+
+Four details are load-bearing:
+
+- xterm reports a selection on mouseup, never during the drag, so the bar does not chase the
+  pointer. But it says nothing about a selection identical to the last one it reported, and its
+  `clearSelection()` — which it also runs when the user types with something selected — does
+  not forget that one, so selecting the same text again showed no bar. The component therefore
+  also reads the selection on the mouseup that ends a press in the terminal, in the document the
+  terminal is in at that moment (a tab can move into a picture-in-picture window).
+- `getSelectionPosition()` is documented as 1-based and returns 0-based columns and buffer rows,
+  the end column exclusive; the e2e measures the bar against the rows it selected.
+- The bar is a sibling of xterm's container, not a child: in select mode that container turns
+  every touch into a selection gesture, which would swallow a tap on the buttons.
+- It is positioned by hand on xterm's `onRender`, which a scroll, a resize and new output all end
+  in, and hidden while none of the selection is in view.
+
 ---
 
 ## Git Integration Flow
@@ -392,6 +418,71 @@ GitService.status() returns:
 UI updates: "src/index.ts" moves from "Unstaged" to "Staged"
 ```
 
+### Source Control, Review changes and Git Graph — one flow
+
+The three are views of one thing, the working tree and the commit about to be made, and they read
+and write it through the same routes, so they cannot disagree about a rename, a conflict or the
+message being written.
+
+- **What is changed**: `GET /git/changes` (`src/services/git-changes/git-changes.service.ts`)
+  answers the branch (upstream, ahead/behind), the operation stopped part way (`git-operation.ts`
+  reads the rebase/merge/cherry-pick/revert markers in `--absolute-git-dir`, which in a linked
+  worktree is `.git/worktrees/<name>`), and one row per file with its blocks on both sides —
+  staged (HEAD → index) and open (index → working tree) — without their lines. One
+  `git status --porcelain=v2` names the files (`porcelain-v2.ts`), then at most one `git diff` per
+  side covers all of them, cut back into files while it streams (`diff-sections.ts`); untracked
+  files go through a throwaway index, at most 400 of them and 4 MB each, beyond which a file is one
+  whole-file block. Every diff uses `PATCH_DIFF_ARGS`, so a block's id is the fingerprint the hunk
+  routes (`src/services/git-hunks/`) resolve a request by. It runs with `GIT_OPTIONAL_LOCKS=0`: it
+  runs on a poll, and a refreshed index would take the lock from under the user's own
+  `git commit`. `GET /git/changes/file?path=` adds the lines of one file. Shapes in
+  `src/shared/git-changes.ts`.
+- **Writes**: blocks and lines are staged, unstaged and discarded through the hunk routes. Undo
+  last commit, publish, pull and the stash are `src/services/git-workflow/git-workflow.service.ts`
+  (pull adds `--no-rebase` only when the repository configures no strategy; stash apply/pop use
+  `--index` and first check the hash of `stash@{n}`). After every POST on the git router a
+  middleware emits `git:changed` (`git-events.ts`), relayed on `/ws/global`, failed commands
+  included; Source Control, the Review tab, the Git Graph and the status bar's poller
+  (`useGitChangesPoller`) read again about 300 ms later.
+- **Discard Undo**: `src/services/git-discard-journal/` keeps what a discard threw away in
+  `<ppm dir>/git-discards/<repo key>/` — the reversed patch for a block (Undo only while the file
+  is still exactly what the discard left), the bytes for a whole file, written before the discard
+  runs (Undo only while every file is still what the discard left) — for a day, 100 per
+  repository, nothing over 20 MB.
+- **One commit message per repository**: `src/services/git-commit-draft.service.ts` keeps it in
+  `chat_drafts` (session id `git-commit`, keyed by the repository's real path, left alone by
+  `deleteOrphaned`), behind `GET/PUT /git/commit-draft`; a change goes out as `git:commit-draft`
+  with the sender's client id, so the sender ignores its own echo. Browser side
+  `src/web/stores/commit-draft-store.ts` (saved 300 ms after the last keystroke) and
+  `src/web/hooks/use-commit-draft.ts`.
+- **Source Control**: `src/web/components/git/git-status-panel.tsx` with `git-branch-row.tsx`,
+  `git-commit-composer.tsx`, `git-change-row.tsx` / `git-change-tree.tsx`,
+  `git-operation-banner.tsx`, `git-stash-section.tsx` and `git-confirm.tsx`; data from
+  `src/web/hooks/use-git-changes.ts`, and the decisions (checkbox state, sync button, hints) as
+  pure functions in `src/web/lib/git-changes-view.ts`.
+- **Review changes**: the `git-review` tab type, one per project and repository
+  (`src/web/components/git-review/`, `src/web/hooks/use-git-review.ts`, opened through
+  `src/web/lib/open-git-review.ts`). `src/web/lib/git-review-model.ts` puts staged blocks, open
+  blocks and the tab's own discards in one list by the one coordinate they share, the line in the
+  index version of the file. Code lines reuse the session review's `review-tokens.tsx`.
+- **Git Graph** (`packages/ext-git-graph/`): the working tree, the blocks and the draft come from
+  PPM's routes (`ppm-git.ts`), and so do the writes of the inspector and the toolbar: stage,
+  unstage, discard and its Undo, commit and Undo last commit, Fetch, Pull, Push, Sync and Publish,
+  stash save, apply, pop and drop, and Abort/Continue. The rest still runs git itself (`spawnGit` in
+  `extension.ts`, `reflog-view.ts`, `rebase-view.ts`) and sends no `git:changed`: the commit,
+  branch, tag and stash menus (checkout, merge, rebase and its Skip, cherry-pick, revert, reset,
+  creating, renaming and deleting branches and tags, a branch from a stash, deleting a remote
+  branch), the Reflog and Rebase views, worktrees, submodule updates, remotes and the user name.
+  Source Control and the Review tab see those when the file watcher reports a change to the working
+  tree, or at their next 5 s poll; the status bar at its next 10 s one. A write that bypasses the
+  routes is heard by nobody until then — the toolbar's Fetch once ran `git fetch` itself and left
+  the status bar on "synced" for up to 10 s. The webview's script is built from the
+  `webview-script-*.ts` modules into one `<script>`. Its file icons are the app's: the panel posts
+  `__ppm.fileIcons` with file names and `src/web/components/extensions/webview-file-icons.ts`
+  answers with each name's class and only the drawings those classes need, the light-theme ones
+  rewritten to `:root[data-ppm-theme="light"]`. Its 5 s poll also reads `for-each-ref` and
+  `stash list`, so a ref moved outside PPM triggers a full re-read.
+
 ---
 
 ## Frontend Performance Optimization (v0.9.86+)
@@ -410,7 +501,6 @@ UI updates: "src/index.ts" moves from "Unstaged" to "Staged"
 
 **3. Lazy Loading**
 - MarkdownRenderer lazy-loaded from 3 sites (reduces initial bundle)
-- CodeMirror on-demand in postgres-viewer
 - Mermaid diagram support loaded dynamically only when diagram syntax detected
 
 **4. Code Splitting (vite.config.ts)**
@@ -440,8 +530,8 @@ the **whole host filesystem** — not just registered project directories — th
 
 ### FS scope = auth boundary
 
-Every `/api/fs` route — including `docx-html`, `read`, `raw`, both SQLite doors — passes through
-one shared guard chain (`src/services/fs-path-guard.service.ts`) before touching disk:
+Every `/api/fs` route — including `docx-html`, `read`, `raw` — and the database file door
+(`/api/db/connections/file/*`) pass through one shared guard chain (`src/services/fs-path-guard.service.ts`) before touching disk:
 
 | Protection | Mechanism |
 |---|---|
@@ -449,7 +539,7 @@ one shared guard chain (`src/services/fs-path-guard.service.ts`) before touching
 | Protected roots | `/`, drive roots (`C:\`), `$HOME` and the PPM dir itself refuse delete/rename/move as a source |
 | Download tokens | `/api/fs/download/token` issues a single-use, path-bound token; `/api/fs/raw` spends it on first use, rejects replay and any path mismatch |
 | Symlink safety | every op `lstat`s the entry itself (never follows to the target) so a link *to* a protected path can itself still be deleted, but nothing can read/write *through* one into the PPM dir |
-| SQL injection surface | the external-DB doors (`/api/fs/sqlite/*`) block `ATTACH`/`DETACH` by keyword scan (after stripping comments/string literals) before executing any query — the same class of guard the project-scoped `/sqlite` route also needed |
+| SQL injection surface | the database file door (`/api/db/connections/file/*`, a `.db` opened by its path) refuses `ATTACH`/`DETACH` by keyword scan (after stripping comments/string literals) before executing any query, for a file inside a project and one reached by absolute path alike |
 | No event-loop blocking | every op is `fs.promises`-based with bounded concurrency and a per-entry timeout — a dead network mount or sleeping USB drive cannot stall unrelated requests, which matters once scope is the whole disk instead of one project |
 
 ### API surface
@@ -462,7 +552,7 @@ one shared guard chain (`src/services/fs-path-guard.service.ts`) before touching
 | POST | `/api/fs/copy` \| `/move` \| `/rename` \| `/touch` \| `/mkdir` | Mutations, collision (`EEXIST`)/self-nesting (`EINVAL`) reported for the client to resolve |
 | DELETE | `/api/fs/delete` \| `/rmdir` | `{permanent?}` — OS trash (Recycle Bin / Trash / gio) by default, permanent on request |
 | POST/GET | `/api/fs/download/token` / `/api/fs/raw` | Single-use, path-bound download |
-| GET/POST | `/api/fs/sqlite/{tables,schema,data,query}` | External `.db` viewer — same shape as the project-scoped `/sqlite` route, `path` absolute, PPM dir refused |
+| GET/POST | `/api/db/connections/file/*?path=&project=` | A `.db` opened from a file tree or the editor — the saved-connection routes under the id `file`, the file named and checked on every request. A path relative to `project` must stay inside it; an absolute one returns at most 1,000 rows of typed SQL; the PPM dir is refused, symlinks followed (`src/services/database/file-database.ts`) |
 
 `host-info.service.ts` orchestrates three OS-specific provider sets (`src/services/host-info/`)
 behind a 60s cache with in-flight de-duplication (concurrent `?refresh=true` calls share one
@@ -583,3 +673,75 @@ restored on reload (see Persistence below).
   tab-host window's titlebar keeps the tab title captured at pop-out time.
 - **Mobile.** Pop-out and PiP are hidden entirely below `md` (`useIsMobile()`) — never a scaled-down
   window.
+
+### Selected editor code as chat context
+
+`editor-selection-context.tsx` draws nothing. It registers a code-action provider for every
+language (`"*"`) that answers only for its own editor's model and, when the selection holds
+non-whitespace text, offers Add to current chat and Add to new chat. Monaco draws the lightbulb and
+the menu, so the two actions sit beside whatever a language server offers — under "More Actions…",
+Monaco's group for an action with no kind — and Ctrl+. reaches them too. Where the bulb goes is
+Monaco's decision: on the line at column 1 when its indentation has room, else on an empty or
+indented neighbouring line, else in the glyph margin left of the line numbers. Standalone Monaco
+turns the glyph margin off (`editor.api2.js`), and the gutter bulb is then drawn nowhere, which is
+why `code-editor.tsx` sets `glyphMargin: true`.
+
+That margin is one line height per glyph lane in use, so with the bulb as the only glyph it is a
+single 19px lane and the bulb fills it flush against the editor's edge. `monaco-lightbulb-gutter.ts`
+holds a second lane open with two empty glyph-margin widgets on line 1 (the width follows the line
+using the most lanes), and `globals.css` moves the bulb to the middle of the two. Moving it with CSS
+alone does not work: Monaco hit-tests the gutter by x, so a bulb drawn over the line-number column
+opens its menu and the same click selects that whole line, replacing the selection. Three details
+are load-bearing. The widgets sit at zIndex -1, because Monaco draws one glyph per lane and line,
+highest first, widgets winning ties — at 0 the left one hides the bulb on line 1. They are widgets,
+not `persistLane` decorations: a glyph decoration on the bulb's line makes Monaco give up the gutter
+and draw the bulb over the text. And `lineNumbersMinChars: 3` gives back the width of the extra lane,
+so the code starts where it did.
+
+The action's arguments are a snapshot taken when the bulb is shown: file path, line range and the
+model's text in that range, unsaved edits included. Markdown fences are sized past the longest
+backtick run. Every mounted editor registers the same command id (`ppm.selection.addToChat`);
+Monaco's registry stacks registrations, so closing one editor leaves the command to the others.
+`sendToChat` adds the snapshot to the last selected chat of the file's project as an attachment
+without replacing its draft (never to another project's chat: with none of its own open, it opens
+one), or opens a new chat with a context chip. Lazy-mounted chats receive `pendingContexts` in tab
+metadata; their composer consumes those once without replacing the existing draft. Neither action
+sends a turn.
+
+Monaco's own rules apply: the bulb waits for every code-action provider, so a slow language server
+delays it; any provider registering resets it until the cursor moves; and code actions are off in a
+read-only editor, so a database-cell preview has no bulb.
+
+### Fix with AI and Explain with AI on editor problems
+
+`editor-fix-with-ai.tsx` is built the same way: a code-action provider for `"*"` that answers only
+for its own editor's model and draws nothing. Monaco hands every provider the markers touching the
+range it asks about (`context.markers`); when one of them is an error or a warning, the provider
+offers two quick fixes, Fix with AI and Explain with AI, both flagged `isAI`. That flag is all
+Monaco needs for the rest:
+
+- a sparkle beside each in its menu, under Quick Fix after the language server's own fixes
+  (Monaco sorts AI actions last, and keeps the provider's order among them);
+- the first AI action as a one-click link in the problem's hover. Monaco shows one there, which is
+  why Fix is listed before Explain, and asks providers for quick fixes only — hence
+  `kind: "quickfix"` rather than no kind;
+- a sparkle for the bulb: `lightbulbSparkle` beside other fixes, `sparkleFilled` when every fix on
+  offer is AI. Monaco runs a *lone* AI action straight from the bulb instead of opening its menu;
+  with Explain beside Fix there is never a lone one, so the bulb always opens the menu, as VS Code's
+  does with Copilot's pair. Dropping either action brings that auto-run back.
+
+The requests are a snapshot taken when the actions are offered: each problem as
+`line:column severity: message source(code)` in file order, then the model's text from three lines
+above the first to three below the last, under "Fix this problem in …:" or "Explain this problem in
+…, without changing any files:" — said outright because the chat it lands in may edit files. Both
+go through one command (`ppm.problems.askAi`) carrying the text, to a new chat, sent from there
+(`sendToChat({ newTab, autoSend })`). The new tab has not rendered when the command runs, so
+`sendOnceMounted` keeps addressing it until its composer acks — idle and empty, the composer sends
+the text itself — and leaves the text as the draft after 10 s, so a slow first load costs a
+keypress rather than the request.
+
+Markers come from the language server (`ppm-lsp`) and from Monaco's own JSON and CSS validators.
+Monaco's TypeScript diagnostics are always off (`monaco-builtin-typescript.ts`), so a TypeScript
+file has problems to fix only with LSP on. The LSP code-action request carries the server's own
+diagnostics for the range (`LspDocument.diagnostics`, as published, `data` included): servers find
+their fixes from that list, and typescript-language-server answers an empty one with none.

package/docs/code-standards.md

@@ -131,6 +131,35 @@ try {
 const file = await FileService.read(path).catch(() => null);
 ```
 
+### Logging
+Server code logs through `createLogger` from `src/services/logger.ts`; the scope becomes the
+`[scope]` of the line in `~/.ppm/ppm.log`:
+
+```typescript
+import { createLogger } from "../services/logger.ts";
+const log = createLogger("fs-ops");
+
+log.info(`Deleted ${count} entries in ${dir}`);
+log.error("Move failed:", err); // an Error keeps its stack
+if (log.isEnabled("debug")) log.debug(`event ${JSON.stringify(event)}`); // skip costly formatting
+```
+
+Pick the level by what happened, not by how important the module feels:
+
+| Level | For | Examples |
+|---|---|---|
+| `fatal` | the process is about to exit, or a core subsystem cannot run at all | port never freed, DB cannot open or migrate, too many uncaught errors |
+| `error` | something that was asked for did not happen | a write, a commit, a backup or a child process failed |
+| `warn` | unexpected but recovered | a fallback, a retry, a timeout, a refused credential, a slow request |
+| `info` | lifecycle and state changes, at a rate a person can read | started/stopped, created/deleted, installed, a job ran |
+| `debug` | per-event chatter, only worth having while diagnosing | stream deltas, protocol detail, "skipping" notes |
+
+`info` is the default threshold (`ppm config set log_level debug`, or `PPM_LOG_LEVEL=debug`, to see
+more). Bare `console.*` calls still work and are logged at their level (`console.debug` is DEBUG).
+Never log secrets, file contents, chat text or tool output. Requests and WebSocket open/close are
+logged centrally (`src/server/middleware/access-log.ts`, `src/server/index.ts`), so a route only
+logs what that line cannot say — a count, a pid, a failure it turned into a 200.
+
 ## Component Patterns
 
 ### React Components
@@ -280,7 +309,7 @@ try {
 
 Query audit logs every SQL statement to a separate database (`~/.ppm/query-audit.db`), recording source (editor, grid, cli, filter), actor (human vs agent), operation type, and sample result rows. **Critical:** audit failures must never break a user query.
 
-**Pattern** (`routes/database.ts`, `routes/sqlite.ts`):
+**Pattern** (`routes/database.ts`):
 ```typescript
 const startedAt = Date.now();
 // Build the audit shape once — the blocked, ok and error branches all reuse it.

package/docs/codebase-summary.md

@@ -85,6 +85,7 @@ src/
 │   ├── extension-rpc.ts         # RPC channel (request/response/events)
 │   ├── extension-host-worker.ts # Worker-side extension loading
 │   ├── contribution-registry.ts # Central registry for commands, views, config
+│   ├── logs/                    # Logs window backend: every log as one list (log-store), live tail, AI-sorted issues, report drafts, GitHub labels + duplicate search
 │   ├── slash-discovery/         # Modular slash command discovery engine
 │   │   ├── types.ts             # DefinitionSource, SkillRoot, SlashItem, DiscoveryResult types
 │   │   ├── definition-source.ts # Priority ranking + scope mapping
@@ -117,11 +118,16 @@ src/
 │   │   ├── query-audit-db.ts    # Connection + schema initialization
 │   │   ├── query-audit.service.ts # Insert/list/count queries; detectOperation()
 │   │   └── result-truncate.ts   # Truncate result rows (first 5 + last 5); cap sql/params at 16KB
-│   ├── database/
-│   │   ├── adapter-registry.ts  # SQLite/Postgres adapter registry
-│   │   ├── sqlite-adapter.ts
-│   │   ├── postgres-adapter.ts
-│   │   └── readonly-check.ts    # CTE-safe readonly validation
+│   ├── database/                # External databases: SQLite, PostgreSQL, MySQL / MariaDB (docs/architecture/data-and-storage.md)
+│   │   ├── adapter-registry.ts  # One adapter per engine (sqlite-, postgres-, mysql-adapter.ts) over {sqlite,postgres,mysql}.service.ts
+│   │   ├── dialect-*.ts         # Quoting, paging and casts per engine; grid-query-builder.ts builds every grid SELECT
+│   │   ├── changeset.service.ts # Grid edits as one script in one transaction, CASCADE deletes
+│   │   ├── structure-edit.service.ts # Structure tab: table diff → DDL plan, preview / apply
+│   │   ├── query-script-runner.ts # Query tab runs: one statement at a time, Stop, row limit
+│   │   ├── readonly-check.ts    # First readonly gate; the database enforces the rest (READ ONLY transaction, readonly handle)
+│   │   ├── ddl/                 # DDL per engine, table diff, SQLite 12-step rebuild
+│   │   ├── drivers/             # mysql2 / ssh2 installed from Settings: catalog, pinned locks, installer, loader
+│   │   └── impexp/              # Import/Export jobs; readers/ for CSV, JSON, JSON lines
 │   ├── jira-api-client.ts       # Jira Cloud REST API v3 (search, getIssue, transitions)
 │   ├── jira-config.service.ts   # Jira config CRUD, AES-256 token encryption
 │   ├── jira-watcher-db.service.ts # Watchers + results table queries
@@ -264,12 +270,23 @@ src/
 │           │   ├── tab-pool-registry.ts # ADDED: slotRegistry — panels/dock/windows publish the element their tab content lives in
 │           │   ├── tab-pop-out-menu-item.tsx # ADDED: "Open in window" tab context-menu item (desktop only)
 │           │   └── use-window-panel-reconcile.ts # ADDED: one-shot repair between persisted window panels and live floating windows
-│           ├── database/            # Database management (5 files, 300+ LOC)
-│           │   ├── database-sidebar.tsx # Sidebar tab container (connection list, form)
-│           │   ├── connection-list.tsx # Connections list with actions, color badges
-│           │   ├── connection-form-dialog.tsx # Create/edit connection form (SQLite/Postgres)
+│           ├── database/            # Database UI, DBGate-style (docs/architecture/data-and-storage.md)
+│           │   ├── database-sidebar.tsx # CONNECTIONS above TABLES, VIEWS, FUNCTIONS, split and resizable
 │           │   ├── connection-color-picker.tsx # WCAG contrast-aware color picker
-│           │   └── use-connections.ts # Hook for connection CRUD operations
+│           │   ├── use-connections.ts # Hook for connection CRUD operations
+│           │   ├── connections-section/ # CONNECTIONS tree: toolbar, folders, status, menus
+│           │   ├── explorer/        # Open / focused connection and database, tree keys, openers for tabs
+│           │   ├── object-tree/     # TABLES, VIEWS, FUNCTIONS of the focused database
+│           │   ├── connection-form/ # Connection tab: General, Advanced, SSH Tunnel, SSL
+│           │   ├── db-login/        # Database Log In dialog (password mode "ask")
+│           │   ├── table/           # DBGate's data tab (type `database`), shared with the .db viewer
+│           │   ├── grid/            # Glide grid parts: filter row, Form view, Cell data, menus, Save changes, copy / export
+│           │   ├── structure/       # Structure tab (`db-structure`): columns, keys, indexes, dependencies
+│           │   ├── table-editor/    # Editing columns, keys and indexes on the Structure tab, its Save dialog
+│           │   ├── sql-object/      # SQL tab (`db-sql`): an object's CREATE / SELECT / INSERT, read-only Monaco
+│           │   ├── impexp/          # Import/Export tab (`db-impexp`)
+│           │   └── query/           # Query tab (`db-query`): scripts, Messages + Result N, Stop, History
+│           ├── logs/                # Logs window (a tab below md): Logs / Issues / Report sub-tabs over one feed; replaced the Report Bug popup
 │           ├── projects/            # Project management (339 LOC, 2 files)
 │           ├── settings/            # Settings as its own window kind (tab below md)
 │           │   ├── settings-body.tsx # Shared shell: rail + pane, layout from @container
@@ -278,14 +295,9 @@ src/
 │           │   └── accounts/        # Multi-account management (add, delete, enable, export, import, rotation, token test)
 │           ├── terminal/            # xterm.js wrapper (143 LOC, 2 files)
 │           ├── shared/              # Shared components (2 files)
-│           │   ├── markdown-renderer.tsx # Render Markdown with syntax highlighting
-│           │   └── bug-report-popup.tsx  # Global bug report popup
-│           ├── sqlite/              # SQLite viewer (unified connectionId API mode)
-│           │   ├── sqlite-viewer.tsx # Display table data, execute queries
-│           │   └── use-sqlite.ts    # Hook for SQLite operations via /api/db routes
-│           ├── postgres/            # PostgreSQL viewer (unified connectionId API mode)
-│           │   ├── postgres-viewer.tsx # Display table data, execute queries
-│           │   └── use-postgres.ts  # Hook for Postgres operations via /api/db routes
+│           │   └── markdown-renderer.tsx # Render Markdown with syntax highlighting
+│           ├── sqlite/              # A .db opened from a file tree or the editor
+│           │   └── sqlite-viewer.tsx # Its tables in a list + the data tab's TableView, on /api/db/connections/file
 │           └── ui/                  # Radix + shadcn primitives (14 files)
 │               ├── button, input, label, dialog, dropdown-menu, select, tabs, tooltip, etc.
 │               └── portal-container-context.tsx # ADDED: shared Radix portal target context — lets a tab's popped-out primitives render into the PiP document
@@ -353,7 +365,7 @@ src/
 - **Services:**
   - **ChatService** — Session lifecycle, message queueing, streaming
   - **ConfigService** — Config in SQLite (dotted keys, typed cache)
-  - **DbService** — SQLite persistence (WAL mode, schema v41, connection/account CRUD, table cache)
+  - **DbService** — SQLite persistence (WAL mode, schema v56, connection/account CRUD, table cache)
   - **AccountService** — Multi-account management, token encryption/decryption
   - **AccountSelectorService** — Select active account based on config
   - **GitService** — Git commands via simple-git
@@ -378,8 +390,8 @@ src/
     `hostname-rules.ts` (one label above the zone, no apex/`www`), `cloudflare-zone-api.ts` /
     `cloudflare-dns-api.ts` (Cloudflare REST lookups for zone name + DNS collision precheck).
     Routes: `src/server/routes/named-tunnel.ts` (`/api/tunnel/named/*`; mutations 403 unless PPM auth
-    is enabled). UI: `src/web/components/tunnels/named-tunnel/` (first-run popup + permanent Tunnel
-    Manager section, sharing one step-reducer-driven flow).
+    is enabled). UI: `src/web/components/tunnels/named-tunnel/` (first-run popup + Settings → Remote
+    Access → Public link, sharing one step-reducer-driven flow).
   - **fs-credential-path-guard.ts** (ADDED) — Refuses `~/.cloudflared` (Cloudflare login cert)
     alongside the PPM dir on every fs read/write/transfer door, symlink-resolved
   - **config-secret-keys.ts** (ADDED) — Denylist + deep redaction for config-dump surfaces
@@ -387,8 +399,9 @@ src/
     caller asked for an ancestor object (e.g. `get tunnel` still masks `namedTunnelToken`)
   - **TableCacheService** — Cache table metadata across connections, search tables by name
   - **DatabaseAdapterRegistry** — Register/retrieve DatabaseAdapter implementations (extensible pattern)
-  - **SQLiteAdapter** — SQLite connection/query execution with readonly checks
-  - **PostgresAdapter** — PostgreSQL connection/query execution with readonly checks
+  - **SQLiteAdapter** — SQLite files via `bun:sqlite`; a readonly connection opens a readonly handle
+  - **PostgresAdapter** — PostgreSQL via postgres.js; readonly statements run inside `BEGIN READ ONLY`
+  - **MysqlAdapter** — MySQL / MariaDB via `mysql2`, installed from Settings; readonly sessions are `READ ONLY`
   - **PPMBotService** — Coordinator orchestrator (startup, shutdown, message routing, task polling)
   - **PPMBotSessionManager** — Coordinator session per chat in ~/.ppm/bot/, project resolver
   - **PPMBotTelegramService** — Telegram API (long-polling, send, edit, typing, command handling)

package/docs/deployment-guide.md

@@ -8,6 +8,13 @@
 - **Disk:** ~500 MB for the binary, plus ~15 MB for the cloudflared binary PPM downloads on first start
 - **Network:** localhost is enough; internet access is needed for the tunnel and for AI providers
 
+### Remote Desktop on Windows
+
+If FFmpeg is missing, click **Install ffmpeg** in Remote Desktop. PPM installs the fixed
+`Gyan.FFmpeg` package through WinGet in the background, displays installation status or
+errors, and checks for FFmpeg again without restarting. Closing the panel does not cancel
+the installation. Windows App Installer (WinGet) and internet access are required.
+
 ### Required Software
 - **Bun** v1.3.6+ (https://bun.sh) — **only** for the `bunx`/`bun add -g`/from-source paths. The
   released binary bundles its own runtime and needs nothing installed.
@@ -167,8 +174,41 @@ The split exists so a restart does not rotate the public URL. Use `down` for a r
 
 ### Logs
 
-The daemon writes to `~/.ppm/ppm.log` (inside `getPpmDir()`). `ppm logs -n 200`, `ppm logs -f` and
-`ppm logs --clear` read and manage it. There is no separate logging config.
+The daemon writes to `~/.ppm/ppm.log` (inside `getPpmDir()`), one line per event:
+
+```
+[2026-10-06T03:06:13.123Z] [WARN] [http] POST /api/project/ppm/git/branch 409 12ms — branch already exists
+```
+
+Every line has a level:
+
+| Level | Meaning |
+|---|---|
+| `FATAL` | the process is about to exit, or a core part cannot run (database will not open, port will not bind) |
+| `ERROR` | something that was asked for did not happen (a request failed, a job failed, a child process died) |
+| `WARN` | unexpected but recovered — a fallback, a retry, a refusal, a timeout |
+| `INFO` | lifecycle and changes: started, stopped, created, deleted, a setting changed, a request that changed something |
+| `DEBUG` | per-event detail: every read request, stream events, protocol chatter |
+
+`info` is the default: `DEBUG` lines are not written at all until asked for.
+
+```bash
+ppm logs -n 200              # last 200 lines
+ppm logs -f                  # follow
+ppm logs --level warn        # only WARN, ERROR and FATAL (works with -n and -f)
+ppm config set log_level debug   # write DEBUG lines too; a running server picks it up within 10s
+ppm config set log_level info    # back to the default
+PPM_LOG_LEVEL=debug bun dev:server   # pins the level for that process, over the config
+ppm logs --clear
+```
+
+Every HTTP request is logged once (`[http]`, with method, path, status and duration — a change at
+`INFO`, a read at `DEBUG`, a failure with the error message it returned), and so is every
+WebSocket opening and closing (`[ws]`). Secrets are redacted before a line is written, and file
+contents, chat text and tool output are never logged. The file rotates at 20 MB, keeping
+`ppm.log.1` … `ppm.log.3`. `GET /api/logs/recent`, the old bug report's log tail, needs signing in
+and returns only `INFO` and above. A CLI command (`ppm db query`, `ppm config set`, …) does not write to `ppm.log`: its log
+lines go to stderr, so what it prints on stdout stays parseable.
 
 ---
 
@@ -212,8 +252,12 @@ already have on Cloudflare — see the next section.
 reachable. Always keep auth on when sharing. The session token is required on the WebSocket
 handshake too, not just on HTTP.
 
-Per-port forwarding for local dev servers is separate: the dock's Cloudflare Tunnels panel drives
-`/api/tunnels`, which spawns one quick tunnel per port.
+Per-port forwarding for local dev servers is separate: the sidebar's Port Forwarding panel drives
+`/api/tunnels`, which forwards each port over Cloudflare (one quick tunnel per port, no sign-in) or over
+Tailscale. Its Set up buttons open Settings → Remote Access, where Tailscale and Cloudflare are signed
+in to. A forwarded page opens in a PPM tab even when it sends `X-Frame-Options` or a CSP
+`frame-ancestors`: the tab tells the server the address PPM is open at, and the forward lets that
+address frame the page while every other site is still refused.
 
 ---
 
@@ -238,15 +282,15 @@ fresh link. Once logged in, PPM reads the zone from the new credential and propo
 the zone (no apex record, no `www`; Cloudflare's free certificate only covers one subdomain level,
 and anything deeper would serve a TLS error).
 
-The Tunnel Manager section (in the app, alongside the quick-tunnel controls) is where the flow lives
-permanently — the popup only covers first-run:
+Settings → Remote Access → Public link (beside the public link's on/off switch) is where the flow
+lives permanently — the popup only covers first-run:
 
-- **Disable** switches back to the quick tunnel. The named-tunnel configuration is kept (not deleted)
-  so re-enabling doesn't require logging in again.
-- **Re-login** ("Log in again") is what to use when the domain's zone changes, or whenever PPM
-  reports the Cloudflare credential looks stale (wrong account, unreadable file). It moves the
-  existing credential aside (`cert.pem` → `cert.pem.bak-<timestamp>`) rather than deleting it, then
-  starts a fresh login — never edit or delete `~/.cloudflared/cert.pem` by hand.
+- **Switch**, on the Temporary address row, goes back to the quick tunnel. The named-tunnel
+  configuration is kept (not deleted) so re-enabling doesn't require logging in again.
+- **Sign in again** takes the place of the address choices whenever PPM reports the Cloudflare
+  credential looks stale (wrong account, unreadable file), and is offered when a setup fails; it is
+  also what to use when the domain's zone changes. It moves the existing credential aside
+  (`cert.pem` → `cert.pem.bak-<timestamp>`) rather than deleting it, then starts a fresh login — never edit or delete `~/.cloudflared/cert.pem` by hand.
 
 ### Troubleshooting
 

package/docs/project-overview-pdr.md

@@ -9,7 +9,7 @@ Built on the **Bun runtime** for performance, PPM enables developers to:
 - Execute commands via xterm.js terminal with full PTY support on macOS, Linux and Windows
 - Chat with multiple AI agents (Claude Agent SDK, OpenAI Codex, Cursor CLI) with file attachments, slash commands, skills, subagents and agent teams
 - View Git status, diffs, and commit graphs in real-time, and resolve conflicts inline
-- Query SQLite and PostgreSQL databases with an audit trail
+- Manage SQLite, PostgreSQL, MySQL and MariaDB databases — browse, edit, change structure, import/export and query — with an audit trail
 - Browse the whole host filesystem and monitor every process on the machine
 - Manage multiple projects via a project registry
 - Access the IDE from mobile, tablet, or desktop browsers — including through a Cloudflare tunnel
@@ -46,7 +46,7 @@ For the user-facing feature list, see the [README](../README.md). For per-releas
 - Monaco editor with diff viewer and inline merge-conflict resolution
 - Terminal — multiple PTY sessions per project plus a dock terminal on any folder
 - Git — status, diff, stage, commit, push/pull, branches, merge, rebase, stash, worktrees, commit graph
-- SQLite + PostgreSQL viewer with query editor, cell editing and a query audit log
+- Database manager (SQLite, PostgreSQL, MySQL, MariaDB) — connection tree, data grid with filters and one-transaction saves, structure editor, import/export jobs, multi-statement Query tab and a query audit log
 - System Monitor — CPU/RAM/disk/network/GPU charts and per-app process control
 - Floating windows, tab pop-out and Document Picture-in-Picture
 - VSCode-compatible extension system running in isolated Bun workers

package/docs/project-roadmap.md

@@ -30,6 +30,25 @@ PPM is the **lightest path from phone to code** — a self-hosted, BYOK, multi-d
 - See `docs/architecture/workspace-and-ui.md` → "Design mode". Verified by
   `tests/e2e/design-mode-e2e.mjs` at 1366 px and 390 px.
 
+### Database v2 — DBGate-style database UI (next release)
+
+- MySQL and MariaDB beside SQLite and PostgreSQL. The `mysql2` driver, and `ssh2` for SSH tunnels,
+  install from Settings → Database Drivers instead of shipping in the binary.
+- A connection tab (General, Advanced, SSH Tunnel, SSL) with "ask for password" logins, allowed
+  databases, isolation level and a query timeout per connection.
+- CONNECTIONS above TABLES, VIEWS, FUNCTIONS in the sidebar; a data grid with DBGate's filter row
+  and filter dialogs, multi-column sort, 100 rows at a time, edits saved as one script in one
+  transaction (with CASCADE deletes), Form view, Cell data, References, Copy advanced and
+  Generate SQL.
+- A Structure editor (columns, keys, indexes; SQLite tables rebuilt in 12 steps), Import/Export
+  jobs (several tables, CSV / JSON / XML / XLSX / SQL, one workbook or a zip), and a Query tab
+  that runs a script statement by statement with Messages, a Result tab per statement, Stop and
+  History.
+- Readonly connections are enforced by the database itself (READ ONLY transactions, a readonly
+  SQLite handle) on every path, `ppm db query` included.
+- See `docs/architecture/data-and-storage.md` → "Database Management". Verified by
+  `tests/e2e/database-e2e.mjs` on a desktop and a 390 × 844 phone viewport.
+
 ### Adaptive onboarding (0.22.3)
 
 - Adaptive onboarding: choose experience and goal, follow contextual guidance, pause/resume,
@@ -108,7 +127,7 @@ PPM is the **lightest path from phone to code** — a self-hosted, BYOK, multi-d
 - Git-Graph UI (v0.9.85+) — faithful SVG graph (vscode-git-graph port), interactive stage/unstage/commit/stash, branch filters, auto-fetch, mobile support
 - Git Workflow (v0.9.86+) — stash management, rebase from context menu, conflict detection, inline Monaco conflict resolution, worktree CRUD
 - Git Insights (ext 0.3.0) — blame with age heatmap, file/line history, compare refs, interactive rebase (incl. reword/edit), reflog with undo, submodules, whole-history commit search, author avatars, drag-to-merge/rebase. Each is its own panel because the extension API exposes no editor to annotate.
-- Language servers in the editor — real completions, hover, go to definition, references, rename, quick fix, formatting and inlay hints from the same server binaries VS Code drives, hosted by the PPM server and reached over a thin bridge. Core rather than an extension because it needs the editor, which the extension API does not expose. Not installed automatically: a missing server is reported with the command that installs it.
+- Language servers in the editor — real completions, hover, go to definition, references, rename, quick fix, formatting and inlay hints from the same server binaries VS Code drives, hosted by the PPM server and reached over a thin bridge. Core rather than an extension because it needs the editor, which the extension API does not expose. Not installed automatically: a missing server is reported with an Install button — npm, Go, rustup, a gem, or a release build pinned by SHA-256 — and the command to run by hand.
   Also a Problems panel in the dock, opened from the status bar counts (VS Code's placement for both), and semantic highlighting driven by each server's own token legend.
 - Git in the core app — inline blame on the cursor's line in the Monaco editor (`Alt+B`), and hunk/line-level stage, unstage and discard from Source Control. Both live in core rather than the extension precisely because they need the editor and the panel the extension cannot reach.
 
@@ -141,7 +160,7 @@ PPM is the **lightest path from phone to code** — a self-hosted, BYOK, multi-d
 | **Self-hosted PPM Cloud** | High | Docker image of PPM Cloud for enterprise/team. Same codebase, self-hosted config flag. LDAP/SSO. |
 | **PPM Marketplace** | High | Publish/install/update extensions, browse community extensions. Today extensions install from npm only. |
 | **Stability & hardening** | Critical | Security audit, performance work, test coverage, contributor docs, CI/CD. |
-| **Inline SQL** | Medium | Select text in Monaco → run as SQL, connection picker in the editor context menu, results panel below the editor. Not started. |
+| **Inline SQL** | Medium | Select text in Monaco → run as SQL, connection picker in the editor context menu, results panel below the editor. Not started, but no longer from scratch: the Query tab (Database v2) already runs a selection statement by statement and shows a result per statement, so this can reuse its runner (`POST /api/db/connections/:id/query/script`) and its result tabs. |
 
 ---
 

package/docs/system-architecture.md

@@ -41,7 +41,7 @@ deployment and the error/security posture. Subsystem detail lives beside it:
 │  │  │ (streaming  │ (simple-   │ (read/write │ (PTY/shell)     ││   │
 │  │  │  messages)  │  git)      │  files)     │ (Bun.spawn)     ││   │
 │  │  │ TableCache  │ DbService  │ DatabaseAdapterRegistry         ││   │
-│  │  │ (metadata)  │ (SQLite)   │ (SQLite, PostgreSQL adapters)   ││   │
+│  │  │ (metadata)  │ (SQLite)   │ (SQLite, PostgreSQL, MySQL)     ││   │
 │  │  └───────────────────────────────────────────────────────────┘│   │
 │  ├────────────────────────────────────────────────────────────────┤   │
 │  │  Providers (src/providers/)                                    │   │
@@ -150,14 +150,16 @@ GET    /api/project/:name/files/tree              → Directory tree
 GET    /api/project/:name/files/raw               → File content
 PUT    /api/project/:name/files/write             → Write file
 GET    /api/db/connections                        → List all connections
-POST   /api/db/connections                        → Create connection (SQLite/PostgreSQL)
+POST   /api/db/connections                        → Create connection (SQLite/PostgreSQL/MySQL/MariaDB)
 GET    /api/db/connections/:id                    → Get connection (sanitized)
-PUT    /api/db/connections/:id                    → Update connection (toggle readonly, UI-only)
+PUT    /api/db/connections/:id                    → Update connection
 DELETE /api/db/connections/:id                    → Delete connection
-GET    /api/db/connections/:id/tables             → List tables (with sync)
-GET    /api/db/connections/:id/tables/:table      → Get table schema + data
-POST   /api/db/connections/:id/query              → Execute query (readonly checked)
-PATCH  /api/db/connections/:id/cell               → Update cell value (single)
+GET    /api/db/connections/:id/objects            → Tables, views, functions (tree)
+POST   /api/db/connections/:id/grid               → One page of a table (SQL built on the server)
+POST   /api/db/connections/:id/changeset/apply    → Save grid edits in one transaction
+POST   /api/db/connections/:id/query/script       → Run a Query tab script (NDJSON stream)
+POST   /api/db/connections/:id/query              → Execute one query (CLI, agents)
+                                                    (full list: data-and-storage.md → Database Management)
 GET    /api/upgrade/status                        → Get current + available versions, install method
 POST   /api/upgrade/apply                         → Install new version, trigger supervisor self-replace
 GET    /api/project/:name/workspace               → Get saved workspace layout + metadata
@@ -376,6 +378,9 @@ HTTP/1.1 200 OK
    facade over a per-platform registry (`remote-desktop-input-win32.ts` = user32 `SendInput`,
    `remote-desktop-input-darwin.ts` = CoreGraphics `CGEventPost`, both via `bun:ffi`, no helper binary).
    Coordinates are 0..1 fractions of the frame; keys are `KeyboardEvent.code` mapped per OS.
+   Windows enumerates individual monitors using `EnumDisplayMonitors` / `GetMonitorInfoW`, in physical
+   pixels with scoped DPI awareness. The viewer offers individual monitors and defaults to the primary monitor. `gdigrab` receives the chosen rectangle through `-offset_x`, `-offset_y`, and `-video_size`;
+   SendInput maps the same rectangle back into virtual-desktop coordinates, including negative origins.
 
 ---